Skip navigation links
4.4.1 Partitioning Document Content into Multiple Files »
Section Navigation      [Toggle]

4.4. General Document Organization

[+/-]

4.4.1. Partitioning Document Content into Multiple Files
4.4.2. Referring to Files in Other Directories
4.4.3. Content of Chapter Files
4.4.4. Entities and Entity Files

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.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  <!ENTITY % all.entities SYSTEM "all-entities.ent">
  %all.entities;
]>
<book id="top" lang="en">

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

  <bookinfo>

    <abstract>

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

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

    </abstract>

    <xi:include href="legalnotice.en.xml"
      xmlns:xi="http://www.w3.org/2001/XInclude"/>

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

  </bookinfo>

  ... document content goes here; chapters, sections, etc. ...

  <index/>

</book>

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 via 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.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<legalnotice>

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

  <para>
    Copyright 2007-2008 MySQL AB, 2009 Sun Microsystems, Inc.
  </para>

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

  <para role="legalnotice-gpl">
    Copyright 2007-2008 MySQL AB, 2009 Sun Microsystems, Inc.
  </para>

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

  <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
    of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
    General Public License for more details.
  </para>

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

  <para role="legalnotice-all">
    For more information on the terms of this license, for details on
    how the MySQL documentation is built and produced, or if you are
    interested in doing a translation, please contact the
    <ulink url="http://www.mysql.com/company/contact/">Documentation
    Team</ulink>.
  </para>

</legalnotice>

    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: 

    <releaseinfo>
  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
  2006</emphasis>
</releaseinfo>

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.