Re: Referencing IDL members in ReSpec

Oh - I agree... <adef> is a simple addition we made for our specs, where 
an 'attribute' is not an IDL attribute, it is an attribute of an 
element.  You would need something more robust for WebIDL.

On 10/20/2010 12:24 PM, Gregg Kellogg wrote:
> I'm inclined to go with the qualified namespace-based definitions, 
> rather than invent special elements. In any case, simply adding an 
> <adef> isn't enough, as the same attribute name could be used in 
> different contexts. Also, ReSpec should be better at ensuring that 
> generated IDs are unique within the document. Note that this might 
> include the addition of WebIDL modules, for which I've added support 
> in ReSpec2.
>
> So, given the following WebIDL:
>
> interfaceDahut7  {
>               attributeDOMString       foo  <file:///Users/gregg/Projects/respec2/test-spec/webidl.html#widl-Dahut7-foo>;
>      readonly attributeDOMString       bar  <file:///Users/gregg/Projects/respec2/test-spec/webidl.html#widl-Dahut7-bar>;
>               attributeunsigned short  xxx  <file:///Users/gregg/Projects/respec2/test-spec/webidl.html#widl-Dahut7-xxx>;
>      readonly attributeunsigned short  yyy  <file:///Users/gregg/Projects/respec2/test-spec/webidl.html#widl-Dahut7-yyy>;
>      [Ook,Oook]
>      readonly attributeunsigned short  ook  <file:///Users/gregg/Projects/respec2/test-spec/webidl.html#widl-Dahut7-ook>;
> };
> Attribute "foo" might be known as "idl-def-Dahut7.foo" and could be 
> referenced as <a href="idl-def-Dahut7.foo"">foo</a>. You should also 
> have a chance of dereferencing <a>Dahut7.foo</a>. This would be fairly 
> easy to implement in v2.
>
> Note that in v2, a reference such as <a href="#foo"></a> can result in 
> the content being filled out with the title of the defining element 
> for section and figure references. For WebIDL references, it could 
> also fill out the defined name.
>
> Also, note that there's a bug in ReSpec (not v2), which would generate 
> the same identifier for Dahut6 and Dahut7, leaving off the digit that 
> makes them distinct).
>
> Gregg
>
> On Oct 20, 2010, at 6:03 AM, Shane McCarron wrote:
>
>>  What we have done in RDFa and other specs is to have a local
>> customization of ReSpec that does local expansions of special elements.
>> I KNOW that you don't like the idea of special elements, Robin.  But...
>> well, I do.  So, for example, in our case I would have an element like
>> <adef>blah</adef> when defining a new attribute name and then have code
>> like the following:
>>
>>       var preProc = {
>>           apply:  function(c) {
>>                     // process the document before anything else is done
>>                     var refs = document.querySelectorAll('adef') ;
>>                     for (var i = 0; i<  refs.length; i++) {
>>                         var item = refs[i];
>>                         var p = item.parentNode ;
>>                         var con = item.innerHTML ;
>>                         var sp = document.createElement( 'dfn' ) ;
>>                         var tit = item.getAttribute('title') ;
>>                         if (!tit) {
>>                             tit = con;
>>                         }
>>                         sp.className = 'adef' ;
>>                         sp.title=tit ;
>>                         sp.innerHTML = con ;
>>                         p.replaceChild(sp, item) ;
>>                     }
>>           };
>>
>> Then in the respecConfig I have
>>
>>          preProcess: [ preProc ]
>>
>>
>> This works well, and we don't need to do any customizations to ReSpec.js
>> for our local weirdness.  We actually have a bunch of new 'elements'
>> that we use to make our markup more efficient and consistent... adef,
>> aref (for attributes), tdef, tref (for 'terms'), dtref (for datatypes
>> defined in other specifications), and ldtref (for datatypes defined
>> locally).  Hope this helps!
>>
>> On 10/20/2010 6:36 AM, Robin Berjon wrote:
>>> On Oct 19, 2010, at 01:25 , Cameron McCormack wrote:
>>>> What’s the proper way to reference IDL members from prose?  Say I have
>>>>
>>>> <dl title='interface A' class=idl>
>>>> <dt>attribute DOMString blah</dt>
>>>> <dd>Oh yeah</dd>
>>>> </dl>
>>>>
>>>> and I want to say “The blah attribute is used for all kinds of things”,
>>>> how should I mark up “blah” so that it links to the definition?
>>> Currently you use<a 
>>> href='#whatever-id-got-generated-for-blah">blah</a>. I'd be very 
>>> happy with any improvement over this. Maybe<a data-idl='A.blah'></a> 
>>>  (generates the content unless specified). Better regularity in the 
>>> way that IDs are generated for WebIDL (i.e. taking into account 
>>> interface and modules) would also be desirable, right now it's 
>>> simplistic and does lead to the occasional clash.
>>>
>>
>> -- 
>> Shane P. McCarron                          Phone: +1 763 786-8160 x120
>> Managing Director                            Fax: +1 763 786-8180
>> ApTest Minnesota                            Inet: shane@aptest.com 
>> <mailto:shane@aptest.com>
>>
>>
>>
>

-- 
Shane P. McCarron                          Phone: +1 763 786-8160 x120
Managing Director                            Fax: +1 763 786-8180
ApTest Minnesota                            Inet: shane@aptest.com