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 [off-list ref] wrote:

quoted

On Tue, Oct 15, 2024 at 02:17:17PM -0700, Ian Rogers wrote:

quoted

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 <redacted>
Signed-off-by: Ian Rogers <irogers@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.

quoted

quoted

 .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.

quoted

quoted

+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/>