Hi, Alex! At 2021-11-02T17:57:28+0100, Alejandro Colomar (man-pages) wrote: > Hey Branden! > > I need your wisdom :)
I hope to find some, someday... ;-)
> I'm facing the 3-faces problem right now.
> I'm trying to write the following sentence:
>
> [
> The macros [U]INTN_WIDTH expand to the width in bits of these types
> (N).
> ]
>
> With the following requisites:
>
> - N is variable, and so (I think) I want it in italics.
> - INT _WIDTH is a macro, and so I want it in bold.
> - [ ] is just indicating an optional character, and so I want it in
> roman.
> - It's all a single identifier, so breaking it into multiple lines to
> avoid > using \f would hurt readability.
Understood. These are all reasonable choices, and the first three are
normative in man pages. The last is one of two ugly sides on a
two-headed coin, and defensible.
> My approach was the following:
>
> [
> The macros
> .RB [ U ] INT \fIN\fP _WIDTH
> expand to the width in bits of these types
> .RI ( N ).
> ]
>
> but for some reason the underscore (_) is also set in italics (well,
> under-underscored, since italics is just a big hype :).
According to my experiment, it is in fact bold as you desire.
The problem is that it's hard to tell an underscored underscore from a
bold underscore.
For that matter, even with a proper typesetting engine, it's nearly
impossible to tell a roman underscore from an italicized one--an
underscore has no vertical component to slant!
> I'm not sure if I'm doing it wrong (somewhat likely), or if it's a bug
> in groff. The weird thing is that WIDTH, even if it's in the same
> word as '_', it correctly ends up in bold.
>
> I'm using 1.22.4 (Debian Sid).
I tried groff 1.22.4 as well. I dumped the output through 'xxd' to
verify that the expected SGR escape sequences are coming through. Since
I can't ever remember SGR's inscrutable numbers, I added some text to
make life easier.
.B Bold.
.I Italics.
$ groff -Tutf8 -man EXPERIMENTS/alex.man | xxd
00000000: 666f 6f28 3329 2020 2020 2020 2020 2020 foo(3)
00000010: 2020 2020 2020 2020 2020 204c 6962 7261 Libra
00000020: 7279 2046 756e 6374 696f 6e73 204d 616e ry Functions Man
00000030: 7561 6c20 2020 2020 2020 2020 2020 2020 ual
00000040: 2020 2020 2020 2020 666f 6f28 3329 0a0a foo(3)..
00000050: 0a0a 1b5b 316d 4e61 6d65 1b5b 306d 0a20 ...[1mName.[0m.
00000060: 2020 2020 2020 666f 6f20 2d20 636f 6d70 foo - comp
00000070: 7574 6520 6120 6261 7220 6f66 6673 6574 ute a bar offset
00000080: 2062 7920 6261 7a0a 0a1b 5b31 6d44 6573 by baz...[1mDes
00000090: 6372 6970 7469 6f6e 1b5b 306d 0a20 2020 cription.[0m.
000000a0: 2020 2020 1b5b 316d 426f 6c64 2e20 2020 .[1mBold.
000000b0: 1b5b 346d 1b5b 3232 6d49 7461 6c69 6373 .[4m.[22mItalics
000000c0: 2e1b 5b32 346d 2020 2054 6865 206d 6163 ..[24m The mac
000000d0: 726f 7320 5b1b 5b31 6d55 1b5b 3232 6d5d ros [.[1mU.[22m]
000000e0: 1b5b 316d 494e 541b 5b34 6d1b 5b32 326d .[1mINT.[4m.[22m
000000f0: 4e1b 5b32 346d 1b5b 316d 5f57 4944 5448 N.[24m.[1m_WIDTH
00000100: 201b 5b32 326d 6578 7061 6e64 2074 6f20 .[22mexpand to
00000110: 7468 6520 7769 6474 6820 696e 2062 6974 the width in bit
00000120: 730a 2020 2020 2020 206f 6620 7468 6573 s. of thes
00000130: 6520 7479 7065 7320 281b 5b34 6d4e 1b5b e types (.[4mN.[
00000140: 3234 6d29 2e0a 0a0a 0a67 726f 6666 2074 24m).....groff t
00000150: 6573 7420 7375 6974 6520 2020 2020 2020 est suite
00000160: 2020 2020 2020 2020 2020 2032 3032 31e2 2021.
00000170: 8090 3131 e280 9030 3320 2020 2020 2020 ..11...03
00000180: 2020 2020 2020 2020 2020 2020 2020 2020
00000190: 2020 2020 2066 6f6f 2833 290a foo(3).
In the foregoing we can see that '[1m' precedes bold, and '[22m'
precedes italics. Before "_WIDTH', I see "[1m".
A check of xterm's ctlseqs.ms confirms.
CSI Pm m Character Attributes (SGR).
Ps = 0 → Normal (default), VT100.
Ps = 1 → Bold, VT100.
Ps = 4 → Underlined, VT100.
Ps = 2 2 → Normal (neither bold nor faint), ECMA‐48 3rd.
Ps = 2 4 → Not underlined, ECMA‐48 3rd.
So everything looks correct to me.
For grins, try this on your terminal.
printf '_\\fB_\\fI_\\f(BI_\n' | nroff | cat -s
On the xterm I'm running, these four are distinguishable, but I'm not
sure I could reliably guess the style of each one if it were presented
to me in isolation.
If there is a lesson here, I think it is to never use underscores,
dashes, equals signs, or other glyphs with only horizontal strokes at
the boundaries of metasyntactic variables, because they are too easy to
confuse with the same glyphs in roman (and, for the underscore only,
with bold on terminals). This is a mostly hypothetical concern in Unix
man pages, I think, because (1) people already generally don't do this
(I tend to use letters, digits, and dashes/hyphens exclusively in
metasyntactic variable names), and (2) none of those characters has
meaning in the roman face and conventions used for syntax synopses.
Regards,
Branden
signature.asc
Description: PGP signature
