Re: Definitions, references, and tooltips

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.

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.

Other opinions?

On Sat, Nov 1, 2014 at 2:08 PM, Tab Atkins Jr. <jackalmage@gmail.com> wrote:

> 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
>



-- 
Shane McCarron
Managing Director, Applied Testing and Technology, Inc.