Hi Ingo, At 2026-09-19T18:33:47+0200, Ingo Schwarze wrote: > G. Branden Robinson wrote on Sat, Sep 19, 2026 at 01:54:43AM -0500: > > I recently encountered the following commit log message of yours to > > a libbsd repository.[...] > > > > commit 58474628790a4d63956e389c5f7489944a3bdf1f > > Author: Guillem Jover <[email protected]> > > AuthorDate: Sun May 17 23:01:52 2026 +0200 > > Commit: Guillem Jover <[email protected]> > > CommitDate: Mon May 18 04:56:59 2026 +0200 > > > > man: Disable hyphenation globally for all man pages > > > > There is no place for hyphenation in a technical document. > > However, i agree there is no place for hyphenation in manual pages > because manual pages are almost always living documents, and > intended for multiple output formats, and consequently careful > human review always never takes place nor is it practical.
I agree with you only up to a point. _Some_ man page authors _do_ want to ratchet the quality of their man(7) and/or mdoc(7) documents up to professional typesetting quality. A major objective of mine since joining groff development in 2017 has been to adapt to man page composition a storied principle of Perl programming: "keep easy things easy, and make hard things possible". (I may be paraphrasing.) That's why I planted my feet with respect to not remapping hyphen-minus character in a moderately notorious episode. https://lwn.net/Articles/947941/ In the discussion that ensued, I said: 'I can accept the interpretive frame that this was a matter of balancing externalities; when I first came to the issue, I asked myself, "well, how are people who *want* typographically superior man pages supposed to see the errors so that they can fix them?"' The general tenor of responses from the loudest spokespeople of the "always remap `-` to `\-`" camp approached crystalline simplicity: >>> I don't care. No one else should, either. F*** that, and f*** you. You may imagine my Samuel L. Jackson-inspired response to that attitude. > > Unfortunately groff insists on hyphenating words that are known > > to be technical terms such as in .Xr, or .Fn, etc. Where groff > > upstream suggests that those words need to be marked up with > > things like \%, which looks like unnecessary busy work. > > I agree that recommending \% is bad advice, for a slightly > different reason. Writing manual pages should be kept simple > for manual page authors, most of whom are not typesetting > specialists nor intested in learning the finer details of > typesetting. Some very basic typesetting knowledge is unavoidable - > like not confusing hyphens, minus signs, and dashes - but asking > manual page authors to worry about hyphenation control escape > sequences feels over the top. I'm not in love with the practice, and it does involve some tedium. But it's portable, and generally _works_,[1] whereas using `hw` was a crap shoot and had a "spooky action at a distance" effect on subsequent man pages rendered in the same batch. Granted, the way man-db man(1) works, you'd never see that nonlocal effect because, when asked to render multiple pages, it spawns a separate *roff process for each document. > [...] > > Yes. Another--likely much less tedious--approach involves using the > > `hw` request to declare a man page's hyphenation exception words > > within the document. > > I'm not enthusiastic - this would be yet another instance of low-level > roff(7) requests in manual pages. Admittedly, the likelihood that .hw > causes any concrete harm in a manual page is lower than for many other > roff(7) requests. Right. `hw`'s blast radius is well-defined and constrained. In my view, resort to formatter requests should be made only when: 1. there's simply no way to achieve the goal with the existing macros; 2. the document renders intelligibly if the requests are unimplemented; and 3. one's objective is to "go above and beyond" what a garden variety man page maintainer is concerned with. Preparing camera-ready typeset copy--though that phrase is, I guess, an anachronism since I gather publishing houses nowadays accept PDF directly--is an example. In my own work on groff's man pages, far and away my most frequent application of formatter requests is the use of "poor man's keeps", for manual widow and orphan management in the compiled PDF we produce. The `br` and `ne` requests can be discarded harmlessly, and when the output format is not paginated, as with HTML and the terminal's "continuous rendering mode", there isn't _any_ effect. Graceful degradation is the guiding star. Relatedly, when I started pursuing the objective of making the `hw` request safe for man pages, I did so knowing full well that it would make no difference to mandoc(1). No incompatibility or divergence in output can arise here, because at _rendering_ time a user can always set `-r HY=0`, whether via /etc/groff/{man,mdoc}.local, or $MANROFFOPTS, or "directly" as a parameter to nroff(1). They'll then get mandoc(1)- compatible non-hyphenation.[2] As the "new age" of `hw` and `rhw` settles in, I expect to experiment with migrating groff's own man pages away from the tedium of prefixing literals with `\%`, because groff's man pages expect to be rendered by a groff-compatible formatter. That's why we use extended escape sequences instead of only AT&T-compatible ones. (This matters most for special characters.) Doing so will give up some compatibility with Heirloom Doctools troff, but that project has become nearly moribund. In 2019, its maintainer said: "Unfortunately I don't have the time to do any further work on GitHub projects. It had already been agreed to continue the Heirloom-doctools development @reffort 's GitHub account." ...and that person (@reffort) added: "The further development I had in mind was to advance the typographical capabilities without any particular consideration for badly coded man pages or groff compatibility." https://github.com/n-t-roff/heirloom-doctools/issues/87 If Heirloom Doctools goes anywhere, it will venture down its own path. But, again, for this `hw`/`rhw` work, the blast radius is limited. Heirloom Doctools will make different, perhaps hard-to-troubleshoot, hyphenation decisions in the event it is used to batch-render man pages, _and_ those pages use `hw` in ways that affect other documents. I expect any divergence to be difficult to perceive for a long time. > > Further, Ingo is of the opinion that `so` is an inherent security > > risk in any application, as I recall. > > That's an exaggeration. > * In manual pages, the X11 pracice of using ".so man3/target.3" > in files man*/*.* located in the same manual page tree is not > usually a security risk. The practice is slightly fragile, > but not much more than that. > * In manual pages, .so becomes a security risk with absolute > path name arguments, or with arguments containing /.. or ../ . > * In general-purpose typesetting, .so can become a security risk > when the formatter is run on an untrusted input file - but > while having untrusted manual pages on a system is not unusual, > most people doing general purpose typesetting typeset their > own files, or files received from trusted acquaintances, > so .so rarely causes actual security risks. Thanks for clarifying; I'm glad to know your position is not as extreme as I feared. :) Regards, Branden [1] Some AT&T troff man(7) packages do something funny with some macro arguments, like prefixing them unconditionally with `\%` or `\&` themselves, which can make an explicit `\%` change its meaning to indicate a hyphenation point. This does not alarm most people, because the result is generally not confusing, just ugly. But if groff produces ugly rendering that is not the result of user error, my dander rises, I pick up a nice heavy wrench, and start swinging. Anyway, AT&T man(7)'s logic can result in output like this (simulated, incongruously, with groff_mdoc(7)). The GNU implementation of the mdoc macro package is part of the groff(1) document formatting system. mdoc is a structurally‐ and ‐ semantically‐oriented package for writing Unix manual pages with troff(1). See the stray hyphen at the end of the second line? That makes me cringe mightily, but I can't say it makes the document unintelligible. I don't worry about this too much because almost all man page rendering in the real world is done either with groff, which doesn't screw this up, or with mandoc, which never automatically hyphenates, and thus _can't_ screw it up. Thus, few people ever actually witness this misrendering. I get to see it because when I contribute man page fixes to other projects, I check them out with Heirloom Doctools troff, DWB 3.3 troff, Solaris 10 troff, and Plan 9 troff (as well as the "Big Two") before submitting them. [2] We've handled breaking at _explicit_ hyphens, and dashes of various sorts, a bit differently over the years. These issues don't involve _automatic_ hyphenation and are very deep in the weeds. The only people who ever seem to talk about them are formatter maintainers. Several years ago we had a relevant discussion on this list, but I cannot now locate it.
signature.asc
Description: PGP signature
