manual.md in bindata-1.4.0 vs manual.md in bindata-1.4.1

@@ -38,11 +38,11 @@
 manipulating.
 
 It supports all the common datatypes that are found in structured binary
 data. Support for dependent and variable length fields is built in. 
 
-Last updated: 2011-06-14
+Last updated: 2011-06-20
 
 ## License
 
 BinData is released under the same license as Ruby.
 
@@ -1083,20 +1083,16 @@
 
     choices = [ type1, type2 ]
     obj = BinData::Choice.new(:choices => choices, :selection => 1)
     obj # => "Type2"
 
-    choices = [ nil, nil, nil, type1, nil, type2 ]
-    obj = BinData::Choice.new(:choices => choices, :selection => 3)
-    obj # => "Type1"
-
     class MyNumber < BinData::Record
       int8 :is_big_endian
       choice :data, :selection => lambda { is_big_endian != 0 },
                     :copy_on_change => true do
-        int32be true
         int32le false
+        int32be true
       end
     end
 
     obj = MyNumber.new
     obj.is_big_endian = 1
@@ -1105,10 +1101,27 @@
 
     obj.is_big_endian = 0
     obj.to_binary_s #=> "\000\005\000\000\000"
 {:ruby}
 
+## Default selection
+
+A key of `:default` can be specified as a default selection.  If the value of the
+selection isn't specified then the :default will be used.  The previous `MyNumber`
+example used a flag for endian.  Zero is little endian while any other value
+is big endian.  This can be concisely written as:
+
+    class MyNumber < BinData::Record
+      int8 :is_big_endian
+      choice :data, :selection => :is_big_endian,
+                    :copy_on_change => true do
+        int32le 0          # zero is little endian
+        int32be :default   # anything else is big endian
+      end
+    end
+{:ruby}
+
 ---------------------------------------------------------------------------
 
 # Advanced Topics
 
 ## Debugging
@@ -1299,9 +1312,31 @@
     class MyData < BinData::Record
       skip :length => 10 * 1024 * 1024
       string :data, :length => 50
     end
 {:ruby}
+
+## Determining stream length
+
+Some file formats don't use length fields but rather read until the end
+of the file.  The stream length is needed when reading these formats.  The
+`count_bytes_remaining` keyword will give the number of bytes remaining in the
+stream.
+
+Consider a string followed by a 2 byte checksum.  The length of the string is
+not specified but is implied by the file length.
+
+    class StringWithChecksum < BinData::Record
+      count_bytes_remaining :bytes_remaining
+      string :the_string, :read_length => lambda { bytes_remaining - 2 }
+      int16le :checksum
+    end
+{:ruby}
+
+These file formats only work with seekable streams (e.g. files).  These formats
+do not stream well as they must be buffered by the client before being
+processed.  Consider using an explicit length when creating a new file format
+as it is easier to work with.
 
 ## Bit-aligned Records
 
 Most structured binary data is byte-aligned.  Any bitfields that occur,
 usually start and end on a byte boundary.  But occasionally you will