Re: [Groff] Simplifying groff documentation

[Eric S. Raymond]

Werner LEMBERG <address@hidden>:
> > > So I think this is worth fixing regardless of the specific case of
> > > DocBook conversion. groff is by far not the only program which is
> > > used to display the groff manual pages.
> 
> Well, does this mean that I should refrain from using any GNU
> extensions in man pages?

I'm not sure what Gunnarr will say, but...Yes.  Yes, actually, I think
it does mean exactly that.

> > Because response on the list was supportive, I went ahead and
> > stripped groff.1.  It's enclosed.  You may have trouble spotting the
> > differences, which is sort of the idea.
> 
> Thanks, especially for fixing Germanisms.  As you've `promised', the
> synopsis is *really* ugly.  In my eyes, it's horrible.

I think that can be fixed with some judicious use of .br and .in at
lower cost thast trying to preserve the wird macros (which, as
Gunnar has pointed out, break other viewers).

> Before doing any hasty actions (this is, committing your changes to
> the CVS) I would like to discuss this topic further.  So please stay
> patient.  Additionally, the `groffer' stuff isn't maintained by me but
> by Bernd, so we have to listen to him too.

I will be patient.  But I will want some resolution on this in finite time.

The alternative to fixing this problem at it source is that (a) other
viewers such as TKMan, Rosetta, or Xman will continue to break on
these pages, and (b) people who want to make decent HTML downsteam of
you would have to integrate patches to strip out the nonstandard
markup.  

This would be just begging for more of a maintenance mess than
getting the Synopses visually perfect on eight man pages 
out of thirteen thousand could possibly be worth.

> BTW, it would have been better to use the current CVS version, which
> differs clearly in some parts.

This is OK.  Now that I've done the conversion once, I can do it  on
any similar document with a couple of Emacs commands.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>