Return-Path: X-Original-To: apmail-directory-dev-archive@www.apache.org Delivered-To: apmail-directory-dev-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id D9D1F78F8 for ; Sun, 18 Sep 2011 21:14:13 +0000 (UTC) Received: (qmail 31080 invoked by uid 500); 18 Sep 2011 21:14:13 -0000 Delivered-To: apmail-directory-dev-archive@directory.apache.org Received: (qmail 31042 invoked by uid 500); 18 Sep 2011 21:14:13 -0000 Mailing-List: contact dev-help@directory.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: "Apache Directory Developers List" Delivered-To: mailing list dev@directory.apache.org Received: (qmail 31021 invoked by uid 99); 18 Sep 2011 21:14:13 -0000 Received: from minotaur.apache.org (HELO minotaur.apache.org) (140.211.11.9) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 18 Sep 2011 21:14:13 +0000 Received: from localhost (HELO mail-ww0-f44.google.com) (127.0.0.1) (smtp-auth username elecharny, mechanism plain) by minotaur.apache.org (qpsmtpd/0.29) with ESMTP; Sun, 18 Sep 2011 21:14:13 +0000 Received: by wwf22 with SMTP id 22so7156778wwf.1 for ; Sun, 18 Sep 2011 14:14:11 -0700 (PDT) MIME-Version: 1.0 Received: by 10.227.200.21 with SMTP id eu21mr1940438wbb.12.1316380451586; Sun, 18 Sep 2011 14:14:11 -0700 (PDT) Reply-To: elecharny@apache.org Received: by 10.180.97.197 with HTTP; Sun, 18 Sep 2011 14:14:11 -0700 (PDT) In-Reply-To: References: Date: Sun, 18 Sep 2011 23:14:11 +0200 Message-ID: Subject: Re: ApacheDS documentation: docbook vs. wiki syntax From: Emmanuel Lecharny To: Apache Directory Developers List Content-Type: multipart/alternative; boundary=000e0cdffbc834c3ff04ad3db5ad --000e0cdffbc834c3ff04ad3db5ad Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable 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 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=3D/org.eclipse.mylyn.wikit= ext.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/ > --=20 Regards, Cordialement, Emmanuel L=E9charny www.iktek.com --000e0cdffbc834c3ff04ad3db5ad Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable Hi Stefan,

no real time this week to look at the links y= ou provided, wil do that when I'll be back from vacations...

On Sun, Sep 18, 2011 at 10:20 PM, Stefan Seelmann <= span dir=3D"ltr"><mail@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=3D/org.eclipse.m= ylyn.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=E9charny
ww= w.iktek.com
--000e0cdffbc834c3ff04ad3db5ad--