Re: Definitions, references, and tooltips

On Tue, Nov 11, 2014 at 11:32 AM, Shane McCarron <shane@aptest.com> wrote:
> On Tuesday, November 11, 2014, Tab Atkins Jr. <jackalmage@gmail.com> wrote:
>> 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.

Yes, it is bad, which is why I'm moving over to a different attribute
for linking text <https://github.com/tabatkins/bikeshed/issues/230>.
The use of "title" is a legacy thing from Bert's preprocessor; it's
sometimes good to have the tooltip display the linking text, when
you're providing something more explicit; it just gets bad when you
start using the microsyntax for multiple linking texts.

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

Ah, so far there hasn't been any need to clarify the type of the "for"
reference.  Every dfn type either has a unique "for" type, or the
chance of a clash is small enough to be insignificant.  (An example of
the latter is the "value" type (for CSS values), which can be for a
"property" or a "type".  However, properties and types have completely
different syntaxes, so there's no chance of a clash.)

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

For the definition types that *require* a "for" value
<https://github.com/tabatkins/bikeshed/blob/master/bikeshed/config.py#L72>,
the auto-generated IDs do indeed include the for value in the ID, to
make clashes within a document less common.  For compat with a common
IDL id scheme, IDL things use a slightly different pattern as well.
All of the auto-generated ID code is at
<https://github.com/tabatkins/bikeshed/blob/master/bikeshed/__init__.py#L871>.
ID generation isn't actually important, though, unless you're
converting between spec preprocessors and want the IDs to be stable
without manually specifying them.

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

for values can indeed nest, and it does indeed show up in the auto-generated ID.

(I don't yet produce the transitive closure of for values, which is
something I need to fix eventually.  That way you'll be able to, say,
define that "foo" is a value dfn for "<bar>", and "<bar>" is a value
for the property 'baz', then ref "foo" as "baz/foo".)

~TJ

Received on Tuesday, 11 November 2014 23:34:14 UTC