Interoperating with Shepherd

[annevk]

@plinss and @tabatkins maintain a tool that Bikeshed specifications use for cross-references. At the moment HTML works poorly with that tool, for instance by defining "origin" three times. We should find some way to work better.

[tabatkins]

Here's Bikeshed/Shepherd's scraping contract https://github.com/tabatkins/bikeshed/blob/master/docs/dfn-contract.md.

We just need to update the <dfn> elements to match up with this. We can do this piecemeal, as WHATWG specs (and others) realize they need to link into HTML. For a start, just go through every WHATWG spec so far and look at all the HTML links in <pre class=anchors>, and annotate them so they can be removed from that block.

[plinss]

Here's Shepherd's algorithm for identifying <dfn> anchors.

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 recognizes the following construct types for <dfn> anchors in specifications:
CSS: 'property', 'value', 'at-rule', 'descriptor', 'type', 'function', 'selector', ‘token', 'grammar', 'concept'
HTML/SVG: 'element', 'element-attr’
IDL: 'event', 'interface', 'constructor', 'method', 'argument', 'attribute', 'iterable', 'maplike', 'setlike',
'serializer', 'stringifier', 'callback',
'dictionary', 'dict-member', 'enum', 'const', 'typedef', 'http-header'

Shepherd classifies <dfn>s 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'
   'grammardef' -> 'grammar'
   'conceptdef' -> 'concept'
   'elementdef-‘ -> 'element'
   'element-attrdef-‘ -> 'element-attr'
   'eventdef-‘ -> 'event'
   'interfacedef-‘ -> 'interface'
   'constructordef-‘ -> 'constructor'
   'methoddef-‘ -> 'method'
   'argdef-‘ -> 'argument'
   'attrdef-‘ -> 'attribute'
   'iterdef-‘ -> 'iterable'
   'mapdef' -> 'maplike'
   'setdef' -> 'setlike'
   'serialdef-‘ -> 'serializer'
   'stringdef-‘ -> 'stringifier'
   'callbackdef-‘ -> 'callback'
   'dictdef-‘ -> 'dictionary'
   'dict-memberdef-‘ -> 'dict-member'
   'enumdef-‘ -> 'enum'
   'constdef-‘ -> 'const'
   'typedefdef-‘ -> 'typedef'
   'http-headerdef' -> 'http-header'

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 a class of one of the id prefixes from step 2.

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.: <foo> -> ‘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>

There should only be a single <dfn> that defines each term, however, it is possible to have additional <dfn>s for the same term that extend or obsolete others. To extend or obsolete other <dfn>s add the attribute 'data-dfn-extends' or 'data-dfn-obsoletes' to the <dfn> or an ancestor. While <dfn>s define by default, you can also add the attribute 'data-dfn-defines' to override an extend or obsolete from a parent element.