diff --git a/NEWS.adoc b/NEWS.adoc index 5453680443..9b63359ea2 100644 --- a/NEWS.adoc +++ b/NEWS.adoc @@ -183,16 +183,20 @@ https://github.com/networkupstools/nut/milestone/9 - NUT Monitor GUI: * Ported Python 3 version to Qt6, now shipped alongside Qt5 for systems with either or both, maximizing compatibility with old and new setups. - - - Introduced handling (possibly rewriting) for man page section "Overviews, - conventions, and miscellaneous" (commonly number 7), to deliver support - for `man nut` queries (NUT overview manual page also created). [#2945] - - - A new `configure --with-docs-man-dir-as-base` option was introduced so - that directories for man page sections can now be automatically named - as either "base" number of the section (e.g. `man1`) or by full section - name (`man1m`), as different OS distributions have different preferences - in this regard. [#2950] + [#2946] + + - Manual page recipes and contents: + * Introduced handling (possibly rewriting) for man page section "Overviews, + conventions, and miscellaneous" (commonly number 7), to deliver support + for `man nut` queries (NUT overview manual page also created). [#2945] + * A new `configure --with-docs-man-dir-as-base` option was introduced so + that directories for man page sections can now be automatically named + as either "base" number of the section (e.g. `man1`) or by full section + name (`man1m`), as different OS distributions have different preferences + in this regard. [#2950] + * Option to `configure --enable-docs-man-for-progs-built-only` was added, + to differentiate NUT builds that deliver man pages for only built programs + (legacy default) or for all of them (as needed for docs sites). [#2976] - The `BUILD_TYPE=default-all-errors ci_build.sh` script handling was revised to simplify code, and to default in CI builds to a quicker diff --git a/UPGRADING.adoc b/UPGRADING.adoc index 845c08100d..66544158e5 100644 --- a/UPGRADING.adoc +++ b/UPGRADING.adoc @@ -36,6 +36,10 @@ Changes from 2.8.3 to 2.8.4 As a packager, you may have to update the recipes accordingly (especially if your platform rewrites section numbers). [#2945, #2950] +- Option to `configure --enable-docs-man-for-progs-built-only` was added, + to differentiate NUT builds that deliver man pages for only built programs + (legacy default) or for all of them (as needed for docs sites). [#2976] + - Added APC BVKxxxM2 to list of devices where `lbrb_log_delay_sec=N` may be necessary to address spurious LOWBATT and REPLACEBATT events. [issue #2942] diff --git a/configure.ac b/configure.ac index 3da29ddb11..363f248e47 100644 --- a/configure.ac +++ b/configure.ac @@ -4218,7 +4218,7 @@ dnl POWERDOWNFLAG, "${POWERDOWNFLAG}", [Default path for upsmon POWERDOWNFLAG dnl --------------------------------------------------------------------- AC_MSG_CHECKING(if requested driver path) AC_ARG_WITH(drvpath, - AS_HELP_STRING([--with-drvpath=PATH], [where to install UPS drivers (EPREFIX/bin)]), + AS_HELP_STRING([--with-drvpath=PATH], [where to install UPS drivers (legacy default: EPREFIX/bin; recommended: a subdir of libexecdir)]), [ case "${withval}" in yes|no) diff --git a/docs/configure.txt b/docs/configure.txt index 7f33f42c43..d57f834a6a 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -808,7 +808,14 @@ See also `--with-drvpath` below. --with-drvpath=PATH The UPS drivers will be installed to this path. By default they -install to `/bin`, i.e. `/usr/local/ups/bin`. +install to `/bin`, i.e. `/usr/local/ups/bin`, but it +may be quite reasonable to install them into a sub-directory of +your `libexec` location or similar (e.g. `/usr/libexec/nut/drv`): +on one hand, to avoid potential conflicts with unrelated programs +that happen to have same names, and on another -- to keep these +NUT programs which should not normally be executed by neither +unprivileged users nor systems administrators, out of default +`PATH` settings. You would want a location that remains mounted when most of the system is prepared to turn off, so some distributions package NUT drivers into diff --git a/docs/man/.gitignore b/docs/man/.gitignore index c7798b0a1e..a5f270d079 100644 --- a/docs/man/.gitignore +++ b/docs/man/.gitignore @@ -11,6 +11,7 @@ /tmp/ /linkman-driver-names.txt /linkman-drivertool-names.txt +/linkman-docbuildmode-note.txt /linkman-*.txt.tmp /.check-html-man /.check-man-pages diff --git a/docs/man/Makefile.am b/docs/man/Makefile.am index 97b9b64fae..f8d4471128 100644 --- a/docs/man/Makefile.am +++ b/docs/man/Makefile.am @@ -1585,7 +1585,7 @@ endif !WITH_HTML_SINGLE # To regenerate these files, you may have to `make distclean` first # FIXME: Track also clients (e.g. NUT-Monitor UI, etc.), development-only tools # (sockdebug), or platform-specific progs (nut.exe) -LINKMAN_INCLUDE_GENERATED = linkman-driver-names.txt linkman-drivertool-names.txt +LINKMAN_INCLUDE_GENERATED = linkman-driver-names.txt linkman-drivertool-names.txt linkman-docbuildmode-note.txt LINKMAN_INCLUDE_CONSUMERS = index.txt upsd.txt nutupsdrv.txt nut.txt CLEANFILES = linkman-*.txt.tmp @@ -1636,9 +1636,38 @@ linkman-drivertool-names.txt: Makefile rm -f "$(builddir)/$(@F).tmp" ; \ fi +# Doing this dynamically as here, so we may later deliver some more dynamic +# content if desired (e.g. lists of built/not-built programs, date, version, +# etc.). Or maybe not, we'll see :) +if DOC_INSTALL_SELECTED_MANS_PROGS_BUILT + +linkman-docbuildmode-note.txt: Makefile + @echo " GENERATE-LINKMAN $@" + @( echo 'NOTE: This build of NUT was configured to deliver only manual pages for programs that were actually built. For more information about the ecosystem please see '; \ + echo 'ifndef::website[]' ; \ + echo 'the NUT website listing at https://networkupstools.org/docs/man/index.html or ' ; \ + echo 'endif::website[]' ; \ + echo 'the sources of these pages at https://github.com/networkupstools/nut/tree/master/docs/man'; \ + ) > "$(builddir)/$(@F)" + +else !DOC_INSTALL_SELECTED_MANS_PROGS_BUILT + +linkman-docbuildmode-note.txt: Makefile + @echo " GENERATE-LINKMAN $@" + @( echo 'NOTE: This build of NUT was configured to deliver all available manual'; \ + echo 'ifndef::website[]' ; \ + echo 'pages, and may include those for programs that were not actually built or installed.' ; \ + echo 'endif::website[]' ; \ + echo 'ifdef::website[]' ; \ + echo 'pages.' ; \ + echo 'endif::website[]' ; \ + ) > "$(builddir)/$(@F)" + +endif !DOC_INSTALL_SELECTED_MANS_PROGS_BUILT + # Dependencies are about particular filenames, since over time # we might have several use-cases for LINKMAN_INCLUDE_GENERATED: -$(LINKMAN_INCLUDE_CONSUMERS): linkman-driver-names.txt linkman-drivertool-names.txt +$(LINKMAN_INCLUDE_CONSUMERS): linkman-driver-names.txt linkman-drivertool-names.txt linkman-docbuildmode-note.txt # These files are generated when we build from git source so not tracked in # git, and not part of tarball (to be in builddir) - so not in EXTRA_DIST. diff --git a/docs/man/clone-outlet.txt b/docs/man/clone-outlet.txt index 890a75df2b..91950f92f9 100644 --- a/docs/man/clone-outlet.txt +++ b/docs/man/clone-outlet.txt @@ -179,8 +179,8 @@ Arjen de Korte SEE ALSO -------- -linkman:upscmd[1], -linkman:upsrw[1], +linkman:upscmd[8], +linkman:upsrw[8], linkman:ups.conf[5], linkman:clone[8], linkman:nutupsdrv[8] diff --git a/docs/man/clone.txt b/docs/man/clone.txt index 8a9d975995..52a25d7842 100644 --- a/docs/man/clone.txt +++ b/docs/man/clone.txt @@ -216,8 +216,8 @@ Arjen de Korte SEE ALSO -------- -linkman:upscmd[1], -linkman:upsrw[1], +linkman:upscmd[8], +linkman:upsrw[8], linkman:ups.conf[5], linkman:clone-outlet[8], linkman:nutupsdrv[8] diff --git a/docs/man/dummy-ups.txt b/docs/man/dummy-ups.txt index d10f0cbd57..6d86195657 100644 --- a/docs/man/dummy-ups.txt +++ b/docs/man/dummy-ups.txt @@ -33,8 +33,8 @@ Dummy Mode In this mode, *dummy-ups* looks like a standard NUT device driver to linkman:upsd[8] and allows one to change any value for testing purposes. -It is both interactive, controllable through the linkman:upsrw[1] and -linkman:upscmd[1] commands (or equivalent graphical tool), and batchable +It is both interactive, controllable through the linkman:upsrw[8] and +linkman:upscmd[8] commands (or equivalent graphical tool), and batchable through script files. It can be configured, launched and used as any other "real" NUT driver. @@ -250,7 +250,7 @@ INTERACTION Once the driver is loaded in dummy mode, you can change any variables, except those of the `driver.*` and `server.*` collections. You can do this by either editing the definition file, or use the -linkman:upsrw[1] and linkman:upscmd[1] commands. +linkman:upsrw[8] and linkman:upscmd[8] commands. Note that in simulation mode, new variables can be added on the fly, but only by adding these to the definition file (and waiting for it to be re-read). @@ -315,8 +315,8 @@ Arnaud Quette SEE ALSO -------- -linkman:upscmd[1], -linkman:upsrw[1], +linkman:upscmd[8], +linkman:upsrw[8], linkman:ups.conf[5], linkman:nutupsdrv[8] diff --git a/docs/man/failover.txt b/docs/man/failover.txt index 537bb5973d..7fe6d94b90 100644 --- a/docs/man/failover.txt +++ b/docs/man/failover.txt @@ -183,7 +183,7 @@ Any linkman:upsmon[8] clients would be set to monitor the `failover` UPS. The driver fully supports setting variables and performing instant commands on the currently elected primary UPS driver, which are proxied and with end-to-end -tracking also being possible (linkman:upscmd[1] and linkman:upsrw[1] `-w`). You +tracking also being possible (linkman:upscmd[8] and linkman:upsrw[8] `-w`). You may notice some variables and commands will be prefixed with `upstream.`, this is to clearly separate the upstream commands from those of `failover` itself. @@ -281,8 +281,8 @@ Sebastian Kuttnig SEE ALSO -------- -linkman:upscmd[1], -linkman:upsrw[1], +linkman:upscmd[8], +linkman:upsrw[8], linkman:ups.conf[5], linkman:upsc[8], linkman:upsmon[8], diff --git a/docs/man/huawei-ups2000.txt b/docs/man/huawei-ups2000.txt index 1479ff17a6..5282e82cb1 100644 --- a/docs/man/huawei-ups2000.txt +++ b/docs/man/huawei-ups2000.txt @@ -1,4 +1,4 @@ -HUAWEI_UPS2000(8) +HUAWEI-UPS2000(8) ================= NAME diff --git a/docs/man/index.txt b/docs/man/index.txt index 38c4321517..88ba105573 100644 --- a/docs/man/index.txt +++ b/docs/man/index.txt @@ -7,6 +7,8 @@ endif::website[] User manual pages ----------------- +include::{builddir}linkman-docbuildmode-note.txt[] + ifndef::in-nut-manpage[] NUT overview ~~~~~~~~~~~~ diff --git a/docs/man/nut.txt b/docs/man/nut.txt index 4a20481b81..249b1e6e3a 100644 --- a/docs/man/nut.txt +++ b/docs/man/nut.txt @@ -116,7 +116,7 @@ Practical work visible to end-users is done by a multitude of 'NUT clients', many of which are delivered by the project itself and more are created and maintained by the community at large. Some standard clients of note include: -* linkman:upsmon[1] is a daemon to monitor primarily the states of UPSes +* linkman:upsmon[8] is a daemon to monitor primarily the states of UPSes (as opposed to other device types that NUT can handle) which power some power source units of this particular system, and based on how many PSUs are required for the system to run -- initiates a local shutdown when too @@ -134,8 +134,8 @@ NOTE: The `upsmon` client typically splits into two processes: an unprivileged the time comes. + NUT deployments which desire higher-fidelity control (e.g. different systems - shutting down after different time spent on battery) often couple `upsmon` - with linkman:upssched[1]. + shutting down after different time spent on battery) often couple the + linkman:upsmon[8] with linkman:upssched[8] as their `NOTIFYCMD` handler. + The "primary" system is usually also responsible for commanding the managed UPS to shut itself down and power up when the "wall power" returns (or to @@ -148,10 +148,10 @@ The "primary" system is usually also responsible for commanding the managed and reboots them) just because external power returned when the shut down spree had already started. -* linkman:upsc[1] is a command-line client for anonymous read-only access, +* linkman:upsc[8] is a command-line client for anonymous read-only access, used to list devices served by a NUT data server, or to query data points reported by a particular device. -* linkman:NUT-Monitor[1] is a GUI client for read-only or read-write access. +* linkman:NUT-Monitor[8] is a GUI client for read-only or read-write access. * A suite of CGI clients can run on a web server like Apache or nginx to provide a simple HTML interface to your devices. @@ -309,7 +309,7 @@ into certain directories according to their documentation: linkman:hosts.conf[5] and linkman:upsset.conf[5] for configuration, and `upsstats-single.html` and `upsstats.html` for HTML UI templates. -Other clients, whether delivered by NUT project (linkman:NUT-Monitor[1] +Other clients, whether delivered by NUT project (linkman:NUT-Monitor[8] GUI) or co-located (link:https://github.com/networkupstools/wmnut[WMNut]) or third-party (see https://networkupstools.org/projects.html) would probably support saving their settings or "favorites". Do not forget diff --git a/docs/man/tripplite_usb.txt b/docs/man/tripplite_usb.txt index 11c0b786f0..4bdb18fdda 100644 --- a/docs/man/tripplite_usb.txt +++ b/docs/man/tripplite_usb.txt @@ -80,7 +80,7 @@ to the same monitoring system, and you want to be sure that you shut them down in the correct order. + This regex is matched against the full USB product string as seen in -linkmanext:lsusb[8]. The `ups.model` in the linkman:upsc[1] output only lists +linkmanext:lsusb[8]. The `ups.model` in the linkman:upsc[8] output only lists the name after `TRIPP LITE`, so to match a 'SMART2200RMXL2U', you could use the regex like `.*SMART2200.*`. diff --git a/docs/nut-versioning.adoc b/docs/nut-versioning.adoc index 4ffe56f1a2..53403c5dff 100644 --- a/docs/nut-versioning.adoc +++ b/docs/nut-versioning.adoc @@ -405,12 +405,12 @@ Variables propagated by nut_version.h Use in C code ------------- -common.c -~~~~~~~~ +common-nut_version.c +~~~~~~~~~~~~~~~~~~~~ -* The `NUT_VERSION_MACRO` is used in `common/common.c` and further made known - to all code base as a static string `UPS_VERSION` linked via `libcommon*.la` - internal libraries. +* The `NUT_VERSION_MACRO` is used in `common/common-nut_version.c` and further + made known to all code base as a static string `UPS_VERSION` linked via + `libcommon*.la` internal libraries. * Method `describe_NUT_VERSION_once()` prepares the string which combines the `NUT_VERSION_MACRO` with comments that it is either a `release` or a `(development iteration after $NUT_VERSION_SEMVER_MACRO)`, based on diff --git a/docs/nut.dict b/docs/nut.dict index 8840b3470a..438793681e 100644 --- a/docs/nut.dict +++ b/docs/nut.dict @@ -1,4 +1,4 @@ -personal_ws-1.1 en 3519 utf-8 +personal_ws-1.1 en 3520 utf-8 AAC AAS ABI @@ -1940,6 +1940,7 @@ dnf dnl dnsmasq docbook +docbuildmode docdir docinfo docs