Re: [Groff] Nesting font macros in man pages

[Colin Watson]

On Mon, Apr 24, 2017 at 06:29:57PM +0200, Ingo Schwarze wrote:
> There is little you can do to make writing legacy man(7) code
> easier for the novice.  The problem is that it always requires
> mixing two different language levels:  man(7) macros and low-level
> roff requests and escapes.  And that it also requires writing
> physical rather than semantic markup, which is obviously harder
> to do in a consistent manner.
> 
> Writing mdoc(7) is much easier for the novice because it's semantic
> and because it does not require mixing in low-level roff features.
> But trying to make man(7) easier to write is bound for disaster.
> The only remaining asset of man(7) is portability,

The main practical reason I've stuck with man(7) in some cases (such as
in man-db) despite generally preferring mdoc(7) is that I think
translations are important, and po4a(1) works rather more gracefully
with man(7).  With mdoc(7), I find that I end up with nonsense like this
in my .pot file, which I really can't expect a translator to have the
slightest clue about:

  #. type: Plain text
  #: madison-lite.1:21
  msgid ""
  "E<.Nm> E<.Op Fl Fl config\\-file Ar file> E<.Op Fl Fl mirror Ar directory> "
  "E<.Op Fl Fl nocache> E<.Op Fl Fl update> E<.Op Fl S> E<.Op Fl r> E<.Op Fl a "
  "Ar architecture Ns Op , Ns Ar ...> E<.Op Fl c Ar component Ns Op , Ns Ar "
  "...> E<.Op Fl s Ar suite Ns Op , Ns Ar ...> E<.Ar package> E<.Op Ar ...>"
  msgstr ""

Locale::Po4a::Man(3pm) does offer some ways to hit this over the head,
but they don't really work very well in practice, I think because it
doesn't understand the way that mdoc(7) parses its argument list for
callable macro names.  An understandable omission given the complexity,
but it does end up being a blocker for me.

This is of course not a deficiency in *roff, but it's a problem in the
wider ecosystem that IMO a serious push towards mdoc(7) ought to
address.

-- 
Colin Watson                                       address@hidden