[Caml-list] Re: Documentation tools

[kiniry@cs.caltech.edu (Joseph R. Kiniry)]

I've used dozens of source processing, documentation, and literate
programming tools over the years.

I think that a simple, but extensible, javadoc-like document processor
is the right way to go.  The inclusion of a standard set of document
tags with *well-defined* semantics is a must.  

My research group and companies use an extensive code standard(1) with
complementary tools for documentation(2) and test code generation(3)
for exactly this purpose and we and our customers been very happy with
this solution.  My only regret is that we are generating renderable
formats (e.g. HTML) directly rather than indirectly.  This leads me to
the following suggestion.

I *strongly* suggest the powers that be look into the Linux
Documentation Project(4) tools, namely sgml-tools and related(5).
>From a single, very simple SGML source the following formats can all
be generated: HTML, info, LaTeX, LyX, RTF, txt, man pages.

I've been very happy with both the use of these tools as well as their
output for the past couple of years.

Best,
Joe Kiniry
-- 
Joseph R. Kiniry                    http://www.cs.caltech.edu/~kiniry/
California Institute of Technology        ID 78860581      ICQ 4344804

(1) http://www.infospheres.caltech.edu/resources/code_standards/java_standard.html
(2) http://www.cs.caltech.edu/~kiniry/papers/JPP/JPP.brief
(3) http://semantik.informatik.uni-oldenburg.de/~jass/
    http://www.cs.iastate.edu/~leavens/JML.html
(4) http://www.linuxdoc.org/
(5) http://www.linuxdoc.org/LDP/LDP-Author-Guide/

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