Re: Referencing IDL members in ReSpec

  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

Received on Wednesday, 20 October 2010 13:04:49 UTC