Re: Issue in man page proc_pid_fd.5

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 2336 bytes --]

Hi Alex,

At 2024-11-17T12:24:56+0100, Alejandro Colomar wrote:
> [CC += Branden]

What do you need from me here?  I'll take a guess and review your patch.

> On Sun, Nov 17, 2024 at 10:46:22AM GMT, Helge Kreutzmann wrote:
> > Without further ado, the following was found:
> > 
> > Issue:    Inode -> I<inode>?
> > 
> > "type:[inode]\n"
> 
> I've applied the following patch:
> 
> 	commit f3ac823f7501910031855c1f6e640f0dc5e295bb (HEAD -> contrib)
> 	Author: Alejandro Colomar <alx@kernel.org>
> 	Date:   Sun Nov 17 12:23:48 2024 +0100
> 
> 	    proc_pid_fd.5: ffix
> 	    
> 	    Reported-by: Helge Kreutzmann <debian@helgefjell.de>
> 	    Cc: "G. Branden Robinson" <branden@debian.org>
> 	    Signed-off-by: Alejandro Colomar <alx@kernel.org>
> 
> 	diff --git a/man/man5/proc_pid_fd.5 b/man/man5/proc_pid_fd.5
> 	index 2e3341ad8..903063e82 100644
> 	--- a/man/man5/proc_pid_fd.5
> 	+++ b/man/man5/proc_pid_fd.5
> 	@@ -24,7 +24,7 @@ .SH DESCRIPTION
> 	 .IP
> 	 .in +4n
> 	 .EX
> 	-type:[inode]
> 	+.IB type :[ inode ]

This markup looks okay to me, if "type" and "inode" are parameterized
and ":[" and "]" are literal.

Personally, I would use `IR` instead of `IB` since the example is of
_output_, not user input.

groff_man_style(7):
            Use bold for literal portions of syntax synopses, for
            command‐line options in running text, and for literals that
            are major topics of the subject under discussion; for
            example, this page uses bold for macro, string, and register
            names.  In an .EX/.EE example of interactive I/O (such as a
            shell session), set only user input in bold.

But (a) the exhibit here is more an example of file content than I/O per
se, and (b) I don't recall if you have an overriding style rule for the
man-pages project.

As ever, clarity is the first principle.  If the example is clear either
way, the choice of typeface for the literal parts of it is a matter of
polish, and not likely a barrier to the reader's comprehension.

> 	 .EE
> 	 .in
> 	 .IP
> 	@@ -50,7 +50,7 @@ .SH DESCRIPTION
> 	 .IP
> 	 .in +4n
> 	 .EX
> 	-.RI anon_inode: file-type
> 	+.BI anon_inode: file-type
> 	 .EE
> 	 .in
> 	 .IP
> 
> If anyone has comments, please let me know.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]