Fix man page section assignments for end-user interactive clients

NEWS.adoc

@@ -129,6 +129,10 @@ https://github.com/networkupstools/nut/milestone/9
      [#2957]
    * Fixed a couple of ancient memory leaks: one "shared" during driver
      program initialization, and one specific to `dummy-ups` wind-down. [#2972]
+   * Refactored `suggest_doc_links()` introduced in a recent NUT release into
+     separate `suggest_doc_links_CMD_SYS()` and `suggest_doc_links_CMD_USR()`
+     helper methods (used in command-line help of programs that refer to their
+     manual pages), wrapping a common implementation. [#2977]
 
  - `dummy-ups` driver updates:
    * A new instruction `ALARM` was added for the `Dummy Mode` operation
@@ -197,6 +201,10 @@ https://github.com/networkupstools/nut/milestone/9
    * 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]
+   * Several man page sources revised to tack the correct section code (e.g.
+     `upsc`, `upscmd`, `upsrw` and `NUT-Monitor` are clients that end-users
+     can interact with (section 1), while `upsmon` and `upssched` are rather
+     system services (section 8). [#2977]
 
  - 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
@@ -289,6 +297,8 @@ https://github.com/networkupstools/nut/milestone/11
      (development or release snapshot); many programs now display such
      references in their command-line usage help, method `suggest_doc_links()`
      was introduced for this purpose. [issue #722, PR #2733]
+     - Note that this method was split into several with NUT v2.843, with
+       similar names. [PR #2977]
 
  - A technologically and practically interesting revamp of NUT mesh of
    link:https://www.gnu.org/software/automake/[automake] (`Makefile.am`)

UPGRADING.adoc

@@ -40,6 +40,11 @@ Changes from 2.8.3 to 2.8.4
   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]
 
+- Man pages for `upsc`, `upscmd`, `upsrw` and `NUT-Monitor` were consistently
+  assigned to man page section 1 (end-user programs).  This may require some
+  changes in packaging recipes to deliver built pages with a different filename
+  extension and/or into different directories. [#2977]
+
 - 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]
 

clients/upsc.c

@@ -68,7 +68,7 @@ static void usage(const char *prog)
 
 	nut_report_config_flags();
 
-	printf("\n%s", suggest_doc_links(prog, NULL));
+	printf("\n%s", suggest_doc_links_CMD_USR(prog, NULL));
 }
 
 static void printvar(const char *var)

clients/upscmd.c

@@ -75,7 +75,7 @@ static void usage(const char *prog)
 
 	nut_report_config_flags();
 
-	printf("\n%s", suggest_doc_links(prog, "upsd.users"));
+	printf("\n%s", suggest_doc_links_CMD_USR(prog, "upsd.users"));
 }
 
 static void print_cmd(char *cmdname)

clients/upslog.c

@@ -235,7 +235,7 @@ static void help(const char *prog)
 
 	nut_report_config_flags();
 
-	printf("\n%s", suggest_doc_links(prog, NULL));
+	printf("\n%s", suggest_doc_links_CMD_SYS(prog, NULL));
 
 	exit(EXIT_SUCCESS);
 }

clients/upsmon.c

@@ -3269,7 +3269,7 @@ static void help(const char *arg_progname)
 
 	nut_report_config_flags();
 
-	printf("\n%s", suggest_doc_links(arg_progname, "upsmon.conf"));
+	printf("\n%s", suggest_doc_links_CMD_SYS(arg_progname, "upsmon.conf"));
 
 	exit(EXIT_SUCCESS);
 }

clients/upsrw.c

@@ -76,7 +76,7 @@ static void usage(const char *prog)
 
 	nut_report_config_flags();
 
-	printf("\n%s", suggest_doc_links(prog, "upsd.users"));
+	printf("\n%s", suggest_doc_links_CMD_USR(prog, "upsd.users"));
 }
 
 static void clean_exit(void)

clients/upssched.c

@@ -1524,7 +1524,7 @@ static void help(const char *arg_progname)
 
 	nut_report_config_flags();
 
-	printf("\n%s", suggest_doc_links(arg_progname, "upsmon.conf"));
+	printf("\n%s", suggest_doc_links_CMD_SYS(arg_progname, "upsmon.conf"));
 
 	exit(EXIT_SUCCESS);
 }

