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) ...
.TH rpm 8 2021-02-28 "rpm 4.17" .TP .BI \-\-macros\~ file-list Replace the list of macro files to be loaded with .IR file-list . . Each file or .IR glob (7) pattern in the colon-separated .I file-list is read sequentially by .I rpm for macro definitions. . Only the first file in .I file-list must exist. . Tildes will be expanded to the value of the environment variable .IR HOME . .\" XXX: Mention %{} RPM variable expansion if not covered more .\" generally elsewhere in the page. . . .IP The default .I file-list is as follows. . .RS .RS \" RS twice to get inboard of IP indented paragraph. .EX /usr/lib/rpm/macros: /usr/lib/rpm/macros.d/macros.*: /usr/lib/rpm/platform/%{_target}/macros: /usr/lib/rpm/fileattrs/*.attr: /usr/lib/rpm/redhat/macros: /etc/rpm/macros.*: /etc/rpm/macros: /etc/rpm/%{_target}/macros: \(ti/.rpmmacros .EE .RE .RE
signature.asc
Description: PGP signature