More doc updates.

doc/encoding.md

@@ -159,71 +159,21 @@ A struct pointer looks like this:
     C (16 bits) = Size of the struct's data section, in words.
     D (16 bits) = Size of the struct's pointer section, in words.
 
-#### Field Positioning
-
-_WARNING:  You should not attempt to implement the following algorithm.  The compiled schemas
-produced by the Cap'n Proto compiler are already populated with offset information, so code
-generators and other consumers of compiled schemas should never need to compute them manually.
-The algorithm is complicated and easy to get wrong, so it is best to rely on the canonical
-implementation._
-
-Ignoring unions, the layout of fields within the struct is determined by the following algorithm:
-
-    For each field of the struct, ordered by field number {
-        If the field is a pointer {
-            Add it to the end of the pointer section.
-        } else if the data section layout so far includes properly-aligned
-                padding large enough to hold this field {
-            Replace the padding space with the new field, preferring to
-                put the field as close to the beginning of the section as
-                possible.
-        } else {
-            Add one word to the end of the data section.
-            Place the new field at the beginning of the new word.
-            Mark the rest of the new word as padding.
-        }
-    }
-
-Keep in mind that `Bool` fields are bit-aligned, so multiple booleans will be packed into a
-single byte.  As always, little-endian ordering is the standard -- the first boolean will be
-located at the least-significant bit of its byte.
-
-When unions are present, add the following logic:
-
-    For each field and union of the struct, ordered by field number {
-        If this is a union, not a field {
-            Treat it like a 16-bit field, representing the union tag.
-                (See no-union logic, above.)
-        } else if this field is a member of a union {
-            If an earlier member of the union is in the same section as
-                    this field and it combined with any following padding
-                    is at least as large as the new field {
-                Give the new field the same offset and the highest-numbered
-                    such previous field, so they overlap.
-            } else {
-                Assign a new offset to this field as if it were not a union
-                    member at all.  (See no-union logic, above.)
-            }
-        } else {
-            Assign an offset as normal.  (See no-union logic, above.)
-        }
-    }
-
-Note that in the worst case, the members of a union could end up using 23 bytes plus one bit (one
-pointer plus data section locations of 64, 32, 16, 8, and 1 bits).  This is an unfortunate side
-effect of the desire to pack fields in the smallest space where they will fit and the need to
-maintain backwards-compatibility as fields are added.  The worst case should be rare in practice,
-and can be avoided entirely by always declaring a union's largest member first.
-
-Inline fields add yet more complication.  An inline field may contain some data and some pointers,
-which are positioned independently.  If the data part is non-empty but is less than one word, it is
-rounded up to the nearest of 1, 2, or 4 bytes and treated the same as a field of that size.
-Otherwise, it is added to the end of the data section.  Any pointers are added to the end of the
-pointer section.  When an inline field appears inside a union, it will attempt to overlap with a
-previous union member just like any other field would -- but note that because inline fields can
-have non-power-of-two sizes, such unions can get arbitrarily large, and care should be taken not
-to interleave union field numbers with non-union field numbers due to the problems described in
-the previous paragraph.
+Fields are positioned within the struct according to an algorithm with the following principles:
+
+* The position of each field depends only on its definition and the definitions of lower-numbered
+  fields, never on the definitions of higher-numbered fields.  This ensures backwards-compatibility
+  when new fields are added.
+* Due to alignment reqirements, fields in the data section may be separated by padding.  However,
+  later-numbered fields may be positioned into the padding left between earlier-numbered fields.
+  Because of this, a struct will never contain more than 63 bits of padding.  Since objects are
+  rounded up to a whole number of words anyway, padding never ends up wasting space.
+* Unions and groups need not occupy contiguous memory.  Indeed, they may have to be split into
+  multiple slots if new fields are added later on.
+
+Field offsets are computed by the Cap'n Proto compiler.  The precise algorithm is too complicated
+to describe here, but you need not implement it yourself, as the compiler can produce a compiled
+schema format which includes offset information.
 
 #### Default Values
 

doc/install.md

@@ -50,7 +50,45 @@ variable `CXX=clang++` before following any instructions below, otherwise `g++`
 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.
 
