Is groff ignoring `.nh` command?

Question

For a man page written in POD (perlpod) I had the effect that the SYNOPSIS was left-adjusted on the text terminal, but the PostScript output (read: troff) adjusted the text to both borders.

So I tried to embed formatting commands in the POD source. However, even when specifying .nh some words like "[--[no-]check-grace-logins]" were hyphenated at a minus.

That made me wonder whether the man -l command disobeys the .nh command. The manual page for roff(7) says:

.nh No hyphenation.

Here is the relevant part of the roff man page:

.\" ========================================================================
.\"
.IX Title "LDAP-USER-CHECK 8"
.TH LDAP-USER-CHECK 8 "2024-08-14" "0.0.0.0.20n" "System Administration"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ldap\-user\-check \- check LDAP account status
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.\" BEGIN roff
.\" save adjustment, then left-adjust
.ds _A \n[.j]
.ad l
.\" save hyphenation, then disable
.ds _H \n[.hy]
.nh
.\" END roff
\&\fBldap-user-check\fR
[\fB\-\-account\-context=\fR\fIcontext\fR]
[\fB\-\-account\-filter=\fR\fIfilter\fR]
[\fB\-\-add\-notification\-bcc\-address=\fR\fIemail-spec\fR]...
[\fB\-\-add\-notification\-cc\-address=\fR\fIemail-spec\fR]...
[\fB\-\-default\-default\-ppolicy=\fR\fIdn\fR]
[\fB\-\-default\-language=\fR\fIlang\fR]
[\fB\-\-default\-notification\-email\-address=\fR\fIemail-spec\fR]...
[\fB\-\-ca\-certs\-path=\fR\fIpath\fR]
[\fB\-\-\fR[\fBno\-\fR]\fBcheck-auth-failure\fR]
[\fB\-\-\fR[\fBno\-\fR]\fBcheck-grace-logins\fR]
[\fB\-\-\fR[\fBno\-\fR]\fBcheck-inconsistent-accounts\fR]
[\fB\-\-\fR[\fBno\-\fR]\fBcheck-locked-accounts\fR]
[\fB\-\-\fR[\fBno\-\fR]\fBcheck-password-policy\fR]
[\fB\-\-\fR[\fBno\-\fR]\fBcheck-pp-override\fR]
[\fB\-\-\fR[\fBno\-\fR]\fBcheck-shadow-password\fR]
[\fB\-\-credentials\-file\-name=\fR\fIfilename\fR]
[\fB\-\-instance\-string=\fR\fIinstance\fR]
[\fB\-\-ldap\-size\-limit=\fR\fInumber\fR]
\&\fB\-\-ldap\-suffix=\fR\fIsuffix\fR
[\fB\-\-ldap\-time\-limit=\fR\fInumber\fR]
\&\fB\-\-ldap\-uri=\fR\fI\s-1URI\s0\fR
\&\fB\-\-notification\-template=\fR\fIfilename\fR
[\fB\-\-override\-default\-ppolicy=\fR\fIdn\fR]
[\fB\-\-override\-expiration\-warning\-time=\fR\fInumber\fR]
[\fB\-\-override\-from\-email\-address=\fR\fIemail-spec\fR]
[\fB\-\-override\-notification\-email\-address=\fR\fIemail-spec\fR]...
[\fB\-\-ppolicy\-context=\fR\fIcontext\fR]
[\fB\-\-set\-notification\-reply\-to\-address=\fR\fIemail-spec\fR]
[\fB\-\-verbosity=\fR\fIlevel\fR]
[\fB\-\-wrap\-template=\fR\fIlen\fR]
.\" BEGIN roff
.\" restore saved hyphenation and adjustment
.hy \*(_H
.ad \*(_A
.\" END roff
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"

And here is what I see on a 80-character wide terminal:

WHen converting that manual page using groff -man -Tps the .nh seems to be ignored as well:

Programs being used are perl 5.18.2, groff-1.22, both from SLES12 SP5.

Answer 1

groff isn’t ignoring .nh, but its scope isn’t as comprehensive as you’re hoping.

.nh disables automatic hyphenation; words containing explicit hyphens (which is what check-auth-failure appears as to roff) are always eligible for breaking. This isn’t obvious from the documentation; but the “Manipulating hyphenation” section starts with

When filling, GNU troff hyphenates words as needed at user-specified and automatically determined hyphenation points.

and then proceeds to discuss, separately, user-specified and automatically determined hyphenation points.

Explicitly hyphenated words such as “mother-in-law” are eligible for breaking after each of their hyphens.

explains how explicit hyphens are handled.

Further down, in the discussion on automatic hyphenation, .nh is documented as a request to

Disable automatic hyphenation; i.e., set the hyphenation mode to 0 (see above).

To avoid unwanted explicit hyphenation in command keywords, use hyphen-minus symbols instead of “regular” hyphens:

[\fB\-\-\fR[\fBno\-\fR]\fBcheck\-auth\-failure\fR]

To understand the difference between the two, see Hyphens, minus, and dashes in Debian man pages (the distinction isn’t Debian-specific).

Since you’re using pod2man, you’d have to get it to use hyphen-minus symbols for you. It does that in some instances, for example after =item; but I don’t know of a way to ask it to generate hyphen-minus symbols elsewhere. It might be worth filing an issue about this.