[Parameters] specifications feedback

Doug,

Here is some feedback on your Parameters specification "SVG 
Parameters 1.0, Part 2: Language" (undated, but last modified 10th 
June 2009). I am not commenting on Part 1, because I believe that 
Part 2 gives me the opportunity to make every point of substance I 
have. I've divided my comments into two parts for readability, plus a 
third proposing a different way of declaring parameters.

Steve.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A. Comments on Part 2, "Use Cases and Requirements" section
===========================================================
A1. Requirements and use cases ought to precede everything else - and be
      written before you consider what might be the best solution to them  :)
      - so I find it strange that they are deferred to the second document.

A2. "Usage Scenarios": This list of usages is helpful, but since they're
      examples they are merely anecdotal. They don't constitute a statement
      of the goals for parameters, which is lacking. The closest you come is
      saying in the Abstract of Part 1 that they're for "re-using a resource
      several times with specified variations", but this is vague and open
      to many interpretations.

     In recent emails, Doug, you have stated that you want to keep the
      Parameters specification simple. But without clearly defining what
      parameters are for, one cannot make an objective judgment of whether
      what's currently specified is adequate, nor whether suggestions for
      extra sophistication are good value or not. BTW, when you say 
enhancements
      could be added in future, what do you mean? SVG 3.0 in 2017?  :^)
      You ought to do you utmost to get it right first time.

     In any case, the ability to add more sophistication in future without
      major disruption would be a useful requirement to add.

A3. "Usage Scenarios": Simplicity in the Parameters specifications is one
      thing; simplicity in the documents that use parameters is something
      else. How many parameters might document authors end up using in a
      single document? All your examples are simple (which is fine), but
      it's not hard to envisage parameters numbering in the dozens. A
      single flat list is less than ideal when it grows longer than, say,
      eight or ten.

A4. "Adapt text to use": This is potentially very useful, but might quickly
      become unwieldy if you have more than one or two text parameters
      (especially when passing via a URL, or for long pieces of text). Some
      authors might be tempted to use this to achieve multi-lingual text,
      which is probably not a good idea.

A5. "Usage Scenarios": The previous point leads me to suggest that you
      investigate possible usage scenarios in more detail: if (sorry, when!)
      you give document authors this parameters facility, what uses might they
      put it to that you haven't thought of? You wouldn't want any nasty
      surprises. Perhaps you could invite suggestions. Some usages could
      be horrible bastardizations. Some might be worth considering in their
      own right, to allow them to be achieved in a cleaner and easier way.

     When investigating in more detail, you ought to create examples that
      are as complex as authors might create in real life. (A 12-month
      bar chart with 6 parameters per month?) The existing examples are
      so simple that they don't tell you much about usage in practice.
      How do parameters scale up? Just how long might long URLs become?
      (Longer than you anticipate, I anticipate.)

A6. "Special Considerations for SVG Parameters", "Implementation
      commitments": For all you say about keep Parameters simple, I
      believe that implementing them as specified is likely to involve
      considerable effort - because of the sheer number of attributes
      that must support the "param(...) ..." syntax. (Would the major
      implementers care to consider this and give us their verdicts?)

A7. Following on from A6, I suggest that the Working Group ponder
      whether any other forthcoming SVG enhancements have a similarly
      wide impact upon existing attributes en masse, so that implementers
      can make all these changes in one go. I have in mind the potential
      for the layout specification to introduce expressions. (I live in
      hope!)

A8. "Special Considerations for SVG Parameters", "Ease of authoring":
      The first consideration is to make it easy for authors to know
      what parameters are available to them when they re-use a particular
      SVG document. I have more to say on this below, because it is a
      consideration I believe is not satisfied at present.

A9. "Requirements", point 1.1: Remove the "(but not limited to)" clause.
      It renders this requirement open-ended, which is unacceptable. Adding
      a new means of passing parameters constitutes an extra requirement.
      (Each existing means ought to be regarded as a distinct requirement too.)

A10. "Requirements", points 2 and 3: Yes, you need to say more about
       scripting and animation! Nasty complications might lurk in both
       places, and you need to flush them out as soon as you can.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
B. Comments on Part 2, "Definitions and Basic Data Types", "Syntax" section
===========================================================================
B1. I find that this document lacks structure. There are two distinct parts
      to Parameters: usage (the documents that refer) and declaration (the
      documents that are referred to). I think everything would be clearer
      if you had two clear top level sections accordingly. The "Syntax" section
      launches into the declaration aspects without introducing that that's
      what it's doing.

     (Actually, if you do choose to restructure Part 2, you could also consider
      merging Parts 1 and 2 into a single document. Two documents are not
      warranted for reasons of size, and a single document would allow you to
      avoid the repetition that is necessarily present now.)

