From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.1.3 (2006-06-01) on yquem.inria.fr X-Spam-Level: * X-Spam-Status: No, score=1.7 required=5.0 tests=AWL,DNS_FROM_SECURITYSAGE, SPF_FAIL autolearn=disabled version=3.1.3 X-Original-To: caml-list@yquem.inria.fr Delivered-To: caml-list@yquem.inria.fr Received: from mail2-relais-roc.national.inria.fr (mail2-relais-roc.national.inria.fr [192.134.164.83]) by yquem.inria.fr (Postfix) with ESMTP id 612BFBBAF for ; Tue, 18 Nov 2008 16:20:35 +0100 (CET) X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AvgCAG1sIknAXQIngWdsb2JhbACTWQEBFiK+aoJ5 X-IronPort-AV: E=Sophos;i="4.33,625,1220220000"; d="scan'208";a="17328854" Received: from concorde.inria.fr ([192.93.2.39]) by mail2-smtp-roc.national.inria.fr with ESMTP; 18 Nov 2008 16:20:35 +0100 Received: from mail4-relais-sop.national.inria.fr (mail4-relais-sop.national.inria.fr [192.134.164.105]) by concorde.inria.fr (8.13.6/8.13.6) with ESMTP id mAIFKYZI008116 (version=TLSv1/SSLv3 cipher=RC4-SHA bits=128 verify=OK) for ; Tue, 18 Nov 2008 16:20:35 +0100 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AvgCAG1sIklQRFuwgWdsb2JhbACTWQEBFiK+aoJ5 X-IronPort-AV: E=Sophos;i="4.33,625,1220220000"; d="scan'208";a="31567966" Received: from furbychan.cocan.org ([80.68.91.176]) by mail4-smtp-sop.national.inria.fr with ESMTP/TLS/AES256-SHA; 18 Nov 2008 16:20:34 +0100 Received: from rich by furbychan.cocan.org with local (Exim 4.63) (envelope-from ) id 1L2SNV-0004oU-0I; Tue, 18 Nov 2008 15:20:33 +0000 Date: Tue, 18 Nov 2008 15:20:32 +0000 To: David Teller Cc: OCaml Subject: Re: [Caml-list] Wanted: your feedback on the hierarchy of OCaml Batteries Included Message-ID: <20081118152032.GA18392@annexia.org> References: <1227002178.6170.25.camel@Blefuscu> <20081118100625.GA25627@annexia.org> <1227007048.6170.35.camel@Blefuscu> <20081118122248.GG27367@annexia.org> <1227012549.6170.103.camel@Blefuscu> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <1227012549.6170.103.camel@Blefuscu> User-Agent: Mutt/1.5.13 (2006-08-11) From: Richard Jones X-Miltered: at concorde with ID 4922DD42.000 by Joe's j-chkmail (http://j-chkmail . ensmp . fr)! X-Spam: no; 0.00; ocaml:01 0100,:01 ocamldoc:01 ocaml:01 ocamldoc:01 mli:01 camlp:01 wrote:01 parsing:01 parsing:01 caml-list:01 argument:02 apis:03 hierarchy:03 redhat:03 On Tue, Nov 18, 2008 at 01:49:09PM +0100, David Teller wrote: > P.S.: I've pointedly ignored your perch on POD :) In my mind, that's a > very different topic. For the moment, we'll stick with ocamldoc. I've used POD selectively even in OCaml projects, mainly because it is by far the easiest way to generate man pages. OCamldoc is great for developer documentation (APIs etc) but POD is super-simple for making manual pages. cf man page: http://hg.et.redhat.com/virt/applications/virt-top--devel/?f=5b38082d8aa4;file=virt-top/virt-top.pod vs ocamldoc documentation: http://hg.et.redhat.com/virt/applications/ocaml-libvirt--devel/?f=893899664388;file=libvirt/libvirt.mli One place where POD really stands out, and could be replicated by camlp4, is for standalone programs that combine argument parsing, usage and man page all in one place. In many cases you can keep the option parsing, implementation of the option, and documentation for the option right next to each other. http://perldoc.perl.org/Getopt/Long.html#Documentation-and-help-texts Rich. -- Richard Jones Red Hat