directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Oliver Schmidt" <oliver.schmidt....@arcor.de>
Subject Re: ApacheDS documentation: docbook vs. wiki syntax
Date Wed, 19 Oct 2011 05:29:31 GMT
Am 18.10.2011, 23:22 Uhr, schrieb Emmanuel Lecharny <elecharny@gmail.com>:

> Hi,
>
> On 9/18/11 10:20 PM, 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.
>
> So I checked the project and the tools today : excellent !
>
> We will now need to move all the wiki pages to svn. I will start with  
> the API doco.
>
> I suggest we create sub-project under documentation, one per project :
> - ApacheDS (apacheds-manuals)
> - Studio (studio-manuals : to be created)
> - API (api-manuals : to be created)
>
> Thoughts ?
>

I also checked this out and found it better for maintaining the  
documentation. In Confluence's web-based editor I could stick much time on  
a comparatively small section while this way it seems easier.

Mime
View raw message