[Groff] Re: Simplifying groff documentation

[Werner LEMBERG]

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

Not really a macro facility, rather regular expressions.

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

Not necessarily.  Currently, you are applying doclifter's heuristic
engine to guess a high-level structure of a man page (cf. the example
w.r.t. embedded C code snippets you've given in another mail).  The
markup in some groff man pages is already doing this -- it implements
macros which gives you those high-level markup!  With other words, a
regexp solution would provide a direct translation instead of reduced
markup followed by educated guessing.

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

This, admittedly, is a valid argument.  But it leads to nowhere IMHO.
It's the same as with HTML -- I'm sure there are still browsers which
can't display HTML 4 correctly...

A man page for groff probably should demonstrate the features it
provides.  On the other hand, I could protect them with

  .if !\n(.g \
  .  ab This man page can be displayed with GNU troff only!

which should `solve' the problem immediately :-)  Honestly, I won't
mind to do

  .ie !\n(.g \{\
    Minimal stuff explaining what it is, where to look at,
    how to process, etc.
  .\}
  .el \{\
    Full groff man page.
  .\}

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

Well, this is something different, I agree.  What's your suggestion to
improve this?  Is it possible at all to write troff code (not
necessarily man markup) so that doclifter can display something nicer?

> > Well, you can start your training with handling groff.texinfo...
>
> Sorry, I don't understand that.

I've misunderstood you.  Apparently, you don't plan to write a
`lifting' engine by yourself to handle texinfo, right?  Otherwise, you
could try groff.texinfo for testing purposes since it uses texinfo to
its extremes -- you might look up the many bug reports I've sent to
bug-texinfo within the last years.


     Werner