Phil -- Wow, I was thinking of using ASCII.
Let me look at Markdown .... hmm, I do like the sound of this: "radically simplified and far more human readable form of HTML" But what's the value proposition of using any kind of markup? Better readability? Linking with other docs? It seems to me that, at least after a build process, we should have plain ASCII somewhere. Do you agree? But it does seem reasonable to do some form of markup as the foundation and generate other things from there (including flat ASCII). I like the Markdown concept. ( And I think DocBook is way too heavyweight. ) ( And I suppose that nothing but flat ASCII is too lightweight. ) Does anybody else agree ? ------------------------ Mick . ----- Original Message ----- From: "Phil Harvey" <p...@philharveyonline.com> To: proton@qpid.apache.org Sent: Monday, February 25, 2013 8:56:12 PM Subject: Re: [documentation] -- Intro to Proton 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. 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. > >> > >> > >> > >> >
