Hi Ingo, Good to hear from you!
At 2023-02-24T09:56:29+0100, Ingo Schwarze wrote: > sorry for being totally swamped right now and temporarily losing > track of mandoc and groff stuff, but by some strange chance, this > caught my eye: > > > +.\" Define fallback for groff 1.23's MR macro if the system lacks it. > > +.nr do-fallback 0 > > +.if !\n(.f .nr do-fallback 1 \" mandoc > > +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff > > +.if !\n(.g .nr do-fallback 1 \" non-groff *roff > > This is excessively complicated. [...] > Besides, in general, using \n(.g is always an extremely bad idea. > Capabilities of implementations (both groff and others) change > over time, so never test for application names or version numbers, > but always test for features. [...] > For example, mandoc supports vast swaths of groff features, > and yet: [...] > What exactly is this aiming for? [...] > Looks like Heirloom does not need it. [...] > Looks like Heirloom blows up quite loudly with your > new "compatibility" code. [...] > Admittedly, Plan 9 supports neither d nor !d. I appreciate your attempt to write *roff feature tests in the style of Autoconf, but I fear it has led you to excessively pessimistic conclusions, and negative ones in the experimental sense. My defense of the current implementation is that, under testing with practical man pages, it _works_. At least on my Debian system. Let me take a small page that uses the `MR` macro and show you. https://git.savannah.gnu.org/cgit/groff.git/tree/src/preproc/eqn/neqn.1.man When built (groff requires sed-replacement of some man page content due to variable configuration-time properties, like a command prefix), the foregoing file produces a man page as shown in the attachment. Now let us see what becomes of it with four renderers: groff 1.22.4, mandoc 1.14.5, Heirloom Doctools troff, and groff 1.23.0.rc3 (all on my Debian bullseye system). $ groff -v | head -n 1 GNU groff version 1.22.4 $ groff -man -Tascii -P -cbou ~/tmp/neqn.1 | cat -s neqn(1) General Commands Manual neqn(1) Name neqn - format equations for character-cell terminal output Synopsis neqn [eqn-options] Description neqn invokes the eqn(1) command with the ascii output device. eqn does not support low-resolution, typewriter-like devices, although it may work adequately for very simple input. See also eqn(1) groff 1.23.0.rc3.23-5712 24 February 2023 neqn(1) $ dpkg -l | grep mandoc | sed 's/ \+/ /g' ii mandoc 1.14.5-1 amd64 BSD manpage compiler toolset $ mandoc ~/tmp/neqn.1 | cat -s neqn(1) General Commands Manual neqn(1) Name neqn - format equations for character-cell terminal output Synopsis neqn [eqn-options] Description neqn invokes the eqn(1) command with the ascii output device. eqn does not support low-resolution, typewriter-like devices, although it may work adequately for very simple input. See also eqn(1) groff 1.23.0.rc3.23-5712 24 February 2023 neqn(1) $ cd ~/heirloom # built ca. 2020-02-05 from most recent tag 191015 $ ./bin/nroff -man ~/tmp/neqn.1 | cat -s neqn(1) General Commands Manual neqn(1) Name neqn - format equations for character-cell terminal output Synopsis neqn [eqn-options] Description neqn invokes the eqn(1) command with the ascii output device. eqn does not support low-resolution, typewriter-like devices, although it may work adequately for very simple input. See also eqn(1) groff 1.23.0.rc3.23-5712 24 February 2023 neqn(1) $ cd ~/src/GIT/groff $ ./build/test-groff -man -Tascii -P -cbou ~/tmp/neqn.1 neqn(1) General Commands Manual neqn(1) Name neqn - format equations for character-cell terminal output Synopsis neqn [eqn-options] Description neqn invokes the eqn(1) command with the ascii output device. eqn does not support low-resolution, typewriter-like devices, although it may work adequately for very simple input. See also eqn(1) groff 1.23.0.rc3.23-5712 24 February 2023 neqn(1) Before pushing the commit to which you replied, I did not in fact test neqn(1); I tested groff_man(7), a more demanding document. > Admittedly, Plan 9 supports neither d nor !d. Plan 9 from User Space (P9US) troff is much like DWB 3.3 troff; it does not reliably render groff man pages and as far as I know it never has. groff's man pages have used \[this_style] of special character escape sequences for decades.[1] I think that either interest or developer energy is lacking to make P9US troff a "modern" troff, with rare exceptions like `MR` in its man(7) macros to make its insular environment more comfortable for its users. I surmise that this is because P9US isn't a "full-stack" solution (some form of Unix kernel is used after all) and a POSIX-ish "host" environment is always available. So I suppose they render only P9US man pages with P9US troff. And if they're happy with it, that's as it should be. > But your "compatibility" code does not work either: [...] > > I did warn you that .MR might land you in trouble... It looked scary there for a moment, and I despaired, but I think we came through in the end. I thank Alexis and John Gardner again for their assistance. > I would have prefered being wrong, but here we are. :-( I think you are in fact wrong here, unless you refer only to the fact that an unusual level of care is required. The fallback logic is assuredly not pretty, but it seems to work. And in part of the commit message you did not quote, I emphasized that I don't want to hang onto this ugly boilerplate forever. This definition is intended as a stopgap measure only. I want to revert this after groff 1.23 is released and has spread to some reasonable degree. How soon I can do this depends largely on packagers/distributors. But I think we're talking years rather than months. I hope it is few enough that only one hand is needed to count them. I am happy to revisit the content of this fallback logic for elegance, which it assuredly lacks at present, after groff 1.23.0 final. Keith Marshall suggested that I might go ahead and use a CSTR #54-legal register name in place of "do-fallback", and that's not a terrible idea. I didn't make it short in the first place because I didn't need to to get groff 1.23.0 man pages rendering on all the formatters of interest (enumerated above), and other things being equal, I prefer communicative variable names to inscrutable Ken Thompson digraphs. If, say, P9US adapts features as discussed in the footnote, that decision is worth reconsidering to achieve greater page portability. Regards, Branden [1] If P9US embraced groff's man(7) macro extensions (the ones in an-ext.tmac, which are licensed such that anyone, even copyleft-hostile projects, may use them), and added support for a handful of special character identifiers you and I documented in groff_man_style(7)'s "Portability" section, it might be worth reconsidering our P9US troff support story, at least as far as our man pages go. (They'd need to implement support for `\:` as well, and that might be the hardest part, because it requires grubbing around down in the hyphenation code.) It wouldn't be a big deal to rewrite those \[xx] escape sequences as \(xx. In conversation with Keith Marshall recently, I went over common features of groff man pages as of groff 1.22.3 (November 2014) that are not portable to "CSTR #54 troff". https://savannah.gnu.org/bugs/index.php?63827#comment3
.TH \%neqn 1 "24 February 2023" "groff 1.23.0.rc3.23-5712"
.SH Name
\%neqn \- format equations for character-cell terminal output
.
.
.\" ====================================================================
.\" Legal Terms
.\" ====================================================================
.\"
.\" Copyright (C) 2001-2020 Free Software Foundation, Inc.
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of
.\" this manual under the conditions for verbatim copying, provided that
.\" the entire resulting derived work is distributed under the terms of
.\" a permission notice identical to this one.
.\"
.\" Permission is granted to copy and distribute translations of this
.\" manual into another language, under the above conditions for
.\" modified versions, except that this permission notice may be
.\" included in translations approved by the Free Software Foundation
.\" instead of in the original English.
.
.
.\" Save and disable compatibility mode (for, e.g., Solaris 10/11).
.do nr *groff_neqn_1_man_C \n[.cp]
.cp 0
.
.\" Define fallback for groff 1.23's MR macro if the system lacks it.
.nr do-fallback 0
.if !\n(.f .nr do-fallback 1 \" mandoc
.if \n(.g .if !d MR .nr do-fallback 1 \" older groff
.if !\n(.g .nr do-fallback 1 \" non-groff *roff
.if \n[do-fallback] \{\
. de MR
. ie \\n(.$=1 \
. I \%\\$1
. el \
. IR \%\\$1 (\\$2)\\$3
. .
.\}
.rr do-fallback
.
.
.\" ====================================================================
.SH Synopsis
.\" ====================================================================
.
.SY \%neqn
.RI [ \%eqn-options ]
.YS
.
.
.\" ====================================================================
.SH Description
.\" ====================================================================
.
.I \%neqn
invokes the
.MR \%eqn 1
command with the
.B ascii
output device.
.
.
.LP
.I \%eqn
does not support low-resolution,
typewriter-like devices,
although it may work adequately for very simple input.
.
.
.\" ====================================================================
.SH "See also"
.\" ====================================================================
.
.MR \%eqn 1
.
.
.\" Restore compatibility mode (for, e.g., Solaris 10/11).
.cp \n[*groff_neqn_1_man_C]
.do rr *groff_neqn_1_man_C
.
.
.\" Local Variables:
.\" fill-column: 72
.\" mode: nroff
.\" End:
.\" vim: set filetype=nroff textwidth=72:
signature.asc
Description: PGP signature
