Re: a point of curiosity about ncurses man pages

[G. Branden Robinson]

At 2024-04-14T16:59:01-0400, Thomas Dickey wrote:
> On Sun, Apr 14, 2024 at 02:48:29PM -0500, G. Branden Robinson wrote:
> > I noticed some changes in this week's snapshot.
> 
> it's to inform my checking-script that it was intentional (I've
> used that script to find several cases where
> 
>       .I foo,
> 
> should have been
> 
>       .IR foo ,
> 
> and putting quotes (which I'm aware don't matter) helps to filter out
> the noise.  If I really wanted it that way, I'd quote it to make the
> script ignore it:
> 
>       .I "foo,"

Ah.  I had noticed changes like this before.

_Typographically_, in my opinion, setting trailing punctuation in
italics when the preceding word is looks better.  Obviously, from a
block-structured HTML-esque perspective, it's "incorrect".  What I tend
to do in the groff man pages is let the punctuation italicize if I'm
using the word as a piece of terminology, not something that would be
copied and pasted.  Otherwise I separate them as you do.

I'll try to follow your convention in future patches I submit to the
ncurses man pages.

> > To the best of my knowledge, in all *roffs everywhere, arguments in
> > macro calls are separated by (unescaped) spaces and nothing else,
> > except in Plan 9 troff, where tab characters are also treated as
> > argument separators (and groff documents this).
> 
> but (barring \'s, etc), quotes work, too

Right; `\ ` does not separate arguments in macro call.

It may not come up in the ncurses man pages, but aggressive quoting of
macro arguments _can_ have surprising consequences due to AT&T troff's
rules for embedding quotation marks _in_ macro arguments.

$ cat EXPERIMENTS/quoted-macro-argument.roff
.de XX
\\$1
..
.ds A baz
.ds B "qux"
.XX foo
.XX "bar"
.XX \*A
.XX "\*B"
$ nroff EXPERIMENTS/quoted-macro-argument.roff| cat -s
foo bar baz qux"

I figure most people would not perfectly predict all of that output.

(The foregoing also illustrates an interesting trait of the `ds`
request.  But people who seek to write portable man pages should not
have to sweat these details 99.99% of the time.)

I would just keep this in the back of your mind when applying quotes to
macro arguments.

Regards,
Branden

signature.asc
Description: PGP signature