[Groff] Why does tty-char.tmac not represent meaning?

[Ingo Schwarze]

Hi,

consider the situation of a document author who strives to write a
roff document with the simultaneous goals of having it render nicely
when typeset (e.g., with -Tpdf) and having it render intelligibly
when on a -Tascii terminal.  For example, that is a usual set of
goals when writing manual pages for portable software.

While most manual pages get away with using nothing but ASCII
characters, there are some specific areas where mathematical symbols
are crucial for understanding, for example in libm and in certain
parts of the X11 libraries.  Right now, it is a bad idea to use
character escape sequences for mathematical symbols in such contexts
because nroff(1) - commonly used by man(1) - includes tty-char.tmac
and tty-char.tmac renders several mathematical symbols in ways that
make it almost impossible to understand the meaning.

>From the comment at the top of tty-char.tmac, i understand that it
deliberately tries to approximate graphical shape and not convey
meaning, but i don't understand why.  When rendering on an ASCII
terminal, graphical shape matters very little (or you would be using
anything but an ASCII terminal in the first place), but meaning is
quite likely rather important.  So this seems like sacrificing an
important, attainable goal in order to pursue an unimportant goal
that, besides, is bound for ugly failure.

History doesn't help me either.  That comment is unchanged since
the beginning of groff git history (groff before CVS: release 1.06).
The earlier groff-1.01 release contained in 4.3BSD-Net/2 (released
August 1991) did not have a file like tty-char.tmac yet; it only
had tmac.tty, which was similar to the modern tty.tmac.  James Clark
created tmac.tty-char on June 2, 1992, but i can't find a rationale
for his choice in ChangeLog.115.


What would you think about changing the - admittedly venerable -
policy in this respect?  About shifting the top priority onto making
the meaning unambiguous in -Tascii output, and only pick a similar
graphical shape if that does not endanger properly conveying the
meaning?

The patch below provides a few examples, picking symbols that
are more frequently used and have particularly hard to understand
renderings.  The patch is neither complete nor consistent, so it
is not intended for commit in its present form.  I'm trying to
get feedback on the general idea and direction, and i'm likely
to draft a proper patch if you say that switching the policy
makes sense to you.

Thanks,
  Ingo


diff --git a/tmac/tty-char.tmac b/tmac/tty-char.tmac
index 93ca2b7c..06b0bfcf 100644
--- a/tmac/tty-char.tmac
+++ b/tmac/tty-char.tmac
@@ -36,23 +36,23 @@
 .tty-char \[dd] \z|=
 .tty-char \[ib] (\z=_
 .tty-char \[ip] \z=_)
-.tty-char \[sb] (=
+.tty-char \[sb] <subset\~of>
 .tty-char \[sp] =)
 .tty-char \[if] oo
 .tty-char \[pt] oc
 .tty-char \[es] {}
-.tty-char \[ca] (^)
-.tty-char \[cu] U
+.tty-char \[ca] <intersection>
+.tty-char \[cu] <union>
 .tty-char \[de] o
 .tty-char \[di] -:-
 .tty-char \[tdi] -:-
 .tty-char \[no] ~
 .tty-char \[tno] ~
 .tty-char \[gr] \Z'\*[tty-rn]'V
-.tty-char \[is] \z'\z,I
-.tty-char \[mo] E
+.tty-char \[is] <integral>
+.tty-char \[mo] <element\~of>
 .tty-char \[pd] a
-.tty-char \[sr] \e/
+.tty-char \[sr] <sqrt>
 .tty-char \[*C] \z_H
 .tty-char \[*D] \z_/\z_\e
 .tty-char \[*F] \zIO
@@ -116,14 +116,14 @@
 .tty-char \[/_] \z_/
 .tty-char \[=~] =~
 .tty-char \[|=] -~
-.tty-char \[Ah] N
+.tty-char \[Ah] <Aleph>
 .tty-char \[CR] _|
-.tty-char \[fa] \z-V
+.tty-char \[fa] <for\~all>
 .tty-char \[nm] \z/E
 .tty-char \[pp] \z_|
 .tty-char \[sd] ''
 .tty-char \[st] -)
-.tty-char \[te] 3
+.tty-char \[te] <there\~exists>
 .if c\[md] .tty-char \[tf] .\[md].
 .tty-char \[tf] .:.
 .if c\[md] .tty-char \[3d] .\[md].