From: Dave Thomas <Dave@...>
Date: 2002-01-28T08:17:21+09:00
Subject: Re: OT: tools for creating documentation

ptkwt@shell1.aracnet.com (Phil Tomson) writes:

> Also - in regard to the Pickaxe book (so this question is primarily 
> addressed to Dave and Andy):  What was the original format that you 
> created the book in and what did you use to create HTML from that format?

The book is written in LaTeX using our own style sheets. We weren't
originally planning on releasing it under an OpenContent license: that
would probably have changed our decision.

We convert it to HTML using a fairly convoluted path. We originally
tried LaTeX2html, but it didn't handle some of the constructs we used,
and changing it to turned in to a wasted week. In the end, I wrote
Ruby script that did the conversion from LaTeX to XML. We then have a
combination of Ruby and XSLT that converts this into HTML.

> I haven't tried RDoc yet, but I plan to real soon.  Does RDoc
> recognize the same kinds of tags that rdtool does (or does RDoc
> recognize RD - Ruby documentation format)?

No :)

rd uses explicit markup, while RDoc tries to use as much implicit
knowledge as possible. For example, the rd documentation for the
constructor in xmltree.rb is

    =begin
    === Class Methods

        --- Node.new(*children)

    make a Node.
    children is a Array of child, or sequence of child.
    child is a String or Node.

    =end
          ## new([child1, child2, ...]) or
          ## new(child1, child2, ...)
          ##     child?: String or Node
          def initialize(*children)
            @value = nil
            @parent = nil
            @children = nil
            self.childNodes = children
          end

In RDoc, you'd probably write something like:

          # Make a Node. children is a Array of child, or sequence of
          # child.  Child is a String or Node.

          def initialize(*children)
            @value = nil
            @parent = nil
            @children = nil
            self.childNodes = children
          end

RDoc knows that it's a class method, and also extracts the signature
for you automatically. In fact, RDoc will also recognize that 'Node'
in the comment refers to a class that you've written and automatically
generate a hyperlink to its description.

The intention behind RDoc is to be as transparent as possible. A
casual reader should be able to look at a source file and not realize
that it has embedded documentation.


Regards


Dave