svn commit - mysqldoc@docsrva: r7864 - trunk/mysqldoc-guide

[mcbrown]

Author: mcbrown
Date: 2007-09-14 18:47:17 +0200 (Fri, 14 Sep 2007)
New Revision: 7864

Log:
Commiting the final version of the public mysqldoc-guide document, which now includes the
style and formatting guides



Modified:
   trunk/mysqldoc-guide/Makefile
   trunk/mysqldoc-guide/fg.xml
   trunk/mysqldoc-guide/formats.xml
   trunk/mysqldoc-guide/mysqldoc-guide.xml
   trunk/mysqldoc-guide/sg.xml
   trunk/mysqldoc-guide/styleguide.xml
   trunk/mysqldoc-guide/tools.xml


Modified: trunk/mysqldoc-guide/Makefile
===================================================================
--- trunk/mysqldoc-guide/Makefile	2007-09-14 16:12:36 UTC (rev 7863)
+++ trunk/mysqldoc-guide/Makefile	2007-09-14 16:47:17 UTC (rev 7864)
Changed blocks: 1, Lines Added: 1, Lines Deleted: 0; 545 bytes

@@ -51,6 +51,7 @@
 # xml-html for single-page HTML output with no images
 # xml-html-dir for single-page HTML output that also has images
 include $(MAKE_DIR)/xml-html
+include $(MAKE_DIR)/xml-eclipse
 include $(MAKE_DIR)/xml-html-dir
 include $(MAKE_DIR)/xml-html-section
 include $(MAKE_DIR)/xml-html-chapter


Modified: trunk/mysqldoc-guide/fg.xml
===================================================================
--- trunk/mysqldoc-guide/fg.xml	2007-09-14 16:12:36 UTC (rev 7863)
+++ trunk/mysqldoc-guide/fg.xml	2007-09-14 16:47:17 UTC (rev 7864)
Changed blocks: 2, Lines Added: 9, Lines Deleted: 1; 830 bytes

@@ -14,7 +14,9 @@
     <abstract>
 
       <para>
-      This guide details how to write proper DocBook XML, primarily for use with the
MySQL DocBook sources used for the MySQL manual. 
+        This guide details how to write proper DocBook XML, primarily
+        for use with the MySQL DocBook sources used for the MySQL
+        manual.
       </para>
 
       <para>

@@ -32,11 +34,17 @@
   </bookinfo>
 
 <!--SRCFILE fg-->
+
 <!--SRCFILE fg-introduction-->
+
 <!--SRCFILE fg-ids-->
+
 <!--SRCFILE fg-structure-links-->
+
 <!--SRCFILE fg-quotes-->
+
 <!--SRCFILE fg-elements-->
+
 <!--SRCFILE fg-graphics-->
 
 </book>


Modified: trunk/mysqldoc-guide/formats.xml
===================================================================
--- trunk/mysqldoc-guide/formats.xml	2007-09-14 16:12:36 UTC (rev 7863)
+++ trunk/mysqldoc-guide/formats.xml	2007-09-14 16:47:17 UTC (rev 7864)
Changed blocks: 3, Lines Added: 129, Lines Deleted: 3; 6376 bytes

@@ -9,6 +9,32 @@
 
   <title>Building Documentation Formats</title>
 
+  <para>
+    The MySQL documentation can be built into a variety of different
+    formats. The same mechanism and toolset is used to both build the
+    documentation and build any additional files or validation steps
+    relating to the documentation.
+  </para>
+
+  <para>
+    For information on how to build the MySQL documentation to a variety
+    of formats, see <xref linkend="mysqldoc-guide-formats-building"/>.
+  </para>
+
+  <para>
+    For details on what goes on behind the scenes when you build a
+    particular target format, see
+    <xref linkend="mysqldoc-guide-formats-processes"/>.
+  </para>
+
+  <para>
+    Information on other targets, including processes that build, check
+    and validate the documentation to ensure that it is ready to be
+    built, see
+    <xref
+    linkend="mysqldoc-guide-formats-othertargets"/>.
+  </para>
+
   <section id="mysqldoc-guide-formats-building">
 
     <title>How to Build MySQL Documentation</title>

