====== Specification Parser ====== Shepherd parses a number of W3C specifications in order to determine available valid link anchors. While doing so, it also recognizes the specification structure and attempts to classify the anchor. Anchors for definitions of web platform constructs are further classified and relationships identified. This document explains the techniques the parser uses to identify definition anchors so that specification authors can assist the accurate gathering of information by providing appropriate markup. For the most part, the parser attempts to re-use existing styling and semantic markup practices, but there are also some specific steps authors can take to override default assumptions when necessary. Note that the Bikeshed spec pre-processor automatically generates the appropriate markup and spec authors need take no action beyond what Bikeshed requires for generating specification cross-references. ===== Definition Anchors ===== Shepherd recognizes any of the following as a definition anchor: * a element with an 'id' attribute * an element with a 'name' or 'id' attribute that contains a * a
element with an 'id' that contains a * a inside a section heading that has an 'id' with the value: 'the-*-element' (HTML5 compat) In addition to the default 'dfn' anchor type, definition anchors are clasified as one of the following types: ; CSS : 'property', 'value', 'at-rule', 'descriptor', 'type', 'function', 'selector', 'grammar', 'token' ; HTML/SVG : 'element', 'element-attr', 'element-state', 'attr-value' ; WebIDL : 'event', 'interface', 'constructor', 'method', 'argument', 'attribute', 'extended-attribute', 'iterator', 'maplike', 'setlike', 'serializer', 'stringifier', 'callback', 'dictionary', 'dict-member', 'enum', 'enum-value', 'const', 'typedef', 'exception', 'except-field', 'except-code' ; Other : 'concept', 'abstract-op', 'state', 'mode', 'context', 'facet', 'http-header', 'scheme' ==== Identifying Anchors ==== Shepherd classifies definition anchors according to the following logic (first match wins): - A 'data-dfn-type' attribute on the with a valid type image - An 'id' on the (or container or
with the 'id') that has one of the following prefixes: image * 'propdef-' -> 'property' * 'valuedef-' -> 'value' * 'valdef-' -> 'value' * 'vdef-' -> 'value' * 'at-ruledef-' -> 'at-rule' * 'descdef-' -> 'descriptor' * 'typedef-' -> 'type' * 'funcdef-' -> 'function' * 'selectordef-' -> 'selector' * 'grammardef-' -> 'grammar' * 'conceptdef-' -> 'concept' * 'abstract-opdef-' -> 'abstract-op' * 'statedef-' -> 'state' * 'modedef-' -> 'mode' * 'contextdef-' -> 'context' * 'facetdef-' -> 'facet' * 'elementdef-' -> 'element' * 'element-attrdef-' -> 'element-attr' * 'element-statedef-' -> 'element-state' * 'attr-valuedef-' -> 'attr-value' * 'eventdef-' -> 'event' * 'interfacedef-' -> 'interface' * 'constructordef-' -> 'constructor' * 'methoddef-' -> 'method' * 'argdef-' -> 'argument' * 'attrdef-' -> 'attribute' * 'extendedattrdef-' -> 'extended-attribute' * 'iterdef-' -> 'iterator' * 'mapdef-' -> 'maplike' * 'setdef-' -> 'setlike' * 'serialdef-' -> 'serializer' * 'stringdef-' -> 'stringifier' * 'callbackdef-' -> 'callback' * 'dictdef-' -> 'dictionary' * 'dict-memberdef-' -> 'dict-member' * 'enumdef-' -> 'enum' * 'enum-valuedef-' -> 'enum-value' * 'constdef-' -> 'const' * 'typedefdef-' -> 'typedef', * 'exceptdef-' -> 'exception' * 'except-fielddef-' -> 'except-field' * 'except-codedef-' -> 'except-code' * 'http-headerdef-' -> 'http-header' * 'schemedef-' -> 'scheme' - If the 's 'id' has one of the following “magic” prefixes (for legacy support, not recommended for use in new specs): * 'attr-' -> 'attribute', 'attr-value', or 'element-state' * 'interface-' -> 'interface' * 'dom-' -> some IDL construct - WebIDL found in the specification will be searched for a construct having the same name as the text contents of the , if not found, then use the heuristics: - if the content starts with an uppercase letter -> 'interface' - if it looks like a function (match '^[^ ]+\([^\(]*\)$') -> 'method' - otherwise -> 'attribute' - Search WebIDL found in the specification for a construct having the same name as the text, if found, use that type - Look for the nearest ancestor with a valid 'data-dfn-type' attribute, or one of the following classes: * 'propdef' -> 'property' * 'valuedef' -> 'value' * 'valdef' -> 'value' * 'vdef' -> 'value' * 'at-ruledef' -> 'at-rule' * 'descdef' -> 'descriptor' * 'typedef' -> 'type' * 'funcdef' -> 'function' * 'selectordef' -> 'selector' * 'grammardef' -> 'grammar' * 'conceptdef' -> 'concept' * 'abstract-opdef' -> 'abstract-op' * 'statedef' -> 'state' * 'modedef' -> 'mode' * 'contextdef' -> 'context' * 'facetdef' -> 'facet' * 'elementdef' -> 'element' * 'element-attrdef' -> 'element-attr' * 'element-statedef' -> 'element-state' * 'attr-valuedef' -> 'attr-value' * 'eventdef' -> 'event' * 'interfacedef' -> 'interface' * 'constructordef' -> 'constructor' * 'methoddef' -> 'method' * 'argdef' -> 'argument' * 'attrdef' -> 'attribute' * 'extendedattrdef' -> 'extended-attribute' * 'iterdef' -> 'iterator' * 'mapdef' -> 'maplike' * 'setdef' -> 'setlike' * 'serialdef' -> 'serializer' * 'stringdef' -> 'stringifier' * 'callbackdef' -> 'callback' * 'dictdef' -> 'dictionary' * 'dict-memberdef' -> 'dict-member' * 'enumdef' -> 'enum' * 'enum-valuedef' -> 'enum-value' * 'constdef' -> 'const' * 'typedefdef' -> 'typedef', * 'exceptdef' -> 'exception' * 'except-fielddef' -> 'except-field' * 'except-codedef' -> 'except-code' * 'http-headerdef' -> 'http-header' * 'schemedef' -> 'scheme' - Look at the text content of the and use the following heuristics: - If the content starts with '@' -> 'at-rule' @foo - If the content is quoted, e.g.: "foo", 'foo', “foo”, or 'foo' -> 'value' "foo" - If the content starts with '<' and ends with '>' -> 'type' <foo> - If the content starts with ':' -> 'selector' :foo - If the content looks like a function and the 'id' does not start with 'dom-' -> 'function' foo(bar) In addition there are special rules for legacy SVG specs: - For

,

, and section heading elements that are anchors, if the element contains a that is not an anchor and has a 'class' attribute - if one of the classes is one of the above definition classes plus '-title', use that definition type - if one of the classes is 'adef' -> 'element-attr' - if one of the classes is 'SVG-TermDefine' -> 'concept' - if the element is a section heading and one of the classes is 'prop-name' -> 'property' - if the element is a section heading and one of the classes is 'element-name' -> 'element', - For section headings, if the anchor name and the section name both start with 'Interface' -> 'interface' ==== Anchor Relationships ==== Shepherd also attempts to determine the relationship between anchors, e.g. which element is an attribute defined for. The logic for determining that is as follows (first match wins): - Use the value of the 's 'data-dfn-for' attribute width - If the is an IDL construct, determine the relationship from the IDL - Look for the nearest element ancestor with a 'data-dfn-for' attribute
width height