Bug #51554 manpages for client tools are incomplete
Submitted: 26 Feb 2010 14:06 Modified: 21 Mar 2014 13:29
Reporter: Axel Schwenke Email Updates:
Status: Closed Impact on me:
None 
Category:MySQL Server: Documentation Severity:S3 (Non-critical)
Version:5.1.42 OS:Any
Assigned to: Paul DuBois CPU Architecture:Any

[26 Feb 2010 14:06] Axel Schwenke
Description:
The UNIX manpages for the client tools (mysql, mysqldump, etc.) don't mention the --defaults-file option or any other details about option file handling.

How to repeat:
man mysql ; then search for "--defaults-file"

Suggested fix:
Looks like the manpages are automagically created from the XML docs. The chapter about option files was forgotten to get included there.
[26 Feb 2010 19:04] Paul DuBois
This is not specific to man pages. No format for mysql, mysqldump, mentions these options. Instead, we have language like this:

mysql supports the following options, which can be specified on the command line or in the [mysql] and [client] option file groups. mysql also supports the options for processing option files described at Section 4.2.3.3.1, “Command-Line Options that Affect Option-File Handling”.
[26 Feb 2010 19:05] Paul DuBois
"The chapter about option files was forgotten to get included there."

Could you clarify what is the meaning of "there" in this sentence?
[27 Feb 2010 7:31] Axel Schwenke
Hi Paul,

The online manual is hypertext and so it is natural and common to use a hyperlink to shared parts of the documentation - such as handling of option files, that is the same for all our programs.

UNIX manpages however should be selfcontained. Certainly they should list *all* command line options that are supported by a certain program.

It is however common practise to split out manpages that describe configuration files, mostly because there is an extra manual section (5) for config files. This is then mentioned explicitly in the manpage and the related manpages are listed in the SEE ALSO section of the manpage.

Look at the ssh manpage for an example.

What should be done for the MySQL manpages:

- split out an extra manpage describing the format and use of MySQL option files. This could be named mysql_config and should go to section 5. This manpage then *must* be mentioned in the SEE ALSO section of all appropriate tool manpages as mysql_config(5). It should also be mentioned in the appropriate places in the manpage text.

- the common file names for option files should be mentioned in a FILES section in the manpage. The bare minimum would be a FILES section pointing to mysql_options(5)

- preferrably the common command line options for handling option files should be duplicated in the tools manpage. This follows our communication pragma: put the burden on the writer, not the reader.

- alternatively the option file specific command line options could go to the mysql_options(5) manpage, but must then be clearly announced in the OPTIONS section of the manpage. Currently there is an obscure reference to the online manual: "... the options for processing them described at Section 4.2.3.3.1, “Command-Line Options that Affect Option-File Handling”." This is completely inappropriate in a UNIX manpage.

The format and contents on a UNIX manpage are formalized quite strictly. I did not find a standards document, but http://www.faqs.org/docs/Linux-mini/Man-Page.html provides some overview.

I appreciate that we have real manpages now (not just a pointer to the online manual). But then we should comply with the standards for such manpages.
[21 Mar 2014 13:29] 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.

Added these options:
--defaults-extra-file
--defaults-file
--defaults-group-suffix
--no-defaults
--print-defaults

as applicable to:
mysql
mysqladmin
mysqlbinlog
mysqlcheck
mysqld
mysqldump
mysqlimport
mysqlshow
mysqlslap
mysqltest
mysql_install_db
mysql_plugin
[21 Mar 2014 21:39] Paul DuBois
Ditto for mysql_upgrade and (in 5.7) mysql_secure_installation.