linux-kernel - Re: [PATCH v4 03/10] man/man2/fspick.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] [thread-next>] [day] [month] [year] [list]

Message-ID: <5mty7i4v7ygpbedhjevg2fvdlm26rmxeatar7a2u675ulacfyh@ljjjc4za4nl6>
Date: Sun, 21 Sep 2025 17:17:20 +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 03/10] man/man2/fspick.2: document "new" mount API

Hi Aleksa,

On Mon, Sep 22, 2025 at 12:55:13AM +1000, Aleksa Sarai wrote:
> > This should use '.B. (Bold).  BR means alternating Bold and Roman, but
> > this only has one token, so it can't alternate.
> > 
> > If you run `make -R build-catman-troff`, this will trigger a diagnostic:
> > 
> > 	an.tmac: <page>:<line>: style: .BR expects at least 2 arguments, got 1
> 
> Grr, I thought I fixed all of these. I must've changed it in a rework
> and forgot to fix it.

No problem; mistakes happen.  :)

> > > +Please note that\[em]in contrast to
> > > +the behaviour of
> > > +.B MS_REMOUNT
> > > +with
> > > +.BR mount (2)\[em] fspick ()
> > 
> > Only have one important keyword per macro call.  In this case, I prefer
> > em dashes to only be attached to one side, as if they were parentheses,
> > so we don't need any tricks:
> > 
> > 	Please note that
> > 	\[em]in contrast to
> > 	...
> > 	.BR mount (2)\[em]
> > 	.BR fspick ()
> 
> Based on my testing, doing it that way adds whitespace to one side of
> the em dash

You're correct; this adds whitespace on one side of the em dash.

> and typographically em dashes should not have whitespace on
> either side AFAIK.

This rule differs for different style guides, and different languages.
In Spanish, the most common style is having spaces as if the dashes
were parentheses; very much in a logical style, like quotes not having
extraneous punctuation inside them.

I very much prefer the Spanish conventions, and dislike the more common
used conventions for English.  I don't know if Branden can illustrate us
with some history about em dashes.

> If there is a way to get the layout right without
> breaking the "one macro per line" rule, I'd love to know! :D

There's a way.  I'll show it just for your curiosity.  :D


	.BR mount (2)\[em]\c
	.BR fspick ()

(I hope it works, because I haven't tested it.  Accidental typos might
 break my untested examples.)  :)


Cheers,
Alex

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

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