doc: Copy all non-hsh files, not just .toml; lay out examples

README.md

@@ -23,3 +23,71 @@ into the Rust code.
 
 Documentation of specific syntax features of husht will be added as they are
 implemented.
+
+## Usage
+
+`husht [options] [sources]`
+
+Transforms some files from husht to Rust. The source specification `sources`
+is a list of files, directories or glob patterns, defaulting to `.`. A
+directory `dir` is interpreted the same way as the glob pattern `dir/**` --
+in other words, all files recursively within that directory. Glob patterns
+are matched and all matching files are added to the list of files to process.
+All files in the output directory are ignored. Files that have
+extension `.hsh` are transformed per the husht language specification into
+Rust `.rs` files, which are written to the appropriate destination specified
+by the options described below. All other files to process are copied
+unchanged to the destination. The latter convention allows `.toml` files, and
+potentially other associated files, to be co-located with the source and yet
+end up in the appropriate place in an intermediate build location with the
+generated Rust code.
+
+Options:
+  - -h, --help -- Print a usage summary and exit
+  - --out-dir [dir] -- Specifies the output directory of the transformed
+    file(s), defaulting to `rust`. The transform of each source file is
+    written into the output directory, preserving its relative path to its
+    "root". The root of a file added by virtue of a glob is the top level
+    directory of that glob pattern, or the current directory if none.
+    The root of a file specified explicitly is the current directory. If a
+    file is not within the tree starting from what would otherwise be its
+    root, its root is considered to be its directory. (In other words, the
+    destination for that file will be the `--out-dir` itself.)
+
+For example, suppose the current directory is the top-level directory of your
+project and is laid out like so:
+
+```
+src
+├─ main.hsh
+├─ Cargo.toml
+└─ sub
+   └─ crate.hsh
+rust
+└─ jnk.txt
+```
+
+Then after `husht src` the `rust` directory would look like:
+
+```
+rust
+├─ jnk.txt
+├─ main.rs
+├─ Cargo.toml
+└─ sub
+   └─ crate.rs
+```
+(Note that the `rust` directory does not have to exist prior to the `husht`
+command; if it had not, the results would look the same, except that of course
+`jnk.txt` would not be there.)
+
+On the other hand, just `husht`, defaulting to `husht .`, would produce:
+```
+rust
+├─ jnk.txt
+└─ src
+   ├─ main.rs
+   ├─ Cargo.toml
+   └─ sub
+      └─ crate.rs
+```