etch-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Michael Fitzner <>
Subject AW: Proposal Etch documentation for PDF and Html
Date Tue, 16 Nov 2010 11:37:05 GMT
Hi Martijn,
Thanks for the information about the new Apache CMS approach. For our website publications,
I think it would be perfect and we should also migrate to it as soon as the CMS will be available
to incubator projects. For the technical documentation (manual style), I would prefere a book
like document structure, where you can generate PDF and Html output. This means that all the
website publications like release note, download info, mailing lists etc. could be done with
Apache CMS and the technical documentation (NSDL, Bindings, Compiler) with docbook.

Do you know about other Apache projects that use the CMS for manual styled documentation (PDF,


-----Urspr√ľngliche Nachricht-----
Von: Martijn Dashorst [] 
Gesendet: Montag, 15. November 2010 21:01
Betreff: Re: Proposal Etch documentation for PDF and Html

Please read if you are looking for
alternatives to confluence.

You are free of course to choose any documentation standard you wish,
in my experience writing XML really is painful. The Apache CMS uses
markdown as their templating language, and that is much better suited
for writing content than XML.

Note that infrastructure probably will move everyone away from
confluence (at least for the website maintenance) in due time. I'm not
sure if infrastructure will come up with an alternative to confluence
for the wiki part.


On Mon, Nov 15, 2010 at 4:54 PM, Michael Fitzner
<> wrote:
> Hi guys,
> A major part of the Etch documentation takes place inside Confluence Wiki at the moment.
We see some disadvantages for doing so and would like to start to improve the Etch documentation.
Some points which we would like to address:
> -One documentation base (XML)
> -Providing different output formats like PDF for storing and printing, HTML for online
> -Customization of output should be possible
> -Continuous development of documentation and versioning of it (etc. with SVN)
> -Release management for documentation
> -Documentation-Patches that are easy to provide
> -Distributed development of documentation
> Our proposal to fulfill all these requirements; is using the docbook (
format and its default toolchain like xslt, fo etc.
> To give you an expression how it could looks like, we have created a Jira-Issue [ETCH-115<>]
with a basic docbook documentation skeleton for etch, a Makefile for creating PDF and HTML
output and some resources like xslt stylesheets. It is possible to recreate the documentation
on a linux based system (for windows some Makefile adjustments are still necessary, but it
should also work)
> The complete Etch documentation could be stored inside SVN and all guys are able to work
on it and provide patches. When the documentation has reached a certain quality it would be
time to do an extract and publish this one to our website (HTML + PDF Version).
> If we plan to change our Website to Apache Forrest in future, we will still able to process
the docbook format with Forrest (this is supported by Apache Forrest).
> If all like it; we would start to add the documentation artifacts to SVN and begin writing
documentation. Feedback is welcome.
> Thanks
> Michael

Become a Wicket expert, learn from the best:

View raw message