diff --git a/NEWS.adoc b/NEWS.adoc index 9b63359ea2..f68c35c921 100644 --- a/NEWS.adoc +++ b/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`) diff --git a/UPGRADING.adoc b/UPGRADING.adoc index 66544158e5..194818c13b 100644 --- a/UPGRADING.adoc +++ b/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] diff --git a/clients/upsc.c b/clients/upsc.c index b9f86871c6..198e48c6cd 100644 --- a/clients/upsc.c +++ b/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) diff --git a/clients/upscmd.c b/clients/upscmd.c index 2c5fe6ec03..26c657079b 100644 --- a/clients/upscmd.c +++ b/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) diff --git a/clients/upslog.c b/clients/upslog.c index c81d7cb7e9..1101b72a68 100644 --- a/clients/upslog.c +++ b/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); } diff --git a/clients/upsmon.c b/clients/upsmon.c index 9c45dffba8..50542db2ef 100644 --- a/clients/upsmon.c +++ b/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); } diff --git a/clients/upsrw.c b/clients/upsrw.c index dc76c9336b..808284b957 100644 --- a/clients/upsrw.c +++ b/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) diff --git a/clients/upssched.c b/clients/upssched.c index d24fed4c73..bde2ed590d 100644 --- a/clients/upssched.c +++ b/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); } diff --git a/common/common-nut_version.c b/common/common-nut_version.c index 419e97bdca..8230ff11cc 100644 --- a/common/common-nut_version.c +++ b/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); +} diff --git a/docs/config-notes.txt b/docs/config-notes.txt index 3fff30e6eb..3169c5e866 100644 --- a/docs/config-notes.txt +++ b/docs/config-notes.txt @@ -421,7 +421,7 @@ probably misconfigured during the <> step. If you reconfigure the driver, use `upsdrvctl stop` to stop it, then start it again as shown in the <> 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], <> Startup scripts diff --git a/docs/man/Makefile.am b/docs/man/Makefile.am index f8d4471128..efa0abdd96 100644 --- a/docs/man/Makefile.am +++ b/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 diff --git a/docs/man/NUT-Monitor.txt b/docs/man/NUT-Monitor.txt index edc0535975..1af04de768 100644 --- a/docs/man/NUT-Monitor.txt +++ b/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: diff --git a/docs/man/al175.txt b/docs/man/al175.txt index eb8a7efc26..989c5462d2 100644 --- a/docs/man/al175.txt +++ b/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. diff --git a/docs/man/bicker_ser.txt b/docs/man/bicker_ser.txt index bebecceef7..53ac80e777 100644 --- a/docs/man/bicker_ser.txt +++ b/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. diff --git a/docs/man/blazer-common.txt b/docs/man/blazer-common.txt index 54daba0b66..544d2f5a56 100644 --- a/docs/man/blazer-common.txt +++ b/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: diff --git a/docs/man/clone-outlet.txt b/docs/man/clone-outlet.txt index 91950f92f9..890a75df2b 100644 --- a/docs/man/clone-outlet.txt +++ b/docs/man/clone-outlet.txt @@ -179,8 +179,8 @@ Arjen de Korte SEE ALSO -------- -linkman:upscmd[8], -linkman:upsrw[8], +linkman:upscmd[1], +linkman:upsrw[1], linkman:ups.conf[5], linkman:clone[8], linkman:nutupsdrv[8] diff --git a/docs/man/clone.txt b/docs/man/clone.txt index 52a25d7842..8a9d975995 100644 --- a/docs/man/clone.txt +++ b/docs/man/clone.txt @@ -216,8 +216,8 @@ Arjen de Korte 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] diff --git a/docs/man/dummy-ups.txt b/docs/man/dummy-ups.txt index 6d86195657..6313d250df 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[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 (`: `). This means you can easily +linkman:upsc[1] data dump (`: `). 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] diff --git a/docs/man/failover.txt b/docs/man/failover.txt index 7fe6d94b90..27806446ea 100644 --- a/docs/man/failover.txt +++ b/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 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], diff --git a/docs/man/genericups.txt b/docs/man/genericups.txt index f3d0b1c5df..998a601028 100644 --- a/docs/man/genericups.txt +++ b/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. diff --git a/docs/man/huawei-ups2000.txt b/docs/man/huawei-ups2000.txt index 5282e82cb1..b68f9760b7 100644 --- a/docs/man/huawei-ups2000.txt +++ b/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*. diff --git a/docs/man/index.txt b/docs/man/index.txt index 88ba105573..845984554c 100644 --- a/docs/man/index.txt +++ b/docs/man/index.txt @@ -30,21 +30,21 @@ Configuration files - linkman:upsset.conf[5] - linkman:upsstats.html[5] -Daemons -~~~~~~~ +Server and Client Daemons +~~~~~~~~~~~~~~~~~~~~~~~~~ - linkman:upsd[8] - linkman:upsmon[8] - linkman:upssched[8] - linkman:upslog[8] -Clients commands -~~~~~~~~~~~~~~~~ +End-User Clients and Commands +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- linkman:upsc[8] -- linkman:upscmd[8] -- linkman:upsrw[8] -- linkman:NUT-Monitor[8] +- linkman:upsc[1] +- linkman:upscmd[1] +- linkman:upsrw[1] +- linkman:NUT-Monitor[1] Configuration commands ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/man/nut.txt b/docs/man/nut.txt index 249b1e6e3a..44f0be7a5d 100644 --- a/docs/man/nut.txt +++ b/docs/man/nut.txt @@ -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[8] is a command-line client for anonymous read-only access, +* linkman:upsc[1] 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[8] is a GUI client for read-only or read-write access. +* linkman:NUT-Monitor[1] 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[8] +Other clients, whether delivered by NUT project (linkman:NUT-Monitor[1] 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/nutdrv_qx.txt b/docs/man/nutdrv_qx.txt index 270f7feac9..a7ffb82717 100644 --- a/docs/man/nutdrv_qx.txt +++ b/docs/man/nutdrv_qx.txt @@ -74,14 +74,14 @@ This value is truncated to units of 60 seconds. + Note that a value below 3 minutes, may cause earlier firmware versions to not switch on automatically, so it defaults to 3 minutes (i.e. 180 seconds). + -This option provides a default value for *ups.delay.start* that will then be used by the driver in the automatic shutdown sequence (i.e. calling the driver with the *-k* option, calling linkman:upsdrvctl[8] with the *shutdown* option or when the +FSD+ flag is set and linkman:upsmon[8] enters its shutdown sequence): however you can change this value `on the fly' for the actual session, only for the use with instant commands, setting *ups.delay.start* with linkman:upsrw[8]. +This option provides a default value for *ups.delay.start* that will then be used by the driver in the automatic shutdown sequence (i.e. calling the driver with the *-k* option, calling linkman:upsdrvctl[8] with the *shutdown* option or when the +FSD+ flag is set and linkman:upsmon[8] enters its shutdown sequence): however you can change this value `on the fly' for the actual session, only for the use with instant commands, setting *ups.delay.start* with linkman:upsrw[1]. *offdelay =* 'value':: Time to wait before shutting down the UPS (seconds). This value is truncated to units of 6 seconds (less than 60 seconds) or 60 seconds (more than 60 seconds). Defaults to 30 seconds. + -This option provides a default value for *ups.delay.shutdown* that will then be used by the driver in the automatic shutdown sequence (i.e. calling the driver with the *-k* option, calling linkman:upsdrvctl[8] with the *shutdown* option or when the +FSD+ flag is set and linkman:upsmon[8] enters its shutdown sequence): however you can change this value "on the fly" for the actual session, only for the use with instant commands, setting *ups.delay.shutdown* with linkman:upsrw[8]. +This option provides a default value for *ups.delay.shutdown* that will then be used by the driver in the automatic shutdown sequence (i.e. calling the driver with the *-k* option, calling linkman:upsdrvctl[8] with the *shutdown* option or when the +FSD+ flag is set and linkman:upsmon[8] enters its shutdown sequence): however you can change this value "on the fly" for the actual session, only for the use with instant commands, setting *ups.delay.shutdown* with linkman:upsrw[1]. *stayoff*:: If you set stayoff in linkman:ups.conf[5] when FSD arises the UPS will call a *shutdown.stayoff* shutting down after *ups.delay.shutdown* seconds and won't return (see <<_known_problems,KNOWN PROBLEMS>>), otherwise (standard behaviour) the UPS will call *shutdown.return* shutting down after *ups.delay.shutdown* seconds and then turn on after *ups.delay.start* seconds (if mains meanwhile returned). @@ -214,7 +214,7 @@ MASTERGUARD PROTOCOL *slave_addr =* 'value':: Make the claim function verify it's talking to the specified 'slave address' (*ups.id*). Safeguard against talking to the wrong one of several identical UPSes on the same USB bus. -Note that when changing *ups.id* (through linkman:upsrw[8]) the driver will continue to talk to the UPS with the new 'slave address', but won't claim it again on restart until the *slave_addr* parameter is adjusted. +Note that when changing *ups.id* (through linkman:upsrw[1]) the driver will continue to talk to the UPS with the new 'slave address', but won't claim it again on restart until the *slave_addr* parameter is adjusted. INNOVART31, INNOVART33, Q1, Q2, Q6 PROTOCOLS @@ -463,7 +463,7 @@ This subdriver, meant to be used with the 'megatec' protocol, does *not* support UPS COMMANDS ------------ -This driver supports some instant commands (see linkman:upscmd[8]): +This driver supports some instant commands (see linkman:upscmd[1]): *beeper.toggle*:: Toggle the UPS beeper. @@ -670,7 +670,7 @@ It no longer defaults to 0 minutes but to 3 minutes (i.e. 180 seconds) for compa *battnumb*:: This option has been renamed to *battery_number*. -The following options are no longer supported by this driver, you can now change them more conveniently "on the fly" calling linkman:upsrw[8] with the appropriate NUT variable -- provided that your UPS supports them. +The following options are no longer supported by this driver, you can now change them more conveniently "on the fly" calling linkman:upsrw[1] with the appropriate NUT variable -- provided that your UPS supports them. [horizontal] *battpacks*:: -> *battery.packs* @@ -883,11 +883,11 @@ linkman:blazer_ser[8], linkman:blazer_usb[8], linkman:nutupsdrv[8], linkman:ups.conf[5], -linkman:upsc[8], -linkman:upscmd[8], +linkman:upsc[1], +linkman:upscmd[1], linkman:upsdrvctl[8], linkman:upsmon[8], -linkman:upsrw[8] +linkman:upsrw[1] Internet Resources: diff --git a/docs/man/nutupsdrv.txt b/docs/man/nutupsdrv.txt index 55b47ae38f..372c97aa37 100644 --- a/docs/man/nutupsdrv.txt +++ b/docs/man/nutupsdrv.txt @@ -40,7 +40,7 @@ systems attached must be turned off to ensure a proper reboot when power returns. In the third mode, using *-d*, the driver will exit after some update loops, -dumping the data tree (in linkman:upsc[8]-like format) to `stdout`. +dumping the data tree (in linkman:upsc[1]-like format) to `stdout`. This can be useful to complement the linkman:nut-scanner[8] to discover devices, along with in-depth data. @@ -83,7 +83,7 @@ output. More often than not, if you just pick a level, the output may be either too limited or too verbose to be of any use. *-d* 'update_count':: -Dump the data tree (in linkman:upsc[8]-like format) to `stdout` after running +Dump the data tree (in linkman:upsc[1]-like format) to `stdout` after running the driver update loop for the specified 'update_count' times and exit. + By default this prevents the driver process from backgrounding after startup. @@ -206,7 +206,7 @@ Information about the startup process is printed to `stdout` and/or `stderr`. Additional messages after that point are only available in the syslog, unless the driver remains in foreground (e.g. due to raised debugging verbosity). -After linkman:upsd[8] starts, the UPS clients such as linkman:upsc[8] can +After linkman:upsd[8] starts, the UPS clients such as linkman:upsc[1] can be used to query the status of an UPS. PROGRAM CONTROL @@ -279,9 +279,9 @@ Server: Clients: ~~~~~~~~ -- linkman:upsc[8] -- linkman:upscmd[8] -- linkman:upsrw[8] +- linkman:upsc[1] +- linkman:upscmd[1] +- linkman:upsrw[1] - linkman:upslog[8] - linkman:upsmon[8] diff --git a/docs/man/oneac.txt b/docs/man/oneac.txt index 50e504a190..aaf477cedc 100644 --- a/docs/man/oneac.txt +++ b/docs/man/oneac.txt @@ -45,8 +45,8 @@ Change shutdown delay time from 0 second default. INSTANT COMMANDS ---------------- -This driver supports the following Instant Commands. -(See linkman:upscmd[8]) +This driver supports the following Instant Commands +(see linkman:upscmd[1]): All UPS units ~~~~~~~~~~~~~ @@ -104,7 +104,7 @@ Mutes the UPS beeper/buzzer for the current alarm condition(s). Writable Variables ------------------ -See linkman:upsrw[8] to see what variables are writable for the UPS. +See linkman:upsrw[1] to see what variables are writable for the UPS. NOTE: If your UPS supports writing `battery.runtime.low`, the new set value is to be entered in minutes (up to '99') but the reported value is reported diff --git a/docs/man/powerman-pdu.txt b/docs/man/powerman-pdu.txt index 2641cbe66b..0b3a63b17b 100644 --- a/docs/man/powerman-pdu.txt +++ b/docs/man/powerman-pdu.txt @@ -39,7 +39,7 @@ prerequisites and using `configure --with-powerman=yes`. UPS COMMANDS ------------ -The following instant commands (see linkman:upscmd[8]) are available for each +The following instant commands (see linkman:upscmd[1]) are available for each outlet of the PDU, with *X* standing for the outlet number: *outlet.X.load.on*:: diff --git a/docs/man/powerpanel.txt b/docs/man/powerpanel.txt index 8e86742545..7636609129 100644 --- a/docs/man/powerpanel.txt +++ b/docs/man/powerpanel.txt @@ -60,7 +60,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. *input.transfer.high*:: diff --git a/docs/man/safenet.txt b/docs/man/safenet.txt index 62ca249eb6..3675376c4e 100644 --- a/docs/man/safenet.txt +++ b/docs/man/safenet.txt @@ -49,7 +49,7 @@ Time to wait before shutting down the UPS (seconds). Defaults to 30 seconds. INSTANT COMMANDS ---------------- -This driver supports some instant commands (see linkman:upscmd[8]): +This driver supports some instant commands (see linkman:upscmd[1]): *test.battery.start*:: Start UPS self test diff --git a/docs/man/socomec_jbus.txt b/docs/man/socomec_jbus.txt index 46ec4775ae..287516108b 100644 --- a/docs/man/socomec_jbus.txt +++ b/docs/man/socomec_jbus.txt @@ -92,7 +92,7 @@ This driver does not (yet?) support sending commands to the UPS. VARIABLES --------- -This driver does not support writable runtime variables (see linkman:upsrw[8]): +This driver does not support writable runtime variables (see linkman:upsrw[1]) for the same reasons. Both should be trivial to implement, but since I've already found one or two inconsistencies in the documentation, I'm withholding from trying them. diff --git a/docs/man/tripplite_usb.txt b/docs/man/tripplite_usb.txt index 4bdb18fdda..8dda6e82aa 100644 --- a/docs/man/tripplite_usb.txt +++ b/docs/man/tripplite_usb.txt @@ -68,7 +68,8 @@ include::nut_usb_addvars.txt[] Select a specific UPS by its unique UPS ID. The argument is a regular expression that must match the UPS ID string. This allows for precise identification of UPS devices when multiple devices of the same make and model are connected. -See below regarding how to read and write the ups id (unit id) using linkman:upsrw[8]. +See below regarding how to read and write the ups id (unit id) using +linkman:upsrw[1]. [NOTE] @@ -80,7 +81,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[8] output only lists +linkmanext:lsusb[8]. The `ups.model` in the linkman:upsc[1] output only lists the name after `TRIPP LITE`, so to match a 'SMART2200RMXL2U', you could use the regex like `.*SMART2200.*`. @@ -114,19 +115,19 @@ RUNTIME VARIABLES *ups.delay.shutdown*:: This variable is the same as the 'offdelay' setting, but it can be -changed at runtime by linkman:upsrw[8]. +changed at runtime by linkman:upsrw[1]. *ups.id*:: Some SMARTPRO models feature an Unit ID (ups.id) that can be set and retrieved. If your UPS supports this feature, this variable will be listed in -the output of linkman:upsrw[8]. +the output of linkman:upsrw[1]. *outlet.1.switch*:: Some Tripp Lite units have a switchable outlet (usually outlet #1) which can be turned on and off by writing '1' or '0', respectively, -to `outlet.1.switch` with linkman:upsrw[8]. +to `outlet.1.switch` with linkman:upsrw[1]. + If your unit has multiple switchable outlets, substitute the outlet number for '1' in the variable name. Be sure to test this first -- @@ -155,7 +156,7 @@ Some of the SMART*2U models have a configurable Unit ID number, and you can now use the `upsid` config argument to uniquely specify which UPS a given driver instance should control. This allows for precise identification of UPS devices when multiple devices are connected. To retrieve or set the -`upsid`, you can use the linkman:upsrw[8] utility. +`upsid`, you can use the linkman:upsrw[1] utility. AUTHORS ------- diff --git a/docs/man/ups.conf.txt b/docs/man/ups.conf.txt index d083b091af..cf7b87931c 100644 --- a/docs/man/ups.conf.txt +++ b/docs/man/ups.conf.txt @@ -284,7 +284,7 @@ Optional. This allows you to request `driver.killpower` instant command, to immediately call the driver-specific default implementation of `upsdrv_shutdown()` method, for same effect as when a NUT driver is started with `-k` command-line flag. This option can be toggled with -linkman:upsrw[8] as `driver.flag.allow_killpower` during run-time. +linkman:upsrw[1] as `driver.flag.allow_killpower` during run-time. *desc*:: @@ -442,7 +442,7 @@ Each driver looks up its section and uses that to configure itself. linkman:upsd[8] learns about which UPSes are installed on this system by reading this file. If this system is called "doghouse" and you have defined a UPS in your *ups.conf* called "snoopy", then you can monitor it -from linkman:upsc[8] or similar as "snoopy@doghouse". +from linkman:upsc[1] or similar as "snoopy@doghouse". SEE ALSO -------- diff --git a/docs/man/upsc.txt b/docs/man/upsc.txt index f63b101252..c357fc47a2 100644 --- a/docs/man/upsc.txt +++ b/docs/man/upsc.txt @@ -1,4 +1,4 @@ -UPSC(8) +UPSC(1) ======= NAME diff --git a/docs/man/upscli_init_default_connect_timeout.txt b/docs/man/upscli_init_default_connect_timeout.txt index cfeedb7f79..d191b16112 100644 --- a/docs/man/upscli_init_default_connect_timeout.txt +++ b/docs/man/upscli_init_default_connect_timeout.txt @@ -23,7 +23,7 @@ DESCRIPTION The *upscli_init_default_connect_timeout()* function initializes upsclient module aspect of default connection timeout for linkman:upscli_connect[3], which -may be important when e.g. linkman:upsc[8] scripting or linkman:upsmon[8] +may be important when e.g. linkman:upsc[1] scripting or linkman:upsmon[8] configuration refers to unresponsive hosts, or when the host name resolution lags, etc. By default, linkman:upscli_connect[3] blocks indefinitely in its attempts to connect (or until the system transport layer interrupts diff --git a/docs/man/upscmd.txt b/docs/man/upscmd.txt index a618c2237f..2a501dc50b 100644 --- a/docs/man/upscmd.txt +++ b/docs/man/upscmd.txt @@ -1,4 +1,4 @@ -UPSCMD(8) +UPSCMD(1) ========= NAME @@ -128,7 +128,7 @@ It involves magic cookies. SEE ALSO -------- -linkman:upsd[8], linkman:upsrw[8] +linkman:upsd[8], linkman:upsrw[1] Internet resources: ~~~~~~~~~~~~~~~~~~~ diff --git a/docs/man/upsd.txt b/docs/man/upsd.txt index 3c42af28dd..14ac5874be 100644 --- a/docs/man/upsd.txt +++ b/docs/man/upsd.txt @@ -191,9 +191,9 @@ SEE ALSO Clients: ~~~~~~~~ -- linkman:upsc[8] -- linkman:upscmd[8] -- linkman:upsrw[8] +- linkman:upsc[1] +- linkman:upscmd[1] +- linkman:upsrw[1] - linkman:upslog[8] - linkman:upsmon[8] diff --git a/docs/man/upslog.txt b/docs/man/upslog.txt index a1499134c9..b6e3e78ba7 100644 --- a/docs/man/upslog.txt +++ b/docs/man/upslog.txt @@ -215,8 +215,8 @@ linkman:upsd[8] Clients: ~~~~~~~~ -linkman:upsc[8], linkman:upscmd[8], -linkman:upsrw[8], linkman:upsmon[8], linkman:upssched[8] +linkman:upsc[1], linkman:upscmd[1], +linkman:upsrw[1], linkman:upsmon[8], linkman:upssched[8] Internet resources: ~~~~~~~~~~~~~~~~~~~ diff --git a/docs/man/upsmon.txt b/docs/man/upsmon.txt index 521946b0dd..c72351b40f 100644 --- a/docs/man/upsmon.txt +++ b/docs/man/upsmon.txt @@ -652,8 +652,8 @@ linkman:upsd[8] Clients: ~~~~~~~~ -linkman:upsc[8], linkman:upscmd[8], -linkman:upsrw[8], linkman:upsmon[8] +linkman:upsc[1], linkman:upscmd[1], +linkman:upsrw[1], linkman:upssched[8] CGI programs: ~~~~~~~~~~~~~ diff --git a/docs/man/upsrw.txt b/docs/man/upsrw.txt index 275a469588..abc4f1d42c 100644 --- a/docs/man/upsrw.txt +++ b/docs/man/upsrw.txt @@ -1,4 +1,4 @@ -UPSRW(8) +UPSRW(1) ======== NAME @@ -140,7 +140,7 @@ confusing. SEE ALSO -------- -linkman:upsd[8], linkman:upscmd[8] +linkman:upsd[8], linkman:upscmd[1] Internet resources: ~~~~~~~~~~~~~~~~~~~ diff --git a/docs/man/upsset.cgi.txt b/docs/man/upsset.cgi.txt index 8c62d2dba2..8c445342c5 100644 --- a/docs/man/upsset.cgi.txt +++ b/docs/man/upsset.cgi.txt @@ -38,7 +38,7 @@ If your UPS doesn't support any read/write variables, there will be nothing to do on this page. Setting values in read/write variables can also be done from the command -line with linkman:upsrw[8]. +line with linkman:upsrw[1]. INSTANT COMMANDS ---------------- @@ -65,7 +65,7 @@ you do it too quickly or slowly, you have to wait at least 3 seconds but not 15 seconds again. You can also invoke instant commands from the command line with -linkman:upscmd[8]. +linkman:upscmd[1]. ACCESS CONTROL -------------- diff --git a/docs/nut-versioning.adoc b/docs/nut-versioning.adoc index 53403c5dff..78fff7beb2 100644 --- a/docs/nut-versioning.adoc +++ b/docs/nut-versioning.adoc @@ -419,9 +419,11 @@ common-nut_version.c It is used from a number of other methods, such as `print_banner_once()`, `nut_report_config_flags()`, and so ends up in version reports of programs via their `help()`/`usage()` methods. -* Method `suggest_doc_links()` prepares a uniform bit of text for driver and - tool programs to report in their `help()`/`usage()` methods, to refer to - their manual page under the `NUT_WEBSITE_BASE`. +* Methods `suggest_doc_links_CMD_SYS()` and `suggest_doc_links_CMD_USR()` help + by preparing a uniform bit of text for driver and tool programs to report in + their `help()`/`usage()` methods, to refer to their locally delivered manual + page (if documentation was built) and an on-line copy under the + `NUT_WEBSITE_BASE`. Man pages ~~~~~~~~~ diff --git a/docs/user-manual.txt b/docs/user-manual.txt index f4c8fbc733..cffeac8d24 100644 --- a/docs/user-manual.txt +++ b/docs/user-manual.txt @@ -72,7 +72,7 @@ This software has been reported to run on: * Since NUT v2.8.1, there is an on-going effort to integrate older platform development of NUT for Windows into the main code base -- allowing to run the whole stack of NUT drivers, data server and same clients as on POSIX - platforms (for fancy GUI clients, see linkman:NUT-Monitor[8] or third-party + platforms (for fancy GUI clients, see linkman:NUT-Monitor[1] or third-party projects). Still, as of NUT release v2.8.3, installation is complicated and there are other known imperfections (not all WIN32 code has equivalents to POSIX); for current details see NUT issues tracked on GitHub under diff --git a/drivers/main.c b/drivers/main.c index 2f18d058ca..a29da76ac9 100644 --- a/drivers/main.c +++ b/drivers/main.c @@ -297,7 +297,7 @@ static void help_msg(void) upsdrv_help(); - printf("\n%s", suggest_doc_links(progname, "ups.conf")); + printf("\n%s", suggest_doc_links_CMD_SYS(progname, "ups.conf")); } #endif /* DRIVERS_MAIN_WITHOUT_MAIN */ diff --git a/drivers/upsdrvctl.c b/drivers/upsdrvctl.c index 645a8cc0ef..092a42a578 100644 --- a/drivers/upsdrvctl.c +++ b/drivers/upsdrvctl.c @@ -1281,7 +1281,7 @@ static void help(const char *arg_progname) printf(" Fields: UPSNAME UPSDRV RUNNING PF_PID S_RESPONSIVE S_PID S_STATUS\n"); printf(" (PF_* = according to PID file, if any; S_* = via socket protocol)\n"); - printf("\n%s", suggest_doc_links(arg_progname, "ups.conf")); + printf("\n%s", suggest_doc_links_CMD_SYS(arg_progname, "ups.conf")); #if (defined(WITH_SOLARIS_SMF) && WITH_SOLARIS_SMF) || (defined(HAVE_SYSTEMD) && HAVE_SYSTEMD) printf("NOTE: On this system you should prefer upsdrvsvcctl and nut-driver-enumerator\n"); #endif diff --git a/include/common.h b/include/common.h index 3cd6f226f1..adb8f3c539 100644 --- a/include/common.h +++ b/include/common.h @@ -227,7 +227,8 @@ const char *describe_NUT_VERSION_once(void); * Optional "progconf" allows to suggest config file(s) to study as well. * NOTE: the string in buffer starts with text and ends with one EOL char. */ -const char *suggest_doc_links(const char *progname, const char *progconf); +const char *suggest_doc_links_CMD_SYS(const char *progname, const char *progconf); +const char *suggest_doc_links_CMD_USR(const char *progname, const char *progconf); /* Based on NUT_QUIET_INIT_BANNER envvar (present and empty or "true") * hide the NUT tool name+version banners; show them by default */ diff --git a/scripts/Aix/nut-aix.spec.in b/scripts/Aix/nut-aix.spec.in index 1302160dcf..d96034638c 100644 --- a/scripts/Aix/nut-aix.spec.in +++ b/scripts/Aix/nut-aix.spec.in @@ -308,9 +308,9 @@ exit 0 %{_libdir}/libupsclient.so* %{_mandir}/man5/upsmon.conf.5 %{_mandir}/man5/upssched.conf.5 -%{_mandir}/man8/upsc.8 -%{_mandir}/man8/upscmd.8 -%{_mandir}/man8/upsrw.8 +%{_mandir}/man1/upsc.1 +%{_mandir}/man1/upscmd.1 +%{_mandir}/man1/upsrw.1 %{_mandir}/man8/upslog.8 %{_mandir}/man8/upsmon.8 %{_mandir}/man8/upssched.8 diff --git a/scripts/Windows/wininit.c b/scripts/Windows/wininit.c index f305b3a955..40f8d4c013 100644 --- a/scripts/Windows/wininit.c +++ b/scripts/Windows/wininit.c @@ -723,7 +723,7 @@ static void help(const char *arg_progname) printf(" -V Display NUT version and exit\n"); printf(" -h Display this help and exit\n"); /* also /? but be hush about the one slash */ - printf("\n%s", suggest_doc_links( + printf("\n%s", suggest_doc_links_CMD_SYS( "nut.exe" /*arg_progname*/, "nut.conf, ups.conf, upsmon.conf, upsd.conf and upsd.users" )); diff --git a/server/pipedebug.c b/server/pipedebug.c index ef1c4a4f8a..0dde456ca6 100644 --- a/server/pipedebug.c +++ b/server/pipedebug.c @@ -139,7 +139,7 @@ int main(int argc, char **argv) fprintf(stderr, " %s apcsmart-com1\n", argv[0]); - fprintf(stderr, "\n%s", suggest_doc_links(prog, NULL)); + fprintf(stderr, "\n%s", suggest_doc_links_CMD_SYS(prog, NULL)); exit(EXIT_SUCCESS); } diff --git a/server/sockdebug.c b/server/sockdebug.c index 2db400db4b..22e5ecc9a9 100644 --- a/server/sockdebug.c +++ b/server/sockdebug.c @@ -145,7 +145,7 @@ int main(int argc, char **argv) argv[0]); fprintf(stderr, " for socket files placed in the standard location\n"); - fprintf(stderr, "\n%s", suggest_doc_links(prog, NULL)); + fprintf(stderr, "\n%s", suggest_doc_links_CMD_SYS(prog, NULL)); exit(EXIT_SUCCESS); } diff --git a/server/upsd.c b/server/upsd.c index abc5a28e47..c977e17776 100644 --- a/server/upsd.c +++ b/server/upsd.c @@ -1825,7 +1825,7 @@ static void help(const char *arg_progname) nut_report_config_flags(); - printf("\n%s", suggest_doc_links(progname, "ups.conf, upsd.conf and upsd.users")); + printf("\n%s", suggest_doc_links_CMD_SYS(progname, "ups.conf, upsd.conf and upsd.users")); exit(EXIT_SUCCESS); } diff --git a/tools/nut-scanner/Makefile.am b/tools/nut-scanner/Makefile.am index 9e5819bc34..6561563fdb 100644 --- a/tools/nut-scanner/Makefile.am +++ b/tools/nut-scanner/Makefile.am @@ -96,7 +96,7 @@ libnutscan_la_LDFLAGS += @NETLIBS_GETADDRS@ # object .so names would differ) # # libnutscan version information -libnutscan_la_LDFLAGS += -version-info 4:0:0 +libnutscan_la_LDFLAGS += -version-info 5:0:0 # libnutscan exported symbols regex # WARNING: Since the library includes parts of libcommon (as much as needed diff --git a/tools/nut-scanner/nut-scanner.c b/tools/nut-scanner/nut-scanner.c index faa696bc5c..c6920c9b50 100644 --- a/tools/nut-scanner/nut-scanner.c +++ b/tools/nut-scanner/nut-scanner.c @@ -1155,7 +1155,7 @@ static void show_usage(const char *arg_progname) printf(" -q, --quiet: Display only scan result. No information on currently scanned bus is displayed.\n"); printf(" -D, --nut_debug_level: Raise the debugging level. Use this multiple times to see more details.\n"); - printf("\n%s", suggest_doc_links(arg_progname, "ups.conf")); + printf("\n%s", suggest_doc_links_CMD_SYS(arg_progname, "ups.conf")); } int main(int argc, char *argv[]) diff --git a/tools/nutconf/nutconf-cli.cpp b/tools/nutconf/nutconf-cli.cpp index f4a83c67f2..d3556ad721 100644 --- a/tools/nutconf/nutconf-cli.cpp +++ b/tools/nutconf/nutconf-cli.cpp @@ -209,7 +209,7 @@ void Usage::print(const std::string & bin) { std::cerr /* << std::endl // last line of s_text is blank */ - << suggest_doc_links(bin.c_str(), nullptr); + << suggest_doc_links_CMD_SYS(bin.c_str(), nullptr); /* Method output brings its own endl */ }