Nut upsdev - Jun 2017 - Proposed new documentation "Configuration Examples"

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

On June 21, 2017 11:03:00 AM GMT+02:00, Roger Price <roger at
rogerprice.org> wrote:
>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
>
>_______________________________________________
>Nut-upsdev mailing list
>Nut-upsdev at lists.alioth.debian.org
>http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/nut-upsdev
Regarding systemd, there are many valid paths, applied in order of preference
(rising from distro to system-local). It may be worded better in official docs,
but in short, the /usr/lib/systemd and to an extent /lib/systemd trees can be
considered distro(package) and core-systemd defaults. The /etc/systemd lists
activated services and system-local customizations or overrides, if any. Finally
/run/systemd has some runtime-local services or links, that are valid until
reboot and must be re-instantiated after boot. Something like that ;)

Jim
--
Typos courtesy of K-9 Mail on my Redmi Android

On Wed, 21 Jun 2017, Jim Klimov wrote:
> Regarding systemd, there are many valid paths, applied in order of 
> preference (rising from distro to system-local). It may be worded better 
> in official docs, but in short, the /usr/lib/systemd and to an extent 
> /lib/systemd trees can be considered distro(package) and core-systemd 
> defaults. The /etc/systemd lists activated services and system-local 
> customizations or overrides, if any. Finally /run/systemd has some 
> runtime-local services or links, that are valid until reboot and must be 
> re-instantiated after boot. Something like that ;)
I simplified my text and added a link to section ?unit file load path? in 
man systemd.unit.  I'll let the the systemd guys explain it.

Roger