proc(5)'s sashimi

proc(5)'s sashimi

[Alejandro Colomar]

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

Hi!

The day has come to cut the proc(5) tuna fish in very little pieces.
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.

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

DESCRIPTION
     /proc/pid/attr/
            The  files  in  this directory provide an API for security
            modules.  The contents of this directory  are  files  that
            can  be  read and written in order to set security‐related
            attributes.  This directory was added to support  SELinux,
            but  the  intention  was that the API be general enough to
            support other security modules.  For the purpose of expla‐
            nation, examples of how SELinux uses these files are  pro‐
            vided below.

            This  directory  is present only if the kernel was config‐
            ured with CONFIG_SECURITY.

     /proc/pid/attr/current (since Linux 2.6.0)
            The contents of this file represent the  current  security
            attributes of the process.

            In  SELinux, this file is used to get the security context
            of a process.  Prior to Linux 2.6.11, this file could  not
            be  used  to  set the security context (a write was always
            denied), since SELinux limited  process  security  transi‐
            tions    to    execve(2)    (see    the   description   of
            /proc/pid/attr/exec, below).  Since Linux 2.6.11,  SELinux
            lifted  this restriction and began supporting "set" opera‐
            tions via writes to this node if authorized by policy, al‐
            though use of this operation is only suitable for applica‐
            tions that are trusted to maintain any desired  separation
            between the old and new security contexts.

            Prior  to  Linux  2.6.28,  SELinux  did  not allow threads
            within a multithreaded process to set their security  con‐
            text  via  this  node  as  it would yield an inconsistency
            among the security contexts of  the  threads  sharing  the
            same  memory  space.   Since  Linux 2.6.28, SELinux lifted
            this restriction and began supporting "set" operations for
            threads within a multithreaded process if the new security
            context is bounded by the old security context, where  the
            bounded  relation is defined in policy and guarantees that
            the new security context has a subset of  the  permissions
            of the old security context.

            Other  security modules may choose to support "set" opera‐
            tions via writes to this node.

     /proc/pid/attr/exec (since Linux 2.6.0)
            This file represents  the  attributes  to  assign  to  the
            process upon a subsequent execve(2).

            In  SELinux, this is needed to support role/domain transi‐
            tions, and execve(2) is the preferred point to  make  such
            transitions because it offers better control over the ini‐
            tialization  of  the process in the new security label and
            the inheritance of state.  In SELinux, this  attribute  is
            reset  on execve(2) so that the new program reverts to the
            default behavior for any execve(2) calls that it may make.
            In   SELinux,   a   process   can   set   only   its   own
            /proc/pid/attr/exec attribute.

     /proc/pid/attr/fscreate (since Linux 2.6.0)
            This  file  represents  the  attributes to assign to files
            created by subsequent calls  to  open(2),  mkdir(2),  sym‐
            link(2), and mknod(2)

            SELinux  employs  this  file to support creation of a file
            (using the aforementioned system calls) in a secure state,
            so that there is no risk of inappropriate access being ob‐
            tained between the time of creation and the time that  at‐
            tributes  are set.  In SELinux, this attribute is reset on
            execve(2), so that the new program reverts to the  default
            behavior  for any file creation calls it may make, but the
            attribute will persist across multiple file creation calls
            within a  program  unless  it  is  explicitly  reset.   In
            SELinux,    a    process    can    set    only   its   own
            /proc/pid/attr/fscreate attribute.

     /proc/pid/attr/keycreate (since Linux 2.6.18)
            If a process writes a security context into this file, all
            subsequently created keys  (add_key(2))  will  be  labeled
            with  this context.  For further information, see the ker‐
            nel source file  Documentation/security/keys/core.rst  (or
            file Documentation/security/keys.txt between Linux 3.0 and
            Linux 4.13, or Documentation/keys.txt before Linux 3.0).

     /proc/pid/attr/prev (since Linux 2.6.0)
            This file contains the security context of the process be‐
            fore  the  last  execve(2); that is, the previous value of
            /proc/pid/attr/current.

     /proc/pid/attr/socketcreate (since Linux 2.6.18)
            If a process writes a security context into this file, all
            subsequently created sockets will  be  labeled  with  this
            context.

SEE ALSO
     proc(5)

Linux man‐pages (unreleased)    (date)                proc_pid_attr(5)

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: proc(5)'s sashimi

[Oskari Pirhonen]

[-- 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 --]

Re: proc(5)'s sashimi

[Günther Noack]

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.

It seems like a good idea to split up proc(5). 👍

—Günther

-- 
Sent using Mutt 🐕 Woof Woof

Re: proc(5)'s sashimi

[Brian Inglis]

Hi Alex,

++ About time.

Instead of the meta path component <pid> in the name, you could use the actual 
path component "self", with a standard note that it may be substituted by the 
pid of any process (to whose metadata you have access).

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry

Re: proc(5)'s sashimi

[G. Branden Robinson]

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

Hi Alex,

At 2023-08-14T16:06:16+0200, Alejandro Colomar wrote:
> 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,

I think it's generally a good practice to have the page topic (the first
argument to `TH`) match the "basename" of the man page document's file
name.  That rules out slashes there.

> but for the NAME I used slashes (so the actual name of the interface).

