Guillaume,
The docs-maven-plugin currently has two goals, one to add a snippet:
url handler so we can reuse the existing snippets in svn and another
goal to generate docbook XML files based on a text file with
Confluence markup.
I don't think it would be a good idea to keep editing the docs in the
wiki and only export it into DocBook, because we would loose a few of
the advantages of having the documentation in subversion (allow for
documentation patches and especially versioning our documentation).
As I see it, we could use that conversion goal in two ways:
- leverage it to copy-paste contents from the wiki into the
documentation project to get us started more quickly and afterwards
copy the generated docbook XML files into the documentation source
- use it to write the documentation itself in Confluence markup rather
than pure DocBook XML
Personally, I would rather pick the latter option because we'll be
editing files that are far less verbose and that still are in a very
easy to understand format, which might also help us attract more
documentation patches in the future. We probably still need to use
pure DocBook XML for setting up title pages, tocs, appendices, ... but
if we add a few more things (like bulleted/numbered lists,
!image.png!, {include} and tables) to the plugin, we can probably
write about 90% of all the contents we need in these Confluence-markup
files.
Wdyt?
Gert Vanthienen
------------------------
Open Source SOA: http://fusesource.com
Blog: http://gertvanthienen.blogspot.com/
On 4 May 2010 16:14, Jean-Baptiste Onofré <[email protected]> wrote:
> Hi Guillaume,
>
> my comments inline:
>
>> Do you want me to start exporting the Karaf User's guide in docbook ?
>> Charles, you were talking about generating some doc from the
>> commands ....
>> Let me know if you need some help.
>
> For sure, Karaf user's guide in docbook could be a big enhancement as we can
> "import" it in the SMX one.
> I can begin to work on it when I come back next friday.
>
>>
>> Gert, for the maven plugin, is the plan to keep things in confluence
>> and
>> reuse it in docbook, or do migrate it slowly over to docbook ?
>
> From my point of view, the master documentation repository should be docbook
> project. We can export docbook data to wiki using the Gert's maven plugin.
>
> Regards
> JB
>
>>
>> On Tue, May 4, 2010 at 09:25, Charles Moulliard
>> wrote:
>>
>> > +1
>> >
>> > Gert,
>> >
>> > Before to work on documentation, I would like to finalize the
>> template
>> > of the xml docbook documents already created. I will do that by the
>> > end of this week. So, I prefer that everybody wait that I finalize
>> > them before to work on material.
>> >
>> > Kind regards,
>> >
>> > Charles Moulliard
>> >
>> > Senior Enterprise Architect (J2EE, .NET, SOA)
>> > Apache Camel/ServiceMix Committer
>> >
>> > *******************************************************************
>> > - Blog : http://cmoulliard.blogspot.com
>> > - Twitter : http://twitter.com/cmoulliard
>> > - Linkedlin : http://www.linkedin.com/in/charlesmoulliard
>> >
>> >
>> >
>> > On Mon, May 3, 2010 at 12:47 AM, Gert Vanthienen
>> > wrote:
>> > > L.S.,
>> > >
>> > > We've been talking about creating a new DocBook-based manual for
>> > > ServiceMix in the past and we currently have two separate
>> > > proof-of-concepts sitting in the sandbox folder:
>> > > - Jean-Baptiste's sandbox folder has a skeleton ServiceMix 4.2.0
>> > > manual, with some of the topics already filled in
>> > > - my own sandbox folder has a base project setup and an extra
>> maven
>> > > plugin to allow (re)using Confluence markup and the snippets we
>> have
>> > > in svn
>> > >
>> > > With some time available tomorrow, I would like to start moving
>> all
>> > > this into a more definitive location so we can start
>> collaborating on
>> > > the content. In my own proposal, I made a distinction between:
>> > > - a programmer's guide, which contains the real ServiceMix manual
>> with
>> > > installation, configuration and development information
>> > > - a JBI Reference Guide, which contains the description of all
>> the
>> > > endpoints with their options and a set of example configurations
>> for
>> > > all of them to avoid cluttering the manual with all this
>> information
>> > >
>> > > If that's OK for everyone, I'll keep this distinction for now and
>> make
>> > > Jean-Baptiste's manual the first document (because he already has
>> a
>> > > good table of contents for that kind of document), so all the
>> work
>> > > that has already been done by him and Charles can be reused.
>> > >
>> > > For the svn layout, I would propose to create these two
>> locations,
>> > > with svnmerge setup to merge docs from trunk into the branch:
>> > > - documentation/trunk for the current 4.x development version
>> > > - documentation/branches/servicemix-4.2.x for documenting the
>> latest
>> > > release 4.2.0
>> > >
>> > > The maven plugin can go into the maven-plugins project we already
>> have
>> > > setup in Hudson -- I'll try to add a Hudson setup for the
>> > > documentation projects as well so they can get built/published
>> > > automatically.
>> > >
>> > > Regards,
>> > >
>> > > Gert Vanthienen
>> > > ------------------------
>> > > Open Source SOA: http://fusesource.com
>> > > Blog: http://gertvanthienen.blogspot.com/
>> > >
>> >
>>
>> --
>> Cheers,
>> Guillaume Nodet
>> ------------------------
>> Blog: http://gnodet.blogspot.com/ [6]
>> ------------------------
>> Open Source SOA
>> http://fusesource.com [7]
>>
>>
>>
>> Links:
>> ------
>> [1]
>> http://webmail.nanthrax.net/parse.php?redirect=http%3A%2F%2Fcmoulliard.blog
>> spot.com%0D%3C%2Ffont[2]
>> http://webmail.nanthrax.net/parse.php?redirect=http%3A%2F%2Ftwitter.com%2Fc
>> moulliard%0D%3C%2Ffont[3]
>> http://webmail.nanthrax.net/parse.php?redirect=http%3A%2F%2Fwww.linkedin.co
>> m%2Fin%2Fcharlesmoulliard%0D%3C%2Ffont[4]
>> http://webmail.nanthrax.net/parse.php?redirect=http%3A%2F%2Ffusesource.com%
>> 0D%3C%2Ffont[5]
>> http://webmail.nanthrax.net/parse.php?redirect=http%3A%2F%2Fgertvanthienen.
>> blogspot.com%2F%0D%3C%2Ffont[6]
>> http://webmail.nanthrax.net/parse.php?redirect=http%3A%2F%2Fgnodet.blogspot
>> .com%2F[7]
>> http://webmail.nanthrax.net/parse.php?redirect=http%3A%2F%2Ffusesource.com
>>
>>
>
>
