Quoth Antonello Cruz on Wed, Aug 27, 2008 at 11:41:25AM -0700: > >> http://cr.opensolaris.org/~lianep/templates-0815/ > > > > smf_template(5) ... > > "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."
That's better. Personally, I think you should avoid the term "level", avoid or define the term "templated", describe matching sooner, describe the algorithm by which your interfaces find template information rather than describing which templates apply to which properties, and maybe provide some justification. (Such as "Since multiple components may read properties from a single service, template information is combined from multiple sources...".) ... > > "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. No, I'm considering languages with different capitalization rules. Doesn't German require capitalization of all nouns? Perhaps this would be better stated as something like "Capitalization should correspond to a sentence fragment. In English, capital letters should only be used for acronyms or proper names." ... > > "internal_separators tells us...": Can this be deprecated now that > > SMF Property Value Ordering has been integrated? > > I don't think so. For example a set of range constraints is store a list > of min,max values. E.g. "150,160 155,170". I don't see how Value > Ordering would maintain the semantics of the ranges above. Couldn't you store them as "150 160 155 170" an interpret the first in each pair as the minimum and the second as the maximum? ... > > 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? I don't think it should be. As far as I know, macros, as you're using them here at least, constitute part of the interface, so if they're not declared public in the ARC case, then they shouldn't be recommended in the manpages. Am I missing a loophole or something? > > "The caller is responsible for freeing the *out buffer on success.": > > I presume you mean the caller should use free(3C). Though in the > > past, the library was required to provide its own freeing function > > in case malloc() or free() were interposed, or the function used > > an allocator in a library other than libc. Is that no longer > > necessary due to direct bindings? > > Isn't direct bindings amazing? ;-) I don't think that's a satisfactory answer, but I think I'll decline to press the issue. > > "The scf_tmpl_pg_target() function will retrieve the property > > group's target as currently templated...": I don't understand what > > you mean by a property group's target. Do you mean the template's > > target? > > I would say that terminology is cumbersome all over SMF. We meant the > template Property Group Pattern's target. What is unexpected in this > particular case is that you did not have the same doubt for > scf_tmpl_pg_name() and scf_tmpl_pg_type() since they use the exact same > wording. Anything in particular throw you off? Yes. The word "target". > I discussed the terminology a bit with Tom and we thought that it could > be helpful using pg_pattern to refer to a template Property Group > Pattern and prop_pattern to refer to a template Property Pattern. Both > are somewhat defined in smf_templates(5). Although this terminology > change has the potential to clarify the different terms is some places, > I am sure it will make things more confusing in other places. > Would you have any suggestions on how we could differentiate template > 'Property Group Pattern' from 'Property Group' and template 'Property > Pattern' besides 'pg_pattern' and 'prop_pattern'? > I'll wait Liane's input before start making changes on the docs. I'm not sure what you're asking. Can you provide a concrete example? In this case, I think The scf_tmpl_pg_target() function will retrieve the target of the property group template and place it in *out. would work. > > scf_tmpl_prop_name(3SCF): > > scf_tmpl_prop_internal_seps(): I don't understand how this function > > will fill the scf_values_t. Will there always be a single element > > for the entire string of separators, or will there be a separate > > element for each character of the separators string? > > internal_separators is a list of separator characters. > scf_tmpl_prop_internal_seps() will place one separator as a single > character string in each element of out. > > Do you think > > "The scf_tmpl_prop_internal_seps() function will retrieve the > list of internal separators as currently templated and place > each of them in a different element of out." > > would make it easier to understand or just more wordy? That's easier to understand, though I think it would help to specify that each separator is a single character. > > 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? > > Re-worded to: > "The template validation functions offer a way to validate the > configuration data of an instance FMRI against the appropriate > template data." Better, though I think it should be "service instance" instead of "instance FMRI". If you must have "FMRI" in the text, I would put it in "service instance specified by an FMRI", though that doesn't really seem appropriate outside the context of a specific function. David
