DocBook - Writing Documentation
Writing Documentation
The DocBook Source File
Configuring Eclipse
Since you will probably be editing your code with an IDE such as Eclipse, it makes sense to also write your documentation with Eclipse.
Separate documentation exists on how to configure Eclipse and set up your Adempiere development environment.
Once you have Eclipse configured properly for Adempiere, you can make it aware of the DocBook 5 namespace by loading the catalog provided by Adempiere.
Open the Preferences window ( → ), select → in the left pane, and click the button in the right pane.
In the popup window, click on the Next Catalog icon and then on the button.
Navigate to docbook/lib/ in the Adempiere project
and select docbook_catalog.xml.
Eclipse is now aware of the DocBook 5 namespace and can assist you with auto-completion and XML validation.
Documentation Subdirectory
Although not strictly necessary, it is recommendable to have a designated subdirectory for your documentation source files. This makes it easier to parameterize your source files for the build process and also makes image handling more efficient.
If you create HTML or WIKI output, any images you use can not be embedded in the document but
must be made available to the target as actual files. The build process therefore copies all images
it finds in or under an images directory under your
source file to the target. If your documentation source file were lumped together in one directory
with your normal source code, it would copy all images you use in your project,
including those which are not used in your documentation.
The documentation subdirectory can be located anywhere in your project, even under your normal source tree.
DocBook 5 source files are XML files, so create a file with the extension
.xml. Choose any file name you like, though a descriptive
name such as projectName_manual.xml has its advantages. When the output
documents are generated, the build process derives the final file name from the document title
and only uses your file name if it can not find any title.
DocBook 5 Markups
DocBook 5 provides three categories of element tags.
Structural Tags
As the name implies, structural tags divide the document into a logical structure. Examples are:
bookorarticleprefacechapterappendix- …
Block Tags
Block tags describe elements which constitute a continuous block of content. Examples are:
paragraphlisttable- …
Inline Tags
Inline tags describe elements which have a special meaning and thus give hints whether any special format should be used. Note that inline tags only mark up the contents and do not define any special format themselves. How the element is finally displayed is decided by stylesheets.
emphasisfilenamelinkproductname- …
Ample documentation is available online, so there is no need to elaborate any further here.
Adempiere Extensions
The DocBook 5 namespace has been extended for Adempiere.
A new element wikicategory, which is used at the bottom of a WIKI page to categorize it,
has been added to the book and article elements. It is ignored in HTML and PDF output.
Furthermore, some tags, when used inside the info element of book or article,
are interpreted with a slightly different meaning by the Adempiere stylesheets:
- title
The first
titleis the document title, and it will also be used to name the output files.If more than one
titleexists, all followingtitles will be printed below- copyright
holderelements of thecopyrightelement will be listed- collab
The
collabelement can contain two different members:- person
a
personwill be listed as contributor in the legal notice- organization
an
orgwill be listed as sponsor in the legal notice
subtitle and abstract on a cover page.
Sample Template
Adempiere supplies a template which you can use as a starting point
to write your project documentation. It can be found at docbook/source/template/template.xml.
Generating Output
Configuring your Project
The ant build file docbook/build.xml
can either be invoked on its own, in which case it will generate the docbook
documentation (this text you are currently reading), or it can be imported into build files of other
subprojects to generate documentation for those.
The following sections explain how to import docbook/build.xml into your own
build file and call it from there.
Setting Properties
You first need to set some global parameters which will
override the properties defined in docbook/build.xml.
This is done in the general area of your build.xml outside of any target definitions.
- docbook.fileset.source
This is the set of source
.xmlfiles from- docbook.dir.target
This is the target directory in which the generated files should
- docbook.paper.type
This is the paper size used for generating PDF output. It defaults to A4
If you wanted to include all .xml files
under your src directory, you could write
To include all .xml files located in a special
documentation directory somewhere under
src, the definition would beIf an images directory exists under a source file,
all images found there will be copied to the target.
If no docbook.fileset.source is defined, the docbook
documentation (this text) will be generated.
be saved. If you do not define it, by default all generated documentation will be
placed inuserdoc in your project's base directory.You could use this setting to direct the output to a central location, for example
the userdoc directory in docbook
For each source file, a subdirectory containing the generated documentation is created
in docbook.dir.target.
if omitted. Sensible values are A4 or USletter, although
the whole range of ISO A0 - C10 is permitted.Chances are that if you want a set of documentation in USletter, you would
prefer USletter in general, so it probably makes more sense to modify
docbook.paper.type in docbook/build.xml than on a
Importing the DocBook Build File
Next, import docbook/build.xml into your own build file. This should be done
optionally so that compilation of your code does not stop just because the docbook
build file could not be found.
It is also a good idea to check whether docbook/build.xml is available at all.
The result can later be used as condition whether documentation should be generated or not.
<available property="docbook.exists" file="../docbook/build.xml"/> <import file="../docbook/build.xml" optional="true"/>
Calling Output Targets
Finally, write a target which executes on condition of docbook/build.xml's
existence which was checked above.
This target should be included in your depends chain.
From here, you can call one of the docbook targets to generate the documentation.
<target name="userdoc" depends="…" if="docbook.exists"> <antcall target="docbook.all" /> </target>
Possible docbook targets are:
- docbook.html.mono
- generate a single monolithic web page
- docbook.html.chunk
- generate multiple web pages, one for each chapter
- docbook.html
- generate both monolithic and chunked web pages
- docbook.wiki.mono
- generate a single monolithic WIKI page
- docbook.wiki.chunk
- generate multiple WIKI pages, one for each chapter
- docbook.wiki
- generate both monolithic and chunked WIKI pages
- docbook.pdf
- generate a PDF book
- docbook.all
- generate all of above
When generating monolithic output, the document's title is used as the file's base name. The monolithic output for this documentation would be:
docbook/userdoc/DocBook/DocBook.htmldocbook/userdoc/DocBook/DocBook.wikidocbook/userdoc/DocBook/DocBook.pdf
For chunked output, the main document's base name is index, and the individual chunks are called pr… for
prefixes, ch… for chapters, and ap… for appendices. The chunked
output for this documentation would be:
docbook/userdoc/DocBook/index.htmldocbook/userdoc/DocBook/pr01.htmldocbook/userdoc/DocBook/ch01.htmldocbook/userdoc/DocBook/ch02.htmldocbook/userdoc/DocBook/ch03.htmldocbook/userdoc/DocBook/index.wikidocbook/userdoc/DocBook/pr01.wikidocbook/userdoc/DocBook/ch01.wikidocbook/userdoc/DocBook/ch02.wikidocbook/userdoc/DocBook/ch03.wiki
Sample build.xml
Following is a real-life build.xml file
(taken from the migrate subproject) illustrating
how to integrate docbook.
The relevant passages have been highlighted.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project name="myProject" default="all" basedir=".">
<description>
This buildfile is used to build myProject
within the Adempiere project.
</description>
<!-- =========================================== -->
<!-- Properties -->
<!-- =========================================== -->
<!-- import global properties -->
<import file="../utils_dev/properties.xml" optional="true"/>
<!-- properties for main build -->
<property name="tools.dir" value="../tools/lib" />
<property name="source.dir" value="src" />
<property name="build.dir" value="build" />
<property name="jar.dir" value="lib" />
<property name="jar.name" value="myProject" />
<path id="project.class.path">
<pathelement path="${classpath}" />
</path>
<!-- properties for distribution -->
<property name="dist.dir" value="../lib" />
<available property="dist.dir.exists" file="${dist.dir}" />
<!-- properties for API documentation -->
<property name="apidoc.dir" value="apidoc" />
<!-- properties for user documentation -->
<fileset
id="docbook.fileset.source"
dir="${source.dir}"
includes="**/documentation/**/*.xml"/>
<available
property="docbook.exists"
file="../docbook/build.xml"/>
<import
file="../docbook/build.xml"
optional="true"/>
<!-- =========================================== -->
<!-- Init -->
<!-- =========================================== -->
<target name="init">
<echo message="=========== Build myProject ===========" />
<!-- create the time stamp -->
<tstamp />
<!-- main build settings -->
<mkdir dir="${build.dir}" />
<mkdir dir="${jar.dir}" />
<uptodate property="jar.uptodate"
targetfile="${jar.dir}/${jar.name}.jar">
<srcfiles dir="${source.dir}">
<include name="**/*.java" />
<include name="**/images/*" />
<include name="**/*.gif" />
<include name="**/*.jpg" />
<include name="**/*.wav" />
<include name="**/*.htm" />
<include name="**/*.html" />
<include name="**/*.properties" />
<exclude name="**/package.html" />
<exclude name="**/documentation/*" />
</srcfiles>
</uptodate>
<!-- API documentation settings -->
<mkdir dir="${apidoc.dir}" />
<uptodate property="apidoc.uptodate"
targetfile="${apidoc.dir}/index.html">
<srcfiles dir="${source.dir}" includes="**/*.java" />
</uptodate>
</target>
<!-- =========================================== -->
<!-- Compile -->
<!-- =========================================== -->
<target name="compile" depends="init" unless="jar.uptodate">
<!-- compile the java code -->
<javac srcdir="${source.dir}" destdir="${build.dir}"
includeAntRuntime="false">
<classpath refid="project.class.path" />
</javac>
<!-- copy all image & sound files from source
to the build directory -->
<copy todir="${build.dir}">
<fileset dir="${source.dir}">
<include name="**/images/*" />
<include name="**/*.gif" />
<include name="**/*.jpg" />
<include name="**/*.wav" />
<include name="**/*.htm" />
<include name="**/*.html" />
<include name="**/*.properties" />
<exclude name="**/package.html" />
<exclude name="**/documentation/*" />
</fileset>
</copy>
</target>
<!-- =========================================== -->
<!-- Pack -->
<!-- =========================================== -->
<target name="pack" depends="compile" unless="jar.uptodate">
<!-- put everything from the build directory into the jar file -->
<jar jarfile="${jar.dir}/${jar.name}.jar"
excludes="**/*.jbx"
index="yes">
<fileset dir="${build.dir}" />
<manifest>
<attribute name="Created-By"
value="Author Name" />
<attribute name="Specification-Title"
value="myProject for ${env.ADEMPIERE_VERSION}" />
<attribute name="Specification-Version"
value="myProject ${env.ADEMPIERE_VERSION} ${env.AD
EMPIERE_VERSION_FILE}" />
<attribute name="Specification-Vendor"
value="Vendor Name" />
<attribute name="Implementation-Title"
value="myProject ${env.ADEMPIERE_VERSION} ${env.AD
EMPIERE_VERSION_FILE}" />
<attribute name="Implementation-Version"
value="${env.ADEMPIERE_VERSION} ${env.ADEMPIERE_VE
RSION_FILE} ${DSTAMP}-${TSTAMP}" />
<attribute name="Implementation-Vendor"
value="${env.ADEMPIERE_VENDOR}" />
<attribute name="Implementation-URL"
value="http://www.adempiere.org" />
<attribute name="Main-Class"
value="com.vendor.myProjectMainClass" />
</manifest>
</jar>
</target>
<!-- =========================================== -->
<!-- Distribute -->
<!-- =========================================== -->
<target name="distinit" if="dist.dir.exists">
<uptodate property="dist.uptodate"
targetfile="${dist.dir}/${jar.name}.jar">
<srcfiles dir="${jar.dir}">
<include name="${jar.name}.jar" />
</srcfiles>
</uptodate>
</target>
<target name="distribute" depends="pack, distinit"
if="dist.dir.exists"
unless="dist.uptodate">
<copy file="${jar.dir}/${jar.name}.jar"
tofile="${dist.dir}/${jar.name}.jar"
overwrite="true" />
</target>
<!-- =========================================== -->
<!-- API documentation (JavaDoc) -->
<!-- =========================================== -->
<target name="apidoc" depends="init" unless="apidoc.uptodate">
<!-- create the api documentation -->
<javadoc packagenames="*"
sourcepath="${source.dir}"
destdir="${apidoc.dir}" />
</target>
<!-- =========================================== -->
<!-- User Documentation (DocBook) -->
<!-- =========================================== -->
<target name="userdoc" depends="init" if="docbook.exists">
<antcall target="docbook.all" />
</target>
<!-- =========================================== -->
<!-- ALL -->
<!-- =========================================== -->
<target name="all" depends="distribute, apidoc, userdoc" />
<!-- =========================================== -->
<!-- Clean up -->
<!-- =========================================== -->
<target name="clean">
<!-- Delete the build directory tree -->
<delete dir="${build.dir}"
failonerror="false" />
<!-- Delete the target files -->
<delete file="${jar.dir}/${jar.name}.jar"
failonerror="false" />
<!-- Delete the distribution files -->
<delete file="${dist.dir}/${jar.name}.jar"
failonerror="false" />
<!-- Delete the api documentation directory trees -->
<delete dir="${apidoc.dir}"
failonerror="false" />
<!-- Delete the user documentation directory trees -->
<delete dir="userdoc"
failonerror="false" />
</target>
</project>
Document Generation
Once your build file is correctly set up, start ./RUN_build.sh or RUN_build.bat to compile your source.
The build process will automatically generate the user documentation.
Distributing and Publishing
Of course simply generating the documentation is not sufficient. It still needs to be published and distributed to reach its intended audience.
WIKI Documents
The quickest way to make your documentation easily available to a wide audience is to include it in the Adempiere WIKI.
This is where it can easily be found by search engines and where users browse for documentation.
In a WIKI, a new page is typically created by establishing a link to it. If a link to a non-existing page is clicked, that page is opened in edit mode and can thus be created.
A good source for help on how to write WIKI pages can be found here.
When you create an account in the Adempiere WIKI, you automatically get your own user page assigned. To publish your documentation in the WIKI, you can simply create a link to it from your user page like this:
[[page name|display text]]
The page name should be the title of your document.
Click on that link and then copy the contents of the WIKI file generated by docbook and paste them into to edit box of the page you just created.
As long pages are discouraged by WIKIs, you will almost always want to use chunked WIKI pages. In this case, copy
and paste the contents of index.wiki, which is basically the title page with a table of contents.
The chunked WIKI pages contain navigation toolbars in the header and footer, so you can successively click
the button and then copy and paste the next chunk into each newly created page.
The page names which docbook generates (and which must be used for the navigation buttons and table of contents to work) are:
- document title for the first page
- document title - chapter title for all following pages
So the page names for this document would be:
- DocBook
- DocBook - Conventions
- DocBook - Introduction
- DocBook - Writing Documentation
- DocBook - Extending DocBook
If your documentation includes any images, they must be uploaded to the WIKI separately. From the WIKI menu, select → .
To avoid name clashes, it is best to prefix your image file names with a unique identifier, such as
doc_projectName_…
Because the WIKI document contains category information supplied by the wikicategory tag, other users will be able to find your documentation from the categories menu.
HTML Documents
To serve the documentation from your own webserver, you can simply copy either the
monolithic or chunked .html files to your
server.
If your documentation includes images, also copy the images
directory. The images are referenced by relative path names as images/picturename
from the .html file.
PDF Documents
PDF documents are far superior to HTML and WIKI versions when it comes to layout and formatting. The reason is that WIKI and HTML documents have much less formatting elements available than PDF, and many markups are simply lost.
For example, it may be perfectly normal to have a verbatim program listing but still want to emphasize some parts of that listing in bold for clarity. No problem in PDF, but a verbatim block in WIKI would also display any tags as verbatim text, so the tags are removed and the result is a block of text without any emphasized passages.
In addition, HTML (and, by extension, WIKI) documents also only use a markup language, and it is left entirely to the browser how things are actually formatted and displayed.
It may therefore by worthwhile to consider distributing the documentation in PDF form.
This can be done by making the PDF version available for download from your web server.
Alternatively, if you use Adempiere's RPM source file found at
utils/unix/adempiere.src.rpm to package your own RPMs,
all .pdf files found after compilation are automatically
installed in /usr/share/doc/adempiere/… as reference
for users.
