Re: Definitions, references, and tooltips

On Sat, Nov 1, 2014 at 9:48 AM, Shane McCarron <shane@aptest.com> wrote:
> Question for the crowd:  ReSpec today allows you to define terms.  When you
> do, you can set a 'title' on the term as a way of telling the system what
> the real referencable term should be (e.g., <dfn
> title="screenshot">Screenshots</dfn> would define the term Screenshots, but
> you would reference it as screenshot).  In bikeshed you can also define
> aliases (e.g., <dfn title="screenshot|screenshots|something
> else">Screenshots</dfn> would define the term Screenshots, but you would
> reference it as screenshot, or screenshots, or 'something else').
>
> Today if there is a 'title' attribute, then ReSpec leaves that on the dfn
> element, which in turn means it shows up as a tooltip when you are mousing
> around the generated document.
>
> Does anyone think this is a useful feature?  Or it just an accident?  I was
> thinking of removing the title attribute during generation - especially as
> we introduce the bikeshed syntax.

You need to maintain the linking text in the generated document; it's
used by scrapers like Shepherd to build the cross-spec linking
database.  For ReSpec, the document looked at by scrapers is the
source doc, so feel free to remove from the post-JS document.

That said, I plan to have Bikeshed move away from using title as a
linking text source
<https://github.com/tabatkins/bikeshed/issues/230>, and use a `data-x`
attribute instead.  Using title in this way is an abuse, and makes it
impossible to provide useful tooltips.  (For example, Bikeshed
autolinks the CSS grammar combinators. I want the tooltip to summarize
their meaning, so you don't have to follow the link and read the
grammar specification most of the time.)

(Note as well that Bikeshed has significant support for English
conjugation in "dfn" type definitions, so you don't have to supply
plurals/possessives/etc as alternates unless it's an irregular form.)

~TJ

Received on Saturday, 1 November 2014 19:08:58 UTC