Bug #45484 mysqldump man page warnings: can't break line
Submitted: 13 Jun 2009 22:26 Modified: 15 Jul 2009 16:50
Reporter: Dan Jacobson Email Updates:
Status: Closed Impact on me:
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:5.1.34, 5.0.83, 5.1.36 OS:Linux
Assigned to: Paul DuBois CPU Architecture:Any
Tags: Contribution, regression

[13 Jun 2009 22:26] Dan Jacobson
The mysqldump man page will produce

<standard input>:1039: warning [p 9, 6.7i, div `3tbd2,1', 0.2i]: can't break line
<standard input>:1045: warning [p 9, 6.7i, div `3tbd3,1', 0.2i]: can't break line

due to

  1038  <field
  1039                      name="\fIcolumn_name\fR"></field>
  1040  T}
  1041  T{
  1042  \'NULL' (\fIstring value\fR)
  1043  T}:T{
  1044  <field
  1045                      name="\fIcolumn_name\fR">NULL</field>

How to repeat:
# su - nobody #for a pristine environment
nobody@jidanni2:/$ man mysqldump > /dev/null
<standard input>:1039: warning [p 9, 6.7i, div `3tbd2,1', 0.2i]: can't break line
<standard input>:1045: warning [p 9, 6.7i, div `3tbd3,1', 0.2i]: can't break line
nobody@jidanni2:/$ apt-cache policy man-db
  Installed: 2.5.5-2
  Candidate: 2.5.5-2
  Version table:
 *** 2.5.5-2 0
        500 http://ftp.tw.debian.org unstable/main Packages
        100 /var/lib/dpkg/status
[15 Jun 2009 7:03] Sveta Smirnova
Thank you for the report.

Which version of MySQL do you use?
[17 Jun 2009 6:05] Dan Jacobson
$ man -w mysqldump|xargs dlocate
mysql-client-5.1: /usr/share/man/man1/mysqldump.1.gz
$ apt-cache policy mysql-client-5.1
  Installed: 5.1.34-1
  Candidate: 5.1.34-1
  Version table:
 *** 5.1.34-1 0
        990 http://ftp.tw.debian.org experimental/main Packages
        100 /var/lib/dpkg/status
[17 Jun 2009 6:38] Sveta Smirnova
Thank you for the feedback.

I assume this is Debian package. Please also try with our packages which are available from http://dev.mysql.com/downloads as I can not repeat described behavior in my environment:

ssmirnova@host ~
$ man -M /users/ssmirnova/mysql-5.1.34-linux-i686-glibc23/man mysqldump >/dev/null

ssmirnova@host ~
[17 Jun 2009 7:17] Dan Jacobson
OK, filed http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=533393
[17 Jun 2009 9:16] Sveta Smirnova
Thank you for the feedback.

Could you also please check in your environment with our binaries?

This also can be duplicate of Bug#45286 fixed in version 5.1.36 (which is not released yet), but in this case strange why I can not repeat it with 5.1.34:

ssmirnova@host ~
$echo $COLUMNS

ssmirnova@host ~
$man -M /users/ssmirnova/mysql-5.1.34-linux-i686-glibc23/man mysqldump >/dev/null

ssmirnova@host ~
[18 Jun 2009 0:21] Dan Jacobson
On http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=533393 they say the
problem it is in the man page. If you give me the exact URL of the man
page source, or mail it to me, I can test. You see
"http://dev.mysql.com/downloads" is to big for me to dig it out of.
[18 Jun 2009 9:20] Sveta Smirnova
mysqldump.1 from 5.1.34 package

Attachment: mysqldump.1 (application/octet-stream, text), 35.17 KiB.

[18 Jun 2009 9:21] Sveta Smirnova
Please find mysqldump.1 from package 5.1.34 attached.
[18 Jun 2009 19:43] Dan Jacobson
Now there are three errors:
# su - nobody
nobody@jidanni2:/$ cd /tmp
nobody@jidanni2:/tmp$ wget -O m.1 http://bugs.mysql.com/file.php?id=12300
nobody@jidanni2:/tmp$ man ./m.1 > /dev/null
<standard input>:1033: warning [p 10, 10.8i, div `3tbd1,1', 0.2i]: can't break line
<standard input>:1039: warning [p 10, 10.8i, div `3tbd2,1', 0.2i]: can't break line
<standard input>:1045: warning [p 10, 10.8i, div `3tbd3,1', 0.2i]: can't break line
[20 Jun 2009 11:39] Sveta Smirnova
mysqldump.1 from 5.1.36 package

Attachment: mysqldump.1 (application/octet-stream, text), 35.47 KiB.

[20 Jun 2009 11:40] Sveta Smirnova
Thank you for the feedback.

Please also try just uploaded man page from 5.1.36 package to check if fix of bug #45286 fixed this problem too.
[20 Jun 2009 19:06] Dan Jacobson
# su - nobody
$ cd /tmp
$ wget -O n.1 http://bugs.mysql.com/file.php?id=12315
$ man ./n.1 > /dev/null
<standard input>:1046: warning [p 9, 8.0i, div `3tbd2,1', 0.2i]: can't break line
<standard input>:1052: warning [p 9, 8.0i, div `3tbd3,1', 0.2i]: can't break line
$ man -l - < n.1 > /dev/null
<standard input>:1040: warning [p 11, 1.0i, div `3tbd1,1', 0.2i]: can't break line
<standard input>:1046: warning [p 11, 1.0i, div `3tbd2,1', 0.2i]: can't break line
<standard input>:1052: warning [p 11, 1.0i, div `3tbd3,1', 0.2i]: can't break line
Odd how I can get two OR three errors. I'll CC
[30 Jun 2009 9:55] Sveta Smirnova
Thank you for the feedback.

We still can not repeat described behavior. Which version of man and troff do you use?
[30 Jun 2009 19:49] Dan Jacobson
(You can see more details on http://packages.debian.org/sid/man-db
$ reportbug --template man-db
Package: man-db
Version: 2.5.5-2
-- System Information:
Debian Release: squeeze/sid
  APT prefers experimental
  APT policy: (990, 'experimental'), (500, 'unstable')
Architecture: i386 (i686)

Kernel: Linux 2.6.30-rc8-686 (SMP w/1 CPU core)
Locale: LANG=C, LC_CTYPE=C (charmap=ANSI_X3.4-1968)

Versions of packages man-db depends on:
ii  bsdmainutils           6.1.10            collection of more utilities from 
ii  debconf [debconf-2.0]  1.5.26            Debian configuration management sy
ii  dpkg                   1.15.3            Debian package management system
ii  groff-base          GNU troff text-formatting system (
ii  libc6                  2.9-18            GNU C Library: Shared libraries
ii  libgdbm3               1.8.3-4           GNU dbm database routines (runtime
ii  zlib1g                 1: compression library - runtime

Versions of packages man-db suggests:
ii  groff               GNU troff text-formatting system
ii  iceweasel [www-browser]      3.0.11-1    lightweight web browser based on M
ii  less                         429-2       pager program similar to more
ii  lynx-cur [www-browser]       2.8.7pre6-1 Text-mode WWW Browser with NLS sup
ii  midori [www-browser]         0.1.7-1     fast, lightweight graphical web br
ii  w3m [www-browser]            0.5.2-2+b1  WWW browsable pager with excellent
[4 Jul 2009 19:32] Dan Jacobson
Also happens for mysqlbinlog
$ man mysqlbinlog > /dev/null
<standard input>:673: warning [p 6, 2.7i, div `3tbd3,2', 0.7i]: can't break line
<standard input>:843: warning [p 6, 2.7i, div `3tbd25,2', 0.3i]: can't break line
<standard input>:895: warning [p 7, 1.3i, div `3tbd1,2', 0.3i]: can't break line
<standard input>:898: warning [p 7, 1.3i, div `3tbd1,2', 1.5i]: can't break line
[7 Jul 2009 7:35] Sveta Smirnova
Thank you for the feedback.

Verified as described. Bug is only repeatable on Debian, so problem still can be Debian man.
[7 Jul 2009 7:36] Sveta Smirnova
Problem does not exists in version 4.1
[8 Jul 2009 0:06] Colin Watson
Hi, I'm the maintainer of the Debian groff and man-db packages.

You may not see the *warnings* on other platforms, but this is an uninteresting detail; the warnings essentially just mean "this page is too wide for an 80-column terminal". Look at the line numbers identified in the warning messages and you'll see that they're wide table rows, such as:

          |NULL (unknown value)  | <field name="column_name"                           |
          |                      |                     xsi:nil="true"                  |
          |                      | />                                                  |

I don't know if this bug tracking system will preserve the formatting, but take my word for it - this looks really ugly (wrapped) in a conventional 80-column terminal, and so the page should try to do better. The simplest workaround I can see is, instead of all those leading spaces on the line after each "<field ...", to use \: to tell groff about zero-width break points (otherwise it doesn't know that it's sensible to break between XML ">" and "<"). \: is a groff extension but IIRC it will just silently do nothing on AT&T troff, which I think should wrap the table cells insignificantly worse than before.

I'll attach a diff implementing this against the mysqldump.1 file that Dan Jacobson provided. The resulting table looks like this, which is much more readable, and it looks slightly better in troff mode (e.g. PostScript output) too:

          |Value:                | XML Representation:        |
          |NULL (unknown value)  | <field name="column_name"  |
          |                      | xsi:nil="true" />          |
          |´’ (empty string)     | <field name="column_name"> |
          |                      | </field>                   |
          |´NULL’ (string value) | <field name="column_name"> |
          |                      | NULL</field>               |
[8 Jul 2009 0:07] Colin Watson
example fix

Attachment: mysqldump.1.diff (text/x-diff), 619 bytes.

[9 Jul 2009 16:50] Paul DuBois
The man pages are produced by running the DocBook source through the DocBook XSL stylesheets, which we do not maintain. This might be a good issue to report to the maintainers of those stylesheets, however:

[11 Jul 2009 19:54] Dan Jacobson
OK, I reported

Please be sure to subscribe to it, as I am only an innocent 3rd party.
[12 Jul 2009 0:02] Paul DuBois
Dan, thanks.
[14 Jul 2009 8:48] Dan Jacobson
https://sourceforge.net/tracker/?func=detail&atid=373747&aid=2820144&group_id=21935 is now asking for your (MySQL Corp.) answers to some questions!
[14 Jul 2009 8:52] Sveta Smirnova

please answer DocBook's question. Thanks in advance.
[14 Jul 2009 17:18] Paul DuBois
Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly, and will be included in the next release of the relevant products.

After further investigation, I think the source of the problem is that <entry> is subject to "pernicious mixed content." By wrapping the affected cell within <para> tags, better word wrapping occurs and improves the man page output.

Dan, I think you can tell the DocBook folks that they can close the bug on the other site.
[15 Jul 2009 16:50] Dan Jacobson
OK I told them to close the bug.