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 WAA17178; Sun, 13 May 2001 22:56:18 +0200 (MET DST) X-Authentication-Warning: pauillac.inria.fr: majordomo set sender to owner-caml-list@pauillac.inria.fr using -f Received: (from weis@localhost) by pauillac.inria.fr (8.7.6/8.7.3) id WAA17191 for caml-list@pauillac.inria.fr; Sun, 13 May 2001 22:56:18 +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 WAA11211 for ; Thu, 10 May 2001 22:36:42 +0200 (MET DST) Received: from localhost.localdomain (cartman93.zip.com.au [61.8.20.221]) by nez-perce.inria.fr (8.11.1/8.10.0) with ESMTP id f4AKac913959 for ; Thu, 10 May 2001 22:36:39 +0200 (MET DST) Received: from ozemail.com.au (IDENT:root@localhost [127.0.0.1]) by localhost.localdomain (8.9.3/8.8.7) with ESMTP id GAA20304 for ; Fri, 11 May 2001 06:36:32 +1000 Message-ID: <3AFAFBCF.DD36D9D@ozemail.com.au> Date: Fri, 11 May 2001 06:36:31 +1000 From: John Max Skaller X-Mailer: Mozilla 4.7 [en] (X11; I; Linux 2.2.12-20 i686) X-Accept-Language: en MIME-Version: 1.0 CC: caml-list@inria.fr Subject: Re: [Caml-list] CDK binary release 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> <15098.46839.795500.758294@pc803> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Sender: owner-caml-list@pauillac.inria.fr Precedence: bulk Jean-Christophe Filliatre wrote: > As the (co)author of ocamlweb, I think I should say something at that > point. > - 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. As the author of a powerful LP tool myself .. I don't have exactly the same view (although I'm not disagreeing entirely either). My tool is intended to be able to produce the kind of document Jean-Christophe described. But it is _also_ capable of a lot more. It can be used to produce interface summaries, to generate tables of test results, to generate code and documentation from compressed specifications, to produce hyperlinked cross references .. and a whole host of other kinds of useful 'documents'. While I agree that LaTeX is often the only choice for documenting theory or complex algorithms, a large amount of software doesn't need such sophisticated documentation. I personally find LaTeX output very difficult to read, since my Linux system is hopeless at rendering fonts at screen resolution (and I don't own a working printer). So I have a strong preference for HTML, since both my Linux and Windows boxes render the fonts quite well. It is also much easier to cross reference than a screen image of paper. Interscript produces _both_ HTML and LaTeX (and plain text as well), from the same source. It hyperlinks HTML cross references, and uses LaTeX cross-reference for LaTeX. [And line numbers for plain text!] It is also possible to include 'typesetter native' sections, which only get output to that typesetter: it is ugly, but possible, to generate nice category theory diagrams with XYpic for LaTeX, and then 'capture' the image into a JPG file and glue it into the HTML document. (I wish this could be automated). HTML can do some things that LaTeX cannot, apart from cross-referencing interactively: it can resize and adjust according to your screen size, and it supports colour on every system I've seen. And, if you have IE5+, interscript produces a folding table of contents -- which is kind of hard to do with LaTeX. :-) And of course, you can post your HTML program on the Web, so others can read annotated versions of your code without downloading the code .. or installing LaTeX, DVI viewers, or even a postscript viewer. My point is that Literate Programming is a paradigm in which code and documentation are co-developed, but that doesn't necessarily imply production of a fine quality journal quality article, although that should be possible. It should also be possible to LP commerical programs, or Ocaml bindings of some C interface, which may be better served by interactive hyperlinking than nice print. I think that means: I see no reason why a tool like Ocamlweb couldn't _also_ output interface summaries, and in HTML too, if it were suitably modified to do so. And this might be a good path, since it would then 'also' be able to produce nice scientific documents. For most applications, that would be an added bonus, rather than the main reason to use it...but that ability is a good incentive to make a deeper committment to LP. -- John (Max) Skaller, mailto:skaller@maxtal.com.au 10/1 Toxteth Rd Glebe NSW 2037 Australia voice: 61-2-9660-0850 checkout Vyper http://Vyper.sourceforge.net download Interscript http://Interscript.sourceforge.net ------------------- To unsubscribe, mail caml-list-request@inria.fr. Archives: http://caml.inria.fr