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. -------------- 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/fa7a5350/attachment.sig>
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>
I will disagree. [n,t]roff is a *nix wide standard that works well. The problem with most other doc formats these days is that they assume sime big bloaty graphics environment exists, and that's just not always true! *roff/man will give outstanding doc on nothing more than a vt100 terminal session (ssh, serial, whatever) with almost zero installed footprint. If your option can still do that, then perhaps, but otherwise, it condemns server users to have no usable doc. Remember, docs are there to help the user/reader, not necessarily to be a dumbed down process for the writer (although both have thier place). Another choice would be a <whatever> ==> nroff translator, and give the end user the choice. (To that end, I've never seen another doc format that consistently worked, and didn't have a huge footprint . . . ) Just my $.02 . . . if it isn't broken, don't fix it . . . - Tim On May 12, 2025 7:40:31 AM EDT, 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. >-- Sent from my Android device with K-9 Mail. Please excuse my brevity. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://alioth-lists.debian.net/pipermail/nut-upsuser/attachments/20250512/e8b740e5/attachment.htm>