search

wryun / es-shell

es: a shell with higher-order functions
http://wryun.github.io/es-shell/
Other
313 stars 26 forks source link

Remove the errant 0s from the man page #64

Closed jpco closed 11 months ago

jpco commented 11 months ago

I don't know if others have noticed this, but the number 0 has started infecting the man page, everywhere there's some special text marked by the .Cr or .Rc or .Ci macros.

How does this change work? I have no idea. Does it have side effects? Not as far as I can tell, by just running man ./doc/es.1, but surely this line was the way it was for a reason. This line I'm changing here hasn't changed since the man page was first written, so I have no clue what caused this to happen.

If anybody here is actually troff-knowledgeable, please tell me what I'm doing wrong here.

memreflect commented 11 months ago

I just tried with GNU roff's nroff and saw the same thing myself.

Consulting the Troff User's Manual revealed \s(10 is the correct fix for troff implementations to correctly change the type size to 10:

Note that through an accident of history, a construction like \s39 is parsed as size 39, … while \s40 is parsed as size 4 followed by 0. The syntax \s(nn and \s±(nn permits specification of sizes that would otherwise be ambiguous.

The relevant groff docs indicates support for \s(10, and indeed it fixes things without affecting the other implementations i tried (Heirloom's nroff/troff, plan9port's nroff/troff, man/man -t on FreeBSD).

Update

The relevant change was in the announcement of groff 1.23.0, which states that an error will occur when the -C compatibility mode flag is enabled:

$ nroff -C -man doc/es.1 > /dev/null
troff:src/es-shell/doc/es.1:228: error: ambiguous type size in escape sequence; rewrite to use '\s(10' or similar
troff:src/es-shell/doc/es.1:229: error: ambiguous type size in escape sequence; rewrite to use '\s(10' or similar
troff:src/es-shell/doc/es.1:231: error: ambiguous type size in escape sequence; rewrite to use '\s(10' or similar
troff:src/es-shell/doc/es.1:236: error: ambiguous type size in escape sequence; rewrite to use '\s(10' or similar
<-- 619 lines omitted -->
troff:src/es-shell/doc/es.1:2846: error: ambiguous type size in escape sequence; rewrite to use '\s(10' or similar
troff:src/es-shell/doc/es.1:2853: error: ambiguous type size in escape sequence; rewrite to use '\s(10' or similar
troff:src/es-shell/doc/es.1:2862: error: ambiguous type size in escape sequence; rewrite to use '\s(10' or similar
troff:src/es-shell/doc/es.1:2864: error: ambiguous type size in escape sequence; rewrite to use '\s(10' or similar
jpco commented 11 months ago

Yes! Great work finding that! Updated to the actual fix now.