Hello Gene, I read and nodded sometimes and caught myself thinking that I used to propose or agree with some of the points you make, but outgrew those.> ...makers claim...I suppose this means asciidoc makers (not e.g. UPS makers)? They are actually largely non-Windows, especially in the part about rendering books, presentations, local HTML pages or web sites. These are all platform-independent formats.> Holding someone's feet to fire for somethingWho are we to do so? Who are "nut folks"? A loose community joined by an interest, with some persons more prominent in a given year. To require something of UPS makers, the wider community members actually have more legal leverage, as paying customers of this or that company delivering what they can claim a defective product, infringed right-to-repair (spec/protocol docs), etc. Core team and project as an entity has exposure that can be useful for vendors' marketing, and occasionally some things happened due to that. But (sadly), there's no incantation like "Bow thyself to celebrity BDFL, you evil corporation!" and so they would. As for civil discourse, anyone can post bugs and raise discussions; maintainers are not special in that regard. (And as said, paying customers can have a slightly upper hand when asking).> Those generated files are not tracked in Git. > But should be.Actually, no. At least not those with non-deterministic rendering results. There are quite a few files rendered and tracked by scripts in NUT recipes, and the massively multiplatform CI does make sure there are no git diffs as result of a build. Rendered docs have timestamps, renderer versions and whatnot embedded, and are hell to git-track.> packaged version in distrosTheir choice. And users'. If they go for stability and a well known landscape that changes slowly (backporting bug fixes to same baseline), or go with daily rolling builds - to each their own, there are pros and cons to both.> doc and code versionsNUT docs are part of its code base so should closely match. Packages from a code snapshot deliver renders of its docs and should match. NUT website since 2.8.0 is rolling with current master, and historic snapshots are issued as part of release rituals to ~never change. So users of packages can go to a site with docs of their version. Hope this helps, Jim PS My condolences. On Tue, May 13, 2025, 17:45 gene heskett via Nut-upsuser < nut-upsuser at alioth-lists.debian.net> wrote:> On 5/12/25 09:46, Jim Klimov via Nut-upsuser wrote: > Comments from a CET's point of view. > > Hi Sam, > > > > Not really sure what you mean here. NUT documentation is written in > > asciidoc, so that it is easy to combine from several source files and > > render into man pages, HTML, PDF, etc. (which does go via docbook XML as > a > > technical detail of asciidoc, and does result in some *roff files as a > > technical detail of man page rendering, but in NUT sources/recipes we do > > not directly care about either of those aspects). Allegedly there are a > few > > quirks with Asciidoc as well (notably there are several renderers out > > there, but any semblance of a formal standard and common testing suite > was > > being discussed as brewing up on FOSDEM 2025), but it is pretty > convenient > > and light-weight once you get a hold of it. > But woefully incomplete, primarily because the makers claim one thing in > their docs, but actually deliver something else. I don't consider that > as a nut fault. However, since nut is the only one providing an > industry wide solution in the face of makers who have NDI what the > non-windblows world needs, I do fault the nut folks for not holding the > makers feet a little closer to the fire, stopping the lies and outright > BS this division of our industry is rife with. > > NUT "dist" tarballs, including release snapshots, do include a copy of > > generated man pages (probably in a *roff format) for the benefit of > > end-users who only have a compiler and do not want to burden their > systems > > and build times with asciidoc/docbook/etc. tooling. So they can just > build > > NUT programs, `make install`, and have them nicely documented out of the > > box. Those generated files are not tracked in Git. > But should be. > > Full-scale builds such as for packaging are encouraged to have the > full > > stack in the build agent (or build root) and re-generate these documents. > > This might, depending on local settings, add distro watermarks ("NUT > pages > > as part of OS XXX docs"), apply distro-wide build timestamp, use the > *roff > > version that OS is comfortable with, or whatever. > > > > Also note that since NUT v2.8.3 we added support for `configure` > options > > to assign man section codes (numbers or not) for systems that do not > follow > > suit of Linux and BSD numbering (e.g. in Solaris/illumos, the system > > commands are historically not "8" but "1m"). Previously this required > > strange patch files on packager side, a burden to be revised/updated for > > each NUT release; now it requires just a few configure options that can > be > > left in the recipe once and forever. > > Another point, you are about o make a 2.8.3, but the latest debian is > 2.8.0. More feet to hold up to the fire. We can't use either to their > full capability because the docs don't match what we read here. The > docs don't even seem to apply to the version they purport to be, if they > exist at all. Hence I'm pleading for docs that match what the repo > installs. > > I have an APC 1500wa, now several years old. Its front panel display > has been asking for a new set of batteries for at least 5 years, but due > to my now passed wife having COPD, a 20kw kohler in the back yard has an > under 10 second startup time. So this machine runs normally for that > time period. And nut is not running, fails to start since bookworm. And > I have NDI why. The APC OTOH is doing what I bought it for. > > >Hope this clarifies a few points? > > Thanks for reading this far, Jim. > > > Jim Klimov > > Cheers, Gene Heskett, CET. > > -- > "There are four boxes to be used in defense of liberty: > soap, ballot, jury, and ammo. Please use in that order." > -Ed Howdershelt (Author, 1940) > If we desire respect for the law, we must first make the law respectable. > - Louis D. Brandeis > > > _______________________________________________ > Nut-upsuser mailing list > Nut-upsuser at alioth-lists.debian.net > https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/nut-upsuser >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://alioth-lists.debian.net/pipermail/nut-upsuser/attachments/20250513/d21770f9/attachment.htm>
On 5/13/25 12:58, Jim Klimov wrote:> Hello Gene, > > I read and nodded sometimes and caught myself thinking that I used to > propose or agree with some of the points you make, but outgrew those. > >> ...makers claim... > I suppose this means asciidoc makers (not e.g. UPS makers)? They are > actually largely non-Windows, especially in the part about rendering books, > presentations, local HTML pages or web sites. These are all > platform-independent formats.I should have clarified: Not the asciidocs people, theey can only work with what the makers supply, but the makers themselves. There seems to be a fairly wide air gap between what is claimed on the box, and what actually falls out of my mail box or is delivered on my front deck.>> Holding someone's feet to fire for something > Who are we to do so? Who are "nut folks"? A loose community joined by an > interest, with some persons more prominent in a given year. To require > something of UPS makers, the wider community members actually have more > legal leverage, as paying customers of this or that company delivering what > they can claim a defective product, infringed right-to-repair > (spec/protocol docs), etc.Here we argue, in good faith, you and the other experts in this group, as the only platform wide supplier of software basically designed to try to work with ALL of the UPS's that do have a control interface, would seem to represent the users to the makers with enough clout to have a measurable effect on sales when a bad product/maker becomes known, and that then becomes the muscle capable of holding recalcitrant feet to the fire.? You personally may not like to be seen in that light, and reluctant to make use of that seat at the top of the mast, but its still a fact. As the now long retired CE of a mid market tv station, I have helped that scenario play out.? Several times. I don't "carry a grudge" once the problem has been solved, but I've been pretty brutal in print at times.? And I have admitted and apologized when I was wrong, when I was.> Core team and project as an entity has exposure that can be useful for > vendors' marketing, and occasionally some things happened due to that. But > (sadly), there's no incantation like "Bow thyself to celebrity BDFL, you > evil corporation!" and so they would. > > As for civil discourse, anyone can post bugs and raise discussions; > maintainers are not special in that regard. (And as said, paying customers > can have a slightly upper hand when asking). > >> Those generated files are not tracked in Git. >> But should be. > Actually, no. At least not those with non-deterministic rendering results. > > There are quite a few files rendered and tracked by scripts in NUT recipes, > and the massively multiplatform CI does make sure there are no git diffs as > result of a build.That situation has improved, and I appreciate its been a slow slog, thank you. However debians legendary slowness to update things does test my patience at times. The fact that bookworms default nut is 2.8.0 is an example.> > Rendered docs have timestamps, renderer versions and whatnot embedded, and > are hell to git-track. > >> packaged version in distros > Their choice. And users'. If they go for stability and a well known > landscape that changes slowly (backporting bug fixes to same baseline), or > go with daily rolling builds - to each their own, there are pros and cons > to both. > >> doc and code versions > NUT docs are part of its code base so should closely match. Packages from a > code snapshot deliver renders of its docs and should match. > > NUT website since 2.8.0 is rolling with current master, and historic > snapshots are issued as part of release rituals to ~never change. So users > of packages can go to a site with docs of their version. > > Hope this helps, > Jim > > PS My condolences. > > On Tue, May 13, 2025, 17:45 gene heskett via Nut-upsuser < > nut-upsuser at alioth-lists.debian.net> wrote: > >> On 5/12/25 09:46, Jim Klimov via Nut-upsuser wrote: >> Comments from a CET's point of view. >>> Hi Sam, >>> >>> Not really sure what you mean here. NUT documentation is written in >>> asciidoc, so that it is easy to combine from several source files and >>> render into man pages, HTML, PDF, etc. (which does go via docbook XML as >> a >>> technical detail of asciidoc, and does result in some *roff files as a >>> technical detail of man page rendering, but in NUT sources/recipes we do >>> not directly care about either of those aspects). Allegedly there are a >> few >>> quirks with Asciidoc as well (notably there are several renderers out >>> there, but any semblance of a formal standard and common testing suite >> was >>> being discussed as brewing up on FOSDEM 2025), but it is pretty >> convenient >>> and light-weight once you get a hold of it. >> But woefully incomplete, primarily because the makers claim one thing in >> their docs, but actually deliver something else. I don't consider that >> as a nut fault. However, since nut is the only one providing an >> industry wide solution in the face of makers who have NDI what the >> non-windblows world needs, I do fault the nut folks for not holding the >> makers feet a little closer to the fire, stopping the lies and outright >> BS this division of our industry is rife with. >>> NUT "dist" tarballs, including release snapshots, do include a copy of >>> generated man pages (probably in a *roff format) for the benefit of >>> end-users who only have a compiler and do not want to burden their >> systems >>> and build times with asciidoc/docbook/etc. tooling. So they can just >> build >>> NUT programs, `make install`, and have them nicely documented out of the >>> box. Those generated files are not tracked in Git. >> But should be. >>> Full-scale builds such as for packaging are encouraged to have the >> full >>> stack in the build agent (or build root) and re-generate these documents. >>> This might, depending on local settings, add distro watermarks ("NUT >> pages >>> as part of OS XXX docs"), apply distro-wide build timestamp, use the >> *roff >>> version that OS is comfortable with, or whatever. >>> >>> Also note that since NUT v2.8.3 we added support for `configure` >> options >>> to assign man section codes (numbers or not) for systems that do not >> follow >>> suit of Linux and BSD numbering (e.g. in Solaris/illumos, the system >>> commands are historically not "8" but "1m"). Previously this required >>> strange patch files on packager side, a burden to be revised/updated for >>> each NUT release; now it requires just a few configure options that can >> be >>> left in the recipe once and forever. >> Another point, you are about o make a 2.8.3, but the latest debian is >> 2.8.0. More feet to hold up to the fire. We can't use either to their >> full capability because the docs don't match what we read here. The >> docs don't even seem to apply to the version they purport to be, if they >> exist at all. Hence I'm pleading for docs that match what the repo >> installs. >> >> I have an APC 1500wa, now several years old. Its front panel display >> has been asking for a new set of batteries for at least 5 years, but due >> to my now passed wife having COPD, a 20kw kohler in the back yard has an >> under 10 second startup time. So this machine runs normally for that >> time period. And nut is not running, fails to start since bookworm. And >> I have NDI why. The APC OTOH is doing what I bought it for. >> >>> Hope this clarifies a few points?It does indeed, thank you.? one final suggestion. incorporate into your sig, a download address, making an update a 1 click process to pull a fresh tarball.>> Thanks for reading this far, Jim. >> >>> Jim Klimov >> Cheers, Gene Heskett, CET. >> >> -- >> "There are four boxes to be used in defense of liberty: >> soap, ballot, jury, and ammo. Please use in that order." >> -Ed Howdershelt (Author, 1940) >> If we desire respect for the law, we must first make the law respectable. >> - Louis D. Brandeis >> >> >> _______________________________________________ >> Nut-upsuser mailing list >> Nut-upsuser at alioth-lists.debian.net >> https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/nut-upsuserCheers, Gene Heskett, CET. -- "There are four boxes to be used in defense of liberty: soap, ballot, jury, and ammo. Please use in that order." -Ed Howdershelt (Author, 1940) If we desire respect for the law, we must first make the law respectable. - Louis D. Brandeis
BTW regarding docs being in sync and the historic nut-website snapshots,
since v2.8.3 the man pages and tools are also aware of the difference, and
generally point to relevant docs more thoroughly, e.g.:
````
:; /tmp/nut283/nut-2.8.3$ ./server/upsd -h
Network UPS Tools upsd 2.8.3 release
NUT network data server for UPS monitoring and management.
usage: upsd [OPTIONS]
...
For more information please Read The Fine Manual ('man 8 upsd') and/or
see
https://www.networkupstools.org/historic/v2.8.3/docs/man/upsd.html
Also check documentation and samples of ups.conf, upsd.conf and upsd.users
````
Which leads to the historic-page rendition with a disclaimer about its
nature:
> Two NUT websites
> This version of the page reflects NUT release *v2.8.3* with codebase
commited c0acf09af at 2025-04-21T23:59:59+00:00
> Options, features and capabilities in current development (and future
releases) are detailed on the main site and may differ from ones described
here.
````
:; man upsd | tail
...
Internet resources:
The NUT (Network UPS Tools) home page:
https://www.networkupstools.org/historic/v2.8.3/
Network UPS Tools 2.8.3 05/14/2025
UPSD(8)
````
(PS: And that date in the man page footer, of today's build from a freshly
fetched copy of the release tarball, is part of why these generated files
should not be in git)
Even the services are now (maybe a bit too) talkative about this. On
another system, with non-release NUT version pointing to the rolling
website:
```
:; systemctl status nut-server
? nut-server.service - Network UPS Tools - power devices information server
Loaded: loaded (/lib/systemd/system/nut-server.service; enabled;
vendor preset: enabled)
Active: active (running) since Fri 2025-05-02 00:47:38 CEST; 1 weeks 5
days ago
Docs: man:upsd(8)
https://www.networkupstools.org/docs/man/upsd.html
man:ups.conf(5)
https://www.networkupstools.org/docs/man/ups.conf.html
man:upsd.conf(5)
https://www.networkupstools.org/docs/man/upsd.conf.html
man:upsd.users(5)
https://www.networkupstools.org/docs/man/upsd.users.html
man:nut.conf(5)
https://www.networkupstools.org/docs/man/nut.conf.html
Process: 9702 ExecStartPre=/usr/bin/systemd-tmpfiles --create
/usr/lib/tmpfiles.d/nut-common-tmpfiles.conf (code=exited, status=0/SUCCESS)
Process: 9705 ExecStartPost=/bin/grep -E Units|Max open files
/proc/${MAINPID}/limits (code=exited, status=0/SUCCESS)
Main PID: 9703 (upsd)
...
```
So at least users have a lot more chances to see the docs relevant to their
NUT build, whether as man pages (presumed built and installed along with
it) or as a rendered on-line version-separated resource.
Hope this helps,
Jim Klimov
On Tue, May 13, 2025 at 6:58?PM Jim Klimov <jimklimov+nut at gmail.com>
wrote:
> Hello Gene,
>
> I read and nodded sometimes and caught myself thinking that I used to
> propose or agree with some of the points you make, but outgrew those.
>
> > ...makers claim...
>
> I suppose this means asciidoc makers (not e.g. UPS makers)? They are
> actually largely non-Windows, especially in the part about rendering books,
> presentations, local HTML pages or web sites. These are all
> platform-independent formats.
>
> > Holding someone's feet to fire for something
>
> Who are we to do so? Who are "nut folks"? A loose community
joined by an
> interest, with some persons more prominent in a given year. To require
> something of UPS makers, the wider community members actually have more
> legal leverage, as paying customers of this or that company delivering what
> they can claim a defective product, infringed right-to-repair
> (spec/protocol docs), etc.
>
> Core team and project as an entity has exposure that can be useful for
> vendors' marketing, and occasionally some things happened due to that.
But
> (sadly), there's no incantation like "Bow thyself to celebrity
BDFL, you
> evil corporation!" and so they would.
>
> As for civil discourse, anyone can post bugs and raise discussions;
> maintainers are not special in that regard. (And as said, paying customers
> can have a slightly upper hand when asking).
>
> > Those generated files are not tracked in Git.
> > But should be.
>
> Actually, no. At least not those with non-deterministic rendering results.
>
> There are quite a few files rendered and tracked by scripts in NUT
> recipes, and the massively multiplatform CI does make sure there are no git
> diffs as result of a build.
>
> Rendered docs have timestamps, renderer versions and whatnot embedded, and
> are hell to git-track.
>
> > packaged version in distros
>
> Their choice. And users'. If they go for stability and a well known
> landscape that changes slowly (backporting bug fixes to same baseline), or
> go with daily rolling builds - to each their own, there are pros and cons
> to both.
>
> > doc and code versions
>
> NUT docs are part of its code base so should closely match. Packages from
> a code snapshot deliver renders of its docs and should match.
>
> NUT website since 2.8.0 is rolling with current master, and historic
> snapshots are issued as part of release rituals to ~never change. So users
> of packages can go to a site with docs of their version.
>
> Hope this helps,
> Jim
>
> PS My condolences.
>
> On Tue, May 13, 2025, 17:45 gene heskett via Nut-upsuser <
> nut-upsuser at alioth-lists.debian.net> wrote:
>
>> On 5/12/25 09:46, Jim Klimov via Nut-upsuser wrote:
>> Comments from a CET's point of view.
>> > Hi Sam,
>> >
>> > Not really sure what you mean here. NUT documentation is
written in
>> > asciidoc, so that it is easy to combine from several source files
and
>> > render into man pages, HTML, PDF, etc. (which does go via docbook
XML
>> as a
>> > technical detail of asciidoc, and does result in some *roff files
as a
>> > technical detail of man page rendering, but in NUT sources/recipes
we do
>> > not directly care about either of those aspects). Allegedly there
are a
>> few
>> > quirks with Asciidoc as well (notably there are several renderers
out
>> > there, but any semblance of a formal standard and common testing
suite
>> was
>> > being discussed as brewing up on FOSDEM 2025), but it is pretty
>> convenient
>> > and light-weight once you get a hold of it.
>> But woefully incomplete, primarily because the makers claim one thing
in
>> their docs, but actually deliver something else. I don't consider
that
>> as a nut fault. However, since nut is the only one providing an
>> industry wide solution in the face of makers who have NDI what the
>> non-windblows world needs, I do fault the nut folks for not holding the
>> makers feet a little closer to the fire, stopping the lies and outright
>> BS this division of our industry is rife with.
>> > NUT "dist" tarballs, including release snapshots, do
include a copy
>> of
>> > generated man pages (probably in a *roff format) for the benefit
of
>> > end-users who only have a compiler and do not want to burden their
>> systems
>> > and build times with asciidoc/docbook/etc. tooling. So they can
just
>> build
>> > NUT programs, `make install`, and have them nicely documented out
of the
>> > box. Those generated files are not tracked in Git.
>> But should be.
>> > Full-scale builds such as for packaging are encouraged to have
the
>> full
>> > stack in the build agent (or build root) and re-generate these
>> documents.
>> > This might, depending on local settings, add distro watermarks
("NUT
>> pages
>> > as part of OS XXX docs"), apply distro-wide build timestamp,
use the
>> *roff
>> > version that OS is comfortable with, or whatever.
>> >
>> > Also note that since NUT v2.8.3 we added support for
`configure`
>> options
>> > to assign man section codes (numbers or not) for systems that do
not
>> follow
>> > suit of Linux and BSD numbering (e.g. in Solaris/illumos, the
system
>> > commands are historically not "8" but "1m").
Previously this required
>> > strange patch files on packager side, a burden to be
revised/updated for
>> > each NUT release; now it requires just a few configure options
that can
>> be
>> > left in the recipe once and forever.
>>
>> Another point, you are about o make a 2.8.3, but the latest debian is
>> 2.8.0. More feet to hold up to the fire. We can't use either to
their
>> full capability because the docs don't match what we read here.
The
>> docs don't even seem to apply to the version they purport to be, if
they
>> exist at all. Hence I'm pleading for docs that match what the repo
>> installs.
>>
>> I have an APC 1500wa, now several years old. Its front panel display
>> has been asking for a new set of batteries for at least 5 years, but
due
>> to my now passed wife having COPD, a 20kw kohler in the back yard has
an
>> under 10 second startup time. So this machine runs normally for that
>> time period. And nut is not running, fails to start since bookworm.
And
>> I have NDI why. The APC OTOH is doing what I bought it for.
>>
>> >Hope this clarifies a few points?
>>
>> Thanks for reading this far, Jim.
>>
>> > Jim Klimov
>>
>> Cheers, Gene Heskett, CET.
>>
>> --
>> "There are four boxes to be used in defense of liberty:
>> soap, ballot, jury, and ammo. Please use in that order."
>> -Ed Howdershelt (Author, 1940)
>> If we desire respect for the law, we must first make the law
respectable.
>> - Louis D. Brandeis
>>
>>
>> _______________________________________________
>> Nut-upsuser mailing list
>> Nut-upsuser at alioth-lists.debian.net
>> https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/nut-upsuser
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://alioth-lists.debian.net/pipermail/nut-upsuser/attachments/20250514/ff896e99/attachment.htm>