Re: [Groff] Nesting font macros in man pages

[Ingo Schwarze]

Hi,

G. Branden Robinson wrote on Mon, Apr 24, 2017 at 09:22:25PM -0400:
> At 2017-04-24T18:29:57+0200, Ingo Schwarze wrote:
>> 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?

Both, because both only make sense together.  If you don't change the
definition of the .TP macro, you cannot use .TP headers containing
two macro lines.  If you don't want two-line .TP headers, there is no
point in changing the syntax of the .TP macro.

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

Sure, i admit roff is not an easy language, so the implementation
of roff macros is often not pretty.  Given that Werner wrote much
of the groff_mdoc(7) implementation, and he really knows what he
is doing, i suspect that most uses of \c could not be avoided.
While mdoc(7) is easy to use, the implementaion is not trivial
at all; in particular the modern groff implementation is quite
a refined thing, much more so than Cynthia's original 4.4BSD
implementation, which was much simpler.

> 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 does seems likely that there is some way to harmonize Heirloom
with what gets done in groff.  But i do doubt the basic direction
in this specific respect.

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

Well, and the partial one in mandoc, but mandoc follows groff in
roff matters.

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

I do suspect there is room for improvement, or at least clarification,
in the \c specification, so working on that likely makes sense.
But please, regard that as a work to help macro implementors,
**not** end users!

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

Well, as long as one doesn't make matters worse, keeping up hope
is not a sin.  :-)

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

Small subsets, yes.  The roff language is indeed quite large, and
man(7) manual pages typically only need a fraction of it.  But
almost every man(7) manual page requires *some* low-level roff
requests.

> In my experience, one can write an attractive manpage almost without
> ever restoring to straight requests.

And yet you suggest that authors should use the \c escape sequence,
which quite definitely is a very low-level roff feature and not
an element of the man(7) language at all.  In the example you
bring up, there is indeed no viable alternative to using \f font
escapes.  You propose to trade the \f for \c.  I say \c is much
worse than \f.  The syntax and semantics of \f is relatively
easy to understand, and people writing man(7) are used to it, while
\c is quite arcane.

> (People are often ignorant of the an-ext macros, which are so
> liberally licensed they can be used anywhere.)

I admit that the en-ext macros minimally improve semantic capabilities
of the man(7) language, but by so little that man(7) remains an
almost exclusively presentational language even with man-ext.
For that reason, i deem that using man-ext does more damage than
good:  It doesn't substantially improve the language, but it
does cause compat grief on old systems, which is exactly where
the legacy man(7) language is still needed.  Bad tradeoff...

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

I mostly agree, with very few reservations.  Their section headers
are gratuitiously different from what groff recommends (in
groff_mdoc(7)) and are out of order.  Some should better not be
used (CONFIGURATION, OPTIONS, ATTRIBUTES, NOTES) and some have
unusual titles (EXAMPLE instead of EXAMPLES, CONFORMING TO instead
of STANDARDS, VERSIONS instead of HISTORY).  AUTHORS should be
encouraged rather than discouraged.  Besides, i'd recommend
constant-width/typewriter font for special macros and errno names
rather than bold, and i see no need to make references to other
manual pages bold, the section number in parentheses is obvious
enough.  I would also disagree with part of the advice given below
"Example programs", but all of the above is minor.  The general
direction of man-pages(7) is very useful.

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

Frankly, i'm not sure.  Illumos has, for example; so of the free
operating systems, it's mostly GNU that doesn't use it.  One reason
could likely be that GNU used to use texinfo(1), but that is being
abandoned now.

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

No real objection to that, if it can be done, but little hope here,
except maybe for style recommendations, and man-pages(7) clearly is
already quite good at that.

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

Sounds good to me.

> People are already writing it wrong--a lot.

That is certainly true.  I see it in our ports tree.  Average quality
of hand-written third party man(7) - unless from Kerrisk, of course -
is usually below average quality of hand-written mdoc(7).  Usually,
the least problematic man(7) code you find in the wild is pod2man(1)
output.

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

I have very little hope for that.  The best we can hope for would
be a tool to convert from man(7) to mdoc(7), doing some guessing of
the required markup, but requiring considerable manual postprocessing.
I know that a full converter is not a realistic goal because i am
maintaining pod2mdoc(1), which is about the same difficulty, and i
used it to convert the complete corpus of OpenSSL manuals, so i
know quite well which amout of postprocessing is required, and
which problems you face when trying to improve the automatic
guessing.

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

> I'd like to see what we can achieve by fiddling with it _without_
> harming its portability.

Sure, but your proposed change from .it to .itc together with the
changed .TP idiom you propose very seriously breaks portability.
If people would start using that, their manuals would severly
misformat on old systems.  And legacy systems that no longer get
properly updated and maintained is exactly where man(7) matters
most nowadays.

Yours,
  Ingo