* Tobias Reif (tobiasreif / pinkjuice.com) wrote:

> Thomas Hurst wrote:
>
> >The HTML's a bit messy, with things like using tables+CSS to provide
> >coloured backgrounds and section headers when a simple <h{1,2,3}> tag
> >would do.
>
> Just send Dave your suggestions, ideas, code, or/and complete
> templates; he's very responsive and thankful for contributions.

I'll look into the templates.

> >It also uses frames, for which I'm afraid Dave is going to hell ;)
>
> AFAIK, a b/w one-document non-frame option for printing is planned.

Frames aren't just bad for printing, they also screw up forward/back,
remove the ability to effectively reference specific URI's and break
bookmarking.  Being bad for printing is also an effect of being
generally bad outside the WIMP graphical browser environment; they don't
transfer well to aural browsers, tty displays, or portable devices
either.

> >To this end, an XML output format would be good.
>
> Which one?
>
> When an existing standard is chose, processing tools exist.  Like the
> XSLTs for Docbook (docbook2html, docbook2xslfo=>PDF) etc.

Depends, a custom schema will allow for more specific
transformations, where something like DocBook that sort of metadata
(methods/classes/modules) can be lost.  Although I think DocBook's
<sect{1,2,3}> will do nicely, a specific XML output format would be nice
when it won't.

> >That can then be processed using XSL/Ruby/whatever to turn it into
> >pretty much anything else, including XHTML, DocBook, plaintext etc.
>
> I'm not sure if I would sit down and write transformations for a
> custom RDoc XML language.

Probably not, but if you suddenly find a desperate need to, for
instance, embed your documentation into a database, a schema which
defines modules, classes, methods, variables etc would be much easier to
process than DocBook.

-- 
Thomas 'Freaky' Hurst  -  freaky / aagh.net  -  http://www.aagh.net/
-
Women complain about sex more than men.  Their gripes fall into two
categories: (1) Not enough and (2) Too much.
		-- Ann Landers