[Caml-list] Documentation tools

[Xavier Leroy <xleroy@pauillac.inria.fr>]

I'm catching up with this interesting discussion between two meetings.
I fully agree with the need for a "standard" documentation tool for
OCaml interfaces, and the Caml team at INRIA is about to start working
on such a tool.  My initial plan was to do something in the style of
"javadoc", that is:

- Put documentation in .mli files, inside special comments
  e.g. (** This is part of the documentation *)
       (* but this is a regular comment *)

- Documentation is written in a subset of HTML plus special tags to
  do cross-referencing ("see also ...") and other stuff.

- The primary output format is HTML with a lot of cross-references
  and automatically-generated indices and tables of contents.

Many good points have been raised in this discussion, and actually
there are plenty other documentation systems that we should look at
before starting.  

Concerning LaTeX, I agree that a LaTeX output (possibly with PDFLaTeX
hyperlinks and folding tables of contents) would also be very nice,
e.g. for the OCaml manual itself.  However, I think HTML output is
even more important, and while Hevea does wonders at LaTeX->HTML
conversion, I believe HTML->LaTeX conversion is much easier *for the
subset of HTML that we need in documentation strings*.  We certainly
do not need full HTML 4.0 to document one function!  All we need is
font changes (e.g. <code>...</code>), line and paragraph breaking,
basic enumerations, hyperlinks, and perhaps tables.

Man pages and Info documents are also useful in some situations,
although in the long run I believe they will disappear and be replaced
by HTML or XML documentation.  Still, if the tool could output these
formats without too much efforts, that would be nice.

Some of you mentioned the interface documentation tool we use for the
Caml manuals.  It's really awful: the input format lacks both
expressiveness and flexibility, the tool itself is very basic
(used to be a 50-line Perl script until one of us took mercy and
rewrote it in Caml), and the output is truly ugly LaTeX.  It needs to
be replaced urgently by something better!

Now, I understand there are other documentation needs.  One is
literate programming (for those who are into that kind of things), but
there are already some pretty good tools for this, e.g. ocamlweb or
Norman Ramsey's noweb.  Another is writing full user's manuals
(and not just library documentation), but there I think LaTeX does a
decent job, and I'm not convinced by the Info format nor the
SGML-based tools used in the Linuxdoc project.

Suggestions and pointers to existing documentation systems are most
welcome.

- Xavier Leroy
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr