At 2023-03-24T13:29:32-0500, Dave Kemper wrote: > On 3/24/23, G. Branden Robinson <g.branden.robin...@gmail.com> wrote: > > This means that mdoc(7) authors will need to learn a habit that is often > > neglected by their man(7) rivals as well: > > > > Use the hyphenation control escape sequence wherever necessary. It can > > suppress hyphenation of _any_ word it prefixes in _any_ context. > > In regular roff documents, one can also use the .hw request to > globally suppress hyphenation of specified words. This is often > preferable, as it doesn't require the user to (1) find and adorn every > instance of a word that ought not be broken, and (2) remember to > prepend a \% every time a new instance of that word is later added to > the text. Let computers do algorithmic things.
This is true, and I do on rare occasions see man pages doing this.
> In man documents, authors are discouraged from using low-level roff
> requests. But I wonder if .hw ought to be one of the exceptions. An
> author of a C-related man page will know they never want the keyword
> "typedef" broken in any context. Seems like they ought to be able to
> tell the formatter once "Never hyphenate this word."
>
> .hw is a longstanding (pre-groff) roff request, so should pose no
> portability problems to roff-rendered man pages. But I realize other
> tools also parse man source, and don't know what portability concerns
> that may raise.
I'm ambivalent about the use of the `hw` request in man pages.
1. I like the clarity of the "never use *roff requests" rule. My
internal bright-line rule enforcer is enamored of this principle.
It keeps the fingers of the novice out of the meat grinder.
2. You're right that `hw` is precisely the correct tool for the job.
3. It seems not to come up very often in practice. Many times when
programming language keywords appear in a man page, they do so in
synopses, where hyphenation is disabled (if you use groff man(7)'s
`SY` and `YS`), or in examples, which aren't filled, and therefore
not hyphenated.[1] That leaves _occasional_ occurrences in running
text, where prefixing the odd word with `\%` _might_ not be
perceived as onerous.
4. If I had to teach learning-resistant man page authors only one of
`hw` and `\%`, I'd pick the latter without hesitation. It solves
more problems and giving it up would degrade man page typography in
other ways.
5. We could hold to principle #1 by adding a man(7) macro, `HW`, which
simply wraps `hw`. Unlike `MR`, this would be a harmless extension
because it's fine to ignore it (as mandoc(1) surely will); the worst
that can happen is that you'll see words hyphenated where you didn't
want them and you end up using `\%` anyway--or just living with it
because writing documentation is so hard for the brogrammer. (It is
also an exception to the rule expressed in groff_man(7) that
"arguments to macros are typically formatted as text.)
6. But the worst will seldom happen--speaking of mandoc(1), it truly
has no reason to interpret either `hw` or the just-mooted `HW`
because it never performs automatic hyphenation anyway. (It _does_
break after "hard" [literal] hyphens '-'. If you want to prevent
that in *roff, you need to prefix a word with `\%`. mandoc(1) will
ignore you and break the line where it pleases anyway.)
7. At present I'd prefer to spend my man(7) new-macro campaigning
energy on things that will pay a larger dividend than `HW`.
8. The status quo would appear to be "don't ask, don't tell". Nobody
recommends the use of the `hw` request in man pages, but nobody
complains about it, either. We don't, and a quick test reveals that
mandoc 1.14.6 doesn't either, even with "-Tlint" (and I hope Ingo
keeps it that way). I feel sure no other *roff does; doing so would
require intercepting the `hw` request in the man(7) macro package
and I've never seen that done. The whole idea of using a reduced
roff dialect to express man pages is a post-groff, post-WWW-
revolution idea anyway, arising from a fashion once in vogue that
everything in the world needed to be translated into HTML.
Maybe the world has passively and quietly found a worthy consensus?
Regards,
Branden
[1] Aside: I did notice just the other day that mdoc(7), being sensitive
to the names of man page sections (`Sh`), also turns off adjustment
for "See also" sections. This does indeed solve the problem of
lists of man page cross references in this section having ridiculous
gaps between items, just like the mdoc(7) synopsis problem Alex
raised earlier this week. I'm mulling over whether and how to give
man(7) "feature parity" here, without adding pattern matching
against natural language phrases, which strikes me as inelegant.
`DS` and `DE`, already defined for many years, and with pre-GNU
provenance, threaten again...
hard-hyphens.man
Description: Unix manual page
signature.asc
Description: PGP signature
