Improve documentation

- Document the various ways files can be included and excluded from torrents in the book. - Make links to the book more prominent in the readme, by including them in sections with obvious names. type: documentation
casey · Apr 25, 2020 · d077da4 · d077da4
1 parent f8711a7
commit d077da4
Show file tree

Hide file tree

Showing 4 changed files with 107 additions and 4 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,9 +2,10 @@ Changelog
 =========
 
 
-UNRELEASED - 2020-04-24
+UNRELEASED - 2020-04-25
 -----------------------
-- :wrench: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Improve the done and merge recipes - _Casey Rodarmor <casey@rodarmor.com>_
+- :books: [`xxxxxxxxxxxx`](https://github.com/casey/intermodal/commits/master) Improve documentation - _Casey Rodarmor <casey@rodarmor.com>_
+- :wrench: [`f8711a79a3d9`](https://github.com/casey/intermodal/commit/f8711a79a3d92da5b30fd3e8b7bba7a5e2d73766) Improve the done and merge recipes - _Casey Rodarmor <casey@rodarmor.com>_
 - :wrench: [`97ee5684f8e0`](https://github.com/casey/intermodal/commit/97ee5684f8e0f8de7dbdb4f930018c8df0f012b1) Don't invalid build cache when `Cargo.lock` changes - _Casey Rodarmor <casey@rodarmor.com>_
 - :books: [`c75ec39b14bb`](https://github.com/casey/intermodal/commit/c75ec39b14bb4375a875d2d2c73718b44eb54e12) Remove watch dropdown image from readme - _Casey Rodarmor <casey@rodarmor.com>_
 - :books: [`8fbe39726fe6`](https://github.com/casey/intermodal/commit/8fbe39726fe6c5bdc342dbd0764f8052ddd03597) Add notes for packagers to readme - _Casey Rodarmor <casey@rodarmor.com>_

diff --git a/README.md b/README.md
@@ -26,6 +26,10 @@ For more about the project and its goals, check out
   - [Linux and MacOS Install Script](#linux-and-macos-install-script)
   - [Cargo](#cargo)
   - [Shell Completion Scripts](#shell-completion-scripts)
+- [Usage](#usage)
+  - [Commands](#commands)
+  - [Examples](#examples)
+  - [FAQ](#faq)
 - [Notes for Packagers](#notes-for-packagers)
   - [Package Artifacts](#package-artifacts)
     - [Binary](#binary)
@@ -131,6 +135,36 @@ command will write the Z shell completion script to `$fpath[0]/_imdl`:
 $ imdl completions --shell zsh --dir $fpath[0]
 ```
 
+
+## Usage
+
+Online documentation is available in the book, hosted
+[here](https://imdl.io/book/).
+
+### Commands
+
+Adding `--help` to any command will print help text about how to use that
+command, including detailed information about any command-line arguments it
+accepts.
+
+So, to get information about `imdl torrent create`, run `imdl torrent create
+--help`.
+
+Additionally, the same help text is available online in
+[the book](https://imdl.io/book/).
+
+### Examples
+
+The intro to [the book](https://imdl.io/book/) has a few simple examples. Check
+[the FAQ](https://imdl.io/book/faq.html) for more complex usage examples.
+
+### FAQ
+
+The [FAQ](https://imdl.io/book/faq.html) covers a variety of specific
+use-cases. If there's a use case you think should be covered, feel free to open
+[an issue](https://github.com/casey/intermodal/issues/new).
+
+
 ## Notes for Packagers
 
 First off, thank you very much! If I can do anything to make packaging

diff --git a/bin/gen/config.yaml b/bin/gen/config.yaml
@@ -123,7 +123,7 @@ references:
       description: 'Grin Slate Serialization'
 
 faq:
-- title: Can intermodal be used to preview torrents with `fzf`?
+- title: Can Intermodal be used to preview torrents with `fzf`?
   anchor: fzf-preview
   text: |-
     Yes! [@mustaqimM](https://github.com/mustaqimM) came up with the following:
@@ -136,7 +136,7 @@ faq:
 
         find . -name '*.torrent' | fzf --preview='imdl -c always -t torrent show -i {}'
 
-- title: Can intermodal be used to create a torrent from a Git repo?
+- title: Can Intermodal be used to create a torrent from a Git repo?
   anchor: git-repo
   text: |-
     Yes! The `--ignore` flag, contributed by [@Celeo](https://github.com/Celeo), can be used
@@ -151,3 +151,41 @@ faq:
     Equivalently, with short flags:
 
         imdl torrent create --ignore -hjg '!.git/*' -i .
+
+- title: How do I include and exclude files when creating a torrent?
+  anchor: include
+  text: |-
+    There are a few ways to control which files are included when you create a torrent.
+
+    By default, symlinks, hidden files, and common "junk" files are excluded. To include these files, use:
+
+    - `--follow-symlinks` to include files pointed to by a symlink.
+    - `--include-hidden` to include files with names that start with `.` or are hidden by a file attribute.
+    - `--include-junk` to include "junk" files like `.DS_Store`.
+
+    The `--ignore` flag makes Intermodal respect `.gitignore` and `.ignore` files.
+
+    This can be used to [create a torrent from a Git repository](#git-repo), or to exclude files by creating a file called `.ignore`, adding patterns with the same syntax as `.gitignore` that match those files, and using `--ignore` when you create the torrent.
+
+    Additionally, you can use `--glob PATTERN` to both include and exclude files.
+
+    If `PATTERN` does not start with `!`, only those files that match `PATTERN` will be included.
+
+    If `PATTERN` starts with `!`, those files that match `PATTERN` will be excluded.
+
+    `--glob` can be passed multiple times, to include multiple subsets of files:
+
+        # only include `foo/bar` and `foo/bob`
+        imdl torrent create --input foo --glob bar/ --glob bob/
+
+    To exclude multiple subsets of files:
+
+        # don't include `foo/bar` and `foo/bob`
+        imdl torrent create --input foo --glob '!bar/' --glob '!bob/'
+
+    Or to refine a pattern:
+
+        # include everything in `foo/bar` but not anything in `foo/bar/baz`
+        imdl torrent create --input foo --glob `bar/` --glob `!bar/baz/`
+
+    `--glob` can be passed any number of times. If multiple `PATTERN`s match a path, the last one on the command line takes precedence.
diff --git a/bin/gen/templates/README.md b/bin/gen/templates/README.md
@@ -108,6 +108,36 @@ command will write the Z shell completion script to `$fpath[0]/_imdl`:
 $ imdl completions --shell zsh --dir $fpath[0]
 ```
 
+
+## Usage
+
+Online documentation is available in the book, hosted
+[here](https://imdl.io/book/).
+
+### Commands
+
+Adding `--help` to any command will print help text about how to use that
+command, including detailed information about any command-line arguments it
+accepts.
+
+So, to get information about `imdl torrent create`, run `imdl torrent create
+--help`.
+
+Additionally, the same help text is available online in
+[the book](https://imdl.io/book/).
+
+### Examples
+
+The intro to [the book](https://imdl.io/book/) has a few simple examples. Check
+[the FAQ](https://imdl.io/book/faq.html) for more complex usage examples.
+
+### FAQ
+
+The [FAQ](https://imdl.io/book/faq.html) covers a variety of specific
+use-cases. If there's a use case you think should be covered, feel free to open
+[an issue](https://github.com/casey/intermodal/issues/new).
+
+
 ## Notes for Packagers
 
 First off, thank you very much! If I can do anything to make packaging