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 13:20:35 GMT
Hi Stefan,

I generated the Docbook HTML and PDF output and it looks really really good...

The syntax is the same we're already used to in Confluence (which allows a lot of different
styles) and the output looks perfect (like our Docbook-written Apache Directory Studio documentation).

On my side, it is a big *+1*.
I really love this solution. Simple, easy and convenient for everyone.

Do you know if it possible (and how) to link some text to another content (another section,
chapter or page for example)?

Is the 'book.txt' file, the central file which defines all chapters? And, is each .confluence
file equivalent to a chapter? Also, would it be possible to split a chapter into various .confluence
files (in the case of a very very big chapter)?

Thanks,
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