You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@directory.apache.org by Stefan Seelmann <ma...@stefan-seelmann.de> on 2011/09/18 22:20:19 UTC
ApacheDS documentation: docbook vs. wiki syntax
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/
Re: ApacheDS documentation: docbook vs. wiki syntax
Posted by Emmanuel Lecharny <el...@gmail.com>.
On 10/19/11 8:52 AM, Pierre-Arnaud Marcelot wrote:
> On 18 oct. 2011, at 23:22, Emmanuel Lecharny wrote:
>
>> 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)
> Studio's documentation already exists in the 'studio' repository.
> It will probably need to stay there, rather than being externalized in its own repository, due to the fact that the documentation is bundled into plugins which are included in the app itself.
oh, ok.
I just created a dedicated dir for the API doco then.
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: ApacheDS documentation: docbook vs. wiki syntax
Posted by Pierre-Arnaud Marcelot <pa...@marcelot.net>.
On 18 oct. 2011, at 23:22, Emmanuel Lecharny wrote:
> 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)
Studio's documentation already exists in the 'studio' repository.
It will probably need to stay there, rather than being externalized in its own repository, due to the fact that the documentation is bundled into plugins which are included in the app itself.
There's still one important thing to do, though, it's moving from our XML based Docbook files to the new format.
Regards,
Pierre-Arnaud
> - API (api-manuals : to be created)
>
> Thoughts ?
>
> --
> Regards,
> Cordialement,
> Emmanuel Lécharny
> www.iktek.com
>
Re: ApacheDS documentation: docbook vs. wiki syntax
Posted by Oliver Schmidt <ol...@arcor.de>.
Am 18.10.2011, 23:22 Uhr, schrieb Emmanuel Lecharny <el...@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.
Re: ApacheDS documentation: docbook vs. wiki syntax
Posted by Emmanuel Lecharny <el...@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 ?
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com
Re: ApacheDS documentation: docbook vs. wiki syntax
Posted by Alex Karasulu <ak...@apache.org>.
Looked at the links as well but did not hands on experiment with the tools.
If you guys are this ecstatic about it then I'm on board :) ... let's just
go for it and I'll conform.
+1
Regards,
Alex
On Tue, Sep 20, 2011 at 12:44 PM, Pierre-Arnaud Marcelot <pa...@marcelot.net>wrote:
>
> On 19 sept. 2011, at 23:25, Stefan Seelmann wrote:
>
> > On Mon, Sep 19, 2011 at 3:44 PM, Pierre-Arnaud Marcelot <pa...@marcelot.net>
> wrote:
> >>
> >> On 19 sept. 2011, at 15:37, Stefan Seelmann wrote:
> >>
> >>> On Mon, Sep 19, 2011 at 3:20 PM, Pierre-Arnaud Marcelot <
> pa@marcelot.net> wrote:
> >>>> 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)?
> >>>
> >>> Hehe, I thought about that use case this morning in the tube. I don't
> >>> know yet but have to check if internal links work.
> >>
> >> It would be great if we can find a way to have those internal links, but
> we can definitively live without them I guess.
> >
> > I added some internal link examples. It quite easy, the pattern is
> > "#HeaderName". The only ugly thing is that links to other .confluence
> > files are marked as error, but the combined book.confluence file in
> > target/generated-sources/basic-user-guide-confluence/book.confluence
> > then works.
>
> Oh yeah, indeed, the editor is marking it as erroneous. Not a real issue
> though, if the result is correct.
>
> >>>> 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)?
> >>>
> >>> Right, book.txt defines the order of chapters for the case that the
> >>> chapter files are not alphabetically ordered. And I think it is
> >>> possible to spilt the chapters, AFAIK the H1 header is transformed to
> >>> a chapter and H2..H6 headers are transformed to (sub-)sections.
> >>
> >> Oh, cool. I feared that chapters were based on the .confluence files. I
> didn't closely look at the generated HTML.
> >> In that case, that's awesome. :)
> >
> > I also added an example and splitted a chapter into sections and
> subsections.
>
> I saw that, that's just perfect.
>
> Thanks a lot for this experiment.
>
> I'm now definitively convinced and more than +1 on using this set of tools
> for our documentation.
>
> Regards,
> Pierre-Arnaud
>
> > Kind Regards,
> > Stefan
>
>
--
Best Regards,
-- Alex
Re: ApacheDS documentation: docbook vs. wiki syntax
Posted by Pierre-Arnaud Marcelot <pa...@marcelot.net>.
On 19 sept. 2011, at 23:25, Stefan Seelmann wrote:
> On Mon, Sep 19, 2011 at 3:44 PM, Pierre-Arnaud Marcelot <pa...@marcelot.net> wrote:
>>
>> On 19 sept. 2011, at 15:37, Stefan Seelmann wrote:
>>
>>> On Mon, Sep 19, 2011 at 3:20 PM, Pierre-Arnaud Marcelot <pa...@marcelot.net> wrote:
>>>> 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)?
>>>
>>> Hehe, I thought about that use case this morning in the tube. I don't
>>> know yet but have to check if internal links work.
>>
>> It would be great if we can find a way to have those internal links, but we can definitively live without them I guess.
>
> I added some internal link examples. It quite easy, the pattern is
> "#HeaderName". The only ugly thing is that links to other .confluence
> files are marked as error, but the combined book.confluence file in
> target/generated-sources/basic-user-guide-confluence/book.confluence
> then works.
Oh yeah, indeed, the editor is marking it as erroneous. Not a real issue though, if the result is correct.
>>>> 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)?
>>>
>>> Right, book.txt defines the order of chapters for the case that the
>>> chapter files are not alphabetically ordered. And I think it is
>>> possible to spilt the chapters, AFAIK the H1 header is transformed to
>>> a chapter and H2..H6 headers are transformed to (sub-)sections.
>>
>> Oh, cool. I feared that chapters were based on the .confluence files. I didn't closely look at the generated HTML.
>> In that case, that's awesome. :)
>
> I also added an example and splitted a chapter into sections and subsections.
I saw that, that's just perfect.
Thanks a lot for this experiment.
I'm now definitively convinced and more than +1 on using this set of tools for our documentation.
Regards,
Pierre-Arnaud
> Kind Regards,
> Stefan
Re: ApacheDS documentation: docbook vs. wiki syntax
Posted by Stefan Seelmann <se...@apache.org>.
On Mon, Sep 19, 2011 at 3:44 PM, Pierre-Arnaud Marcelot <pa...@marcelot.net> wrote:
>
> On 19 sept. 2011, at 15:37, Stefan Seelmann wrote:
>
>> On Mon, Sep 19, 2011 at 3:20 PM, Pierre-Arnaud Marcelot <pa...@marcelot.net> wrote:
>>> 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)?
>>
>> Hehe, I thought about that use case this morning in the tube. I don't
>> know yet but have to check if internal links work.
>
> It would be great if we can find a way to have those internal links, but we can definitively live without them I guess.
I added some internal link examples. It quite easy, the pattern is
"#HeaderName". The only ugly thing is that links to other .confluence
files are marked as error, but the combined book.confluence file in
target/generated-sources/basic-user-guide-confluence/book.confluence
then works.
>>> 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)?
>>
>> Right, book.txt defines the order of chapters for the case that the
>> chapter files are not alphabetically ordered. And I think it is
>> possible to spilt the chapters, AFAIK the H1 header is transformed to
>> a chapter and H2..H6 headers are transformed to (sub-)sections.
>
> Oh, cool. I feared that chapters were based on the .confluence files. I didn't closely look at the generated HTML.
> In that case, that's awesome. :)
I also added an example and splitted a chapter into sections and subsections.
Kind Regards,
Stefan
Re: ApacheDS documentation: docbook vs. wiki syntax
Posted by Pierre-Arnaud Marcelot <pa...@marcelot.net>.
On 19 sept. 2011, at 15:37, Stefan Seelmann wrote:
> On Mon, Sep 19, 2011 at 3:20 PM, Pierre-Arnaud Marcelot <pa...@marcelot.net> wrote:
>> 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)?
>
> Hehe, I thought about that use case this morning in the tube. I don't
> know yet but have to check if internal links work.
It would be great if we can find a way to have those internal links, but we can definitively live without them I guess.
>> 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)?
>
> Right, book.txt defines the order of chapters for the case that the
> chapter files are not alphabetically ordered. And I think it is
> possible to spilt the chapters, AFAIK the H1 header is transformed to
> a chapter and H2..H6 headers are transformed to (sub-)sections.
Oh, cool. I feared that chapters were based on the .confluence files. I didn't closely look at the generated HTML.
In that case, that's awesome. :)
Thanks,
Pierre-Arnaud
> Kind Regards,
> Stefan
Re: ApacheDS documentation: docbook vs. wiki syntax
Posted by Stefan Seelmann <se...@apache.org>.
On Mon, Sep 19, 2011 at 3:20 PM, Pierre-Arnaud Marcelot <pa...@marcelot.net> wrote:
> 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)?
Hehe, I thought about that use case this morning in the tube. I don't
know yet but have to check if internal links work.
> 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)?
Right, book.txt defines the order of chapters for the case that the
chapter files are not alphabetically ordered. And I think it is
possible to spilt the chapters, AFAIK the H1 header is transformed to
a chapter and H2..H6 headers are transformed to (sub-)sections.
Kind Regards,
Stefan
Re: ApacheDS documentation: docbook vs. wiki syntax
Posted by Pierre-Arnaud Marcelot <pa...@marcelot.net>.
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/
Re: ApacheDS documentation: docbook vs. wiki syntax
Posted by Pierre-Arnaud Marcelot <pa...@marcelot.net>.
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/
Re: ApacheDS documentation: docbook vs. wiki syntax
Posted by Emmanuel Lecharny <el...@apache.org>.
Hi Stefan,
no real time this week to look at the links you provided, wil do that when
I'll be back from vacations...
On Sun, Sep 18, 2011 at 10:20 PM, Stefan Seelmann
<ma...@stefan-seelmann.de>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/
>
--
Regards,
Cordialement,
Emmanuel Lécharny
www.iktek.com