Merge pull request networkupstools#2797 from jimklimov/fix-docs-markup

Fix asciidocs markup

Author: jimklimov

AUTHORS

@@ -86,12 +86,22 @@ N: Mark Powell
 E: medp@primagraphics.co.uk
 D: Ported to SunOS4
 
+N: Evgeny "Jim" Klimov
+E: jimklimov+nut@gmail.com
+D: Primary coordinator ; author of numerous CI recipes, tests and OS
+D: integration scripts - including NDE (NUT Driver Enumerator), NIT
+D: (NUT Integration Test suite) and Jenkins-Dynamatrix, to name a few.
+D: Also automake/autoconf/m4 scripting, asciidoc documentation.
+D: More of a bug-fixer, warnings-squasher and portability maintainer,
+D: rather than e.g. specifically a driver developer.
+P: 4096R/7043DCF7 B834 59F7 76B9 0224 988F 36C0 DE01 84DA 7043 DCF7
+
 N: Arnaud Quette
 E: aquette.dev@gmail.com
 E: arnaud.quette@mgeups.com
 E: aquette@debian.org
 W: http://arnaud.quette.free.fr/
-D: Primary coordinator ; author of snmp-ups, mge-shut, usbhid-ups ;
+D: Previous primary coordinator ; author of snmp-ups, mge-shut, usbhid-ups ;
 D: co author of mge-utalk, hidups, SNMP UPS Agent ; contributor to blazer,
 D: bestferrups, nut core, and many others ; coordination with MGE UPS
 D: SYSTEMS, linux-usb developers (for hidups), Net SNMP and packagers

INSTALL.nut.adoc

@@ -179,6 +179,12 @@ into their operating system.  On the other hand, distributions and appliances
 tend to package "official releases" of projects such as NUT, and so do not
 deliver latest and greatest fixes, new drivers, bugs and other features.
 
+Stable distributions also tend to deliver minor fixes to the version of
+third-party software (like NUT) a particular release of the operating
+system has initially delivered, so those release lines can be years behind
+development in terms of new features (or bug fixes, if they are not trivial
+to patch into the old code base snapshot used to create the package).
+
 [[Installing_source]]
 Installing from source
 ----------------------
@@ -300,6 +306,8 @@ This will build the NUT client and server programs and the
 selected drivers. It will also build any other features that were
 selected during <<Configuration,configuration>> step above.
 
+NOTE: NUT is regularly tested with GNU, BSD and Sun implementations of `make`.
+
 
 Installation
 ^^^^^^^^^^^^
@@ -403,7 +411,7 @@ drivers; this should allow you to follow the below
 instructions. However, don't forget to set up the correct
 permissions later!).
 
-NOTE: if you are using something like udev or devd, make sure
+NOTE: If you are using something like udev or devd, make sure
 these permissions stay set across a reboot.  If they revert to the
 old values, your drivers may fail to start.
 
@@ -480,16 +488,21 @@ copy the proposed-source URL of that "from" part.
 For example, in some PR this says `jimklimov:issue-1234` and links to
 `https://github.com/jimklimov/nut/tree/issue-1234`.
 For manual git-cloning, just paste that URL into the shell and replace
-the `/tree/` with "`-b`" CLI option for branch selection, like this:
+the `/tree/` with "`-b`" CLI option for branch selection; it also helps
+to keep the workspace directory name dedicated to that PR, like this:
 
 	:; cd /tmp
 	### Checkout https://github.com/jimklimov/nut/tree/issue-1234
-	:; git clone https://github.com/jimklimov/nut -b issue-1234
+	:; git clone https://github.com/jimklimov/nut -b issue-1234 nut-issue-1234
+	:; cd nut-issue-1234
+	### OPTIONALLY fetch known git tags, so semantic versions look better
+	:; git fetch --tags --all
+	### Proceed with build (common instructions below)
 
 Testing with CI helper
 ~~~~~~~~~~~~~~~~~~~~~~
 
-NOTE: this uses the `ci_build.sh` script to arrange some rituals and
+NOTE: This uses the `ci_build.sh` script to arrange some rituals and
 settings, in this case primarily to default the choice of drivers to
 auto-detection of what can be built, and to skip building documentation.
 Also note that this script supports many other scenarios for CI and
@@ -501,6 +514,9 @@ An "in-place" _testing_ build and run would probably go along these lines:
 	:; cd /tmp
 	:; git clone -b master https://github.com/networkupstools/nut
 	:; cd nut
+	### OPTIONALLY fetch known git tags, so semantic versions look better
+	:; git fetch --tags --all
+	### Proceed with build
 	:; ./ci_build.sh inplace
 	### Temporarily stop your original drivers
 	:; ./drivers/nutdrv_qx -a DEVNAME_FROM_UPS_CONF -d1 -DDDDDD \
@@ -555,6 +571,9 @@ This goes similar to usual build and install from Git:
 	:; cd /tmp
 	:; git clone https://github.com/networkupstools/nut
 	:; cd nut
+	### OPTIONALLY fetch known git tags, so semantic versions look better
+	:; git fetch --tags --all
+	### Proceed with build
 	:; ./autogen.sh
 	:; ./configure --enable-inplace-runtime # --maybe-some-other-options
 	:; make -j 4 all && make -j 4 check && sudo make install
@@ -583,6 +602,9 @@ symlinks) and to get them started:
 	:; cd /tmp
 	:; git clone https://github.com/networkupstools/nut
 	:; cd nut
