Re: [Groff] Nesting font macros in man pages

[Ingo Schwarze]

Hi,

G. Branden Robinson wrote on Mon, Apr 24, 2017 at 11:41:22AM -0400:

> to the more readable (and, I submit, more writable-by-the-novice):
> 
> .TP
> .B \-scale \c
> .IR xfac [, yfac ]
> Multiply the horizontal and vertical window size by

YIKES, that sounds like an absolutely terrible idea!

The \c escape sequence is a horrible hack that should never
be used by end users and should be avoided, if possible,
even in the implementation of macro sets.  Did you read the
description of \c on:

https://www.gnu.org/software/groff/manual/html_node/Line-Control.html

It is horribly complicated, referring to various purely internal
concepts.

Besides, i'm not at all convinced that this is even mildly portable.
For example, the Heirloom nroff/troff User's Manual says that "the
next encountered input text line will be considered to be a
continuation of the same line of input text".  So, the effect is
only defined if both the interrupted line and the continuation
line are *text lines*, and neither ".B ..." nor ".IR ..." qualify
as text lines as far as i can tell: both are macro lines.
Even the groff documentation talks about "the next input text line".

It may happen to more or less work in some cases with the current
groff implementation, but relying on that would seem unwise to me.

Yours,
  Ingo


P.S.
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, and even that
is becoming less and less of an argument for using it given the
wide availablity of both mdoc(7) itself and the mandoc -Tman
mdoc(7)-to-man(7) converter.  If, by fiddling with man(7) syntax,
you harm man(7) portability, then you really throw it's last remaining
asset overboard.