Refactor suggest_doc_links() into suggest_doc_links_CMD_SYS() and suggest_doc_links_CMD_USR() [#2977]

Signed-off-by: Jim Klimov <[email protected]>

Author: jimklimov

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
@@ -293,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`)

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/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
 ~~~~~~~~~

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 */