" JamesBritt" <james / jamesbritt.com> 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.

What I envisage is an integrated tool for the documentation of Ruby
libraries and code. ri as we know it now would be thrown away.
Instead, documentation would be produced by a beefed-up version of
RDoc and stored in a repository. This process would be incremental:
new documentation could be added (and existing documentation updated)
at all times. Repositories would be stored on user's local machines:
we could even have multiple repositories for multiple users where
necessary (in fact I think we'd want to support hierarchies of
repositories: when a system administrator installs Ruby, the
repository for the standard libraries gets installed. When a user then
installs their own copy of package X, then the documentation for it
could be stored locally for that user, but hyperlinked to the
system-wide repository where necessary.)

The documentation in this repository would have all the formatting
capabilities of rdoc, and would also enjoy all the automated
hyperlinking that rdoc provides. The documentation would also be
produced from the code (so it is more likely to be up to date). Matz
has already agreed to let me add the rdoc documentation for all the
built-in library into the interpreter C-source.

Once the repository is built, it can be read in many ways. A command
line tool similar to 'ri' is an obvious start. So is HTML access over
the web. But I'd also like to use this documentation to update the
PickAxe, so that when when new versions of Ruby come along, the
library documentation in the book in guaranteed to be up to date.

The idea behind ruby-doc.org is a good one. But, as I discussed with
James at RubyConf, let's try to get the most out of the energy being
put in to it. Rather than simply repackaging existing stuff, let's
try to show the world how language and library documentation should be
done.

What needs to happen?

First, RDoc needs some work.

- it doesn't currently bother to record the fully qualified names of
  methods: it didn't need to until now.

- it doesn't have a repository - it goes from source to whatever
  output format you select. However, this isn't a major problem - it
  does have that division internally, so splitting it in two shouldn't
  be too hard

- once we have a repository, it needs to be made incremental. Again,
  this shouldn't be too hard.

- Given the repository, the existing RDoc mechanisms could be adapted
  to produce HTML, XML, and RDF from it. We could also write a
  command-line query tool to replace ri.

- Once all this is in place, we have 'documentation day'. We take the
  PickAxe documentation for both the built-in methods and the standard
  library and add it to the source. Much of this can be automated, but
  it needs people to check the result.

- Finally, we include all these tools with the standard distribution,
  so that Ruby documentation is available 'out of the box'.

Web sites such as ruby-doc could then feed straight from this
repository, giving them far richer content.

I'm trying to work on this, but to be honest I'm finding it hard to
make the time. A combination of some deaths of friends and family,
along with a heavy workload, have meant that progress on RDoc has been
slow recently. If anyone thinks this vision has merit and has the time
to spend to help make it real, I'd welcome the help.



Regards


Dave