dummy-ups.txt : text and formatting revised to be clearer to the unin…

…itiated

docs/man/dummy-ups.txt

@@ -8,67 +8,79 @@ dummy-ups - Driver for multi-purpose UPS emulation
 NOTE
 ----
 This man page only documents the specific features of the
-dummy-ups driver.  For information about the core driver, see
+*dummy-ups* driver.  For information about the core driver, see
 linkman:nutupsdrv[8].
 
 DESCRIPTION
 -----------
 This program is a multi-purpose UPS emulation tool.
-Its behavior depends on the running mode:
+Its behavior depends on the running mode: "dummy" or "repeater".
 
 Dummy Mode
 ~~~~~~~~~~
 
-*dummy-ups* looks like a standard 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 through script files. It can be
-configured, launched and used as any other real driver.  This mode is mostly
-useful for development and testing purposes.
+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
+through script files. It can be configured, launched and used as any other
+"real" NUT driver. This mode is mostly useful for development and testing
+purposes.
 
 Repeater Mode
 ~~~~~~~~~~~~~
 
-*dummy-ups* acts as a NUT client, simply forwarding data. This can be useful
-for supervision purposes. This can also allow some load sharing between several
-UPS instances, using a point-to-point communication with the UPS.
+In this mode, *dummy-ups* acts as a NUT client, simply forwarding data.
+This can be useful for supervision purposes. This mode can also allow some
+load sharing between several `upsd` instances communicating with ultimate
+NUT clients, wit a "central" one using a point-to-point communication with
+the UPS. This arrangement can also help with networked UPSes, whose network
+management cards can be overwhelmed with a farm of servers directly polling
+SNMP or other protocols every few seconds.
 
 IMPLEMENTATION
 --------------
 
-The port specification depends on the running mode, and allows the driver to
-select the right mode.
+The `port` specification in `ups.conf` depends on the running mode, and allows
+the driver to select the right mode of operation.
 
 Dummy Mode
 ~~~~~~~~~~
 
-Port is a definition file name for *dummy-ups*. This can either
-be an absolute or a relative path name. In the latter case the NUT
-sysconfig directory (ie /etc/nut, /usr/local/ups/etc, ...) is prepended.
+In this context, `port` in the `ups.conf` block defines a file name for the
+*dummy-ups* to read data from. This can either be an absolute or a relative
+path name. In the latter case the NUT sysconfig directory (i.e. `/etc/nut`,
+`/usr/local/ups/etc`, ...) is prepended.
 
 For instance:
 
 	[dummy]
 		driver = dummy-ups
-		port = evolution500.dev
+		port = evolution500.seq
 		desc = "dummy-ups in dummy mode"
 
-This file is generally named "something.dev". It contains a list of all
-valid data and associated values, and has the same format as an linkman:upsc[8]
-dump (<varname>: <value>). So you can easily create definition
-files from an existing UPS using "upsc > file.dev".
+This file 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] dump (`<varname>: <value>`). So you can easily create
+definition files from an existing UPS using `upsc > file.dev`.
+
 It can also be empty, in which case only a basic set of data is available:
-device.*, driver.*, ups.mfr, ups.model, ups.status
+`device.*`, `driver.*`, `ups.mfr`, `ups.model`, `ups.status` as filled by
+the driver itself.
 
-Samples definition files are available in the "data" directory of the nut source
-tree, and generally in the sysconfig directory of your system distribution.
+Some sample definition files are available in the `data` directory of the
+NUT source tree, and generally in the sysconfig directory of your system
+distribution.
 
 Since *dummy-ups* will loop on reading this file, you can dynamically modify
-it to interact with the driver. This will avoid message spam into your
-system log files, if you are using NUT default configuration.
+it with some external process to "interact" with the driver. This will avoid
+message spam into your system log files, if you are using NUT default
+configuration.
 
-You can also use the "TIMER <seconds>" instruction to create scheduled events
-sequences. For example, the following sequence will loop on switching ups.status
+You can also use the `TIMER <seconds>` instruction to create scheduled event
+sequences (such files are traditionally named with the `.seq` extension).
+For example, the following sequence will loop on switching `ups.status`
 between "OL", "OB" and "OB LB" every minute:
 
 	ups.status: OL
@@ -78,21 +90,23 @@ between "OL", "OB" and "OB LB" every minute:
 	ups.status: LB
 	TIMER 60
 
-It is wise to end the script with a TIMER. Otherwise dummy-ups will directly
-go back to the beginning of the file.
+It is wise to end the script with a `TIMER` keyword. Otherwise *dummy-ups*
+will directly go back to the beginning of the file and, in particular, forget
+any values you could have just set with `upsrw`.
 
 Repeater Mode
 ~~~~~~~~~~~~~
 
-Port is the name of a remote UPS, using the NUT form, ie:
+In this context, `port` in the `ups.conf` block is the name of a remote UPS,
+using the NUT format, i.e.:
 
 	<upsname>@<hostname>[:<port>]
 
 For instance:
 
-    [repeater]
+	[repeater]
 		driver = dummy-ups
-		port = ups@hostname
+		port = ups1@remotehost
 		desc = "dummy-ups in repeater mode"
 
 Unlike UPS specifications in the rest of NUT, the `@hostname` portion is not
@@ -103,17 +117,18 @@ INTERACTION
 -----------
 
 Once the driver is loaded in dummy mode, you can change any variables, except
-those of the driver.* and server.* collections.
+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.
 
-Note that in simulation mode, new variables can be added on the fly, by
-adding these to the definition file. Conversely, if you need to remove
-variable (such as transient ones, like ups.alarm), simply update these
-by setting an empty value. As a result, they will get removed from the data.
+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).
+Conversely, if you need to remove variable (such as transient ones, like
+`ups.alarm`), simply update these by setting an empty value. As a result,
+they will get removed from the data.
 
-In repeater mode, the driver acts according to the capabilities of the UPS, and
-so support the same instant commands and settable values.
+In repeater mode, the driver acts according to the capabilities of the UPS,
+and so supports the same instant commands and settable values.
 
 BACKGROUND
 ----------