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:
signature.asc
Description: PGP signature
