[Caml-list] CDK Documentation format

[Dave Mason <dmason@sarg.Ryerson.CA>]

>>>>> On Thu, 10 May 2001 11:19:40 +0200 (CEST), Fabrice Le Fessant <fabrice.le_fessant@inria.fr> said:

> 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

LaTeX runs fine on MS-Windows.

> and its wonderful editors).

(I don't know if this was meant as sarcastic.  Probably not, although
it doesn't match my experience with MS-Windows.  For me, there is only
one decent editor for MS-Windows; it's called emacs.)

> For now, I think the
> best language is a specific language, for example, a subset of HTML.
> This would have the benefit of being easily translatable to LaTex(ie
> PS), HTML and MAN (I think HTML --> LaTeX is easier than LaTeX -->
> HTML, even with HeVea).

Unless you are providing (or pointing to) a translator from HTML-->
LaTeX, this is an iffy argument.  Simple LaTeX, understandable by
HeVea, isn't very difficult to write even if you never feed it to
LaTeX and only produce HTML.  And as a bonus, you can get rather nice
output from LaTeX!

> Note that the current language used by cdk_doc is documented in the
> HTML documentation of the CDK (cdk_doc.html).

I haven't had a chance to look at this yet, but wanted to make the
point that there is an open-source formatting system that produces
good output (LaTeX), already available, and it would be good to use it.

> cdk_doc was not designed for being used by everybody, but to
> generate immediatly some documentation for the CDK with a minimal
> effort. Now, we have to think about how to change Sebastien's tool
> in a more general documentation tool.

It shouldn't be very difficult to have it spit out LaTeX for HeVea.

> Another approach I used a few years ago was to generate HTML
> documentation using the compiler, which can add cross-links between
> modules (and even between types in the same module). This could be
> another good idea ...

Sounds interesting, but why not generate LaTeX?

../Dave
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr