[Groff] Re: Simplifying groff documentation

[Eric S. Raymond]

Gunnar Ritter <address@hidden>:
> > .br .nl .sp .bp .ft .fi .nf .ul .cu .tm .so .ds .as .rm
> > .rn .em .am .nr .rr .ig .pm .cc .c2 .ab .do 
> >
> > This is not all the requests doclifter interprets.  I also handle
> > .nop .return .mso .als .shift .fam, but recommend against putting
> > these in the safe set because heirloom troff and other viewers 
> > probably won't get them right.
> 
> The "Heirloom troff" I refered to is not plain AT&T troff but my
> extended variant, <http://heirloom.sourceforge.net/doctools.html>.

Hm.  I was not aware of the Heirloom project.  I'm glad someone 
is doing this, and will add a link to it from my Retrocomputing
Museum page.

> From this list it supports anything except .fam.

Sorry, I have to ask this because you're not a native English speaker
and the above seems technically implausible: did you get the sense of
the negative in that sentence reversed?  That is, if

A = .br .nl .sp .bp .ft .fi .nf .ul .cu .tm .so .ds .as .rm
    .rn .em .am .nr .rr .ig .pm .cc .c2 .ab .do 

are you saying:

1) Heirloom troff supports $A plus .fam

or

2) Heirloom troff supports $A plus .nop .return .mso .als .shift 

?

> On the other hand, the script which I use to convert the manual
> pages for my web pages, manServer by Rolf Howarth,
> <http://www.squarebox.co.uk/users/rolf/download/manServer.shtml>,
> supports none of the groff extensions, and also does not support
> .nl, .bp, .ul, .cu, .tm, .as, .em, .am, .rr, .pm, .cc, .c2, .ab,
> and .do from the list of two-character requests. (It generally
> does its job quite good, though.)

I didn't think so.  manServer was one of the sucks-pretty-badly 
translators that made me dissatisfied enough to write doclifter.
The others were man2html and a project that (I think) used to 
be called CMan and later changed its name to RosettaMan.  To be
fair, though, manServer is probably the least bad of the three.

All three have the same flaw: too close to presentation level, almost
no attempt to recognize content patterns.  I knew I could do better
than that.  (My background in AI popping up.)

>                                  Certainly, a look at a single
> script cannot define a set of reasonable requests in manual pages.

Agreed.  Based on your experience of multiple *roff implementations, what 
would you propose as a safe set?  You are probably the only person here 
with experience of even more weird *roff variants than I know about, 
so I would put your judgment on this above mine,
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>