Each Sensor Data Type should provide a file that contains documentation about its structure and purpose. The set of all SDT docbook documentation is generated into the Reference Guide as Chapter 25, Sensor Data Types. Note that each SDT gets a section within this chapter.
To see the formatted docbook documentation for the hackyDoc_SimpleSdt module, you can invoke "ant -q hackyCore_Build.buildDocBook", as illustrated below with much of the output deleted:
C:\svn\hackyCore_Build>ant -q hackyCore_Build.buildDocBook
[style] Writing C:\svn\hackyCore_Build\build\war\docbook/ch01s02.html for section
:
[style] Writing C:\svn\hackyCore_Build\build\war\docbook/index.html for book
[echo] (12:44:45) Completed hackyCore_Build.buildDocbook
BUILD SUCCESSFUL
Total time: 2 minutes 46 seconds
You can now see the SimpleSdt documentation by using a browser to open the index.html file in the build/war/docbook directory of your local build, and navigating to the Reference Guide chapter containing sensor data type documentation.
Sensor data type documentation generally consists of an overview section, which describes the required and "common optional" properties for this SDT, and an applications section, which discusses how the SDT is commonly used for process and product analysis. Example 15.7, “The SimpleSdt DocBook documentation” illustrates the source for the SimpleSdt page.
Example 15.7. The SimpleSdt DocBook documentation
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section 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;
]>
<section id="hackyDoc_SimpleSdt:sec:sdt.simplesdt">
<title>The SimpleSdt Sensor Data Type</title>
<section>
<title>Overview</title>
<para>
The SimpleSdt sensor data type is designed to help new Hackystat developers become comfortable
with the design and implementation of sensor data types. This docbook file provides a template
for how the SDT documentation should be written.
<xref linkend="hackyDoc_SimpleSdt.sdt.attributes"/> documents the SimpleSdt attributes.
<table id="hackyDoc_SimpleSdt.sdt.attributes" frame="all" rowsep="1" colsep="1">
<title>SimpleSdt SDT attributes</title>
<tgroup cols="2" align="left">
<thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>tstamp</entry>
<entry>The UTC time at which this data was collected.</entry>
</row>
<row>
<entry>tool</entry>
<entry>A string indicating the tool that collected this data, such as "BCML" or "LOCC".</entry>
</row>
<row>
<entry>name</entry>
<entry>A string indicating a name to be associated with this SimpleSdt sensor data instance. </entry>
</row>
<row>
<entry>elapsedTime</entry>
<entry>An Integer indicating elapsed time in seconds.
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
In addition to the above required fields for all Simplesdt data, there are a number of "Common optional" attributes
that can appear on the property map. These are documented in <xref linkend="hackyDoc_SimpleSdt.sdt.properties"/>
so that sensor writers can produce SimpleSdt
sensor data that can be processed by the built-in SimpleSdt analyses and reduction functions.
<table id="hackyDoc_SimpleSdt.sdt.properties" frame="all" rowsep="1" colsep="1">
<title>SimpleSdt SDT "Common Optional" properties</title>
<tgroup cols="2" align="left">
<thead>
<row>
<entry>Property</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>url</entry>
<entry>Provides the home page associated with name.</entry>
</row>
<row>
<entry>units</entry>
<entry>Provides the units to be associated with elapsedTime, if not the default (seconds).</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section>
<title>Applications of the SimpleSdt SDT</title>
<para>
This section provides a simple overview of how the sensor data is used, including examples of tools that would
generated this kind of data. See the existing Sensor Data Type documentation for examples.
</para>
</section>
</section>
The Hackystat Build system requires all docbook documentation to be defined for the build system by an accompanying file that ends with ".docbook.def.xml". In the case of hackyDoc_SimpleSdt, this file is called hackyDoc_SimpleSdt.simplesdt.sdt.docbook.def.xml, and is illustrated in Example 15.8, “The SimpleSdt DocBook documentation definition file”.
Example 15.8. The SimpleSdt DocBook documentation definition file
<hackydocbook>
<reference-guide-section chapter="Sensor Data Types"
sortString="SimpleSdt"
fileName="hackyDoc_SimpleSdt.simplesdt.sdt.docbook.xml" />
</hackydocbook>
The docbook definition file tells the build system how to organize the set of docbook documentation files into the overall docbook document. The definition file above indicates that the SimpleSdt documentation should be inserted into the Reference Guide in the chapter called "Sensor Data Types". It provides a string to be used to sort the sections so that they appear in a reasonable alphabetical order. Finally, it provides the name of the file containing this docbook documentation.
Writing the docbook documentation is simple enough once you understand a few concepts. . We currently use Emacs with the XAE package. Eclipse has a plugin from XML editing that might also be helpful. More details on writing docbook documentation for Hackystat will be covered in a future chapter of this Developer Guide.