Documentation update.

README.md

@@ -44,7 +44,7 @@ NAME
 	colf — compile Colfer schemas
 
 SYNOPSIS
-	colf [-b <dir>] [-p <path>] [-v] <language> [<file> ...]
+	colf [ options ] language [ file ... ]
 
 DESCRIPTION
 	Generates source code for the given language. The options are: Go,
@@ -54,25 +54,30 @@ DESCRIPTION
 	the working directory.
 	A package can have multiple schema files.
 
+OPTIONS
   -b directory
     	Use a specific destination base directory. (default ".")
-  -f	Normalizes the format of the schemas on the fly.
+  -f	Normalizes schemas on the fly.
   -l expression
-    	Sets the list limit expression. (default "64 * 1024")
+    	Sets the default upper limit for the number of elements in a
+    	list. The expression is applied to the target language under the
+    	name ColferListMax. (default "64 * 1024")
   -p prefix
     	Adds a package prefix. Use slash as a separator when nesting.
   -s expression
-    	Sets the size limit expression. (default "16 * 1024 * 1024")
-  -v	Enables verbose reporting to the standard output.
+    	Sets the default upper limit for serial byte sizes. The
+    	expression is applied to the target language under the name
+    	ColferSizeMax. (default "16 * 1024 * 1024")
+  -v	Enables verbose reporting to the standard error.
 
 EXIT STATUS
-	The command exits 0 on succes, 1 on compilation failure and 2 when
-	invoked without arguments.
+	The command exits 0 on succes, 1 on compilation failure and 2
+	when invoked without arguments.
 
 EXAMPLES