@@ -309,14 +335,34 @@
         by the document.
       </para>
 
+      <para>
+        The same basic process is used for all the packaged HTML
+        formats, including Zip, Tar/GZip and RPM builds. The same output
+        files are used in each case, so that the build produces one set
+        of files that are packaged up multiple times.
+      </para>
+
     </section>
 
     <section id="mysqldoc-guide-formats-processes-eclipse">
 
       <title>How Eclipse Packages are produced</title>
 
-      <para></para>
+      <para>
+        The DocBook XSL stylesheets contain a specialized output target
+        for the Eclipse Packages. Eclipse documentation is essentially
+        HTML documentation packaged up with a suitable Eclipse
+        <filename>plugin.xml</filename> file so that the extracted
+        directory can be dropped onto the users
+        <filename>plugins</filename> directory.
+      </para>
 
+      <para>
+        The plugin registers the <literal>toc.html</literal> file as the
+        root of the MySQL documentation, and adds the name and title of
+        the documentation (and version) to the plugin details.
+      </para>
+
     </section>
 
     <section id="mysqldoc-guide-formats-processes-pdf">

@@ -405,16 +451,96 @@
 
       <title>How CHM is produced</title>
 
-      <para></para>
+      <para>
+        The Compiled HTML (CHM) format was developed by Microsoft as a
+        solution to the problem of distributing an online viewable
+        version of documentation as a convenient single file.
+      </para>
 
+      <para>
+        At the core, CHM is just HTML, but some additional files are
+        produced during the build process to generate a suitable table
+        of contents and index file that can be indexed and updated so
+        make browsing and searching the CHM content easier.
+      </para>
+
+      <para>
+        The core of the CHM process is therefore a suite a XSL
+        stylesheets that generated the HTML and the associated TOC and
+        index files required by the CHM standard. This process can be
+        run on any machine.
+      </para>
+
+      <para>
+        To actually produce a CHM file, you need to use a Windows only
+        application called HTMLHelp that compiles (and compresses) the
+        individual HTML files and the table of contents/index files into
+        the CHM file.
+      </para>
+
+      <para>
+        It is difficult to build the files directly on Windows. At MySQL
+        we use a combination of assembly of the core files on a Unix
+        system and a conversion of that source XML file and the source
+        images on a Windows system to produce the CHM. The Windows
+        system uses <command>xsltproc</command> to create the HTML files
+        and the associated table of contents and index files, and
+        <command>htmlhelp</command> to create the final CHM.
+      </para>
+
     </section>
 
     <section id="mysqldoc-guide-formats-processes-texinfo">
 
       <title>How Tex/Texinfo is produced</title>
 
-      <para></para>
+      <para>
+        The info format is supported by Emacs and many other tools as a
+        method for browsing large and small documents. Individual
+        chapters and sections are converted into nodes within the info
+        document.
+      </para>
 
