[OpenAFS-Doc] Re: [OpenAFS-devel] The OpenAFS man page project

[Jeffrey Hutzelman]

Without having looked at the source Russ committed...

On Friday, December 09, 2005 03:28:43 PM -0800 Russ Allbery 
<rra@stanford.edu> wrote:



> 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.

OK, but since man pages are not an essential operational part of the 
system, people checking things out of CVS should _also_ not be required to 
have pod2man available in order to build the software.  I would suggest 
that regen.sh check for availability of pod2man, and if it is not 
available, print a warning and move on.

In an ideal world, this would be fatal when building release source; one 
way to do this would be to make regen.sh take a command-line switch which, 
when given, indicates that this is a release build and it should be more 
strict.  We can then cause make_release to use that switch when 
constructing the source tarballs for releases.


While I generally support the idea of building the man pages at regen time, 
I anticipate that folks packaging OpenAFS may want to run pod2man on the 
"right" platform, to get more consistency with whatever conventions are 
used on that platform.  It might be good to do something to facilitate 
regenerating the man pages without doing the autoconf step.  Similarly, as 
the number of man pages gets large, we may actually want regen to run a 
make-like operation so only pages which do not exist or whose sources have 
changed get rebuilt.



>   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.

Again, I think it would be good for the script to print a warning if the 
best tools are not available.


> 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.

Well, when you talk about etc and root.server, you're clearly looking at 
where things are being installed in the transarc-paths case.  That case 
exists for compatibility, and so deliberately installs things where AFS has 
always installed them.  It should not be changed.

For the non-transarc-paths case, we chose to install things according to 
GNU conventions, in which

- binaries that will be invoked by ordinary users are installed in bin
- binaries that will be invoked by system administrators, either directly
  or indirectly (e.g. by system startup scripts) are installed in sbin
- binaries that are normally invoked only by other programs are installed
  in libexec/openafs

Things in the first category should be documented in man1.
Things in the other two categories should be documented in man8.



Thanks for all the work you've done on this, Russ.

-- Jeff