Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.debian.bugs.dist > #1154598

Bug#1041317: dgit: table too wide in man page, trashes autopkgtests

Show all headers | View raw

[Multipart message — attachments visible in raw view] - view raw

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.

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.

Here are the juicy bits.

[...]
941s + for roff in $manpages
941s + section=1
941s + page=dgit
[...]
941s + cmd='man --warnings "$@" $section $page'
941s + eval 'man --warnings "$@" $section $page 2>&1 >/dev/null |tee /tmp/autopkgtest-lxc.3j70k01o/downtmp/autopkgtest_
tmp/dgit.1.txt-errs'
941s ++ man --warnings 1 dgit
941s ++ tee /tmp/autopkgtest-lxc.3j70k01o/downtmp/autopkgtest_tmp/dgit.1.txt-errs
941s <standard input>:46: warning: table wider than line length minus indentation
[...]
941s RE (?^:^(?:(?^:^(?=a)b))$)|(?^:^(?:ERROR.*)$)|(?^:^(?:.* # table wider than line width)$)
941s unexpected: <standard input>:46: warning: table wider than line length minus indentation
941s unexpected errors
941s END failed--call queue aborted, <> line 1.
[...]
941s %%%%%%%%%%%%%%%%%%%% EXITING 22 %%%%%%%%%%%%%%%%%%%%
[...]
941s TEST FAILED
[...]
2435s manpages-format      FAIL non-zero exit status 16

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.

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.

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.

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?

$ MANPAGER=cat MANWIDTH=80 command man --warnings dgit |wc -L
<standard input>:46: warning: table wider than line length minus indentation
79

Hence the warning.

groff 1.22.4 didn't used to throw this warning in this circumstance.

That was a bug.

https://savannah.gnu.org/bugs/index.php?61854

Now it does.

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 allows you to treat the Debian archive as if it were a git reposi-
       tory.   Conversely, it allows Debian to publish the source of its pack-
       ages as git branches, in a format which is directly useable by ordinary
       people.

       This is the command line reference.  Please read the tutorial(s):
       dgit-user(7)              for users: edit, build and share packages
       dgit-nmu-simple(7)        for DDs: do a straightforward NMU
       dgit-maint-native(7)      for maintainers of Debian-native packages
       dgit-maint-debrebase(7)   for maintainers: a pure-git rebasish workflow
       dgit-maint-merge(7)       for maintainers: a pure-git merging workflow
       dgit-maint-gbp(7)         for maintainers already using git-buildpackage
       dgit-sponsorship(7)       for sponsors and sponsored contributors
       dgit-downstream-dsc(7)    setting up dgit push for a new distro

       See dgit(7) for detailed information about the data model, common prob-
       lems likely to arise with certain kinds of package, etc.

OPERATIONS

Yup, if we look carefully, we can see that the word "git-buildpackage"
encroaches into the right margin.

My recommendation is a simple tweak to the table format, stealing one en
of column separation to make the table fit.

$ diff -u ./dgit.1.orig ./dgit.1
--- ./dgit.1.orig       2023-07-17 06:03:04.465368217 -0500
+++ ./dgit.1    2023-07-17 06:03:26.309288710 -0500
@@ -42,7 +42,7 @@
 This is the command line reference.
 Please read the tutorial(s):
 .TS
-lb l.
+lb2 l.
 dgit-user(7)   for users: edit, build and share packages
 dgit-nmu-simple(7)     for DDs: do a straightforward NMU
 dgit-maint-native(7)   for maintainers of Debian-native packages

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.

https://savannah.gnu.org/bugs/index.php?62471

Maybe it will happen for groff 1.24.

Regards,
Branden

Back to linux.debian.bugs.dist | Previous | Next — Next in thread | Find similar | Unroll thread

Thread

Bug#1041317: dgit: table too wide in man page, trashes autopkgtests "G. Branden Robinson" <g.branden.robinson@gmail.com> - 2023-07-17 13:30 +0200
  Bug#1041317: dgit: table too wide in man page, trashes autopkgtests Colin Watson <cjwatson@debian.org> - 2023-07-17 14:20 +0200
  Bug#1041317: dgit: table too wide in man page, trashes autopkgtests Ian Jackson <ijackson@chiark.greenend.org.uk> - 2023-07-17 15:40 +0200

csiph-web