Re: Referencing IDL members in ReSpec

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:


interface Dahut7 {
             attribute DOMString      foo<file:///Users/gregg/Projects/respec2/test-spec/webidl.html#widl-Dahut7-foo>;
    readonly attribute DOMString      bar<file:///Users/gregg/Projects/respec2/test-spec/webidl.html#widl-Dahut7-bar>;
             attribute unsigned short xxx<file:///Users/gregg/Projects/respec2/test-spec/webidl.html#widl-Dahut7-xxx>;
    readonly attribute unsigned short yyy<file:///Users/gregg/Projects/respec2/test-spec/webidl.html#widl-Dahut7-yyy>;
    [Ook, Oook]
    readonly attribute unsigned 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>