Nut upsdev - Jun 2025 - Man page sections

Cheers,

  During a recent PR review, I found that some man pages had links that
referred to clients like upsc as in man section 1, others as 8, and set out
to rectify it... only to find out that I am not sure about the actual right
path forward. So seeking community concensus on this one :)

  Namely, it seems that the only page built as a `.1` (since recently,
formalized as `.$(MAN_SECTION_CMD_USR)` because not all OSes follow the
same section layout) is a page for `libupsclient-config` (pre-pkgconf
helper script), and all other NUT programs landed in `.8` (or
`.$(MAN_SECTION_CMD_SYS)`).

  As a reminder, rough section definitions (common denominators that I
could find) that we juggle in docs/man/Makefile.am are:

* (3) Library calls: MAN_SECTION_API
* (5) File formats and configuration files: MAN_SECTION_CFG
* (8) System management commands: MAN_SECTION_CMD_SYS
* (1) User commands (Programs):
MAN_SECTION_CMD_USR
* (7) Overview, conventions, and miscellaneous:
MAN_SECTION_MISC

  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)?

  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`?

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

  So far this is posted as part of
https://github.com/networkupstools/nut/pull/2977 but I guess I'll break up
that PR to move forward with the less-questionable changes.

Jim Klimov
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://alioth-lists.debian.net/pipermail/nut-upsdev/attachments/20250604/464ca958/attachment.htm>

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.