extracting an index of faqs from the commentary

[Claus Reinke]

> so i don't think that adding to the main text alone would help
> people like me, who would need an index or a how-to faq. 
> but trying to keep an entirely separate index or faq in sync 
> with the main text seems hopeless as well. 
> 
> in light of this, my suggestion for improvement would be
> to embedd individual faq answers directly into the main
> text, with a special tag, and to have a separate faq page,
> which would do nothing but gather those tags from the
> main text in a single collection (preferably automatically).

something like this shouldn't be too hard, in principle, but
as always, there are hurdles, in practice:-) my first thought,
since the wiki seems to be xhtml, was to use xslt (after all,
it seems a straightforward task of extracting some elements 
marked FAQ from a collection of xml documents).

unfortunately, the commentary pages aren't quite valid xhtml,
the main offender being unescaped & and the like (should be 
& - even in hrefs?? at least, the error messages complain
about incomplete EntityRefs there, or missing ';'), especially, 
but not only, in the sidebars (which i can't edit on the wiki?).

there might be objections against the xslt approach in
general (wiki will never stay valid; not all browsers support
xslt fully, so instead of just putting an xml-page with an
xslt-stylesheet online, one would need to run something 
like xsltproc, to regenerate the index whenever one of 
the commentary pages was updated; perhaps one might
want to use something like haskell tagsoup instead).

but anyway, i thought i'd use the Renamer page (edited
to escape &s and to add one FAQ, which is just a div
with a class and an anchor for reference) to demonstrate 
the idea: if you put the attached files in a single directory,
and either open faq.xml in ie, or run xsltproc over faq.xml,
you'll get, courtesy of Index.xslt, a simple html page listing 
h1/h2-headers, with the single faq entry mixed in, all with 
links back to the edited Renamer page. 

so the faq entries would remain in the main text, where
they could provide a focus, and stay in sync, while the
faq, providing a how-to reference index, would be 
extracted from the main text by script. similar methods
could perhaps be applied to the user guide?

do you think this would be worthwhile to have? and how
would one keep the wiki xml valid (can the trac wiki
validate on edit?), or should one use tagsoup instead?
is it even possible to trigger an extraction script on edit?

claus

it's been a long time since i did silly things like using 
xslt to read rss feeds, so expect some errors in the 
xslt/xml!-)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/cvs-ghc/attachments/20070911/792fd219/Renamer-0001.html
-------------- next part --------------
A non-text attachment was scrubbed...
Name: faq.xml
Type: text/xml
Size: 3905 bytes
Desc: not available
Url : http://www.haskell.org/pipermail/cvs-ghc/attachments/20070911/792fd219/faq-0001.xml
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Index.xslt
Type: application/octet-stream
Size: 1664 bytes
Desc: not available
Url : http://www.haskell.org/pipermail/cvs-ghc/attachments/20070911/792fd219/Index-0001.obj