Re: [Caml-list] CDK binary release

[Jean-Christophe Filliatre <Jean-Christophe.Filliatre@lri.fr>]

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