[OpenAFS-Doc] another mini-project: ensure man1, man5, and man8 are correct

[Russ Allbery]

Steven Jenkins <steven.jenkins@gmail.com> writes:

> Quite a few administrative commands are documented in man1 (pod1 in the
> src) that should actually be over in pod8 as they require administrative
> privileges.  B<vos> and all it's children should be moved, as general
> users should not be using those commands.

The sections of the man pages should also match the directories into which
the commands are installed as well.  Commands installed in bin should be
documented in section 1 and commands installed in sbin should be
documented in section 8.  This may in some cases mean moving the commands.

Note that there are vos commands that anyone can run and often do (vos
examine, for instance).  It's very hard with AFS to clearly draw this
line.  My inclination is to keep most things in section 1, even commands
for AFS administrators.

There's also the standard ambiguity around section 8 -- is it for commands
that require administrative privileges on the local system, or
administrative privileges in some nebulous larger sense?

> Thought needs to go into whether or not we want to split B<fs> and
> B<pts>, for example, as some of the commands are for users, some are
> not.  If we make a decision _not_ to split them, then that should be
> documented somewhere in the README for future reference.

I don't think splitting them is a good idea for several reasons, one of
which is that I think the section should match the installation directory
and we can only install fs and pts in one directory.  But it's not a
strong opinion and I could be convinced otherwise.

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