[Nut-upsdev] Man page sections

[Jim Klimov]

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>