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@xxxxxxxxxx> 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@xxxxxxxxx> > > > Signed-off-by: Ian Rogers <irogers@xxxxxxxxxx> > > > --- > > > 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/>
Attachment:
signature.asc
Description: PGP signature
