From mboxrd@z Thu Jan 1 00:00:00 1970 Received: (from majordomo@localhost) by pauillac.inria.fr (8.7.6/8.7.3) id GAA09438; Tue, 15 May 2001 06:24:14 +0200 (MET DST) X-Authentication-Warning: pauillac.inria.fr: majordomo set sender to owner-caml-list@pauillac.inria.fr using -f Received: from nez-perce.inria.fr (nez-perce.inria.fr [192.93.2.78]) by pauillac.inria.fr (8.7.6/8.7.3) with ESMTP id GAA09362 for ; Tue, 15 May 2001 06:24:13 +0200 (MET DST) Received: from beaune.inria.fr (beaune.inria.fr [128.93.8.3]) by nez-perce.inria.fr (8.11.1/8.10.0) with ESMTP id f4F4OD524160 for ; Tue, 15 May 2001 06:24:13 +0200 (MET DST) Received: by beaune.inria.fr (8.8.8/1.1.22.3/14Sep99-0328PM) id GAA0000023003; Tue, 15 May 2001 06:24:13 +0200 (MET DST) Date: Tue, 15 May 2001 06:24:13 +0200 (MET DST) From: Damien Doligez Message-Id: <200105150424.GAA0000023003@beaune.inria.fr> To: caml-list@pauillac.inria.fr Subject: Re: [Caml-list] Documentation tools Sender: owner-caml-list@pauillac.inria.fr Precedence: bulk >From: "Benjamin C. Pierce" > >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 or . 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