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

README.md

@@ -33,10 +33,14 @@ 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 do not have
-extension `.toml` or `.hsh` are ignored. The former are copied unchanged;
-the latter are transformed per the husht language specification into
-Rust `.rs` files.
+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
@@ -45,11 +49,45 @@ Options:
     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.
+    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, if the `src` directory contains `main.hsh`, `sub/crate.hsh`, and
-`Cargo.toml` (and there are no other .hsh or .toml files in the directory
-tree), then `husht src` would write `rust/main.rs`, `rust/sub/crate.rs`, and
-`rust/Cargo.toml`. On the other hand just `husht`, defaulting to `husht .`,
-would write `rust/src/main.rs`, `rust/src/sub/crate.rs`, and
-`rust/src/Cargo.toml`.
+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
+```