Index: docs/README.txt
===================================================================
--- docs/README.txt
+++ docs/README.txt
@@ -6,7 +6,4 @@
 
 We currently use the 'nature' theme and a Beaker inspired structure.
 
-To rebuild documents into html:
-
-   [/lld/docs]> make html
-
+See sphinx_intro.rst for more details.
Index: docs/WebAssembly.rst
===================================================================
--- docs/WebAssembly.rst
+++ docs/WebAssembly.rst
@@ -1,13 +1,10 @@
 WebAssembly lld port
 ====================
 
-Note: The WebAssembly port is still a work in progress and is be lacking
-certain features.
-
 The WebAssembly version of lld takes WebAssembly binaries as inputs and produces
-a WebAssembly binary as its output.  For the most part this port tried to mimic
-the behaviour of traditional ELF linkers and specifically the ELF lld port.
-Where possible that command line flags and the semantics should be the same.
+a WebAssembly binary as its output.  For the most part it tries to mimic the
+behaviour of traditional ELF linkers and specifically the ELF lld port.  Where
+possible that command line flags and the semantics should be the same.
 
 
 Object file format
@@ -23,14 +20,86 @@
 ``-DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD=WebAssembly``.
 
 
+Usage
+-----
+
+The WebAssembly version of lld is installed as **wasm-ld**.  It shared many 
+common linker flags with **ld.lld** but also includes several
+WebAssembly-specific options:
+
+.. option:: --no-entry
+
+  Don't search for the entry point symbol (by default ``_start``).
+
+.. option:: --export-table
+
+  Export the function table to the environment.
+
+.. option:: --import-table
+
+  Import the function table from the environment.
+
+.. option:: --export-all
+
+  Export all symbols (normally combined with --no-gc-sections)
+
+.. option:: --[no-]export-default
+
+  Export symbols marked as 'default' visibility.  Default: true
+
+.. option:: --global-base=<value>
+
+  Address at which to place global data
+
+.. option:: --[no-]merge-data-segments
+
+  Enable/Disble merging of data segments.  Default: true
+
+.. option:: --stack-first
+
+  Place stack at start of linear memory rather than after data
+
+.. option:: --compress-relocations
+
+  Compress the relocation targets in the code section.
+
+.. option:: --allow-undefined
+
+  Allow undefined symbols in linked binary
+
+.. option:: --import-memory
+
+  Import memory from the environment
+
+.. option:: --initial-memory=<value>
+
+  Initial size of the linear memory. Default: static data size
+
+.. option:: --max-memory=<value>
+
+  Maximum size of the linear memory. Default: unlimited
+
+By default the function table is neither imported nor exported.
+
+Symbols are exported if they are marked as ``visibility=default`` at compile
+time or if they are included on the command line via ``--export``.
+
+Since WebAssembly is designed with size in mind the linker defaults to
+``--gc-sections`` which means that all un-used functions and data segments will
+be stripped from the binary.
+
+The symbols which are preserved by default are:
+
+- The entry point (by default ``_start``).
+- Any symbol which is to be exported.
+- Any symbol transitively referenced by the above.
+
+
 Missing features
 ----------------
 
-There are several key features that are not yet implement in the WebAssembly
-ports:
-
-- COMDAT support.  This means that support for C++ is still very limited.
-- Function stripping.  Currently there is no support for ``--gc-sections`` so
-  functions and data from a given object will linked as a unit.
-- Section start/end symbols.  The synthetic symbols that mark the start and
-  of data regions are not yet created in the output file.
+- Merging of data section similiar to ``SHF_MERGE`` in the ELF world is not
+  supported.
+- No support for creating shared libaries.  The spec for shared libraries in
+  WebAssembly is still in flux:
+  https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md