Switch to TOML for configuration

docs/src/config-file.md

@@ -2,14 +2,18 @@
 
 The `task` command will work out-of-the-box with no configuration file, using default values.
 
-Configuration is read from `taskchampion.yaml` in your config directory.
+Configuration is read from `taskchampion.toml` in your config directory.
 On Linux systems, that directory is `~/.config`.
 On OS X, it's `~/Library/Preferences`.
 On Windows, it's `AppData/Roaming` in your home directory.
-The path can be overridden by setting `$TASKCHAMPION_CONFIG`.
+This can be overridden by setting `$TASKCHAMPION_CONFIG` to the configuration filename.
 
-Individual configuration parameters can be overridden by environment variables, converted to upper-case and prefixed with `TASKCHAMPION_`, e.g., `TASKCHAMPION_DATA_DIR`.
-Nested configuration parameters such as `reports` cannot be overridden by environment variables.
+The file format is [TOML](https://toml.io/).
+For example:
+
+```toml
+data_dir = "/home/myuser/.tasks"
+```
 
 ## Directories
 

docs/src/reports.md

@@ -14,6 +14,7 @@ $ task
 Id Description              Active Tags              
 1  learn about TaskChampion        +next
 2  buy wedding gift         *      +buy
+3  plant tomatoes                  +garden
 ```
 
 The `Id` column contains short numeric IDs that are assigned to pending tasks.
@@ -23,58 +24,56 @@ The `list` report lists all tasks, with a similar set of columns.
 
 ## Custom Reports
 
-Custom reports are defined in the configuration file's `reports` property.
+Custom reports are defined in the configuration file's `reports` table.
 This is a mapping from each report's name to its definition.
 Each definition has the following properties:
 
-* `filter` - criteria for the tasks to include in the report
-* `sort` - how to order the tasks
+* `filter` - criteria for the tasks to include in the report (optional)
+* `sort` - how to order the tasks (optional)
 * `columns` - the columns of information to display for each task
 
+For example:
+
+```toml
+[reports.garden]
+sort = [
+    { sort_by = "description" }
+]
+filter = [
+    "status:pending",
+    "+garden"
+]
+columns = [
+    { label = "ID", property = "id" },
+    { label = "Description", property = "description" },
+]
+```
+
 The filter is a list of filter arguments, just like those that can be used on the command line.
-See the `task help` output for more details on this syntax.
-For example:
+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.
 
-```yaml
-reports:
-  garden:
-    filter:
-      - "status:pending"
-      - "+garden"
-```
-
-The sort order is defined by an array of objects containing a `sort_by` property and an optional `ascending` property.
+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.
-For example:
-
-```yaml
-reports:
-  garden:
-    sort:
-      - sort_by: description
-      - sort_by: uuid
-        ascending: false
-```
 If `ascending` is given, it can be `true` for the default sort order, or `false` for the reverse.
 
+In most cases tasks are just sorted by one criterion, but a more advanced example might look like:
+
+```toml
+[reports.garden]
+sort = [
+    { sort_by = "description" }
+    { sort_by = "uuid", ascending = false }
+]
+...
+```
+
 The available values of `sort_by` are
 
 (TODO: generate automatically)
 
-Finally, the configuration specifies the list of columns to display in the `columns` property.
-Each element has a `label` and a `property`:
-
-```yaml
-reports:
-    garden:
-        columns:
-          - label: Id
-            property: id
-          - label: Description
-            property: description
-          - label: Tags
-            property: tags
-```
+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: