Version française
Home     About     Download     Resources     Contact us    
Browse thread
Re: [Caml-list] Documentation tools
[ Home ] [ Index: by date | by threads ]
[ Search: ]

[ Message by date: previous | next ] [ Message in thread: previous | next ] [ Thread: previous | next ]
Date: -- (:)
From: Damien Doligez <Damien.Doligez@i...>
Subject: Re: [Caml-list] Documentation tools
>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