B2. Further to B1, the subject of parameters would be easier to write about
      if we had clear terms for the 'usage' documents and for the 'declaring'
      documents. (I'm finding it hard to decide how to refer to them in this
      email. For want of something better, I call them the 'usage document'
      and 'declaring document' respectively.)

B3. "The 'param' Attribute", fourth paragraph: In order to stress how pervasive
      this change is, you ought to highlight as boldly as you can the statement
      that the "param attribute value must be available as a value on any SVG
      attribute". Further, I would change 'any' to 'every', and add "on every
      SVG element". The implications of this are considerable: 
potentially large
      development effort by implementers (and perhaps even more for 
authoring tool
      developers), extra tests for every attribute in every SVG element, and
      ... what else? (My proposed alternative, described below, avoids all
      of these changes.)

B4. "The 'param' Attribute": Any changes you make to attribute values ought
      also to apply to property values too, for consistency. Am I correct in
      believing that to date the values allowed in all property values are
      identical to the values allowed in the equivalent attributes? If so,
      this commonality should be maintained.

B5. "The 'param' Attribute", fifth paragraph: You are correct that this section
      needs a lot of work. This section deals only with the local syntax for
      declaring a single parameter, which is relatively straightforward. A
      separate topic, which deserves a new section in its own right, is
      interactions between multiple parameter declarations. Topics that need
      addressing include:

       (a) Multiple parameters with the same name. This is useful and is
            presumably acceptable, to allow one parameter to affect multiple
            parts of the re-used document at once. For example a 'color'
            parameter could set the color of several sub-elements.

       (b) Inconsistencies between parameters with the same name. For example,
            if parameter name 'p1' is a color attribute in one place and a
            co-ordinate in another, then ... well ... something's gonna break.
            A declaring document is in a position to detect such 
inconsistencies
            - but only by navigating the whole document tree to find all
            parameter declarations.

B6. "The 'param' Attribute", fifth paragraph: Point B5 (b) leads to the subject
      of error handling, which I think your specification ought to 
address explicitly.
      The validity of a parameter value written in a 'usage' document 
can only be
      determined by reference to its declaration in a separate 
document. This could
      lead to errors that aren't easy to explain to the user 
(especially since they
      may otherwise have no cause to look into the declaring 
document; indeed, one
      of the benefits of parameters is that they don't need to). This 
is an area
      where implementers need to take extra care with their error 
messages. Perhaps
      the Parameters specification could lay down some guidelines.

B7. "The 'param' Attribute", fifth paragraph: Further to B6, one 
source of errors
      in parameters is in data typing: an attribute might expect a 
color, but be
      given a length. Such errors are usually straightforward to deal with, but
      the fact that the value is supplied by one document and validated with
      reference to another introduces an extra level of complexity.

B8. Another situation to consider is an SVG document both declaring and
      using parameters. That is, a declaring document could refer to other
      documents that use parameters. This would appear to cause no problems
      if each usage is treated as self-contained. But might document authors
      want the parameter mechanism to percolate down the chain of referenced
      documents? For instance, if document A uses a parameter 'p1' in document
      B, and document B uses a parameter 'p1' in document C, should the same
      value of p1 passed from A to B also be passed to C? (I hope you 
can follow
      that.)

     Your 12-month bar chart example in Part 1 might benefit from a two-level
      declaration of this kind (especially if you wished to make it 
more complex):
      one document for the bar chart and a separate one for a column.

B9. The 'parameters' property: Good luck to anyone who attempts to animate
      a list of parameters! I suspect that specifiers of standards have a
      tendency to throw in any feature which is easy for them to write. Making
      a property inheritable and animatable is for you a matter of a few
      keystrokes. Ditto your policy of making every new attribute a property
      (which I dislike, find ridiculous for some attributes, and regard as
      not in the spirit of the original SVG standard). Do you 
adequately consider
      the implications each time you slip in (or copy in) such innocuous words?
      Conscientious as you are, you're not superhuman, so I imagine you can't.
      If in doubt, leave it out! Deliver on your promise to keep parameters
      simple!  :)

And one more suggestion which I'll put here to save me creating a 
whole new section for it:

B10. You use parameters to reference a whole SVG document. There's no reason
       why you couldn't reference a single element. This would allow multiple
       related 'referencable' elements to be placed in one document, which
       would give authors more flexibility, reduce the number of documents,
       potentially reduce the number of resources that need to be loaded, and
       allow these elements to share the same <defs> element (thus avoiding
       repetition).

      To do this would complicate the URL format to include the ID of the
       element to reference - but that's not a big deal.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Proposal for an alternative to "param(...) ..." attribute values
