Hi Arsen, On Sun, Sep 21, 2025 at 02:02:16PM +0200, Arsen Arsenović wrote: > IMO, docs should not be outsourced from the project they correspond to. > Doing so makes them harder to install and keep accurate to the installed > version of what they target.
I could maintain them within the coreutils repo, if that's preferred. > > I understand GNU's stance on manual pages, and that you might not be > > interested in improving them much, but maybe you're open to them being > > improved elsewhere. > > It's frankly better to improve them inline. But I'd rather see us move > past the woefully inadequate 'man' documentation system, I disagree with man(1) being inadequate. :) > for instance by > providing an info viewer users are more likely to find usable (though, I > struggle to see why the current standalone info viewer is so > problematic, especially since I taught multiple people who got the hang > of it fairly easily). Installing pages with a richer markup (HTML > perhaps, or a new format that can be easily rendered on-the-fly to > reflowable text or HTML) would also be nice. The current format is one > of lightly marked up catfiles, and so isn't great in modern > environments. I think what you don't like of man(7) documentation is man(1) and not man(7). A more featureful man(1) viewer could be developed, and some people have attempted to build one, where key bindings could for example show an index of a page. Jumping from one page to another will also be possible soon, with the recently added .MR macro for manual-page references. (And in the PDF book, we already have that in old pages, with some heuristics that work reasonably well.) > Given that coreutils manpages are generated from help text, adding a > paragraph to the tsort help text would probably suffice (see sort for an > example). > > > The Linux man-pages project already documents the GNU C library, so it > > wouldn't be extraneous to also take ownership of the coreutils manual > > pages. > > And it's a source of problems; they don't always correspond to the > installed version of the libc, That's not very important. The manual pages keep old information, so as long as you have the latest pages, they're good for whatever glibc is installed. Of course, we are missing a few pages, but there are few. And of course, if you have bleeding edge glibc, there are more chances some details may be missing. > don't get installed with libc, and have > lead to the actual manual being somewhat forgotten. In general, the manual pages are more accurate than glibc's own manual, as even some glibc maintainers have acknowledged in the past, so I wouldn't worry much about this. Have a lovely day! Alex -- <https://www.alejandro-colomar.es> Use port 80 (that is, <...:80/>).
signature.asc
Description: PGP signature
