Re: [Groff] eqn's `...' operator

[Eric S. Raymond]

Ted Harding <address@hidden>:
> How can we find out what precisely, and so far, has been done
> to groff and its components (tbl, eqn, pic, .. ) in the name
> of the man-page upgrade, and what the effects of this are likely
> to be on non-man-page usage? And what is likely to be next in
> the pipeline?

Let me try to answer that question.

The issues I've brought up have triggered three sets of changes.

1. eqn now has a MathML output mode

This was, essentially, one big change that is now finished.  While I was
working on this, I noticed that the eqn 'cdot' primitive could be expressed 
as \(md rather than a period shifted upward by micromotions.  I made
a couple other similar changes, rendering << and >> with the corresponding
groff specials rather than ASCII < and > double-struck via micromotions.

In doing this I had two goals.  One was to push composition of these 
glyphs down to the output driver, where it belongs.  The other was to
narrow geqn's dependency on groff.  I didn't like seeing \v motions in
the geqn  predefined macros, and I got rid of them in favor of 'up' and
'down' operations specified in geqn itself and handed off to geqn's 
postprocessor (whatever that happens to be).

Werner asked whether ... should turn into \(md \(md \(md.  After looking
at the way ... is typeset in the 1976 Guide to EQN, I agreed that this 
seems to have been Kernighan & Cherry's intention, and made that change.

I've already stated that I agree with Tadziu.  If it weren't for the 
compatibility issue, I would have left the rendering of ... as three
lower dots. If there is strong feeling that compatibility should not
govern here, I will revert that change.

None of what's been going on with eqn affects the groff man pages or the 
rest of the groff toolset, except of course that eqn.man has some new
material on MathML output mode.  The behavior of eqn when emitting
troff rather than MathML is, by design, unaltered.

2. Werner and I have defined some extension macros for man pages.

These are .SY, .OP, .YS, .EX, .EE, .UR, .UE, .MT, .ME, and .TQ.  .DS
and .DE are planned to be added, but Werner has not written them yet.
They live in the new an-ext.tmac file.

The purpose of .UR, .UE, .MT, and .ME is to replace .URL and .MTO
macros from www.tmac.  The new ones improve on .URL and .MTO by being
both portable to classic troff and easier to use.

The purpose of the rest of these macros is to reduce the need for raw
troff requests in man pages.  .EX/.EE, for example, obviates the most
common raw-troff cliche in the 13,000-page corpus I test with --
.nf/.fi and .ft calls surrounding a code or configuration-file
example.

My reason for wanting to get rid of as many raw-troff cliches as
possible is so doclifter can do a better job.  Werner's is (I believe)
to make man-page markup more concise and maintainable.  They can be 
sufficiently justified on either ground independently of the other.

Again, the new macros don't affect the groff toolchain itself.  Man-page
authors may choose to ignore them, though we hope they won't.

3. I have been simplifying the groff man pages to use portable markup.

The elaborate macrology and groff-specific extensions used in many of the
groff man pages break both doclifter and non-groff page viewers such as
man2html.  Elaborate macrology is also a maintainability problem.  

I have been hacking these pages into a simpler dialect, one than
man2html and other viewers should be able to handle without garbling.
I have been extremely careful about preserving the content and rendered 
appearance of the groff pages.  Werner and I have developed a test 
protocol, now documented in tmac/TESTING-HINTS, to help ensure that
the pages do not get damaged by this translation.  Werner is keeping
an eye on and occasionally correcting my work.

Once again, the effect on the rest of the groff toolchain is nil, There
have been zero changes to groff itself and zero changes to non-man
macro packages.

I hope that sufficiently answers your question.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>