DocBook - Writing Documentation

From ADempiere
Jump to: navigation, search
This Wiki is read-only for reference purposes to avoid broken links.


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 (WindowPreferences), select XMLXML Catalog in the left pane, and click the Add … button in the right pane.

Eclipse Preferences

In the popup window, click on the Next Catalog icon and then on the File System … button.

Eclipse XML Catalog Popup

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:

  • book or article
  • preface
  • chapter
  • appendix

Block Tags

Block tags describe elements which constitute a continuous block of content. Examples are:

  • paragraph
  • list
  • table

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.

  • emphasis
  • filename
  • link
  • productname

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 title is the document title, and it will also be used to name the output files.

If more than one title exists, all following titles will be printed below

the subtitle and abstract on a cover page.

copyright

holder elements of the copyright element will be listed

in the legal notice

collab

The collab element can contain two different members:

person

a person will be listed as contributor in the legal notice

organization

an org will be listed as sponsor in the legal notice

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 .xml files from

which the documentation should be generated.

If you wanted to include all .xml files under your src directory, you could write

<fileset id="docbook.fileset.source" dir="${basedir}/src" includes="**/*.xml"/>

To include all .xml files located in a special

documentation directory somewhere under

src, the definition would be

<fileset id="docbook.fileset.source" dir="${basedir}/src" includes="**/documentation/**/*.xml"/>

If 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.

docbook.dir.target

This is the target directory in which the generated files should

be saved. If you do not define it, by default all generated documentation will be

placed in userdoc 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

<property name="docbook.dir.target" value="../docbook/userdoc" />

For each source file, a subdirectory containing the generated documentation is created in docbook.dir.target.

docbook.paper.type

This is the paper size used for generating PDF output. It defaults to A4

if omitted. Sensible values are A4 or USletter, although

the whole range of ISO A0 - C10 is permitted.

<property name="docbook.paper.type" value="USletter" />

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

per-project basis.

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.html
  • docbook/userdoc/DocBook/DocBook.wiki
  • docbook/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.html
  • docbook/userdoc/DocBook/pr01.html
  • docbook/userdoc/DocBook/ch01.html
  • docbook/userdoc/DocBook/ch02.html
  • docbook/userdoc/DocBook/ch03.html
  • docbook/userdoc/DocBook/index.wiki
  • docbook/userdoc/DocBook/pr01.wiki
  • docbook/userdoc/DocBook/ch01.wiki
  • docbook/userdoc/DocBook/ch02.wiki
  • docbook/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 next 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 toolboxUpload file.

Uploading Files to the Wiki

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.

Retrieved from "http://www.adempiere.com/index.php5?title=DocBook_-_Writing_Documentation&oldid=11616"