[Nut-upsdev] Man page sections

[Greg Troxel]

Jim Klimov via Nut-upsdev <nut-upsdev at alioth-lists.debian.net> writes:

>   The puzzle I found myself solving is whether all NUT programs truly fit
> into "System management commands" (well, in a way they do all relate to
> power mgmt), or if the division line is more about end-user/interactive
> programs vs. daemons and sysadmin commands - similar to "bin" vs. "sbin"
> (can that choice of install path semi-bluntly apply to man section
> selection too)?

>From having used Unix since Sixth Edition, and not really going to study
anything before responding, my immediate reaction is

  Users should have /bin and /usr/bin in PATH, but not sbin.  Programs
  in bin are thus intended for users, and man pages should be foo.1

  System administration is generally done with /sbin and /usr/sbin
  additionally in path.   Programs in sbin are thus sysadmin commands,
  and man pages should be bar.8

>   Is the `NUT-Monitor` (python UI) a sysmgmt or user program? What about
> `upsc`, `upscmd`, `upsrw`? Perhaps tools like `nut-scanner` or `nutconf`?
> Or developer aids like `sockdebug`/`pipedebug`?

To answer this, think about a computer with a UPS, and 8 users, 2 of
whom are able to become root and do sysadmin, and 6 are not.  This is
the normal situation for a server.

If it's reasonable for a non-admin user to run a program, and it will
run and at least read status without needing to be a uid/gid with any
kind of privileges, then that program should probably be in bin and .1.
If the program doesn't make sense to use without privileges (even if the
privileges are knowing a nut pw, not being uid 0), then it belongs sbin
and .8.

I would say

  bin/1:
    upsc	

  sbin/8:
    upscmd, upsrw, nut-scanner, nutconf

>   There is less of question about `upsd` or daemon clients like `upsmon`,
> `upssched`, `upslog`, CGI, drivers, etc. - they belong in .8.

Agreed.  But cgi doesn't belong in sbin.  It belongs in libexec/cgi,
because sbin should only contain programs that people run.  Programs
that are (only) run by other programs belong in libexec.




An example of this "sort of logically system management but sensible for
normal users" is envstat (on NetBSD) which prints the CPU temperatures.
I would have said that belongs in bin/1, but it's in sbin/8.   So not
the right place (on a knife-edge decision) but consistentcy in place for
program and place for manual.