Hello, 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.[1] > [1] https://gitlab.freedesktop.org/libbsd/libbsd.git > > 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. I agree that statement is overly broad. If the technical document is exclusively used for typesetting purposes (as opposed to being a living document, or a document intended for multiple output formats) and the typesetting process involves the manual, human review of typesetting details that usually occurs in high-quality book publishing, then using hyphenation where appropriate is acceptable and common practice - Branden listed many examples. 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. > 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. > The current workaround requires to use low-level troff markup to > globally disable hyphenation with groff, which is less than ideal, > but the best known option available. I disagree. You are trying to solve a non-critical problem on the wrong level. The result is ugly source code pollution for negligible benefit. The problem is non-critical: i agree that groff(1) sometimes hyphenates at places where it better shouldn't, and it sometimes breaks the output line at hyphens where it better shouldn't (which is not the same, but a related problem); but the damage is slightly ugly output at worst, and the output remains intelligble. Besides, Brandon often works on improving hyphenation, so the situation slowly improves over time. Your solution is on the wrong level for various reasons. * Formatting conventions should be decided by the maintainers of formatting programs (like Branden and myself). Operating system maintainers can (sparingly) modify these conventions when packaging the formatting programs. But individual manual pages should definitely not attempt to override global formatting conventions because that is fragile at best, jeopardizes portability, and harms uniformity of formatting within each operating system. * Manual pages should not use low-level roff(7) requests (with very few exceptions not relevant in the present context). Apart from fragility and portability concerns, such practice risks founding cargo cults when other authors follow the example - which is a particular concern when it happens in influential libraries like libbsd. * When formatters make problematic decisions, that really needs to be addressed on the formatter level (subject to OS-specifc formatter packaging). [...] > 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. > (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. Ingo Schwarze, the > mandoc(1) maintainer, and I would both discourage shipping a populated > man page with `so` requests in it, since there is no convention for > locating such auxiliary *roff files on the file system. Indeed, .so is somewhat fragile; details of its behaviour very across systems and formatters. > 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. Yours, Ingo
