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

[Alejandro Colomar]

Hi Branden, Dave,

On 3/25/23 09:40, G. Branden Robinson wrote:
> At 2023-03-24T13:29:32-0500, Dave Kemper wrote:

>> 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.

Maybe it would be a good thing for man.local?  For manual pages, it
seems a bit too repetitive, IMO.  Maybe for a manual page that uses
very rare keywords would be a good place to use those.

> 
>> 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`.

What's the gain of such a thing?  Translators will have the same problem
translating .hw than translating .HW.  The only difference is that .HW
would appear in the man(7) spec, which would force them to recognize it,
as opposed to saying "we don't support plain roff".

>  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?

.MR will only improve the status quo, so if not many complained till now
(I did, but 1 is not too many), there will be even less need for .hw
soon.  I'd say, let's defer this problem for long after .MR, and see if
there are any remaining issues.  Same with \%, which is why I don't yet
want to introduce it in the Linux man-pages.

Cheers,
Alex

> 
> 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...

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

OpenPGP_signature
Description: OpenPGP digital signature