At 2025-10-26T17:23:42-0400, Thomas Dickey wrote: > I use a script which tells me the formatted length. That's separate > from the groff and mandoc checks which it runs.
I figured. I haven't arsed myself to come up with an equivalent. The
wc(1) from GNU coreutils supports `-m` for counting characters these
days, which should work well enough if nobody uses "fullwidth" Unicode
code points in man pages--and no project to which I've contributed does,
as far as I've seen.
> 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);
Yeah, that page looked pretty daunting, so I haven't attacked it yet
with my formatting revision cookbook. Maybe this thread will point its
way forward.
> ./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).
Visually, yes.
> > 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...).
I try to deal with the Oracle Corporation and its wares as little as
possible. The main reason I examine Solaris troff at all is to
foreclose objections to my proposed man page revisions on the grounds
that the billions and billions of people still enthusiastically reading
man pages on Solaris 10 will be inconvenienced. A secondary reason is
that Solaris 10 is the easiest specimen of a troff that descends from
DWB 2.0 but not, apparently, DWB 3.0, and thus, as I understand it,
characterizes System V troffs in general. The groff list hears from
HP-UX and AIX users with less frequency than total solar eclipses occur.
Incidentally I should note that for a while I thought, and may have
said publicly, that Solaris 11 threw over its troff for groff. That was
an overstatement. Solaris troff still exists on Solaris 11, but
Solaris 11's man(1) runs groff to format documents.
> > 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.
You can prevent that by using the unbreakable space escape sequence,
`\ ` (backslash-space). That can be ugly, and I discourage it, in
adjusted text where portability to AT&T troff is not sought, in favor of
GNU troff's `\~` adjustable nonbreaking space. At my prompting,[A] Plan
9 from User space supports that as a synonym of `\ `, meaning it's not
adjustable.
However the distinction doesn't matter when adjustment is disabled,
which is the scenario here. `\ ` is universally portable.
> > 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.
That's easily implemented with either approach; with filling reënabled,
you can break the input lines wherever makes sense for document
maintenance purposes.
Here's a sample of how I might handle `extended_color_content_sp()`
using each approach, pretending that it's the only function in the page.
.TH foo 3 2025-10-26 "groff test suite"
.SH SYNOPSIS
.HP
.nr sA \n(.j \" Save the adjustment mode.
.na
.B int\ extended_color_content_sp(
.BI screen\ *\ sp ,
.BI int\ color ,
.BI int\ *\ r ,
.BI int\ *\ g ,
.BI int\ *\ b );
.ad \n(sA \" Restore the adjustment mode.
.rr sA
.SH DESCRIPTION
etc.
Rendering:
$ nroff -rLL=65n -man /tmp/thomas-hp.man
$ ~/groff-HEAD/bin/nroff -rLL=65n -man /tmp/thomas-hp.man
foo(3) Library Functions Manual foo(3)
SYNOPSIS
int extended_color_content_sp( screen * sp, int color,
int * r, int * g, int * b);
DESCRIPTION
etc.
groff test suite 2025‐10‐26 foo(3)
(Older groffs are the same except for extraneous blank lines.)
And here's the `SY` solution.
.TH foo 3 2025-10-26 "groff test suite"
.SH SYNOPSIS
.B int
.SY extended_color_content_sp (
.BI screen\ *\ sp ,
.BI int\ color ,
.BI int\ *\ r ,
.BI int\ *\ g ,
.BI int\ *\ b );
.YS
.SH DESCRIPTION
etc.
Rendering:
$ ~/groff-HEAD/bin/nroff -rLL=65n -man /tmp/thomas-sy.man
SYNOPSIS
int extended_color_content_sp(screen * sp, int color,
int * r, int * g, int * b);
DESCRIPTION
etc.
You could quote macro arguments to avoid having two spaces in sequence
in the source, which might bit-rot in maintenance.
The advantages to the new-and-improved `SY` and `YS` are that they (1)
avoid requiring the man page author to use *roff requests to manage
adjustment and (2) indent subsequent lines of the paragraph in a way
that makes more sense syntactically, and more closely resembles some
source code indentation conventions. Advantage (2) could be achieved
with AT&T troff as well, but it would require direct use of *roff
features again (the `\w` escape sequence), and either violation of the
DRY principle or the definition and use of a page-local macro.
> > [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 :-)
I try to get respectable mileage out of my ESR grievances.
Regards,
Branden
[A] https://github.com/9fans/plan9port/pull/567
signature.asc
Description: PGP signature
