[Groff] Re: Simplifying groff documentation

[Werner LEMBERG]

> I want to drastically simplify the markup used in several pieces of
> groff documentation, eliminating a lot of the hairy custom macros
> they presently use.

Mhmm.

> groffer.1
> groff_out.5
> groff_tmac.5
> groff.7.gz
> groff_char.7
> groff_mdoc.7
> groff_trace.7
>
> Technically this won't be hard; I could make the required changes in a few
> hours.  But I hear you asking "Why fix what ain't broken?".

Hehe.  There's some truth in it.

> The immediate technical answer is "the macro hackery is getting in
> the way of lossless translation to a Web-ready format".

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.

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

> I want to fix the groff documentation so that it's no longer in the
> way of automatic lifting of *everything* to HTML.  (As a side
> benefit, the markup in the groff documentation will become easier to
> maintain.)  The only downside might be a slight decrease in the
> visual quality of the printed versions -- in particular, command
> synopses might no longer look quite as pretty.

Indeed.  The `only downside' is one of my main concerns.  And the
`slight decrease in visual quality' is sometimes really terrible.  I
really dislike the `unify everything, but in worse quality'.  There
*must* be a solution which satisfies both you and me.

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.

> The philosophical issue this raises about groff's place in the world
> is simple: are we willing to accept that it's a legacy rather than a
> primary format?

I don't care, really.  Personally, I dislike docbook as an input
format but this is just me.

> But I think it's time to move on.  This little change will help us
> get to a fully-hypertexted, Web-centric documentation corpus. Let's
> do it.

Let's do it right.

> (And brace yourselves for the *real* political bunfight, which is
> when I try to kill off GNU info...)

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


    Werner