Hi Günther! Oskari! On 2023-08-15 13:41, Günther Noack wrote: > On Mon, Aug 14, 2023 at 10:10:52PM -0500, Oskari Pirhonen wrote: >> On Mon, Aug 14, 2023 at 16:06:16 +0200, Alejandro Colomar wrote: >> OTTOMH, I can think of some prior art WRT to "namespaced/split man >> pages" in at least git, btrfs-progs, and as of recently it seems, >> cryptsetup. > > There are also the ioctl_* man pages which are similarly split up > and which are prior art within the man-pages repo. Good reminder! Yup. > > It seems like a good idea to split up proc(5). 👍 > > —Günther > Thanks :) On 2023-08-15 05:10, Oskari Pirhonen wrote: > On Mon, Aug 14, 2023 at 16:06:16 +0200, Alejandro Colomar wrote: >> Hi! >> >> The day has come to cut the proc(5) tuna fish in very little pieces. > > This is a great idea. Large man pages, while no problem for me > personally, are more often than not very intimidating and overwhelming > for newcomers. Thank you too :) > >> As a first step, I'm pasting the contents of proc(5) into little >> files, without changing any contents (not even the formatting). For >> example see the two files at the bottom of this email. >> >> I'd like to hear any comments before pushing such a change to the repo. >> I'll soon post a branch called 'proc' to my repo (I'll ping when it's >> done), so you can observe the changes). >> >> One of the questions I have at the moment is how should we call the >> pages, and what should we write in the TH and NAME. Branden, do you >> have any comments on that? I used underscores for the page title and >> file name, but for the NAME I used slashes (so the actual name of the >> interface). I didn't do any italics in the name, though, so /pid/ is >> no special in the name. >> > > OTTOMH, I can think of some prior art WRT to "namespaced/split man > pages" in at least git, btrfs-progs, and as of recently it seems, > cryptsetup. Some samples: > > I find the case of programs (man1) slightly different. The point is that the command syntax is with a space, man man(1) happens to allow a space to be used as if it were a space: $ man -w git range-diff /usr/share/man/man1/git-range-diff.1 which nicely fits with the command syntax: $ git range-diff In the case of slashes, we have a deeper problem, which is that there's no way to have a slash in the actual pathname of a page, since the man sections are flat. man(1) doesn't seem to be able to index according to the NAME within the page if it has slashes (or I didn't know how to make it work). Also, since man accepts a pathname in place of the page name, `man /proc` would be ambiguous, so we really can't have slashes there. '_' and '-' are equal to me, and in general, I tend to favour '_' in identifiers all else equal (maybe it's Branden's fault, or maybe it's C). [...] > > So, for these examples, perhaps proc-pid-gid-map.5 and proc-pid-attr.5 > to fit in with our friends from above. Similarly for the title. I think > NAME should match how it exists on the filesystem (so leave that how you > have it now). > > The /proc/pid/gid_map is an interesting case. The file itself has an > underscore, but having mixed dash and underscore (proc-pid-gid_map) > feels ugly even though it's technically more correct. I'd like to respect characters that can be respected. Since '_' is in the name of the actual interface, I'd like to respect it in the manual page. > A potential > solution to that problem is to have the man page be proc-pid-gid-map.5 > and install a proc-pid-gid_map.5 symlink pointing to the page. Or vice > versa. BTW, there' are /proc interfaces that have a '-' in their name: /proc/key-users > > - Oskari > > PS: A special shoutout goes to git. The fact that `git help $THING` > pulls up the man page for git-$THING, combined with `git help` alone > providing some nice starting points, is a huge plus when it comes to the > discoverability of its documentation. Yup, git(1)'s manual pages are quite nicely organized. A rare thing, I'd say. > > So in case whoever wrote that happens to read this -- many thanks <3 +1 Cheers, Alex -- <http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
