dhis2-devs team mailing list archive

[Jason Pickering <jason.p.pickering@xxxxxxxxx>]

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



On Sun, Sep 13, 2009 at 4:24 PM, Jason Pickering <
jason.p.pickering@xxxxxxxxx> wrote:

> Well, it was actually not so difficult. I have just commited in 687 which
> will allow for automated documentation builds for documentation in DocBook
> format stored in the /dhis2/docs/src/docbook directory
>
> Just execute
>
> mvn docbook:transform
>
> in the docs directory. You will find the HTML files in
> /docs/target/site/docbook/.
>
> I think someone that understands maven needs to modify that pom.xml file a
> bit. All images that the DocBook source file needs to reference need to be
> stored somewhere., and then I guess copied over to the target directory
> during the build.
>
> I guess we should add other formats as well, such as PDF. It should be
> possible, but I do not know enough about maven to make it work. I just
> copied that pom.xml file from the site in my previous mail and it worked
> pretty much magically.
>
>
> I modified the directory structure a bit as well to fit the needs of maven.
> Perhaps they need to be standardized a bit to fit the rest of the project.
>
> Regards,
> Jason
>
>
>
> On Sun, Sep 13, 2009 at 2:23 PM, Jason Pickering <
> jason.p.pickering@xxxxxxxxx> wrote:
>
>> Oh, forgot to add, maybe someone that understand maven better than I do
>> (pretty much everyone) can use/modify this to automate the building of the
>> documentation.
>>
>>
>> http://docbook.svn.sourceforge.net/viewvc/docbook/trunk/maven/docbook-sample/
>>
>> Regards,
>> Jason
>>
>>
>>
>> On Sun, Sep 13, 2009 at 2:21 PM, Jason Pickering <
>> jason.p.pickering@xxxxxxxxx> wrote:
>>
>>> Hi there,
>>>
>>> It does not look too bad for a first pass. :)
>>>
>>> Basically, I tried a number of ways to get the manual in this format, but
>>> the easiest I think was simply copying and pasting chunks of text into XXE
>>> (a docbook editor). I just could not get any of the exporters to work very
>>> well (YAWC, XMLSpy were the ones I tried). This initial conversion took
>>> about 30 minutes for this doucment, so it was not too painful.
>>>
>>> As you say, there are essentially no style information at the moment. I
>>> guess this would need to be handled by the XSL with appropriate tags in the
>>> source document.
>>> This should be able to be added as we go along.
>>>
>>> Best,
>>> Jason
>>>
>>>
>>>
>>>
>>> On Sun, Sep 13, 2009 at 12:06 PM, Bob Jolliffe <bobjolliffe@xxxxxxxxx>wrote:
>>>
>>>> Just had a first glance at section one of the manual.  It looks very
>>>> nice but it is unstructured word processed text - ie. everything is styled
>>>> "default".  So there are no shortcuts to be had - conversion to docbook and
>>>> creation of structure for the document will be  manual.  I guess the others
>>>> will be the same.  This will be a bit painful but will add considerable
>>>> value to the documentation.
>>>>
>>>> Regards
>>>> Bob
>>>>
>>>> 2009/9/11 Ola Hodne Titlestad <olatitle@xxxxxxxxx>
>>>>
>>>>  The user manual developed in India is on word format, have a look here:
>>>>> http://folk.uio.no/knutst/pub/usermanual/
>>>>>
>>>>> Which is linked from the front page of hisp.info (and should be linked
>>>>> from dhis2.com as well, but it is not at the moment).
>>>>>
>>>>>
>>>>> Ola Hodne Titlestad |Technical Officer|
>>>>> Health Metrics Network (HMN) | World Health Organization
>>>>> Avenue Appia 20 |1211 Geneva 27, Switzerland | Email:
>>>>> titlestado@xxxxxxx|Tel: +41 788216897
>>>>> Website: www.healthmetricsnetwork.org
>>>>>
>>>>> Better Information. Better Decisions. Better Health.
>>>>>
>>>>>
>>>>> 2009/9/11 Bob Jolliffe <bobjolliffe@xxxxxxxxx>
>>>>>
>>>>>> Hi Jason
>>>>>>
>>>>>>
>>>>>> I will have a look at odf2docbook.  It is just implemented as an xslt
>>>>>> filter in openoffice so I should be able to get it out.
>>>>>>
>>>>>> If there are word documents with  reasonable structure (highly
>>>>>> unlikely!!) then this might be a shortcut to getting a first pass going.
>>>>>> Otherwise, from word save as xhtml (I presume it can do that) and transform
>>>>>> that to docbook.
>>>>>>
>>>>>> Cheers
>>>>>> Bob
>>>>>>
>>>>>>
>>>>>>
>>>>>> 2009/9/11 Jason Pickering <jason.p.pickering@xxxxxxxxx>
>>>>>>
>>>>>>
>>>>>>> Aha, there is a user manual, on yet another server! Never knew about
>>>>>>> this one. :)
>>>>>>>
>>>>>>> Wow, there really is a lot of material out there, and it is going to
>>>>>>> be a monumental task to get into into some type of "proper" form.
>>>>>>>
>>>>>>> Well, I am willing to try and coordinate the initial pass at getting
>>>>>>> the documentation into DocBook, but it will have to be a team effort. This
>>>>>>> was one of my arguments for moving towards this format, as it should allow
>>>>>>> collaborative work. This will have to be done in my "spare" time, but I am
>>>>>>> willing to give it a try, assuming that everyone else is on board, and this
>>>>>>> is the direction the community wants to go. It will be a lot of work, but it
>>>>>>> seems that the long-term advantages are abundant.
>>>>>>>
>>>>>>> I would still be interested to hear what the technical writer to be
>>>>>>> engaged by HMN has to say, as we definitely do not want to jump off a cliff
>>>>>>> here.
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> 2009/9/11 Knut Staring <knutst@xxxxxxxxx>
>>>>>>>
>>>>>>> 2009/9/11 Lars Helge Øverland <larshelge@xxxxxxxxx>
>>>>>>>>
>>>>>>>>>
>>>>>>>>>> The intrinsic problem with formats such as DockuWiki is that they
>>>>>>>>>> are pretty much a one way street. It is an easy format to use, but not
>>>>>>>>>> entirely easy to transform into something else. Pure XML formats such as
>>>>>>>>>> DocBook separate entirely the content away from the presentation. Want Word?
>>>>>>>>>> No problem. How about PDF? Can do. How about an integrated help system with
>>>>>>>>>> the application? Should not be an issue as you have pure XML to work with.
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>> I want to emphasize this argument: We have decided earlier to have
>>>>>>>>> an integrated dynamic help function in dhis2, and we already have a simple
>>>>>>>>> solution implemented which we can build on. Still, syncronizing the content
>>>>>>>>> of this help function with the general documentation effort would be
>>>>>>>>> desirable (and necessary). Going for an xml format such as docbook and
>>>>>>>>> locating the help file inside the repo will solve this issue. Choosing a
>>>>>>>>> wiki will demand lots of manual work.
>>>>>>>>>
>>>>>>>>
>>>>>>>> Ola and I agree with going for DocBook - so please don't hesitate,
>>>>>>>> Jason. That said, we should look into ways of making it easy for people to
>>>>>>>> contribute. An initial approach would be for contributors to send their
>>>>>>>> material to you, and you make sure it fits in DocBook.
>>>>>>>>
>>>>>>>> The changes with release 2.0.2 does probably mean a new manual
>>>>>>>> should be created. Some material from the previous user manual may still be
>>>>>>>> suitable:
>>>>>>>> http://folk.uio.no/knutst/pub/usermanual/
>>>>>>>>
>>>>>>>> Knut
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>>>
>>>>>>>>> Lars
>>>>>>>>>
>>>>>>>>> _______________________________________________
>>>>>>>>> Mailing list: https://launchpad.net/~dhis2-devs<https://launchpad.net/%7Edhis2-devs>
>>>>>>>>> Post to     : dhis2-devs@xxxxxxxxxxxxxxxxxxx
>>>>>>>>> Unsubscribe : https://launchpad.net/~dhis2-devs<https://launchpad.net/%7Edhis2-devs>
>>>>>>>>> More help   : https://help.launchpad.net/ListHelp
>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> --
>>>>>>>> Cheers,
>>>>>>>> Knut Staring
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> _______________________________________________
>>>>>>> Mailing list: https://launchpad.net/~dhis2-devs<https://launchpad.net/%7Edhis2-devs>
>>>>>>> Post to     : dhis2-devs@xxxxxxxxxxxxxxxxxxx
>>>>>>> Unsubscribe : https://launchpad.net/~dhis2-devs<https://launchpad.net/%7Edhis2-devs>
>>>>>>> More help   : https://help.launchpad.net/ListHelp
>>>>>>>
>>>>>>>
>>>>>>
>>>>>> _______________________________________________
>>>>>> Mailing list: https://launchpad.net/~dhis2-devs<https://launchpad.net/%7Edhis2-devs>
>>>>>> Post to     : dhis2-devs@xxxxxxxxxxxxxxxxxxx
>>>>>> Unsubscribe : https://launchpad.net/~dhis2-devs<https://launchpad.net/%7Edhis2-devs>
>>>>>> More help   : https://help.launchpad.net/ListHelp
>>>>>>
>>>>>>
>>>>>
>>>>
>>>
>>
>