Re: proc(5)'s sashimi

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1.1: Type: text/plain, Size: 4339 bytes --]

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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]