- From: Doug Schepers <schepers@w3.org>
- Date: Wed, 09 Dec 2009 23:44:10 -0500
- To: Steve Withall <steve@withallyourequire.com>
- CC: www-svg@w3.org
Hi, Steve- Thanks for your comments. This is a long email with lots of points, so some of it I still have to consider and discuss with the SVG WG. With the approach of the holiday season, it is unlikely that we will have time to get back to you with a comprehensive reply before late January (we have quite a lot on our plate), but I will give you my initial impressions here, inline... Steve Withall wrote (on 12/8/09 8:16 PM): > > 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. The primer is simply intended as an introduction to the technology for users of the technology to give them a broad overview of how it can be used, and the syntax to use it. The use case and requirements are just before the normative language in the technical spec, which I think it appropriate. > 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. I don't claim particular skill in developing formal use cases and requirements, so if you want to educate me, I would be interested in doing it better. Some concrete examples would go a long way, as well as a summary of overall strategy. I will note that this is a source of quite a lot of difference in opinion in most of the working groups I've participated in. There is a lot of debate as to what is an adequate level of detail for use cases and requirements. In short, specific comments, change requests, and additional use cases or requirements regarding these are welcome; high-level comments like the above may be too open ended for me to know how to satisfy the request. Also, I believe that use cases are meant to be representative of an unknowably large set of uses to which features are put... this is a feature. They represent the minimum set of cases that the features should satisfy. (I don't mean to be terse, but this kind of discussion quickly leads down the rabbit hole.) > 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. As mentioned in the spec, here are the use cases I'm trying to solve, based on my own authoring experience and the feedback of other authors: * Adapt colors to fit theme * Change size or position of graphical elements * Hide or show elements * Adapt text to use * Change link locations * Change aspects of 'use' content I think those are very specific, and I think Params as specified meets those cases adequately. I am open to better mechanisms, but I haven't yet seen one that seems a better fit. > 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. My personal opinion is that the spec is at the right level of power vs. ease of use. All too often, new features take on a life of their own, growing in complexity without direct implementation and author experience. I am adamant that this should not happen with SVG Params. While the spec will almost certainly go through some changes before its done, I don't think it's appropriate for it to get much more complex than it is right now. > In any case, the ability to add more sophistication in future without > major disruption would be a useful requirement to add. Though that's a reasonable requirement in general, I'm not sure how this specification could address it without adding another level of complexity. If you (or anyone) suggests a way to do so, I would add it. In fact, I think that Params already satisfies the level of sophistication needed for this feature. All suggestions I have heard that make it more comprehensive also make it much more complicated, or duplicate functionality found in other languages such as CSS or XSLT. Keep in mind that this is just one part of SVG, and it's meant to work in combination with other features to provide a more powerful whole. > 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. If an author is making a document that has more than a few parameters, I would argue that they are doing it wrong. As with O-O design, simple reusable components are what this spec aims to address. I am happy to put a note in the spec to that effect. What sort of documents do you have in mind that would require such complexity? I know you have a sophisticated implementation with SVG as a central part of an application framework, but for most uses of SVG I envision it being most applicable to compound documents using both SVG and HTML, so smaller, more discrete SVG components seem most appropriate. > 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. On the contrary, I think it is a good idea to use it for alternate languages... why do you think it's not? > 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. I have been actively inviting suggestions, by presenting on this at conferences. That's also the goal of public Working Drafts. > 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.) Yes, I'd love to see people putting this into practice. That's one reason I implemented it in Javascript, to allow authors to play with it and find where it falls down. So far, I haven't heard back much about it, but hopefully as the spec becomes more widely known, we will. For what it's worth, I'm not a huge fan of the idea of sending parameters via the URL string, but it's a case that must be covered. > 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?) The SVG WG discussed this, and in light of the fact that we plan on allowing more functional notations as attribute/property values for layout, we didn't feel that "param()" adds significant burden. Implementer feedback is obviously going to be taken into consideration. > 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!) See above. This is only one of several similar additions we are considering along these lines. > 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. While not trying to say that "tools will save us", one of the scenarios I had in mind was that authoring tools would expose these keywords, their associated property or attribute, and perhaps display some permutations on these. For example, a clipart gallery could show several variations on a theme with the same image, or an authoring tool could highlight those parts of the image which are subject to parameterization. > 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.) SVG specs cannot make requirements on other specifications. If DocBook or ODF or some other markup language or framework provides an adequate way to pass parameters that can be interpreted by a conforming SVG Param implementation, it is not the place of this spec to disallow that... in fact, I encourage it, because we do not know all the environments that SVG is or will be used in. For example, Company Gamma may make a set-top-box framework where they pass parameters this way: <component file="mybutton.svg" color="red" label="Record" /> As long as they hook that into SVG Params the right way, I think that's just fine. > 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. Agreed. Do you have any specific points to add? > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > 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. You're right... I'm not sure why I did that this way... it is still just an early draft, but I should have different sections for "Definitions and Basic Data Types" and "Syntax". > (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.) The two documents are intended for different audiences. We've heard feedback in the past from implementers that they don't want user examples in the normative document, and from authors that they find the technical implementation details too be confusing. By splitting them out into paired documents, we address those concerns. The repetition isn't that much overhead. > 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.) I'm not sure what you mean... are you referring to the spec format ('usage document' == Primer, 'declaring document' == Language Spec), or > 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.) I can add a note to the spec to that effect, but I think any implementer reviewing it could hardly fail to take note of the implications. > 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. I wanted to first run the idea by the CSS WG before saying anything about property values in CSS syntax. Early feedback from the CSS WG seems positive, so it is likely that it will apply to property values as well. (Note that the presentation attributes like 'fill' are still attributes, even if they can also be expressed as properties.) > 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. This is easily done with the current proposal... for example, passing the parameter 'color:blue' to this file would result in both the stroke of the rectangle and the fill of the text being blue. <svg ...> <rect stroke="param(color) red" ... /> <text fill="param(color) black" ... >Label</text> </svg> Any attribute that uses the same param keyword would have the same value passed in. > (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. Different parameters cannot have the same name. Yes, if a file is composed which uses multiple parameters that have the same name for different purposes, something may break... authors shouldn't do that. Obviously, the lacuna value would be used for anything that didn't have the right value type (fill="8.54" would result in a black fill, cx="green" would result in cx="0"). > B6. "The 'param' Attribute", fifth paragraph: Point B5 (b) leads to the > subject of error handling, which I think your specification ought to > addressexplicitly. What I had in mind (but which it seems I haven't yet put into the spec) is that if a fallback is provided (cx="param(posx) 20%"), and a parameter doesn't match the expected value types for that attribute, then the fallback value ("20%") is used. > 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 > sincethey 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. Agreed. I had planned to be more explicit in how the parameter names are exposed to external examination... maybe providing a list of the expected parameters and their datatypes in the Parameters API would be useful in this respect. > 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. Regarding error messages, I will put in a note that mismatched values for attributes should be reported to a UA's error console for the file it's found it (which is already defacto SOP), with the suggestion that the parameter name and expected value type also be provided, along with the file name of the document where the parameter was declared. > 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.) This is why I introduced the <param> element into SVG, for referencing elements like <use>, with the <param@value> also able to take the 'param()' keyword. The author explicitly states the parameter names and values passed to the referenced file: <use xlink:href="someExternalFile.svg#root"> <param name="p1" value="param(p1)" /> <param name="dot" value="param(color)" /> <param name="x" value="param(y)" /> <param name="y" value="50%" /> </use> By decoupling the parameter names and values this way, each component file is indeed self-contained, but can easily be made part of an inheritance chain. In fact, an SVG file which is called with parameters, and which in turn calls parameterized components, might not use the parameters for any other purpose than to pass them on to the referenced files. > 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. Yes, I had the same thought myself, but hadn't acted on it yet. I will do so. > B9. The 'parameters' property: Good luck to anyone who attempts to animate > a list of parameters! What specifically are you saying is the problem? >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. My chief concern is with empowering authors. Implementors are considered, of course, but if I have to make a choice between making the lives of millions of authors easier or the lives of a few implementers easier, I will choose the authors every time. As a corollary to that, I have to make sure that the feature is easy enough to implement consistently, and well-specified enough to do so interoperably. So, in that respect, I am sensitive to the concerns of implementers. To that end, I have taken to the practice of writing a script implementation of the features I'm specifying, to make sure that they are implementable (at least to some degree... I realize that there are differences between how easy something is to accomplish in script vs. C*/Java/etc.), that they cover the details that are needed, and they are usable by authors. There are parts of SVG Param that I removed or never put in because my personal experience taught me that it wasn't a good approach. >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! :) I rely on my own authoring and implementing experience to inform most of my judgments, yes. Different implementers and implementations (and authors) may draw different conclusions than I do... that's why these specifications are open for review. Creating a spec (especially in these early stage) is an iterative process. In this particular instance, I hadn't gotten around to thinking deeply about the 'parameters' property... I should have marked it as a placeholder while I talked to the CSS WG and looked at implementing it myself. But a more productive (and less confrontational) way to comment on this or other issues would be to explain the specific performance and implementation challenges, and suggest a way to resolve it. > 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. Complicating the URL syntax and forcing users to reference a specific id along with the parameter name seems very unwieldy to me. > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > 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> Indeed, this is very similar to the first approach I took [2]. We moved away from that for a number of reasons, including a more verbose syntax, an additional level of abstraction, and because we plan on introducing new attribute value syntax anyway. What you're suggesting can be done using CSS or paint servers (gradients, solidColor, etc.) in combination with Params, i.e. the 'param()' functional notation is used for the gradient or solidColor, which is referenced by the target element (the value is "pulled" by the target element), or for the CSS values which are applied to the target elements via selectors (the value is "pushed" onto the target element by the class). > 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. CSS selectors are a similar mechanism to XPath, and more broadly implemented, in browsers at least. > 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. Though I don't like using CSS-injected text content, that could be used as well. > 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. This is well down the side of the slippery slope... I don't want Params to become a Turing-complete feature. At the very most, I would suggest using <switch> elements with a new evaluation attribute, but for v1, I think that goes too far. > (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.) That should fall more into the realm of SVG Layout, possibly in conjunction with SVG Params. > 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. No, it doesn't... we could always add these features for use with the abstraction of paint servers, CSS, etc. if experience shows that they are needed. > 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. As mentioned, the "param(...) ..." construct matches the planned growth of SVG. > 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. This can be done with the existing proposal as well, as explained above. > Ad3. The parameter-related elements provide a place to *document* the > parameters (which the existing specification does not provide). Comments can be placed at any place in the document to explain these, and exposing the list of param keywords through the API is more programmatically useful. > 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. I'm not sure why this is a particular advantage. > 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. What sort of enhancements? I'm not trying to be negative, but I don't see your proposal as substantive more powerful or specifically easier to implement, and it seems much more complicated and abstract to author. The SVG WG will discuss it, of course, and may have a different opinion than I do. I do appreciate your thought-provoking comments, and I think the spec will be improved by them. I will try to make an updated version of the spec that reflects the changes I've agreed to in the next few weeks, and I'll notify you and www-svg when I have. [1] http://www.w3.org/TR/SVGParamPrimer/#param-el [2] http://dev.w3.org/SVG/modules/ref/master/SVGRefPrimer.html Regards- -Doug Schepers W3C Team Contact, SVG and WebApps WGs
Received on Thursday, 10 December 2009 04:44:22 UTC