Re: Qpid Wiki in DocBook
On Thu, Mar 11, 2010 at 2:31 PM, Jonathan Robie jonathan.ro...@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-subscr...@qpid.apache.org
Re: Qpid Wiki in DocBook
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-subscr...@qpid.apache.org
Re: Qpid Wiki in DocBook
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-subscr...@qpid.apache.org -- Bruno Matos bruno.ma...@paradigmaxis.pt smime.p7s Description: S/MIME cryptographic signature
Re: Qpid Wiki in DocBook
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-subscr...@qpid.apache.org - Apache Qpid - AMQP Messaging Implementation Project: http://qpid.apache.org Use/Interact: mailto:dev-subscr...@qpid.apache.org
Re: Qpid Wiki in DocBook
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-subscr...@qpid.apache.org
Re: Qpid Wiki in DocBook
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 acon...@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-subscr...@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-subscr...@qpid.apache.org
Re: Qpid Wiki in DocBook
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-subscr...@qpid.apache.org
RE: Qpid Wiki in DocBook
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.ro...@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-subscr...@qpid.apache.org - Apache Qpid - AMQP Messaging Implementation Project: http://qpid.apache.org Use/Interact: mailto:dev-subscr...@qpid.apache.org
Re: Qpid Wiki in DocBook
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-subscr...@qpid.apache.org
Re: Qpid Wiki in DocBook
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-subscr...@qpid.apache.org
Re: Qpid Wiki in DocBook
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-subscr...@qpid.apache.org
