groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

the compatibility of man(7) (was: man(7) .TH font change, was: groff man


From: G. Branden Robinson
Subject: the compatibility of man(7) (was: man(7) .TH font change, was: groff man(7) `B` macro...)
Date: Sat, 16 Jul 2022 07:37:54 -0500

At 2022-06-19T19:28:26+0200, Ingo Schwarze wrote:
> Given that the base system corpora of FreeBSD and NetBSD are of the
> same order of magnitude as in OpenBSD (and treating DragonFly as a
> FreeBSD fork for now, which is not fair in general, but good enough
> for this particular purpose because Dragonfly is likely to evetually
> merge FreeBSD manual page improvements, even if with a long delay)
> the estamited total number of mdoc manual pages might be about 15k,
> with each of the major BSD systems contolling rougly 20-25% each, and
> third-party software controlling maybe on the order of 20-40%.
> 
> To summarize, the *BSD base systems very likely collectively control
> the majority of existing mdoc(7) manual pages, whereas the Linux man
> pages project likely controls on the order of 1% of the existing
> man(7) pages - even when we consider neither commercial UNIX systems
> nor proprietary software.
> 
> That makes compatibility in man(7) significantly more of a concern
> than in mdoc(7).  All the same, i would certainly not consider
> adding anything as disruptive as .MR to mdoc(7).

This argument amounts to saying that because the BSDs control both the
majority of the extant mdoc(7) pages in the world and the mandoc(1)
renderer that has been made the default on those systems (at the expense
of all troffs), then the mdoc(7) language can be allowed to evolve.

It furthermore implies that because the groff project does not control a
large proportion of the world's man(7) pages (though I have striven to
make what we do provide exemplary), the man(7) language _cannot_ be
allowed to evolve.

I do not accept this proposition.  You are insisting upon stagnation.

Yes, distributors that incorporate packages with man pages using the new
`MR` macro, racing ahead of those same distributors' update of groff
1.23.0 (whenever that happens), run the risk of some unhappy man page
readers.

If a distributor takes a wait-and-see attitude toward groff 1.23.0,
whether deliberately or because their package maintainer is comatose,
then another contributor who doesn't have a great command of *roff can
apply the following patch to the man.local file they ship.

.if !d MR \{\
.  de MR
.    IR \\$1 (\\$2)\\$3
.  .
.\}

(This is a simplified version of what we provide in an-ext.tmac, where
it is used only if the formatter is not groff.[1])

You have persuaded me that the foregoing is a point worth cautioning
people about in the groff 1.23.0 release notes, which with any luck will
be read by a wider audience than this mailing list or any other piece of
the groff distribution.

The man(7) language is one of many things in the traditional Unix world
that never bothered to declare a versioned interface mechanism.  (I've
become convinced that doing so is essential for serious software
engineering work--yet look how long ELF symbol versioning took.)  We
could certainly add one to it.

Man pages could say

.NE 2.1 \" "needs"

and man(7) renderers could declare that they "provide", say, "3.4".

It would then be possible for interactions between future man pages and
their renderers to be negotiated and gracefully fail if unsatisfied.

It wouldn't displease me in the least to apply a semantic versioning
practice to the man(7) language and our implementation of it.

Regards,
Branden

[1] It does run the risk of man page names getting hyphenated, but this
    isn't much of a "regression" from current uses of man page cross
    references, where practically no man page author remembers to prefix
    the page title with `\%`.  Moreover, the numerous barbarians who
    unconditionally turn off hyphenation in man pages are ineligible to
    complain about it.

Attachment: signature.asc
Description: PGP signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]