Re: [Caml-list] CDK binary release

[John Max Skaller <skaller@ozemail.com.au>]

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