Skip navigation links
4.11.2 Help Tag Markup »
Section Navigation      [Toggle]

4.11.1. Markup for Unix Man Pages

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.

Note

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 <refentry> elements. One problem with using <refentry> is that the DocBook DTD prohibits <refentry> and <section> from appearing at the same level within a document if the document is to be considered valid. To work around this, we wrap <refentry> elements within “fake” <section> elements so that the source refman files pass validation. For output generation, we strip off these fake element tags, and then either pass through the <refentry> elements unchanged (for man page output), or map them onto regular <section> elements (for all other output formats).

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 <refsection> element per <refentry>. By convention, the first should be titled “Description”. If there are further subdivisions to be made, those should also be marked up as <refsection> elements. It is permissible to nest <refsection> elements.

Here is a prototype for a manual section that generates a man page: 

<section id="fake-id-for-PROGNAME-manpage-section-wrapper">

  <title>fake title for PROGNAME man page section wrapper</title>

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

</section>

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 example, mysql_config becomes mysql-config.

  • VOLNUM = Unix man page “volume” number

    Most of our man pages are part of volume 1. The mysqld and mysqlmanager man pages are in volume 8.

  • PURPOSE-FOR-TITLE, 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 PURPOSE-FOR-MANPAGE.

    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 PURPOSE-FOR-TITLE.

    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 output. The <refmiscinfo> element does not allow much internal markup. In particular, <literal> and <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 myisamchk.1 that contains the man page contents, and another “stub” file named isamchk.1 that contains a .so directive that simply includes the other page: 

    .so man1/myisamchk.1

  • 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

    The <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 generate 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 of <refentry> handling to be done is handled by setting the value of the $map.refentry.to.section parameter. See the comments in dbk-prep.xsl for more information.

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:

  • A SEE ALSO section that names every other man page and provides the URL to the online Reference Manual.

  • An AUTHOR section that names MySQL AB and indicates that the software comes with no warranty.

For the 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.