On June 21, 2017 11:03:00 AM GMT+02:00, Roger Price <ro...@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@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 _______________________________________________ Nut-upsdev mailing list Nut-upsdev@lists.alioth.debian.org http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/nut-upsdev