[OpenAFS-devel] The OpenAFS man page project

[Russ Allbery]

Hello everyone,

I'm sending this to openafs-devel as well as openafs-doc since I'm not
sure if everyone who's interested is on openafs-doc.  Further messages on
this subject will go only to openafs-doc, so those of you who want to see
the discussion should join that mailing list.

I've committed to the trunk the initial conversion of the AFS
Administration Reference to POD, and have completed a hand edit of all of
the section one man pages to clean up various formatting issues and
inconsistencies.  (For all the vaunted benefits of professional
documentation writers, and indeed the documentation is wonderfully
complete, the existing HTML pages are rather inconsistent about formatting
and markup.)

This editing pass for formatting and markup took me about a day for the
section one man pages, so I expect there are two days of editing left to
be done.  My goal is to get that work done by the 16th.

The POD source is converted to formatted man pages as part of running
regen.sh so that consumers of release tarballs won't have to have pod2man
available to get man pages.  The quality of the conversion should be
adequate for any version of Perl released in the past five years, but for
best results you want to use pod2man that comes with Perl 5.8 or later, or
alternately install Pod::Simple 3.03 (or later) and podlators 2.00 (or
later) from CPAN before running regen.sh.

The section one man pages should now be in reasonable shape and are ready
for general review.  I'll be sending out the README in a moment which
explains known issues and how to contribute.  For right now, if you want
to review the man pages, you need to check out the OpenAFS trunk from CVS;
this will change in the future (see below).  Please do not bother looking
at the section five and section eight man pages yet.  What's in CVS is an
initial starting point after an automated conversion and needs significant
cleanup work to be even adequate.  I'm currently working on this and will
send out another message when it's done.

The breakdown of man pages between sections is somewhat arbitrary,
particularly since I wanted to keep command suites together.  Yes, vos is
in section one and bos is in section eight and this doesn't necessarily
make a tremendous amount of sense.  If someone comes up with a clear
guideline for what should go where, I'm all ears; in the meantime, this
seemed vaguely reasonable, and we can always move commands later.
Unfortunately, where OpenAFS itself installs commands (bin or etc or
root.server) also needs to be reviewed and isn't a particularly great
guide.

The current next steps are:

 * Finish the editing on section five and section eight.

 * Evaluate the available HTML converters and find the one that does the
   best job.  Develop a recipe for good HTML conversion and publish it.

 * Publish an HTML copy of all of the man pages for easier public review.

 * Invite public review of all of the man pages.

 * Ongoing: Respond to the results of public review, committing
   contributions and trying to fix problems.

If you're comfortable with CVS and reviewing man pages, please feel free
to check out the current trunk, run regen.sh to generate the man pages,
and start looking at the section one man pages and sending patches,
corrections, additional documentation, or problem reports to openafs-doc.
Please be aware that I'm going to finish the first editing pass on all the
man pages before responding to any review results on the section one man
pages, but I will be keeping all of those messages and promise that I'll
get to them.

If you'd rather review HTML pages, please wait for now.  As mentioned
above, that's coming.

If you're annoyed by POD and really want to edit Docbook, please help with
the Docbook conversion of the *other* reference manuals, which need just
as much attention, if not more, than the man pages do.

Currently, this work is only on the trunk, but provided that I make the
progress I expect to, it's targetted for 1.4.2.  I'm keeping track of the
trunk deltas and plan on pulling them all up to the stable branch as soon
as I've finished the first comprehensive editing pass and I'm confident
that the results won't be too embarassing.

-- 
Russ Allbery (rra@stanford.edu)             <http://www.eyrie.org/~eagle/>