| Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision |
| spec:dfn-patterns [2013/07/30 11:45] – [Manually Specifying the Definition Type] tabatkins | spec:dfn-patterns [2013/07/30 15:20] – [Exporting Definitions] tabatkins |
|---|
| |
| 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. |
| In many cases, the definition type can be automatically inferred. In others, you may have to manually mark up the type using any of several methods, whichever is most convenient. | In many cases, the definition type can be automatically inferred. In others, you may have to manually mark up the type using any of several methods, whichever is most convenient. |
| |
| The following methods are listed in order of convenience to use, but in *reverse* order of power. That is, the very last method (manually specifying the type) wins out over everything else, and the very first method (inferring type from contents) will only be used if all the others fail. | The following methods are listed in order of convenience to use, but in **reverse** order of power. That is, the very last method (manually specifying the type) wins out over everything else, and the very first method (inferring type from contents) will only be used if all the others fail. |
| |
| ==== Inferring <dfn> Type From Contents ==== | ==== Inferring <dfn> Type From Contents ==== |
| |
| 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. |
