Substitute usage information into the documentation

This will simplify keeping documentation in sync with the code.

docs/README.md

@@ -1,3 +1,10 @@
 This is an [mdbook](https://rust-lang.github.io/mdBook/index.html) book.
 Minor modifications can be made without installing the mdbook tool, as the content is simple Markdown.
 Changes are verified on pull requests.
+
+To build the docs locally, you will need to build `usage-docs`:
+
+```
+cargo build -p taskchampion-cli --feature usage-docs --bin usage-docs
+mdbook build docs/
+```

docs/book.toml

@@ -7,3 +7,6 @@ title = "TaskChampion"
 
 [output.html]
 default-theme = "ayu"
+
+[preprocessor.usage-docs]
+command = "target/debug/usage-docs"

docs/build.sh

@@ -1,23 +0,0 @@
-#! /bin/bash
-
-REMOTE=origin
-
-set -e
-
-if ! [ -f "./src/SUMMARY.md" ]; then
-    echo "Run this from the docs/ dir"
-    exit 1
-fi
-
-if ! [ -d ./tmp ]; then
-    git worktree add tmp gh-pages
-fi
-
-(cd tmp && git pull $REMOTE gh-pages)
-
-rm -rf tmp/*
-mdbook build
-cp -rp book/* tmp
-(cd tmp && git add -A)
-(cd tmp && git commit -am "update docs")
-(cd tmp && git push $REMOTE gh-pages:gh-pages)

docs/src/SUMMARY.md

@@ -3,9 +3,11 @@
 - [Welcome to TaskChampion](./welcome.md)
   * [Installation](./installation.md)
   * [Using the Task Command](./using-task-command.md)
-    * [Configuration](./config-file.md)
     * [Reports](./reports.md)
     * [Tags](./tags.md)
+    * [Filters](./filters.md)
+    * [Modifications](./modifications.md)
+    * [Configuration](./config-file.md)
     * [Environment](./environment.md)
     * [Synchronization](./task-sync.md)
   * [Running the Sync Server](./running-sync-server.md)

docs/src/filters.md

@@ -0,0 +1,9 @@
+# Filters
+
+Filters are used to select specific tasks for reports or to specify tasks to be modified.
+When more than one filter is given, only tasks which match all of the filters are selected.
+When no filter is given, the command implicitly selects all tasks.
+
+Filters can have the following forms:
+
+<!-- INSERT GENERATED DOCUMENTATION - filters -->

docs/src/modifications.md

@@ -0,0 +1,5 @@
+# Modifications
+
+Modifications can have the following forms:
+
+<!-- INSERT GENERATED DOCUMENTATION - modifications-->

docs/src/reports.md

@@ -49,9 +49,8 @@ columns = [
 ]
 ```
 
-The filter is a list of filter arguments, just like those that can be used on the command line.
-See the `ta help` output for more details on this syntax.
-It will be merged with any filters provided on the command line, when the report is invoked.
+The `filter` property is a list of [filters](./filters.md).
+It will be merged with any filters provided on the command line when the report is invoked.
 
 The sort order is defined by an array of tables containing a `sort_by` property and an optional `ascending` property.
 Tasks are compared by the first criterion, and if that is equal by the second, and so on.
@@ -70,11 +69,11 @@ sort = [
 
 The available values of `sort_by` are
 
-(TODO: generate automatically)
+<!-- INSERT GENERATED DOCUMENTATION - report-sort-by -->
 
 Finally, the `columns` configuration specifies the list of columns to display.
 Each element has a `label` and a `property`, as shown in the example above.
 
 The avaliable properties are:
 
-(TODO: generate automatically)
+<!-- INSERT GENERATED DOCUMENTATION - report-columns -->

docs/src/using-task-command.md

@@ -4,6 +4,13 @@ The main interface to your tasks is the `ta` command, which supports various sub
 Customizable [reports](./reports.md) are also available as subcommands, such as `next`.
 The command reads a [configuration file](./config-file.md) for its settings, including where to find the task database.
 And the `sync` subcommand [synchronizes tasks with a sync server](./task-sync.md).
-You can find a list of all subcommands, as well as the built-in reports, with `ta help`.
 
 > NOTE: the `task` interface does not precisely match that of TaskWarrior.
+
+## Subcommands
+
+The sections below describe each subcommand of the `ta` command.
+The syntax of `[filter]` is defined in [filters](./filters.md), and that of `[modification]` in [modifications](./modifications.md).
+You can also find a summary of all subcommands, as well as filters, built-in reports, and so on, with `ta help`.
+
+<!-- INSERT GENERATED DOCUMENTATION - subcommands -->