On Fri, Jan 24, 2025 at 07:47:00AM +0100, Ingo Schwarze wrote: > G. Branden Robinson wrote on Wed, Jan 22, 2025 at 08:47:20PM -0600: > > At 2025-01-22T07:10:54+0100, Ingo Schwarze wrote:
> -a, --all > By default, man will exit after displaying the most suitable > manual page it finds. Using this option forces man to display > all the manual pages with names that match the search criteria. > > man-db is quite inconvenient in this respect because "man -a crontab" > first opens only crontab(1), so you cannot compare to crontab(5) because > that is not yet displayed. When you are done reading crontab(1), you > have to press 'q' and then you need another (!!) keystroke (RETURN) > to get to crontab(5). From there, you have no way at all to get back > to crontab(1): when you press 'q' there, the whole program terminates > and drops you back to the shell. I wouldn't be averse to changing this, especially if there's prior art in mandoc. Perhaps somebody could file a bug report as a reminder? (These discussion threads are generally so extremely long and verbose that I rarely read all of them and only happened to notice this bit by luck.) > So fortunately, man-db and mandoc agree about the basic meaning > of both -a and -k. That's hardly a coincidence though: > > https://mandoc.bsd.lv/man/man.options.1.html > > -a display all matching manual pages > man: 4.3BSD-Tahoe (June 1988), Eaton (before July 7, 1993; 1990/91?); > OpenBSD, FreeBSD, NetBSD, man-db, man-1.6, illumos, Solaris 9-11 > apropos, whatis, mandoc: OpenBSD 5.7 (August 27, 2014) > > only display items that match all keywords > apropos: man-db (Aug 29, 2007) > > use all directories and files for mandoc.db(5) > makewhatis: OpenBSD 5.6 (April 18, 2014) > > [superseded by -T ascii] ASCII output mode > troff: Version 7 AT&T UNIX (January 1979) > groff: probably before groff-0.4 (before July 14, 1990) > > So, while man-db clashes *with itself* in so far -a has > two conflicting meanings in man(1) and apropos(1), it actually > agrees with mandoc (as far as that is still possible despite > its internal conflict). Adding -a with a conflicting meaning is an unfortunate mistake I made in 2007, indeed. Sorry. > Please avoid adding options to man(1) if you can, and if you > cannot avoid it, then *please* do consult > https://mandoc.bsd.lv/man/man.options.1.html > before doing so in order to minimize the risk of clashes. In recent years (or even decades) I've generally tried to avoid adding short options at all, but I'm aware of man.options(1) and would indeed consult it nowadays. -- Colin Watson (he/him) [cjwat...@debian.org]
