While the distributed, configurable nature of the Hackystat documentation is very nice in terms of scalability, it leads to a rather basic development process: (a) write a small amount of documentation, such as one <section>; (b) run "ant hackyCore_Build.buildDocBook" and look for errors; (c) debug your XML until there are no more errors; (d) go to (a).
This section describes a few hints and resolutions to some of the most common problems that occur to help your documentation writing process go as fast and as efficiently as possible.
First off, do not use the -q option to Ant when running the target hackyCore_Build.buildDocBook. It will omit some very important output that is useful to determine when you've made errors during development.
Unlike the rest of the Hackystat build system, the hackyCore_Build.buildDocBook command does not invoke the dependent module checking procedure. This means that you do not have to make available all of the dependent modules of the module in which you are writing documentation.
This can make the documentation building process much, much faster. You will always need to have the hackyCore_Build module available in your hackystat.build.properties file. In most cases, you can probably write your documentation successfully by enabling only the hackyCore_Build and your chosen module.
I generally build the documentation about every five to ten minutes or so. I do it this way because it is quite easy to introduce errors into the XML file, and by checking my work frequently via a build, I can usually find my formatting errors within a few seconds, since I know they are within the last dozen or so paragraphs of text.
The most frequent error in my experience is forgetting to provide a </para> tag at the end of a paragraph. Example 18.21, “Error message from missing </para> tag” illustrates what happens.
Example 18.21. Error message from missing </para> tag
docbook.consolidate:
[copy] Copying 19 files to C:\svn\hackyCore_Build\build\docbook\tmp
[style] Processing C:\svn\hackyCore_Build\build\docbook\tmp\index.docbook.xml to C:\svn\hackyCore_Build\build\docbook\tmp\docbook-ready-file.tmp
[style] Loading stylesheet C:\svn\hackyCore_Build\lib\styler\preprocess\preprocess.xsl
[style] file:/C:/svn/hackyCore_Build/build/docbook/tmp/hackyCore_Build.documentation.docbook.xml:1575:3:
Fatal Error! Error reported by XML parser Cause: org.xml.sax.SAXParseException:
The element type "para" must be terminated by the matching end-tag "</para>".
[style] : Warning! org.xml.sax.SAXParseException: The element type "para" must be terminated by the matching end-tag "</para>".
Cause: org.xml.sax.SAXParseException: The element type "para" must be terminated by the matching end-tag "</para>".
html.chunked:
First off, note where this error was reported: in the "docbook.consolidate" target output after running the preprocess.xsl style sheet. Next, note that the error includes the file name (hackyCore_Build.documentation.docbook.xml) and the line number within the file (1575). This pretty much points you to where you are (probably) missing the </para> tag.
Second, what you'll find is that the Hackystat documentation will be built without the file containing the incorrect XML tag structure. If you are puzzled about why your documentation is not showing up in the final product, it's most likely because of an error in the docbook.consolidate target. (If there's no error here, then the problem is most likely that you haven't made your module "available" in hackystat.build.properties, so it's not being included in the build.)
Make sure you always check the docbook.consolidate target when doing a build of the documentation, because that is one of the two targets where errors will be reported. Note that Ant will still report the build as "Successful" even if problems occur during the parsing.
A second very common mistake is to forget to include not the close tag, but the open tag, such as: <para>. Example 18.22, “Error message from missing <para> tag” illustrates what happens.
Example 18.22. Error message from missing <para> tag
docbook.consolidate:
[copy] Copying 19 files to C:\svn\hackyCore_Build\build\docbook\tmp
[style] Processing C:\svn\hackyCore_Build\build\docbook\tmp\index.docbook.xml to C:\svn\hackyCore_Build\build\docbook\tmp\docbook-ready-file.tmp
[style] Loading stylesheet C:\svn\hackyCore_Build\lib\styler\preprocess\preprocess.xsl
[style] file:/C:/svn/hackyCore_Build/build/docbook/tmp/hackyCore_Build.documentation.docbook.xml:1619:3:
Fatal Error! Error reported by XML parser Cause: org.xml.sax.SAXParseException:
The element type "section" must be terminated by the matching end-tag "</section>".
[style] : Warning! org.xml.sax.SAXParseException: The element type "section" must be terminated by the matching end-tag "</section>".
Cause: org.xml.sax.SAXParseException: The element type "section" must be terminated by the matching end-tag "</section>".
html.chunked:
[copy] Copying 1 file to C:\svn\hackyCore_Build\build\docbook\tmp
The error message in this case is misleading: it says that the problem is with a missing </section>, though the actual problem is with a missing <para>! Several times, I have spent fruitless time searching for a missing </section> tag, only to finally realize it was the lack of a <para>.
The way to save yourself frustration is to read the error message closely. In this case, the line number (1619) where the parser stopped was actually a </para> tag. This is your hint that the problem is with the <para> tag, not the <section> tag.
Once you get past the docbook.consolidate target with no errors, the next source of difficulty manifests itself in the html.chunked target. Here, the problem is with missing or incorrectly spelled cross-references. This occurs when the "linkend" attribute of an <xref> does not match the "id" attribute of the corresponding <section>, <chapter>, <example>, or <figure>. Example 18.23, “Error message from incorrectly spelled or missing cross references” illustrates what happens.
Example 18.23. Error message from incorrectly spelled or missing cross references
[style] Writing C:\svn\hackyCore_Build\build\war\docbook/ch05s03.html for section [style] Error: no ID for constraint linkend: ch:designing.sensordatatypes. [style] XRef to nonexistent id: ch:designing.sensordatatypes [style] Error: no ID for constraint linkend: hackyCore_Kernel.sdt.simplesdt.installation. [style] XRef to nonexistent id: hackyCore_Kernel.sdt.simplesdt.installation
These are generally fairly simple to fix. The one that often causes problems is the "pasteFigure" tag, since the "id" attribute for that tag has "figure:" prepended to it during the translation process. Therefore, if you supply the id "foo" in your <pasteFigure> tag, you need to remember to use "figure:foo" when referring to that figure in the linkend attribute of your <xref> tag.
The last characteristic documentation bug is a missing image, which typically occurs when you misspell the name of the .png file containing your image in the <pasteFigure> tag, or else forget to SVN 'add' the image file to your repository.
Unfortunately, there's no way I know of to catch these errors other than to actually bring up your documentation in a browser and visually check to see that all of the images are displayed.
Note that a very weird error can result when you make a mistake in the case of your file name containing an image. For example, I recently committed a file named "hackyCore_build.documentation.simplesdt.png", and referred to it in the documentation source as "hackyCore_Build.documentation.simplesdt.png". When viewing the documentation page containing this image in a browser under Windows using file: urls, the image appeared correctly (since Windows is fundamentally case-insensitive). However, once I viewed the page using the http: url in a deployed server, the page did not appear (since http is a case-sensitive protocol). The moral is to make sure you do not make mistakes in the case of your file names.