directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Pierre-Arnaud Marcelot ...@marcelot.net>
Subject Re: ApacheDS documentation: docbook vs. wiki syntax
Date Mon, 19 Sep 2011 07:13:44 GMT
Thanks Stefan!

I'm checking out your PoC.

More to come...

Regards,
Pierre-Arnaud


On 18 sept. 2011, at 22:20, Stefan Seelmann wrote:

> 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/


Mime
View raw message