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 XAA27028; Wed, 12 May 2004 23:53:58 +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 XAA27239 for ; Wed, 12 May 2004 23:53:54 +0200 (MET DST) Received: from calmail-cl.berkeley.edu (mailfarm.Berkeley.EDU [128.32.61.106]) by concorde.inria.fr (8.12.10/8.12.10) with ESMTP id i4CLrqSH028996 for ; Wed, 12 May 2004 23:53:53 +0200 Received: from [64.162.212.212] (HELO tallman.kefka.frap.net) by calmail-cl.berkeley.edu (CommuniGate Pro SMTP 4.1.8) with SMTP id 27171382; Wed, 12 May 2004 14:53:52 -0700 Received: by tallman.kefka.frap.net (sSMTP sendmail emulation); Wed, 12 May 2004 14:51:56 -0700 Date: Wed, 12 May 2004 14:51:56 -0700 From: Kenneth Knowles To: "William D. Neumann" Cc: caml-list@inria.fr Subject: Re: [Caml-list] [ANNOUNCE] ocamlconf-0.5 release Message-ID: <20040512215156.GA8592@tallman.kefka.frap.net> References: <20040512095902.GA26460@tallman.kefka.frap.net> <20040512183504.GA8359@tallman.kefka.frap.net> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.6i X-Miltered: at concorde with ID 40A29CF0.002 by Joe's j-chkmail (http://j-chkmail.ensmp.fr)! X-Loop: caml-list@inria.fr X-Spam: no; 0.00; knowles:99 caml-list:01 2004:99 0600,:01 ocamldoc:01 more-or-less:01 mlgmp:01 ocamldoc:01 api:01 ocamlweb:01 ocaml:01 literate:01 wrote:03 inline:03 neumann:03 Sender: owner-caml-list@pauillac.inria.fr Precedence: bulk On Wed, May 12, 2004 at 02:20:20PM -0600, William D. Neumann wrote: > This is really, I suppose, the heart of my complaint. It seems that a > number of OCaml developers are relying on ocamldoc as their primary > documentation method. While this may work more-or-less well for a library > like mlgmp or similar, it is woefully inadequate for documenting anything > more substantial (e.g. applications). I basically think of OCamlConf as a library, but agree that ocamldoc output is not appropriate for applications. Every time I sit down to write a user's manual for ocamlconf (It is on the gameplan!) I end up re-hashing the inline comments almost word-for-word. I'm not sure the best way to write a tutorial that is heavily hyperlinked into the code, so it just gives a friendly front-end to the API. I'll take a look at ocamlweb; I'm curious about literate programming but usually find that the ordering necessary in prose is inconvenient for code. Kenn ------------------- To unsubscribe, mail caml-list-request@inria.fr Archives: http://caml.inria.fr Bug reports: http://caml.inria.fr/bin/caml-bugs FAQ: http://caml.inria.fr/FAQ/ Beginner's list: http://groups.yahoo.com/group/ocaml_beginners