[self-follow-up] Hi Guillem,
Here are some updates and corrections to my claims. At 2026-09-19T01:54:47-0500, G. Branden Robinson wrote: > And in fact groff_mdoc's `Xr` macro already does that.[3] However, > `Fn` does not, and so I interpret your commit log as a bug report to > that effect. I'll file an appropriate Savannah ticket against groff. Filed as <https://savannah.gnu.org/bugs/?68706>. > > Where groff upstream suggests that those words need to be marked up > > with things like \%, which looks like unnecessary busy work. > > Yes. Another--likely much less tedious--approach involves using the > `hw` request to declare a man page's hyphenation exception words > within the document. (Or, in source maintenance, an entire project's > list of hyphenation exception words could be kept in a single file and > `so`urced into the installed version of the man page. I was not clear here. I was trying to say that one could generate the "installable" version of a man page at package build time by running soelim(1) on it then. Imagine the following make(1) rule. foo.man: foo.man.in soelim foo.man.in > foo.man Where "foo.man.in" looks in part like this... .Dd 2026-09-19 .Dt foo 1 .Os "frobnicate 2.34" .so misc/hyphenation_exception_words.roff ...and "misc/hyphenation_exception_words.roff" looks like this. .hw andovabegarin frotz-ify eatdata > Ingo Schwarze, the mandoc(1) maintainer, and I would both discourage > shipping a populated man page with `so` requests in it, The implication of an "unpopulated" man page is a perhaps elliptical reference to the common idiom of "link pages". Example: $ zcat /usr/share/man/man1/ctags.emacs.1.gz .so man1/etags.1 > Your technique is to inject `.nr HY 0` requests into every man page. [...] > That technique will fail in the forthcoming groff 1.25, at least for > man(7) documents.[4] In fact, as I should have noticed from the date stamp in the quoted commit, the technique is _already_ broken in groff 1.24.0 (released 28 February 2026) and 1.24.1. > I'll need to double-check that it does for mdoc(7) as well--thank you > for the reminder! It does.[A] Regards, Branden [A] commit e0a498b6bc2a0b209616910bfa16d33a8453139c Author: G. Branden Robinson <[email protected]> Date: Mon Jul 21 19:27:59 2025 -0500 [mdoc]: Fix Savannah #67363 (3/4). Make man page rendering more robust against meddling with the hyphenation mode by individual pages. In part this is to ensure that meddling doesn't persist outside the meddlesome document when rendering multiple pages, but it also makes user preferences more reliably discernible. Prompted by a discussion (about adjustment in man(7)) with Russ Allbery in late 2023. * tmac/doc.tmac ([initialization]): When rendering a man page, this macro file is read before any mdoc(7) document:track man/mdoc initialization status in new register `andoc*is-initialized`. When initializing, if the `HY` register is set, we know it was specified on the command line or by the "man.local" file. Stash its value in new register `andoc*HY` so it can be recovered after meddling by the document. * tmac/mdoc/doc-common (Dd): Remove the potentially page-local `HY` register when starting a new document, and call `doc-reset-hyphenation-mode` interpolating `andoc*HY` as an argument to impose the user's preference (or the package default) at each new document. (doc-reset-hyphenation-mode): Accept an argument, and if valid, assign its value to the `HY` register. (Sh): Configure hyphenation _after_ determining formatting parameters dependent on the name of the section heading. Move `nh` request out of control branch matching the `doc-sec-head` and `doc-section-synopsis` strings. Later, invoke `nh` if we're in a synopsis section and `doc-reset-hyphenation-mode` otherwise. (Ss): Invoke `nh` if we're in a synopsis section and `doc-reset-hyphenation-mode` otherwise. As a side effect, this subjects subsection headings to hyphenation. (Section headings produced by the `Sh` macro already were.) * tmac/tests/doc_hyphenation-mode-restoration-works.sh: Add test to verify preservation of document- and user-selected hyphenation modes. * tmac/tmac.am (tmac_TESTS): Run test. Fixes <https://savannah.gnu.org/bugs/?67363> (3/4). Thanks to Russ Allbery for posing the challenge.
signature.asc
Description: PGP signature
