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
