Home Specs Ideas Testing About
You are here: CSS Working Group Wiki » Specification Issues and Planning » <dfn> Patterns for Proper Cross-Linking

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
spec:dfn-patterns [2013/07/30 11:46] – [<dfn> Types] markup tweak tabatkinsspec:dfn-patterns [2014/12/09 15:48] (current) – external edit 127.0.0.1
Line 10: Line 10:
  
 Some types of definitions are part of some higher construct.  This should be indicated with a ''data-dfn-for'' attribute on the definition or a container. Some types of definitions are part of some higher construct.  This should be indicated with a ''data-dfn-for'' attribute on the definition or a container.
 +
 +"dfn" type definitions (ones that don't fit into any other category) aren't exported for cross-referencing by default.  If you intend them to be linkable by other specs, indicate it with a ''data-export'' attribute.
  
 Getting this metadata right is easy and helps with auto-crossreferencing (in Tab's preprocessor) and automatically generated documentation (in Shepherd), so please get it right. Getting this metadata right is easy and helps with auto-crossreferencing (in Tab's preprocessor) and automatically generated documentation (in Shepherd), so please get it right.
Line 24: Line 26:
   * function (like counter() or linear-gradient())   * function (like counter() or linear-gradient())
   * selector   * selector
 +  * token
  
 There are additional categories for WebIDL definitions: There are additional categories for WebIDL definitions:
Line 31: Line 34:
   * attribute   * attribute
   * dictionary   * dictionary
 +  * dictmember
   * enum   * enum
   * const   * const
Line 54: Line 58:
   * Does it start with an @? Then it's an **at-rule**.   * Does it start with an @? Then it's an **at-rule**.
   * Is it surrounded by <>? Then it's a **type**.   * Is it surrounded by <>? Then it's a **type**.
 +  * Is it surrounded by 〈〉? Then it's a **token**.
   * Does it start with a :? Then it's a **selector**. (This is a simplistic auto-detection for pseudo-classes and pseudo-elements.)   * Does it start with a :? Then it's a **selector**. (This is a simplistic auto-detection for pseudo-classes and pseudo-elements.)
   * Does it end with ()? Then it's a **function**.   * Does it end with ()? Then it's a **function**.
Line 72: Line 77:
 |funcdef | function| |funcdef | function|
 |selectordef | selector| |selectordef | selector|
 +|tokendef | token|
 |interfacedef | interface| |interfacedef | interface|
 |methoddef | method| |methoddef | method|
 |attrdef | attribute| |attrdef | attribute|
 |dictdef | dictionary| |dictdef | dictionary|
 +|dictmemberdef | dictmember|
 |enumdef | enum| |enumdef | enum|
 |constdef | const| |constdef | const|
Line 95: Line 102:
 |funcdef- | function| |funcdef- | function|
 |selectordef- | selector| |selectordef- | selector|
 +|tokendef- | token|
 |interfacedef- | interface| |interfacedef- | interface|
 |methoddef- | method| |methoddef- | method|
 |attrdef- | attribute| |attrdef- | attribute|
 |dictdef- | dictionary| |dictdef- | dictionary|
 +|dictmemberdef- | dictmember|
 |enumdef- | enum| |enumdef- | enum|
 |constdef- | const| |constdef- | const|
Line 149: Line 158:
  
 If using Tab's preprocessor, you may instead use a simple ''for'' attribute on the ''<dfn>'', or a ''dfn-for'' attribute on a container.  As well, Tab's preprocessor automatically enforces the use of "for" indicators, flagging an error if they're missing.  (TODO: Rather, it will soon. Haven't coded it up quite yet.) If using Tab's preprocessor, you may instead use a simple ''for'' attribute on the ''<dfn>'', or a ''dfn-for'' attribute on a container.  As well, Tab's preprocessor automatically enforces the use of "for" indicators, flagging an error if they're missing.  (TODO: Rather, it will soon. Haven't coded it up quite yet.)
 +
 +===== Exporting Definitions =====
 +
 +Definitions have a concept of being "exported" from a spec, which makes them available for automatic cross-referencing.  Most types of definitions are //automatically// exported, with no additional effort from you.  The only exception is "dfn" type definitions - to make these available for cross-referencing, you must add a ''data-export'' attribute to them or an ancestor.
 +
 +For example, the Flexbox spec contains a definition like ''<dfn>flex item</dfn>''.  This isn't auto-detected as any of the other types, so it (correctly) gets the type "dfn".  As it stands, though, this definition can't be auto-linked from any other spec.  To make that happen, it needs to be written as ''<dfn data-export>flex item</dfn>'' (or in Tab's preprocessor, ''<dfn export>flex item</dfn>'').
 +
 +Conversely, if you want to *block* a particular definition from being exported (because it's only meaningful locally), add a ''data-noexport'' attribute to the definition or an ancestor.
 +
 +If using Tab's preprocessor, you may instead just use an ''export'' or ''noexport'' attribute.
 
spec/dfn-patterns.1375209993.txt.gz · Last modified: 2014/12/09 15:48 (external edit)
Recent changes RSS feed Valid XHTML 1.0 Valid CSS Driven by DokuWiki