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: | |
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
[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.