You are viewing a plain text version of this content. The canonical link for it is here.
Posted to proton@qpid.apache.org by Michael Goulish <mg...@redhat.com> on 2013/02/25 17:15:04 UTC
[documentation] -- Intro to Proton
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.
Re: [documentation] -- Intro to Proton
Posted by Michael Goulish <mg...@redhat.com>.
Jakub --
Thanks for your thoughts!
Yes, I am thinking of it as part of a larger doc, and yes I
definitely should change that to specify "Proton Messenger API".
I keep forgetting that there are more quarks in this particle than
just the one I am looking at! I'll make that change in next version.
And in addition to the name change, I should also mention in my doc
that there are other interfaces that the Messenger API uses -- maybe
give a quick list of all of them ( engine, driver, whatever ).
Maybe I'll get to do similar docs for each interface.
--------------------------- Mick .
----- Original Message -----
From: "Jakub Scholz" <ja...@scholz.cz>
To: proton@qpid.apache.org
Sent: Monday, February 25, 2013 5:53:29 PM
Subject: Re: [documentation] -- Intro to Proton
Hi Michael,
I know you mentioned plans to write some bigger document ... it is not
entirely clear to me, whether this is supposed to be a standalone
introduction or just a first chapter of the larger document. It suppose the
second is correct, right?
Also, is it introduction to Proton or just to the Proton Messenger API?
>From what I understood so far from the discussions here in the mailing
list, Proton is much more than just the Messenger API. I would either call
it Proton Messenger introduction or add some short explanation that the
Messenger API is just one part of Proton which might be the most
interesting for beginners.
Thanks & Regards
Jakub
On Mon, Feb 25, 2013 at 5:15 PM, Michael Goulish <mg...@redhat.com>wrote:
> The messenger interface allows you to use the Secure Sockets Layer
> by exposing an interface to the OpenSSL library.
>
Re: [documentation] -- Intro to Proton
Posted by Jakub Scholz <ja...@scholz.cz>.
Hi Michael,
I know you mentioned plans to write some bigger document ... it is not
entirely clear to me, whether this is supposed to be a standalone
introduction or just a first chapter of the larger document. It suppose the
second is correct, right?
Also, is it introduction to Proton or just to the Proton Messenger API?
>From what I understood so far from the discussions here in the mailing
list, Proton is much more than just the Messenger API. I would either call
it Proton Messenger introduction or add some short explanation that the
Messenger API is just one part of Proton which might be the most
interesting for beginners.
Thanks & Regards
Jakub
On Mon, Feb 25, 2013 at 5:15 PM, Michael Goulish <mg...@redhat.com>wrote:
> The messenger interface allows you to use the Secure Sockets Layer
> by exposing an interface to the OpenSSL library.
>
Re: [documentation] -- Intro to Proton
Posted by Rafael Schloming <rh...@alum.mit.edu>.
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 <ac...@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" <ra...@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 <mg...@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" <ph...@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 <mg...@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.
> > > >>
> > > >>
> > > >>
> > > >>
> > >
>
>
>
Re: [documentation] -- Intro to Proton
Posted by Alan Conway <ac...@redhat.com>.
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" <ra...@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 <mg...@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" <ph...@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 <mg...@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.
> > >>
> > >>
> > >>
> > >>
> >
Re: [documentation] -- Intro to Proton
Posted by Rajith Attapattu <ra...@gmail.com>.
Phil,
I think it's worth experimenting with an approach that has a low
barrier-to-entry.
Markdown seems very very appealing. Anytime you can get away with
plain text, it's great.
And as Alan mentioned, the source doc itself can be a finished product.
So my +1 for trying this.
Regards,
Rajith
On Mon, Feb 25, 2013 at 8:56 PM, Phil Harvey <ph...@philharveyonline.com> 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.
>
> 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" <ra...@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 <mg...@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" <ph...@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 <mg...@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.
>> >>
>> >>
>> >>
>> >>
>>
Re: [documentation] -- Intro to Proton
Posted by Alan Conway <ac...@redhat.com>.
On Tue, 2013-02-26 at 10:37 -0500, Michael Goulish wrote:
> Phil --
>
> Wow, I was thinking of using ASCII.
Markdown is 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?
We need to provide docs in HTML and PDF. It is impossible to generate
useful HTML or PDF from arbitrarily structured ASCII.
> It seems to me that, at least after a build process, we should have
> plain ASCII somewhere. Do you agree?
Markdown is plain ASCII but with fixed conventions about how to
represent headings, bold, italic etc. It is intended to be readable as
plain ascii as well as being structured enough to generate HTML etc.
>
> 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 ?
>
Yep. I've never tried it but I think its worth a try. Docbook is a pain.
My main concern is how we verify that changes to the doc are valid
markdown. Anyone know of approaches to that?
Re: [documentation] -- Intro to Proton
Posted by Michael Goulish <mg...@redhat.com>.
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" <ph...@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" <ra...@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 <mg...@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" <ph...@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 <mg...@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.
> >>
> >>
> >>
> >>
>
Re: [documentation] -- Intro to Proton
Posted by Phil Harvey <ph...@philharveyonline.com>.
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" <ra...@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 <mg...@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" <ph...@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 <mg...@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.
> >>
> >>
> >>
> >>
>
Re: [documentation] -- Intro to Proton
Posted by Rajith Attapattu <ra...@gmail.com>.
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 <mg...@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" <ph...@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 <mg...@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.
>>
>>
>>
>>
Re: [documentation] -- Intro to Proton
Posted by Michael Goulish <mg...@redhat.com>.
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" <ph...@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 <mg...@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.
>
>
>
>
Re: [documentation] -- Intro to Proton
Posted by Phil Harvey <ph...@philharveyonline.com>.
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 <mg...@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.
>
>
>
>