scripts/*/README.adoc: revise markup for proper rendered visuals

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>

data/html/README.adoc

@@ -13,12 +13,13 @@ NUT HTML pages have been created as a central point
 that ease the access to the various CGI scripts
 providing the NUT web interface.
 
-It consists of three `.html` files:
-- `index.html`: defines the two container frames,
+It consists of three HTML files:
+
+* `index.html`: defines the two container frames,
   `topFrame` and `mainFrame`
-- `header.html`: contains the header including links
+* `header.html`: contains the header including links
   to NUT website, and `upsstats.cgi`/`upsset.cgi`
-- `bottom.html`: empty frame that will be replaced
+* `bottom.html`: empty frame that will be replaced
   with the content of `upsstats.cgi` or `upsset.cgi`.
 
 2) Integration

docs/nut.dict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 3409 utf-8
+personal_ws-1.1 en 3410 utf-8
 AAC
 AAS
 ABI
@@ -2448,6 +2448,7 @@ mandir
 manpage
 manpages
 masterguard
+matcher
 maxacvi
 maxacvo
 maxd

scripts/Windows/README.adoc

@@ -98,6 +98,7 @@ or
 (it can help to open two terminals and copy one ARCH into each
   and then the lines below into both of them; be sure to use separate
   directory trees for the unpacked build workspaces)
+
 - for either-ARCH build environment further set:
 ------
 :; export HOST_FLAG="--host=$ARCH"

scripts/augeas/README.adoc

@@ -14,9 +14,10 @@ through Augeas lenses and modules.
 
 From link:http://augeas.net[Augeas homepage]:
 
-"Augeas is a configuration editing tool. It parses configuration files in their
-native formats and transforms them into a tree. Configuration changes are made
-by manipulating this tree and saving it back into native config files."
+> "Augeas is a configuration editing tool. It parses configuration files
+> in their native formats and transforms them into a tree. Configuration
+> changes are made by manipulating this tree and saving it back into
+> native config files."
 
 In other words, Augeas is the dreamed Registry, with all the advantages
 (such as a uniform interface and tools), and the added bonus of being
@@ -39,11 +40,11 @@ are welcome).
 
 As an example, on Debian and derivatives, do the following:
 
-	$ apt-get install augeas-lenses augeas-tools
+	:; apt-get install augeas-lenses augeas-tools
 
 And optionally:
 
-	$ apt-get install libaugeas0 libaugeas-dev python-augeas
+	:; apt-get install libaugeas0 libaugeas-dev python-augeas
 
 On RedHat and derivatives, you have to install the packages 'augeas' and
 'augeas-libs'.
@@ -53,23 +54,23 @@ On RedHat and derivatives, you have to install the packages 'augeas' and
 NUT lenses and modules for Augeas
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-These are the *.aug files in the present directory.
+These are the `*.aug` files in the present directory.
 
 You can either install the files to the right location on your system,
-generally in '/usr/share/augeas/lenses/', or use these from NUT
-source directory ('nut/scripts/augeas'). The latter is to be preferred for
+generally in `/usr/share/augeas/lenses/`, or use these from NUT
+source directory (`nut/scripts/augeas`). The latter is to be preferred for
 the time being.
 
 
 Create a test sandbox
 ---------------------
 
-NOTE: for now, it's easier to include an existing /etc/nut/ directory.
+NOTE: For now, it is easier to include an existing `/etc/nut/` directory.
 
-	$ export AUGEAS_ROOT=./augeas-sandbox
-	$ mkdir $AUGEAS_ROOT
-	$ sudo cp -pr /etc/nut $AUGEAS_ROOT
-	$ sudo chown -R $(id -nu):$(id -ng) $AUGEAS_ROOT
+	:; export AUGEAS_ROOT=./augeas-sandbox
+	:; mkdir $AUGEAS_ROOT
+	:; sudo cp -pr /etc/nut $AUGEAS_ROOT
+	:; sudo chown -R $(id -nu):$(id -ng) $AUGEAS_ROOT
 
 
 Start testing and using
@@ -89,13 +90,13 @@ Shell
 
 Start an augeas shell using:
 
-	$ augtool -b
+	:; augtool -b
 
-NOTE: if you have not installed NUT lenses, add '-I/path/to/nut/scripts/augeas'.
+NOTE: If you have not installed NUT lenses, add `-I/path/to/nut/scripts/augeas`.
 
 From there, you can perform different actions like:
 
-- list existing nut related files:
+- list existing NUT-related files:
 
 	augtool> ls /files/etc/nut/
 	nut.conf/ = (none)
@@ -104,45 +105,50 @@ From there, you can perform different actions like:
 	ups.conf/ = (none)
 	upsd.conf/ = (none
 +
-or using:
+or using the matcher:
 +
 	augtool> match /files/etc/nut/*
 	/files/etc/nut/nut.conf = (none)
 	/files/etc/nut/upsd.users = (none)
 	/files/etc/nut/upsmon.conf = (none)
 	/files/etc/nut/ups.conf = (none)
 	/files/etc/nut/upsd.conf = (none)
-
-NOTE: if you don't see anything, you may search for error messages by using:
 +
+[NOTE]
+======
+If you don't see anything, you may search for error messages by using:
+
 	augtool> ls /augeas/files/etc/nut/*/errors