+      <para>
+        The info format is produced by calling
+        <command>makeinfo</command> on the
<literal>texi</literal> file.
+        The <literal>texi</literal> can be produced directly from the
+        DocBook file format using the XSL stylesheets.
+      </para>
+
+      <para>
+        To build the info file, use the <literal>info</literal> target:
+      </para>
+
+<programlisting>$ make manual.info
+XML_CATALOG_FILES="/MySQLData/Docs/mysqldoc/trunk/catalog.xml" xsltproc --xinclude
--novalid  \
+                --stringparam repository.revision "`../tools/get-svn-revision`" \
+                --param map.remark.to.para 0 \
+                --stringparam qandaset.style "" \
+                ../xsl.d/dbk-prep.xsl manual.xml > manual-prepped.xml.tmp2
+../tools/bug-prep.pl &lt; manual-prepped.xml.tmp2 > manual-prepped.xml.tmp
+../tools/idremap.pl  --srcpath=". ../refman-common ../falcon ../ndbapi"
manual-prepped.xml.tmp > manual-prepped.xml.tmp2
+mv manual-prepped.xml.tmp2 manual-prepped.xml
+rm -f manual-prepped.xml.tmp
+XML_CATALOG_FILES="/MySQLData/Docs/mysqldoc/trunk/catalog.xml" xsltproc --xinclude
--novalid   \
+                --stringparam l10n.gentext.default.language en \
+                ../xsl.d/dbk-texi.xsl manual-prepped.xml > manual.texi.tmp
+WARNING: FOUND 'REGISTERED' SYMBOL
+WARNING: FOUND 'REGISTERED' SYMBOL
+WARNING: FOUND 'REGISTERED' SYMBOL
+WARNING: FOUND 'REGISTERED' SYMBOL
+../tools/fixup-texi.pl manual.texi.tmp > manual.texi.tmp2
+rm -f manual.texi.tmp
+mv manual.texi.tmp2 manual.texi
+makeinfo --no-split -I . manual.texi</programlisting>
+
+      <para>
+        Note that during the process we correct some problems in the
+        <filename>texi</filename> output before it is processed that are
+        known are to cause problems when the file is converted to info
+        format.
+      </para>
+
     </section>
 
   </section>


Modified: trunk/mysqldoc-guide/mysqldoc-guide.xml
===================================================================
--- trunk/mysqldoc-guide/mysqldoc-guide.xml	2007-09-14 16:12:36 UTC (rev 7863)
+++ trunk/mysqldoc-guide/mysqldoc-guide.xml	2007-09-14 16:47:17 UTC (rev 7864)
Changed blocks: 2, Lines Added: 2, Lines Deleted: 4; 657 bytes

@@ -14,8 +14,8 @@
     <abstract>
 
       <para>
-        [OPTIONAL HIGH-LEVEL DESCRIPTION OF DOCUMENT; edit or remove
-        this para]
+        This document describes the machinery, format and operationof
+        the MySQL documentation.
       </para>
 
       <para>

@@ -43,6 +43,4 @@
 
   <xi:include href="styleguide.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
 
-  <index/>
-
 </book>


Modified: trunk/mysqldoc-guide/sg.xml
===================================================================
--- trunk/mysqldoc-guide/sg.xml	2007-09-14 16:12:36 UTC (rev 7863)
+++ trunk/mysqldoc-guide/sg.xml	2007-09-14 16:47:17 UTC (rev 7864)
Changed blocks: 2, Lines Added: 8, Lines Deleted: 1; 752 bytes

@@ -14,7 +14,8 @@
     <abstract>
 
       <para>
-      This guide details the conventions and writing guidelines for writing MySQL
documentation. 
+        This guide details the conventions and writing guidelines for
+        writing MySQL documentation.
       </para>
 
       <para>

@@ -32,11 +33,17 @@
   </bookinfo>
 
 <!--SRCFILE sg-principles-->
+
 <!--SRCFILE sg-numbering-->
+
 <!--SRCFILE sg-capitilzation-->
+
 <!--SRCFILE sg-names-->
+
 <!--SRCFILE sg-grammar-->
+
 <!--SRCFILE sg-spelling-->
+
 <!--SRCFILE sg-gui-->
 
 </book>


Modified: trunk/mysqldoc-guide/styleguide.xml
===================================================================
--- trunk/mysqldoc-guide/styleguide.xml	2007-09-14 16:12:36 UTC (rev 7863)
+++ trunk/mysqldoc-guide/styleguide.xml	2007-09-14 16:47:17 UTC (rev 7864)
Changed blocks: 1, Lines Added: 1, Lines Deleted: 0; 438 bytes

