From: JamesBritt <james@...>
Date: 2002-11-11T13:32:59+09:00
Subject: Re: [ANN] www.ruby-doc.org

> Hasn't docbook been proposed for documentation in the past?  I too
> like the idea of having abstract logical document markup in XML and
> then using a suite of tools to convert it into XHTML, plain HTML,
> LaTeX, troff, PDF, etc. Indeed, docbook (or perhaps simplified
> docbook, as docbook is very rich) was designed for this very purpose.
> The sites http://www.docbook.org and
> http://www.oasis-open.org/docbook/xml/simple decribe the XML and SGML
> standards for docbook and simplified docbook.
>
> Indeed, I think James Britt himself has mentioned using docbook for
> embedded documentation.  The site www.rubydoc.org is down right now,
> otherwise I'd check to see if support for docbook is in the planning
> stages.

I like DocBook as one of many possible end or intermediate forms, i.e., if you
plan on treating the information as book material, DocBook may be a realy good
choice.  I don't recall ever endorsing DocBook for *embedded* documentation
(though it's conceivable), since hand-editing XML is a pain in the ass.

To be sure, it would be useful if RDoc could emit DocBook XML, but if the
default RDoc XML contains sufficient semantic information then converting it to
DocBook (or whatever else) should be straightforward.

However, while the data emitted by RDoc is most likely intended for use as
documentation, it shouldn't be burdened with a tag set that is perhaps not
focused on source code semantics.  The RDoc XML element set should be designed
to capture the semantic information of Ruby code, not a book.  DocBook may not
have the best model for the expression of relationships as found in dynamic, OO
code.


James


>
>