Control: severity -1 serious
Hi. Thanks for your comprehensive, detailed and helpful email.
G. Branden Robinson writes ("Bug#1041317: dgit: table too wide in man page,
trashes autopkgtests"):
> Package: dgit
> Version: 9.13
> Severity: Important
> Justification: causes problems for everybody's autopkgtests
>
> I noticed that groff 1.23.0-2 (and -1 before it) will be blocked from
> ever migrating to testing due to an autopkgtest failure on EVERY
> architecture.
I'm sorry that this test is causing you an inconvenience. Thanks for
filing the bug. I think the right severity for a bug which is
preventing another package from migrating is serious, so I am raising
the severity of your report.
> https://tracker.debian.org/pkg/groff
>
> So I downloaded the 2.4MB compressed autopkgtest log for groff 1.23.0-2
> on amd64 and trawled through the 325,000+ lines of output looking for
> the problem. On the one hand, that is an obnoxiously huge amount of
> information. On the other, the log is annotated well enough that I was
> able to quickly locate the problem.
Thanks very much for investigating. And thanks also to Colin for the
MR adjusting the regexp.
> Here are the juicy bits.
...
> 941s RE (?^:^(?:(?^:^(?=a)b))$)|(?^:^(?:ERROR.*)$)|(?^:^(?:.* # table wider
> than line width)$)
...
> That regex is sufficiently complex that I can't tell if it's trying to
> filter the diagnostic message "table wider than line width" or not. If
> it is, the fact that I have recast the language of the diagnostic
> message in groff 1.23.0 has fooled it.
Yes, that is what it is doing. Unfortunately as far as I'm aware,
groff doesn't offer a formal warning suppression or classification
mechanism. So instead there is this regexp, which (as might be
expected of such a thing) is fragile and keeps growing cases as
messages change, becoming ever more baroque and inscrutable.
> It is a bad idea to rely on the exact wording of diagnostic messages.
> That is one reason error conditions in many software systems are given
> an unintelligible identifier.
Quite so. If you had an alternative way to suppres this, I would
have been happy to hear it! However later you tell me how to avoid
the warning completely, which is much better.
> https://git.savannah.gnu.org/cgit/groff.git/commit/?id=7111d3378f0c2ceab891d66ae815d393ff87dae5
>
> Yes, the language in the regex could be updated if it's doing what I
> think it is, but that just kicks the can down the road. It is better
> for groff to have the freedom to continue to improve its diagnostic
> messages for the comprehension of the user.
I agree.
> So let's the fix the problem in the dgit man page.
>
> Man pages are formatted for a width of 78n if the terminal width is 80
> columns. This origin of this practice is not well documented but
> experience with groff upstream leads me to believe that it is a
> workaround for bugs in GNU tbl(1). (In AT&T Unix Version 7, they were
> formatted for a line length of 65n, with a page offset of one tenth of
> an inch. On Western Electric Teletype Model 37 printing terminals.)
>
> How wide is dgit's man page?
...
> 79
...
> Hence the warning.
>
> groff 1.22.4 didn't used to throw this warning in this circumstance.
I'm pretty sure at least one version of groff I encountered produced
this warning, and that's why I have this adhoc regexp-based ignore
rule.
> The diagnostic is wholly legitimate.
>
> Let's have a look:
>
> $ MANPAGER=cat MANWIDTH=80 command man --warnings -Tascii dgit | sed -n
> '/DESCRIPTION/,/OPERATIONS/p'
> <standard input>:46: warning: table wider than line length minus indentation
> DESCRIPTION
...
> dgit-maint-gbp(7) for maintainers already using
> git-buildpackage
...
> Yup, if we look carefully, we can see that the word "git-buildpackage"
> encroaches into the right margin.
This is true in a strictly technical sense: the generated formatting
does violate groff's the intended behaviour. However, the output is,
in fact, perfectly fine, when looked at from a user's point of view:
the output line is 79 characters long, which as you note doesn't in
fact currently cause trouble (other than this warning).
So I felt justified in ignoring the warning. But, I didn't want to
ignore all warnings since it is so easy to introduce syntax errors
etc. Hence the fragile regexp.
I think that the best fix would be this:
> I would like in the future to improve GNU tbl to the point where tables
> can spread their wings to the full 80 column span of the widely accepted
> minimum terminal width, but a deeply ingrained feature of GNU tbl makes
> that tough.
>
> Maybe it will happen for groff 1.24.
I quite believe you that it's difficult.
> My recommendation is a simple tweak to the table format, stealing one en
> of column separation to make the table fit.
This sounds like a very reasonable workaround to me. I'll take a look
at the generated output and (assuming I'm happy with it) I'll adopt
your suggestion.
> $ diff -u ./dgit.1.orig ./dgit.1
...
> -lb l.
> +lb2 l.
I expect to make an upload within a few days, maybe a week. I hope
that's satisfactory.
Ian.
--
Ian Jackson <ijack...@chiark.greenend.org.uk> These opinions are my own.
Pronouns: they/he. If I emailed you from @fyvzl.net or @evade.org.uk,
that is a private address which bypasses my fierce spamfilter.
