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

[Steven Jenkins]

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


Steven

[Russ Allbery]

Post by Steven Jenkins
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?

Post by Steven Jenkins
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.

[Steven Jenkins]

Post by Russ Allbery
...

But it's not a

Post by Russ Allbery
strong opinion and I could be convinced otherwise.

I, too, could be convinced either way on moving/splitting/leaving alone.

However, a section in the README documenting the existing rationale would be
most helpful. (e.g., cut and paste your comments and put them into the
README.

Steven