Hi Alex, At 2023-03-23T23:53:18+0100, Alejandro Colomar wrote: > I saw yesterday something that might have to do with this. Check the > timespecsub(3bsd) man (actually mdoc(7)) page, and in the SYNOPSYS > you'll find some weird filled function prototypes. I tried adding > hyphens to them, to see if it would break there, and it breaks, even > on the terminal! > > Here's a small reproducer of this issue (which might have to do with > the one reported by Brian, or might be a different one): > > $ cat timespecsub.3 > .Dd June 7, 2010 > .Dt timeradd 3bsd > .Os > .Sh NAME > .Nm timespecsub > .Nd operations on time structure > .Sh SYNOPSIS > .Ft void > .Fn timespecsub "struct-timespec *a" \ > "struct-timespec *b" "struct-timespec *res"
This issue isn't related to the one Brian reported except insofar as
man(7) and mdoc(7) are two macro packages with a very similar purpose
trying to do nearly the same thing. Therefore there is room for
independent bugs in each implementation.
I can reproduce the problem. In groff Git what is also noticeable
is that groff mdoc(7) now adjusts to both margins by default as is
historically correct for man pages. (Yes, you can turn this off; see
groff_mdoc(7).)
But it is not correct to do this in synopsis sections. When I enabled
both-margin adjustment for mdoc(7) in the 1.23.0 development cycle I
neglected to handle this. So that's unfortunately a regression (or
exposure of a latent bug) from groff 1.22.4. (I didn't notice because I
don't test a corpus of mdoc(7) test documents apart from groff_mdoc(7),
which _does_ exercise nearly every mdoc(7) macro that exists--its
original purpose is in part exercising the package--but doesn't have a
lengthy synopsis.) Time for a regression test.
$ ./build/test-groff -mandoc -Tascii ATTIC/timespecsub.mdoc
timeradd(3bsd) LOCAL timeradd(3bsd)
NAME
timespecsub -- operations on time structure
SYNOPSIS
void
timespecsub(struct-timespec *a, struct-timespec *b, struct-
timespec *res);
GNU June 7, 2010 timeradd(3bsd)
I conclude that mdoc(7) synopses rendered by groff need to do what
groff's man(7) rendering is already doing: disable hyphenation and
adjust to the left margin only.
Please find a patch attached--it fixes adjustment for me; how about you?
But it doesn't solve the problem you reported. That is because even
with hyphenation "off", hard hyphens are still considered eligible break
points because that is part of all *roff behavior everywhere, going back
forever.[1] It is not, I gather, mandoc(1) behavior, though, and it is
mandoc(1) users who are predominantly concerned with mdoc(7) rendering.
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.
From groff_man_style(7), forthcoming in groff 1.23.0:
[snip]
Fundamental concepts
groff is a programming system for typesetting: we thus often use the
verb "to set" in the sense "to typeset". The formatter troff(1)
collects words from the input and fills output lines with as many as
will fit. Words are separated by spaces and newlines. A transition
to a new output line is called a break. When formatted, a word may
be broken at hyphens, at \% or \: escape sequences (see subsection
"Portability" below), or at predetermined locations if automatic
hyphenation is enabled (see the -rHY option in section "Options"
below).
[snip]
Portability
[snip]
\% Control hyphenation. The location of this escape sequence
within a word marks a hyphenation point, supplementing groff's
automatic hyphenation patterns. At the beginning of a word, it
suppresses any automatic hyphenation points within; any
specified with \% are still honored.
[snip]
Perhaps instead:
At the beginning of a word, it suppresses any hyphenation breaks
within _except_ those specified with \%.
Here is a fixed version of the reproducer:
.Dd June 7, 2010
.Dt timeradd 3bsd
.Os
.Sh NAME
.Nm timespecsub
.Nd operations on time structure
.Sh SYNOPSIS
.Ft void
.Fn timespecsub "\%struct-timespec *a" \
"\%struct-timespec *b" "\%struct-timespec *res"
\% is desperately underused, despite being as portable as anything is in
*roff. Learn it, live it, love it!
Regards,
Branden
[1] The reader is invited to look this one up. Learn to fire up a V7
Unix environment under SIMH as I have and party like it's 1979!
signature.asc
Description: PGP signature
