Re: [Groff] Nesting font macros in man pages

[G. Branden Robinson]

At 2017-04-24T18:29:57+0200, Ingo Schwarze wrote:
> 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!

My example, or the method I proposed to achieve it?  You quoted the
former but proceeded to discuss the latter and I want to make sure I
understand how many objections you're raising.

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

In that case we groff fans have some sweeping around our own door to do,
first and foremost with the (arguably) two most excellent macro packages
we have:

$ grep -c '\\c' /usr/share/groff/1.22.3/tmac/*.* | grep -v ':0$' \
        | sort -t : -n -r -k 2,2
/usr/share/groff/1.22.3/tmac/doc.tmac:117
/usr/share/groff/1.22.3/tmac/om.tmac:110
/usr/share/groff/1.22.3/tmac/m.tmac:14
/usr/share/groff/1.22.3/tmac/s.tmac:8
/usr/share/groff/1.22.3/tmac/www.tmac:6
/usr/share/groff/1.22.3/tmac/pdfmark.tmac:6
/usr/share/groff/1.22.3/tmac/pdf.tmac:5
/usr/share/groff/1.22.3/tmac/hyphenex.det:4
/usr/share/groff/1.22.3/tmac/hyphen.sv:3
/usr/share/groff/1.22.3/tmac/hdtbl.tmac:3
/usr/share/groff/1.22.3/tmac/e.tmac:3
/usr/share/groff/1.22.3/tmac/an-old.tmac:3
/usr/share/groff/1.22.3/tmac/spdf.tmac:2
/usr/share/groff/1.22.3/tmac/psatk.tmac:2
/usr/share/groff/1.22.3/tmac/doc-old.tmac:2
/usr/share/groff/1.22.3/tmac/an-ext.tmac:2

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

Yes, I've read it before, plus the brief description in groff(7) which I
find so terse as to be incomprehensible, and Kernighan's description of
it is CSTR #54, which also doesn't leave me terribly enlightened.

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

I'm happy to examine the impact this change would have on Heirloom
troff.  First I'd like to get some feedback on my specific objective.

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

There are only two living implementations of *roff in the world, right?
And everybody 

If \c is documented badly and/or under-specified, let's determine its
precise semantics and document them clearly.

> P.S.
> There is little you can do to make writing legacy man(7) code
> easier for the novice.

I don't agree.  Or perhaps more precisely, I haven't yet given up hope.

> The problem is that it always requires mixing two different language
> levels:  man(7) macros and low-level roff requests and escapes.

"Always requires" is much too strong.  Lots of manpages are written in a
very small subset of the language.

In my experience, one can write an attractive manpage almost without
ever restoring to straight requests.  (People are often ignorant of the
an-ext macros, which are so liberally licensed they can be used
anywhere.)

Font escapes can be eliminated if you:
        1) Don't try for constant-width fonts or bold italics; and
        2) Don't try to put rich material in the first line after a .TP.

It's problem (2) that I'm interested in solving in this thread.

> And that it also requires writing physical rather than semantic
> markup, which is obviously harder to do in a consistent manner.

I entirely agree with the virtues of semantic of "presentation"-based
markup.  However, this could be mitigated by encouraging a consistent
style in groff_man(7) itself.  Some coordination with Michael Kerrisk et
al. of the man-pages project would be valuable as well; I think almost
all of the advice in man-pages(7) of that package is very sound.

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

And yet, why have so few people outside of the BSD community adopted it?

It's a great macro package and I admire it.  But USENIX and BSD built
it, and "they" didn't come.

People keeep writing in man(7).  Let's do what we can to help them write
it better.

I submit that one reason mdoc didn't take over the world is for the same
reason DocBook didn't--it's too huge.  I think that man(7), even with
the an-ext stuff added on, is small enough to keep in one's head.

That doesn't mean I think it's superior--I simply think it's easier to
sell to software developers who don't want to learn *roff or write man
pages for a living.  When someone gripes a development team to write a
man page for their tool or library, they can pop off for a bit and do
it.

Ideally, I'd like to make some enhancements to man and its documentation
that encourage people to make the leap to mdoc, _especially_ those
people who are enlightened enough to see the sinfulness of
presentation-based, rather than semantic, markup.  We should make it
obvious to them that the groff people aren't fools, either, and want to
help them make that jump.  But for those who don't, here's man with some
semantic training wheels to file the rougher edges off.

> But trying to make man(7) easier to write is bound for disaster.

No; you presume that making it easier to write means making it harder to
write correctly.  That is the opposite of my intention.

People are already writing it wrong--a lot.

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

Of course what we need is a converter that goes in the other direction;
but that requires the encoding of semantic information that is lacking.

> If, by fiddling with man(7) syntax, you harm man(7) portability, then
> you really throw it's last remaining asset overboard.

I'd like to see what we can achieve by fiddling with it _without_
harming its portability.  Even as small as man(7) is, people neglect a
lot of its capabilities.

-- 
Regards,
Branden