-##### Clang 3.2 on Mac OSX
+**Mac OSX users:**  Don't miss the [special instructions for OSX](#clang_32_on_mac_osx).
+
+### 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
+./configure
+make -j6 check
+sudo make install</code></pre>
+
+This will install `capnp`, the Cap'n Proto command-line tool.  It will also install `libcapnp`,
+`libcapnpc`, and `libkj` in `/usr/local/lib` and headers in `/usr/local/include/capnp` and
+`/usr/local/include/kj`.
+
+On Linux, if running `capnp` immediately after installation produces an error complaining about
+missing libraries, run `sudo ldconfig` and try again.
+
+### Building from Git with Autotools
+
+If you download directly from Git, and you don't want to
+[build with Ekam](install.html#building_with_ekam), you will need to have the GNU autotools --
+[autoconf](http://www.gnu.org/software/autoconf/),
+[automake](http://www.gnu.org/software/automake/), and
+[libtool](http://www.gnu.org/software/libtool/) -- installed.  You will also need Subversion
+installed (in addition to Git) in order to fetch the Google Test sources (done by
+`setup-autotools.sh`).
+
+    git clone https://github.com/kentonv/capnproto.git
+    cd capnproto/c++
+    ./setup-autotools.sh
+    autoreconf -i
+    ./configure
+    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 --
@@ -90,42 +128,6 @@ newly-downloaded Clang binary:
 
 Hopefully, Xcode 5.0 will be released soon with a newer Clang, making this extra work unnecessary.
 
-### 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
-./configure
-make -j6 check
-sudo make install</code></pre>
-
-This will install `capnp`, the Cap'n Proto command-line tool.  It will also install `libcapnp`,
-`libcapnpc`, and `libkj` in `/usr/local/lib` and headers in `/usr/local/include/capnp` and
-`/usr/local/include/kj`.
-
-On Linux, if running `capnp` immediately after installation produces an error complaining about
-missing libraries, run `sudo ldconfig` and try again.
-
-### Building from Git with Autotools
-
-If you download directly from Git, and you don't want to
-[build with Ekam](install.html#building_with_ekam), you will need to have the GNU autotools --
-[autoconf](http://www.gnu.org/software/autoconf/),
-[automake](http://www.gnu.org/software/automake/), and
-[libtool](http://www.gnu.org/software/libtool/) -- installed.  You will also need Subversion
-installed (in addition to Git) in order to fetch the Google Test sources (done by
-`setup-autotools.sh`).
-
-    git clone https://github.com/kentonv/capnproto.git
-    cd capnproto/c++
-    ./setup-autotools.sh
-    autoreconf -i
-    ./configure
-    make -j6 check
-    sudo make install
-
 ### 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

@@ -12,7 +12,7 @@ manipulate that message type in your desired language.
 
 For example:
 
-{% highlight capnproto %}
+{% highlight capnp %}
 # unique file ID, generated by `capnp id`
 @0xdbb9ad1f14bf0b36;
 

doc/otherlang.md

@@ -12,15 +12,19 @@ maintained by respective authors and have not been reviewed by me
 ##### Ready To Use
 
 * [C++](cxx.html) by [@kentonv](https://github.com/kentonv) -- Official reference implementation
+* [Python](https://github.com/jparyani/capnpc-python-cpp) by
+  [@jparyani](https://github.com/jparyani) -- Based on C extensions wrapping the C++ implementation.
 
 ##### Works In Progress
 
+* [Erlang](http://ecapnp.astekk.se/) by [@kaos](https://github.com/kaos)
+* [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
+
 * [C and Go](https://github.com/jmckaskill/go-capnproto) by
   [@jmckaskill](https://github.com/jmckaskill)
-* [Python (via C extensions)](https://github.com/jparyani/capnpc-python-cpp) by
-  [@jparyani](https://github.com/jparyani)
-* [Rust](https://github.com/dwrensha/capnproto-rust) by [@dwrensha](https://github.com/dwrensha)
-* [Ruby](https://github.com/cstrahan/capnp-ruby) by [@cstrahan](https://github.com/cstrahan)
 
 ## Contribute Your Own!