Re: [Caml-list] Documentation tools

[Markus Mottl <mottl@miss.wu-wien.ac.at>]

I fully agree with Benjamin and Damien. Some light annotations as opposed
to heavy markup would be ok, but at least for me it's really important
that I can also easily cross-reference to "real" documentation, which
currently only leaves Latex as viable alternative.

Difficult algorithmic stuff is better explained in separate documents,
and heavy-weight literate programming is too cumbersome for me if I want
to maintain code. For simple library interface documentation, something
as "light" as the current documentation style used in the OCaml standard
libraries would suffice for me.

There is also the psychological issue that if we allow advanced
annotations, people will really use them. This is not unlikely to produce
good looking but completely incomprehensible documentation, not even to
mention the difficulty of reading the source comments. It's the contents
that matters...

Regards,
Markus Mottl

-- 
Markus Mottl, mottl@miss.wu-wien.ac.at, http://miss.wu-wien.ac.at/~mottl

On Tue, 15 May 2001, Damien Doligez wrote:
> >From: "Benjamin C. Pierce" <bcpierce@saul.cis.upenn.edu>
> >
> >So I would not like to see us decide on a documentation tool that
> >requires *every* entry in every interface file to be annotated with some
> >kind of heavy markup like a big pile of html/docbook tags.  A small
> >amount of extra cruft in interfaces is acceptable, but please let's not
> >make all our .mli files totally unreadable for the sake of generating
> >fancy docs.
> 
> I couldn't agree more !!  I would absolutely hate to be forced to
> write my comments in some non-human-readable language such as HTML (or
> any other instance of SGML/XML).  In my opinion, unobtrusiveness is a
> lot more important than any fancy feature like <blink> or
> <img src="http://cristal.inria.fr/~harley/ecdl7/pics/planar.gif">.
> </blink>
> 
> You want titles and subtitles, font change for code, enumerations,
> maybe some escape mechanism to write formulas in LaTeX, a way of
> producing cross-references, and that's it.  Everything else is
> overhead.
> 
> -- Damien
> -------------------
> To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr
-------------------
To unsubscribe, mail caml-list-request@inria.fr.  Archives: http://caml.inria.fr