[Groff] Re: Simplifying groff documentation

[Eric S. Raymond]

Werner LEMBERG <address@hidden>:
> Simply replacing them with the `standard' man macros is not the
> optimal solution.  Instead, I would rather prefer some helper
> instructions so that doclifter can do the translation without
> problems.

I tried a similar path.  The problem is that in order to interpret 
the extended macros correctly, doclifter would have to correctly handle
some strange groff macro extensions (such as while looping and \*[ with
arguments) that nobody else in the universe uses.

I'm not averse to hard work, but that much effort for a half-dozen
pages seemed excessive and still does. 

> > So this is the answer to "why fix it?".  Because the groff pages
> > presently do elaborate, bizarre things that doclifter can't cope
> > with.
> 
> Bizarre?  I don't think so.  The results are satisfying.  However, I
> agree that the used macros are non-standard, causing headaches to
> doclifter.

Trust me, while-looping counts as bizarre :-).
 
> The markup used within those man pages is not bad since it tries to
> separate content from layout.  What do you think about a few comment
> lines in the header to `help' doclifter, something like
> 
>   .\" doclifter: .File_name (<foo>) == ...preferred doclifter command...
>   .\" doclifter: .Opt_[--]          == "[--]"
> 
> etc., etc.  Such an interface could be generic, to be used with
> texinfo macros also.

I see.  You're proposing a sort of macro facility that DocBook interprets
itself, overriding the groff macros.

That's kind of an appealing solution.  I would actually enjoy designing and
implementing something like that.   But there are two obvious problems with 
it.  Three, actually...

1) It would address the issue by adding complexity to the markup and the
interpretation path, rather than subtracting it.

2) It won't solve the problem someone else in this thread pointed out,
   which is that the nonstandard macros break other viewers, including
   older *roff versions.

3) It won't solve the actual problem with the simplified markup, which 
   is the command synopsis not looking as nice.

> Well, you can start your training with handling groff.texinfo...

Sorry, I don't understand that. 
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>