1.1 --- a/maindocs.h	Sat May 24 17:25:06 2008 -0700
     1.2 +++ b/maindocs.h	Sun May 25 10:28:26 2008 -0700
     1.3 @@ -10,7 +10,7 @@
     1.4  
     1.5  /*! \mainpage MYNetwork: Mooseyard Networking library, including BLIP protocol implementation. 
     1.6   
     1.7 -    \section intro_sec Introduction
     1.8 +\section intro_sec Introduction
     1.9   
    1.10      MYNetwork is a set of Objective-C networking classes for Cocoa applications on Mac OS X.
    1.11      It consists of:
    1.12 @@ -24,8 +24,49 @@
    1.13   
    1.14      MYNetwork is released under a BSD license, which means you can freely use it in open-source
    1.15      or commercial projects, provided you give credit in your documentation or About box.
    1.16 +
    1.17 +\section blipdesc What's BLIP?
    1.18   
    1.19 -    \section config Configuration
    1.20 +BLIP is a message-oriented network protocol that lets the two peers on either end of a TCP socket send request and response messages to each other. It's a generic protocol, in that the requests and responses can contain any kind of data you like. 
    1.21 + 
    1.22 +BLIP was inspired by <a
    1.23 +href="http://beepcore.org">BEEP</a> (in fact BLIP stands for "BEEP-LIke Protocol") but is
    1.24 +deliberately simpler and somewhat more limited. That translates to a smaller and cleaner implemenation, especially since it takes advantage of Cocoa's and CFNetwork's existing support for network streams, SSL and Bonjour.
    1.25 + 
    1.26 +\subsection blipfeatures BLIP Features:
    1.27 +
    1.28 + <ul>
    1.29 + <li>Each message is very much like a MIME body, as in email or HTTP: it consists of a
    1.30 +blob of data of arbitrary length, plus a set of key/value pairs called "properties". The
    1.31 +properties are mostly ignored by BLIP itself, but clients can use them for metadata about the
    1.32 +body, and for delivery information (i.e. something like BEEP's "profiles".)
    1.33 +
    1.34 +<li>Either peer can send a request at any time; there's no notion of "client" and "server" roles.
    1.35 + 
    1.36 +<li> Multiple messages can be transmitted simultaneously in the same direction over the same connection, so a very long
    1.37 +message does not block any other messages from being delivered. This means that message ordering
    1.38 +is a bit looser than in BEEP or HTTP 1.1: the receiver will see the beginnings of messages in the
    1.39 +same order in which the sender posted them, but they might not <i>end</i> in that same order. (For
    1.40 +example, a long message will take longer to be delivered, so it may finish after messages that
    1.41 +were begun after it.)
    1.42 +
    1.43 +<li>The sender can indicate whether or not a message needs to be replied to; the response is tagged with the
    1.44 +identity of the original message, to make it easy for the sender to recognize. This makes it
    1.45 +straighforward to implement RPC-style (or REST-style) interactions. (Responses
    1.46 +cannot be replied to again, however.)
    1.47 +
    1.48 +<li>A message can be flagged as "urgent". Urgent messages are pushed ahead in the outgoing queue and
    1.49 +get a higher fraction of the available bandwidth.
    1.50 +
    1.51 +<li>A message can be flagged as "compressed". This runs its body through the gzip algorithm, ideally
    1.52 +making it faster to transmit. (Common markup-based data formats like XML and JSON compress
    1.53 +extremely well, at ratios up to 10::1.) The message is decompressed on the receiving end,
    1.54 +invisibly to client code.
    1.55 + 
    1.56 +<li>The implementation supports SSL connections (with optional client-side certificates), and Bonjour service advertising.
    1.57 +</ul>
    1.58 + 
    1.59 +\section config Configuration
    1.60   
    1.61      MYNetwork requires Mac OS X 10.5 or later, since it uses Objective-C 2 features like
    1.62      properties and for...in loops.
    1.63 @@ -35,19 +76,26 @@
    1.64      which contains the minimal set of MYUtilities files needed to build MYUtilities. (That project
    1.65      has its search paths set up to assume that MYUtilities is in a directory next to MYNetwork.)
    1.66  
    1.67 -    \section download How To Get It
    1.68 +\section download How To Get It
    1.69  
    1.70      <ul>
    1.71 -    <li><a href="http://mooseyard.com/hg/hgwebdir.cgi/MYNetwork/archive/tip.zip">Download the current source code</a>
    1.72 +    <li><a href="/hg/hgwebdir.cgi/MYNetwork/archive/tip.zip">Download the current source code</a>
    1.73      <li>To check out the source code using <a href="http://selenic.com/mercurial">Mercurial</a>:
    1.74 -    \verbatim hg clone http://mooseyard.com/hg/hgwebdir.cgi/MYNetwork/ MYNetwork \endverbatim
    1.75 +    \verbatim hg clone /hg/hgwebdir.cgi/MYNetwork/ MYNetwork \endverbatim
    1.76 +    <li>As described above, you'll also need to download or check out <a href="/hg/hgwebdir.cgi/MYUtilities">MYUtilities</a> and put it in 
    1.77 +    a directory next to MYNetwork.
    1.78      </ul>
    1.79  
    1.80      Or if you're just looking:
    1.81  
    1.82      <ul>
    1.83 -    <li><a href="http://mooseyard.com/hg/hgwebdir.cgi/MYNetwork/file/tip">Browse the source code</a>
    1.84 +    <li><a href="/hg/hgwebdir.cgi/MYNetwork/file/tip">Browse the source code</a>
    1.85      <li><a href="annotated.html">Browse the class documentation</a>
    1.86      </ul>
    1.87   
    1.88 +    There isn't any conceptual documentation yet, beyond what's in the API docs, but you can 
    1.89 +    <a href="/hg/hgwebdir.cgi/MYNetwork/file/tip/BLIP/Demo/">look
    1.90 +    at the sample BLIPEcho client and server</a>, which are based on Apple's 
    1.91 +    <a href="http://developer.apple.com/samplecode/CocoaEcho/index.html">CocoaEcho</a> sample code.
    1.92 + 
    1.93   */