MySQL Bugs: #24788: mysql manpage contains improperly formatted paragraph

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

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.

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!

Thank you for the bug report. Verified on 5.0.27 package.

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/?

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!

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.

Don't mean to nag, but any news?

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.

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!

I don't think it's fixable. As far as I can see, it looks like
a bug in tbl/groff.

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.