Merge pull request #2796 from jimklimov/fix-docs-markup

Fix sms-brazil-protocol and sms_ser docs markup; quiesce driver service framework notifications when exiting due to bad CLI args

NEWS.adoc

@@ -113,6 +113,11 @@ https://github.com/networkupstools/nut/milestone/11
    now to report human-friendly text instead of internal enum codes. Follow-up
    to [issue #1590, PR #1777, PR #2136]
 
+ - drivers should no longer print warning messages about not-initializing the
+   notification subsystem because not running as a service when they are either
+   started explicitly to show the help message, or when their CLI arguments
+   are fatally wrong (no UPS name, no `port`, invalid trailing keywords...)
+
  - drivers, `upsd`, `upsmon`: reduce "scary noise" about failure to `fopen()`
    the PID file (which most of the time means that no previous instance of
    the daemon was running to potentially conflict with), especially useless
@@ -273,6 +278,12 @@ https://github.com/networkupstools/nut/milestone/11
    * ...should now track the fact of `assumed_LogMax` (typically when firmware
      encoding logic is wrong, and `-1` is resolved by parser). [#1512, #1040]
 
+ - snmp-ups updates:
+   * added support to monitor BayTech RPC3-NC PDUs, with `baytech-rpc3nc-mib`
+     serving same basic data points as were available in `baytech-mib.c`,
+     but checking for a different model OID subtree and different OIDs for
+     the device model information. [#2779]
+
  - Introduced a new driver concept for interaction with OS-reported hardware
    monitoring readings. Currently instantiated as `hwmon_ina219` specifically
    made for Texas Instruments INA219 chip as exposed in the Linux "hwmon"
@@ -745,10 +756,6 @@ https://github.com/networkupstools/nut/milestone/10
  - snmp-ups driver:
    * added support for Eaton EMP002 sensor for ATS16 NM2 sub-driver. [#2286]
    * mapping table updates for apc-mib sub-driver. [#2264]
-   * added support to monitor BayTech RPC3-NC PDUs, with `baytech-rpc3nc-mib`
-     serving same basic data points as were available in `baytech-mib.c`,
-     but checking for a different model OID subtree and different OIDs for
-     the device model information. [#2779]
 
  - usbhid-ups driver:
    * `arduino-hid` subdriver was enhanced from "initial bare bones" experimental

docs/Makefile.am

@@ -123,6 +123,15 @@ EXTRA_DIST += $(ALL_TXT_SRC) $(SHARED_DEPS) $(IMAGE_FILES) \
  $(IMAGE_LOGO_FILES) $(IMAGE_LOGO_FILES_JENKINS_NUT) $(CABLES_IMAGES) $(NUT_SPELL_DICT) \
  docinfo.xml common.xsl xhtml.xsl chunked.xsl asciidoc.txt asciidoc-vars.conf
 
+# NOTE: ALL_TXT_SRC does not include sms-brazil-protocol.txt because it
+# primarily includes samples of configuration files with a lot of Spanish
+# (Brazilian) words which confuse the spell-checker. Adding them to common
+# NUT_SPELL_DICT would compromise its usefulness for purely English documents.
+# FIXME: Add support for custom additional dictionaries for specific document
+# files, e.g. "something.txt.dict" if present? There is precedent and code in
+# nut-website recipes by now...
+EXTRA_DIST += sms-brazil-protocol.txt
+
 ASCIIDOC_HTML_SINGLE = user-manual.html \
 	developer-guide.html \
 	packager-guide.html \

docs/man/sms_ser.txt

@@ -15,8 +15,8 @@ SYNOPSIS
 
 NOTE: This man page only documents the hardware-specific features
 of the sms_ser driver.  For information about the core driver, see
-linkman:nutupsdrv[8], and for the technical background check in
-doc/sms-brazil-protocol.txt.
+linkman:nutupsdrv[8], and for the technical background check the
+`docs/sms-brazil-protocol.txt` file in NUT sources.
 
 NOTE: Given the proximity of this protocol to Megatec Qx family,
 this driver may later become part of `nutdrv_qx` collection.
@@ -28,7 +28,8 @@ SUPPORTED HARDWARE
 sms_ser supports only the "sms 1phase" SMS Product, as described in
 the `monofasico.xml` file delivered with the device.
 
-Other SMS protocols for their other products are not supported.
+Other SMS protocols (for their other products) are not supported by
+this driver.
 
 
 AUTHOR

docs/sms-brazil-protocol.txt

@@ -1,9 +1,14 @@
 SMS Brazil Protocols
 ====================
 
-Using the PowerView as source, there is a folder, called `protocols` inside the installed directory, e.g. `"C:\Alerta24h\SMS_Power_View\resource"`. There are 4 protocol files (`monofasico.xml`, `trifasico.xml`, `upsilon.xml` and `voltronic.xml`), and one file called `verificaProtocolo.xml`.
+Using the PowerView (accompanying UPS application for Windows) as source,
+there is a folder, called `protocols` inside the installed directory, e.g.
+`"C:\Alerta24h\SMS_Power_View\resource"`. There are 4 protocol files
+(`monofasico.xml`, `trifasico.xml`, `upsilon.xml` and `voltronic.xml`),
+and one file called `verificaProtocolo.xml`.
 
-The file `verificaProtocolo.xml` has serial/USB commands to be sent, to detect the UPS device.
+The file `verificaProtocolo.xml` has serial/USB commands to be sent,
+to detect the UPS device.
 
 The file contents are:
 

drivers/main.c

@@ -131,6 +131,7 @@ static int nut_debug_level_protocol = -1;
 /* everything else */
 static char	*pidfn = NULL;
 static int	help_only = 0,
+		cli_args_accepted = 0,
 		dump_data = 0; /* Store the update_count requested */
 #endif /* DRIVERS_MAIN_WITHOUT_MAIN */
 
@@ -796,7 +797,7 @@ int do_loop_shutdown_commands(const char *sdcmds, char **cmdused) {
 			"too deeply nested, this seems to be either "
 			"a NUT programming error or a mis-configuration "
 			"of your 'sdcommands' setting", NUT_STRARG(upsname));
-	}	
+	}
 
 	if (cmdused) {
 		if (*cmdused)
@@ -1833,6 +1834,15 @@ static void exit_cleanup(void)
 	dstate_setinfo("driver.state", "cleanup.exit");
 
 	if (!dump_data && !help_only) {
+		if (!cli_args_accepted && !getenv("NUT_QUIET_INIT_UPSNOTIFY")) {
+			/* Default to not yelling about notification method support (or
+			 * lack thereof) when CLI arguments did not get handled early on.
+			 * Set envvar to cause "upsnotify_report_verbosity = 1" in
+			 * common.c::upsnotify() (if still applicable; if already
+			 * reported - oh well).
+			 */
+			setenv("NUT_QUIET_INIT_UPSNOTIFY", "yes", 0);
+		}
 		upsnotify(NOTIFY_STATE_STOPPING, "exit_cleanup()");
 	}
 
@@ -2333,6 +2343,7 @@ int main(int argc, char **argv)
 			"Try -h for help.");
 	}
 
+	cli_args_accepted = 1;
 	assign_debug_level();
 
 	new_uid = get_user_pwent(user);