Re: Plan 9 man added a new macro for man page references

[G. Branden Robinson]

Hi, Alex!

At 2021-08-03T09:29:14+0200, Alejandro Colomar (man-pages) wrote:
> Thinking about it twice...

I think your reconsideration is based on some assumptions that are too
categorical.

> Given mdoc(7) already implemented that, and that the basic difference
> between mdoc(7) and man(7) is basically that man(7) is simple and
> doesn't have semantic macros (only style macros),

That is not quite true.  TH, SH, SS, and TP are all semantic, and all
but SS are ubiquitous in page sources.  (SS was implemented but not
documented in the V7 Unix manual (1979), a curse which seems to have
afflicted it with underutilization ever since.)

> and mdoc(7) was designed to superseed man(7) by having semantic macros
> instead of style macros

mdoc was certainly designed to supersede man(7), but it is not
"semantically pure" either.  Its lack of innocence lies more in its
quotation macros than anything to do with setting the typeface, however.
Nonetheless I'm willing to stipulate that mdoc has a superior vocabulary
for expressing semantic annotations to man pages.  It pays a price with
a larger lexicon.

> (but with the side effect of being much more complex in the way), I
> think it would be wrong to "port" back (some of) those features back
> into man(7).
> 
> Either we should move to use mdoc(7), or we don't at all.  (And for
> the moment, I think I'll keep with the man(7) simpler macros.)
> 
> What are your thoughts?

I pretty much share Dave Kemper's perspective on this, to which I would
add, if mdoc were going to bury man(7) in the backyard, it's had 30
years to do so.  Waiting longer is not going to clear man(7)'s problems
off of our plate.  Those which are remediable with a good cost/benefit
tradeoff should be implemented.

Maybe the next generation will finally Sphinx its way to documentation
format supremacy, the way Git arrived late to the revision control wars
and nonetheless proceeded to eat most of the mindshare of its rivals.

If that's what happens, that's okay; I'll adapt.  But in the meantime,
people are _trying_ to write good documentation in man(7), and I want to
help them.  You do too--you process their patch submissions every day.

I'm stubborn about several things, like escaping hyphens, but I don't
have a good answer for people who ask where inter-page linking support
is.  It should be there.  And it can be supplied without bloating the
language[2] or breaking existing pages.

Regards,
Branden

[1] "Tag" may be a _broad_ semantic category, but of itself it tells you
    absolutely nothing about presentation.

[2] It may interest you to know that I seek to pull a man(7) macro _out_
    of circulation as well: OP, an ill-considered innovation of DWB
    troff (widely but wrongly credited to GNU) that promises semantic
    value but can't deliver it for sophisticated command-line option
    formats.  In this sense one might perceive that I'm using it as a
    "pay-for" to get MR, to abuse the parlance of U.S. political
    commentary, but that's not true (I don't promise to have groff's own
    man pages scrubbed of it by the time we release 1.23, whenever that
    is).  MR is worthwhile on its own merits, as is trimming fat off the
    existing man(7) lexicon.

    I've made noise a few times about adding "keeps" to man(7), modeled
    directly after ms(7)'s KS and KE.  So far no one has screamed.  This
    would be to solve problems that only arise when typesetting to paper
    (real or simulated).  A formatter that doesn't render to paper
    doesn't need to consider such problems and could completely ignore
    the macros without losing any page content.  KS and KE would be way
    better than 'ne' requests, which are tedious to maintain and tempt
    people into looking up what other roff requests they might use.  In
    man pages, we want to discourage that.

    The other hole in man(7) functionality that pains me, and which I
    see people deploying ersatz simulacra thereof, is the list.[3]  Our
    own page groff(7) sins voluptuously in this respect to produce
    lengthy references of escape sequences, request names, and built-in
    registers.  Fixing it will require a major overhaul.  I'm not sure
    what I want to do about this yet.  mdoc has tackled the
    problem--with a frighteningly complex interface.  I question the
    wisdom of "porting" mdoc's "Bl" to man(7) under any name.

[3] Perhaps this reflects Ingo's accurate absorption of the Unix
    Philosophy--the commands were so simple you didn't need lists of
    _anything_!  I caught a list lurking in the 1979 sed(1) today,
    though.

signature.asc
Description: PGP signature