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