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

[Alejandro Colomar]

Hi Ian,

On Fri, Nov 01, 2024 at 11:19:18AM -0700, Ian Rogers wrote:
> On Fri, Nov 1, 2024 at 6:24 AM Alejandro Colomar <alx at kernel.org> wrote:
> >
> > On Tue, Oct 15, 2024 at 02:17:17PM -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. Remove the initial tagged pragraph and move the
> > > styling to the initial summary description.
> > >
> > > Suggested-by: G. Branden Robinson <g.branden.robinson at gmail.com>
> > > Signed-off-by: Ian Rogers <irogers at google.com>
> > > ---
> > >  man/man5/proc_pid_fdinfo.5 | 66 ++++++++++++++++++--------------------
> > >  1 file changed, 32 insertions(+), 34 deletions(-)
> > >
> > > diff --git a/man/man5/proc_pid_fdinfo.5 b/man/man5/proc_pid_fdinfo.5
> > > index 1e23bbe02..8678caf4a 100644
> > > --- a/man/man5/proc_pid_fdinfo.5
> > > +++ b/man/man5/proc_pid_fdinfo.5
> > > @@ -6,20 +6,19 @@
> > >  .\"
> > >  .TH proc_pid_fdinfo 5 (date) "Linux man-pages (unreleased)"
> > >  .SH NAME
> > > -/proc/pid/fdinfo/ \- information about file descriptors
> > > +.IR /proc/ pid /fdinfo " \- information about file descriptors"
> >
> > I wouldn't add formatting here for now.  That's something I prefer to be
> > cautious about, and if we do it, we should do it in a separate commit.
> 
> I'll move it to a separate patch. Is the caution due to a lack of test
> infrastructure? That could be something to get resolved, perhaps
> through Google summer-of-code and the like.

That change might be controversial.  We'd first need to check that all
software that reads the NAME section would behave well for this.

Also, many other pages might need to be changed accordingly for
consistency.

For testing infrastructure I think we're good.  The makefile already
does a lot of testing.

> 
> > >  .SH DESCRIPTION
> > > -.TP
> > > -.IR /proc/ pid /fdinfo/ " (since Linux 2.6.22)"
> > > -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.
> > > -The contents of each file can be read to obtain information
> > > -about the corresponding file descriptor.
> > > -The content depends on the type of file referred to by the
> > > -corresponding file descriptor.
> > > -.IP
> > > +Since Linux 2.6.22,
> >
> > You could move this information to a HISTORY section.
> 
> Sure, tbh I'm not sure anybody cares about this information and it
> could be as well to delete it. Sorry people running 17 year old
> kernels. For now I'll try to leave it unchanged.

I would like to keep it in HISTORY.  You never know when it'll be useful
and it's just one line or a few; it won't hurt.

> 
> > > +this subdirectory contains one entry for each file that process
> > > +.I pid
> > > +has open, named by its file descriptor.  The files in this directory
> >
> > Please don't reflow existing text.  Please read about semantic newlines
> > in man-pages(7):
> >
> > $ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
> >    Use semantic newlines
> >      In  the  source of a manual page, new sentences should be started
> >      on new lines, long sentences should be split into lines at clause
> >      breaks (commas, semicolons, colons, and so on), and long  clauses
> >      should be split at phrase boundaries.  This convention, sometimes
> >      known  as  "semantic newlines", makes it easier to see the effect
> >      of patches, which often operate at the level of  individual  sen‐
> >      tences, clauses, or phrases.
> 
> I'll update for v3 but I'm reminded of `git diff --word-diff=color` so
> perhaps this recommendation is outdated.

No, this isn't outdated, since that reduces the quality of the diff.
Also, I review a lot of patches in the mail client, without running
git(1).  And it's not just for reviewing diffs, but also for writing
them.  Semantic newlines reduce the amount of work for producing the
diffs.  And lastly, the source code reads much better if it's logically
divided in phrases.

> 
> Thanks,
> Ian

-- 
<https://www.alejandro-colomar.es/>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://lists.freedesktop.org/archives/dri-devel/attachments/20241101/148b7a25/attachment.sig>