Re: Definitions, references, and tooltips

On Tue, Nov 11, 2014 at 10:13 AM, Shane McCarron <shane@aptest.com> wrote:
> Yes - I am aware of what Bikeshed uses as its source form.  In the case of
> ReSpec, I am more inclined to use the Bikeshed "output" form of the
> attributes as the source form.  I could be persuaded to change my mind.

No, you misunderstand.  Bikeshed uses "title" in both its input and
output forms.  That's why I corrected you with "Bikeshed just uses
'title'.".

> Here is what I have implemented so far:
>
> title works as it always did in ReSpec for backward compatibility.  If there
> is a title attribute, it defines the linking text that can be used to
> reference the definition.  In the output data-title is supplied as well.
> data-title works as it does in Bikeshed.  You can define aliases.  Using any
> of these will result in a reference to the defintiion.  It is retained in
> the output.

As noted, there's no such thing as "data-title".

> data-local-title works as it does in Bikeshed.  It is NOT retained in the
> output.

Sounds good.

> export and noexport work as in Bikeshed.  In the output these are captured
> as data-export and data-noexport.
> data-dfn-type can be used to specify the scope of a definition (it's type).
> I did not do anything with data-dfn-for.  Frankly I am confused about when
> you would use which of these.

Hmm, can you tell me what's unclear in the docs about this?  "type"
gives the definition's type - is it a property def, an interface def,
etc.  "for" gives another definition that namespaces the current
definition - there can be a lot of methods named "foo()", so you use
"for" to specify that this is the foo() method of the Bar interface,
like <dfn method for=Bar>foo()</dfn>.

That way autolinks can specify which foo() they want, like
{{Bar/foo()}} in the Bikeshed shorthand syntax (or <a method
for=Bar>foo()</a> in the longhand, or <a data-link-type=method
data-link-for=Bar>foo()</a> in the output syntax, which is also
accepted in the input format), and get pointed to the correct
definition.

> During processing ReSpec builds up a collection of defined terms.  It also
> keeps track of what should be 'exported'.  At some point I plan on allowing
> ReSpec to connect to an end point to push the exported terms.  For now it is
> sitting there, waiting.
>
> The upshot of this is that, once I check it in and get it reviewed, ReSpec
> users will be able to use aliases for definitions within the current
> document.  And, once I completely understand what Shepherd expects, it
> should be able to scrape the static versions of ReSpec documents and
> incorporate the exported references into that database.

Cool. I'll be writing the documentation today; I've been on vacation
for several days. ^_^

~TJ

Received on Tuesday, 11 November 2014 19:03:06 UTC