From: Richard Jones <rich@annexia.org>
To: David Teller <David.Teller@univ-orleans.fr>
Cc: OCaml <caml-list@inria.fr>
Subject: Re: [Caml-list] Wanted: your feedback on the hierarchy of OCaml Batteries Included
Date: Tue, 18 Nov 2008 15:20:32 +0000 [thread overview]
Message-ID: <20081118152032.GA18392@annexia.org> (raw)
In-Reply-To: <1227012549.6170.103.camel@Blefuscu>
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
next prev parent reply other threads:[~2008-11-18 15:20 UTC|newest]
Thread overview: 80+ messages / expand[flat|nested] mbox.gz Atom feed top
2008-11-18 9:56 David Teller
2008-11-18 10:06 ` [Caml-list] " Richard Jones
2008-11-18 10:21 ` Zheng Li
2008-11-18 11:22 ` David Teller
2008-11-18 12:52 ` Zheng Li
2008-11-18 14:10 ` [Caml-list] " Alain Frisch
2008-11-18 14:19 ` David Teller
2008-11-19 3:06 ` Yaron Minsky
2008-11-19 3:47 ` Till Varoquaux
2008-11-19 10:57 ` Stefano Zacchiroli
2008-11-19 18:05 ` Stéphane Glondu
2008-11-20 0:14 ` Stefano Zacchiroli
2008-11-18 10:29 ` [Caml-list] " Erkki Seppala
2008-11-18 11:34 ` Daniel Bünzli
2008-11-18 11:47 ` Thomas Gazagnaire
2008-11-18 12:15 ` David Teller
2008-11-18 12:32 ` Richard Jones
2008-11-18 12:56 ` David Teller
2008-11-19 13:38 ` Stefano Zacchiroli
2008-11-19 17:37 ` Richard Jones
2008-11-23 10:32 ` Stefano Zacchiroli
[not found] ` <9b415f950811180428x2de94a64q6fa92887f8e00705@mail.gmail.com>
2008-11-18 12:51 ` David Teller
2008-12-19 11:00 ` Benedikt Grundmann
2009-01-05 10:40 ` David Teller
2008-11-18 13:24 ` Daniel Bünzli
2008-11-18 14:46 ` David Teller
2008-11-18 12:40 ` David Teller
2008-11-18 13:31 ` Dario Teixeira
2008-11-18 14:23 ` David Teller
2008-11-18 14:40 ` Stefano Zacchiroli
2008-11-19 13:36 ` Stefano Zacchiroli
2008-11-19 14:28 ` Daniel Bünzli
2008-11-19 14:45 ` Paolo Donadeo
2008-11-21 12:37 ` Michaël Le Barbier
2008-11-18 11:17 ` David Teller
2008-11-18 12:22 ` Richard Jones
2008-11-18 12:49 ` David Teller
2008-11-18 15:20 ` Richard Jones [this message]
2008-11-18 18:17 ` Jon Harrop
2008-11-18 17:51 ` Nicolas Pouillard
2008-11-18 22:43 ` Jon Harrop
2008-11-18 18:59 ` Richard Jones
2008-11-18 20:17 ` Jon Harrop
2008-11-18 19:22 ` Richard Jones
2008-11-18 19:50 ` Daniel Bünzli
2008-11-18 21:50 ` Richard Jones
2008-11-19 13:48 ` Stefano Zacchiroli
2008-11-19 19:02 ` Stéphane Glondu
2008-11-18 22:07 ` Alain Frisch
2008-11-18 23:49 ` Jon Harrop
2008-11-18 23:13 ` Alain Frisch
2008-11-19 13:28 ` Stefano Zacchiroli
2008-11-18 23:30 ` Jon Harrop
2008-11-19 6:29 ` David Teller
2008-11-19 8:36 ` Jon Harrop
2008-11-19 9:46 ` Paolo Donadeo
2008-11-19 20:11 ` Maxence Guesdon
2008-11-20 9:28 ` Nicolas Pouillard
2008-11-20 10:33 ` Richard Jones
2008-11-20 10:49 ` open Module (not?) considered harmful Stefano Zacchiroli
2008-11-20 11:29 ` [Caml-list] " David Allsopp
2008-11-20 11:48 ` Richard Jones
2008-11-20 17:56 ` Stefano Zacchiroli
2008-11-20 13:01 ` Nicolas Pouillard
2008-11-20 13:41 ` Nicolas Pouillard
2008-11-20 16:44 ` Stefano Zacchiroli
2008-11-21 2:56 ` Stability of exceptions Eliot Handelman
2008-11-21 7:39 ` [Caml-list] " Daniel Bünzli
2008-11-21 9:52 ` Christophe TROESTLER
2008-11-20 14:46 ` [Caml-list] open Module (not?) considered harmful Ashish Agarwal
2008-11-20 17:54 ` Stefano Zacchiroli
2008-11-20 11:31 ` Daniel Bünzli
2008-11-23 10:36 ` Stefano Zacchiroli
2008-11-20 11:41 ` Richard Jones
2008-11-23 10:38 ` Stefano Zacchiroli
2008-11-23 11:01 ` Richard Jones
2008-11-20 12:58 ` [Caml-list] Wanted: your feedback on the hierarchy of OCaml Batteries Included Nicolas Pouillard
2008-11-20 21:12 ` David Teller
2008-11-20 23:18 ` Daniel Bünzli
2008-11-21 9:34 ` David Teller
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20081118152032.GA18392@annexia.org \
--to=rich@annexia.org \
--cc=David.Teller@univ-orleans.fr \
--cc=caml-list@inria.fr \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).