Hi Russ, At 2025-10-09T17:49:24-0700, Russ Allbery wrote: > "G. Branden Robinson" <[email protected]> writes: > > > Here's my method.[1] > > > 1. Grab all the ".pod" files installed on my Debian bookworm(-ish) > > box. > > 2. Run them through _current_ podlators pod2man,[2] _with_ groff > > Git HEAD, but with the `cflags 0 "` line in "tmac/an.tmac" > > commented out, disabling adjustment at the command line, and > > saving standard output and standard error. This captures the > > "status quo ante". > > 3. Uncomment the `cflags 0 "` line. > > 4. Run the same file through _current_ podlators pod2man again, > > saving standard output and standard error. This captures the > > effect of my reckless and dangerous change. ;-) > > 5. Diff 'em. > > [snip] > > Ah! Okay, you caught instances that I didn't because I suspect there > were no quotes most of your examples other than the first in the POD > source (I think those are blocks in C<>), which found a bunch of > places where the changed behavior does catch cases where there are > periods inside quotes.
Judging from my diff, a great many of these seem to involve ellipses at
(or, strictly, near) the right ends of literals.
- "(?[...])" construct, this is an error, rather than a warning. Con‐
+ "(?[...])" construct, this is an error, rather than a warning. Con‐
- Each watcher type further has its own "ev_TYPE_set (watcher *, ...)"
macro
+ Each watcher type further has its own "ev_TYPE_set (watcher *, ...)" macro
- Creates "->commandSub(...)" as an alias for "->command('sub',...)" e.g.
+ Creates "->commandSub(...)" as an alias for "->command('sub',...)" e.g.
- dition to the already supported "0x..." and "0b..." syntax [perl #76296].
+ dition to the already supported "0x..." and "0b..." syntax [perl #76296].
- on pseudo‐processes, and "kill("TERM", ...)" might not get delivered if
+ on pseudo‐processes, and "kill("TERM", ...)" might not get delivered if
the
- larly, if the "(" and "*" are separated in "(*VERB...)" constructs.
+ larly, if the "(" and "*" are separated in "(*VERB...)" constructs.
- is part of a "?[...])" construct. When the "[...]" stands alone, the
+ is part of a "?[...])" construct. When the "[...]" stands alone, the
> I'm assuming most of these cases are ones where the end of the line in
> the input happens immediately after the C<> block.
I confess to lazily not checking the POD sources, but all of the
foregoing seem like probable "C<>" fodder to me.
> I think I'm convinced that overall your change makes slightly better.
> I still don't like that it breaks the ability of someone who is
> intentionally ending a sentence with `."` to get correct results, but
> as previously mentioned, line spacing in *roff output from POD is in
> practice such a mess that I doubt many people will notice. So given
> that, I can't really make a good argument against your incremental
> improvement.
I must admit to spotting one _seeming_ regression among the 126 changes,
once I recharged some mana.
@@ -166027,7 +166027,7 @@
task: "Filter::exec" and "Filter::sh". Both allow you to run any external
executable. Both use a coprocess to control the flow of data into and out
of the external executable. (For details on coprocesses, see Stephens,
- W.R., "Advanced Programming in the UNIX Environment." Addison‐Wesley,
ISBN
+ W.R., "Advanced Programming in the UNIX Environment." Addison‐Wesley, ISBN
0-210-56317-7, pages 441-445.) The difference between them is that "Fil‐
ter::exec" spawns the external command directly, while "Filter::sh" spawns
a shell to execute the external command. (Unix uses the Bourne shell; NT
That's a shame given (1) the (deserved) sterling reputation of that
book and (2) the late Stephens's own high level of *roff competency.
http://kohala.com/start/pagelayout.html
However, if we look more closely we can see that the bibliographic
citation, in (roughly) MLA format, is not standard. When citing a major
work (like an entire monograph), italics should be used instead of
quotation marks. (That's true across multiple style authorities.)
https://owl.purdue.edu/owl/research_and_citation/mla_style/mla_formatting_and_style_guide/mla_sample_works_cited_page.html
Granted, had the cited work been a minor one (like an article), my
`cflags` change _would_ have caused an inarguable regression, if one
narrow in scope and pretty uncommon.
On the third hand, that seems like such an edge case for POD that it
might not be too much to ask any author using that format who is
persnickety enough to throw down an MLA-style "Works Cited" entry inline
in a paragraph to, pretty please, just use typographer's quotes from
Unicode to bracket the titles of minor works.
(And on the fourth hand, I don't think the MLA police would ding the
spacing change here, as, looking closely at the embedded PDF in the
foregoing URL, if the Purdue Online Writing Lab is correct, MLA doesn't
endorse supplemental inter-sentence spacing anyway! Further, this
preference is configurable in groff man(7) if man page authors--and
maintainers of man(7) output generators--will only keep their
dang-blasted hands off it in the documents themselves.[2])
> I'll update the Pod::Man documentation to explain that getting
> consistent end of line spacing from POD converted to *roff is probably
> not going to be universally possible unless one uses Unicode quotes,
> but that you'll probably also not notice the occasional errors since
> they're fairly rare.
Sounds good to me!
Regards,
Branden
[1] I've now looked over all 126 cases, and the Stephens APUE citation
was the only one that even approached arguable regression. As
noted, most cases involved ellipses near the right ends of literals
(often followed by characters transparent to *roff's end-of-sentence
detection and also syntactically meaningful to Perl). A second
category appears to be quotations within sentences of full sentences
including terminal punctuation. A third category is quotation of
sentence-terminal punctuation characters in a literal context.
[2]
groff_man_style(7):
Files
/.../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
signature.asc
Description: PGP signature
