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/
