Re: Definitions, references, and tooltips

On Tuesday, November 11, 2014, Tab Atkins Jr. <jackalmage@gmail.com> wrote:

> On Tue, Nov 11, 2014 at 10:13 AM, Shane McCarron <shane@aptest.com
> <javascript:;>> 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'.".
>

Oh - I thought there was some additional tranform that happened for
Shepherd.  Thanks


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

Understood.  But using @title in this way in the OUTPUT form means that the
resulting tooltip and potentially things like ARIA names could end up as
something like 'foo|bar|bat', right?  That feels bad to me.



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

I think it is phrases like "gives another definition that namespaces the
current definition" that throws me.  Let me try to say it back.  If I have
a definition 'foo' somewhere that is of type 'interface', I can say that
the definition of 'bar' is of type 'method' and that it is a method "FOR"
'foo'.  What is unclear is how I say that it is "for" the 'foo' that is of
type 'interface', as opposed to the 'foo' that is of type 'attribute' or
something.  And yes, I get that it is possible to put the 'for' at a higher
level so that all of the declared definitions within that level get
automatically bound.

How does this effect the generated IDs?  The pattern I was trying to use
was something like 'dfn-TYPE-TERM'.  So in the example above I would have
'dfn-interface-foo' and 'dfn-method-bar'.  If the bar in question is
actually "FOR" interface foo, then the generated ID should be something
like 'dfn-interface-foo-method-bar'?

Can this nest any further?  Can I have an interface that has methods that
are FOR it, and then those methods have parameters that are FOR them?
E.g., dfn-interface-foo-method-bar-parameter-bat ?



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



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