Hi Ingo, On Tue, Sep 23, 2025 at 06:48:51PM +0200, Ingo Schwarze wrote: > Hello Alejandro, > > Alejandro Colomar wrote on Tue, Sep 23, 2025 at 12:50:54PM +0200: > > > Michael Kerrisk reported to me that he preferred the old proc(5) page, > > where everything under /proc was in a single page. > > > > The rationale is that it was possible to search through that page with > > less(1), and you didn't need to know where it was what you were > > searching for. > > > > He proposed reverting the splits of proc(5), > > I agree that is indeed approaching the task at the wrong level. > > Showing multiple manual pages at the same time is a job for the > manual page viewer man(1), not for the manual page formatter, > for example nroff(1) or mandoc(1). > > For example, with the mandoc implementation of man(1): > > $ man true false > > shows the true(1) manual page, followed by a separating line: > ------------------------------------------------------------------------------ > followed by the false(1) manual page. The entire output is shown in > a single less(1) instance as if it were a single output file, with no > need to type ":n" to get to the next manual page. Consequently, it > is trivial to search for strings across the whole output, across > all pages, with just the less "/" command, or to perform semantic > searches across all pages with just the less ":t" command.
I prefer your approach over that of man-db, at least per how you
describe it. I've never used mman(1) before with more than one page,
and it seems to be broken at the moment in Debian Sid:
alx@debian:~$ mman false true | cat
mman: outdated mandoc.db lacks false(1) entry, run makewhatis
/usr/share/man
mman: outdated mandoc.db lacks true(1) entry, run makewhatis
/usr/share/man
FALSE(1) User Commands
FALSE(1)
NAME
false - do nothing, unsuccessfully
SYNOPSIS
false [ignored command line arguments]
false OPTION
DESCRIPTION
Exit with a status code indicating failure.
--help display this help and exit
--version
output version information and exit
Your shell may have its own version of false, which usually
supersedes
the version described here. Please refer to your shell's
documentation
for details about the options it supports.
AUTHOR
Written by Jim Meyering.
REPORTING BUGS
GNU coreutils online help:
<https://www.gnu.org/software/coreutils/>
Report any translation bugs to
<https://translationproject.org/team/>
SEE ALSO
Full documentation <https://www.gnu.org/software/coreutils/false>
or available locally via: info '(coreutils) false invocation'
Packaged by Debian (9.7-3)
Copyright © 2025 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later
<https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute
it.
There is NO WARRANTY, to the extent permitted by law.
GNU coreutils 9.7 June 2025
FALSE(1)
------------------------------------------------------------------------------
()
()
?�????????�TÑnÓ0?}ÏW\[u00FA]Â?�Ë6!D��ºµÝ2uM�¤B?áÁMn?Cb?Ûi׿çÚe?Þ�úÐÚ>ç�{î¹eù?æ?¬£?�¢y¸ÜBö?¦°?W�W?¡�#7P¡DÍ-�°;A�MwÝr
Wìý;vÅ?�=@�l?0º?Áè±�?×ï®ßÓ÷ûõ?
¥±·¢1ð�}
³�Awª%�Ò�?�>Àzö´?¬î?òK(?Hek!«1�¾(Ð�}ß4'ÿ2Ý®£8Ó�Ý�??_ó}��E%©JIµ<-4�4p]õ-JkòI¾O¾?l§?�GEq?Fk?ëÉç�ô.
ýaÀÈ�YY?�'àe)¬P�7P¢)´èÜ/òAcÀâ8X<?²IØ?8?ËmoHH� d) n©��F�W1?¿Í/óKç£+]
Ó5ü?Ô³ñæ�k?�ôï×?Ô�ª:�êm×[ø}BeöJ·Ükú�$][Õk0ÄØ@Kü5?�&k@?å?V{oÈ?�µ(jèMÏÉkÒÛÑ?¤v?[ãðúÜþ��vÍ3�¸An?4îi¨VÁi(ùÚÐ$???/-
��·Ü%�ï¨?pÌÊ{iH�«Ù)m�I4�Ù&{��à�?Ö¢t¹{?-<á
5?z~3J?q�dáú?n7÷é(ø7oJú?8K§ð©¶¶3ÓÉäx<²JöLéjbÔÞ?¹ÆÉ?�|ö9IÐIñÓ·�KÓ�íÝõ�qm?d?]vZ}ÇÂz^�¼uLNcºXÀl�F£`I1þ×�ÿVåftVF.ò?�ÈwB£
?®�àS�?È/øÏ�?÷Æ?�n?ªð?ݵÏ�£�yñ�Wç¥�ãNÐJ_Ð�æ�7oüý�êNZTµ%ÖBù��¥F�ô·@Xª^��x?¡,��D��Bq?¯?7o§à�Bß�?Ý?õ@�Qb�ö_ZoÎX3©º�Õ¶m>�93·?ôÙ»ò/þL]ÜÀéðÇ4�¢æ²B¿?ôw
�¥°öÖ¥þ��bëxÖ?|�%Él�mÇ?è¢�Ï?4??üÖeÎÛÒð#?~?çé$�#???
()
> At the same time, even flipping through the pages page-by-page
> becomes slightly easier because
>
> /^- n n n ? ENTER n n n
>
> is slightly less typing effort than:
>
> :n :n :n :p :p :p
>
> > which I refuse to do, but
> > I think he has a point. I refuse to do so, because I agree with
> > something Doug complained about, which is that some of the pages we have
> > are not really pages, but rather entire books, and for me it has
> > important maintenance costs (plus, it's easier for me to find stuff with
> > small pages; but that seems to be subjective, depending on your
> > specific needs and experience).
>
> Keeping pages down to a reasonable size also helps users because
> making head or tail of a gigantic page is hard, and reading a page
> of a reasonable size is much easier. Stuff like
>
> https://man.openbsd.org/rpc.3
> https://man.openbsd.org/PEM_read_bio_PrivateKey.3
> https://man.openbsd.org/compress.3
>
> places serious strain on user's eyes, including because the place
> where any particular function is discussed in the SYNOPSIS and
> DESCRIPTION and RETURN VALUES is then so far apart.
+1
Another thing is when indenting stuff, there's so many levels of
intendation (think of the old proc(5)), and each level might be hundreds
of lines, that I have a really hard time tracking down where things
start and end.
In general, catenating stuff is trivial, but undoing that operation is
not.
> > Right now, the only way for searching something across several pages is
> > going to /usr/share/man/, and doing a manual search there. This was
> > already true in the general case, before the split of pages. For
> > example, if one wanted (or wants) to know where FD_CLOEXEC is specified,
>
> $ man -ak Dv=FD_CLOEXEC
>
> puts me into less(1), where i type
>
> :tFD_CLOEXEC or /FD_CLOEXEC
>
> to my heart's content.
Yup; I remembered that while discussing with Michael. :-)
> [...]
> > (We may want for example an FD_CLOEXEC.2const manual page to link to the
> > canonical page for it, but I'm not yet decided, because that could mean
> > lots and lots of new link pages. I'm open to comments about that.)
>
> You could simply add FD_CLOEXEC as a name to the NAME section that you
> consider canonical for defining FD_CLOEXEC, such that users can simply
> type "man FD_CLOEXEC". We don't to that in OpenBSD because when
> semantic search is available, "man FD_CLOEXEC" provides little benefit
> over "man -ak Dv=FD_CLOEXEC" or "man -ak any=FD_CLOEXEC", so just
> as you consider additional links in the file system excessively noisy,
> we consider even (less noisy) additional name section entries too noisy.
> Don't forget that defined constants are significantly more numerous
> in some APIs than function names, so there is a real danger to cause
> readers to miss the forest among all the additional trees.
Yup; that's what has stopped me from doing that in the past, and I still
don't think I'll do that. I prefer leaving it up to a trivial Unix
pipe searching within /usr/share/man (for non-trivial needs), or man -K
for trivial needs.
This is quite easy:
alx@debian:~$ man -awK FD_CLOEXEC
/usr/local/man/man3/popen.3
/usr/local/man/man3/posix_spawn.3
/usr/local/man/man3/shm_open.3
/usr/local/man/man3/catopen.3
/usr/share/man/man3/catopen.3posix.gz
/usr/share/man/man3/close.3posix.gz
/usr/share/man/man3/dup.3posix.gz
/usr/share/man/man3/exec.3posix.gz
/usr/share/man/man3/fcntl.3posix.gz
/usr/share/man/man3/fdopendir.3posix.gz
/usr/share/man/man3/iconv_open.3posix.gz
/usr/share/man/man3/open.3posix.gz
/usr/share/man/man3/pipe.3posix.gz
/usr/share/man/man3/posix_spawn.3posix.gz
/usr/share/man/man3/posix_spawn_file_actions_addclose.3posix.gz
/usr/share/man/man3/posix_spawn_file_actions_adddup2.3posix.gz
/usr/share/man/man3/posix_typed_mem_open.3posix.gz
/usr/share/man/man2/eventfd.2.gz
/usr/share/man/man3/catopen.3.gz
/usr/share/man/man3/shm_open.3posix.gz
/usr/share/man/man3/system.3posix.gz
/usr/share/man/man3/popen.3.gz
/usr/share/man/man3/posix_spawn.3.gz
/usr/share/man/man3/shm_open.3.gz
/usr/local/man/man2/inotify_init.2
/usr/local/man/man2/memfd_create.2
/usr/local/man/man2/pidfd_getfd.2
/usr/local/man/man2/dup.2
/usr/local/man/man2/pipe.2
/usr/local/man/man2/socket.2
/usr/local/man/man2/accept.2
/usr/local/man/man2/eventfd.2
/usr/local/man/man2/signalfd.2
/usr/local/man/man2/fanotify_init.2
/usr/local/man/man2/fcntl.2
/usr/local/man/man2/epoll_create.2
/usr/local/man/man2const/F_DUPFD.2const
/usr/local/man/man2/memfd_secret.2
/usr/local/man/man2/open.2
/usr/local/man/man2/timerfd_create.2
/usr/local/man/man2const/F_GETFD.2const
/usr/local/man/man2/execve.2
/usr/local/man/man2/perf_event_open.2
/usr/share/man/man2/accept.2.gz
/usr/share/man/man2/dup.2.gz
/usr/share/man/man2/epoll_create.2.gz
/usr/share/man/man2/execve.2.gz
/usr/share/man/man2/fanotify_init.2.gz
/usr/share/man/man2/fcntl.2.gz
/usr/share/man/man2/inotify_init.2.gz
/usr/share/man/man2/memfd_create.2.gz
/usr/share/man/man2/memfd_secret.2.gz
/usr/share/man/man2/open.2.gz
/usr/share/man/man2/perf_event_open.2.gz
/usr/share/man/man2/pidfd_getfd.2.gz
/usr/share/man/man2/pipe.2.gz
/usr/share/man/man2/signalfd.2.gz
/usr/share/man/man2/socket.2.gz
/usr/share/man/man2/timerfd_create.2.gz
/usr/share/man/man7/systemd.directives.7.gz
/usr/share/man/man7/fcntl.h.7posix.gz
And when I need more complex stuff, I can do just anything with pipes.
It requires knowing where the source code is located, but people with
those needs will most likely know where the manual pages are installed,
and that they might be compressed, so I'm not too worried.
> > My idea is having a proc(7) page that would essentially be built as:
> >
> > $ find man5/ | grep proc | sort | sed 's/^/.so /' > man7/proc.7;
>
> I'd very strongly advise against that, for more than one reason.
> Neither of the two manual page formats is well-suited for
> concatenating input files and formatting them in a single run
> of the formatter. Doing that tends to cause lots of unexpected
> and hard to diagnose issues. Instead, such a job should be done
> by man(1): let the formatter format each page individually, then
> concatenate the results, *never* concatenate the source code.
I find recent groff(1) being quite able to handle multi-.TH pages
I am going to agree to not do this for users, but I do this often for
myself. I often want to see all the SYNOPSYS or STANDARDS (or whatever)
sections of *all* manual pages under man2 and man3, and what I do is
cat(1) them together, extract the right sections (plus the TH lines)
with sed(1) (actually, I first do this, then catenate), and then pipe to
'man /dev/stdin'. It works quite nicely (with recent groff(1)).
> Also, this would result in massive multiplication of installed
> text (wasting space)
.so pages don't duplicate text, do they? Or you mean in indices?
> and in massive degradation of apropos(1)
> usefulness as proc(7) would appear in each and every search result
> with a semantic seach tool like mandoc apropos(1)
Yep, this would be an important problem.
> - or showing up in
> almost no search results with non-semantic seach tools like man-db
> because the man-db implementation of database generation cannot handle
> concatenated manual pages.
>
> Manual pages using fragment concatenation are most notorious for
> causing all kinds of trouble. IIRC, zsh(1) used to be a particularly
> egregious example (i hope i don't misremeber which shell that was,
> sorry to them if i do), but even they stopped concatenating at some
> point unless i'm mistaken.
>
> [...]
> > What do you think?
>
> I expect you will be very surpised in how many different ways such
> a scheme will bite you if, God forbid, you ever try it for real.
Nah, I've been convinced of not trying it. Thanks! :)
Have a lovely day!
Alex
--
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).
signature.asc
Description: PGP signature