This seems like a good idea to me.  Neither the man(7) package nor the
formatter care what is in that section.

Consider:

$ cat slashy.man
.TH slashy 1 2023-08-15 "groff test suite"
.SH Name
.IR /etc/slashy/ n
\- configuration of Roguelike game,
version
.I n
.SH Description
Eat and chop.

`nroff -man` and `mandoc | ul` both render this correctly.

> I didn't do any italics in the name, though, so /pid/ is no special in
> the name.

As shown above, I would go ahead and mark it up The Right Way™.

Except...

Unfortunately, lexgrog(1) failed.  CCing man-db maintainer Colin Watson.

slashy.man: parse failed

For the time being, therefore, I would back things down to the
following, which _does_ work.

.TH less\-slashy 1 2023-08-15 "groff test suite"
.SH Name
.I /etc/slashy/n
\- configuration of Roguelike game,
version
.I n
.SH Description
Eat and chop.

$ lexgrog less-slashy.man
less-slashy.man: "/etc/slashy/n - configuration of Roguelike game, version n"

...so you can still do quite a bit, just not change fonts _within_ the
page "name" (which can be a comma-separated list of names).[1]

Interestingly, the following _doesn't_ bomb:

$ cat moderately-slashy.man
.TH moderately\-slashy 1 2023-08-15 "groff test suite"
.SH Name
.IR /etc/slashy/n
\- configuration of Roguelike game,
version
.I n
.SH Description
Eat and chop.

Observe the missing second argument to `IR`.  `nroff -rCHECKSTYLE=1
-man` would holler about this, but lexgrog chokes only if there's an
argument there.

$ lexgrog moderately-slashy.man
moderately-slashy.man: "/etc/slashy/n - configuration of Roguelike game, version n"