+
 and
+
 	augtool> get /augeas/files/etc/nut/ups.conf/error/message
 	/augeas/files/etc/nut/ups.conf/error/message = Permission denied
+======
 
-- create a new device entry (in ups.conf), called 'augtest':
+- create a new device entry (in `ups.conf`), called `augtest`:
 
 	augtool> set /files/etc/nut/ups.conf/augtest/driver dummy-ups
 	augtool> set /files/etc/nut/ups.conf/augtest/port auto
 	augtool> save
 
-- list the devices using the 'usbhid-ups' driver:
+- list the devices currently using the `usbhid-ups` driver:
 
 	augtool> match /files/etc/nut/ups.conf/*/driver dummy-ups
 
 
 C
 ~
 
-A library is available for C programs, along with pkg-config support.
+A library is available for C programs, along with `pkg-config` support.
 
 You can get the compilation and link flags using the following code
-in your configure script or Makefile:
+in your program's `configure` script or `Makefile`:
 
 	CFLAGS="`pkg-config --silence-errors --cflags augeas`"
 	LDFLAGS="`pkg-config --silence-errors --libs augeas`"
 
-Here is an code sample using this library for NUT configuration:
+Here is a code sample using this library for NUT configuration:
 
 --------------------------------------------------------------------------------
 augeas *a = aug_init(NULL, NULL, AUG_NONE);

scripts/python/README.adoc

@@ -7,44 +7,55 @@ by David Goncalves, and released under GPL v3.
 module
 ~~~~~~
 
-This directory contains PyNUT.py, which is a Python abstraction class to
+This directory contains `PyNUT.py`, which is a Python abstraction class to
 access NUT data server(s). You can use it in Python programs to access NUT's
-upsd data server in a simple way, without having to know the NUT protocol.
+`upsd` data server in a simple way, without having to know the NUT protocol.
 
 The same module should work for Python 2 and Python 3.
 
-To import it on Python programs you have to use the following (case sensitive):
+To import it into Python programs you have to use the following line (case
+sensitive):
 
     import PyNUT
 
-This module provides a 'PyNUTClient' class that can be used to connect and
-get data from an upsd data server.
+This module provides a `PyNUTClient` class that can be used to connect and
+get data from an `upsd` data server.
 
-To install the PyNUT module on Debian/Ubuntu, copy it to:
-/usr/share/python-support/python-pynut/
+To install the `PyNUT` module on Debian/Ubuntu, copy it to:
+`/usr/share/python-support/python-pynut/`
 
 For quick tests, just make sure its directory is exported in `PYTHONPATH`
 environment variable.
 
-This directory also contains test_nutclient.py, which is a PyNUT test program.
-For this to be fully functional, you will need to adapt the login, password and
-upsname to fit your configuration. A NUT data server should be running for the
-test program to verify connection and protocol support.
+This directory also contains `test_nutclient.py`, which is a `PyNUT` test program
+and it also serves as a code example. For this to be fully functional, you will
+need to adapt the login, password and upsname to fit your configuration.
+A NUT data server should be running for the test program to verify connection
+and protocol support.
 
 For one practical example, you can research `tests/NIT/nit.sh` in NUT sources.
 
 app
 ~~~
 
-This directory contains the NUT-Monitor application, which uses the
-PyNUT class, along with its resources.
+This directory contains the `NUT-Monitor` UI application, which uses the
+`PyNUT` class, along with its own resources.
+
+There are two closely related separate implementations, for Python 2 with GTK2
+and for Python 3 with Qt5. Both can be installed at the same time, if your
+distribution has not yet outlawed the obsolete Python 2 interpreters.
 
 To install it, you will either need to keep the files together, or to install:
-- Depending on the Python version(s) your system has, put NUT-Monitor-py2gtk2
-  or NUT-Monitor-py3qt5 to /usr/bin/, /usr/X11R6/bin/ or something like that
-  (optionally making a simple NUT-Monitor symlink to the preferred version),
-- ui/*.glade (for NUT-Monitor-py2gtk2) or ui/*.ui (for NUT-Monitor-py3qt5)
-  to /usr/share/nut-monitor/,
-- nut-monitor.png to something like /usr/share/pixmaps/
-- finally, nut-monitor-py2gtk2.desktop and/or nut-monitor-py3qt5.desktop
-  (optionally symlinked as nut-monitor.desktop) to /usr/share/applications/
+
+- Depending on the Python version(s) your system has, put `NUT-Monitor-py2gtk2`
+  and/or `NUT-Monitor-py3qt5` to `/usr/bin/`, `/usr/X11R6/bin/` or something
+  like that (optionally making a simple `NUT-Monitor` symlink to the preferred
+  implementation version or using the provided wrapper script),
+- `ui/*.glade` (for `NUT-Monitor-py2gtk2`) or `ui/*.ui` (for `NUT-Monitor-py3qt5`)
+  files to `/usr/share/nut-monitor/`,
+- `nut-monitor.png` to something like `/usr/share/pixmaps/`,
+- finally, `nut-monitor-py2gtk2.desktop` and/or `nut-monitor-py3qt5.desktop`
+  (optionally symlinked as `nut-monitor.desktop`) to `/usr/share/applications/`
+
+The `PyNUT` module can be kept nearby, or must be installed as a "site" or "vendor"
+provided script into your Python modules location. See the wrapper script for more technical details.

scripts/python/app/README.adoc

@@ -12,19 +12,22 @@ uses the python-pynut class (available at http://www.lestat.st), delivered
 as PyNUT in the NUT source tree.
 
 Refer to your OS packaging and/or install custom modules with `pip` (or `pip3`)
-to get required dependencies (GTK + GObject or QT5).
+to get required dependencies (GTK + GObject or Qt5).
 
 Path to PyNUT module
 --------------------
 
 For quick tests (e.g. during development), you can run the clients like this:
-````
+
+----
 :; PYTHONPATH=../module/ python2 ./NUT-Monitor-py2gtk2.in
-````
+----
+
 or:
-````
+
+----
 :; PYTHONPATH=../module/ python3 ./NUT-Monitor-py3qt5.in
-````
+----
 
 Localization
 ------------
@@ -58,7 +61,7 @@ Kudos
 NUT-Monitor and PyNUT (for Python 2 syntax) were originally authored
 by David Goncalves <david@lestat.st>
 
-NUT-Monitor was converted to Python 3 + QT5 by Luke Dashjr
+NUT-Monitor was converted to Python 3 + Qt5 by Luke Dashjr
 
 PyNUT was extended, and two variants of NUT-Monitor converged and wrapped
 for Python 2+3 dual support by Jim Klimov

scripts/usb_resetter/README.adoc

@@ -40,6 +40,7 @@ Found device 0665:5161 at /dev/bus/usb/001/002 Manufacturer=INNO TECH, Product=U
 ----
 
 The `usb_resetter` can work in three different ways:
+
 - Reset device itself
 - Reset the hub the device is attached to
 - Reset all USB controllers