Re: [Groff] Re: Simplifying groff documentation

[Gunnar Ritter]

"Eric S. Raymond" <address@hidden> wrote:

> > 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 
>
> ?

2)

> > 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.

With a little CSS added, it suffices to do what I want, i.e. to
convert manual pages (whose source code I control) to HTML just
to give people an idea about the programs before they download
and install them.

> 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.

That was also my impression when I was looking for such tools.

> 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, 

Certainly not. I know the source code of DWB 2 troff quite well
now, but I have never used any closed-source version of troff.

> so I would put your judgment on this above mine,

Real *roff is hardly the problem since it has supported the
two-character requests (except .do) for more than thirty years
now. The issues are with scripts that convert manual pages or
build indexes for them or whatever. I would say a program that
claims to read manual pages is broken enough to be irrelevant
if it cannot at least handle

  .br .fi .nf .sp .ig .in .ti

Also it must have basic tbl support.
  
Then there are requests that do not hurt so much if they are
left uninterpreted, e.g.

  .ps .ss .cs .bd .ft .fp .ad .na .vs .ls .ll .lg
  .ul .cu .hy .hw

Under some circumstances, it may be appropriate to use other
requests when the benefits outweigh the risk of glitches with
some viewers; for example, I think it is okay when the manual
page for eqn or some other math-oriented program uses .EQ/.EN
and eqn markup.

I have normally avoided .de/.ds/.nr since it is not difficult
to do so. But scripts in current practice might well be able to
handle these, I do not know exactly what their limitations are.
I just think it is advisable to be cautious.

        Gunnar