Re: proc(5)'s sashimi

[Oskari Pirhonen <xxc3ncoredxx@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 3854 bytes --]

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.

> 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:


$ MANWIDTH=72 man git-range-diff | head
GIT-RANGE-DIFF(1)             Git Manual             GIT-RANGE-DIFF(1)

NAME
       git-range-diff - Compare two commit ranges (e.g. two versions
       of a branch)

SYNOPSIS
       git range-diff [--color=[<when>]] [--no-color] [<diff-options>]
               [--no-dual-color] [--creation-factor=<factor>]
               [--left-only | --right-only]


$ MANWIDTH=72 man btrfs-send | head
BTRFS-SEND(8)                    BTRFS                   BTRFS-SEND(8)

NAME
       btrfs-send - generate a stream of changes between two subvolume
       snapshots

SYNOPSIS
       btrfs send [-ve] [-p <parent>] [-c <clone-src>] [-f  <outfile>]
       <subvol> [<subvol>...]


$ MANWIDTH=72 man cryptsetup-resize | head
CRYPTSETUP-RESIZE(8)     Maintenance Commands     CRYPTSETUP-RESIZE(8)

NAME
       cryptsetup-resize - resize an active mapping

SYNOPSIS
       cryptsetup resize [<options>] <name>

DESCRIPTION
       Resizes an active mapping <name>.


> Cheers,
> Alex
> 
> ---
> 
> $ MANWIDTH=72 man ./proc_pid_gid_map.5 | cat
> proc_pid_gid_map(5)       File Formats Manual      proc_pid_gid_map(5)
> 
> NAME
>      /proc/pid/gid_map - group ID mappings
> 
> DESCRIPTION
>      /proc/pid/gid_map (since Linux 3.5)
>             See user_namespaces(7).
> 
> SEE ALSO
>      proc(5)
> 
> Linux man‐pages (unreleased)    (date)             proc_pid_gid_map(5)
> 
> 
> $ MANWIDTH=72 man ./proc_pid_attr.5 | cat
> proc_pid_attr(5)          File Formats Manual         proc_pid_attr(5)
> 
> NAME
>      /proc/pid/attr/ - security‐related attributes
> 

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. 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.

- 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.

So in case whoever wrote that happens to read this -- many thanks <3

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]