Arbitrary Docs Machinery

[Stefan Hinz]

The MySQL documentation team has created a way that enables us to
extract arbitrary pieces of MySQL documentation and recombine them into
a new document. With that machinery for creating arbitrary docs, we
could, for example, do this:

* Bond the Cluster docs with the rest of the Storage Engines.
* Create a Cluster and Partitioning standalone guide.
* Collate all the Windows sections into a single document.
* Create a Connectors/APIs document where each of the current connector
  sections is a chapter in the new book.
* Put a section anywhere, and remap any section to any block (i.e.
  section to chapter or appendix, chapter to appendix, you name it).

Basically, we can combine excerpts from any documentation that can be
found on http://dev.mysql.com/doc.

The arbitrary docs machinery doesn't work in a copy-and-paste manner,
but rather by including blocks (chapters, appendices, or sections) of
the original documentation. This means that whenever the underlying
documentation changes the arbitrary docs will also change. (You may
have noticed that this concept is similar to views in a database.)

This is what our users can do with that machinery:

1. Look at our sample PDF file that demonstrates what can be done; it
   combines all Windows-related installation instructions from various
   docs files:
   http://svn.mysql.com/svnpublic/mysqldoc/arbitrary/windows-sample.pdf
2. Tell us (docs@stripped) which new excerpts or combinations of
   documents you'd like us to create and make available on
   http://dev.mysql.com/doc.
3. Create arbitrary docs yourself. For this, you can find everything
   you need in the public copy of our mysqldoc repository (viewable
   with any web browser) on
   http://svn.mysql.com/svnpublic/documentation.

To see how creating your own arbitrary documents works, try our sample
files:

1. Use Subversion (SVN) to pull a working copy of
   http://svn.mysql.com/svnpublic/mysqldoc.
2. You need an environment that has "make" and "xsltproc" installed
   (any Unix-like system, or Cygwin on Windows). To create PDF files,
   you also need "fop".
3. A sample arbitrary specification file (windows.aspec) and the
   necessary DocBook wrapper (windows.xml) are located in the
   "arbitrary" directory. A sample of the file generated from that
   specification is provided as windows-sample.pdf.
4. To generate HTML or PDF output for yourself:
   * Change to the upmost directory and run "make realclean" - this
     will clean out any old and temporary files.
   * Change to the "arbitrary" directory and run "make idmap.refs" -
     this will rebuild all the ID map reference files which are
     required for the arbitrary functionality.
   * Within "arbitrary", run "make windows-arbitrary.pdf" to make the
     PDF version, or "make windows-arbitrary.html" to create the HTML
     version.

Regards,

Stefan
-- 
Stefan Hinz <stefan@stripped>
MySQL AB Documentation Team Lead. Berlin, Germany (UTC +1:00)
Skype:stefanhinz Cell:[phone] Desk:[phone] Fax:[phone]