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.
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.
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.
Hope this clarifies a few points?
Jim Klimov
On Mon, May 12, 2025 at 1:50?PM Sam Varshavchik <mrsam at courier-mta.com>
wrote:
> Jim Klimov via Nut-upsuser writes:
>
> > Alas, with NUT's long history starting when computers were tools
of the
> > relatively few engineer nerd types, much of the documentation remains
> > "elitist".
> >
> > Partially due to this, I've started a new manual page (after
release
> v2.8.3)
> > so people can get a reasonable overview of the NUT layering and some
> > practical caveats by uttering `man nut`.
>
> It also doesn't help things that nroff has survived since ancient
times,
> back when dinosaurs roamed the Earth.
>
> nroff is long overdue for retirement. It served its purpose. But there
> are
> better tools out there, now. Sadly, Linux still insists on keeping this
> fossil.
>
> > Surprisingly, there was no such
> > thing for over the quarter of a century that the project has been out
> there!
>
> That's about the timeframe back when I started writing my manual pages
in
> Docbook XML, and generating beautiful HTML documentation from it, as well
> as
> legacy man pages.
>
> I even started a project that successfully converted all Linux manual
> pages
> from nroff into Docbook XML. Sadly it did not get any traction, and I
> shut
> it down a few years ago.
>
> I humbly suggest that you use Docbook XML for your original source, and
> then
> just have it spew out nroff, and also have something nice that can be
> thrown
> onto a web server.
>
> _______________________________________________
> 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/20250512/dd47caff/attachment.htm>
Jim Klimov writes:> ? NUT "dist" tarballs, including release snapshots, do include a copy of > generated man pages (probably in a *roff format) for the benefit of end-usersYes, I do the same. I store Docbook XML in git, and when a packaged tarball gets prepared it includes the generated nroff man pages, for direct installation. I'm not familiar with asciidoc, but that workflow seems analogous. When you wrote that you were contemplating large scale man page updates I thought you meant manual editing of nroff. Scary, scary thought?> ? 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.Yowza. Solaris is still around? -------------- next part -------------- A non-text attachment was scrubbed... Name: not available Type: application/pgp-signature Size: 228 bytes Desc: not available URL: <http://alioth-lists.debian.net/pipermail/nut-upsuser/attachments/20250512/c94de4aa/attachment.sig>
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 KlimovCheers, 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