Mailing-List: contact dev-help@directory.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Apache Directory Developers List" <dev@directory.apache.org>
Received-SPF: neutral (nike.apache.org: local policy)
MIME-Version: 1.0
Date: Sun, 18 Sep 2011 22:20:19 +0200
Message-ID: 
 <CAPz8h_UBRfTsk+py+Ktxdh8zH1XW7x_t3gc0KcDiAfoMy8kwAA@mail.gmail.com>
Subject: ApacheDS documentation: docbook vs. wiki syntax
From: Stefan Seelmann <mail@stefan-seelmann.de>
To: Apache Directory Developers List <dev@directory.apache.org>
Content-Type: text/plain; charset=UTF-8

Hi guys,

I'd like to come back to our documentation issue:
- docu in confluence isn't versionized
- docbook in source control isn't easy to write

I did some research and found some interesting links [1][2][3]. I
setup an additonal user guide as PoC [4].

The idea is as follows:
1. Documenation source is still stored in source control.
2. We use wiki syntax (confluence) to edit the documenation. Eclipse
Mylyn WikiText includes editors for various wiki syntaxes (e.g.
confluence, but not markdown) that provide content assist, syntax
highlighting and a nice preview, see "Getting Started" of [1].
3. The wiki syntax is transformed to docbook xml. Unfortunately the
required Mylyn libraries are not available in public maven repo and
there is no maven plugin*. So I worked around and added the two
required jars to the lib folder and added a maven-antrun-plugin
execution to the POM.
4. Docbook is transformed to HTML, PDF, whatever

I think that is a good way to make docu editing easier but still use
the power of docbook to create different output formats. Of course not
all features of docbook can be used but I think that is a minor issue.
A bigger task is the transformation of the existing docbook files to
confluence syntax.

Looking forward to your feedback.

Kind Regards,
Stefan


* The Apache ServiceMix guys created a maven plugin but it doesn't
seem to be maintained.
[1] http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.mylyn.wikitext.help.ui/help/Mylyn%20WikiText%20User%20Guide.html
[2] http://www.peterfriese.de/getting-started-with-wikitext/
[3] http://www.peterfriese.de/advanced-wikitext/
[4] http://svn.apache.org/repos/asf/directory/documentation/apacheds-manuals/trunk/src/basic-user-guide-confluence/