Hi,
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), 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).
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,
one must know a little bit about Unix organization of manual pages, and
use some pipes:
alx@debian:/usr/share/man$ find man2 -type f | sort | xargs zgrep
FD_CLOEXEC -l
man2/accept.2.gz
man2/dup.2.gz
man2/epoll_create.2.gz
man2/eventfd.2.gz
man2/execve.2.gz
man2/fanotify_init.2.gz
man2/fcntl.2.gz
man2/inotify_init.2.gz
man2/memfd_create.2.gz
man2/memfd_secret.2.gz
man2/open.2.gz
man2/perf_event_open.2.gz
man2/pidfd_getfd.2.gz
man2/pipe.2.gz
man2/signalfd.2.gz
man2/socket.2.gz
man2/timerfd_create.2.gz
(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.)
But I admit that the splitting of proc(5) and other pages has regressed
this feature that was present, and in some sense, this is something that
info(1) does right-ish: documentation is nested in levels, and you can
start from the top level if you don't know what you're looking for.
I had an idea that somehow relates to the original format in which Unix
documentation was presented, and which thanks to Deri James we have now
again in this project: a typeset book covering the entire set of manual
pages. There, one can search for anything, and it will be found.
We could also have something similar in the terminal, and not as huge as
the entire book. It would be mini-books, for some topics, such as
proc(5).
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;
(Actually, I'd also build a proc_pid(7) page, which would include only
the proc_pid_*(5) pages, and similarly for other /proc/ subdirs. And
then proc(7) would only source those subdir pages.)
Then, one could consult proc(5) as documentation exclusively for the
/proc directory itself, or one could consult proc(7) as a book that
describes both /proc and its contents.
And the maintenance would be as simple as it is now, because the
contents are in the small pages only. Updating the link books should be
easy (and I'm thinking of a script to create them at build time, so it
should be fine).
What do you think?
I'm CCing Doug, as he probably has an opinion as editor of the V7 Unix
manual, and Michael as the reporter of the regression. I'm also CCing
groff@, as they probably have some opinion on multi-.so pages (and thus,
multi-.TH pages).
Have a lovely day!
Alex
--
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).
signature.asc
Description: PGP signature
