Hi Thomas, At 2025-10-26T06:59:32-0400, Thomas Dickey wrote: > On Sun, Oct 26, 2025 at 06:10:50AM -0400, Thomas Dickey wrote: > > On Sun, Oct 26, 2025 at 05:55:53AM -0400, Thomas Dickey wrote: > > > On Sun, Oct 26, 2025 at 04:53:38AM -0400, Thomas Dickey wrote: > > > > On Sat, Oct 25, 2025 at 08:53:02PM -0500, G. Branden Robinson wrote: > > > > > At 2025-10-26T00:43:19+0000, Thomas Dickey wrote: > > > > > > + correct a recent change to curs_termino.3x, along with > > > > > > formatting fixes for manpages. > > > > > > > > > > This change regresses formatting on DWB 3.3, Plan 9, and > > > > > Solaris 10 troffs, causing some synopsis lines to overset > > > > > (overrun the right margin). That's because those formatters > > > > > use a line length of 65n in nroff mode, not 78-80n as Heirloom > > > > > Doctools troff and groff (for their man(7) packages), and > > > > > mandoc(1) do. > > > > > > > > so... can we set the line-length for those in a directive? > > > > > > For instance, would > > > .if n .ll 70 > > > > > > work with those older versions, or would (putting it before .TH > > > for instance) be ignored?
Putting it _before_ the `TH` call will definitely not work in groff.
That's by design to support the user- (reader-) definable `LL` register.
NEWS (groff 1.23.0, July 2023):
* The an (man) macro package no longer honors an `ll` request to set
the line length on nroff devices prior to processing a man page.
This was deprecated in groff 1.18 (July 2002), and all known man
program and macro package implementations either have set an LL
register since 2002 (man-db man), 2005 (Brouwer/Lucifredi man), or
don't let the user vary the line length freely (DWB troff, Solaris
troff, Plan 9 troff), don't permit its configuration via the `ll`
request (mandoc), or at all (Heirloom Doctools troff).
groff_man(7):
History
...
UC appeared in 3BSD (1980). Unix System III (1980) introduced P
and exposed the registers IN and LL, which had been internal to
Seventh Edition Unix man.
...
Options
The following groff options set registers (with -r) and strings
(with -d) recognized and used by the man macro package. To ensure
rendering consistent with output device capabilities and reader
preferences, man pages should never manipulate them.
...
-rLL=line‐length
Set line length; the default is 80n on terminals and 6.5i
on typesetters.
> > I see with groff that works after the .TH line, but is ignored with
> > Solaris 10. Also, comparisons don't appear to work, e.g,
> > .if n .l > 70
That's invalid syntax. Here's how to (portably) write that.
.if n .if \n(.l>70n
...but I wouldn't bother; see "Finally" below.
> Revisiting
> .if n .ll 70
>
> I see that the .SH, .PP, etc., commands reset the line length in
> Solaris 10.
Yes. That's probably what I was thinking of when I wrote (over 2½ years
ago) that that implementation doesn't let the user modify the line
length freely. In that instance, neither the document author nor the
reader (at formatting time) is at liberty to configure the line length.
> which admittedly is odd to look at, but since we're not often using
> terminals which have only 65 columns, is arguably okay.
I agree that it's a mostly cosmetic problem, but there's no guardrail
(apart from human diligence) against ncurses man page synopses
overrunning 80 columns, either.
I'd prefer something more robust.
> Solaris 10 nroff can't handle terminfo.5 anyway...
...and I saw for the first time yesterday that Plan 9 nroff--I didn't
check its troff--chokes on the section headings (`SH` calls) of multiple
ncurses man pages, emitting macro package logic literally into the
output, a strange defect. Might be a bug in the package.
$ 9 nroff -man $(man -w insstr) | grep -F .ss
"'''ifNAMESYNOPSIS .ss 18 NAME
"'''ifSYNOPSISSYNOPSIS .ss 18 SYNOPSIS
"'''ifDESCRIPTIONSYNOPSIS .ss 18 DESCRIPTION
"'''ifRETURNSYNOPSIS .ss 18 RETURN VALUE
"'''ifNOTESSYNOPSIS .ss 18 NOTES
"'''ifEXTENSIONSSYNOPSIS .ss 18 EXTENSIONS
"'''ifPORTABILITYSYNOPSIS .ss 18 PORTABILITY
"'''ifHISTORYSYNOPSIS .ss 18 HISTORY
"'''ifSEESYNOPSIS .ss 18 SEE ALSO
It also rings the terminal bell, maybe once for each of these lines. My
nose tells me someone goofed up usage of the "formatted output
comparison operator".[1] (Because AT&T troffs maintain no stack of
interpretation contexts, one has recourse to a bizarre panoply of
characters one can employ as delimiters, including control characters
like ^B, ^C, and ^G. Nevertheless there isn't a uniform set of
delimiters available in AT&T troff, but rather three different
context-dependent ones.[2])
I've successfully gotten a patch into Plan 9 from User Space's man(7)
package with fast turnaround.[3]
I will therefore:
1. See if I can discern the root cause of P9US's bad rendering above.
2. See what's going wrong with terminfo(5) on Solaris 10. Whatever the
problem is, I'll see if I can reproduce it on DWB 3.3 or Plan 9,
since Solaris's is by far the implementation most tedious for me to
test. (I have to SSH to the FSF's compiler farm.[4])
Finally, to get back to the synopsis filling problem...
I think setting an explicit line length is the worst of three possible
solutions as explored above. What are the other two solutions?
A. Instead of turning of filling, turn off adjustment, and use the `HP`
macro to get a hanging indent if a synopsis item requires more than
one output line.[5] There is in fact a portable way to temporarily
turn off (and restore) adjustment, but I've never encountered a man
page that has used it.[6] I recently proposed this approach for the
GNU less(1) man page, which also wants to be portable well outside
the GNU/Linux ecosystem and where AT&T troff or primitive work-
alikes may be in use, and Mark Nudelmann merged it.[7]
B. Define page-local versions of groff's `SY` and `YS` macros, newly
revised for the forthcoming 1.24 release to handle both command and
function synopses.[8] Alex Colomar of the Linux man-pages project
provided invaluable service in field testing these.
I'm happy to prepare patches migrating ncurses's man pages to either of
these solutions. Do you have a preference?
Regards,
Branden
[1]
https://www.gnu.org/software/groff/manual/groff.html.node/Operators-in-Conditionals.html#index-output-comparison-operator
[2] https://savannah.gnu.org/bugs/?67408
[3] https://github.com/9fans/plan9port/pull/735
[4] https://gcc.gnu.org/wiki/CompileFarm
[5] groff 1.23.0 man(7)'s man page and undocumented `CHECKSTYLE`
register advise that the `HP` macro is deprecated. That decision
appears to be an Eric S. Raymond-driven choice,[9] predicated, I
suppose, on making life easier for his "doclifter" project; he
didn't _say_ that in his commit message, but was flogging it as a
man page validator two days previous.[10] The observation about
hanging indents being inexpressible naturally in HTML overlooks the
availability of CSS,[11] which our grohtml(1) output driver was
inlining even back then.[12]
[6]
https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/tmac/an.tmac?id=af13618a30cb04ce35eb122e70b716f217e7bf06#n156
[7]
https://github.com/gwsw/less/pull/663/commits/890c0ec6b0d8149d995e649597b66e97e577cb57
[8]
https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/tmac/an-ext.tmac?id=af13618a30cb04ce35eb122e70b716f217e7bf06#n60
[9]
https://cgit.git.savannah.gnu.org/cgit/groff.git/commit/?id=26e827e36a4d98e9a9403bcc73b4afb116495407
[10] https://lists.gnu.org/archive/html/groff/2007-02/msg00011.html
[11] https://www.w3schools.com/cssref/pr_text_text-indent.php
[12]
https://cgit.git.savannah.gnu.org/cgit/groff.git/commit/?id=c4125fd2ef3f433676bd9cf67120598d33387e26
signature.asc
Description: PGP signature
