You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@qpid.apache.org by Jonathan Robie <jo...@redhat.com> on 2010/03/11 15:31:50 UTC
Qpid Wiki in DocBook
Here's a PDF built from the Qpid Wiki, converted to DocBook:
http://people.apache.org/~jonathan/qpid-book.pdf
I'm posting this now as a sign of life, to give a feel for where this is
headed, and to get feedback on the organization.
There are some things that still need cleaning up:
- some links don't resolve properly
- some formatting issues
- some pages have been updated since I converted them
But some of this should simply be replaced with new content - I have
some existing content that we can contribute, and I'd like to start
creating new content here, instead of or in addition to the Wiki.
I'd also like to get some other people working on this with me. I'd
particularly like to get someone to be in charge of the section on the
Java Broker.
Who wants to get involved in this?
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Qpid Wiki in DocBook
Posted by Jonathan Robie <jo...@redhat.com>.
On 03/11/2010 12:08 PM, Cliff Jansen (Interop Systems Inc) wrote:
> I'll try to put together some WCF/C++ client related material over the weekend.
>
Excellent!
The sources are in qpid/doc/book/src. I'll have a README later today.
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
RE: Qpid Wiki in DocBook
Posted by "Cliff Jansen (Interop Systems Inc)" <v-...@microsoft.com>.
Hi Jonathan,
Great stuff!
I'll try to put together some WCF/C++ client related material over the weekend.
Cheers.
Cliff
-----Original Message-----
From: Jonathan Robie [mailto:jonathan.robie@redhat.com]
Sent: Thursday, March 11, 2010 6:32 AM
To: dev@qpid.apache.org
Subject: Qpid Wiki in DocBook
Here's a PDF built from the Qpid Wiki, converted to DocBook:
http://people.apache.org/~jonathan/qpid-book.pdf
I'm posting this now as a sign of life, to give a feel for where this is
headed, and to get feedback on the organization.
There are some things that still need cleaning up:
- some links don't resolve properly
- some formatting issues
- some pages have been updated since I converted them
But some of this should simply be replaced with new content - I have
some existing content that we can contribute, and I'd like to start
creating new content here, instead of or in addition to the Wiki.
I'd also like to get some other people working on this with me. I'd
particularly like to get someone to be in charge of the section on the
Java Broker.
Who wants to get involved in this?
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Qpid Wiki in DocBook
Posted by Bruno Matos <br...@paradigmaxis.pt>.
On 2010/03/11, at 14:31, Jonathan Robie wrote:
> Here's a PDF built from the Qpid Wiki, converted to DocBook:
>
> http://people.apache.org/~jonathan/qpid-book.pdf
Excellent work!!!
>
> I'm posting this now as a sign of life, to give a feel for where
> this is headed, and to get feedback on the organization.
>
> There are some things that still need cleaning up:
>
> - some links don't resolve properly
> - some formatting issues
> - some pages have been updated since I converted them
>
> But some of this should simply be replaced with new content - I have
> some existing content that we can contribute, and I'd like to start
> creating new content here, instead of or in addition to the Wiki.
>
> I'd also like to get some other people working on this with me. I'd
> particularly like to get someone to be in charge of the section on
> the Java Broker.
>
> Who wants to get involved in this?
I would like, but I don't know enough.
>
> Jonathan
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
>
--
Bruno Matos
bruno.matos@paradigmaxis.pt
Re: Qpid Wiki in DocBook
Posted by Jonathan Robie <jo...@redhat.com>.
On 03/11/2010 09:47 AM, Alan Conway wrote:
>
> This is a great start, we really need proper versioned documentation.
> The content definitely needs work to get it up to date and accurate,
> and we should strip out remarks such as "in version 0.4" since this
> doc should refers to the version it's in SVN with. It may also need
> some re-org but that will probably come about as we rework the content.
I agree. And yes, it's a start.
I think the next step is probably to decide whether the rough
organization is good, and identify portions that need to be replaced,
portions that should be kept but improved, etc. To me, polishing the
presentation of the existing material "as is" may not be worth the effort.
> I suggest that this book be strictly user documentation and we strip
> out any design stuff that may have been imported from the wiki. We
> need design docs also but they're separate. I'm currently thinking
> that design docs belong closer to the source, e.g. in doxygen for C++.
I agree. And I tried to keep design docs mostly out of this.
> I'll give the clustering content the once-over, may take me a week or
> two though.
I think we can probably contribute better material on Clustering,
Federation, Persistence, Security, etc. based on other materials that we
have at Red Hat.
I also think we can write high level API tutorials in DocBook, perhaps
using some of the material in the Red Hat tutorials.
> Anyone know any good open-source docbook WYSIWYG editing tools?
> Editing the raw XML is a little unappealing :)
For the Emacs crowd, I like nxml-mode, especially if you learn how to
use tag completion, outlining, etc. (See
http://www.dpawson.co.uk/relaxng/nxml/info.html).
For vi folks, here's something I've seen but never tried:
http://www.linuxjournal.com/article/7737.
On Windows, I like Stylus Studio (http://www.stylusstudio.com/). On
Linux, I like Oxygen (http://www.oxygenxml.com/). Both are commercial
products.
Here's a page on authoring tools for DocBook:
http://wiki.docbook.org/topic/DocBookAuthoringTools
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Qpid Wiki in DocBook
Posted by Rafael Schloming <ra...@redhat.com>.
Alan Conway wrote:
> On 03/11/2010 10:20 AM, Jonathan Robie wrote:
>> On 03/11/2010 10:07 AM, Gordon Sim wrote:
>>> Indeed, thanks! Can you put in a readme with some basic
>>> instructions/process for building pdf or html for those not yet
>>> conversant with docbook?
>>
>> Absolutely - and I'll also put some info on editing tools into the
>> README.
>>
>> I want to check in a build system, I'll put instructions into the README
>> when I do that. I think an ant-based system is probably best at least
>> until there are no dangling references.
>>
> I'd suggest a Makefile as make as it has fewer dependencies than ant.
> I'm guessing it will be pretty simple in any case.
If you want to be able to build the docs on windows, then ant is
probably easier than a Makefile.
On unix both make and ant are readily available in just about any
distro, along with all their dependencies, so it shouldn't really matter
much from that perspective.
--Rafael
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Qpid Wiki in DocBook
Posted by Alan Conway <ac...@redhat.com>.
On 03/11/2010 10:20 AM, Jonathan Robie wrote:
> On 03/11/2010 10:07 AM, Gordon Sim wrote:
>> Indeed, thanks! Can you put in a readme with some basic
>> instructions/process for building pdf or html for those not yet
>> conversant with docbook?
>
> Absolutely - and I'll also put some info on editing tools into the README.
>
> I want to check in a build system, I'll put instructions into the README
> when I do that. I think an ant-based system is probably best at least
> until there are no dangling references.
>
I'd suggest a Makefile as make as it has fewer dependencies than ant. I'm
guessing it will be pretty simple in any case.
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Qpid Wiki in DocBook
Posted by Jonathan Robie <jo...@redhat.com>.
On 03/11/2010 10:07 AM, Gordon Sim wrote:
> Indeed, thanks! Can you put in a readme with some basic
> instructions/process for building pdf or html for those not yet
> conversant with docbook?
Absolutely - and I'll also put some info on editing tools into the README.
I want to check in a build system, I'll put instructions into the README
when I do that. I think an ant-based system is probably best at least
until there are no dangling references.
I like Publican, it's easy to use and gives great output, but it's
unforgiving.
Jonathan
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Qpid Wiki in DocBook
Posted by Gordon Sim <gs...@redhat.com>.
On 03/11/2010 02:47 PM, Alan Conway wrote:
> On 03/11/2010 09:31 AM, Jonathan Robie wrote:
>> Here's a PDF built from the Qpid Wiki, converted to DocBook:
>>
>> http://people.apache.org/~jonathan/qpid-book.pdf
>>
>> I'm posting this now as a sign of life, to give a feel for where this is
>> headed, and to get feedback on the organization.
>>
>> There are some things that still need cleaning up:
>>
>> - some links don't resolve properly
>> - some formatting issues
>> - some pages have been updated since I converted them
>>
>> But some of this should simply be replaced with new content - I have
>> some existing content that we can contribute, and I'd like to start
>> creating new content here, instead of or in addition to the Wiki.
>>
>> I'd also like to get some other people working on this with me. I'd
>> particularly like to get someone to be in charge of the section on the
>> Java Broker.
>>
>> Who wants to get involved in this?
>>
>
> This is a great start, we really need proper versioned documentation.
Indeed, thanks! Can you put in a readme with some basic
instructions/process for building pdf or html for those not yet
conversant with docbook?
> The content definitely needs work to get it up to date and accurate, and
> we should strip out remarks such as "in version 0.4" since this doc
> should refers to the version it's in SVN with. It may also need some
> re-org but that will probably come about as we rework the content.
>
> I suggest that this book be strictly user documentation and we strip out
> any design stuff that may have been imported from the wiki. We need
> design docs also but they're separate. I'm currently thinking that
> design docs belong closer to the source, e.g. in doxygen for C++.
>
> I'll give the clustering content the once-over, may take me a week or
> two though.
>
> Anyone know any good open-source docbook WYSIWYG editing tools? Editing
> the raw XML is a little unappealing :)
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Qpid Wiki in DocBook
Posted by Rajith Attapattu <ra...@gmail.com>.
First up good job jonathan !
I think we can start from here and improve it gradually.
As Alan said we should strip out any design docs etc..
I will also have a look and try organize the java client side as much as I can.
Joanthan would you like to send an email outlining how the docs are
currently organized and how we may want the end product to look?
Perhaps then people can keep that in mind when they do the updates or
new addition of content.
On Thu, Mar 11, 2010 at 9:47 AM, Alan Conway <ac...@redhat.com> wrote:
> On 03/11/2010 09:31 AM, Jonathan Robie wrote:
>>
>> Here's a PDF built from the Qpid Wiki, converted to DocBook:
>>
>> http://people.apache.org/~jonathan/qpid-book.pdf
>>
>> I'm posting this now as a sign of life, to give a feel for where this is
>> headed, and to get feedback on the organization.
>>
>> There are some things that still need cleaning up:
>>
>> - some links don't resolve properly
>> - some formatting issues
>> - some pages have been updated since I converted them
>>
>> But some of this should simply be replaced with new content - I have
>> some existing content that we can contribute, and I'd like to start
>> creating new content here, instead of or in addition to the Wiki.
>>
>> I'd also like to get some other people working on this with me. I'd
>> particularly like to get someone to be in charge of the section on the
>> Java Broker.
>>
>> Who wants to get involved in this?
>>
>
> This is a great start, we really need proper versioned documentation. The
> content definitely needs work to get it up to date and accurate, and we
> should strip out remarks such as "in version 0.4" since this doc should
> refers to the version it's in SVN with. It may also need some re-org but
> that will probably come about as we rework the content.
>
> I suggest that this book be strictly user documentation and we strip out any
> design stuff that may have been imported from the wiki. We need design docs
> also but they're separate. I'm currently thinking that design docs belong
> closer to the source, e.g. in doxygen for C++.
>
> I'll give the clustering content the once-over, may take me a week or two
> though.
>
> Anyone know any good open-source docbook WYSIWYG editing tools? Editing the
> raw XML is a little unappealing :)
>
> ---------------------------------------------------------------------
> Apache Qpid - AMQP Messaging Implementation
> Project: http://qpid.apache.org
> Use/Interact: mailto:dev-subscribe@qpid.apache.org
>
>
--
Regards,
Rajith Attapattu
Red Hat
http://rajith.2rlabs.com/
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Qpid Wiki in DocBook
Posted by Alan Conway <ac...@redhat.com>.
On 03/11/2010 09:31 AM, Jonathan Robie wrote:
> Here's a PDF built from the Qpid Wiki, converted to DocBook:
>
> http://people.apache.org/~jonathan/qpid-book.pdf
>
> I'm posting this now as a sign of life, to give a feel for where this is
> headed, and to get feedback on the organization.
>
> There are some things that still need cleaning up:
>
> - some links don't resolve properly
> - some formatting issues
> - some pages have been updated since I converted them
>
> But some of this should simply be replaced with new content - I have
> some existing content that we can contribute, and I'd like to start
> creating new content here, instead of or in addition to the Wiki.
>
> I'd also like to get some other people working on this with me. I'd
> particularly like to get someone to be in charge of the section on the
> Java Broker.
>
> Who wants to get involved in this?
>
This is a great start, we really need proper versioned documentation. The
content definitely needs work to get it up to date and accurate, and we should
strip out remarks such as "in version 0.4" since this doc should refers to the
version it's in SVN with. It may also need some re-org but that will probably
come about as we rework the content.
I suggest that this book be strictly user documentation and we strip out any
design stuff that may have been imported from the wiki. We need design docs also
but they're separate. I'm currently thinking that design docs belong closer to
the source, e.g. in doxygen for C++.
I'll give the clustering content the once-over, may take me a week or two though.
Anyone know any good open-source docbook WYSIWYG editing tools? Editing the raw
XML is a little unappealing :)
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org
Re: Qpid Wiki in DocBook
Posted by Aidan Skinner <ai...@gmail.com>.
On Thu, Mar 11, 2010 at 2:31 PM, Jonathan Robie
<jo...@redhat.com> wrote:
> Here's a PDF built from the Qpid Wiki, converted to DocBook:
>
> http://people.apache.org/~jonathan/qpid-book.pdf
This is all kinds of awesome.
> I'd also like to get some other people working on this with me. I'd
> particularly like to get someone to be in charge of the section on the Java
> Broker.
I'll try to update this when I get back to the land of real internet
next week, my 3G mobile broadband thing does not play well with svn or
large downloads atm. In general I'd argue that changes which require
doc changes should include them as part of the patch.
- Aidan
--
Apache Qpid - AMQP, JMS, other messaging love http://qpid.apache.org
"A witty saying proves nothing" - Voltaire
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:dev-subscribe@qpid.apache.org