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

[Ian Rogers]

On Tue, Oct 15, 2024 at 1:32 PM G. Branden Robinson
<g.branden.robinson@xxxxxxxxx> wrote:
>
> 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@xxxxxxxxxx>
> > ---
> >  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.

Thanks for the advice on how to make things more idiomatic. I'll try
to incorporate your feedback into v2.

Ian