Fwd: Marking up specs for Shepherd's spec parser

-------- Original Message --------
Subject: [Moderator Action] Marking up specs for Shepherd's spec parser
Date: Fri, 15 Nov 2013 11:52:23 +0000
From: Peter Linss <plinss@csswg.org>
To: SVG WG <public-svg-wg@w3.org>

As discussed at TPAC, Shepherd recognizes the following construct types 
for <dfn> anchors in specifications:
 CSS: 'property', 'value', 'at-rule', 'descriptor', 'type', 'function', 
'selector', ‘token'
 HTML/SVG: 'element', 'element-attr’
 IDL: 'event', 'interface', 'constructor', 'method', 'argument', 
'attribute', 'iterator',
             'serializer', 'stringifier', 'callback',
             'dictionary', 'dict-member', 'exception', 'except-field', 
'enum', 'const', 'typedef'

Note that Shepherd recognizes a <dfn> “anchor” as:
1) a <dfn> element with an ‘id’ attribute
2) an <a> element with a ‘name’ or ‘id’ attribute that contains a <dfn>
3) a <dt> with an ‘id’ that contains a <dfn>
4) a <dfn> inside a section heading that has an ‘id’ with the value: 
‘the-*-element’ (HTML5 compat)


Shepherd classifies <dfn> according to the following logic (first match 
wins):

1) a ‘data-dfn-type’ attribute on the <dfn> with a valid type, e.g.: 
<dfn id=“foo” data-dfn-type=“element”>svg</dfn>

2) an ‘id’ on the <dfn> (or container <a> or <dt> with the ‘id’) that 
has one of the following prefixes (e.g. <dfn 
id=“elementdef-image”>image</dfn>):
     'propdef-‘ -> 'property'
     'valuedef-‘ -> 'value'
     'at-ruledef-‘ -> 'at-rule'
     'descdef-‘ -> 'descriptor'
     'typedef-‘ -> 'type'
     'funcdef-‘ -> 'function'
     'selectordef-‘ -> 'selector'
     'tokendef-‘ -> 'token'
     'elementdef-‘ -> 'element'
     'element-attrdef-‘ -> 'element-attr'
     'eventdef-‘ -> 'event'
     'interfacedef-‘ -> 'interface'
     'constructordef-‘ -> 'constructor'
     'methoddef-‘ -> 'method'
     'argdef-‘ -> 'argument'
     'attrdef-‘ -> 'attribute'
     'iterdef-‘ -> 'iterator'
     'serialdef-‘ -> 'serializer'
     'stringdef-‘ -> 'stringifier'
     'callbackdef-‘ -> 'callback'
     'dictdef-‘ -> 'dictionary'
     'dict-memberdef-‘ -> 'dict-member'
     'exceptdef-‘ -> 'exception'
     'except-fielddef-‘ -> 'except-field'
     'enumdef-‘ -> 'enum'
     'constdef-‘ -> 'const'
     'typedefdef-‘ -> 'typedef'

2a) if the <dfn>’s ‘id’ has one of the following “magic” prefixes (for 
legacy support, not recommended):
     ‘attr-‘ -> ‘attribute’
     ‘interface-‘ -> ‘interface’
     ‘dom-‘ -> some IDL construct
         the contents of the <dfn> will be searched for in any parsed 
IDL, if not found, then use the heuristics:
             if the <dfn> content starts with an uppercase letter -> 
‘interface’
             if it looks like a function (match '^[^ ]+\([^\(]*\)$’) -> 
‘method’
             else -> ‘attribute’

3) search for the contents of the <dfn> in parsed IDL, if it matches the 
name of an IDL construct, use that type

4) look for the nearest ancestor with a valid ‘data-dfn-type’ attribute, 
or one of the following classes:
     'propdef' -> 'property'
     'valuedef' -> 'value'
     'at-ruledef' -> 'at-rule'
     'descdef' -> 'descriptor'
     'typedef' -> 'type'
     'funcdef' -> 'function'
     'selectordef' -> 'selector'
     'tokendef' -> 'token'
     'elementdef' -> 'element'
     'element-attrdef' -> 'element-attr'
     'eventdef' -> 'event'
     'interfacedef' -> 'interface'
     'constructordef' -> 'constructor'
     'methoddef' -> 'method'
     'argdef' -> 'argument'
     'attrdef' -> 'attribute'
     'iterdef' -> 'iterator'
     'serialdef' -> 'serializer'
     'stringdef' -> 'stringifier'
     'callbackdef' -> 'callback'
     'dictdef' -> 'dictionary'
     'dict-memberdef' -> 'dict-member'
     'exceptdef' -> 'exception'
     'except-fielddef' -> 'except-field'
     'enumdef' -> 'enum'
     'constdef' -> 'const'
     'typedefdef' -> 'typedef'

5) look at the <dfn> text content and use the following heuristics:
     if the <dfn> content starts with ‘@‘ -> ‘at-rule’
     if the <dfn> content is quoted, e.g.: "foo", 'foo', “foo”,  “foo”, 
or ‘foo’ -> ‘value’
     if the <dfn> content starts with ‘<‘ and ends with ‘>’, e.g.: 
&lt;foo&gt; -> ‘type’
     if the <dfn> content starts with ‘:’ -> ‘selector’
     if the <dfn> content looks like a function and the ‘id’ does not 
start with ‘dom-‘ -> ‘function’


Shepherd also maintains any relationship between anchors, e.g. which 
element is an attribute defined for. The logic for determining that is 
as follows (first one wins):

1) if the <dfn> has the attribute ‘data-dfn-for’, e.g.: <dfn 
id=“image-width” data-dfn-type=“element-attr” 
data-dfn-for=“image”>width</dfn>

2) if the <dfn> is an IDL construct, extract the ‘for’ from the IDL

3) look for the nearest element ancestor with a ‘data-dfn-for’ 
attribute, e.g.:
     <div data-dfn-for=“image” data-dfn-type=“element-attr”>
         <dfn id=“image-width”>width</dfn>
         <dfn id=“image-hieght”>height</dfn>
     <div>

Received on Sunday, 17 November 2013 07:24:13 UTC