Quoth Liane Praza on Mon, Sep 08, 2008 at 07:56:59AM -0700: > >David Bustos wrote: > >>Quoth Liane Praza on Fri, Aug 15, 2008 at 03:41:37PM -0700: > >>>I'm re-posting our manpage diffs and interface information here for > >>>reference, though it is not under review: > >>> http://cr.opensolaris.org/~lianep/templates-0815/ ... > >> smf_template(5) > >> "Templates may be defined for a service to describe metadata about > >> the service in general...": I think this would be more useful to > >> users if it were more concrete. Specifically by describing when ... > I've rewritten this section. > > Templates are defined by service developers to describe metadata > about a service in general or individual configuration properties on > a service, including human-consumable descriptions as well as > definitions of valid configuration. > > Administrators are provided access to templates through SMF commands > which describe configuration values and validate configuration against > templates. > > Tool developers can use templates to provide more helpful user > interfaces for service configuration.
That's fine. I suspect the word 'metadata' is unnecessarily general, but I also suspect that it's not worth the time to change it. > >> "A template is created...": This paragraph confuses me because the ... > This underwent significant discussion in follow-up emails. I admit I'm > not really thrilled with the results yet, though the critiques are > well-placed. ... What you wrote is fine. When you're comfortable with the changes, please publish an updated manpage so I can read it in situ. > >> "Templates defined globally...": I think you should clarify when > >> a template is considered to re-define another template. Do they > >> have individual names? Or is it based on their matching criteria? > >> It seems this information is most relevent to template authors, > >> except for when template consumers need to understand that > >> configuration validation can fail due to miscoordination between > >> different template authors. So I'm not sure that the "Template > >> Composition" section is the best place for this. > >I'll wait for Liane's input on this one too. > > I think this is partially addressed by raising the most important > criteria for re-definition in Template Definition before this section. > I've also reiterated and clarified in the Template Composition rewrite > above. Sure. > >> "Capital letters...": I suspect this should be qualified with "in > >> English locales". ... > Frankly, this confuses me and optimizes for the uncommon case (based on > data about localization of SMF manifests today). I'm changing it to: > > Capital letters must be used only for acronyms or proper names. > For locales other than English, use appropriate capitalization > for a sentence fragment. Yes, good call. > >> scf_tmpl_pg_name(3SCF): > >> "this funtion will return a string containing SCF_TMPL_WILDCARD": > >> SCF_TMPL_WILDCARD doesn't seem to be in the interface table of the > >> ARC case. Is it appropriate to mention it here? ... > There are no loopholes -- there's simply the fact that during the normal > course of implementation and review some of the interfaces as designed > were inadequate. We'll run a very small (likely > closed-approved-automatic, or an update of the previous case) ARC case > to update the materials. But, I really saw no need to do that until the > bulk of the review had been done so that we didn't have to go back twice > if other issues were found in formal review. Sure. > >> scf_tmpl_validate_fmri(3SCF): > >> "The template validation functions offer a way to validate an > >> FMRI...": Really you're validating the configuration data associated > >> with an instance, eh? > > I'm good with the re-wording Antonello proposed (and implemented) in > subsequent mails, but do not want to change the function name: the FMRI > string is the input, and elsewhere where we use "instance" in the > function name, we mean instance_t as input. Agreed. David
