Version française
Home     About     Download     Resources     Contact us    
Browse thread
Wanted: your feedback on the hierarchy of OCaml Batteries Included
[ Home ] [ Index: by date | by threads ]
[ Search: ]

[ Message by date: previous | next ] [ Message in thread: previous | next ] [ Thread: previous | next ]
Date: -- (:)
From: Richard Jones <rich@a...>
Subject: Re: [Caml-list] Wanted: your feedback on the hierarchy of OCaml Batteries Included
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