common/common-nut_version.c

@@ -270,7 +270,7 @@ void nut_report_config_flags(void)
 	}
 }
 
-const char *suggest_doc_links(const char *progname, const char *progconf) {
+static const char *do_suggest_doc_links(const char *progname, const char *progconf, const char *mansection) {
 	static char	buf[LARGEBUF];
 
 	buf[0] = '\0';
@@ -297,7 +297,9 @@ const char *suggest_doc_links(const char *progname, const char *progconf) {
 		 */
 		snprintfcat(buf, sizeof(buf),
 			"Read The Fine Manual ('man %s %s') and/or ",
-			MAN_SECTION_CMD_SYS, buf2);
+			mansection, buf2);
+#else
+		NUT_UNUSED_VARIABLE(mansection);
 #endif
 		snprintfcat(buf, sizeof(buf),
 			"see\n\t%s/docs/man/%s.html\n",
@@ -314,3 +316,11 @@ const char *suggest_doc_links(const char *progname, const char *progconf) {
 
 	return buf;
 }
+
+const char *suggest_doc_links_CMD_SYS(const char *progname, const char *progconf) {
+	return do_suggest_doc_links(progname, progconf, MAN_SECTION_CMD_SYS);
+}
+
+const char *suggest_doc_links_CMD_USR(const char *progname, const char *progconf) {
+	return do_suggest_doc_links(progname, progconf, MAN_SECTION_CMD_USR);
+}

docs/config-notes.txt

@@ -421,7 +421,7 @@ probably misconfigured during the <<Driver_configuration, Driver configuration>>
 step.  If you reconfigure the driver, use `upsdrvctl stop` to stop it, then
 start it again as shown in the <<Starting_drivers, Starting driver(s)>> step.
 
-Reference: man page: linkman:upsc[8]
+Reference: man page: linkman:upsc[1]
 
 
 All data
@@ -481,7 +481,7 @@ above.  A sample run on an UPS (Eaton Ellipse MAX 1100) looks like this:
 	ups.timer.start: -1
 	ups.vendorid: 0463
 
-Reference: man page: linkman:upsc[8],
+Reference: man page: linkman:upsc[1],
 <<nut-names,NUT command and variable naming scheme>>
 
 Startup scripts

docs/man/Makefile.am

@@ -334,13 +334,13 @@ SRC_CLIENT_PAGES = \
 
 INST_MAN_CLIENT_PAGES = \
 	nutupsdrv.$(MAN_SECTION_CMD_SYS) \
-	upsc.$(MAN_SECTION_CMD_SYS) \
-	upscmd.$(MAN_SECTION_CMD_SYS) \
+	upsc.$(MAN_SECTION_CMD_USR) \
+	upscmd.$(MAN_SECTION_CMD_USR) \
 	upsd.$(MAN_SECTION_CMD_SYS) \
 	upsdrvctl.$(MAN_SECTION_CMD_SYS) \
 	upslog.$(MAN_SECTION_CMD_SYS) \
 	upsmon.$(MAN_SECTION_CMD_SYS) \
-	upsrw.$(MAN_SECTION_CMD_SYS) \
+	upsrw.$(MAN_SECTION_CMD_USR) \
 	upssched.$(MAN_SECTION_CMD_SYS)
 
 INST_HTML_CLIENT_MANS = \
@@ -399,19 +399,19 @@ DIST_ALL_MAN_PAGES += $(MAN_CLIENT_PAGES_ADDON_NUT_EXE)
 endif !HAVE_WINDOWS
 
 MAN_CLIENT_PAGES_ADDON_NUT_MONITOR = \
-	NUT-Monitor-py2gtk2.$(MAN_SECTION_CMD_SYS) \
-	NUT-Monitor-py3qt5.$(MAN_SECTION_CMD_SYS) \
-	NUT-Monitor-py3qt6.$(MAN_SECTION_CMD_SYS) \
-	NUT-Monitor.$(MAN_SECTION_CMD_SYS)
+	NUT-Monitor-py2gtk2.$(MAN_SECTION_CMD_USR) \
+	NUT-Monitor-py3qt5.$(MAN_SECTION_CMD_USR) \
+	NUT-Monitor-py3qt6.$(MAN_SECTION_CMD_USR) \
+	NUT-Monitor.$(MAN_SECTION_CMD_USR)
 
 # Alias page for one text describing two commands:
-NUT-Monitor-py2gtk2.$(MAN_SECTION_CMD_SYS): NUT-Monitor.$(MAN_SECTION_CMD_SYS)
+NUT-Monitor-py2gtk2.$(MAN_SECTION_CMD_USR): NUT-Monitor.$(MAN_SECTION_CMD_USR)
 	touch $@
 
-NUT-Monitor-py3qt5.$(MAN_SECTION_CMD_SYS): NUT-Monitor.$(MAN_SECTION_CMD_SYS)
+NUT-Monitor-py3qt5.$(MAN_SECTION_CMD_USR): NUT-Monitor.$(MAN_SECTION_CMD_USR)
 	touch $@
 
-NUT-Monitor-py3qt6.$(MAN_SECTION_CMD_SYS): NUT-Monitor.$(MAN_SECTION_CMD_SYS)
+NUT-Monitor-py3qt6.$(MAN_SECTION_CMD_USR): NUT-Monitor.$(MAN_SECTION_CMD_USR)
 	touch $@
 
 if WITH_NUT_MONITOR

docs/man/NUT-Monitor.txt

@@ -1,4 +1,4 @@
-NUT-Monitor(8)
+NUT-Monitor(1)
 ==============
 
 NAME
@@ -47,9 +47,9 @@ actual Python UI client.
 
 For each individual run, the UI client can connect to a single NUT data server
 and a device on it.  This can use either anonymous read-only connections (like
-linkman:upsc[8]), or authenticated connections (see linkman:upsd.users[5])
-which can also issue commands to the driver (like linkman:upscmd[8]) and
-set supported variables (like linkman:upsrw[8]) -- propagated to the device,
+linkman:upsc[1]), or authenticated connections (see linkman:upsd.users[5])
+which can also issue commands to the driver (like linkman:upscmd[1]) and
+set supported variables (like linkman:upsrw[1]) -- propagated to the device,
 where applicable.
 
 The Python UI client can be used on a system different from the NUT data
@@ -96,9 +96,9 @@ AUTHORS
 SEE ALSO
 --------
 
-linkman:upsc[8],
-linkman:upscmd[8],
-linkman:upsrw[8],
+linkman:upsc[1],
+linkman:upscmd[1],
+linkman:upsrw[1],
 linkman:upsd.users[5]
 
 Internet resources:

docs/man/al175.txt

@@ -40,7 +40,7 @@ linkman:ups.conf[5].
 INSTANT COMMANDS
 ----------------
 
-This driver supports some extra commands (see linkman:upscmd[8]):
+This driver supports some extra commands (see linkman:upscmd[1]):
 
 *test.battery.start*::
 Start a battery test.

docs/man/bicker_ser.txt

@@ -38,7 +38,7 @@ VARIABLES
 ---------
 
 Depending on the type of your UPS unit, some of the following variables may
-be changed with linkman:upsrw[8]. If the driver can't read a variable from the
+be changed with linkman:upsrw[1]. If the driver can't read a variable from the
 UPS, it will not be made available. Whenever not explicitly stated, any variable
 can be disabled, in which case the action it performs will not be executed. To
 disable a variable, set it to an empty value.

docs/man/blazer-common.txt

@@ -156,7 +156,7 @@ endif::blazer_usb[]
 UPS COMMANDS
 ------------
 
-This driver supports some instant commands (see linkman:upscmd[8]):
+This driver supports some instant commands (see linkman:upscmd[1]):
 
 *beeper.toggle*::
 
@@ -305,7 +305,8 @@ endif::blazer_usb[]
 ifndef::blazer_usb[]
 linkman:blazer_usb[8],
 endif::blazer_usb[]
-linkman:nutupsdrv[8], linkman:upsc[8], linkman:upscmd[8], linkman:upsrw[8]
+linkman:nutupsdrv[8],
+linkman:upsc[1], linkman:upscmd[1], linkman:upsrw[1]
 
 
 Internet Resources:

docs/man/clone-outlet.txt

@@ -179,8 +179,8 @@ Arjen de Korte <[email protected]>
 SEE ALSO
 --------
 
-linkman:upscmd[8],
-linkman:upsrw[8],
+linkman:upscmd[1],
+linkman:upsrw[1],
 linkman:ups.conf[5],
 linkman:clone[8],
 linkman:nutupsdrv[8]

docs/man/clone.txt

@@ -216,8 +216,8 @@ Arjen de Korte <[email protected]>
 SEE ALSO
 --------
 
-linkman:upscmd[8],
-linkman:upsrw[8],
+linkman:upscmd[1],
+linkman:upsrw[1],
 linkman:ups.conf[5],
 linkman:clone-outlet[8],
 linkman:nutupsdrv[8]

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[8] and
-linkman:upscmd[8] commands (or equivalent graphical tool), and batchable
+It is both interactive, controllable through the linkman:upsrw[1] and
+linkman:upscmd[1] commands (or equivalent graphical tool), and batchable
 through script files.
 
 It can be configured, launched and used as any other "real" NUT driver.
@@ -141,7 +141,7 @@ This definition file, specified by the `port` argument in the example above,
 is generally named `something.dev` or `something.seq`. It contains a list of
 all valid variables and associated values (you can later use `upsrw`
 only to modify values of these variables), and has the same format as an
-linkman:upsc[8] data dump (`<varname>: <value>`). This means you can easily
+linkman:upsc[1] data dump (`<varname>: <value>`). This means you can easily
 create definition files from an existing UPS using `upsc > file.dev`.
 
 Note that the Network UPS project provides an extensive
@@ -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[8] and linkman:upscmd[8] commands.
+linkman:upsrw[1] and linkman:upscmd[1] 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[8],
-linkman:upsrw[8],
+linkman:upscmd[1],
+linkman:upsrw[1],
 linkman:ups.conf[5],
 linkman:nutupsdrv[8]
 

docs/man/failover.txt

@@ -27,7 +27,7 @@ for "primary" duty according to a set of user configurable rules and priorities.
 At any given time, `failover` designates one UPS driver as the *primary*, and
 presents its commands, variables and status to the outside world as if it were
 directly talking to that UPS. From the perspective of the clients (such as
-linkman:upsmon[8] or linkman:upsc[8]), the `failover` driver behaves like any
+linkman:upsmon[8] or linkman:upsc[1]), the `failover` driver behaves like any
 single UPS, abstracting away the underlying redundancy, and allowing for
 seamless transitioning between all monitored UPS drivers and their datasets.
 
@@ -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[8] and linkman:upsrw[8] `-w`). You
+tracking also being possible (linkman:upscmd[1] and linkman:upsrw[1] `-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,10 +281,10 @@ Sebastian Kuttnig <[email protected]>
 SEE ALSO
 --------
 
-linkman:upscmd[8],
-linkman:upsrw[8],
+linkman:upscmd[1],
+linkman:upsrw[1],
 linkman:ups.conf[5],
-linkman:upsc[8],
+linkman:upsc[1],
 linkman:upsmon[8],
 linkman:nutupsdrv[8],
 linkman:clone[8],

docs/man/genericups.txt

@@ -284,7 +284,7 @@ Start the driver with the type you want to try, e.g.:
 
         genericups -x upstype=n /dev/port
 
-Let linkman:upsd[8] sync up (watch the syslog), and then run linkman:upsc[8]
+Let linkman:upsd[8] sync up (watch the syslog), and then run linkman:upsc[1]
 to see what it found.  If the `STATUS` is correct (should be "OL" for online),
 continue to <<_step_3,Step 3>>, otherwise go back to step 1.
 

docs/man/huawei-ups2000.txt

@@ -197,7 +197,7 @@ as line power is restored.
 INSTANT COMMANDS
 ----------------
 
-This driver supports some instant commands (see linkman:upscmd[8]):
+This driver supports some instant commands (see linkman:upscmd[1]):
 
 *shutdown.stayoff*::
 After an *offdelay*, turn off the load. When line power is back,
@@ -277,7 +277,7 @@ Stop a running battery test.
 VARIABLES
 ---------
 
-This driver supports some writable runtime variables (see linkman:upsrw[8]):
+This driver supports some writable runtime variables (see linkman:upsrw[1]):
 
 **ups.beeper.status**::
 Enable or disable the UPS beeper, *disabled* or *enabled*.