Re: [BUG] typo in man2/readlink.2

[Alejandro Colomar <alx@kernel.org>]

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

Hi Dirk,

On 2026-04-15T23:57:12+0200, Dirk Müller wrote:
> Hi Alejandro,
> 
> On Wed, Apr 15, 2026 at 11:36 PM Alejandro Colomar <alx@kernel.org> wrote:
> 
> > That's not what readlink(2) documents.  readlink(2) has a semicolon (;)
> > after the fisrt 'size_t bufsiz'.  That means it's a forward declaration
> > of a function parameter, and not a real parameter declaration.
> 
> Ah, got it! Thanks for being patient with me. This made me realize
> what tricked me here (other than not being able to distinguish ; and ,
> on my particular terminal today):

:)

> 
> In `man 2 strlcpy`,  or `man 2 strncpy`, and probably a few others the
> forward declaration is in "regular font" not in bold/highighted color

That's correct.  We call it Roman font, BTW.

> for the type.

Both the type and the identifier should be in roman, actually.

> for 2 readlink the forward declaration type is bolded.

I can't reproduce that in my terminal.  I see the forward declaration of
the parameter in readlink(2) also in Roman.

> I derive a visual clue from that to scan for the argument types.

Yup.  The commit responsible for that was:

	$ git show 8eea66b8 -- man/man2/readlink.2;
	commit 8eea66b827a11bc8983da517499cc236c6cd97ba
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   2025-06-06 13:27:02 +0200

	    man/: SYNOPSIS: Don't highlight forward declarations of function parameters
	    
	    Previously, many people confused these for actual parameters, since it's
	    hard to distinguish a ',' from ';'.  By removing bold/italics from
	    these, it will be easier to distinguish them.
	    
	    The cases have been found with a script:
	    
		    $ find -type f \
		    | xargs grep -l '^\.TH ' \
		    | sort \
		    | xargs mansect SYNOPSIS \
		    | man /dev/stdin \
		    | grep -e '^[^ ]' -e '[^ ]( [^ )].*[^)];' \
		    | less;
	    
	    Reported-by: Mark Naughton <mnaughto@redhat.com>
	    Suggested-by: Mark Harris <mark.hsj@gmail.com>
	    Acked-by: Mark Naughton <mnaughto@redhat.com>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/man/man2/readlink.2 b/man/man2/readlink.2
	index 8e543851..b6c663cd 100644
	--- a/man/man2/readlink.2
	+++ b/man/man2/readlink.2
	@@ -13,14 +13,14 @@ .SH SYNOPSIS
	 .nf
	 .B #include <unistd.h>
	 .P
	-.BI "ssize_t readlink(size_t " bufsiz ;
	+.BR "ssize_t readlink(" "size_t bufsiz;"
	 .BI "                 const char *restrict " path ,
	 .BI "                 char " buf "[restrict " bufsiz "], size_t " bufsiz );
	 .P
	 .BR "#include <fcntl.h>            " "/* Definition of " AT_* " constants */"
	 .B #include <unistd.h>
	 .P
	-.BI "ssize_t readlinkat(size_t " bufsiz ;
	+.BR "ssize_t readlinkat(" "size_t bufsiz;"
	 .BI "                 int " dirfd ", const char *restrict " path ,
	 .BI "                 char " buf "[restrict " bufsiz "], size_t " bufsiz );
	 .P

> Is there a particular style preferred? Either strlcpy/strncpy needs to
> be also doing bold for the forward declaration or readlink should be
> changed to not be bold on the forward declaration.

From what I can see (both when reading readlink(2) and strncpy(3), and
reading the diff pasted above), readlink is in Roman as expected.

If you can reproduce the difference, please share the details.  Maybe
there's something wrong that I'm not seeing.


Cheers,
Alex

> 
> WDYT?
> 
> Thanks,
> Dirk



-- 
<https://www.alejandro-colomar.es>

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