Merge 8801edd into 8c45b56

jimklimov · web-flow · commit 50315d87066b · 2025-06-04T11:11:31.000+02:00
diff --git 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
@@ -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/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
@@ -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
@@ -179,8 +179,8 @@ Arjen de Korte <adkorte-guest@alioth.debian.org>
 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
@@ -216,8 +216,8 @@ Arjen de Korte <adkorte-guest@alioth.debian.org>
 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
@@ -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
@@ -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 <sebastian.kuttnig@gmail.com>
 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
@@ -1,4 +1,4 @@
-HUAWEI_UPS2000(8)
+HUAWEI-UPS2000(8)
 =================
 
 NAME
diff --git 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
@@ -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
+  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
@@ -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
@@ -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
@@ -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

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-HUAWEI_UPS2000(8)`
	`1`	`+HUAWEI-UPS2000(8)`
`2`	`2`	`=================`
`3`	`3`
`4`	`4`	`NAME`