[erlang-questions] Erlang documentation cleanup (PREV: R13B01 modules, quick reference)

[Richard O'Keefe]

I'd just like to say that comparing the Erlang on-line
documentation with typical JavaDoc -- including stuff
from Sun -- makes me pathetically grateful for Erlang.

I keep on pointing people at the R documentation for
a great example.  One thing which R shares with Pop-11
is *examples* which you can actually run.  This is
conspiciously lacking in JavaDoc, but could be supported
by Erlang.  In R, where > is the prompt

	> ?lm

brings up a "man page" for the lm function (fits linear models).
There's some example code at the bottom showing what it's like
to use it.

	> example(lm)

runs that example code in the REPL.  There is a standard
tool-supported R process for building a package for
distribution.  One step in that is automatically checking
that the examples work.

By the way, using information retrieval engines (locally)
is a FINE way to navigate manuals.  A few years ago our
3rd-year software engineering students were given as their
project to write FTFM "Find The F* Manual", doing just this
with the Linux man pages.  Once they had done it. they found
it very useful.

We have our own research IR engine (it changes all the time,
and students frequently break it, so don't ask).  I've heard
people speak well of ht://Dig (http://htdig.sourceforge.net/).
It hasn't been updated for a while, but there are other free
engines out there, like Zettair.

The Erlang man pages are about 5 MB of lightly marked up text.
The HTML pages are about 31 MB.  They include more documents
and are more verbosely marked up.  By the standards of IR,
these document collections are *tiny*.