Hi Alex, Alejandro Colomar <[email protected]> writes:
>> 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. That's alright, I'm sure. >> 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. :-) The subject said "GNU" so I was intentionally speaking in generalities. > (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.) Git falls back to the "Pro Git" book also. IMO manuals should largely be like the "Pro Git" book, but also incorporating references (git is near this but splits the two, as you know). > [...] >> >> 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. The latter is probably fine, but you clarified you intend to keep them in coreutils' distribution, so that solves that issue. >> 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. The division between the two is somewhat unique to free software projects, so I can see the struggle :-) > 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. Yep ;) -- Arsen Arsenović
signature.asc
Description: PGP signature
