W3C home > Mailing lists > Public > spec-prod@w3.org > October to December 2014

Re: Definitions, references, and tooltips

From: Shane McCarron <shane@aptest.com>
Date: Tue, 11 Nov 2014 13:32:47 -0600
Message-ID: <CAOk_reEXXxNyY46787GLwk3cmA50tH-0nJbBgnarfjpq9JFwNw@mail.gmail.com>
To: "Tab Atkins Jr." <jackalmage@gmail.com>
Cc: Tobie Langel <tobie.langel@gmail.com>, "spec-prod@w3.org Prod" <spec-prod@w3.org>
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.
Received on Tuesday, 11 November 2014 19:33:15 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 19:55:20 UTC