From mboxrd@z Thu Jan 1 00:00:00 1970 Received: (from majordomo@localhost) by pauillac.inria.fr (8.7.6/8.7.3) id AAA23987; Thu, 17 May 2001 00:13:09 +0200 (MET DST) Received: from nez-perce.inria.fr (nez-perce.inria.fr [192.93.2.78]) by pauillac.inria.fr (8.7.6/8.7.3) with ESMTP id AAA23976 for ; Thu, 17 May 2001 00:13:08 +0200 (MET DST) Received: from obento.cs.caltech.edu (obento.cs.caltech.edu [131.215.44.101]) by nez-perce.inria.fr (8.11.1/8.10.0) with ESMTP id f4GMD6b13169 for ; Thu, 17 May 2001 00:13:07 +0200 (MET DST) Received: from sphere.cs.caltech.edu (sphere.cs.caltech.edu [131.215.44.92]) by obento.cs.caltech.edu (Postfix) with ESMTP id 0A21E4051; Wed, 16 May 2001 15:13:05 -0700 (PDT) Received: (from kiniry@localhost) by sphere.cs.caltech.edu (8.10.2+Sun/8.10.2) id f4GMD5d03086; Wed, 16 May 2001 15:13:05 -0700 (PDT) X-Authentication-Warning: sphere.cs.caltech.edu: kiniry set sender to kiniry@cs.caltech.edu using -f To: caml-list@pauillac.inria.fr Subject: [Caml-list] Re: Documentation tools References: <200105150424.GAA0000023003@beaune.inria.fr> <20010515114226.A10458@miss.wu-wien.ac.at> X-Image-Url: http://www.cs.caltech.edu/~kiniry/graphics/jrk-8.99.jpg X-Url: http://www.cs.caltech.edu/~kiniry/ X-Face: 9X:!41!x9hOT+cJU.gb=hXxEm6v)ZczE-':_8mlM-7^G!j%2$QC00w?G "x_1ZnY3[!+gGQD.6%=0EMBt[m|kdKsr*m=3J&r(#is5]J>&eVWNy-h^DrtO_5jES gK6NFKoj%c=+E?*%+\S$Rn7Y|mT(a~1Y{[$MZR[8~(bK[P4]RM2E<"5:n|2Gm!V

7aWw 9+K|b{`Ou,uYaNn(`QDDR Message-ID: User-Agent: Gnus/5.0808 (Gnus v5.8.8) Emacs/20.7 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Sender: owner-caml-list@pauillac.inria.fr Precedence: bulk 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