Bug #24788 mysql manpage contains improperly formatted paragraph
Submitted: 4 Dec 2006 9:08 Modified: 22 Feb 2007 18:09
Reporter: Rouben Tchakhmakhtchian Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:All OS:Any (All)
Assigned to: Paul DuBois CPU Architecture:Any

[4 Dec 2006 9:08] Rouben Tchakhmakhtchian
Description:
The man page for mysql, contains the following improperly formatted paragraph:
---SNIP---
       The default mysql> prompt can be
       reconfigured. The string for defining the
       prompt can contain the following special
       sequences: OptionDescription\vThe server
       version\dThe default database\hThe server
       host\pThe current TCP/IP port or socket
       file\uYour username\UYour full
                         user_name@host_name
                         account name\\A literal
       ‘\’ backslash character\nA newline
       character\tA tab character\ A space (a
       space follows the backslash)\_A
       space\RThe current time, in 24-hour
       military time (0-23)\rThe current time,
       standard 12-hour time (1-12)\mMinutes of
       the current time\yThe current year, two
       digits\YThe current year, four
       digits\DThe full current date\sSeconds of
       the current time\wThe current day of the
       week in three-letter format (Mon, Tue,
       ...)\Pam/pm\oThe current month in numeric
       format\OThe current month in three-letter
       format (Jan, Feb, ...)\cA counter that
       increments for each statement you
       issue\lThe current delimiter. (New in
       5.0.25)\SSemicolon\’Single quote\"Double
       quote.PP ‘\’ followed by any other letter
       just becomes that letter.
---SNIP---
This was successfully reproduced on several Linux distributions with official and unofficial MySQL packages for 4.x and 5.x releases.

How to repeat:
1. Issue command "man mysql"
2. Search for string "reconfigured".
3. Check the paragraph containing this string, you will see broken formatting.

Suggested fix:
Simply fix the manpage formatting in your documentation tree.
[4 Dec 2006 15:06] Lenz Grimmer
Verified on my SUSE Linux 10.2 System.

This bug was originally reported at https://launchpad.net/bugs/74349

The man pages are created out of the DocBook sources of the MySQL reference manual. Please assign to the Documentation Team. Thanks!
[4 Dec 2006 15:17] MySQL Verification Team
Thank you for the bug report. Verified on 5.0.27 package.
[7 Dec 2006 18:00] Paul DuBois
Seems to be a problem of the DocBook XSL stylesheets for manpage
output.  Can you try downloading a new set of manpages from
http://dev.mysql.com/doc/?
[10 Dec 2006 18:35] Rouben Tchakhmakhtchian
The issue originally reported has been fixed partially. Thank you very much! However, if I am not mistaken, you have introduced another issue, or perhaps it was there all along...

When I load up the mysql.1 manpage, I get the following warning message from right off the bat:
mysql.1:931: warning [p 8, 7.3i, div `3tbd25,1', 0.2i]: can't break line

Assuming that man is complaining about line 931, I looked it up in the file and discovered the following chunk of code (line 931 being the first indented line starting with "\fIuser_name"):
---SNIP---
Your username
T}
T{
\\U
T}:T{
Your full
                  \fIuser_name\fR@\fIhost_name\fR
                  account name
T}
T{
\\\\
T}:T{
---SNIP---

My guess is that man doesn't like this indent. Apparently this is just the aftermath of this cleanup, since the actual text generated by the code above looks somewhat out of what. The table that was messed up (original bug report) now sports the following row:
---SNIP---
       +---------------------+---------------------------------------+
       |\u                   | Your username                         |
       +---------------------+---------------------------------------+
       |\U                   | Your full                             |
       |                     |                   user_name@host_name |
       |                     |                   account             |
       |                     | name                                  |
       +---------------------+---------------------------------------+
       |\T}:T{ A literal ‘\’ |                                       |
       |backslash character  |                                       |
       +---------------------+---------------------------------------+
---SNIP---
Note that this is not due to my terminal being too narrow, I've tried resizing it. And besides, if that were the case the table borders would be all messed up as well.

Again, thanks for your attention and for your fix attempts!
[10 Dec 2006 22:54] Rouben Tchakhmakhtchian
The following is a more comprehensive report from Onno Benschop (https://launchpad.net/people/onno-itmaze) taken from https://launchpad.net/distros/ubuntu/+source/mysql-dfsg-5.0/+bug/74349

Thanks!
-------------------------------
On the standard console width I get the same error, but on a wider console I don't. The error seems to be where the text table is created and this source line seems to refer to the text: "The current TCP/IP port or"

The error I get is this:
    ./mysql.1:939: warning [p 8, 7.3i, div `3tbd25,1', 0.2i]: can't break line

Also, there appears to be a paragraph break missing at:
   Beginning with MySQL 5.1.12, the output when --xml ...

Under MYSQL COMMANDS, the charset, connect, delimiter and source commands each have a one-line explanation that does not wrap properly.

There may be a paragraph break or an indent missing here:
          mysql> pager cat > /tmp/log.txt
       You can also pass any options for the program that you want to use as
       your pager:

And here also:
          mysql> pager cat | tee /dr1/tmp/res.txt \
                    | tee /dr2/tmp/res2.txt | less -n -i -S
       In this example, the command would send query results to two files in

And here:
          [mysql]
          prompt=(\\u@\\h) [\\d]>\\_
       In this example, note that the backslashes are doubled. If you set the

Apart from that, it appears as if the original problem is resolved.
[15 Dec 2006 8:07] Rouben Tchakhmakhtchian
Don't mean to nag, but any news?
[15 Dec 2006 14:24] Paul DuBois
The original problem has been fixed. The additional problems
reported after that were there as well, but not listed in the
original report.  With one exception, these appear to be limitations
of the DocBook XSL transform that produces manpage format.
The exception is that this:

T{        
\\\\      
T}:T{     
A literal \(oq\\\(cq backslash character
T}        

Produces this:

       +---------------------+---------------------------------------+
       |\T}:T{ A literal ‘\’ |                                     
 |
       |backslash character  |                                       |
       +---------------------+---------------------------------------+

It's not clear to me why that should be.  \\\\ is legal and should produce
\\, not a \ followed by tbl markup.
[1 Jan 2007 10:08] Rouben Tchakhmakhtchian
Thanks for the comment, Paul. Are there any news on the "new" formatting issue? Given XSL limitations you mentioned, do you believe that the new issue is fixable?

P.S. Happy 2007!
[1 Jan 2007 15:56] Paul DuBois
I don't think it's fixable. As far as I can see, it looks like
a bug in tbl/groff.
[22 Feb 2007 18:09] Paul DuBois
I'm closing this bug report because the original issue
has been dealt with. Regarding the problem that occurs
with double backslashes at the end of lines in tables, I've
discussed this with the manpages XSL maintainer and we
both agree that it appears to be a groff bug. It's possible
that this could be dealt with by writing \ as \e in the output
rather than as \\. If that becomes a feature of the manpages
XSL, we'll look into using it.