Hi Arsen, On Thu, Sep 25, 2025 at 04:04:50PM +0200, Arsen Arsenović wrote: > Hi Alex, > > Alejandro Colomar <[email protected]> writes: > > > [[PGP Signed Part:No public key for EB89995CC290C2A9 created at > > 2025-09-21T14:53:21+0200 using RSA]] > > 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. > > That'd be significantly better, yes, if by that you mean that they'd > become part of the coreutils (et al) distribution.
I'd guess that if the pages are within the coreutils.git repo, the build system will package them with the rest of the distribution, so yes. However, I'm unable to deal with autotools, so that would need to be handled by some of you. But yes, that's the idea. I can maintain the contents of the pages. > >> > 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. :) > > Unfortunately, it is. A collection of linear mostly-unrelated pages in > predetermined shape simply cannot document complex software, a > hierarchical approach is non-negotiable. > > libc, (most of) the syscall API and coreutils are a lucky case in that > they are, fundamentally, large collections of *very* simple bits > (functions and programs), Luckily, we're discussing the documentation of coreutils. :-) (Actually, git(1) also has more-or-less hierarchical manual pages for documentation, and it works quite well, IMO. But I agree it's not always the case. PCRE is a counter-example, where I can't find anything.) [...] > >> 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. > > This addresses half of the issue (what if the pages are old?), A solution for old pages is cloning them from the upstream repo, and running 'make && sudo make install'. But that's not for everybody. Alternatively, kindly ask your distribution manager to package a recent version of the pages. After all, they're just text, so stability isn't very important. > and still > leaves the fact its a separate software distribution unsolved. The issue there is that the distinction between manual pages for the kernel and for glibc isn't very clear. That's why we have one project that covers all, instead of duplicating the information, or having incomplete information in either side. But that's not an issue in coreutils, as we could have them distributed with the binaries. > >> 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. > > That is precisely the problem I was referring to. Ah, I thought you were worried users would forget about it. If the maintainers forget about it, that's a problem for users of info manuals, indeed. > > Have a lovely day! You too! :-) Alex > -- > Arsen Arsenović -- <https://www.alejandro-colomar.es> Use port 80 (that is, <...:80/>).
signature.asc
Description: PGP signature
