Quoth Liane Praza on Wed, May 02, 2007 at 02:59:08PM -0700:
> http://cr.grommit.com/~lianep/templates-design/templates-design.html
1. Introduction
- I think you should add some text about which programs should use the
template information, and perhaps to what degree.
2.1 Property groups
- Did you consider naming "pg_pattern" "pg_template" instead?
- Did you consider allowing pg_pattern elements inside property_group
elements? It seems to me that would make life easier to service
authors.
2.2 Property Group Names
- Shouldn't this & 2.3 be subsections of 2.1?
2.2.1 common_name Guidelines
- You should include some examples in this section.
2.5.1 common_name Guidelines
- Should there be a guideline about capitalization, for the C locale
at least?
2.7 Property description
- Is "Not the height." really a good example?
2.8 Property visibility
- Should there be a "not" in "Some properties are internal..."?
- Shouldn't "visibility" be correlated with the property's stability
somehow?
2.9 Property format
- s/separators characters/separator characters/
2.10 Value constraints
- For the value element, why is the value in the "name" attribute?
Couldn't it be the contents of the element, as in
<value>blue</value>
? Particularly since the internal_separators doesn't use an
attribute. What's the difference?
- Is there a relationship between constraints/value and cardinality?
- Is "range" only valid for numeric types?
- Should the "set" attribute of the "valueset" element be named "name"
instead?
2.11 Value choices
- You should probably explain what ``choices'' are before saying that
there is a difference between them and constraints.
- Would "include" be a better name for the "allvalues" element?
- Under what circumstances is the UI author "in the best position to
decide what the user is prepared to see"?
3 Customizations, Precedence, and Errors
"More generally, we must also provide appropriate overrides for
customizations.": You mean you must define rules which allow users to
customize, right?
3.1 Customizations
- A service would only want to further constrain a method when it
consumes the properties, right? I suppose process-based services
may implicitly consume the properties (e.g., arguments), but if it's
possible to do everything through service-specific properties, then
there's no need to do that, right?
3.1.1 Site Customizations
"These templates must be scoped at the same level...": Are you
saying that users are allowed to customize most properties of
a template, but never the scope property?
4.3 svc:/network/inetd
"It will also be updated to clarify...": What will be updated?
4.4 svc:/system/console-login:default
s/wil/will/
5.1 svccfg import checking
- Since -v is already used globally for verbose, I wonder if it would
be better to choose another option letter, to avoid confusion, and
maybe someday to allow -v to be specified on each subcommand, like
the ZFS commands.
6 Library Interfaces
- It seems to me that since template data is so closely associated
with the properties, the scf_ prefix would be appropriate.
I imagine smf_ should be reserved for concepts which involve
restarters. "Visual Panels"' Java APIs made a distinction between
SCF & SMF -- perhaps they should be considered.
6.1 Reading/Description Interfaces
- Might names like "scf_tmpl_get_for_pg" be more user-friendly?
"how do we ensure...": I don't think even the repository's iterators
are guaranteed to return items only once when the underlying
repository is changing.
scf_tmpl_pg_common_name(): I assume this returns the name in the
current locale? Should there be another function which returns the
name in a given locale?
6.2 Validation/Constraint Interfaces
- Please don't use the phrase "editing snapshot". Snapshots are
read-only.
scf_tmpl_value_in_constraint(): Shouldn't this take an scf_value_t?
scf_tmpl_validate_fmri(): Does this accept "editing" as a snapshot
name?
7.1 svcprop
- What does "inline with service" mean?
- Did you consider modifying svcs?
8.1 Existing Template Definitions
- You should explain that flush-left lines denote property group names
and types, and indented lines denote property names and types.
8.2 Property Layout for New Template Information
- You should explain that nt_, n_, and t_ stand for name/type, name,
and type.
- It appears that 'automatic' is only described in "11. Rejected Ideas".
9.1 Template Definition for inetd Property Group
- Would it make sense to have a way to say "this property should be
constrained to the values described in the values element", rather
than relisting them all in the constraints element?
David
