Re: man(7) .TH font change, was: groff man(7) `B` macro...

[G. Branden Robinson]

Hi Ingo,

At 2022-06-19T17:00:47+0200, Ingo Schwarze wrote:
> I'm not opposed to introducing new syntax in each and every case.

That remains to be seen.  What new man(7) syntax have you supported at
the time it was proposed (or implemented)?

> I'm merely saying new syntax needs strong justification,
> and new backward-incompatible syntax needs very strong justification.
> 
> In this case, justification is not completely absent: there is a
> benefit for PDF output,

...and terminals (thanks to grotty's OSC 8 support), and HTML output.
You are on record as having great contempt for groff HTML output but it
nevertheless does operate.  (I will not defend its esthetics.)

Between those 3 one covers what I dare to estimate is over 90% of all
runs of the GNU troff formatter.

> which, however, i consider minor for the stated reasons.

Let's review these reasons, stated in the NEWS file.

  Inclusion of the `MR` macro was prompted by its introduction to
  plan9port's troff in August 2020.  Its purpose is to ameliorate
  several long-standing problems with man page cross references: (1) the
  package's lack of inherent hyperlink support for them; (2)
  false-positive identification of strings resembling man page cross
  references (as can happen with "exit(1)", "while(1)", "sleep(5)",
  "time(0)" and others) by terminal emulators and other programs; (3)
  the unwanted intrusion of hyphens into man page titles, which
  frustrates copy-and-paste operations (this problem has always been
  avoidable through use of the \% escape sequence, but cross references
  are frequent in man pages and some page authors are inexpert *roff
  users); and (4) deep divisions in man page maintenance communities
  over which typeface should be used to set the man page title (italics,
  roman, or bold).

I assert that point (4) in particular is not minor for you because you
have argued with me at great length over it in the past, finally
admitting that I had the better of the historical argument (at least up
to 1990 or so),[1] but then still did not contemplate changing mandoc(1)
anyway.

To be fair, I didn't ask you to.  I don't subscribe to OpenBSD mailing
lists and prophesy the collapse of the sky if you pursue your ideas.

> Also, in this particular case, i deplore that the design was rushed in
> a reckless manner.

Interface-wise, there wasn't a lot of design to be done; with the
exception of no longer needing parentheses around the man section
number, it's the same interface man page writers have always used with
`IR` or `BR`.

As is, without those parentheses, it is the same syntax as mdoc(7)'s own
`Xr`,
https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/groff_mdoc.7.man#n2496
and, reportedly, also the same as DEC Ultrix's `MS` macro in its man(7)
https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/man.ultrix#n56
(checked in by James Clark in March 1993--I have no idea how long Ultrix
defined it before that).

This design is precisely the opposite of hasty.  It's been lying around
for 30 years.

> I don't think it was seriously considered whether the same can be
> achieved *without* new syntax, even though Jonathan Gray already
> suggested in 2014 that it is likely possible and the suggestion
> is publicly documented in the mandoc TODO file.

I didn't see that.  You could have pointed it out alongside some of your
previous objections to this change, none of which you offered when I
originally proposed it 23 months ago.[5]

> The same very definitely *is* possible with backard-compatible
> syntax.  For example, a syntax like the following can be made
> to achieve the same effect and is fully backward compatible:
> 
>   .MR
>   name(section)

That does have the virtue of not making the text disappear, as will
happen if there is no definition of `MR` at all.

On the other hand it comes with a cost, and that is the expansion--a
dramatic one, given the ubiquity of man page cross references--of the
frequency of use of man(7) macros that observably exercise input line
traps.  In the dialect of man(7) prescribed in groff_man(7), and in full
compatibility with the language going back to 1979, you can write a page
never knowingly using an input trap except when calling `TP`.  And since
users expect a break, or at least some indentation, after the paragraph
tag consumed by the input trap of `TP` anyway, this isn't too jarring a
thing.  But other macro calls without arguments in man(7) seem to most
users to have little to do with the text on the next line.  This
includes all of the other paragraphing macros, and the sectioning
macros, which even though they _can_ be used that way, nearly never are.
Similarly with `B` and `I`.  Between those and the always-argumentful
macros, you've covered the vast majority of man(7) macro calls seen in
practice.

People can disagree about the tradeoffs.

> That probably isn't the only way to achieve it in a
> backward-compatible way.  Unfortunately, I think options for
> backward-compatibility weren't seriously considered either.

Where were they proposed?

> Design discussions mostly revolved around details that had no
> bearing on compatibility.

I submit that this is because the application and usage is natural and
obvious to people with even a slight amount of experience writing
man(7), and consistent with the call syntax of the reasonably familiar
font style alternation macros.  So neither novice nor journeyman users
are likely to be confused.

Mastering the use of input traps, on the other hand, is a subtle art, as
we have recently discussed.[2]

> > The same applies to man(7) .MR, I think.
> 
> Absolutely not.  The argument you made about the C standard does not
> apply to manual pages at all.
> 
> When programmers maintain a piece of software and decide to use the
> latest compiler features, they are used to the fact that they need
> the latest compiler(s).  They also usually document the build system
> requirements in installation instructions (e.g., "requires C11").
> Porters and packagers are used to the fact that if the software
> they wish to package requires a particular compiler, that compiler
> needs to be installed at build time during packaging.
> 
> Manual pages, on the other hand, are usually installed as source
> code on end-user machines.  If programmers decide to use the
> latest markup features in their manual pages, they usually do not
> say so in installation notes.  Even if they wanted too, what
> would they be supposed to say?  All that groff_man(7) currently
> tells them is
> 
>    History
>        [...]
>        The plan9port project's troff introduced .MR in 2020.
> 
> So what are they supposed to say?  "Formatting our documentation
> requires plan9port troff from 2020 or later, groff 1.23.0 or later, or
> mandoc 1.14.7 or later and will not work with other implementations of
> the man(7) language"?  That would require doing some serious research
> on their part, and i expect that most programmers, even experienced
> and competent ones, do not have the required domain knowledge about
> manual page markup to correctly research and explain such a
> requirement.
>
> And even when stated correctly, such a statement would be highly
> cumbersome and eventually become incomplete and outdated.
>
> Even if such an unsusual statement would be made, what the hell
> is the packager supposed to do with it?  They have no idea whether
> the end-users they are making their packages for will choose to
> install man-db+groff or mandoc when these options exist.
> The packager for some random piece of software likely has no control
> over which version of groff or mandoc other packagers may package
> for the same operating system.  And what are they supposed to do
> if their system uses a completely different man(1) and *roff(1)
> implementation in the first place?
> 
> At the end of the day, there isn't much they can do in *any*
> case, and the statement "Formatting our documentation requires..."
> will likely be completely ignored by most packagers, all the more so
> as this will usually *not* result in build-time problems that become
> apparent to the packager, which means end-users will see random
> gaps in manual pages without having the slightest idea why, without
> having any diagnostic tools at hand, nor any of the skills needed
> to fix such issues.  And even if they knew what was going on, what
> *should* an end-user do?  Manually ditch the packaged version of groff
> or mandoc installed on their computer and compile a newer version
> from source?  That's completely unrealistic and would seriously annoy
> even highly capable, technically-minded people.
> 
> You see, what you say about compilers has basically nothing to do
> with what we are dealing with here, at least not from any practical
> perspective.

Like I said in my previous mail,[3] we could introduce semantic
versioning to the man(7) language to address the foregoing litany of
grief.  A renderer can assume a page is using man(7) "1.0" (as seen in
Unix V7) until the "NE" macro is called announcing a requirement for a
later version.

We could say that "MR" requires version "1.1" of the language.  Or,
arguably, we could call "MR" the defining feature of "1.2", and
retrospectively assign "1.1" to the earlier set of GNU extensions,
SY/YS/UR/UE/MT/ME/EX/EE.  Or we could split the hair even finer and call
Research Unix V9's addition of EX/EE 1.1, and bump the minor version for
groff extensions accordingly.

We might want to think more carefully about that last nit, though, since
V9 man(7) also introduced other extensions that don't appear to have
caught on.  I had to leave my paper copies of the manual in storage, but
I seem to remember that V9 man added columnation macros just like
ms's: `2C` and `1C` (yes, really!).  V10 has this and a lot of other
stuff, like still more font macros.[4]

There's probably not much point in retrojecting version numbers on to
Bell Labs history, though, since the relevant documents certainly did
not claim any level of man(7) language conformance or rendering
requirement.  They fired blindly.  They got away with it because, as you
tout for the BSD world, they controlled both the renderer and the
document corpus.

On the other hand most of their post-V7 man(1) innovations did _not_
become recognized by other man(7) renderers.  EX/EE is the only one I
can think of, and it is damnable old groff that adopted them.

And there would remain the question what to do about SunOS's `SB`.

> It *is* possible to carefully evolve manual page markup syntax, but
> compatibility concerns are significantly more important and harder to
> handle than when going from one C standard to the next, or from one
> version of a shared library to the next.

Do you want man(7) to evolve?  Do you think it should?  What would such
careful evolution look like?

Regards,
Branden

[1] https://lists.gnu.org/archive/html/groff/2021-08/msg00034.html
[2] https://lists.gnu.org/archive/html/groff/2022-06/msg00041.html
[3] https://lists.gnu.org/archive/html/groff/2022-07/msg00069.html
[4] https://minnie.tuhs.org/cgi-bin/utree.pl?file=V10/cmd/mk/export/tmac.an
[5] https://lists.gnu.org/archive/html/groff/2020-08/msg00068.html

signature.asc
Description: PGP signature