Version française
Home     About     Download     Resources     Contact us    

This site is updated infrequently. For up-to-date information, please visit the new OCaml website at

Browse thread
Re: [Caml-list] Documentation tools
[ Home ] [ Index: by date | by threads ]
[ Search: ]

[ Message by date: previous | next ] [ Message in thread: previous | next ] [ Thread: previous | next ]
Date: -- (:)
From: kiniry@c...
Subject: [Caml-list] Re: Documentation tools
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.

Joe Kiniry
Joseph R. Kiniry          
California Institute of Technology        ID 78860581      ICQ 4344804


To unsubscribe, mail  Archives: