Lots of documentation updates for 0.5.

doc/_includes/header.html

@@ -43,6 +43,7 @@
           <li><a href="{{ site.baseurl }}cxxrpc.html">C++ RPC</a></li>
           <li><a href="{{ site.baseurl }}otherlang.html">Other Languages</a></li>
           <li><a href="{{ site.baseurl }}roadmap.html">Road Map</a></li>
+          <li><a href="{{ site.baseurl }}faq.html">FAQ</a></li>
         </ul>
       </section>
       <section id="main_content" class="inner">

doc/cxx.md

 ---
 layout: page
-title: C++ Runtime
+title: C++ Serialization
 ---
 
 # C++ Serialization

doc/cxxrpc.md

 ---
 layout: page
-title: C++ Runtime
+title: C++ RPC
 ---
 
 # C++ RPC
@@ -402,3 +402,9 @@ path name.
 
 For a more complete example, see the
 [calculator server sample](https://github.com/kentonv/capnproto/tree/master/c++/samples/calculator-server.c++).
+
+## Debugging
+
+If you've written a server and you want to connect to it to issue some calls for debugging, perhaps
+interactively, the easiest way to do it is to use [pycapnp](http://jparyani.github.io/pycapnp/).
+The `capnp` tool probably will never add RPC functionality because pycapnp is better.

doc/install.md

@@ -22,9 +22,9 @@ you should keep in mind some caveats:
 * **Performance:** While Cap'n Proto is inherently fast by design, the implementation has not yet
   undergone serious profiling and optimization.  Currently it only beats Protobufs in realistic-ish
   end-to-end benchmarks by around 2x-5x.  We can do better.
-* **RPC:** The RPC protocol has not yet been specified, much less implemented.
-* **Support for languages other than C++:** Work is being done to support languages other than C++,
-  but at this time only the C++ implementation is ready to be used.
+* **RPC:** The RPC implementation is very new (introduced in v0.4 / Dec 2013).  It is missing many
+  features that are essential in real-world use (like timeouts), the interface is still in flux,
+  and it needs a lot of optimization work.
 
 If you'd like to hack on Cap'n Proto, you should join the
 [discussion group](https://groups.google.com/group/capnproto)!
@@ -38,6 +38,9 @@ The Cap'n Proto tools, including the compiler which takes `.capnp` files and gen
 for them, are written in C++.  Therefore, you must install the C++ package even if your actual
 development language is something else.
 
+This package is licensed under the
+[BSD 2-Clause License](http://opensource.org/licenses/BSD-2-Clause).
+
 ### GCC 4.7 or Clang 3.2 Needed
 
 If you are using GCC, you MUST use at least version 4.7 as Cap'n Proto uses recently-implemented
@@ -47,18 +50,21 @@ need to set the environment variable `CXX=g++-4.7` before following the instruct
 If you are using Clang, you must use at least version 3.2.  To use Clang, set the environment
 variable `CXX=clang++` before following any instructions below, otherwise `g++` is used by default.
 
-This package is officially tested on Linux (GCC 4.7, Clang 3.2), Mac OSX (Clang 3.2), and Cygwin
-(Windows; GCC 4.7), in 32-bit and 64-bit modes.
+This package is officially tested on Linux (GCC 4.7, GCC 4.8, Clang 3.2), Mac OSX (Xcode 5), and
+Cygwin (Windows; GCC 4.8), in 32-bit and 64-bit modes.
 
-**Mac OSX users:**  Don't miss the [special instructions for OSX](#clang_32_on_mac_osx).
+Mac/Xcode users:  You must use at least Xcode 5, and you must download the Xcode command-line tools
+under Xcode menu > Preferences > Downloads.  Alternatively, compiler builds from
+[Macports](http://www.macports.org/), [Fink](http://www.finkproject.org/), or
+[Homebrew](http://brew.sh/) are reported to work.
 
 ### Building from a release package
 
 You may download and install the release version of Cap'n Proto like so:
 
-<pre><code>curl -O <a href="http://capnproto.org/capnproto-c++-0.2.1.tar.gz">http://capnproto.org/capnproto-c++-0.2.1.tar.gz</a>
-tar zxf capnproto-c++-0.2.1.tar.gz
-cd capnproto-c++-0.2.1
+<pre><code>curl -O <a href="http://capnproto.org/capnproto-c++-0.0.0.tar.gz">http://capnproto.org/capnproto-c++-0.0.0.tar.gz</a>
+tar zxf capnproto-c++-0.0.0.tar.gz
+cd capnproto-c++-0.0.0
 ./configure
 make -j6 check
 sudo make install</code></pre>
@@ -85,46 +91,6 @@ installed (in addition to Git) in order to fetch the Google Test sources (done b
     make -j6 check
     sudo make install
 
-### Clang 3.2 on Mac OSX
-
-As of this writing, Mac OSX 10.8 with Xcode 4.6 command-line tools is not quite good enough to
-compile Cap'n Proto.  The included version of GCC is ancient.  The included version of Clang --
-which mysteriously advertises itself as version 4.2 -- was actually cut from LLVM SVN somewhere
-between versions 3.1 and 3.2; it is not sufficient to build Cap'n Proto.
-
-There are two options:
-
-1. Use [Macports](http://www.macports.org/), [Fink](http://www.finkproject.org/), or
-   [Homebrew](http://brew.sh/) to get an up-to-date GCC.
-2. Obtain Clang 3.2
-   [directly from the LLVM project](http://llvm.org/releases/download.html).  (Unfortunately,
-   Clang 3.3 apparently does NOT work, because the libc++ headers shipped with XCode contain
-   bugs that Clang 3.3 refuses to compile.)
-
-Option 2 is the one preferred by Cap'n Proto's developers.  Here are step-by-step instructions
-for setting this up:
-
-1. Get the Xcode command-line tools:  Download Xcode from the app store.  Then, open Xcode,
-   go to Xcode menu > Preferences > Downloads, and choose to install "Command Line Tools".
-2. Download the Clang 3.2 binaries and put them somewhere easy to remember:
-
-       curl -O http://llvm.org/releases/3.2/clang+llvm-3.2-x86_64-apple-darwin11.tar.gz
-       tar zxf clang+llvm-3.2-x86_64-apple-darwin11.tar.gz
-       mv clang+llvm-3.2-x86_64-apple-darwin11 ~/clang-3.2
-
-3. We will need to use libc++ (from LLVM) rather than libstdc++ (from GNU) because Xcode's
-   libstdc++ (like its GCC) is too old.  In order for your freshly-downloaded Clang binaries to
-   be able to find it, you'll need to symlink it into the Clang tree:
-
-       ln -s /usr/lib/c++ ~/clang-3.2/lib/c++
-
-You may now follow the instructions below, but make sure to tell `configure` to use your
-newly-downloaded Clang binary:
-
-    ./configure CXX=$HOME/clang-3.2/bin/clang++
-
-Hopefully, Xcode 5.0 will be released soon with a newer Clang, making this extra work unnecessary.
-
 ### Building with Ekam
 
 Ekam is a build system I wrote a while back that automatically figures out how to build your C++

doc/language.md

@@ -280,8 +280,8 @@ group" in Cap'n Proto, which was the case that got into the most trouble with Pr
 
 ### Dynamically-typed Fields
 
-A struct may have a field with type `Object`.  This field's value can be of any pointer type -- i.e.
-any struct, interface, list, or blob.  This is essentially like a `void*` in C.
+A struct may have a field with type `AnyPointer`.  This field's value can be of any pointer type --
+i.e. any struct, interface, list, or blob.  This is essentially like a `void*` in C.
 
 ### Enums
 
@@ -498,7 +498,9 @@ annotation myAnnotation(struct) :Int32 $baz(10);
 const myConst :Int32 = 123 $baz(11);
 {% endhighlight %}
 
-`Void` annotations can omit the value.  Struct-typed annotations are also allowed.
+`Void` annotations can omit the value.  Struct-typed annotations are also allowed.  Tip:  If
+you want an annotation to have a default value, declare it as a struct with a single field with
+a default value.
 
 {% highlight capnp %}
 annotation qux(struct, field) :Void;
@@ -511,6 +513,15 @@ struct MyStruct $qux {
 annotation corge(file) :MyStruct;
 
 $corge(string = "hello", number = 123);
+
+struct Grault {
+  value @0 :Int32 = 123;
+}
+
+annotation grault(file) :Grault;
+
+$grault();  # value defaults to 123
+$grault(value = 456);
 {% endhighlight %}
 
 ### Unique IDs

doc/otherlang.md

@@ -17,14 +17,20 @@ maintained by respective authors and have not been reviewed by me
 
 ##### Works In Progress
 
+* [C](https://github.com/jmckaskill/c-capnproto) by [@jmckaskill](https://github.com/jmckaskill)
 * [Erlang](http://ecapnp.astekk.se/) by [@kaos](https://github.com/kaos)
+* [Go](https://github.com/jmckaskill/go-capnproto) by [@jmckaskill](https://github.com/jmckaskill)
 * [Ruby](https://github.com/cstrahan/capnp-ruby) by [@cstrahan](https://github.com/cstrahan)
 * [Rust](https://github.com/dwrensha/capnproto-rust) by [@dwrensha](https://github.com/dwrensha)
 
-##### Inactive
+##### Non-language Projects
 
-* [C and Go](https://github.com/jmckaskill/go-capnproto) by
-  [@jmckaskill](https://github.com/jmckaskill)
+These are other misc projects related to Cap'n Proto that are not actually implementations in
+new languages.
+
+* [Common Test Framework](https://github.com/kaos/capnp_test) by [@kaos](https://github.com/kaos)
+* [Vim Syntax Highlighting](https://github.com/cstrahan/vim-capnp) by
+  [@cstrahan](https://github.com/cstrahan)
 
 ## Contribute Your Own!
 

doc/roadmap.md

@@ -5,23 +5,26 @@ title: Road Map
 
 # Road Map
 
-Here's what's (hopefully) in store for future versions of Cap'n Proto!
+Here's what's (hopefully) in store for future versions of Cap'n Proto!  Of course, everything here
+is subject to change.
 
-## Next version: 0.4
+## Next version: 0.5
 
-These features are planned for version 0.4.  Some may get pushed back depending on how long
-they take.
+* **Shared memory RPC:**  Zero-copy inter-process communication.  Synchronized with futexes.
+* **Persistent capabilities (level 2 RPC):**  Allow system-assisted saving and restoring of
+  capabilities across connections.
+* **Three-way introductions (level 3 RPC):**  Allow RPC interactions between more than two parties,
+  with new connections formed automatically as needed.
+* **Fiber-based concurrency:**  The C++ runtime's event loop concurrency model will be augmented
+  with support for fibers, which are like threads except that context switches happen only at
+  well-defined points (thus avoiding the need for mutex locking).  Fibers essentially provide
+  syntax sugar on top of the event loop model.
+* **Dynamic schema transmission:**  Allow e.g. Python applications to obtain schemas directly from
+  the RPC server so that they need not have a local copy.  Great for interactive debugging.
 
-* **Generate code for interfaces**
-* **Define RPC protocol**
-* **Implement RPC transports**
-  * **Stream:**  Standard TCP-based RPC.
-  * **Datagram:**  Low-latency UDP-based RPC.
-  * **Shared memory:**  Zero-copy inter-process communication.  Synchronized with futexes.
+## Near future (after 0.5)
 
-## Near future (after 0.4)
-
-Provisionally, these are probably the things that will be worked on after 0.4.
+Provisionally, these are probably the things that will be worked on after 0.5.
 
 * **C++98 Backport:**  Fork and backport the key functionality from the C++11 implementation to
   work under C++98/C++03.  This will make Cap'n Proto accessible to MSVC users.  The schema and
@@ -33,10 +36,6 @@ Provisionally, these are probably the things that will be worked on after 0.4.
   nicer interface which encapsulates the type's inner state.
 * **Implement maps:**  Based on encapsulated and parameterized types.
 
-Note also that after 0.4, Kenton plans to begin devoting some of his time to another project
-built on top of Cap'n Proto.  Experience from this project will help guide future changes to
-Cap'n Proto itelf.
-
 ## Before version 1.0
 
 These things absolutely must happen before any 1.0 release.  Note that it's not yet decided when

doc/rpc.md

@@ -22,7 +22,7 @@ on its result, i.e. `bar(foo())`.  Or -- as is very common in object-oriented pr
 want to call a method on the result of another call, i.e. `foo().bar()`.  With any traditional RPC
 system, this will require two network round trips.  With Cap'n Proto, it takes only one.  In fact,
 you can chain any number of such calls together -- with diamond dependencies and everything -- and
-Cap'n Proto will collapse them all into one call.
+Cap'n Proto will collapse them all into one round trip.
 
 By now you can probably imagine how it works:  if you execute `bar(foo())`, the client sends two
 messages to the server, one saying "Please execute foo()", and a second saying "Please execute