Thought you guys might be interested - they're talking about documentation tools on the Caml mailing list: -----Original Message----- From: Xavier Leroy [mailto:Xavier.Leroy@inria.fr] Sent: Monday, May 14, 2001 9:12 AM To: caml-list@pauillac.inria.fr Subject: [Caml-list] Documentation tools 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