Re: [Groff] Correct protocol for making changes

[Eric S. Raymond]

Werner LEMBERG <address@hidden>: 
> > The previous stuff on my agenda is done, [...]
> 
> Please add a ChangeLog entry!  I insist on having entries for
> everything which isn't trivial (e.g., fixing typos in comments or
> documentation).

A catchup entry is done, and will be in my next commit.  I'll follow this
practice in future.

> > When I go back to trying to make the man pages portable, I'm
> > wondering what the appropriate test protocol is.  Is an eyeball
> > check that it looks right under both man in a terminal window and
> > Postscript sufficient?
> 
> Yes.  Please use groff's `-ww' option to catch potential problems.
> Ideally, there shouldn't be any warnings.
> 
> BTW, according to my experience, a great deal of errors can be caught
> if you use
> 
>   (a) the colorized man output of the Midnight Commander (this is,
>       pressing the F3 key on a man page)
>   (b) different terminal line lengths, say, 80 and 100 characters.

The above sounds like it should be added to a README or TESTING file
in the tmac directory, if for no other reason than that the usefulness
of -ww is not elsewhere documented that I have seen.  I think I'll
make that happen.

I have been applying the eyeball test to .SY/.OP/.YS conversions of
chem.man, grog.man, and the roff2.man pages, and it looks like I have
managed not to screw the pooch this time.  Possibly this is because I
have not yet tried re-converting anything with .eo or truly hairy
macros in it.  I'll torture these pages with groff -ww and mc, and
commit the new versions if that does not reveal breakage.

The truly horrible pages like groff_out.5 and groffer.1 are...still
truly horrible.  But progress is being made.  At this point I think
you can stop trying to rescue my old patches -- instead, I'll do a
second pass at the hard cases using what I learned the first time
around, changing them in small steps and testing each step.  

(It's much, *much* easier to do things in small, manageable steps now
that I have CVS privs, so thanks for that.)

As for the -TMathML code, it has been stable through several runs on
the complete corpus of 13,000+ pages I use for doclifter testing,
producing results that look right and pass xmllint in all cases.  I'm
feeling pretty confident about it.  Until I decide to add mark/lineup
support, or coalesce numeric character boxes, or we decide to address
the font-escape problem in some other way than ignoring them, that 
code is *done*.

It is rather remarkable how easy the -TMathmL implementation was --
less than three days from a gleam in my eye to production-quality
code.  While I will cheerfully admit to being pretty good at things
that resemble compiler-writing, in this case no exceptional skill was
required.  eqn and Presentation MathML have very different syntaxes,
but their object-and-box models are as near identical as makes no
difference.

This isn't a trivial observation, because other models are possible.  
The rather more elaborate box-and-glue one TeX uses, for example, or 
CSS's.  I think one of the principals behind MathML must have studied
eqn very, very carefully.  Which I guess is not surprising.

Makes me wonder why nobody wrote a translator before.  And I did look.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>