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

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