Document capnp tool and constants.

doc/_includes/header.html

@@ -38,6 +38,7 @@
           <li><a href="{{ site.baseurl }}language.html">Schema Language</a></li>
           <li><a href="{{ site.baseurl }}encoding.html">Encoding</a></li>
           <li><a href="{{ site.baseurl }}rpc.html">RPC Protocol</a></li>
+          <li><a href="{{ site.baseurl }}capnp-tool.html">The <code>capnp</code> Tool</a></li>
           <li><a href="{{ site.baseurl }}cxx.html">C++ Runtime</a></li>
           <li><a href="{{ site.baseurl }}otherlang.html">Other Languages</a></li>
         </ul>

doc/capnp-tool.md

+---
+layout: page
+title: The capnp Tool
+---
+
+# The `capnp` Tool
+
+Cap'n Proto comes with a command-line tool called `capnp` intended to aid development and
+debugging.  This tool can be used to:
+
+* Compile Cap'n Proto schemas to produce source code in multiple languages.
+* Generate unique type IDs.
+* Decode Cap'n Proto messages to human-readable text.
+* Encode text representations of Cap'n Proto messages to binary.
+* Evaluate and extract constants defined in Cap'n Proto schemas.
+
+This page summarizes the functionality.  A complete reference on the command's usage can be
+found by typing:
+
+    capnp help
+
+## Compiling Schemas
+
+    capnp compile -oc++ myschema.capnp
+
+This generates files `myschema.capnp.h` and `myschema.capnp.c++` which contain C++ source code
+corresponding to the types defined in `myschema.capnp`.  Options exist to control output location
+and import paths.
+
+The above example generates C++ code, but the tool is able to generate output in any language
+for which a plugin is available.  Compiler plugins are just regular programs named
+`capnpc-language`.  For example, the above command runs `capnpc-c++`.  [More on how to write
+compiler plugins](http://localhost:4000/capnproto/otherlang.html#how_to_write_compiler_plugins).
+
+Note that some Cap'n Proto implementations (especially for interpreted languages) do not require
+generating source code.
+
+## Decoding Messages
+
+    capnp decode myschema.capnp MyType < message.bin > message.txt
+
+`capnp decode` reads a binary Cap'n Proto message from standard input and decodes it to a
+human-readable text format (specifically, the format used for specifying constants and default
+values in [the schema language](http://localhost:4000/capnproto/language.html)).  By default it
+expects an unpacked message, but you can decode a
+[packed](http://localhost:4000/capnproto/encoding.html#packing) message with the `--packed` flag.
+
+## Encoding Messages
+
+    capnp encode myschema.capnp MyType < message.txt > message.bin
+
+`capnp encode` is the opposite of `capnp decode`: it takes a text-format message on stdin and
+encodes it to binary (possibly [packed](http://localhost:4000/capnproto/encoding.html#packing),
+with the `--packed` flag).
+
+This is mainly useful for debugging purposes, to build test data or to apply tweaks to data
+decoded with `capnp decode`.  You should not rely on `capnp encode` for encoding data written
+and maintained in text format long-term -- instead, use `capnp eval`, which is much more powerful.
+
+## Evaluating Constants
+
+    capnp eval myschema.capnp myConstant
+
+This prints the value of `myConstant`, a
+[const](http://localhost:4000/capnproto/language.html#constants) declaration, after applying
+variable substitution.  It can also output the value in binary format (`--binary` or `--packed`).
+
+At first glance, this may seem no more interesting that `capnp encode`:  the syntax used to define
+constants in schema files is the same as the format accepted by `capnp encode`, right?  There is,
+however, a big difference:  constants in schema files may be defined in terms of other constants,
+which may even be imported from other files.
+
+As a result, `capnp eval` is a great basis for implementing config files.  For example, a large
+company might maintain a production server that serves dozens of clients and needs configuration
+information about each one.  Rather than maintaining the config as one enormous file, it can be
+written as several separate files with a master file that imports the rest.
+
+Such a configuration should be compiled to binary format using `capnp eval` before deployment,
+in order to verify that there are no errors and to make deployment easier and faster.  While you
+could techincally ship the text configs to production and have the servers parse them directly
+(e.g. with `capnp::SchemaParser`), encoding before deployment is more efficient and robust.

doc/cxx.md

@@ -321,7 +321,7 @@ the enum's values are scoped within the type.  E.g. for an enum `Foo` with value
 refer to the value as `Foo::BAR`.
 
 To match prevaling C++ style, an enum's value names are converted to UPPERCASE_WITH_UNDERSCORES
-(whereas in the definition language you'd write them in camelCase).
+(whereas in the schema language you'd write them in camelCase).
 
 Keep in mind when writing `switch` blocks that an enum read off the wire may have a numeric
 value that is not listed in its definition.  This may be the case if the sender is using a newer
@@ -343,7 +343,11 @@ Interfaces (RPC) are not yet implemented at this time.
 
 ### Constants
 
-Constants are not yet implemented at this time.  (They are not hard, but they are low-priority.)
+Constants are exposed with their names converted to UPPERCASE_WITH_UNDERSCORES naming style
+(whereas in the schema language you’d write them in camelCase).  Primitive constants are just
+`constexpr` values.  Pointer-type constants (e.g. structs, lists, and blobs) are represented
+using a proxy object that can be converted to the relevant `Reader` type, either implicitly or
+using the unary `*` or `->` operators.
 
 ## Messages and I/O
 

doc/javascripts/main.js

@@ -40,9 +40,14 @@ function initSidebar() {
     var href = link.href;
     if (href.lastIndexOf(filename) >= 0) {
       var parent = link.parentNode;
-      parent.removeChild(link);
       var p = document.createElement("p");
-      p.appendChild(document.createTextNode(link.innerText || link.textContent));
+
+      while (link.childNodes.length > 0) {
+        var child = link.childNodes[0];
+        link.removeChild(child);
+        p.appendChild(child);
+      }
+      parent.removeChild(link);
       p.onclick = (function(url) {
         return function(event) {
           window.location.href = url;

doc/language.md

@@ -267,13 +267,30 @@ reference to an object inherently represents a "capability" to access it.
 ### Constants
 
 You can define constants in Cap'n Proto.  These don't affect what is sent on the wire, but they
-will be included in the generated code.
+will be included in the generated code, and can be [evaluated using the `capnp`
+tool](http://localhost:4000/capnproto/capnp-tool.html#evaluating_constants).
 
 {% highlight capnp %}
 const pi :Float32 = 3.14159;
 const bob :Person = (name = "Bob", email = "bob@example.com");
 {% endhighlight %}
 
+Additionally, you may refer to a constant inside another value (e.g. another constant, or a default
+value of a field).
+
+{% highlight capnp %}
+const foo :Int32 = 123;
+const bar :Text = "Hello";
+const baz :SomeStruct = (id = .foo, message = .bar);
+{% endhighlight %}
+
+Note that when substituting a constant into another value, the constant's name must be qualified
+with its scope.  E.g. if a constant `qux` is declared nested in a type `Corge`, it would need to
+be referenced as `Corge.qux` rather than just `qux`, even when used within the `Corge` scope.
+Constants declared at the top-level scope are prefixed just with `.`.  This rule helps to make it
+clear that the name refers to a user-defined constant, rather than a literal value (like `true` or
+`inf`) or an enum value.
+
 ### Nesting, Scope, and Aliases
 
 You can nest constant, alias, and type definitions inside structs and interfaces (but not enums).

doc/stylesheets/stylesheet.css

@@ -177,6 +177,10 @@ pre, code {
   -webkit-border-radius: 2px;
 }
 
+h1>code {
+	font-size: 30px;
+}
+
 pre {
   width: -moz-calc(100% - 20px);
   width: -webkit-calc(100% - 20px);