Hi,
I have just had a look at this, a few comments:
I have reorganized the directory structure a little. I put the maven project in a separate directory called “dhis-documentation-docbook” and used the same name for the project’s artifact id. Also removed the packaging: pom element, which now makes it possible to execute “mvn eclipse:eclipse” and then import the project directly into eclipse. All this to make it conform to the maven projects in the system.
I have tried out a few docbook-capable xml editors. My favourite was Serna Free 4.2, which formats the xml nicely and makes it easy to insert/modify elements in the document. It is free and under active development. Vex worked reasonably well, but is not so easy-to-use as Serna. Also the Eclipse plugin version did not work in my Eclipse installation (Galileo 3.5) and I had to download the stand-alone version (my guess is that this happens because it is no longer under active development.)
http://www.syntext.com/products/serna-free/
One question is how to provide access to documentation writers. By giving people write access to the documentation we also give them write access to the whole branch, including the source code, which is something we don’t want to do. A weakness with Launchpad is that we cannot give people access to only parts of a branch. My suggestion is to create a new, dedicated branch for the documentation.
Finally I want to thank Jason for taking the lead on this important work… I hope other people using the system will follow his example and contribute to this process.
cheers
Lars
···
On Tue, Sep 15, 2009 at 10:44 PM, Jason Pickering jason.p.pickering@gmail.com wrote:
I have just committed in 731 some changes to the documentation system. After a bit of experimentation, it would seem that at least for now, the maven plugin docbkx is a better choice than the previous dependency. I was having issues with the other dependency, so thought I would try some others. Anyway…
Just execute…
mvn docbkx:generate-html to generate HTML
or
mvn docbkx:generate-pdf to generate PDF files for the documents that are present.There seem to be a lot more possibilities with this dependency, but it is a rather heavy download the first time you try and compile the documentation (at least in Zambia).
You can read about it here.
http://docbkx-tools.sourceforge.net/
One of the reasons that I decided to move to this for now was that it seems to be under active development, actually has a mailing list, and good enough documentation for me to understand, (which must mean it is pretty good. Maven is still pure magic for me.)
I have not added a CSS yet for the HTML files, so they still look crappy, but I guess we could make one similar to the DHIS CSS in order to standardize the look and feel.
Let me know what your mileage is.
Best regards,
Jason