The DocBook format defines a bewildering number of tags. Fortunately, we have found that there are relatively few that you need to know about in order to produce Hackystat documentation. The following subsections list the tags necessary for all the situations that we know about. If you come up with another generally useful tag, please let us know so that we can include it here.
OK, so this really isn't a tag at all, but the following "header" text is required at the top of all Hackystat docbook.xml files. It defines the XML DocType as being the DocBook along with a few extensions defined by the Ant and DocBook Styler Suite by Dawid Weiss. Example 18.10, “File header example” illustrates this text.
Example 18.10. File header example
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC
"-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
"http://www.cs.put.poznan.pl/dweiss/dtd/dweiss-docbook-extensions.dtd" [
<!ENTITY % isopub SYSTEM "iso-pub.ent">
%isopub;
<!ENTITY % local SYSTEM "local-entities.ent">
%local;
]>
Note that the second line specifies "chapter" as the doctype. If you prefer, you can substitute "section" when inserting this header at the top of Reference Guide section documentation.
The "isopub.ent" file defines a large number of special characters for use in the docbook. The "local-entities.ent" defines some Hackystat-specific entities, such as URLs to the Hackystat public server and so forth. You can find the local-entities.ent file in hackyCore_Build/docbook.
In general, don't think about adding entries to local-entities.ent unless you wish to define an entity that is applicable to multiple modules and for which you want a globally standardized definition. In most cases, you don't need to define any entities at all, but if you do, the typical approach would be to define your own module-specific entities file. This should be named something like "hackyApp_MyModule.local-entities.ent" to guarantee uniqueness. You will then have to provide a local definition of the copyDocbook target in your local.build.xml that overrides the default definition in modules.build.xml that copies this entities file to the build directory. Finally, you have to update your header to include your own definition. This is typically too much work unless you are going to refer to this entity a lot.
The <chapter> tag should be used as the top-level tag in documentation files for the User, Administrator, and Developer guides. For these Guides, the "unit" of documentation is the chapter. Example 18.11, “<chapter> tag example” illustrates this tag.
Example 18.11. <chapter> tag example
<chapter id="hackyApp_Foo.userguide.UsingFoo"> <title>Using Foo</title> : : </chapter>
It's useful for every chapter to have an ID, and you should always make sure your ID begins with the name of your module to avoid conflicts with any other module documentation. All chapters should have a title, of course.
The <section> tag should be used to denote sections, subsections, subsubsections, and so forth. It and the <chapter> tag are the only two "divisional" tags that should appear in your documentation. You can nest <section> tags to create any level of subsectioning. Example 18.12, “<section> tag example” illustrates this tag.
Example 18.12. <section> tag example
<section id="hackyApp_Foo.userguide.UsingFoo.FooParams"> <title>Foo Parameters</title> : : </section>
Sections should always contain a title, but may or may not require an ID depending upon whether the section will be referenced elsewhere using an <xref> tag. If you provide an ID, make sure it is unique by beginning its name with your module name.
The <para> tag should be used to enclose almost all text in your documentation. Exceptions are the text that appears in <title> tags. Example 18.13, “<para> tag example” illustrates this tag.
The <ulink> tag creates a clickable link to an URL. Example 18.14, “<ulink> tag example” illustrates this tag.
Example 18.14. <ulink> tag example
<ulink url="http://www.hackystat.org/">Hackystat Home Page</ulink>
You can see that this tag is written similarly to the HTML <a> tag, where you enclose the text to be made clickable between the <ulink> and </ulink> tags, and provide the URL as an attribute.
The <itemizedlist> tag creates an itemized list, and the <orderedlist> tag creates an ordered list. Example 18.15, “<itemizedlist> tag example” illustrates the first tag.
Example 18.15. <itemizedlist> tag example
<itemizedlist> <listitem><para>The first item.</para></listitem> <listitem><para>The second item.</para></listitem> </itemizedlist>
Be sure to remember to put enclose each list item in at least one <para> tags. If you want an ordered list, use the <orderedlist> tag instead.
The <programlisting> tag is used to provide smaller, formatted text. You can either provide a <programlisting> inline inside of a paragraph, or as the contents of an <example>. Example 18.16, “<programlisting> tag example” illustrates this tag with some sample code inside.
Example 18.16. <programlisting> tag example
<programlisting>
public String getRequiredModuleString(String moduleName) throws Exception {
LocalBuildXmlFile buildFile = (LocalBuildXmlFile)this.buildFileMap.get(moduleName);
if (buildFile == null) {
throw new Exception("AutoConfig error: request for undefined module: " + moduleName);
}
return buildFile.getRequiredModuleString();
}
</programlisting>
Note that you should substitute "<" for "<", ">" for ">", and "&" for "&" in the programlisting environment.
As discussed further below, we recommend the use of Emacs for creating Hackystat docbook files, along with some customizations including an interactive command (called escape-xml-tags-in-region) which is bound to a key sequence (control-c x) to perform these substitutions automatically on the currently selected region.
These tags are used to create boxed text with various icons to signify their importance. Example 18.17, “<note> tag example” illustrates one of these tags.
Example 18.17. <note> tag example
<note> <title>Be sure to frob the baz</title> <para> If you don't frob the baz, the qux will foo! </para> </note>
With <note>, <tip>, and <important>, it is important to provide a <title> and make sure that all of your interior text is enclosed in one or more <para> tags.
This tag is used to generate a clickable reference to another section, chapter, example, or figure in your documentation. Example 18.18, “<xref> tag example” illustrates the use of the tag.
This tag is used to insert a screen image as part of a "Figure" DocBook component. This is not a standard DocBook tag, but rather a special tag provided by the DocBook styler package to simplify the image insertion process. Each occurrence of the pastFigure tag will be expanded into the DocBook <inlinemediaobject> and <imageobject> tags during the build process. Example 18.19, “<pasteFigure> tag example” illustrates the use of the tag.
Example 18.19. <pasteFigure> tag example
<pasteFigure id="hackyCore_Build.documentation.newmodule.toc" width="3in" src="hackyCore_Build.documentation.newmodule.toc.png"> The table of contents showing the NewModule chapter </pasteFigure>
The <pasteFigure> tag takes three attributes, "id", "width", and "src". The "id" attribute should be a unique string that will become the ID associated with this figure. The "width" attribute provides a bound on the image size in certain formats. We supply it with a standard value of "3in", but it is currently ignored when generating HTML format. The "src" attribute provides the name of the image file to be inserted. Note that this file name should be unique, and so it is important to prefix these file names with your module name.
The text between the <pasteFigure> and </pasteFigure> tags will be used as the caption for the figure.
You will typically want to refer to your Figure using an xref tag. For reasons known only to the designer of the Ant Styler package, he decided in this case to prepend the string "figure:" to the ID when generating the DocBook code from this tag. Thus, if you specify "hackyCore_Build.foo" as your pasteFigure ID, then you must use "figure:hackyCore_Build.foo" as the linkend value in your <xref> tag.
We generally create screen image files by using control-printscreen to capture the current window, then paste it into a program such as Paint Shop Pro, then write it out in .png format. Other approaches can be used with equally positive results.
This tag is used to create a table. It is not the most user-friendly tag we've ever seen. Example 18.20, “<table> tag example” illustrates the use of the tag.
Example 18.20. <table> tag example
<table id="hackySdt_Activity.activity.sdt.attributes" frame="all" rowsep="1" colsep="1">
<title>Activity SDT attributes</title>
<tgroup cols="2" align="left">
<thead>
<row>
<entry><para>Attribute</para></entry>
<entry><para>Description</para></entry>
</row>
</thead>
<tbody>
<row>
<entry><para>tstamp</para></entry>
<entry><para>The UTC time at which this data was collected.</para></entry>
</row>
<row>
<entry><para>tool</para></entry>
<entry><para>A string indicating the tool that collected this data.</para></entry>
</row>
</tbody>
</tgroup>
</table>
There are several things to note about this element. First, you will want to supply an ID, and you will want to name it according to the by-now familiar Hackystat uniqueness guaranteeing guidelines. The frame, rowsep, and colsep attributes are standard and hopefully produce reasonable results in most contexts. You will want to provide a <title>.
You must then provide a <tgroup> tag indicating the number of columns in your table. Inside this tag, you will provide a <thead> tag indicating your column titles, with <row> and <entry> elements specifying the column heads. Finally, all text should be enclosed in <para>. Once you have finished with the <thead> element, you can provide a <tbody> element with more nested <row>, <entry>, and <para> tags to provide the "body" of your table.