italicizing pointer stars (was: [PATCH] getline.3: wfix.)

G. Branden Robinson
2022-08-05T19:20:14Z

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

At the risk of opening another typographical can of worms...

At 2022-08-02T14:17:24-0700, enh wrote:
> diff --git a/man3/getline.3 b/man3/getline.3
> index 8b7357825..cb9e5b049 100644
> --- a/man3/getline.3
> +++ b/man3/getline.3
> @@ -36,12 +36,12 @@ Feature Test Macro Requirements for glibc (see
> .BR getline ()
> reads an entire line from \fIstream\fP,
> storing the address of the buffer containing the text into
> -.IR "*lineptr" .
> +.IR *lineptr .
[several other instances in same page snipped]

I'm wondering if we should really be setting the dereferencing operator
in italics here.

In declarations, the star is part of the _type_, not the identifier.
Similarly, in expressions, the star is an operator, like "+", not part
of the identifier.

Before answering, consider also the common practice of "setting all
literals in bold". I think this habit is over-applied, and thus I do
not articulate it in groff_man_style(7)[1]. Here, an insistence upon it
in the above-quoted case leads us straight into the three-font problem,
and an especially devilish case of it to boot.

We would need...

.BI * lineptr\c
\&.

...where our man page contributors find not only that they need to
apply the historically nigh-incomprehensible `\c` escape sequence,[2]
but also have to remember to put the ineffable `\&` escape sequence[3]
at the start of the line so that the period will be formatted (rather
than interpreted as the *roff control character).

If the consensus is that applying the "literals in bold" convention
would indeed be too painful, then I suggest adding a style note
regarding this point to man-pages(7), and explaining why it was adopted.

I can propose some language for that.

There _is_ another way to skin this cat.[4]

.B *\c
.IR lineptr .

Maybe that would be preferable.

Regards,
Branden

[1] https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/groff_man.7.man.in
[2] I believe it is explained clearly here.
https://git.savannah.gnu.org/cgit/groff.git/tree/doc/groff.texi#n9509
[3] An argument has been raging on the groff mailing list over the best
nomenclature for `\&` for some time.
https://savannah.gnu.org/bugs/index.php?62816
[4] I reject the use font selection escape sequences out of hand.

[-- Attachment #2: signature.asc --]