Some sections of the MySQL Reference Manual describe programs, such as the sections for mysql and mysqladmin. To avoid writing descriptions for the programs both in the manual and in separate Unix-style man pages (which are written using troff/groff markup), we generate man pages directly from the manual DocBook source. This strategy can be used for other documents as well (for example, the MySQL Test Framework Manual).
Formerly, MySQL distributions contained a set of handwritten man page files, but these were contributed by third parties and rarely were updated, so they became obsolete. Also, there were some programs for which no man pages had ever been written. By generating the man pages from the Reference Manual, we can keep them up to date easily, and we have a man page for every program described in the manual.
If the set of man pages generated from the manual changes, it's
necessary to let the build team know about it. (For example,
they need to update the
.spec files used for
the RPM distributions.) Examples of changes requiring
notification of the build team:
You mark up a new man page in the manual.
You change the “volume” for a man page. For example, mysqld(1) becomes mysqld(8).
You remove a section from which a man page formerly was created. For example, safe_mysqld is no longer present in MySQL 5.1.
The DocBook XSL stylesheets have a man page mode that can be used for generating man page output. The markup described here requires at least version 1.69.0 of the stylesheets, because man page support was improved markedly in that version, and we use features not supported in older versions.
The DocBook XSL stylesheets man page mode requires that man page
sections be marked up using
elements. One constraint on the use of
<refentry> is that the DocBook DTD
<section> from appearing at the same
level within a document if the document is to be considered valid.
Therefore, a section that contains
<refentry> children must contain only
<refentry> children. For output
generation, we either pass through the
<refentry> elements unchanged (for man
page output), or map them onto regular
<section> elements (for all other output
The following template shows how to mark up a section so that a
man page can be generated from it. The
<ref...> tags and their subelements
should be used in the order shown, because the DTD doesn't allow
much flexibility and variations from the order shown typically
result in validation errors.
There must be at least one
<refentry>. By convention,
the first should be titled “Description”. If there
are further subdivisions to be made, those should also be marked
<refsection> elements. It is
permissible to nest
Here is a prototype for a manual section that generates a man page:
<refentry id="PROGNAME"> <!-- initial index terms go here --> <refmeta> <refentrytitle>PROGNAME</refentrytitle> <manvolnum>VOLNUM</manvolnum> <refmiscinfo class="manual">MySQL Database System</refmiscinfo> <refmiscinfo class="source">MySQL</refmiscinfo> <refmiscinfo class="version">VERSION</refmiscinfo> <refmiscinfo class="refman">PURPOSE-FOR-TITLE</refmiscinfo> </refmeta> <refnamediv> <refname>PROGNAME</refname> <refpurpose>PURPOSE-FOR-MANPAGE</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>PROGNAME ARGUMENT-SYNTAX</command> </cmdsynopsis> </refsynopsisdiv> <refsection id="PROGNAME-description"> <title>Description</title> <para> Description of the program, how to use it, its allowable command-line options, and so forth. </para> </refsection> </refentry>
In the template, make the following substitutions:
PROGNAME = program name
If the program name occurs within an element attribute value,
underscores in the name should be written as dashes. For
VOLNUM = Unix man page
Most of our man pages are part of volume 1. The mysqld and mysqlmanager man pages are in volume 8.
PURPOSE-FOR-MANPAGE = short phrase
describing program purpose
The purpose string will appear with the program name in the output, but which of the two strings to use depends on the output format. Man pages typically begin with a name section that looks like this, where words in the description are not title-capped:
.SH "NAME" myprog \- a program for doing this and that
Here, “a program for doing this and that” is the
text to use for
In non-man page output, the name and description become a section title, so words in the description should be title-capped:
<title>myprog - A Program for Doing This and That<title>
Here, “A Program for Doing This and That” is the
text to use for
To accommodate both output formats, we include both
description strings in the man page markup. The title-capped
version is included using a
<refmiscinfo> element (with a
class attribute of
"refman") that does not appear in man page
does not allow much internal markup. In particular,
<command> are not allowed.
In some cases, a manual page describes more than one program.
For example, the same material in the MySQL 4.1
Reference Manual describes both
myisamchk and isamchk.
To handle this, include one
<refnamediv> element for each
program. The first such element should be for the primary
program described by the man page. For example:
<refnamediv> <refname>myisamchk</refname> <refpurpose>MyISAM table-maintenance utility</refpurpose> </refnamediv> <refnamediv> <refname>isamchk</refname> <refpurpose>ISAM table-maintenance utility</refpurpose> </refnamediv>
When the file is processed, the man page stylesheets will
produce a file named
contains the man page contents, and another
“stub” file named
that contains a
.so directive that simply
includes the other page:
VERSION = version of MySQL to which the
manual applies (4.1, 5.0, 5.1, and so forth)
If the document is unversioned, omit the version element.
ARGUMENT-SYNTAX = syntax for any arguments
that the program takes
<cmdsynopsis> value describes
program invocation syntax. It appears in the
SYNOPSIS section of man page output. It
does not appear in non-man page output.
Where the “initial index terms” comment appears,
you may add
<indexterm> elements for
index terms that apply to the program as a whole. Index terms
for specific features probably are better placed near the text
that describes the feature.
Output generation always begins with a preprocessing step. For
non-man page output from a source document
manual.xml, we generate
manual-prepped.xml, and then run that through
the appropriate DocBook XSL stylesheets. For man page output, we
manual-manprepped.xml, and run that
through the man page DocBook XSL stylesheets. The preprocessing in
both cases is done using the
xsl.d/dbk-prep.xsl transform, where the type
<refentry> handling to be done is
handled by setting the value of the
$map.refentry.to.section parameter. See the
dbk-prep.xsl for more
For man page generation, we also have a postprocessing step that acts on the set of mapages as a whole. The postprocessing script is tools/fixup-manpages.pl. For each man page file, it adds this information:
SEE ALSO section that names every
other man page and provides the URL to
the online Reference Manual.
AUTHOR section that names MySQL AB and
indicates that the software comes with no warranty.
SEE ALSO section to be generated
properly, fixup-manpages.pl must be invoked
with the names of all man pages as its
arguments. fixup-manpages.pl --help shows the
help message that describes the invocation syntax.