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 RAA07370; Thu, 10 May 2001 17:42:39 +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 RAA07366 for ; Thu, 10 May 2001 17:42:38 +0200 (MET DST) Received: from ext.lri.fr (ext.lri.fr [129.175.15.4]) by nez-perce.inria.fr (8.11.1/8.10.0) with ESMTP id f4AFgb910463; Thu, 10 May 2001 17:42:37 +0200 (MET DST) Received: from pc803.lri.fr (IDENT:root@pc803 [129.175.8.114]) by ext.lri.fr (8.11.1/jtpda-5.3.2) with ESMTP id f4AFgY502194 ; Thu, 10 May 2001 17:42:34 +0200 (MET DST) Received: by pc803.lri.fr (8.9.3/feuille) id RAA09287 ; Thu, 10 May 2001 17:42:47 +0200 X-Authentication-Warning: localhost.localdomain: filliatr set sender to filliatr@pc803 using -f From: Jean-Christophe Filliatre MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <15098.46839.795500.758294@pc803> Date: Thu, 10 May 2001 17:42:47 +0200 (MEST) To: Markus Mottl Cc: Sven LUTHER , Fabrice Le Fessant , John Max Skaller , caml-list@inria.fr, Claude.Marche@lri.fr Subject: Re: [Caml-list] CDK binary release In-Reply-To: <20010510151854.A6851@miss.wu-wien.ac.at> References: <15094.25994.675673.222337@cremant.inria.fr> <20010509125858.B28402@miss.wu-wien.ac.at> <3AF9852A.F2B18679@ozemail.com.au> <20010510004003.A27333@miss.wu-wien.ac.at> <3AF9D067.93E6DE1A@ozemail.com.au> <15098.23852.403551.65183@cremant.inria.fr> <20010510131646.A20887@lambda.u-strasbg.fr> <20010510151854.A6851@miss.wu-wien.ac.at> X-Mailer: VM 6.49 under Emacs 20.4.1 Reply-To: Jean-Christophe.Filliatre@lri.fr (Jean-Christophe Filliatre) Sender: owner-caml-list@pauillac.inria.fr Precedence: bulk Markus Mottl writes: > On Thu, 10 May 2001, Sven LUTHER wrote: > > On Thu, May 10, 2001 at 11:19:40AM +0200, Fabrice Le Fessant wrote: > > > The CDK documentation tool has still many problems, but it is > > > currently the only tool which produces man pages for Ocaml modules and > > > functions. Moreover, LaTeX is not used by all Ocaml users (some are > > > using Windows and its wonderful editors). For now, I think the best > > > language is a specific language, for example, a subset of HTML. > > I agree with Dave and Sven that producing LaTeX should be supported in > some way or the other. HTML alone is not good enough, and translating > from HTML to LaTeX definitely doesn't seem to be so much easier than the > other way round. It's usually better to translate from more powerful to > less powerful languages. > > To summarize, I'd prefer a tool that produces Latex and also allows > Latex-code within the documentation. Ocamlweb could surely be improved > (more features, more beautiful formatting, etc.), but I think it gets > the ideas of simplicity + expressiveness basically right. Why not take > this tool and make it ready for wide-spread public use? I was a bit > surprised that cdk_doc doesn't build on ocamlweb + hevea. As the (co)author of ocamlweb, I think I should say something at that point. First, I agree that ocamlweb could be improved, and in particular that its HTML output is rather ugly. But the purposes of cdk_doc and ocamlweb are clearly different: - cdk_doc is nice to produce HTML documentations of libraries, to be browsed when developping. Personally, I find these pages quite nice and useful. - ocamlweb is a literate programming tool; it means that it is used to produce a document describing the all code i.e. interface but also implementation, explaining the algorithms, giving complexity analysis, scientific references, etc. This document is intended to be read as an article (not to be quickly browsed to find out the name and/or spec of a function) and, for that purpose, it has to be *beautiful*, especially if it involves mathematical material. Knuth invented TeX to support literate programming (among other applications like scientific publishing), because literate programming *needs* a complex typographic tool. HTML is not (and will probably never be) such a tool. I hope this will help clarifying the difference between cdk_doc and ocamlweb. -- Jean-Christophe FILLIATRE mailto:Jean-Christophe.Filliatre@lri.fr http://www.lri.fr/~filliatr ------------------- To unsubscribe, mail caml-list-request@inria.fr. Archives: http://caml.inria.fr