From: adamon@... (Damon) Date: 2002-11-11T12:05:14+09:00 Subject: Re: [ANN] www.ruby-doc.org Dave Thomas wrote in message news:... > " JamesBritt" writes: > > > There's more work to be done on the site, but comments are invited. > > I want to add more data to the site's ri so that things currently > > missing from ri (and the pickaxe) are retrievable via the munged > > version online. Right now, for example, you can get Matrix info > > online, something not available from the standard ri, though the > > code was sparsely commented. Likewise, WeakRef, Pstore, and a few > > others are in there via rimport. > > For what it's worth, I applaud the effort, but disagree with this > approach. > > A little history. > > When we wrote PickAxe, we used LaTeX, as it gave us the typographic > control we needed. We tried fairly hard to use logical (as opposed to > physical) markup. This was fortunate, as it meant that is was fairly > straightforward to convert the book from LaTeX to XML (and then on to > HTML) when we put the book online (the diagrams remain troublesome, as > they're in PSTricks). > > Once it was in XML, it became easier to play with it. In particular, I > was playing with it one day and realized it would be simple to produce > a command line reference from the builtin library section of the > book--all I had to do was interpret the logical markup and strip out > the physical markup and cross references. This became ri. > > 'ri' represents the lowest common denominator of documentation: it has > almost no semantic information in it. 'ri' was always intended to be > a stop-gap. The final goal was always more ambitious. > 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.