using the `hw` request in man pages (was: adjustment and hyphenation in mdoc(7) pages)

[G. Branden Robinson]

At 2023-03-24T13:29:32-0500, Dave Kemper wrote:
> On 3/24/23, G. Branden Robinson <g.branden.robinson@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