2.2.1 How HTML is Produced

You can convert DocBook XML to HTML directly using a XSL stylesheet. The stylesheet converts elements from the DocBook XML, such as a <para> into HTML equivalents, in this case <p>. We support a number of different HTML output formats that split up documentation into separate (chunked) files.

These different formats are available through the same make interface by using the following targets:

  • make document.html: Converts the source document into a single HTML file.

  • make document.html-dir: Converts the source document into a single HTML file, placing the HTML file and any required images into a directory named document.html-dir.

  • make document.html-chapter: Converts the source document into HTML, creating a separate file for each chapter or appendix. The files are created in the directory document.html-chapter, and all the required images are copied into the directory.

  • make document.html-section: Converts the source document into HTML, creating a separate file for each section within the manual. The result is a higher number of files, but because each is smaller, they are quicker to load. The HTML files and required images are placed into the directory document.html-section.

  • make document.html-web: Converts the source document into HTML section by section, like the html-section target, but this option prepends each file with a block of PHP code which is used by MySQL when the manual is placed on the MySQL website. The files generated by this process are not usable outside of MySQL, but you may find the principles of the process useful.

You can see a sample of the process of converting to an HTML section-based format below:

In addition to the stages shown above common to all documents, making HTML in this way performs the following:

For both the online (web) and file-based HTML targets a CSS stylesheet us used to format the output for display. The CSS stylesheet used is located in xsl.d/mysql-html.css. For the directory-based formats this file is automatically copied into the directory as part of the package.