On Sun, Oct 26, 2025 at 03:55:02PM -0500, G. Branden Robinson wrote: > 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 use a script which tells me the formatted length. That's separate from
the groff and mandoc checks which it runs.
groff complains here:
./infocmp.1m:208: warning: table row does not fit on page 1
and mandoc here:
./tput.1:50:86: STYLE: input text line longer than 80 bytes: initialize
a termina...
reviewing that (I'd made some change to exclude nonfilled lines...),
I see a few lines to investigate:
./curs_sp_funcs.3x:67: line longer than 80 columns (81 formatted):
int extended_color_content_sp(SCREEN * sp, int color, int * r, int * g,
int * b);
./curs_sp_funcs.3x:115: line longer than 80 columns (81 formatted):
WINDOW * newwin_sp(SCREEN * sp, int nlines, int ncols, int begin_y, int
begin_x);
./curs_sp_funcs.3x:171: line longer than 80 columns (90 formatted):
int vid_puts_sp(SCREEN * sp, attr_t attrs, short pair, void * opts,
NCURSES_SP_OUTC putc);
./curs_sp_funcs.3x:194: line longer than 80 columns (84 formatted):
int restartterm_sp(SCREEN * sp, NCURSES_CONST char *term, int filedes,
int *errret);
./terminfo.5:2260: line longer than 80 columns (85)
It also flags repeated words, but there's a fair amount of noise in that.
But still better than inspecting the files manually.
(By human diligence, I assume you mean inspecting the output from groff, etc).
> 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])
I have VirtualBox machines for 10 and 11.4 (on my Intel hosts...).
> 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
that splits the line on (whatever) whitespace, which generally
isn't nice code-formatting.
> 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?
as long as the result looks ok.
I'd prefer splitting the lines after comma - seems the simplest rule.
> 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]
I recall you mentioning this :-)
> [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
--
Thomas E. Dickey <[email protected]>
https://invisible-island.net
signature.asc
Description: PGP signature
