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" <[email protected]> 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 <[email protected]> > > 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" <[email protected]> > > > To: [email protected] > > > 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 <[email protected]> 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. > > >> > > >> > > >> > > >> > >
