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

Jim Klimov jimklimov at cos.ru
Wed Jun 21 09:40:32 UTC 2017

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
>> because it should not be as much of a burden as other markup formats
>> read or write, and because it offers several output formats. If it
>> out to be a deterrent to contributions, that is something we should 
>> address. I am concerned about the maintainability of several
>> going forward, and I (selfishly, perhaps) would appreciate more help
>> the core NUT documentation. Your thoughts on this would be
>Yes, I have used AsciiDoc as part of my failed attempt to add SIGUSR1/2
>NUT. That was my second patch. 
>I generated PDF, HTML, and groff man pages.  I should explain that in
>past I have done a lot of markup in pre-SGML languages such as groff,
>and it's sub-languages such as HTML, and hundreds of pages of
>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
>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,
>than core documentation, so I didn't consider the need for an agreed 
>team documentation technique.  My only concern was for readily
>tools and LaTeX for me fits the bill.
>I think that maintenance of the core NUT documentation is a separate 
>> I agree that printers are becoming less and less common. However, I
>> not sure that a two-column format with little space and no rule
>> the columns is the best choice for screen display. Many PDF viewers
>> display two pages side-by-side, and will do so with a dark border
>> 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
>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
>> 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
>> to consider choosing another color for either upsd or upsmon.
>I have reduced the saturation of the colours so that the text will be
>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
>making the changes.
>> The CHRG and DISCHRG status flags are probably confusing for an 
>> entry-level text, and are more informational than the critical
>> flags. Some models do not indicate CHRG or DISCHRG, and others will
>> 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
>> to be links. (This might be my web browser and PDF reader
>> 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
>and clickable.
>> You have probably noticed that I often link to a specific section of
>> 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
>> 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
>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
>> 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
>function which contains (c-set-style "K&R"). My intention was to say
>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
>> /etc/systemd/... or /usr/local/systemd/... ?
>Yes, it should say /etc/systemd/... for user scripts.  I was looking at
>ancient openSUSE release which is out-of-date.  I have corrected this.
>I would like to include specifics from other distributions, but I rely
>others to volunteer the data.
>The updated text is available at 
>Nut-upsdev mailing list
>Nut-upsdev at lists.alioth.debian.org

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 ;)

Typos courtesy of K-9 Mail on my Redmi Android

More information about the Nut-upsdev mailing list