@@ -1242,6 +1242,7 @@
           100Mb/s to mean 100 megabits per second.
         </para>
       </listitem>
+
       <listitem>
         <para>
           administer, not administrate


Modified: trunk/mysqldoc-guide/tools.xml
===================================================================
--- trunk/mysqldoc-guide/tools.xml	2007-09-14 16:12:36 UTC (rev 7863)
+++ trunk/mysqldoc-guide/tools.xml	2007-09-14 16:47:17 UTC (rev 7864)
Changed blocks: 1, Lines Added: 121, Lines Deleted: 1; 4511 bytes

@@ -9,15 +9,135 @@
 
   <title>Documentation Tools</title>
 
+  <para>
+    In addition to the tools used to actually build and convert
+    documentation into the various target formats, a number of
+    additional tools and utilities have been developed that aid the
+    build and production of documentation. Some of these tools relate to
+    the build process and provide additional functionality or
+    formatting. Others are used to aid in the validation.
+  </para>
+
+  <para>
+    For example, <command>deepcheck.pl</command> parses the DocBook XML
+    file and looks for
+  </para>
+
+  <para>
+    In this chapter we will look at some of the key tools that make up
+    the documentation utilities.
+  </para>
+
   <section id="mysqldoc-guide-tools-deepcheck">
 
     <title>Deep Checker</title>
 
     <para>
       The Deep Checker script (<command>deep-check.pl</command>)
-      provides additional validation on DocBook XML files.
+      provides additional validation on DocBook XML files. Standard
+      validation is provided through the <literal>valid</literal> target
+      on a document. However, this validation is limited to ensuring
+      that the XML is valid XML, that all of the files included or
+      referred to (including image files) are available, and that the
+      different entities in the file can be parsed.
     </para>
 
+    <para>
+      The standard validation doesn't check whether the definitions of
+      the different elements are valid, or whether problems with
+      specific combinations of different DocBook sequences will cause
+      issues in certain target formats.
+    </para>
+
+    <para>
+      The Deep Checker script addresses these issues by parsing the
+      DocBook XML and then identifying different issues and reporting on
+      them. The script checks a for a variety of problems, including:
+    </para>
+
+    <itemizedlist>
+
+      <listitem>
+        <para>
+          Missing IDs on chapter and section elements.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Checks for duplicate IDs in a single file.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Checks the format and definition of tables (both
+          <literal>table</literal> and
+          <literal>informaltable</literal>). In particular, it checks:
+        </para>
+
+        <itemizedlist>
+
+          <listitem>
+            <para>
+              Compares the column definitions
+              (<literal>colspec</literal>), and the actual number of
+              columns defined in the table.
+            </para>
+          </listitem>
+
+          <listitem>
+            <para>
+              Calculates the specified width of the table and ensures
+              that it is not more than 100% of the width of page.
+            </para>
+          </listitem>
+
+        </itemizedlist>
+      </listitem>
+
+      <listitem>
+        <para>
+          Checks that specified images exist and that the image files
+          available on the filesystem and those specified match.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Checks the line length of <literal>programlisting</literal>
+          elements to highlight potential line wrap in PDF documents.
+          The line length can be configured on the command line.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          Checks for empty <literal>link</literal> references. A link
+          reference does not automatically populate the link text, so an
+          empty link produces a link with the link text as question
+          marks.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+          If you specifically request it, you can also check the
+          <literal>ulink</literal> elements, which point to standard
+          Internet URLs. The checking process accesses each URL and then
+          verifies whether the URL is still reachable.
+        </para>
+      </listitem>
+
+    </itemizedlist>
+
+    <para>
+      Errors reported by the Deep Checker script are reported in
+      relation to the section in which they appear. This enbles you to
+      identify more easily where a problem is within the DocBook XML
+      source.
+    </para>
+
   </section>
 
   <section id="mysqldoc-guide-tools-idmap">