-	Compile ./src/main/colfer/*.colf into ./target/ as Java:
+	Compile ./api/*.colf into ./src/ as Java:
 
-		colf -p com/example -b target java src/main/colfer
+		colf -p com/example -b src java api
 
 BUGS
 	Report bugs at https://github.com/pascaldekloe/colfer/issues
@@ -93,33 +98,36 @@ Maven users may [disagree](https://github.com/pascaldekloe/colfer/wiki/Java#mave
 Data structures are defined in `.colf` files. The format is quite conventional.
 
 ```
-// Package example offers a quick demonstration.
+// Package demo offers a demonstration.
 // These comment lines will end up in the generated code.
-package example
+package demo
 
 // Coarse is the grounds where the game of golf is played.
 type coarse struct {
 	ID    uint64
 	name  text
 	holes []hole
-	map   binary
+	image binary
 	tags  []text
 }
 
 type hole struct {
 	// Lat is the latitude of the cup.
-	lat   float64
+	lat float64
 	// Lon is the longitude of the cup.
-	lon   float64
+	lon float64
 	// Par is the difficulty index.
-	par   uint8
+	par uint8
 	// Water marks the presence of water.
 	water bool
 	// Sand marks the presence of sand.
-	sand  bool
+	sand bool
 }
 ```
 
+[See](https://gist.github.com/pascaldekloe/f5f15729cceefe430c9858d58e0dd1a3)
+what the generated code looks like.
+
 The following table shows how Colfer data types are applied per language.
 
 | Colfer	| ECMAScript	| Go		| Java		|
@@ -191,6 +199,7 @@ lists.
 Data is represented in a big-endian manner. The format relies on *varints* also
 known as a
 [variable-length quantity](https://en.wikipedia.org/wiki/Variable-length_quantity).
+Bits reserved for future use (*RFU*) must be set to 0.
 
 
 #### Value Definiton
@@ -199,23 +208,30 @@ Each definition starts with an 8-bit header. The 7 least significant bits
 identify the field by its (0-based position) index in the schema. The most
 significant bit is used as a *flag*.
 
-Boolean occurrences set the value to `true`.
+Boolean occurrences set the value to `true`. The flag is RFU.
+
+Unsigned 8-bit integer values just follow the header byte and the flag is RFU.
+Unsigned 16-bit integer values greather than 255 also follow the header byte.
+Smaller values are encoded in one byte with the header flag set.
+Unsigned 32-bit integer values less than 1<<21 are encoded as varints and
+larger values set the header flag for fixed length encoding.
+Unsigned 64-bit integer values less than 1<<49 are encoded as varints and
+larger values set the header flag for fixed length encoding.
 
-Integers are encoded as varints. The header flag indicates negative for signed
-types and fixed size for unsigned types. The tenth byte for 64-bit integers is
-skipped for encoding since its value is fixed to `0x01`.
+Signed 32- and 64-bit integers are encoded as varints. The flag stands for
+negative. The tenth byte for 64-bit integers is skipped for encoding since its
+value is fixed to `0x01`.
 
-Floating points are encoded conform IEEE 754.
+Floating points are encoded conform IEEE 754. The flag is RFU.
 
 Timestamps are encoded as a 32-bit unsigned integer for the number of seconds
 that have elapsed since 00:00:00 UTC, Thursday, 1 January 1970, not counting
 leap seconds. When the header flag is set then the number of seconds is encoded
 as a 64-bit two's complement integer. In both cases the value is followed with
-32 bits for the nanosecond fraction. Note that the first two bits are not in use
-(reserved).
+32 bits for the nanosecond fraction. Note that the first two bits are RFU.
 
 The data for text and binaries is prefixed with a varint byte size declaration.
-Text is encoded as UTF-8.
+Text is encoded as UTF-8. The flag is RFU.
 
 Lists of floating points, text, binaries and data structures are prefixed with a
-varint element size declaration.
+varint element size declaration. The flag is RFU.

cmd/colf/main.go

@@ -15,11 +15,11 @@ import (
 var (
 	basedir = flag.String("b", ".", "Use a specific destination base `directory`.")
 	prefix  = flag.String("p", "", "Adds a package `prefix`. Use slash as a separator when nesting.")
-	format  = flag.Bool("f", false, "Normalizes the format of the schemas on the fly.")
-	verbose = flag.Bool("v", false, "Enables verbose reporting to the standard output.")
+	format  = flag.Bool("f", false, "Normalizes schemas on the fly.")
+	verbose = flag.Bool("v", false, "Enables verbose reporting to the standard error.")
 
-	sizeMax = flag.String("s", "16 * 1024 * 1024", "Sets the size limit `expression`.")
-	listMax = flag.String("l", "64 * 1024", "Sets the list limit `expression`.")
+	sizeMax = flag.String("s", "16 * 1024 * 1024", "Sets the default upper limit for serial byte sizes. The\n    \t`expression` is applied to the target language under the name\n    \tColferSizeMax.")
+	listMax = flag.String("l", "64 * 1024", "Sets the default upper limit for the number of elements in a\n    \tlist. The `expression` is applied to the target language under the\n    \tname ColferListMax.")
 )
 
 var report = log.New(ioutil.Discard, "", 0)
@@ -137,11 +137,8 @@ func init() {
 
 	help := bold + "NAME\n\t" + cmd + clear + " \u2014 compile Colfer schemas\n\n"
 	help += bold + "SYNOPSIS\n\t" + cmd + clear
-	help += " [" + bold + "-b" + clear + " <" + underline + "dir" + clear + ">]"
-	help += " [" + bold + "-p" + clear + " <" + underline + "path" + clear + ">]"
-	help += " [" + bold + "-v" + clear + "]"
-	help += " <" + underline + "language" + clear
-	help += "> [<" + underline + "file" + clear + "> " + underline + "..." + clear + "]\n\n"
+	help += " [ " + underline + "options" + clear + " ] " + underline + "language" + clear
+	help += " [ " + underline + "file" + clear + " " + underline + "..." + clear + " ]\n\n"
 	help += bold + "DESCRIPTION\n\t" + clear
 	help += "Generates source code for the given " + underline + "language" + clear
 	help += ". The options are: " + bold + "Go" + clear + ",\n"
@@ -150,13 +147,14 @@ func init() {
 	help += "\tfiles with the colf extension. If " + underline + "file" + clear + " is absent, " + cmd + " includes\n"
 	help += "\tthe working directory.\n"
 	help += "\tA package can have multiple schema files.\n\n"
+	help += bold + "OPTIONS\n" + clear
 
 	tail := "\n" + bold + "EXIT STATUS" + clear + "\n"
-	tail += "\tThe command exits 0 on succes, 1 on compilation failure and 2 when\n"
-	tail += "\tinvoked without arguments.\n"
+	tail += "\tThe command exits 0 on succes, 1 on compilation failure and 2\n"
+	tail += "\twhen invoked without arguments.\n"
 	tail += "\n" + bold + "EXAMPLES" + clear + "\n"
-	tail += "\tCompile ./src/main/colfer/*.colf into ./target/ as Java:\n\n"
-	tail += "\t\t" + cmd + " -p com/example -b target java src/main/colfer\n"
+	tail += "\tCompile ./api/*.colf into ./src/ as Java:\n\n"
+	tail += "\t\t" + cmd + " -p com/example -b src java api\n"
 	tail += "\n" + bold + "BUGS" + clear + "\n"
 	tail += "\tReport bugs at https://github.com/pascaldekloe/colfer/issues\n\n"
 	tail += bold + "SEE ALSO\n\t" + clear + "protoc(1)\n"