Option syntax

I'm very worried that our syntax for setting options can be really 
confusing, especially given that in-scope options can be referred to in 
options whose values are XPath expressions.

An example from Norm several hundred messages back:

   <p:string-replace>
     <p:option name="match" value="doc/@v"/>
     <p:option name="replace" value="p:position()"/> <!-- NB: value= -->
   </p:string-replace>

   <p:string-replace>
     <p:option name="match" value="doc/@s"/>
     <p:option name="replace" select="p:position()"/> <!-- NB: select= -->
   </p:string-replace>

Norm used comments to draw attention to the fact that the replace option 
was being set with the value attribute in one place and the select 
attribute in another. Using the wrong attribute name is very easy to do 
(especially when the value of the option is an XPath expression and 
you're using to writing 'select=' to set an XPath) but gives the wrong 
result without giving any kind of error.

I think we need to have a bigger distinction between the two methods of 
setting options, namely (a) to a static value and (b) to a dynamic 
value, using an XPath expression.

Possibilities are:

1. Setting the option to a static value must be done through an 
attribute on the step element; setting to a dynamic value must be done 
with the current <p:option> syntax:

   <p:string-replace match="doc/@v" replace="position()" />

   <p:string-replace match="doc/@v">
     <p:option name="replace" select="position()"/>
   </p:string-replace>

Advantages:
  - concise
  - big difference between static and dynamic value syntax
Disadvantages:
  - hard to switch between static and dynamic value
  - possible clashes between option names and standard attributes

2. Setting the option to a static value must be done through the content 
of the <p:option> element rather than a value attribute; setting to a 
dynamic value must be done with the current <p:option> syntax:

   <p:string-replace>
     <p:option name="match">doc/@v</p:option>
     <p:option name="replace">position()</p:option>
   </p:string-replace>

   <p:string-replace>
     <p:option name="match">doc/@s</p:option>
     <p:option name="replace" select="position()" />
   </p:string-replace>

Advantages:
  - moderate difference between static and dynamic value syntax
Disadvantages:
  - uses content rather than attributes

3. <p:option> only has a value attribute, and we use an attribute value 
template syntax to set it to a dynamic value:

   <p:string-replace>
     <p:option name="match" value="doc/@v" />
     <p:option name="replace" value="position()" />
   </p:string-replace>

   <p:string-replace>
     <p:option name="match" value="doc/@s" />
     <p:option name="replace" value="{position()}" />
   </p:string-replace>

Advantages:
  - simple and familiar syntax
  - AVTS are easier to write than concat() calls
Disdvantages:
  - AVTs are a new feature; more work for the spec and implementers

I'd be content with any of the above over the status quo (if forced to 
choose, I'd say 3 was my favourite, then 1, then 2).

Cheers,

Jeni
-- 
Jeni Tennison
http://www.jenitennison.com

Received on Sunday, 27 May 2007 19:37:21 UTC