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

[Russ Allbery]

Hm, I'm not sure this message actually made it to openafs-doc.  At least,
I don't seem to have gotten a copy from the mailing list.

Jeffrey Hutzelman <jhutz@cmu.edu> writes:

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

Good idea.

Well, it kind of does this now, it just prints out 400 warning messages.
Which is a little excessive.  :)  I'll fix that.

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

I can do that, sure.

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

I was thinking about moving the man page generation to a separate script
that regen.sh just runs anyway.  I'll see if I can work out something that
meets the above criteria (although I'll probably finish the first editing
pass first, since after that point the work becomes much more
parallelizable.)

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

Also a good idea.

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

Okay, I'll try doing a regular build and seeing where that puts things.
That's a good idea; I should have done that first.

It's probably a good idea to switch the Debian build over to doing a
regular install rather than a make dest, actually, since Debian doesn't
care about Transarc compatibility and that's the whole point of make dest.

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