4.4 General Document Organization

MySQL documents vary somewhat in their structural characteristics, but the overall layout generally is similar to the following example. The document shown uses <book> and <bookinfo>, which is appropriate for a longer document. Shorter documents might use <article> and <articleinfo> instead.

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  <!ENTITY % all.entities SYSTEM "all-entities.ent">
<book id="top" lang="en">

  <title><replaceable>... document title ...</replaceable></title>



        <replaceable>... optional high-level description of document ...</replaceable>

        Document generated on:
        <?dbtimestamp format="Y-m-d"?>
        <remark role="repository.revision"/>


    <xi:include href="legalnotice.en.xml"

    <releaseinfo><replaceable>... disclaimer (for translations only) ...</replaceable></releaseinfo>


  <replaceable>... document content goes here; chapters, sections, etc. ...</replaceable>

  <index id="ix01"/>


The first line is the XML declaration, which indicates the character encoding. This is almost always utf-8 for document files. Exceptions might occur for files containing licensing text containing special characters in some other character set such as iso-8859-1.

The DOCTYPE declaration names the root element contained in the file and identifies the relevant DTD. If a document file needs to use entity references, those entities should be defined in the DOCTYPE declaration. Our convention is to place all definitions for the entities needed by the XML files in a given directory in a file named all-entities.ent. Then the DOCTYPE declaration for each XML file that needs entities defines and references the single entity file all-entities.ent. This makes the DOCTYPE declaration easier to write. Also, if the set of required entities changes, the change needs to be made only in all-entities.ent. For additional information about using entity files, see Section 4.4.4, “Entities and Entity Files”.

Each DocBook document has a root element and a title. For longer documents, the root element is <book>. For a shorter document, the root element might be <article>. The root element must be the same as specified in the DOCTYPE declaration. The opening tag of the root element should have an id attribute, and a lang attribute that indicates the document language.

Following the title, the document contains an info element that includes some standard elements. The info element is <bookinfo> if the root element is <book>, and <articleinfo> if the root element is <article>. The info element contains several parts:

  • An <abstract> element. The abstract includes an optional high-level description of the document and a paragraph containing special markup that causes the current date and repository revision number to be inserted when formatted output is generated from the document. The date and revision number are useful for determining how up to date a document is. For example, when you're looking at an online manual on dev.mysql.com, you can tell when changes that you have committed have propagated to that site by noting when the revision number changes. The special markup paragraph must be written exactly as shown, except that the amount of whitespace between its elements does not matter.

  • A legal notice that contains the copyright date and the conditions under which the document can be copied. This is a boilerplate file, so its content is stored in a separate file that is referenced through XInclude from the main document file. The legal notice file is named legalnotice.lang.xml, where lang is the code for the document language. An English legal notice file (legalnotice.en.xml) looks like this:

    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE legalnotice PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
      The role attribute for each top-level legalnotice element determines
      the context in which the element is used: 1) no role attribute: part
      of the default legalnotice, used for regular documentation that is
      not released under GPL; 2) role = legalnotice-gpl: for man page
      legalnotices, which are released under GPL; 3) role =
      legalnotice-all: included in legalnotice for all documentation.
        Copyright 2007-2008 MySQL AB, 2009 Sun Microsystems, Inc.
        This documentation is NOT distributed under a GPL license. Use of
        this documentation is subject to the following terms: You may create
        a printed copy of this documentation solely for your own personal
        use. Conversion to other formats is allowed as long as the actual
        content is not altered or edited in any way. You shall not publish
        or distribute this documentation in any form or on any media, except
        if you distribute the documentation in a manner similar to how MySQL
        disseminates it (that is, electronically for download on a Web site
        with the software) or on a CD-ROM or similar medium, provided
        however that the documentation is disseminated together with the
        software on the same medium. Any other use, such as any
        dissemination of printed copies or use of this documentation, in
        whole or in part, in another publication, requires the prior written
        consent from an authorized representative of MySQL AB. MySQL AB
        reserves any and all rights to this documentation not expressly
        granted above.
      <para role="legalnotice-gpl">
        Copyright 2007-2008 MySQL AB, 2009 Sun Microsystems, Inc.
      <para role="legalnotice-gpl">
        This documentation is free software; you can redistribute it and/or
        modify it only under the terms of the GNU General Public License as
        published by the Free Software Foundation; version 2 of the License.
      <para role="legalnotice-gpl">
        This documentation is distributed in the hope that it will be
        useful, but WITHOUT ANY WARRANTY; without even the implied warranty
        General Public License for more details.
      <para role="legalnotice-gpl">
        You should have received a copy of the GNU General Public License
        along with the program; if not, write to the Free Software
        Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
        02110-1301 USA or see http://www.gnu.org/licenses/.
      <para role="legalnotice-all">
        For more information on the terms of this license, or for details on
        how the MySQL documentation is built and produced, please visit
        <ulink url="http://dev.mysql.com/contact/">MySQL Contact &amp;

    Observe that the legal notice has text for different kinds of licenses. MySQL documentation is under copyright, so for most output formats we use the non-GPL text. The exception is that we release Unix man pages under the GPL to make it easier for organizations that produce GPL operating system distributions. These organizations often include MySQL, and having the man pages under GPL enables them to include some documention for the MySQL programs in the distribution.

    For MySQL Reference Manual documents, the legal notice also contains a paragraph pointing to the Preface, Notes, License section for additional licensing information. The preface.xml file then has subsections for a more complete copyright notice and for licensing terms of any third-party products used in MySQL that require their licensing to be reproduced in the documentation of any including products. The files for these subsection are found in the refman-common directory.

  • For translated documents, the info element includes a <releaseinfo> element. The content of this element is a disclaimer that points out that the translation is based on the English version but might not be as up to date. The German disclaimer for the MySQL 5.1 Reference Manual looks like this:

      Dies ist eine Übersetzung des MySQL-Referenzhandbuchs, das sich auf
      <ulink url="http://dev.mysql.com/doc/mysql/en">dev.mysql.com</ulink>
      befindet. Das ursprüngliche Referenzhandbuch ist auf Englisch,
      und diese Übersetzung ist nicht notwendigerweise so aktuell wie
      die englische Ausgabe. <emphasis role="bold">Das vorliegende
      deutschsprachige Handbuch behandelt MySQL bis zur Version 5.1. Es
      ist derzeit noch unvollständig (Teile sind noch nicht
      übersetzt). Geplanter Fertigstellungstermin: 30. Juni

Following the info element, write the document's content. This content can be written directly (inline) within the root element, or placed in other files and referenced from the main document file using XInclude directives. For more information about using multiple content files, see Section 4.4.1, “Partitioning Document Content into Multiple Files”.

If the document should have an index, place an <index/> element just before the root element closing tag. For the index to have any content, you must place <indexterm> elements at appropriate places within the document. As a matter of convention, the index element's id is set to "ix01", so use <index id="ix01"/>.