Re: Adjusting long lines in man pages and how to temporarily disable a warning?

[G. Branden Robinson]

Hi, Tim!

At 2021-02-28T01:08:37+0000, Tim Landscheidt wrote:
> Hi,
> 
> the man page for rpm(8) has a section that causes a warning
> on display (added ".TH" here for a reproducible example):
[snip]
> When run through "groff -mandoc -rLL=162n -rLT=162n -Tutf8 <
> rpm.8 | sed -e 's/\x1b\[[0-9;]*m//g;'", this displays:
> 
> | <standard input>:10: warning [p 1, 1.2i]: cannot adjust line
[snip]
> At first, I thought "cannot adjust line" means that groff
> cannot find a place to wrap a line, which was at odds with
> the plenty of zero-width break points, but I believe I now
> understand correctly that "cannot adjust line" means that
> groff finds no/not enough spaces between words to spread the
> words "from left to right"?

That's right.  When groff can't _break_ a line, it uses that word in the
diagnostic.  If you take out all the non-printing break point escapes
(\:), and add a hyphenation control escape (\%) to the beginning of the
long string (the RPM macro file list) in question, that is what you will
get.

$ ./build/test-groff -mandoc -rLL=145n -Tutf8 < EXPERIMENTS/rpm2.8 \
  | sed -e 's/\x1b\[[0-9;]*m//g;'
troff: backtrace: file '<standard input>':10
troff: <standard input>:10: warning [p 1, 1.3i]: can't break line

> Supposing that, is there a way to achieve a warning-free/"beautiful"
> look for such para- graphs with "words" longer than a line?

There are two forms of beauty that I think can be discussed here--the
typographical kind, or the sort where innocent users are not troubled
with diagnostic messages from the formatter that they have nothing to do
with.

In the typographical case, when lines are being adjusted to both margins
and two adjacent unbreakable words are both of length x as a percentage
of the line length, where 50%<x<100%, then adjustment is simply
impossible.  You will either have to over-set a line (exceed the line
length) or have a ragged margin for at least one line.  This is why the
formatter warns.

> Second, the warning can confuse the user.  Therefore (if
> there is no way to set this long line "beautifully"), I'd
> like to disable it temporarily for this line.  I found that
> I can achieve that by wrapping:
> 
> | .\" If warnings for breaks (4) are set, disable them.
> | .nr saved-warn-level \n[.warn]
> | .if ((\n[.warn] - ((\n[.warn] / 8) * 8)) > 3) .warn (\n[.warn] - 4)
> 
> and:
> 
> | .warn \n[saved-warn-level]
> 
> around it (and now I see that tmac/doc.tmac-u even has a si-
> milar piece of code).
> 
> Is that the groffy way to to do that?  Or is there some al-
> ready existing macro that says "my argument can be long,
> don't complain about it"?
> 
> Any other advice is highly appreciated.

I don't think the above approach is a good idea.  It's not only
groff-specific, which will cause the material to be ignored by the
mandoc(1) formatter[1], but dependent on the inscrutable and
un-memorizable numeric warning codes, which in the opinions of a few
people on this list are bizarrely categorized anyway (though IMO "break"
is a good category).

Worse, "adjust" is simply not an available category for warning
suppression, so you can't solve the problem this way even if the
structure of the solution were advisable.  Adjustment warnings use
groff's diagnostic subsystem slightly differently than other warnings.

My recommendation is to recast the material, breaking the lines at the
colons explicitly.  This will also, in my view, make the prose more
readable.

I'm attaching a revised version of your snippet.  I made many more
changes, following the style and practices of groff's own man pages,
largely because these are habits I've cultivated while working on them
over the past few years, but also because I honestly believe they make
page maintenance and the rendered result better.

The changes that directly addresses your point are

(1) bracketing of the default file-list in .EX/.EE ("example") macros;
(2) breaking of lines after colons in the default file-list; and
(3) use of the more typographically correct \(ti (tilde) special
    character for a non-overstriking "ASCII" tilde on the centerline.

Feel free to follow-up with me about any of the others[2].

The result renders nicely for me without warnings using groff 1.22.4,
groff Git HEAD, and mandoc 1.14.4.

Regards,
Branden

[1] You're in double-edged luck here for the instant problem,
    however--mandoc(1) refuses to do anything but left adjustment
    (ragged right margin) when formatting; it will neither attempt to
    pad any lines with spaces nor complain that it can't.  Amusingly,
    the version I'm using (mandoc 1.14.4) ignores the \: escape sequence
    (it _is_ a groffism), so it merrily oversets the line.  Also, mandoc
    _always_ formats for a line length of 78n, so the output is
    _guaranteed_ to be ugly for this page--another reason to consider my
    suggested recast or something similar.

[2] I successfully resisted the temptation to add

  .SH "See also"
  .IR dpkg (1)

...

rpm-gbr.8
Description: Text document

signature.asc
Description: PGP signature