[CC list trimmed since I'm covering only English style and typesetting issues here; adding groff@gnu accordingly]
At 2025-09-21T11:47:21+0200, Alejandro Colomar wrote: > > +(Note that the unmount operation on > > Maybe I would make this note a paragraph of its own; this would give > it more visibility, I think. And I'd remove 'Note that', and start > directly with the noted contents (everything in a manual page must be > noteworthy, in general). Good advice. I call such removal a "Kemper notectomy", in honor of the groff colleague who brought the superfluity of such constructions to my attention. Also see <https://en.wikipedia.org/wiki/Wikipedia:It_should_be_noted>. > > +is lazy\[em]akin to calling > > I prefer em dashes in both sides of the parenthetical; it more clearly > denotes where it ends. > > is lazy > \[em]akin to calling > .BR umount2 (2) > with > .BR MOUNT_DETACH \[em]; > > (I assume that's where it ends.) I'm uneasy about the acceptability of setting an em dash and semicolon adjacently like this. I checked my copy of the Chicago Manual of Style (18th ed., 2024) and it has something close, but not squarely, on point. ---snip--- §6.95. Em dashes and other punctuation. In modern usage, a question mark or an exclamation point—but never a comma, a colon, or a semicolon— may precede an em dash. ... If the context calls for an em dash where a comma would ordinarily separate a dependent clause from an independent clause, the comma is omitted. ---end snip--- Here's the full sentence at issue. >>> +(Note that the unmount operation on >>> +.BR close (2) >>> +is lazy\[em]akin to calling >>> +.BR umount2 (2) >>> +with >>> +.BR MOUNT_DETACH ; >>> +any existing open references to files >>> +from the mount object >>> +will continue to work, >>> +and the mount object will only be completely destroyed >>> +once it ceases to be busy.) This construction uses a semicolon rather than a comma, and that semicolon separates two independent clauses. (Whether "Note that" is retained or deleted makes no difference.) CMoS therefore doesn't flag this as "wrong", but I think it'll look weird to a native English reader and maybe to non-native ones, too. The best solution might be to recast. It's seldom wrong to break a sentence using a semicolon into two sentences when the purpose of the prose is to explain rather than specify. > You need to escape dashes in manual pages. Otherwise, they're > formatted as hyphens, s/they're/they can be/ Some distributions, like Arch[1], Debian[2], and Fedora[3], won't exhibit this problem. Why doesn't groff do this upstream? Because some groff users _do_ care about correct typesetting, and it's more straightforward for distributors to patch their packages as the aforementioned have done than for groff to adopt that as a default and leave people to their own devices to revert it.[4] (Maybe I should copy some of that rationale into groff's "PROBLEMS" file. Opinions?) > which can't be pasted into the terminal (and another consequence is > not being able to search for them in the man(1) reader with literal > dashes). ...but if you're looking for an incorrectly hyphenated term like "foo-bar", you _can_ search for "foo.bar". Both the more(1) and less(1) in the (now over 2 years old) Debian Bookworm can manage this on UTF-8-encoded input. > Depending on your system, you might be able to search for them or paste > them to the terminal, because some distros patch this in > /etc/local/an.tmac, That's not the file name any of the foregoing distributors use, but you've got the right idea. > at the expense of generating lower quality pages, but in general don't > rely on that. > > I've noticed now, but this probably also happens in previous pages in > this patch set. > > While at it, you should also use a non-breaking space, to keep the > entire command in the same line. > > .IR \%mount\~\-\-bind ) Here's where I disagree a little. Lengthy unhyphenable character sequences like this can lead to ugly formatting, even when adjustment is disabled. (A ragged right margin can get _really_ ragged.) While I personally would not use italics for inline examples (and don't in groff man pages), regardless of the font style you use, you can surround multi-word inline examples with quotation marks so that they are properly understood even if broken. (Further, no font style selection survives copy-and-paste into plain text email.) The Linux man-pages don't require portability to AT&T troff, so you can achieve this with groff's `lq` and `rq` special characters. I therefore propose: .RI \[lq] \%mount .IR \-\-bind \[rq] If you _did_ require portability to AT&T troff, you could use the `lq` and `rq` _strings_ instead. .RI \*(lq \%mount .IR \-\-bind \*(rq These strings are _almost_ universally portable. The only line of *roff descent that didn't incorporate them into man(7) was that of Research Unix, of which the only surviving specimen is Plan 9 troff. In other words, BSD troff (1980), Unix System V Release 4 and its descendants (1988)--including Solaris 10, and groff (1989) all support them. I'm working up a patch to add it to Plan 9 from User Space a.k.a. plan9port. Quotation is a useful and important linguistic facility. It's a shame man page authors have neglected it so long. Regards, Branden [1] https://gitlab.archlinux.org/archlinux/packaging/packages/groff/-/commit/e474b541a32fc905b4f748de0313acfb8b98c081 [2] https://salsa.debian.org/debian/groff/-/commit/d5394c68d70e6c5199b01d2522e094c8fd52e64e [3] https://bodhi.fedoraproject.org/updates/FEDORA-2023-f5d1e63191 [4] https://lwn.net/Articles/948616/
signature.asc
Description: PGP signature
