From 9e03dba41354867b84cd6a7f7ed8e1111776bddf Mon Sep 17 00:00:00 2001
From: Nick Fitzgerald <fitzgen@gmail.com>
Date: Fri, 3 Aug 2018 16:05:14 -0700
Subject: [PATCH] guide: Overhaul the CLI reference content

* Add missing documentation for a couple existing flags.

* Make each flag its own header, so it gets an anchor, and can be permalinked
  to.

* Streamline some content and descriptions.
---
 guide/src/reference/cli.md | 82 ++++++++++++++++++++++++++++----------
 1 file changed, 60 insertions(+), 22 deletions(-)

diff --git a/guide/src/reference/cli.md b/guide/src/reference/cli.md
index 8da60dd68..0a870c63a 100644
--- a/guide/src/reference/cli.md
+++ b/guide/src/reference/cli.md
@@ -1,30 +1,68 @@
 # The `wasm-bindgen` Command Line Interface
 
-The `wasm-bindgen` tool has a number of options available to it to tweak the JS
-that is generated. By default the generated JS uses ES modules and is compatible
-with both Node and browsers (but will likely require a bundler for both use
-cases).
+The `wasm-bindgen` command line tool has a number of options available to it to
+tweak the JavaScript that is generated. The most up-to-date set of flags can
+always be listed via `wasm-bindgen --help`.
 
-Supported flags of the CLI tool can be learned via `wasm-bindgen --help`, but
-some notable options are:
+## Usage
 
-* `--nodejs`: this flag will tailor output for Node instead of browsers,
-  allowing for native usage of `require` of the generated JS and internally
-  using `require` instead of ES modules. When using this flag no further
-  postprocessing (aka a bundler) should be necessary to work with the wasm.
+```
+wasm-bindgen [options] ./target/wasm32-unknown-unknown/release/crate.wasm
+```
 
-* `--browser`: this flag will tailor the output specifically for browsers,
-  making it incompatible with Node. This will basically make the generated JS a
-  tiny bit smaller as runtime checks for Node won't be necessary.
+## Options
 
-* `--no-modules`: the default output of `wasm-bindgen` uses ES modules but this
-  option indicates that ES modules should not be used and output should be
-  tailored for a web browser. More information on this flag, and
-  `--no-modules-global`, can be found in the [no ES modules
-  documentation](./no-esm.html).
+### `--out-dir DIR`
 
-* `--no-typescript`: by default a `*.d.ts` file is generated for the generated
-  JS file, but this flag will disable generating this TypeScript file.
+The target directory to emit the JavaScript bindings, TypeScript definitions,
+processed `.wasm` binary, etc...
 
-* `--debug`: generates a bit more JS and wasm in "debug mode" to help catch
-  programmer errors, but this output isn't intended to be shipped to production.
+### `--nodejs`
+
+This flag will tailor output for Node instead of browsers, allowing for native
+usage of `require` of the generated JS and internally using `require` instead of
+ECMAScript modules. When using this flag no further postprocessing (aka a
+bundler) should be necessary to work with the wasm.
+
+### `--browser`
+
+This flag will tailor the output specifically for browsers, making it
+incompatible with Node. This will basically make the generated JS a tiny bit
+smaller as runtime checks for Node won't be necessary.
+
+### `--no-modules` and  `--no-modules-global VAR`
+
+The default output of `wasm-bindgen` uses ECMAScript modules. These options
+indicate that ECMAScript modules should *not* be used, and that output should be
+tailored for a properties on the JavaScript global object (e.g. `window`).
+
+The `--no-modules-global VAR` option makes `VAR` the global property that the
+JavaScript bindings are attached to.
+
+More information can be found in the [documentation for building without
+ECMAScript modules](./no-esm.html).
+
+### `--typescript`
+
+Output a TypeScript declaration file for the generated JavaScript bindings. This
+is on by default.
+
+### `--no-typescript`
+
+By default, a `*.d.ts` TypeScript declaration file is generated for the
+generated JavaScript bindings, but this flag will disable that.
+
+### `--debug`
+
+Generates a bit more JS and wasm in "debug mode" to help catch programmer
+errors, but this output isn't intended to be shipped to production.
+
+### `--no-demangle`
+
+When post-processing the `.wasm` binary, do not demangle Rust symbols in the
+"names" custom section.
+
+### `--keep-debug`
+
+When post-processing the `.wasm` binary, do not strip DWARF debug info custom
+sections.