linux-kernel - Re: [PATCH v1 1/3] proc_pid_fdinfo.5: Reduce indent for most of the page

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20241015203202.vyfi4nykkid35luj@illithid>
Date: Tue, 15 Oct 2024 15:32:02 -0500
From: "G. Branden Robinson" <g.branden.robinson@...il.com>
To: Ian Rogers <irogers@...gle.com>
Cc: Alejandro Colomar <alx@...nel.org>, David Airlie <airlied@...il.com>,
	Simona Vetter <simona@...ll.ch>,
	Maarten Lankhorst <maarten.lankhorst@...ux.intel.com>,
	Maxime Ripard <mripard@...nel.org>,
	Thomas Zimmermann <tzimmermann@...e.de>,
	Jonathan Corbet <corbet@....net>, dri-devel@...ts.freedesktop.org,
	linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
	linux-man@...r.kernel.org
Subject: Re: [PATCH v1 1/3] proc_pid_fdinfo.5: Reduce indent for most of the
 page

At 2024-10-15T11:38:22-0700, Ian Rogers wrote:
> When /proc/pid/fdinfo was part of proc.5 man page the indentation made
> sense. As a standalone man page the indentation doesn't need to be so
> far over to the right.
> 
> Signed-off-by: Ian Rogers <irogers@...gle.com>
> ---
>  man/man5/proc_pid_fdinfo.5 | 50 +++++++++++++++++++-------------------
>  1 file changed, 25 insertions(+), 25 deletions(-)
> 
> diff --git a/man/man5/proc_pid_fdinfo.5 b/man/man5/proc_pid_fdinfo.5
> index 1e23bbe02..0c4950d5d 100644
> --- a/man/man5/proc_pid_fdinfo.5
> +++ b/man/man5/proc_pid_fdinfo.5
> @@ -8,8 +8,9 @@
>  .SH NAME
>  /proc/pid/fdinfo/ \- information about file descriptors
>  .SH DESCRIPTION
> -.TP
> +.TP 0
>  .IR /proc/ pid /fdinfo/ " (since Linux 2.6.22)"
> +.P
>  This is a subdirectory containing one entry for each file which the
>  process has open, named by its file descriptor.
>  The files in this directory are readable only by the owner of the process.

I don't find this usage to be idiomatic.

There's no point having a tagged paragraph if you want that paragraph's
indentation to be zero.

I'll grant that it's also unusual to have a man page's "Description"
section lurch straight into a definition list without any preamble.

Since the only topic of this man page is now the file (or class of
files) in question, I suggest dropping the paragraph tag altogether
since it duplicates the summary description.

And as it happens, you can put font styling _in_ the summary desription.

So I suggest something like:

.SH NAME
.IR /proc/ pid /fdinfo " \- information about file descriptors"
.SH DESCRIPTION
Since Linux 2.6.22,
this subdirectory contains one entry for each file that process
.I pid
has open,
named for its file descriptor.

This renders fine with groff and mandoc(1).

Sample page attached.

Regards,
Branden

Download attachment "proc_pid_fdinfo_ropers.man" of type "application/x-troff-man" (6611 bytes)

Download attachment "signature.asc" of type "application/pgp-signature" (834 bytes)