Re: Definitions, references, and tooltips

On Sat, Nov 1, 2014 at 12:16 PM, Shane McCarron <shane@aptest.com> wrote:
> obviously we want shepherd to be able to scrape the respec source documents,
> so we want the syntax to be as similar as possible.  There are some things
> we just cannot do, like <<foo>> being detected as whatever type that is -
> because the browser would eat that before we got to it.

Sorry, you misunderstand.  All of the shorthand syntaxes - <<foo>> for
grammar nonterminals, {{Foo}} for IDL terms, etc - are transformed
into plain HTML before Shepherd sees them, because Shepherd only
scrapes the output documents, not the input.

I'm discussing this with you separately in
<https://github.com/tabatkins/bikeshed/issues/257>, so I'll leave
further discussion in this vein to that issue, where I've already gone
into more detail.

> I don't mind also supporting data-title or whatever.  Not sure we can ever
> remove support for title though (in the source document) because of backward
> compatibility.

Note that the local-title attribute (which is translated into
data-local-title in the output document) does something special: it
provides linking text that is only valid within that spec, and is not
exported to the global autolinking database.  This is useful when, for
example, you want to use a short, easy term to refer to something, but
it's too generic to reasonably use cross-spec.  You can provide a
normal linking text that has enough context in its name to be clear
and avoid collisions, while providing a "local" linking text that is
short and easy to type, and understandable because it has the context
of the surrounding spec to provide meaning.

~TJ

Received on Saturday, 1 November 2014 19:50:28 UTC