David Bustos wrote:
> Quoth Antonello Cruz on Wed, Aug 27, 2008 at 11:41:25AM -0700:
>> "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...".)
I'll try to re-work this paragraph and post it here later.
For now, I am not comfortable with the term "templated" too, but that
may be because English is not my first language...
I am kind of struggling to find a different term for level. I thought of
scope but I don't want to overload the term that is already used in SMF.
At the lack of a better term (I am assuming you don't have any
suggestions) I'll keep level but I'll try to give it some context.
>
> ...
>>> "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."
I see your point and agree with it. But there is room for improvement:
"Capitalization should correspond to a sentence fragment. In English,
capital letters should only be used for acronyms or proper names initials."
After all we want 'David Bustos', not 'DAVID BUSTOS', right? ;-)
I made changes in all occurrences of "- Capital letters..."
>
> ...
>>> "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?
This could work for ranges because we know each range is made of two
values, what about the case where we don't know how many values should
be in each list element? For instance "10,15,18 12 13,10". No, I don't
have a use case.
>
> ...
>>> 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?
I see your point and I tend to agree with you. But I don't quite
understand why macros such as SCF_TMPL_VALIDATE_FLAG_CURRENT, SCF_TERR_*
defined in scf_tmpl_validate_fmri(3SCF) but not in the interface table
of the ARC case are a different case.
>
>>> "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
I think there are two confusing terms. One is property group that is a
configuration data and is defined in the xml tag <property_group> in the
manifest. The other is the property group template pattern that is
metadata for the property group and is defined under the xml tag
<pg_pattern> in the manifest. We have a similar case for property
(<propval> in the manifest) and property template pattern (<prop_pattern>).
I am not sure how's the best way to differentiate them without using the
word template.
>
> The scf_tmpl_pg_target() function will retrieve the target of the
> property group template and place it in *out.
>
> would work.
Agree, this works and may also answer my question above...
I'll also change the phrase for scf_tmpl_pg_{name|type}().
>
>>> 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.
re-phrased to:
"The scf_tmpl_prop_internal_seps() function will retrieve the list of
internal separators as currently defined in the template. Each
separator will be a single string character in a different element of
out."
>
>>> 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.
I agree with you, I have changed 'instance FMRI' to 'service instance'.
I am afraid this would also call to change the function name to
scf_tmpl_validate_instance(3SCF) but I'll wait for consensus (and
self-convincing) before making such a change.
Antonello