================================================================
Rationale: The problem of discovering what parameters can be passed 
to a particular declaring document led me to consider the analogy 
with programming languages. Functions in high level programming 
languages typically (always?) declare all their parameters at the 
beginning, which makes it clear what parameters to pass. A 
programming language that let you declare parameters anywhere in the 
body of a function's code would be considered very strange. Isn't 
that what the Parameters specification does?

(Another analogy is to the animation of attribute values: SVG 
sensibly has separate animation elements, rather than attempting to 
pack the definition of an animation into an attribute's value - which 
is effectively what "param(...)" does for parameters.)

An alternative is to declare all an SVG document's parameters in one 
place, as near the beginning of the document as possible - perhaps in 
the <defs> element. The declaration of a parameter needs a name plus 
references to one or more attributes that its value can be passed to. 
(An attribute value is not needed, because each attribute's normal 
value plays this role.)

The equivalent of the SVG document in the "Passing Values to SVG 
Files" section in your specification Part 1 might be something like:

<svg xmlns="http://www.w3.org/2000/svg" 
xmlns:xlink="http://www.w3.org/1999/xlink"
     viewBox="0 0 110 40" width="100%" height="100%">
   <defs>
     <paramDefs>
       <paramDef name="color" elementId="button_rect" attribute="fill"/>
       <paramDef name="outline" elementId="button_rect" attribute="stroke">
         <paramDef elementId="button_label" attribute="fill"/>
       </paramDef>
       <paramDef name="label" elementId="button_label"/>
     </paramDefs>
   <defs>
   <title>Reusable Button</title>
   <desc>Takes parameters from parent document's embedding element.</desc>
   <g>
     <rect id="button_rect" x="5" y="5" width="100" height="30" 
rx="15" ry="15"
       fill="blue" stroke="navy" />
     <text id="button_label" x="55" y="30" text-anchor="middle"
       font-size="25" fill="black" font-family="Verdana">
       button
     </text>
   </g>
</svg>

Miscellaneous points and extra suggestions:

C1. I have modified the example to apply the 'outline' value to the fill
      of the <text> element too, to demonstrate using a parameter in more than
      one place. (And I lazily used the same <paramDef> element name for the
      child element, which is probably inadvisable, but I couldn't think
      of a good alternative quickly.)

C2. This example references elements by ID, but XPath could be offered as
      an alternative.

C3. The last <paramDef> element refers to the content of the <text> element.
      This is (supposedly) implied by the absence of an 'attribute' attribute,
      but it could be done in a more explicit way.

C4. Elements defining parameters could be further nested, to group related
      parameters. This could be convenient where many parameters are declared.
      This would result in hierarchical names, for which a dot notation might
      be suitable (eg. "may.percent" and "may.color", in your bar 
chart example).

C5. The passing on of parameters to other documents with parameters (as per
      point B8 above) would probably demand its own extra constructs.

C6. To support the referencing of a single element (as per point B10, above),
      any SVG element could be allowed to contain a <paramDefs> element.

C7. Parameters could be used for more than just passing values directly to
      attributes and properties. Two possibilities:

      (a) Conditional logic. For example, a parameter definition could say
           that if parameter "side" equals "left" then change an attribute
           in one element, else change an attribute in another.

      (b) As the basis for calculations, which could be useful for laying out
           elements. For instance, in your 12-month bar chart example 
in Part 1,
           you could have a "column-width" parameter that is used to calculate
           the position of each column. (In the preamble to that example you
           admit that parameters as specified have limitations; enhanced
           <paramDef> elements could overcome some of these limitations.)

     There are likely to be other interesting possibilities - which can be
      added relatively easily because they are merely additions within the
      <paramDefs>. The "param(...) ..." construct slams the door shut against
      such possibilities.

This approach offers several advantages:

Ad1. The new parameter-related elements are the *only* changes. No attributes
       or properties in existing elements need be changed. There is no need
       for the "param(...) ..." construct, nor the "content-value" attribute.

Ad2. All the parameters are declared in one place, at the top of the document.
       So it's easy to see what they all are.

Ad3. The parameter-related elements provide a place to *document* the 
parameters
       (which the existing specification does not provide).

Ad4. Checking parameters for consistency involves checking just the content
       of the <paramDefs> element and the elements its descendents refer to,
       rather than the whole document tree.

Ad5. Future enhancements have a good chance of being localized to the
       parameter-related elements, rather than potentially involving further
       rounds of changes to all attributes in all elements.