Re: Rendering of math symbols in ASCII mode

[Ingo Schwarze <schwarze@usta.de>]

Hi Anthony,

Anthony J. Bentley wrote on Sun, Jun 18, 2017 at 06:04:23PM -0600:

> This beauty shows up in erf(3):
> 
> .Bd -filled -offset indent
> .if n \{\
> erf(x) = 2/sqrt(pi)*\|integral from 0 to x of exp(\-t*t) dt. \}
> .if t \{\
> erf\|(x) :=
> (2/\(sr pi)\|\(is\d\s8\z0\s10\u\u\s8x\s10\d\|exp(\-t\u\s82\s10\d)\|dt. \}
> .Ed
> 
> My first instinct was to replace it with eqn(7),

I agree with that direction.  While eqn(7) is better avoided where
it can reasonably be avoided, it is the best solution for those
unusual cases where non-trivial mathematical formulae are essential
content of a manual page.

> a pleasant way to write non-trivial equations:
> 
> .EQ
> roman erf ( x ) = 2 over {sqrt pi} int sub 0 sup x e sup {- t sup 2} dt
> .EN

Why roman?  Aren't function names usually set italic in mathematic
papers?

> This looks great in groff -Tpdf and mandoc -Thtml, and is serviceable
> enough in mandoc -Tutf8. Unfortunately, in ASCII it looks like this:
> 
>     erf ( x ) = 2/(sqrt(n)) I_0^x e^(- t^2) dt
> 
> As per mandoc_char(7), the integral symbol is replaced with I and pi
> is replaced with n. Awful!

Awful indeed, but not our choice.

Look at this in /usr/local/share/groff/1.22.3/tmac/tty-char.tmac:

.\" These definitions are chosen so that, as far as possible, they:
.\" - work with all of -Tascii, -Tlatin1, -Tutf8, and -Tcp1047.
.\" - work on devices that display only the last overstruck character
.\"   as well as on devices that support overstriking
.\" - represent the character's graphical shape (not its meaning)

> While I'm inclined to think that attempting to render equations in pure
> ASCII is somewhat futile, the human-readable nature of eqn(7) suggests
> the possibility of simply displaying the symbol name for certain symbols
> like Greek letters and integrals.
> 
>     erf ( x ) = 2/(sqrt(pi)) int_0^x e^(- t^2) dt

I agree that is a clear improvement.

> This would make it practical to use eqn(7) in certain libm manuals,
> which I think could be a nice improvement. Viewing the math-heavy libGL
> manuals on man.openbsd.org is a real pleasure.
> 
> Thoughts?

Currently, words like "integral" are translated to character escape
sequences by the parser, independent of the output format.  Moving
that translation to the formatters in order to avoid it for -Tascii
would cause code duplication because several formatters need the
same translation: -Tutf8, -Tpdf, -Thtml...

Besider, eqn(7) advertises that "the character escape sequences
documented in mandoc_char(7) can be used, too", in addition to the
translated words, so moving the tranlation to the formatters would
only solve part of the problem and leave people in the rain who -
legitimately - use \(is or \[integral] directly.

So i think the rendering of special characters in -Tascii needs to
be improved, but that requires building consensus with groff first,
hoping that they might be willing to move away from the "graphical
shape, not meaning" paradigm.

Here are some of the unintelligible renderings:

	\(Ah	N	ALEF SYMBOL
	\(fa	V	FOR ALL
	\(pd	a	PARTIAL DIFFERENTIAL
	\(te	3	THERE EXISTS
	\(mo	E	ELEMENT OF
	\(st	-)	CONTAINS AS MEMBER
	\(sr	\/	SQUARE ROOT
	\(ca	(^)	INTERSECTION
	\(cu	U	UNION
	\(is	I	INTEGRAL
	\(sb	(=	SUBSET OF
	\(su	=)	SUPERSET OF
	\(ib	(_	SUBSET OF OR EQUAL TO
	\(ip	_)	SUPERSET OF OR EQUAL TO

I don't think any of these allow intelligible one- or two-character
ASCII renderings.

Multi-character descriptive renderings cause a problem with
spacing.  For example, rendering

  \[sr]2\[mo]R

as

  sqrt2element ofR

is not very readable.

For some character escape sequences that render to nothing in
groff -Tascii, i decided to use descriptive renderings
enclosed in angle brackets in the past:

	\(sc	<sec>	SECTION SIGN
	\(de	<deg>	DEGREE SIGN
	\(ps	<par>	PILCROW SIGN
	\(CS	<lub>	BLACK CLUB SUIT

Do you consider that desirable for cases like the above, too?

	\(Ah	<Aleph>		ALEF SYMBOL
	\(fa	<for all>	FOR ALL
	\(te	<there exists>	THERE EXISTS
	\(mo	<element of>	ELEMENT OF
	\(sr	<sqrt>		SQUARE ROOT
	\(ca	<intersection>	INTERSECTION
	\(cu	<union>		UNION
	\(is	<integral>	INTEGRAL
	\(sb	<subset of>	SUBSET OF
	\(su	<superset of>	SUPERSET OF

There is a similar problem with small greek letters.

  e^iomegat

is not very readable.  Or is it good enough?  Is

  e^i<omega>t 

better?  If so, what about pi?

  cos(2pi) = 1

is obviously fine, but

  exp(2pii) = 1

would arguably be more readable as

  exp(2<pi>i) = -1

It might be a good idea to form consensus here before approaching
the groff community with patches.

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mdocml.bsd.lv