I am evaluating Maven not only as a build tool, but as a central point
for project documentation. Writing technical docs in DocBook seem the
right choice, but integrating all the moving parts seems difficult. I
would like to include docbkx-maven-plugin plugin in site generation. The
doxia-module-docbook-simple does not work very well by first impression.
It does not even display images (see my post doxia-module-docbook-simple).
In chapter 3.12. Creating a Web Site for your Application of Better
Build with Maven it is stated
Currently the most well supported formats available are:
* The XDOC format, which is a simple XML format used widely at
Apache.
* The APT format, "Almost Plain Text", which is a Wiki-like
format that allows you to write simple, structured documents
(like this) very quickly. A full reference of the A PT Format6
is available.
* The FML format, which is the FAQ format. A simple XML format
for managing FAQs.
* The DocBook Simple format, which is a less complex version of
the full DocBook format.
Maven also has limited support for :
* The Twiki format, which is a popular Wiki markup format.
* The Confluence format, which is another popular Wiki markup
format .
* The DocBook format.
So far, in my experience, and also what I found at
http://agilejava.com/blog/?p=31 the above does not hold true for
DocBook. The doxia-module-docbook-simple has no documentation of its own
at all
(http://maven.apache.org/doxia/doxia-modules/doxia-module-docbook-simple/index.html).
Maybe I didn't look at the right places.
If using docbkx-maven-plugin (http://agilejava.com/blog/?p=31),which is
better, then I guess there is no way to have all the menus and other
tech documentation generated by site plugin.
One of the requirements for the project documentation is to be
printable. That is achived by formatting html site to be printer
friendly or by converting it to PDF format, which is very well
implemented in Apache Forrest. DocBook can be turned into PDF, that is
why I think it is the most suitable (for us) format.
So, the ideal would be the doxia site plugin implementing DocBook Simple
(or docbkx with menus or somehow integrated) with Forrest functionality
of generating PDF directly from web page (or on demand from command line).
I would like to hear your oppinions, experience with documentation and
any future plans.
Somehow related is also this article
http://www.oreillynet.com/onjava/blog/2006/03/maven_project_info_reports_con.html
from Timothy M. O'Brien.
Thanks for your input!
Borut
