It's important that whatever it is adds minimal dependencies to the toolset required to build. I took a quick look at markdown and it seems to have a number of different implementations (perl, php, python, etc) that are fairly widely available. The web site also claims that it is designed to be natural looking and human readable in its original form without any processing, so worst case if the tools aren't available we can skip that part of the build and let people read the source documentation directly. Given all that it sounds like it's worth a try to me.
--Rafael On Tue, Feb 26, 2013 at 8:20 AM, Alan Conway <acon...@redhat.com> wrote: > On Tue, 2013-02-26 at 01:56 +0000, Phil Harvey wrote: > > I do agree with you that having documentation committed alongside code is > > the right approach. > > > > I propose that we write this documentation in Markdown syntax. That gives > > us (or our users) the option of easily generating HTML whilst keeping the > > barrier to entry low for authors. > > Markdown is worth a try. docbook is a severe pain in the rear to write > and the XML is almost as painful to read. Seems like pandoc can generate > PDF and even docbook from markdown. > > > > > I recognise that Markdown lacks the semantic richness of Docbook (used > for > > the Qpid Broker), but I believe that's ok in this case since our > > documentation should be quite short (or we're doing something wrong). > > > > Phil > > On Feb 25, 2013 7:07 PM, "Rajith Attapattu" <rajit...@gmail.com> wrote: > > > > > I'm strong believer in maintaining our docs in the source tree, as it > > > makes it easy to release docs along side the code. > > > Also it helps keep the docs current. > > > The wiki based documentation in the past had many issues, the chief > > > complaint being stale most of the time. > > > > > > We could look at doing something similar to the qpid docs, or we could > > > also use this opportunity to experiment with a different approach/tool > > > set. > > > > > > Rajith > > > > > > On Mon, Feb 25, 2013 at 1:50 PM, Michael Goulish <mgoul...@redhat.com> > > > wrote: > > > > > > > > I think I will be landing it in the code tree first, and > > > > from there, I don't know. Any suggestions? > > > > > > > > In the code -- I assume it should be at the top level? > > > > i.e. a sibling of the README file? i.e. > > > > > > > > > > > > qpid-proton-0.4/pulitzer_prize_winning_documentation > > > > > > > > > > > > or something along those lines? > > > > > > > > Agree? Disagree? > > > > > > > > > > > > > > > > > > > > > > > > > > > > ----- Original Message ----- > > > > From: "Phil Harvey" <p...@philharveyonline.com> > > > > To: proton@qpid.apache.org > > > > Sent: Monday, February 25, 2013 12:14:00 PM > > > > Subject: Re: [documentation] -- Intro to Proton > > > > > > > > Hi Michael, > > > > > > > > Maybe you didn't see my previous question (or maybe I didn't see your > > > > answer). > > > > > > > > Where are you intending to store this documentation? Similarly, > where > > > are > > > > you intending to publish it, e.g. as HTML and/or PDF on our web > site, as > > > a > > > > wiki page etc? > > > > > > > > Thanks > > > > Phil > > > > > > > > > > > > On 25 February 2013 16:15, Michael Goulish <mgoul...@redhat.com> > wrote: > > > > > > > >> > > > >> Here's the introduction I'm planning on. > > > >> > > > >> If anyone has any opinions, I'd be happy to get them -- > > > >> is there too much detail for a quick intro? Too > > > >> little? A crucial bit I left out? Something I got wrong? > > > >> > > > >> ############################################################## > > > >> > > > >> > > > >> > > > >> > > > >> > > > >> Introduction to Proton > > > >> =============================================== > > > >> > > > >> > > > >> > > > >> The Messenger interface is a simple, high-level API that lets > > > >> you create point-to-point messaging applications quickly and easily. > > > >> > > > >> The interface offers four main categories of functionality. > > > >> > > > >> > > > >> > > > >> > > > >> Messenger Operation > > > >> ----------------------------------------------- > > > >> > > > >> There are only a few operations that are not directly concerning > > > >> with message transmission. > > > >> > > > >> A messenger can be created, named, and freed. It can be started > > > >> and stopped, and it can be checked for errors after any operation. > > > >> > > > >> > > > >> > > > >> > > > >> > > > >> Sending and Receiving > > > >> ----------------------------------------------- > > > >> > > > >> Both sending and receiving happen in two stages, the inner stage > > > >> moving the message between your application and a queue, the > > > >> outer stage transmitting messages between your queues and > > > >> remote messaging nodes. > > > >> > > > >> By changing the ratio of transmissions to queue transfers, you > > > >> can optimize your messaging application for message latency or > > > >> for overall throughput. > > > >> > > > >> Subscriptions control what sources your messenger can receive > > > >> from, and what sources it can send to. Your messenger > > > >> subscribes to the sources you want to receive from, while your > > > >> outgoing messages will be received by messengers that have > > > >> subscribed to your outgoing address. > > > >> > > > >> > > > >> > > > >> > > > >> > > > >> Message Disposition > > > >> ----------------------------------------------- > > > >> > > > >> When you receive messages, you must either accept or reject them. > > > >> > > > >> You can either configure your messenger to automatically accept > > > >> all messages that you get, or you can exercise finer control over > > > >> message acceptance and rejection, individually or in groups. > > > >> > > > >> Trackers and Windows let you set or check the disposition of > > > >> messages in groups. Applying the disposition operations to > > > >> groups of messages can improve your system's throughput. > > > >> > > > >> When receiving messages, you can create a tracker > > > >> for the most recently received message, and later use that tracker > > > >> to accept or reject all messages up to (and including) that one. > > > >> > > > >> When sending messages, you can create a tracker for your most > > > >> recently sent message, and later use it to inquire about the > > > >> remote disposition of all sent messages up to that point. > > > >> If you don't want to let a receiver make you wait forever > > > >> to see what he's going to do, you can set a timeout that will > > > >> control how long he can take making up his mind. > > > >> > > > >> By using incoming and outgoing Windows, you can limit the > > > >> number of messages that these operations affect. > > > >> > > > >> > > > >> > > > >> > > > >> > > > >> > > > >> > > > >> Security > > > >> ----------------------------------------------- > > > >> > > > >> The messenger interface allows you to use the Secure Sockets Layer > > > >> by exposing an interface to the OpenSSL library. > > > >> > > > >> > > > >> > > > >> > > > > > >
