You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@directory.apache.org by Emmanuel Lecharny <el...@gmail.com> on 2010/06/01 19:05:43 UTC
Writing docos : howto ?
Hi guys,
if we are considering switching back to docbook in place of confluence
for our user guid, here is an interesting post :
http://blog.discursive.com/blog/1913?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed:+Discursive+(Discursive)
This guy is using xmlmind which seems to be more convenient than a
simple text editor when it comes to edit XML documents ...
--
Regards,
Cordialement,
Emmanuel Lécharny
www.nextury.com
Re: Writing docos : howto ?
Posted by Felix Knecht <fe...@apache.org>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On 06/01/10 20:48, Felix Knecht wrote:
> On 06/01/10 19:05, Emmanuel Lecharny wrote:
>> Hi guys,
>
>> if we are considering switching back to docbook in place of confluence
>> for our user guid, here is an interesting post :
>> http://blog.discursive.com/blog/1913?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed:+Discursive+(Discursive)
>
>
>> This guy is using xmlmind which seems to be more convenient than a
>> simple text editor when it comes to edit XML documents ...
>
> Openoffice 3.2 seems also able to export documents as docbook xml
http://xml.openoffice.org/xmerge/docbook/UserGuide.html
(Save
> as ...) as the header of a save document shows:
>
> "
> <?xml version="1.0" encoding="UTF-8"?>
> <!DOCTYPE article
> PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
> "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
> "
>
> But another question which ish IMO also important is how the site can be
> updated. Using confluence now it's easy - just change it in confluence
> and the site is updated within x minutes. Is this still wanted? And if
> so how it can be done?
> Does a committer after updating the docs in svn needs to generate and
> deploy the site himself? Or is it done by the CI server (which seems to
> work not very stable)?
>
>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.15 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iEYEARECAAYFAkwFWYAACgkQ2lZVCB08qHE8UACgpVu4SuDlCZDXyuhFkhdkjVd0
J30AoKfmLSW3eLSh250z/BuKF1b4vsBm
=37ub
-----END PGP SIGNATURE-----
Re: Writing docos : howto ?
Posted by Stefan Seelmann <se...@apache.org>.
Felix Knecht wrote:
> On 06/01/10 19:05, Emmanuel Lecharny wrote:
>> Hi guys,
>
>> if we are considering switching back to docbook in place of confluence
>> for our user guid, here is an interesting post :
>> http://blog.discursive.com/blog/1913?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed:+Discursive+(Discursive)
>
>
>> This guy is using xmlmind which seems to be more convenient than a
>> simple text editor when it comes to edit XML documents ...
>
> Openoffice 3.2 seems also able to export documents as docbook xml (Save
> as ...) as the header of a save document shows:
>
> "
> <?xml version="1.0" encoding="UTF-8"?>
> <!DOCTYPE article
> PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
> "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
> "
>
> But another question which ish IMO also important is how the site can be
> updated. Using confluence now it's easy - just change it in confluence
> and the site is updated within x minutes. Is this still wanted? And if
> so how it can be done?
The question is if we only want to move the documentation to docbook and
svn, or the complete website?
I think for the website it's easier to manage via confluence. However a
mix of confluence and docbook is also confusing.
> Does a committer after updating the docs in svn needs to generate and
> deploy the site himself? Or is it done by the CI server (which seems to
> work not very stable)?
Can we run a cron job on people.apache.org? We already have some that
copies the confluence export to the right directories. However docbook
XSL transformation requires lot of memory.
Kind Regards,
Stefan
Re: Writing docos : howto ?
Posted by Felix Knecht <fe...@apache.org>.
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On 06/01/10 19:05, Emmanuel Lecharny wrote:
> Hi guys,
>
> if we are considering switching back to docbook in place of confluence
> for our user guid, here is an interesting post :
> http://blog.discursive.com/blog/1913?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed:+Discursive+(Discursive)
>
>
> This guy is using xmlmind which seems to be more convenient than a
> simple text editor when it comes to edit XML documents ...
Openoffice 3.2 seems also able to export documents as docbook xml (Save
as ...) as the header of a save document shows:
"
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
"
But another question which ish IMO also important is how the site can be
updated. Using confluence now it's easy - just change it in confluence
and the site is updated within x minutes. Is this still wanted? And if
so how it can be done?
Does a committer after updating the docs in svn needs to generate and
deploy the site himself? Or is it done by the CI server (which seems to
work not very stable)?
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.15 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
iEYEARECAAYFAkwFVgEACgkQ2lZVCB08qHHYogCePECj3tlHrcp3KO7/ypdpcILJ
b6MAn0q3wnmgqqXqDB+bsfoYMXlk4rCH
=ZgcQ
-----END PGP SIGNATURE-----
Re: Writing docos : howto ?
Posted by Guillaume Nodet <gn...@gmail.com>.
I guess the main point is that this confluence markup snippets do not
reside in confluence, but in subversion.
So confluence isn't involved at all.
On Tue, Jun 1, 2010 at 20:03, Guillaume Nodet <gn...@gmail.com> wrote:
> I was not suggesting to use confluence, rather just using the
> confluence syntax (which is imho easier to use) to generate docbook
> xml. The plugin converts snippets of confluence markup into docbook
> xml.
>
> On Tue, Jun 1, 2010 at 19:32, Emmanuel Lécharny <el...@apache.org> wrote:
>> On 6/1/10 7:19 PM, Guillaume Nodet wrote:
>>>
>>> FWIW, we're about to do the same in servicemix and we're working on a
>>> maven plugin to generate docbook xml from confluence wiki syntax.
>>> This is way easier than xml docbook to write and patch imho.
>>> See the following for the maven plugin:
>>>
>>> http://svn.apache.org/repos/asf/servicemix/maven-plugins/docs-maven-plugin/trunk/
>>> and an exmaple:
>>>
>>> http://svn.apache.org/repos/asf/servicemix/documentation/trunk/docs/jbi/src/confluence/servicemix-bean.wiki
>>>
>>
>> We just find Confluence a bit too convoluted to use when it comes to doco.
>> Not only links are rather complicated to manage (back and forwards links),
>> but it's also impossible to generate PDF from confluence AFAIK.
>>
>> We should rather use confluence for the FAS, changing doco, and dev infos.
>>
>> --
>> Regards,
>> Cordialement,
>> Emmanuel Lécharny
>> www.nextury.com
>>
>>
>>
>
>
>
> --
> Cheers,
> Guillaume Nodet
> ------------------------
> Blog: http://gnodet.blogspot.com/
> ------------------------
> Open Source SOA
> http://fusesource.com
>
--
Cheers,
Guillaume Nodet
------------------------
Blog: http://gnodet.blogspot.com/
------------------------
Open Source SOA
http://fusesource.com
Re: Writing docos : howto ?
Posted by Guillaume Nodet <gn...@gmail.com>.
FWIW, we're about to do the same in servicemix and we're working on a
maven plugin to generate docbook xml from confluence wiki syntax.
This is way easier than xml docbook to write and patch imho.
See the following for the maven plugin:
http://svn.apache.org/repos/asf/servicemix/maven-plugins/docs-maven-plugin/trunk/
and an exmaple:
http://svn.apache.org/repos/asf/servicemix/documentation/trunk/docs/jbi/src/confluence/servicemix-bean.wiki
On Tue, Jun 1, 2010 at 19:05, Emmanuel Lecharny <el...@gmail.com> wrote:
> Hi guys,
>
> if we are considering switching back to docbook in place of confluence for
> our user guid, here is an interesting post :
> http://blog.discursive.com/blog/1913?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed:+Discursive+(Discursive)
>
> This guy is using xmlmind which seems to be more convenient than a simple
> text editor when it comes to edit XML documents ...
>
> --
> Regards,
> Cordialement,
> Emmanuel Lécharny
> www.nextury.com
>
>
>
--
Cheers,
Guillaume Nodet
------------------------
Blog: http://gnodet.blogspot.com/
------------------------
Open Source SOA
http://fusesource.com