[Nut-upsdev] Proposed new documentation "Configuration Examples"

[Roger Price]

On Tue, 13 Jun 2017, Charles Lepple wrote:

> On Jun 9, 2017, at 10:16 AM, Roger Price wrote:
>> To address this, I propose a "NUT configuration for Noobs" which is 
>> called "Configuration Examples".

> I am also curious whether you tried to edit any of the existing NUT 
> documentation before creating a new document. We chose AsciiDoc in part 
> because it should not be as much of a burden as other markup formats to 
> read or write, and because it offers several output formats. If it turns 
> out to be a deterrent to contributions, that is something we should 
> address. I am concerned about the maintainability of several documents 
> going forward, and I (selfishly, perhaps) would appreciate more help on 
> the core NUT documentation. Your thoughts on this would be appreciated.

Yes, I have used AsciiDoc as part of my failed attempt to add SIGUSR1/2 to 
NUT. That was my second patch. 
https://lists.alioth.debian.org/pipermail/nut-upsdev/2016-July/007204.html 
I generated PDF, HTML, and groff man pages.  I should explain that in my 
past I have done a lot of markup in pre-SGML languages such as groff, SGML 
and it's sub-languages such as HTML, and hundreds of pages of mathematics 
and technical stuff in LaTeX.  I was, for my sins, a member of the SGML 
working group in the ISO, and editor of the International Standard behind 
HTML.  I can markup quickly and accurately, and I find WYSIWYG tools a 
pain and a frustration.

I intended the Configuration Examples as a personal contribution, rather 
than core documentation, so I didn't consider the need for an agreed 
team documentation technique.  My only concern was for readily available 
tools and LaTeX for me fits the bill.

I think that maintenance of the core NUT documentation is a separate 
subject.

> I agree that printers are becoming less and less common. However, I am 
> not sure that a two-column format with little space and no rule between 
> the columns is the best choice for screen display. Many PDF viewers can 
> display two pages side-by-side, and will do so with a dark border around 
> each page. There is probably a middle ground between these dimensions 
> and the ones used in the AsciiDoc-generated PDFs.

My choice of A4 landscape with 2 pages per sheet was not very reader 
friendly.  I have generated a second format: A5 with one page per sheet in 
portrait mode.  My PDF viewer is happy to put two pages side by side. 
This is probably the best choice.

> There are recommendations out there concerning maximum line lengths for 
> readability, and I think they are closer to 65 characters. The 90-100 
> character lines seem to me to be harder to read, especially with the 
> close column spacing.

My problem was that I was using too small a font.  Now that the font is 
bigger, there are just over 80 characters per line, which I claim is 
tolerable for technical documentation.

> I think color can be useful in diagrams, but it can be distracting in 
> running text. Also, red/green colorblindness is probably common enough 
> to consider choosing another color for either upsd or upsmon.

I have reduced the saturation of the colours so that the text will be more 
easily readable.  The colours in the text are very easy to change, but 
diagrams done with xfig need more effort. I'd like to hear from someone 
with the problem what the result looks like, and get some agreement before 
making the changes.

> The CHRG and DISCHRG status flags are probably confusing for an 
> entry-level text, and are more informational than the critical OL/OB/LB 
> flags. Some models do not indicate CHRG or DISCHRG, and others will omit 
> CHRG if they are OL but not topping off the battery.

Good point, I have removed the references to CHRG and DISCHRG.

> Also, some of the internal references to lines and sections do not seem 
> to be links. (This might be my web browser and PDF reader combination, 
> but usually the table-of-contents links work.)

Agreed, a LaTeX package was missing and the hyperlinking was broken. 
It's now fixed and fully operational. Table of contents, chapter 
references, line numbers, man pages, external sites and files: all linked 
and clickable.

> You have probably noticed that I often link to a specific section of the 
> NUT HTML documentation. I appreciate that you have written this in a 
> tutorial format rather than as a reference, but you may still need to 
> point users to a specific location, and page numbers are not stable over 
> time (and neither are section numbers).

A URL such as http://rogerprice.org/NUT/ConfigExamples.A5.pdf#page.20 
works for Firefox but not Opera. Again with Firefox, 
ConfigExamples.A5.pdf#section.5 and ConfigExamples.A5.pdf#subsection.5.2 
also work, but I cannot get #namedest... to work.

> The last one is a bit pedantic, but the K&R format of the source code is 
> probably not important enough to mention in the introduction. Usually 
> "K&R" refers to code that will not compile without adjustment in a 
> C89-compliant (or later) compiler.

The "K&R" comes from the Developer's Guide, Ch 3.5 proposal for an Emacs 
function which contains (c-set-style "K&R"). My intention was to say "This 
is real code, lean and mean - not C++ overbloat".  If you prefer I say 
that instead of "K&R", I'm happy to change it.

> On page 5 (right column), it mentions that 
> /usr/lib/systemd/system-shutdown is for user scripts, and 
> /lib/systemd/system-shutdown is for system scripts. Should the first be 
> /etc/systemd/... or /usr/local/systemd/... ?

Yes, it should say /etc/systemd/... for user scripts.  I was looking at an 
ancient openSUSE release which is out-of-date.  I have corrected this.

I would like to include specifics from other distributions, but I rely on 
others to volunteer the data.

The updated text is available at 
http://rogerprice.org/NUT/ConfigExamples.A5.pdf

Roger