Maybe this is easy to fix, but even if so you'll probably want to wait
until the fixed version has percolated in to distributions of interest,
or your man page won't be indexed, and not show up in apropos(1) or `man
-k` searches.

What if it's not easy to fix?  We could of course just give up on some
man(7) features.

Or...we could make lexgrog(1) unnecessary (more likely, a wrapper).

I've had an idea for a while: what if the man(7) package paid attention
to the arguments to `SH` macro calls?

And what if man(7) supported a string that could hold the name of a
section heading of interest?

Consider the difference.

$ nroff -man moderately-slashy.man
moderately-slashy(1)        General Commands Manual       moderately-slashy(1)

Name
       /etc/slashy/n - configuration of Roguelike game, version n

Description
       Eat and chop.

groff test suite                  2023‐08‐15              moderately-slashy(1)

$ nroff -man -dEXTRACT=Name moderately-slashy.man
       /etc/slashy/n - configuration of Roguelike game, version n

$ echo "sweet as"

This would be _really easy_ to do.  (Famous last words, I know, but
groff mdoc(7) already does a similar thing, for different reasons.[2])

lexgrog(1) could then become a wrapper around `nroff -man -dEXTRACT=Name
-P -cbou`.  It would be easy to chop off the trailing blank line.  You
wouldn't need to chop off the leading spaces, thanks to a groff-next
feature that's already landed.

$ ./build/test-groff -rBP=0 -man -T utf8 -P -cbou \
    moderately-slashy.man | grep Rogue
/etc/slashy/n - configuration of Roguelike game, version n

(`BP` is the new "base paragraph indentation" register.  The "-P -cbou"
options strip all formatting, leaving you a pure character stream in the
output--no escape sequences, no overstriking.  See grotty(1).)

Colin, how do you feel about this idea?  I aim to do it anyway, but if
it doesn't excite you as a means of making lexgrog's job simpler--at
least on systems that run a sufficiently new version of groff--I may
kick it down the road until after we solve the automatic tagging
problem.  I want to be able to type something like this:

nroff -man -dEXTRACT=Options/-e

...and have it do exactly what you think it would do.  That future
doesn't seem very far away given what we're having to implement for PDF
bookmarks.[3]  At least at present, before difficult obstacles arise...

Regards,
Branden

[1] Further experimentation reveals that lexgrog seems to be tripping
    _only_ on second arguments to font style alternation macros.

.I /etc/slashy/\fRn
\- configuration of Roguelike game,
version
.I n

is accepted (but don't do it--`\f` is hateful).

.I /etc/slashy/n
\- configuration of Roguelike game,
version
.IB n "oh yeah"

...doesn't break lexgrog but doesn't store quite the right data, either.

broadly-slashy.man: "/etc/slashy/n - configuration of Roguelike game, version n "oh yeah""

Maybe this means a fix to lexgrog on its own terms will be easy.  No
idea.  I seem to remember Colin mentioning before that it is dismaying
how much *roff syntax a makewhatis(1) or lexgrog(1) or similar program
has to understand to do its job.  I have no idea why brighter minds than
mine didn't think up a solution like my "EXTRACT" string above decades
ago.  Maybe they did, and I'm about to find out what's wrong with it...

[2] https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/mdoc/doc-common?h=1.23.0#n1414
[3] https://lore.kernel.org/linux-man/20230815005022.47vpqsjoczn4vyii@illithid/


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

Re: proc(5)'s sashimi

[Alejandro Colomar]

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

Hi Branden,

On 2023-08-15 17:36, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-08-14T16:06:16+0200, Alejandro Colomar wrote:
>> 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,
> 
> I think it's generally a good practice to have the page topic (the first
> argument to `TH`) match the "basename" of the man page document's file
> name.  That rules out slashes there.
> 
>> but for the NAME I used slashes (so the actual name of the interface).
> 
> This seems like a good idea to me.  Neither the man(7) package nor the
> formatter care what is in that section.
> 
> Consider:
> 
> $ cat slashy.man
> .TH slashy 1 2023-08-15 "groff test suite"
> .SH Name
> .IR /etc/slashy/ n
> \- configuration of Roguelike game,
> version
> .I n
> .SH Description
> Eat and chop.
> 
> `nroff -man` and `mandoc | ul` both render this correctly.
> 
>> I didn't do any italics in the name, though, so /pid/ is no special in
>> the name.
> 
> As shown above, I would go ahead and mark it up The Right Way™.
> 
> Except...
> 
> Unfortunately, lexgrog(1) failed.  CCing man-db maintainer Colin Watson.

I'm worried that mandoc(1) may have even more tight assumptions.  I even
warns you if the Name and TH don't match, AFAIR.

Considering that I can't have the right formatting, I prefer to leave it
with no formatting at all; otherwise, it could be confusing.  Having no
formatting leaves a clue that it doesn't have it because it's not
possible.

> 
> slashy.man: parse failed
> 
> For the time being, therefore, I would back things down to the
> following, which _does_ work.
> 
> .TH less\-slashy 1 2023-08-15 "groff test suite"
> .SH Name
> .I /etc/slashy/n
> \- configuration of Roguelike game,
> version
> .I n
> .SH Description
> Eat and chop.
> 
> $ lexgrog less-slashy.man
> less-slashy.man: "/etc/slashy/n - configuration of Roguelike game, version n"
> 
> ...so you can still do quite a bit, just not change fonts _within_ the
> page "name" (which can be a comma-separated list of names).[1]
> 
> Interestingly, the following _doesn't_ bomb:
> 
> $ cat moderately-slashy.man
> .TH moderately\-slashy 1 2023-08-15 "groff test suite"
> .SH Name
> .IR /etc/slashy/n
> \- configuration of Roguelike game,
> version
> .I n
> .SH Description
> Eat and chop.
> 
> Observe the missing second argument to `IR`.  `nroff -rCHECKSTYLE=1
> -man` would holler about this, but lexgrog chokes only if there's an
> argument there.
> 
> $ lexgrog moderately-slashy.man
> moderately-slashy.man: "/etc/slashy/n - configuration of Roguelike game, version n"
> 
> Maybe this is easy to fix, but even if so you'll probably want to wait
> until the fixed version has percolated in to distributions of interest,
> or your man page won't be indexed, and not show up in apropos(1) or `man
> -k` searches.
> 
> What if it's not easy to fix?  We could of course just give up on some
> man(7) features.
> 
> Or...we could make lexgrog(1) unnecessary (more likely, a wrapper).
> 
> I've had an idea for a while: what if the man(7) package paid attention
> to the arguments to `SH` macro calls?
> 
> And what if man(7) supported a string that could hold the name of a
> section heading of interest?
> 
> Consider the difference.
> 
> $ nroff -man moderately-slashy.man
> moderately-slashy(1)        General Commands Manual       moderately-slashy(1)
> 
> Name
>        /etc/slashy/n - configuration of Roguelike game, version n
> 
> Description
>        Eat and chop.
> 
> groff test suite                  2023‐08‐15              moderately-slashy(1)
> 
> $ nroff -man -dEXTRACT=Name moderately-slashy.man
>        /etc/slashy/n - configuration of Roguelike game, version n
> 
> $ echo "sweet as"

That reminds me of man_section(), which is quite useful for reviewing
global changes to man pages.

I can, after a global fix to the SYNOPSIS, render all synopses, and
grep there if there's any inconsistency.

It's in ./scripts/bash_aliases:

man_section()
{
	if [ $# -lt 2 ]; then
		>&2 echo "Usage: ${FUNCNAME[0]} <dir> <section>...";
		return $EX_USAGE;
	fi

	local page="$1";
	shift;
	local sect="$*";

	find "$page" -type f \
	|xargs wc -l \
	|grep -v -e '\b1 ' -e '\btotal\b' \
	|awk '{ print $2 }' \
	|sort \
	|while read -r manpage; do
		(sed -n '/^\.TH/,/^\.SH/{/^\.SH/!p}' <"$manpage";
		 for s in $sect; do
			<"$manpage" \
			sed -n \
				-e "/^\.SH $s/p" \
				-e "/^\.SH $s/,/^\.SH/{/^\.SH/!p}";
		 done;) \
		|mandoc -Tutf8 2>/dev/null \
		|col -pbx;
	done;
}

Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: proc(5)'s sashimi

[Alejandro Colomar]

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

Hi Branden,

On 2023-08-15 16:26, Brian Inglis wrote:
> Hi Alex,
> 
> ++ About time.
> 
> Instead of the meta path component <pid> in the name, you could use the actual 
> path component "self", with a standard note that it may be substituted by the 
> pid of any process (to whose metadata you have access).

I considered that, but I think it's better to use the placeholder.  self is just
a special case.  Also, there's /proc/tid/ too, so it seems more consistent to
use pid.

Cheers,
Alex

> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: proc(5)'s sashimi

[Alejandro Colomar]

[-- 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 --]

Re: proc(5)'s sashimi

[Alejandro Colomar]

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

Hi!

On 2023-08-14 16:06, Alejandro Colomar wrote:
> Hi!
> 
> The day has come to cut the proc(5) tuna fish in very little pieces.
> 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).

The sashimi is ready.  Feel free to grab your portion and have a nice
supper.

I've created a signed tag 'proc-sashimi-v1' for review.  It's around
100 commits, so I'm not sending them to the mailing list.  Below
is a summary.

I didn't change anything from what I suggested yesterday, so I'm not
resending renderings of any page, but feel free to ask for them if
you want.

As always, all commits are GPG-signed, and the tag is also GPG-signed.

You may notice that proc_sys(5) is still huge, compared to the other
pages.  I'll probably cut it in pieces in the future; I was just
tired at that point and kept the depth of the cuts limited for this
time.

Also, manual-page references are broken now, since all pages still
point to proc(5), and I didn't go page by page updating the
references to whatever the new page should be.  I think that's too
much for now.  If anyone wants to send updates for those, please
feel welcome!  Also the references in proc(5) should be moved to the
appropriate new pages, but that's a similar story.

Cheers,
Alex

---

$ git request-pull master \
      git://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git \
      proc-sashimi-v1;
The following changes since commit 26ffcd4fa9a4f89ab60371e9c19fa39cae58634b:

  scripts/sortman: Ignore only leading underscores or dashes (2023-08-14 15:16:59 +0200)

are available in the Git repository at:

  git://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git tags/proc-sashimi-v1

for you to fetch changes up to 92cdcec79df039146e5ed42cac23cd4b7e3f9e25:

  proc.5: Clean up after making sashimi of this page (2023-08-15 23:27:07 +0200)

----------------------------------------------------------------
proc(5) sashimi; v1

----------------------------------------------------------------
Alejandro Colomar (98):
      proc.5: srcfix
      proc.5, proc_pid_attr.5: Split /proc/PID/attr/ from proc(5)
      proc.5, proc_pid_autogroup.5: Split /proc/PID/autogroup from proc(5)
      proc.5, proc_pid_auxv.5: Split /proc/PID/auxv from proc(5)
      proc.5, proc_pid_cgroup.5: Split /proc/PID/cgroup from proc(5)
      proc.5, proc_pid_clear_refs.5: Split /proc/PID/clear_refs from proc(5)
      proc.5, proc_pid_cmdline.5: Split /proc/PID/cmdline from proc(5)
      proc.5, proc_pid_comm.5: Split /proc/PID/comm from proc(5)
      proc.5, proc_pid_coredump_filter.5: Split /proc/PID/coredump_filter from proc(5)
      proc.5, proc_pid_cpuset.5: Split /proc/PID/cpuset from proc(5)
      proc.5, proc_pid_cwd.5: Split /proc/PID/cwd from proc(5)
      proc.5, proc_pid_environ.5: Split /proc/PID/environ from proc(5)
      proc.5, proc_pid_exe.5: Split /proc/PID/exe from proc(5)
      proc.5, proc_pid_fd.5: Split /proc/PID/fd/ from proc(5)
      proc.5, proc_pid_fdinfo.5: Split /proc/PID/fdinfo/ from proc(5)
      proc.5, proc_pid_uid_map.5, proc_pid_gid_map.5: Split /proc/PID/[ug]id_map from proc(5)
      proc.5, proc_pid_io.5: Split /proc/PID/io from proc(5)
      proc.5, proc_pid_limits.5: Split /proc/PID/limits from proc(5)
      proc.5, proc_pid_map_files.5: Split /proc/PID/map_files/ from proc(5)
      proc.5, proc_pid_maps.5: Split /proc/PID/maps from proc(5)
      proc.5, proc_pid_mem.5: Split /proc/PID/mem from proc(5)
      proc.5, proc_pid_mountinfo.5: Split /proc/PID/mountinfo from proc(5)
      proc.5, proc_pid_mounts.5, proc_mounts.5: Split /proc/PID/mounts (and /proc/mounts) from proc(5)
      proc.5, proc_pid_mountstats.5: Split /proc/PID/mountstats from proc(5)
      proc.5, proc_pid_net.5, proc_net.5: Split /proc/PID/net/ (and /proc/net/) from proc(5)
      proc.5, proc_pid_ns.5: Split /proc/PID/ns/ from proc(5)
      proc.5, proc_pid_numa_maps.5: Split /proc/PID/numa_maps from proc(5)
      proc.5, proc_pid_oom_score_adj.5, proc_pid_oom_adj.5: Split /proc/PID/oom_score_adj (and /proc/PID/oom_adj) from proc(5)
      proc.5, proc_pid_oom_score.5: Split /proc/PID/oom_score from proc(5)
      proc.5, proc_pid_pagemap.5: Split /proc/PID/pagemap from proc(5)
      proc.5, proc_pid_personality.5: Split /proc/PID/personality from proc(5)
      proc.5, proc_pid_root.5: Split /proc/PID/root/ from proc(5)
      proc.5, proc_pid_projid_map.5: Split /proc/PID/projid_map from proc(5)
      proc.5, proc_pid_seccomp.5: Split /proc/PID/seccomp from proc(5)
      proc.5, proc_pid_setgroups.5: Split /proc/PID/setgroups from proc(5)
      proc.5, proc_pid_smaps.5: Split /proc/PID/smaps from proc(5); XXX: what's s in smaps?
      proc.5, proc_pid_stack.5: Split /proc/PID/stack from proc(5)
      proc.5, proc_pid_stat.5: Split /proc/PID/stat from proc(5)
      proc.5, proc_pid_statm.5: Split /proc/PID/statm from proc(5)
      proc.5, proc_pid_status.5: Split /proc/PID/status from proc(5)
      proc.5, proc_pid_syscall.5: Split /proc/PID/syscall from proc(5)
      proc.5, proc_pid_timers.5: Split /proc/PID/timers from proc(5)
      proc.5, proc_pid_timerslack_ns.5: Split /proc/PID/timerslack_ns from proc(5)
      proc.5, proc_pid_wchan.5: Split /proc/PID/wchan from proc(5)
      proc.5, proc_pid.5, proc_self.5: Split /proc/PID/ (and /proc/self/) from proc(5)
      proc.5, proc_pid_task.5, proc_tid.5, proc_thread-self.5: Split /proc/PID/task/ (and /proc/TID/, /proc/thread-self/) from proc(5)
      proc.5, proc_tid_children.5: Split /proc/TID/children from proc(5)
      proc.5, proc_apm.5: Split /proc/apm from proc(5)
      proc.5, proc_buddyinfo.5: Split /proc/buddyinfo from proc(5)
      proc.5, proc_bus.5: Split /proc/bus/ from proc(5)
      proc.5, proc_cgroups.5: Split /proc/cgroups from proc(5)
      proc.5, proc_cmdline.5: Split /proc/cmdline from proc(5)
      proc.5, proc_config.gz.5: Split /proc/config.gz from proc(5)
      proc.5, proc_crypto.5: Split /proc/crypto from proc(5)
      proc.5, proc_cpuinfo.5: Split /proc/cpuinfo from proc(5)
      proc.5, proc_devices.5: Split /proc/devices from proc(5)
      proc.5, proc_diskstats.5: Split /proc/diskstats from proc(5)
      proc.5, proc_dma.5: Split /proc/dma from proc(5)
      proc.5, proc_driver.5: Split /proc/driver/ from proc(5)
      proc.5, proc_execdomains.5: Split /proc/execdomains from proc(5)
      proc.5, proc_fb.5: Split /proc/fb from proc(5)
      proc.5, proc_filesystems.5: Split /proc/filesystems from proc(5)
      proc.5, proc_fs.5: Split /proc/fs/ from proc(5)
      proc.5, proc_ide.5: Split /proc/ide/ from proc(5)
      proc.5, proc_interrupts.5: Split /proc/interrupts from proc(5)
      proc.5, proc_iomem.5: Split /proc/iomem from proc(5)
      proc.5, proc_ioports.5: Split /proc/ioports from proc(5)
      proc.5, proc_kallsyms.5, proc_ksyms.5: Split /proc/kallsyms (and /proc/ksyms) from proc(5)
      proc.5, proc_kcore.5: Split /proc/kcore from proc(5)
      proc.5, proc_keys.5, proc_key-users.5: Split /proc/keys (and /proc/key-users) from proc(5)
      proc.5, proc_kmsg.5: Split /proc/kmsg from proc(5)
      proc.5, proc_kpagecgroup.5: Split /proc/kpagecgroup from proc(5)
      proc.5, proc_kpagecount.5: Split /proc/kpagecount from proc(5)
      proc.5, proc_kpageflags.5: Split /proc/kpageflags from proc(5)
      proc.5, proc_loadavg.5: Split /proc/loadavg from proc(5)
      proc.5, proc_locks.5: Split /proc/locks from proc(5)
      proc.5, proc_malloc.5: Split /proc/malloc from proc(5)
      proc.5, proc_meminfo.5: Split /proc/meminfo from proc(5)
      proc.5, proc_modules.5: Split /proc/modules from proc(5)
      proc.5, proc_mtrr.5: Split /proc/mtrr from proc(5)
      proc.5, proc_partitions.5: Split /proc/partitions from proc(5)
      proc.5, proc_pci.5: Split /proc/pci from proc(5)
      proc.5, proc_profile.5: Split /proc/profile from proc(5)
      proc.5, proc_scsi.5: Split /proc/scsi/ from proc(5)
      proc.5, proc_slabinfo.5: Split /proc/slabinfo from proc(5)
      proc.5, proc_stat.5: Split /proc/stat from proc(5)
      proc.5, proc_swaps.5: Split /proc/swaps from proc(5)
      proc.5, proc_sys.5: Split /proc/sys/ from proc(5)
      proc.5, proc_sysrq-trigger.5: Split /proc/sysrq-trigger from proc(5)
      proc.5, proc_sysvipc.5: Split /proc/sysvipc/ from proc(5)
      proc.5, proc_timer_list.5: Split /proc/timer_list from proc(5)
      proc.5, proc_timer_stats.5: Split /proc/timer_stats from proc(5)
      proc.5, proc_tty.5: Split /proc/tty from proc(5)
      proc.5, proc_uptime.5: Split /proc/uptime from proc(5)
      proc.5, proc_version.5: Split /proc/version from proc(5)
      proc.5, proc_vmstat.5: Split /proc/vmstat from proc(5)
      proc.5, proc_zoneinfo.5: Split /proc/zoneinfo from proc(5)
      proc.5: Clean up after making sashimi of this page

 man5/proc.5                     | 6722 +----------------------------------------------------------------------------------------------------------------------------------------------------
 man5/proc_apm.5                 |   17 +
 man5/proc_buddyinfo.5           |   58 ++
 man5/proc_bus.5                 |   35 +
 man5/proc_cgroups.5             |   16 +
 man5/proc_cmdline.5             |   22 +
 man5/proc_config.gz.5           |   40 +
 man5/proc_cpuinfo.5             |   24 +
 man5/proc_crypto.5              |   26 +
 man5/proc_devices.5             |   16 +
 man5/proc_diskstats.5           |   21 +
 man5/proc_dma.5                 |   16 +
 man5/proc_driver.5              |   15 +
 man5/proc_execdomains.5         |   16 +
 man5/proc_fb.5                  |   17 +
 man5/proc_filesystems.5         |   33 +
 man5/proc_fs.5                  |   18 +
 man5/proc_ide.5                 |   37 +
 man5/proc_interrupts.5          |   22 +
 man5/proc_iomem.5               |   15 +
 man5/proc_ioports.5             |   16 +
 man5/proc_kallsyms.5            |   25 +
 man5/proc_kcore.5               |   24 +
 man5/proc_key-users.5           |    1 +
 man5/proc_keys.5                |   20 +
 man5/proc_kmsg.5                |   28 +
 man5/proc_kpagecgroup.5         |   25 +
 man5/proc_kpagecount.5          |   24 +
 man5/proc_kpageflags.5          |   75 ++
 man5/proc_ksyms.5               |    1 +
 man5/proc_loadavg.5             |   27 +
 man5/proc_locks.5               |  118 +++
 man5/proc_malloc.5              |   18 +
 man5/proc_meminfo.5             |  327 ++++++++
 man5/proc_modules.5             |   17 +
 man5/proc_mounts.5              |    1 +
 man5/proc_mtrr.5                |   24 +
 man5/proc_net.5                 |    1 +
 man5/proc_partitions.5          |   16 +
 man5/proc_pci.5                 |   28 +
 man5/proc_pid.5                 |   73 ++
 man5/proc_pid_attr.5            |  137 ++++
 man5/proc_pid_autogroup.5       |   17 +
 man5/proc_pid_auxv.5            |   27 +
 man5/proc_pid_cgroup.5          |   16 +
 man5/proc_pid_clear_refs.5      |   88 ++
 man5/proc_pid_cmdline.5         |   49 ++
 man5/proc_pid_comm.5            |   49 ++
 man5/proc_pid_coredump_filter.5 |   16 +
 man5/proc_pid_cpuset.5          |   17 +
 man5/proc_pid_cwd.5             |   36 +
 man5/proc_pid_environ.5         |   48 ++
 man5/proc_pid_exe.5             |   59 ++
 man5/proc_pid_fd.5              |  161 ++++
 man5/proc_pid_fdinfo.5          |  300 +++++++
 man5/proc_pid_gid_map.5         |    1 +
 man5/proc_pid_io.5              |   98 +++
 man5/proc_pid_limits.5          |   25 +
 man5/proc_pid_map_files.5       |   72 ++
 man5/proc_pid_maps.5            |  157 ++++
 man5/proc_pid_mem.5             |   24 +
 man5/proc_pid_mountinfo.5       |  124 +++
 man5/proc_pid_mounts.5          |   49 ++
 man5/proc_pid_mountstats.5      |   46 ++
 man5/proc_pid_net.5             |  298 +++++++
 man5/proc_pid_ns.5              |   20 +
 man5/proc_pid_numa_maps.5       |   16 +
 man5/proc_pid_oom_adj.5         |    1 +
 man5/proc_pid_oom_score.5       |   58 ++
 man5/proc_pid_oom_score_adj.5   |  117 +++
 man5/proc_pid_pagemap.5         |   77 ++
 man5/proc_pid_personality.5     |   23 +
 man5/proc_pid_projid_map.5      |   17 +
 man5/proc_pid_root.5            |   75 ++
 man5/proc_pid_seccomp.5         |   36 +
 man5/proc_pid_setgroups.5       |   16 +
 man5/proc_pid_smaps.5           |  128 +++
 man5/proc_pid_stack.5           |   25 +
 man5/proc_pid_stat.5            |  380 +++++++++
 man5/proc_pid_statm.5           |   46 ++
 man5/proc_pid_status.5          |  366 +++++++++
 man5/proc_pid_syscall.5         |   33 +
 man5/proc_pid_task.5            |   97 +++
 man5/proc_pid_timers.5          |   83 ++
 man5/proc_pid_timerslack_ns.5   |   41 +
 man5/proc_pid_uid_map.5         |   20 +
 man5/proc_pid_wchan.5           |   21 +
 man5/proc_profile.5             |   24 +
 man5/proc_scsi.5                |   66 ++
 man5/proc_self.5                |    1 +
 man5/proc_slabinfo.5            |   18 +
 man5/proc_stat.5                |  140 ++++
 man5/proc_swaps.5               |   17 +
 man5/proc_sys.5                 | 1623 ++++++++++++++++++++++++++++++++++++
 man5/proc_sysrq-trigger.5       |   25 +
 man5/proc_sysvipc.5             |   25 +
 man5/proc_thread-self.5         |    1 +
 man5/proc_tid.5                 |    1 +
 man5/proc_tid_children.5        |   37 +
 man5/proc_timer_list.5          |   18 +
 man5/proc_timer_stats.5         |  117 +++
 man5/proc_tty.5                 |   16 +
 man5/proc_uptime.5              |   17 +
 man5/proc_version.5             |   27 +
 man5/proc_vmstat.5              |  702 ++++++++++++++++
 man5/proc_zoneinfo.5            |   17 +
 106 files changed, 7860 insertions(+), 6717 deletions(-)
 create mode 100644 man5/proc_apm.5
 create mode 100644 man5/proc_buddyinfo.5
 create mode 100644 man5/proc_bus.5
 create mode 100644 man5/proc_cgroups.5
 create mode 100644 man5/proc_cmdline.5
 create mode 100644 man5/proc_config.gz.5
 create mode 100644 man5/proc_cpuinfo.5
 create mode 100644 man5/proc_crypto.5
 create mode 100644 man5/proc_devices.5
 create mode 100644 man5/proc_diskstats.5
 create mode 100644 man5/proc_dma.5
 create mode 100644 man5/proc_driver.5
 create mode 100644 man5/proc_execdomains.5
 create mode 100644 man5/proc_fb.5
 create mode 100644 man5/proc_filesystems.5
 create mode 100644 man5/proc_fs.5
 create mode 100644 man5/proc_ide.5
 create mode 100644 man5/proc_interrupts.5
 create mode 100644 man5/proc_iomem.5
 create mode 100644 man5/proc_ioports.5
 create mode 100644 man5/proc_kallsyms.5
 create mode 100644 man5/proc_kcore.5
 create mode 100644 man5/proc_key-users.5
 create mode 100644 man5/proc_keys.5
 create mode 100644 man5/proc_kmsg.5
 create mode 100644 man5/proc_kpagecgroup.5
 create mode 100644 man5/proc_kpagecount.5
 create mode 100644 man5/proc_kpageflags.5
 create mode 100644 man5/proc_ksyms.5
 create mode 100644 man5/proc_loadavg.5
 create mode 100644 man5/proc_locks.5
 create mode 100644 man5/proc_malloc.5
 create mode 100644 man5/proc_meminfo.5
 create mode 100644 man5/proc_modules.5
 create mode 100644 man5/proc_mounts.5
 create mode 100644 man5/proc_mtrr.5
 create mode 100644 man5/proc_net.5
 create mode 100644 man5/proc_partitions.5
 create mode 100644 man5/proc_pci.5
 create mode 100644 man5/proc_pid.5
 create mode 100644 man5/proc_pid_attr.5
 create mode 100644 man5/proc_pid_autogroup.5
 create mode 100644 man5/proc_pid_auxv.5
 create mode 100644 man5/proc_pid_cgroup.5
 create mode 100644 man5/proc_pid_clear_refs.5
 create mode 100644 man5/proc_pid_cmdline.5
 create mode 100644 man5/proc_pid_comm.5
 create mode 100644 man5/proc_pid_coredump_filter.5
 create mode 100644 man5/proc_pid_cpuset.5
 create mode 100644 man5/proc_pid_cwd.5
 create mode 100644 man5/proc_pid_environ.5
 create mode 100644 man5/proc_pid_exe.5
 create mode 100644 man5/proc_pid_fd.5
 create mode 100644 man5/proc_pid_fdinfo.5
 create mode 100644 man5/proc_pid_gid_map.5
 create mode 100644 man5/proc_pid_io.5
 create mode 100644 man5/proc_pid_limits.5
 create mode 100644 man5/proc_pid_map_files.5
 create mode 100644 man5/proc_pid_maps.5
 create mode 100644 man5/proc_pid_mem.5
 create mode 100644 man5/proc_pid_mountinfo.5
 create mode 100644 man5/proc_pid_mounts.5
 create mode 100644 man5/proc_pid_mountstats.5
 create mode 100644 man5/proc_pid_net.5
 create mode 100644 man5/proc_pid_ns.5
 create mode 100644 man5/proc_pid_numa_maps.5
 create mode 100644 man5/proc_pid_oom_adj.5
 create mode 100644 man5/proc_pid_oom_score.5
 create mode 100644 man5/proc_pid_oom_score_adj.5
 create mode 100644 man5/proc_pid_pagemap.5
 create mode 100644 man5/proc_pid_personality.5
 create mode 100644 man5/proc_pid_projid_map.5
 create mode 100644 man5/proc_pid_root.5
 create mode 100644 man5/proc_pid_seccomp.5
 create mode 100644 man5/proc_pid_setgroups.5
 create mode 100644 man5/proc_pid_smaps.5
 create mode 100644 man5/proc_pid_stack.5
 create mode 100644 man5/proc_pid_stat.5
 create mode 100644 man5/proc_pid_statm.5
 create mode 100644 man5/proc_pid_status.5
 create mode 100644 man5/proc_pid_syscall.5
 create mode 100644 man5/proc_pid_task.5
 create mode 100644 man5/proc_pid_timers.5
 create mode 100644 man5/proc_pid_timerslack_ns.5
 create mode 100644 man5/proc_pid_uid_map.5
 create mode 100644 man5/proc_pid_wchan.5
 create mode 100644 man5/proc_profile.5
 create mode 100644 man5/proc_scsi.5
 create mode 100644 man5/proc_self.5
 create mode 100644 man5/proc_slabinfo.5
 create mode 100644 man5/proc_stat.5
 create mode 100644 man5/proc_swaps.5
 create mode 100644 man5/proc_sys.5
 create mode 100644 man5/proc_sysrq-trigger.5
 create mode 100644 man5/proc_sysvipc.5
 create mode 100644 man5/proc_thread-self.5
 create mode 100644 man5/proc_tid.5
 create mode 100644 man5/proc_tid_children.5
 create mode 100644 man5/proc_timer_list.5
 create mode 100644 man5/proc_timer_stats.5
 create mode 100644 man5/proc_tty.5
 create mode 100644 man5/proc_uptime.5
 create mode 100644 man5/proc_version.5
 create mode 100644 man5/proc_vmstat.5
 create mode 100644 man5/proc_zoneinfo.5


-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: proc(5)'s sashimi

[Alejandro Colomar]

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

On 2023-08-15 18:46, Alejandro Colomar wrote:
> Hi Branden,
> 

Oops, I meant Brian!  :/

Cheers,
Alex


> On 2023-08-15 16:26, Brian Inglis wrote:
>> Hi Alex,
>>
>> ++ About time.
>>
>> Instead of the meta path component <pid> in the name, you could use the actual 
>> path component "self", with a standard note that it may be substituted by the 
>> pid of any process (to whose metadata you have access).
> 
> I considered that, but I think it's better to use the placeholder.  self is just
> a special case.  Also, there's /proc/tid/ too, so it seems more consistent to
> use pid.
> 
> Cheers,
> Alex
> 
>>
> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: proc(5)'s sashimi

[Alejandro Colomar]

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

On 2023-08-15 23:47, Alejandro Colomar wrote:
> 
> ---
> 
> $ git request-pull master \
>       git://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git \
>       proc-sashimi-v1;
> The following changes since commit 26ffcd4fa9a4f89ab60371e9c19fa39cae58634b:
> 
>   scripts/sortman: Ignore only leading underscores or dashes (2023-08-14 15:16:59 +0200)
> 
> are available in the Git repository at:
> 
>   git://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git tags/proc-sashimi-v1
> 
> for you to fetch changes up to 92cdcec79df039146e5ed42cac23cd4b7e3f9e25:
> 
>   proc.5: Clean up after making sashimi of this page (2023-08-15 23:27:07 +0200)
> 
> ----------------------------------------------------------------
> proc(5) sashimi; v1
> 


I've merged the changes.


commit 0569afbbccd6de28d1bacd13471a679ad2674aa1 (HEAD -> main, korg/master, alx/main, master)
Merge: 29597f1e7 92cdcec79
Author: Alejandro Colomar <alx@kernel.org>
Date:   Thu Aug 17 22:47:16 2023 +0200

    proc*.5: Make sashimi
    
    [Merge tag 'proc-sashimi-v1' of <git://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git>]
    
    proc(5) was a huge page, which was quite hard to maintain, extend, read,
    and refer to.  Split the page into small pages for the different
    directories and files within /proc.  Some pages are still too large
    (e.g., proc_sys(5)), and will some day be split even more.
    
    This split keeps the contents of the original page, without modifying
    anything; not even the formatting.
    
    The only thing that has been modified in this patches, is that
    directories are consistently represented with a trailing slash.
    
    For the file name of the pages, we've used the name of the interface
    (e.g., /proc/pid/), removing the leading and trailing '/'s and then
    translating the remaining ones as `tr / _` (e.g., proc_pid.5).  The
    title of the pages (TH) is consistent with this.  The NAME of the pages,
    however, is the actual path name of the interfaces.
    
    The man page references have not been updated, as that was a more
    complex and tedious work, so I expect that they'll be slowly updated as
    we and users find out.
    
    Link: <https://lore.kernel.org/linux-man/e3a5bc09-e835-9819-4aaa-12959495ac59@kernel.org/T/>
    Acked-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com>
    Acked-by: Günther Noack <gnoack@google.com>
    Acked-by: "G. Branden Robinson" <g.branden.robinson@gmail.com>
    Cc: Brian Inglis <Brian.Inglis@Shaw.ca>
    Cc: Ingo Schwarze <schwarze@usta.de>
    Cc: Colin Watson <cjwatson@debian.org>
    Signed-off-by: Alejandro Colomar <alx@kernel.org>


Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]