My thanks as well for the feedback, David -- we definitely appreciate feedback to make the documentation clearer. I'm going to address the outstanding documentation questions in this mail, and will elide ones already addressed.
Antonello Cruz wrote: > 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/ >> >> While reading about the interfaces, I came across some text which >> I think many users will find unclear. And during the review, I had some >> questions. Since this documentation is not under review, however, feel >> free to ignore. >> >> 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 >> users might want to produce or consume templates. Perhaps saying >> that service developers use templates to describe what >> configuration values are valid, administrators can use templates >> to validate configuration, and tool developers can use templates >> to provide more helpful configuration user interfaces. > I agree with you, but I'll wait for Liane come back from vacations since > she will have much better real examples than me. 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. >> "A template is created...": This paragraph confuses me because the >> first sentence says what creates a template, but the rest >> describes, I think, how service developers should write templates >> in their manifests. Though maybe it's trying to describe which >> templates should be used for which properties. I suppose it turns >> on the definition of "templated". > With Tom's input, I changed the paragraph to: > > "Templates can be defined at several levels. Templates that apply to a > specific instance or service are defined in the service manifest. > Templates that apply to all services that are controlled by a > restarter are defined in the restarter's manifest. Finally, SMF > framework property groups and properties are templated in the manifest > for svc:/system/svc/global. SMF takes a composed view of the template > specifications in these levels." 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. The first thing I'd like to do is move the Template Definition section above this section. I think it'll help the whole manpage flow more smoothly, as it will now work from the general to the more specific. Then, I've rewritten the Template Composition section based on the discussion: All template interfaces search for template data about a property group first on the instance, then on the service, then on the service's restarter, and finally globally. A property group template is defined by its author to apply to a specific instance, to a service and all of its instances, to a restarter's delegates, or globally. A typical service author will define the template on an instance or on a service. A template defined on an instance are applied to that instance only, and can override a template for that property group defined on the service. A template defined on the service is applied to all instances of that service. Restarter authors may define templates in their manifest that apply to any service which uses their restarter, which is also known as a "delegate". SMF framework authors have defined templates for property groups with well-known meanings to the entire SMF framework in the manifest for svc:/system/svc/global. Templates defined globally or by the restarter and re-defined by the service or instance will be flagged as a validation error. Service authors may avoid these errors by creating templates only for property groups specific to their service and not consumed by the SMF framework. Property group templates may also be wildcarded by name and/or type. Only the most specific template definition applicable to a property group will be honored. > >> >> "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. >> "Capital letters...": I suspect this should be qualified with "in >> English locales". > It would also qualify for any Latin based locale. I guess you're > considering Asian, Arabic or locales without the concept of Capital > Letters. I would leave it like this as if you're capable of reading > English you should be able to understand the meaning of the phrase. We started with: Capital letters must be used only for acronyms or proper names. In subsequent mails, we ended up with: Capitalization should correspond to a sentence fragment. In English, capital letters should only be used for acronyms or proper names initials. 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. >> 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? > It is in the man pages that have been updated since the ARC case > approval. None of the newly introduced macros are explicitly in the > interface table of the ARC case. Why should it be different for this one? 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. >> 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. liane
