Hi, Mike Hodson <[email protected]> writes:
> On Sat, Sep 20, 2025, 10:34 Pádraig Brady <[email protected]> wrote: > >> On 20/09/2025 17:08, Alejandro Colomar wrote: >> > Hi! >> > >> > GNU coreutils manual pages are to some degree incomplete. I was told >> > today that "tsort(1) is a bad joke". I wonder if you'd be interested in >> > moving the maintenance of the manual pages of GNU coreutils to the Linux >> > man-pages project, where I could take care of them, and improve their >> > contents. >> > >> > 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. >> > >> > 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. >> > >> > What do you think? >> >> The man pages are programmatically generated from the sources. >> I.e. $cmd --help is processed by help2man. >> >> All of the man pages have links to the info docs for full documentation. >> >> Any concise improvements for the man pages are gladly accepted, >> but would be applied to the source (also for --help). >> >> cheers, >> Padraig >> > > My initial reason for being a part of this list was because I found the > manual pages to be lacking. > > I do not like 'info'. I do not like hypertext because my brain remembers > where something is in a linear file far easier. I want a single page that > is text searchable for one word that I am looking for that literally > contains every single bit of documentation about the product. You can search 'info'. Hit C-s for a regex search, repeat that input to find next match. You can also do an index search with the 'i' key. For instance, if you run 'info coreutils', you can type: i --dired RET ... and it will find you documentation for the --dired flag. The effect can be gotten also via just: info coreutils --index-search=--dired > I have mentioned that I actually am _exceedingly happy_ with the way > that mplayer/ffmpeg manual pages literally have everything all in one > place. I cannot claim the same for any of the gnu core utilities > because the info command is absolutely mind-boggling in terms of > finding something that I need to find easily in the same place. I think this is a result of the info tutorial being packages with Emacs(!) rather than the standalone viewer. The official reason is that the latter emulates the former, but the real effect of this is that the vast majority of potential info users simply won't have access to this tutorial. It is quite disheartening. I intend to try and convince distros to fix this (I've started the process in Gentoo but apparently it stalled at some point.. whoops), but I am not sure how effective I will be. > I absolutely know for a fact that the command line arguments for > ffmpeg will exist in its manual page, and I know that I don't have to > search through perhaps five or 10 separate hyperlinked sections just > to find what I need. I simply use textual search. See above for textual search. > Can 'info' be made to produce this single flat textual representation of > its hypertext? Yes, if the output is not a TTY it will simply dump the contents of the info manual (filtered to remove special markup and tables in the raw info format, and joined back together if it was generated as split). So, 'info foo | less' does the same thing 'man' does. But then you lose index searching and link following, of course. ... but now that I said that, I remembered 'less' supports tag files. Perhaps we could add a mode of operation that just generates a less-style tag file and launches less on the contents of the info page, like OpenBSD 'man' viewer does, and provides a tag file with all intex entries and nodes. Still, one can't follow links, but that's the issue with pagers anyway. BTW, the info viewer, if looked at as an Emacs-like text editor, acts on a large text file, that is the entire info document, displaying only one node at a time (but, the entire document is there; searches cross node boundaries). > If not, then my opinion is still what it was back a few years ago: I > would rather have the complete text from the info pages simply copied > into a manual page for searching linearly and reading without having > to learn a completely different tool which in my 27 years of Linux > computing I have yet to understand in any way shape or form other than > knowing I hate it and it causes me grief every time I attempt to look > at anything detailed about a coreutil command. I lose my place, > cannot get back to what I was previously looking at easily, and > usually just give up. If you're open to it, may I suggest installing emacs documentation, from whatever distro you're using, and running: info '(info)Help' The file that you need to get installed is info.info The effect of this is the same as opening the info viewer and hitting 'h' on your keyboard (that, as info tells you on startup, opens the tutorial). It should turn the info viewer from an foreign mess into something quite usable. Again, I hope to rectify the situation with the documentation not being installed at some point soon. > To me, the command line is not a place for odd to navigate > hypertext. I am very comfortable with flat text files and my brain > thinks in this fashion. If I want hypertext I will load Chrome. I disagree - terminals are quite capable of this (and we aren't the only ones with this insight, see, for instance, the vim helptext system, which does the same thing, as well as *some* pagers designed for 'man'). BTW, there's also an alternative viewer, 'pinfo', that you could try. I've never used it so I can't be sure how good or bad it is. Have a lovely day. -- Arsen Arsenović
signature.asc
Description: PGP signature
