Re: Spec Index

Hi, SVG-

Mike(tm) Smith pointed me at the DocBook XSL Stylesheets, which we might
be able to draw from:

https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/xsl/html/autoidx.xsl

[[
See the autoidx*.xsl files. The stylesheets provide three
different options for generating an index: A "basic" one based on
Jeni Tennison's stuff, one that Jirka wrote, and one that was
contributed by Eliot Kimber.

Jirka and Eliot's methods are designed mostly for enabling
generation of indexes for non-English languages. So the "basic"
method in the autoidx.xsl file may be all you want to take time to
look at.
]]

-Doug

Doug Schepers wrote (on 9/13/08 5:13 PM):
> 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 Tuesday, 16 September 2008 12:45:40 UTC