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 LAA13401; Tue, 15 May 2001 11:42:36 +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 LAA13542 for ; Tue, 15 May 2001 11:42:35 +0200 (MET DST) Received: from miss.wu-wien.ac.at (miss.wu-wien.ac.at [137.208.107.17]) by nez-perce.inria.fr (8.11.1/8.10.0) with ESMTP id f4F9gZ903445; Tue, 15 May 2001 11:42:35 +0200 (MET DST) Received: (from mottl@localhost) by miss.wu-wien.ac.at (8.9.0/8.9.0) id LAA12961; Tue, 15 May 2001 11:42:26 +0200 (MET DST) Date: Tue, 15 May 2001 11:42:26 +0200 From: Markus Mottl To: Damien Doligez Cc: caml-list@pauillac.inria.fr Subject: Re: [Caml-list] Documentation tools Message-ID: <20010515114226.A10458@miss.wu-wien.ac.at> References: <200105150424.GAA0000023003@beaune.inria.fr> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline User-Agent: Mutt/1.2.5i In-Reply-To: <200105150424.GAA0000023003@beaune.inria.fr>; from Damien.Doligez@inria.fr on Tue, May 15, 2001 at 06:24:13 +0200 Sender: owner-caml-list@pauillac.inria.fr Precedence: bulk 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" > > > >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 ------------------- To unsubscribe, mail caml-list-request@inria.fr. Archives: http://caml.inria.fr