Re: [Groff] Correct protocol for making changes

[Eric S. Raymond]

Werner LEMBERG <address@hidden>:
> I see that you are going to replace \[..] with \(.. -- do we really
> need that?  (a) It makes the code more difficult to read.  (b) I
> thought that we've agreed on staying with long macros/variables/glyph
> names, and that we currently only `normalize' the man pages.

You are right about the long names.  I clean forgot about this, for
reasons I'll explain in a moment.  I can undo that step easily enough
if you want.

> OK.  However, we should come to a conclusion what we are really going
> to achieve.

I've been shooting for "no doclifter warnings".  This is significant because 
I spent about a half-day taking the results of my research into viewer 
portability and teaching doclifter to emit warnings on all nonportable
constructs.

What I forgot is that I overshot the C man2html viewer, our agreed-on
target, a bit when I coded the tests.  In the future I need to let the
long-names and \*[ warnings slide by.  The other ones, for requests
like .tr/.in/.ta etc, are still worth heeding.

Sorry about that.  Came of having too many versions of the portability
report buzzing around in my head and trying to fulfil several
objectives at once.
 
> Looking at the code, it seems to me (being a quite bad C++ programmer)
> that the constant use of `if' clauses to select the output device is
> not very elegant.  Perhaps this could be virtualized, at least to a
> certain extent?  Maybe it's not worth the trouble...

I don't know C++ at all well (I can sort of read it, but not write it).

I believe this could be addressed with virtual methods, but it would
mean that all the class initializer calls would have to be replaced
with calls that dispatch to initializers for one of n different
concrete classes where n is the number of output modes.  

That mode dispatch has to be done *somewhere*; the choices are top,
middle, or bottom of the flow graph.  I elected the bottom so as to
disturb the middle and top (the C++ parts I don't really understand) as
little as possible.

I did think about implementing with named functions for each output
mode, and ::output() methods that are just case statements dispatching
to one of them.  I concluded, on reflection, that the extra layer of
glue would be a larger maintenance problem than the big conditionals
(I wrote warnings about this kind of over-layering in "The Art Of Unix
Programming", for good reasons).

As it is, I know the patch looks large, but using "diff -b" should be
very revealing.  As you've seen, most of the diff lines are from
otherwise-undisturbed troff output code being pushed into if
blocks. With those dropped out, the resulting patch is about 500
lines, over half of which is the troff-special-to-XML-entity
translation table.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>