Re: [Groff] Nesting font macros in man pages

[G. Branden Robinson]

At 2017-04-25T07:04:27+0200, Ingo Schwarze wrote:
> 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.

No, what I really want is a TP-ish macro that lets you break the tag
across multiple input lines, so the writer doesn't have to use font
escapes.

If that means a new macro, I'm fine with that.

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

This is fine, but it says to me that your original complaint ("a
horrible hack [to be] avoided ... even in the implementation of macro
sets") is overstated.

Maybe \c it's like inline assembly in C.  Something best reserved to
experts under special circumstances, perhaps, but not a horrible hack.

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

You confuse my methods for my goals.  I am no Werner Lemberg and I am
wide open to alternative implementation proposals.  I was simply
surprised at how easy it was to get what I wanted, and how little
collateral damage there was by doing so.

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

I need to look more deeply into that; I don't know how you'd implement
mandoc without implementing the bulk of *roff.

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

Well, fine, let's proceed with that, then.  See end of this mail.

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

I don't agree, but we have different opinions about the utility of
an-ext.tmac.  I think it's valuable.  With EX/EE, for example, one
hardly needs .nf/.fi requests for the purposes I've seen it used: code
or shell session examples.

The groff community needs to be singing from the same hymnal when it
comes to recommended best practices.  If an-ext.tmac should be
deprecated and avoided, that needs to be formally established and
reflected in the software releases, maybe with a .tm warning in its
source.

How do others in the group feel about an-ext?

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

Yes, but so are character escapes, which are unavoidable in good manpage
writing.

The reason \c attracted my attention was because it enabled the
suppression of word-breaking, which in turn enables the use of macros
for font changes rather than escapes.  I mentioned this before, but I
hate font escapes.  I think we should give man(7) users a way to write a
good manpage without ever using them.

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

Okay.  What alternatives can you propose for getting rid of \f in man
pages, short of migrating the universe to mdoc?

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

What I'm hearing is that you feel that man(7) is a lost cause:

A.  It desparately needs improvement because of its presentational,
    rather than semantic, focus.
B.  Improvement will break portability.

This basically amounts to doing nothing and letting man(7) die of its
own accord.

But it hasn't.  Look at the past 20 years.  It's still alive, and what
vibrancy it has lost, it has lost to stuff like Markdown which is even
_less_ semantic.  Not to mdoc.

I think an-ext has taken a good approach; add semantic markup to the
language, and license the macros so permissively that man page authors
have no reason _not_ to inline them if they care to target legacy
systems.

My recommendation is to take the momentum an-ext has, however small, and
press it:

a.  Add more macros to fit semantic needs and the hiding of lower-level
    requests and escapes.
b.  Hand-hold users to the nth degree with examples and recommended best
    practices.
c.  Show people a mapping from groff's "extended" man macro package to
    mdoc, so that the route for switching over is clearly signposted.

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

I have my pet peeves as well; I don't like the shouty caps in arguments
to TH and SH.  That's information-losing and presentationy.  Why not
encourage people to have site-local files that redefine these macros to
do a ".tr aAbBcC" etc. if they insist on seeing screaming caps?

The first half of your complaints (which section headings should be
present, and in what order) are not presentational, on the other hand,
and IMO would be best sorted out by convening a working group.  I don't
see any other way to attack that problem.  Two independent sources of
fiat have not brought about harmonization.

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

Is that official?  The last time I checked their list archives (a few
months ago), they were openly wondering "whither texinfo?" but hadn't
yet decided to abandon the project.

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

Yes, the problem is "AI-hard" which is why I don't consider it viable.

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

I'm perfectly willing to abandon my hare-brained itc hack, but my
underlying objective remains, and I disagree with your final statement.
man(7) matters most where it is being read--and that's on every *nix
system that still supports a terminal interface.

The mdocification of the universe has not happened of its own accord and
it won't.  If we want to get people there, we have to show them a way.
Throwing mdoc(7), groff_mdoc(7), and mdoc.samples(7) at them has not
done it.

I emphasize: GNU roff's _own_ man pages are written predominantly in man
rather than mdoc.  If we are physicians, we had better heal ourselves.

This discussion is sprawling quite a bit.  I see three further
directions that are largely independent:

1.  Let's document, for the newbs and ourselves, what the heck "\c"
    really means.

2.  Let's figure out whether we have any consensus for the further
    development of an-ext.

3.  Let's talk to the man-pages folks about harmonizing style
    recommendations.  If full consensus cannot be achieved, I note that
    mdoc already supports "ATT" vs. "BSD" style conventions in some
    places.  With care, an-ext could support "GNU" vs. "LNX" (say)
    conventions, and the man page author could declare his or her
    allegiance with a single macro call at the top of the page source.
    Plus it would keep the "GNU/Linux" wars going, and they're in dire
    need of a new front in the flame wars.  ;-)

I don't propose to undertake (3) right away, but I'd like to solicit
opinions on (1) and (2) now to direct my own work.

Are there items you'd like to add?

Regards,
Branden