Hi Branden, G. Branden Robinson wrote on Wed, Oct 21, 2020 at 02:44:44AM -0400:
> commit 697e6db7fcacd403f5dde682002d02caa52e48df > Author: G. Branden Robinson <g.branden.robin...@gmail.com> > AuthorDate: Mon Oct 19 04:40:31 2020 +1100 > > tmac/an-old.tmac: Stop remapping ` and '. > > Our own pages now appear to be clear of wrong-quote problems, so let's > make them visible if they recur. Those who don't want to fix bad man > pages (distributors, site admins) can restore the mappings in their > man.local files. I think this commit ought to be reverted. Sorry for not finding the time earlier to inspect its consequences and to discuss it with fellow documentation maintainers. To start explaining why i consider this change bad, i should like to quote Anthony J. Bentley, with his permission: :: As a rule I correctly escape ` as \` and ' as \(aq even in manpages. :: They're actually needed less often than one might think. But most :: developers (even many manpage authors!) are unfamiliar with this :: historical oddity in troff. Expecting them to remember this rule :: and get it right is too much. Searching the corpus of manuals to :: correct all missing escapes is also too much. :: :: In the proposed fantasy world, everyone would be intimately familiar :: with the rules of elegant typography. Groff could make its change, :: and no manpages would suffer. :: :: In the current world, ` and ' and such are always displayed literally. :: It means I give up my curly quotes in favor of a slight typographical :: downgrade, but important content (command/config examples, source :: code, etc) is never wrongly transformed. This is what we have in :: the www repository, and with the current mandoc rendering, basically :: what we have in base also. :: :: Groff making its change will take us to a third place, where because :: manpages are often poorly written and the distinction between escapes :: is subtle and poorly understood, manpages will often be poorly :: rendered and correcting the changes will be a lot of unpopular, :: frustrating busywork. :: :: As an example, I point you to this commit, where I fixed multiple :: pages whose authors decided to turn apostrophes into *acute accents* :: and never noticed. It's worse than bad kerning! :: https://marc.info/?l=openbsd-cvs&m=155945840114941&w=2 :: :: I'm sympathetic to groff here. I can see why they want to fix a :: rather glaring divergence between terminal and PDF output. But in :: my opinion the change will cause more rendering problems than it :: will fix. The minor typographic gain of pretty quotes in prose will :: be offset by the far worse typographic loss of unescaped literal :: ASCII ' and ` in command contexts, most of which will never be :: fixed. Let me add that the current rules for manual pages are not wrong, they are merely slightly *different* from the rules for general- purpose roff typography. For general typography, we have: input output ` U+2018 left single quotation mark ' U+2019 right single quotation mark \(ga U+0060 grave accent \(aq U+0027 apostrophe-quote That does make sense for general typography, in particular for texts that are not concerned with computer programming, because quotes appear frequently in such texts, a grave accent without a supporting character is very rarely needed, and the ASCII apostrophe-quote is almost never needed; it isn't even a real character in general-purpose typography. In contrast, the current rules for manual pages are: input output ` U+0060 backtick for shell command substitution and the like ' U+0027 programming-language single quote \(oq U+2018 left single quotation mark for running text \(cq U+2019 right single quotation mark for running text Even if we were to design all this from scratch - which we cannot do since many thousands of manual pages already exist -, that would be a better design for manual pages, for three reasons: 1. Literal ' and ` are frequently needed in manual pages, programmers will constantly forget escaping them, and when they are escaped, they make the manual page source code very ugly, hard to write, hard to read, and error-prone. 2. Typographical quality of single quotes is not nearly as important in manual pages as in technical texts, so even if escaping them as \(oq and \(cq is forgotten, it doesn't really matter. 3. Manual page authors rarely need to type \(oq and \(cq by hand in the first place but will normally use macros like .Sq or .Ql which do that automatically, so there is no burden on manual page authors. The strongest reason why this should be reverted is that it is an incompatible change both ways with little to no hope of ever fixing the consequences. Correctly written old manual pages using ` and ' literally e.g. in code samples will suddenly render incorrectly with new formatters, in an important way. Correctly written new manual pages that no longer escape \(oq and \(cq and instead rely on the general typesetting rules will look worse with old formatters. As explained above with the points 1-3, these downsides will not even be offset by any advantages, but will in addition make life harder for manual pages authors for no benefit. Arguably, there is a very minor benefit of the change. People who write both manual pages and use roff for general-purpose typography have to learn fewer rules. But such people exist in much smaller numbers than people merely writing manual pages. They have to learn a lot more than people merely writing manual pages anyway, so the additional rule is no burden for them. And finally, even those people don't need to remember any differing rules if they simply use \(aq, \(ga, \(oq, and \(cq only in manual pages if they want to. Finally, the change as committed is incomplete. It changes the rules for the man(7) macros but leaves the identical rules for the mdoc(7) macros unchanged. I think trying to explain to manual page maintainers that quoting rules in manual pages depend on which macro set is in use would be an extremely bad idea, it would be utterly confusing. That alone - the change being inconsistent and incomplete - would already seem sufficient to me for requesting a revert, even if it wouldn't be a bad change for all the reasons explained above. Your argument that distributors and packages of groff can individually decide to revert your change if they want to is an even worse idea. That would result in ecosystem fragmentation. You want different rules for manual page markup depending on the operating system? You want that the manual pages from one operating system render incorrectly on another system, and vice versa? What about the manual pages of portable software - those poor people would be *forced* to escape everything: \(aq, \(ga, \(oq, and \(cq - not as a choice because they want to, but to get correct rendering on all systems. Inviting distributors and packagers to mess with these rules clearly exacerbates the problems rather than helping to solve them. If groff insists on this change, then mandoc and all systems using it (OpenBSD, FreeBSD, NetBSD, Illumos, Alpine Linux, Void Linux) will probably be forced to follow your advice to not follow groff and to patch your change out of groff. I don't see what the alternative would be... And i'm not sure what Fedora could do, which officially supports both man-db/groff (by default) and mandoc (which can be activated with its "alternatives" configuration system). Yours, Ingo
