dhis2-devs team mailing list archive

[Lars Helge Øverland <larshelge@xxxxxxxxx>]

On Tue, Sep 15, 2009 at 10:44 PM, Jason Pickering <
jason.p.pickering@xxxxxxxxx> 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
>
>
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