linux-kernel - Re: [PATCH v4 07/10] man/man2/open_tree.2: document "new" mount API

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <aqhcwkln4fls44e2o6pwnepex6yec6lg2jnngrtck3g5pc6q5d@7zibx3l2vrjw>
Date: Mon, 22 Sep 2025 15:22:27 +0200
From: Alejandro Colomar <alx@...nel.org>
To: Aleksa Sarai <cyphar@...har.com>
Cc: "Michael T. Kerrisk" <mtk.manpages@...il.com>, 
	Alexander Viro <viro@...iv.linux.org.uk>, Jan Kara <jack@...e.cz>, Askar Safin <safinaskar@...omail.com>, 
	"G. Branden Robinson" <g.branden.robinson@...il.com>, linux-man@...r.kernel.org, linux-api@...r.kernel.org, 
	linux-fsdevel@...r.kernel.org, linux-kernel@...r.kernel.org, 
	David Howells <dhowells@...hat.com>, Christian Brauner <brauner@...nel.org>
Subject: Re: [PATCH v4 07/10] man/man2/open_tree.2: document "new" mount API

Hi Aleksa,

On Mon, Sep 22, 2025 at 08:09:47PM +1000, Aleksa Sarai wrote:
> > > +is lazy\[em]akin to calling
> > 
> > I prefer em dashes in both sides of the parenthetical; it more clearly
> > denotes where it ends.
> > 
> > 	is lazy
> > 	\[em]akin to calling
> > 	.BR umount2 (2)
> > 	with
> > 	.BR MOUNT_DETACH \[em];
> 
> An \[em] next to a ";"? Let me see if I can rewrite it to avoid this...

You could use parentheses, maybe.

> > > +.IR "mount --bind" )
> > 
> > You need to escape dashes in manual pages.  Otherwise, they're formatted
> > as hyphens, which can't be pasted into the terminal (and another
> > consequence is not being able to search for them in the man(1) reader
> > with literal dashes).
> > 
> > Depending on your system, you might be able to search for them or paste
> > them to the terminal, because some distros patch this in
> > /etc/local/an.tmac, at the expense of generating lower quality pages,
> > but in general don't rely on that.
> > 
> > I've noticed now, but this probably also happens in previous pages in
> > this patch set.
> > 
> > While at it, you should also use a non-breaking space, to keep the
> > entire command in the same line.
> > 
> > 	.IR \%mount\~\-\-bind )
> 
> My bad, I think my terminal font doesn't distinguish between them well
> enough for it to be obvious. I'll go through and fix up all of these
> cases.

I should probably add an automated diagnostic.  At least the case of two
'--' together, which I've never seen useful unescaped, should be
diagnosed.  I'll add a make(1) 'lint-man-dash' target that catches this
with a regex.


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>
Use port 80 (that is, <...:80/>).

Download attachment "signature.asc" of type "application/pgp-signature" (834 bytes)