+	### OPTIONALLY fetch known git tags, so semantic versions look better
+	:; git fetch --tags --all
+	### Proceed with build
 	:; ./autogen.sh
 	:; ./configure --enable-inplace-runtime # --maybe-some-other-options
 	:; make -j 4 all && make -j 4 check && \
@@ -635,6 +657,9 @@ e.g.:
 	:; git clone https://github.com/networkupstools/nut
 	:; cd nut
 	:; git checkout -b issue-1234 ### your PR branch name, arbitrary
+	### OPTIONALLY fetch known git tags, so semantic versions look better
+	:; git fetch --tags --all
+	### Proceed with build
 	:; ./autogen.sh
 	:; ./configure --enable-inplace-runtime # --maybe-some-other-options
 	### Iterate your code changes (e.g. PR draft), build and install with:
@@ -645,6 +670,13 @@ e.g.:
 	    sudo systemctl restart \
 	        nut-driver-enumerator.service nut-monitor nut-server
 
+Note that to contribute your work back to upstream NUT codebase, you would
+need to create a "fork" of https://github.com/networkupstools/nut on GitHub,
+then `git remote add USERNAME https://github.com/USERNAME/nut`, maybe refresh
+the workspace index with `git fetch --all`, and finally `git push USERNAME`
+(possibly follow further instructions from `git` tooling) to create the
+pull request. For more details, see `docs/developers.txt` in NUT sources.
+
 Next steps after an in-place upgrade
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -668,7 +700,7 @@ Debian, Ubuntu and other derivatives
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 NOTE: NUT is packaged and well maintained in these systems.
-The official Debian packager is part of the NUT Team.
+The official Debian packager used to be part of the NUT Team.
 
 Using your preferred method (apt-get, aptitude, Synaptic, ...), install
 the 'nut' package, and optionally the following:

MAINTAINERS

@@ -64,6 +64,15 @@ P: Greg Troxel
 M: gdt@lexort.com
 S: Maintained: pkgsrc (sysutils/ups-nut)
 
+CI, tests and recipes
+=====================
+
+P: Evgeny "Jim" Klimov
+M: jimklimov+nut@gmail.com
+S: Maintained or Supported: numerous CI recipes, tests and OS integration
+S: scripts: NDE (NUT Driver Enumerator), NIT (NUT Integration Test suite),
+S: Jenkins-Dynamatrix, automake/autoconf/m4 scripting, asciidoc documentation.
+
 Everything else
 ===============
 

README.adoc

@@ -446,11 +446,14 @@ UPS Shutdowns
 
 upsdrvctl can also shut down (power down) all of your UPS hardware.
 
-WARNING: if you play around with this command, expect your filesystems
+[WARNING]
+=========
+If you play around with this command, expect your filesystems
 to die.  Don't power off your computers unless they're ready for it:
 
 	/usr/local/ups/sbin/upsdrvctl shutdown
 	/usr/local/ups/sbin/upsdrvctl shutdown sparky
+=========
 
 You should read the {xref}UPS_shutdown{x-s}[Configuring automatic UPS shutdowns]
 chapter to learn more about when to use this feature.  If called at the wrong
@@ -598,6 +601,7 @@ not have any effect on your system.
 
 A driver that supports read/write variables will give results like this:
 
+----
 	$ upsrw sparky@localhost
 
 	( many skipped )
@@ -610,12 +614,15 @@ A driver that supports read/write variables will give results like this:
 	Option: "0"
 
 	( more skipped )
+----
 
 On the other hand, one that doesn't support them won't print anything:
 
+----
 	$ upsrw fenton@gearbox
 
 	( nothing )
+----
 
 `upsrw` requires administrator powers to change settings in the hardware.
 Refer to {linkman2}upsd.users{lm-s}upsd.users{lm-c}5{lm-e} for information on defining
@@ -631,6 +638,7 @@ hardware/drivers support them.
 
 Use the -l command to list them, like this:
 
+----
 	$ upscmd -l sparky@localhost
 	Instant commands supported on UPS [sparky@localhost]:
 
@@ -639,6 +647,7 @@ Use the -l command to list them, like this:
 	calibrate.start - Start run time calibration
 	calibrate.stop - Stop run time calibration
 	...
+----
 
 `upscmd` requires administrator powers to start instant commands.
 To define users and passwords in `upsd`, see
@@ -734,6 +743,14 @@ Major release jumps are mostly due to large changes to the features
 list.  There have also been a number of architectural changes which
 may not be noticeable to most users, but which can impact developers.
 
+Since NUT v2.8.2 or so, development iterations have additional version
+components, to account for the amount of commits on the main branch
+(`master`) since the last known Git tag, and amount of commits on the
+developed feature branch that are unique to it compared to main branch.
+This allows for a reasonably growing version of stable baseline and
+local development, so that experimental packages can be installed as
+upgrades (or well-exposed downgrades).
+
 Backwards and Forwards Compatibility
 ------------------------------------
 

data/html/README.adoc

@@ -56,6 +56,7 @@ b) configure manually
 
 - Now edit your webserver configuration file, adding for
   example (for Apache):
++
 ----
 #Begin Section
 ScriptAlias /nut/cgi-bin/ /usr/local/nut/cgi-bin/
@@ -84,7 +85,8 @@ Alias /nut/ /usr/local/nut/html/
 
 - Make sure to restart your webserver.
 
-- Configure the CGI scripts.  Manpages can be found from:
+- Configure the CGI scripts.  Man pages can be found from:
++
 ----
 :; man -M /usr/local/nut/man/ upsstats.cgi
 :; man -M /usr/local/nut/man/ upsset.cgi