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 OAA28159; Mon, 14 May 2001 14:22:57 +0200 (MET DST) X-Authentication-Warning: pauillac.inria.fr: majordomo set sender to owner-caml-list@pauillac.inria.fr using -f Received: from concorde.inria.fr (concorde.inria.fr [192.93.2.39]) by pauillac.inria.fr (8.7.6/8.7.3) with ESMTP id OAA28154; Mon, 14 May 2001 14:22:56 +0200 (MET DST) Received: from saul.cis.upenn.edu (SAUL.CIS.UPENN.EDU [158.130.12.4]) by concorde.inria.fr (8.11.1/8.10.0) with ESMTP id f4ECMs524343; Mon, 14 May 2001 14:22:54 +0200 (MET DST) Received: from localhost (localhost [127.0.0.1]) by saul.cis.upenn.edu (8.10.1/8.10.1) with SMTP id f4ECMtg16641; Mon, 14 May 2001 08:22:55 -0400 (EDT) To: Xavier Leroy cc: caml-list@pauillac.inria.fr Reply-to: bcpierce@cis.upenn.edu Subject: Re: [Caml-list] Documentation tools In-reply-to: Your message of Mon, 14 May 2001 10:11:44 +0200. <20010514101144.A22215@pauillac.inria.fr> Date: Mon, 14 May 2001 08:22:55 EDT Message-ID: <16639.989842975@saul.cis.upenn.edu> From: "Benjamin C. Pierce" Sender: owner-caml-list@pauillac.inria.fr Precedence: bulk I'd like to add one small point to the discussion of interface documentation tools: Being able to quickly get to texinfo files, man pages, or html docs for interfaces is great, but there is another way that is often even quicker, especially for the interfaces in the very project you're working on at the moment: just read the source! No matter how fancy our programming environments and support tools become, we're still going to spend a lot of time dealing directly with source files for interfaces -- not just writing, but reading them. 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. This is one thing that I think ocamlweb gets right: documentation comments can usually be just straight text, with embedded ML fragments enclosed in [...] so that the tool knows to change the font (and a more sophisticated tool might know to cross-reference known identifiers, etc.). I hope whatever tool the OCaml community chooses or designs will maintain this philosophy. -- B ------------------- To unsubscribe, mail caml-list-request@inria.fr. Archives: http://caml.inria.fr