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@lists.alioth.debian.org
http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/nut-upsdev
