Hi Russ, It seems I never properly responded to this.
At 2025-08-24T13:55:29-0700, Russ Allbery wrote: > "G. Branden Robinson" <[email protected]> writes: > > > I observe the following in "lib/Pod/Man.pm". > > > .\" Escape single quotes in literal strings from groff's Unicode transform. > > .ie \n(.g .ds Aq \(aq > > .el .ds Aq ' > > > Do you think it would be worthwhile to do the following as well? > > > .ie \n(.g .ds Dq \(dq > > .el .ds Dq ""\" two double quotes because `ds` strips the first > > > I don't understand the patterns where you're replacing ` and ' in > > POD input to make them `\*(Aq` in *roff output well enough to make a > > literal suggestion for `\*(Dq` here, unfortunately. > > I went back and reviewed more of the thread. I'm not entirely sure > that I understand the context correctly, but it sounds like you're > proposing removing " from the list of characters that are skipped over > when determining if a period (and related characters) indicate the end > of a sentence for the purposes of applying intersentence spacing. Correct. > I don't really understand how that is a solution to the problem that > the thread started with, which was that \[dq] was not skipped over for > this determination. Maybe it's not, and it was an unrelated thing that > you noticed while looking at the issues raised in that message? The original concern that Alex reported was not that \[dq] was not skipped over, but that \[dq] and " behaved _differently_. Alex wrote: >>>> I was going to replace some unmatched double quote as argument to a >>>> man(7) macro, which was used as a literal double quote in the >>>> output, by the more readable (less ambiguous in source code) \[dq]. >>>> >>>> However, I've realized that groff(1) seems to treat them slightly >>>> differently. Is this intentional, or a bug? The proposal was to, for groff man(7) and mdoc(7), make them behave the same, selecting \[dq]'s behavior for both. (Technically, unsetting all of `"`'s "character flags".) > The position I have taken in Pod::Man is that people writing pure > ASCII POD should use " for quotation marks (not `` or '' or anything > else). That character is then copied directly to the output (with > escaping as necessary for macro arguments). At present, this produces > reasonable behavior with groff. Earlier versions of Pod::Man attempted > to do other things to enable typographic paired quotes, and those > efforts were a fragile maintenance disaster with all sorts of failing > edge cases. All of that code was removed in 5.00 and v6.0.0. That's fine, and is consistent with the presumption that underlies my proposed change: most of the time, in man pages, authors use `"` for some purpose other than prose quotation. > If people writing POD want proper typographic quotes (and I do > understand the desire for that), then my position is that they should > use: > > =encoding utf-8 > > and then use “Unicode quotes” in the input POD. That's a good solution, and maybe the only one if they can't bust down to *roff strings or special character escape sequences, and I understand why that would be discouraged in POD, if it's even possible. > This allows the author to unambiguously indicate their intent, rather > than relying on software making often-erroneous guesses that may > misinterpret " quotes in, for example, code samples. Agree. > For better or for ill, the definition of POD never said that people > should use `` and '' (or anything else other than ") as quote > characters, unlike *roff and TeX, and therefore the vast majority of > existing POD documents do not. There is no reliable way to tell from > the POD source what the intent of a given " character is, so the only > supportable treatment (IMO) is to handle it as a neutral double quote. Yes, and I don't encourage groff users to employ `` and '' for double quotes anyway. The formatter doesn't maintain enough state to "do what the user means" and convert them into directional double quotes. AT&T troff hand-waved this problem away; on typesetters, because these glyphs were narrow, they'd set together fairly closely and would look "good enough". On typewriters, they were ugly as hell, but I guess the CSRC despaired of getting attractive output on Teletypes. You were lucky if the rattly machine didn't delete all your files.[1] > > But I think substituting `"` with `\*(Dq` would produce better > > results in most cases--I'll cover a (possibly notional) exception > > below--and be backward compatible to groff 1.23 and earlier, and > > correct regardless of whether groff 1.24 makes the `cflags` change > > to the `"` character, for man pages only, as proposed in this > > thread. > > I think you are making an assumption that " in *roff input is mostly > only used for code. Not quite. I'm making the assumption that " _in man(7) and mdoc(7) input_ is mainly used for code. I proposed no change for the formatter per se, just to macro package behavior. And indeed I would oppose such a change for ms, me, and mm, for which I have some maintenance responsibility. But that's kind of afield from my (tentative) suggestion that Pod::Man add a `Dq` string definition to its preamble. I'm no longer interested in pursuing that suggestion, FWIW. It seems like it doesn't address anything that is broken, not with the cflags change coming in groff 1.24. > This is probably true for the universe of documents written directly > in *roff, since that has (always?) been part of the *roff language, > but it's false for the universe of *roff generated from POD, where " > is used for nearly all English double quotation marks. I believe > making this change is quite likely to result in inconsistent sentence > spacing for lots of existing *roff output. The `Dq` string change, I assume you mean, not the `cflags 0 "` change. > This obviously would not be the end of the world, nor would it be a > new problem given that use of double spaces after periods in input > text is now largely no longer used. (Indeed, I switched to a single > space after periods in emails a year or so ago as an exercise in > practicing my own mental plasticity after noticing that few people > younger than I use or expected that spacing.) I expect to go to my grave as a double-spacer. It's more readable, IMO. > Pod::Man says the following about the general problem: > > CAVEATS > Sentence spacing > Pod::Man copies the input spacing verbatim to the output *roff document. > This means your output will be affected by how nroff generally handles > sentence spacing. > > nroff dates from an era in which it was standard to use two spaces > after sentences, and will always add two spaces after a > line-ending period (or similar punctuation) when reflowing text. > For example, the following input: > > =pod > > One sentence. > Another sentence. > > will result in two spaces after the period when the text is > reflowed. If you use two spaces after sentences anyway, this will > be consistent, although you will have to be careful to not end a > line with an abbreviation such as "e.g." or "Ms.". Output will > also be consistent if you use the *roff style guide (and XKCD 1285 > <https://xkcd.com/1285/>) recommendation of putting a line break > after each sentence, although that will consistently produce two > spaces after each sentence, which may not be what you want. Good advice! I'll have to keep XKCD #1285 in mind. > If you prefer one space after sentences (which is the more modern > style), you will unfortunately need to ensure that no line in the > middle of a paragraph ends in a period or similar sentence-ending > paragraph. Otherwise, nroff will add a two spaces after that > sentence when reflowing, and your output document will have > inconsistent spacing. I disagree with this lament, and strike a note of less futility in groff_man_style(7). ---snip--- /.../share/groff/site-tmac/man.local Put site‐local changes and customizations into this file. .\" Put only one space after the end of a sentence. .ss 12 0 \" See groff(7). .\" Keep pages narrow even on wide terminals. .if n .if \n[LL]>80n .nr LL 80n ---end snip--- (That's /etc/groff/man.local in Debian-based systems.) This facility is not new to groff; it's been available since 1992. The man page's coaching _is_ new. Regards, Branden [1] https://www.tuhs.org/pipermail/tuhs/2019-September/018655.html
signature.asc
Description: PGP signature
