Ok, I had misunderstood the goal of the maven plugin. And I agree using the wiki syntax is easier than pure docbook xml.
On Tue, May 4, 2010 at 20:35, Gert Vanthienen <[email protected]>wrote: > 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 > >> > >> > > > > > -- Cheers, Guillaume Nodet ------------------------ Blog: http://gnodet.blogspot.com/ ------------------------ Open Source SOA http://fusesource.com
