Spec Index

Hey, SVG WG-

I've had some thoughts about autogenerating an index.  Basically, since
most of our important terms, such as definitions, element and attributes
names, methods and interfaces, etc., have ids, and we make reference to
those ids through the spec, we can use the ids as keys, and the  links
to those ids as additional references.  For example, given this fragment:

 <h4 id="classAttr">The <span class="attr-name">'class'</span>
attribute</h4>
 <p>
   The <a href="#classAttr"><span class="attr-name">'class'</span></a>
   attribute assigns one or more class names to an element. The
   element may be said to belong to these <a href="#classAttr"><span
   class="attr-name">classes</span></a>. A class name
   may be shared by several element instances. The class attribute
   has several roles:
 </p>

We have one key, "class (attribute)", and 2 references to it.  We know
it's a attribute because of the class (getting all recursive here, stay
with me) "attr-name".  We could use XSLT to assign an id to the
referencing instances (assuming they don't already have ids), like this:

 <a id="classAttr-ref-1" href="#classAttr"><span
class="attr-name">'class'</span></a>
 <a id="classAttr-ref-2" href="#classAttr"><span
class="attr-name">classes</span></a>

Which would then allow us to generate the following index entry:

 <dl>
   <dt>
     <a href="struct.html#classAttr"><span
class="attr-name">'class'</span></a>
     (attribute):
   </dt>
   <dd>
     <p>
       <a href="struct.html">Document Structure</a>:
       <a href="struct.html#classAttr-ref-1">1</a>,
       <a href="struct.html#classAttr-ref-2">2</a>,
       ...
     </p>
     ...
     <p>
       <a href="metadata.html">Metadata</a>:
       <a href="metadata.html#classAttr-ref-7">7</a>,
       ...
     </p>
   </dd>
 </dl>

Obviously, this would not be as good as a hand-generated index, but it
would be a lot faster, and we could supplement it with a list of
hand-made entries.  Also, if we keep up our current good practice of
applying ids and classes, and linking where appropriate, the quality of
the index will improve.

Here are a couple of resources that might be helpful.  Neither of them
does exactly what we need, but they should help with specific subtasks
(like grouping the results):

 "Using XSLT for getting back-of-the-book indexes" by Jirka Kosek [1]
 "Grouping Using the Muenchian Method" by Jeni Tennison [2]

I would be surprised if someone hadn't already done this (maybe even
within the W3C Team, I'll ask), so before we write it ourselves, we
should poke around for something we could reuse.

[1] http://www.idealliance.org/proceedings/xml04/papers/77/xslindex.html
[2] http://www.jenitennison.com/xslt/grouping/muenchian.html

Regards-
-Doug Schepers
W3C Team Contact, WebApps, SVG, and CDF

Received on Saturday, 13 September 2008 21:13:58 UTC