Merge pull request #141 from djmitche/issue102

Update documentation for reports, new CLI

cli/src/invocation/mod.rs

@@ -110,10 +110,10 @@ fn get_replica(settings: &Config) -> Fallible<Replica> {
 
 /// Get the server for this invocation
 fn get_server(settings: &Config) -> Fallible<Box<dyn server::Server>> {
-    // if server_client_id and server_origin are both set, use
+    // if server_client_key and server_origin are both set, use
     // the remote server
     if let (Ok(client_key), Ok(origin)) = (
-        settings.get_str("server_client_id"),
+        settings.get_str("server_client_key"),
         settings.get_str("server_origin"),
     ) {
         let client_key = Uuid::parse_str(&client_key)?;

docs/src/SUMMARY.md

@@ -2,7 +2,12 @@
 
 - [Welcome to TaskChampion](./welcome.md)
   - [Installation](./installation.md)
-  - [Usage](./usage.md)
+  * [Using the Task Command](./using-task-command.md)
+    * [Configuration](./config-file.md)
+    * [Reports](./reports.md)
+    * [Synchronization](./task-sync.md)
+  * [Running the Sync Server](./running-sync-server.md)
+  * [Debugging](./debugging.md)
 - [Internal Details](./internals.md)
   - [Data Model](./data-model.md)
     - [Replica Storage](./storage.md)

docs/src/config-file.md

@@ -0,0 +1,42 @@
+# Configuration
+
+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.
+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`.
+
+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.
+
+## Directories
+
+* `data_dir` - path to a directory containing the replica's task data (which will be created if necessary).
+  Default: `taskchampion` in the local data directory.
+
+## Sync Server
+
+If using a local server:
+
+* `server_dir` - path to a directory containing the local server's data.
+  This is only used if `server_origin` or `server_client_key` are not set.
+  Default: `taskchampion-sync-server` in the local data directory.
+
+If using a remote server:
+
+* `server_origin` - Origin of the TaskChampion sync server, e.g., `https://taskchampion.example.com`.
+  If not set, then sync is done to a local server.
+* `encryption_secret` - Secret value used to encrypt all data stored on the server.
+  This should be a long random string.
+  If you have `openssl` installed, a command like `openssl rand -hex 35` will generate a suitable value.
+  This value is only used when synchronizing with a remote server -- local servers are unencrypted.
+  Treat this value as a password.
+* `server_client_key` -  Client key to identify this replica to the sync server (a UUID)
+  If not set, then sync is done to a local server.
+
+# Reports
+
+* `reports` - a mapping of each report's name to its definition.
+  See [Reports](./reports.md) for details.

docs/src/debugging.md

@@ -0,0 +1,9 @@
+# Debugging
+
+Both `task` and `taskchampion-sync-server` use [env-logger](https://docs.rs/env_logger) and can be configured to log at various levels with the `RUST_LOG` environment variable.
+For example:
+```shell
+$ RUST_LOG=taskchampion=trace task add foo
+```
+
+The output may provide valuable clues in debugging problems.

docs/src/reports.md

@@ -0,0 +1,81 @@
+# Reports
+
+As a to-do list manager, listing tasks is an important TaskChampion feature.
+Reports are tabular displays of tasks, and allow very flexible filtering, sorting, and customization of columns.
+
+TaskChampion includes several "built-in" reports, as well as supporting custom reports in the [configuration file](./config-file.md).
+
+## Built-In Reports
+
+The `next` report is the default, and lists all pending tasks:
+
+```text
+$ task
+Id Description              Active Tags              
+1  learn about TaskChampion        +next
+2  buy wedding gift         *      +buy
+```
+
+The `Id` column contains short numeric IDs that are assigned to pending tasks.
+These IDs are easy to type, such as to mark task 2 done (`task 2 done`).
+
+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.
+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
+* `columns` - the columns of information to display for each task
+
+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:
+
+```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.
+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.
+
+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
+```
+
+The avaliable properties are:
+
+(TODO: generate automatically)

docs/src/running-sync-server.md

@@ -0,0 +1,8 @@
+# Running the Sync Server
+
+> NOTE: TaskChampion is still in development and not yet feature-complete.
+> The server is functional, but lacks any administrative features.
+
+Run `taskchampion-sync-server` to start the sync server.
+Use `--port` to specify the port it should listen on, and `--data-dir` to specify the directory which it should store its data.
+It only serves HTTP; the expectation is that a frontend proxy will be used for HTTPS support.

docs/src/task-sync.md

@@ -0,0 +1,23 @@
+# Synchronization
+
+A single TaskChampion task database is known as a "replica".
+A replica "synchronizes" its local information with other replicas via a sync server.
+Many replicas can thus share the same task history.
+
+This operation is triggered by running `task sync`.
+Typically this runs frequently in a cron task.
+Synchronization is quick, especially if no changes have occurred.
+
+Each replica expects to be synchronized frequently, even if no server is involved.
+Without periodic syncs, the storage space used for the task database will grow quickly, and performance will suffer.
+
+By default, TaskChampion syncs to a "local server", as specified by the `server_dir` configuration parameter.
+Every replica sharing a task history should have precisely the same configuration for `server_origin`, `server_client_key`, and `encryption_secret`.
+
+Synchronizing a new replica to an existing task history is easy: begin with an empty replica, configured for the remote server, and run `task sync`.
+The replica will download the entire task history.
+
+It is possible to switch a single replica to a remote server by simply configuring for the remote server and running `task sync`.
+The replica will upload the entire task history to the server.
+Once this is complete, additional replicas can be configured with the same settings in order to share the task history.
+

docs/src/usage.md

@@ -1,75 +0,0 @@
-# Usage
-
-## `task`
-
-The main interface to your tasks is the `task` command, which supports various subcommands.
-You can find a quick list of all subcommands with `task help`.
-
-Note that the `task` interface does not match that of TaskWarrior.
-
-### Configuration
-
-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.
-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`.
-
-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 cannot be overridden by environment variables.
-
-The following configuration parameters are available:
-
-* `data_dir` - path to a directory containing the replica's task data (which will be created if necessary).
-  Default: `taskchampion` in the local data directory.
-* `server_dir` - path to a directory containing the local server's data.
-  This is only used if `server_origin` or `server_client_id` are not set.
-  Default: `taskchampion-sync-server` in the local data directory.
-* `encryption_secret` - Secret value used to encrypt all data stored on the server.
-  This should be a long random string.
-  If you have `openssl` installed, a command like `openssl rand -hex 35` will generate a suitable value.
-  This value is only used when synchronizing with a remote server -- local servers are unencrypted.
-  Treat this value as a password.
-* `server_origin` - Origin of the TaskChampion sync server, e.g., `https://taskchampion.example.com`.
-  If not set, then sync is done to a local server.
-* `server_client_id` -  Client ID to identify this replica to the sync server (a UUID)
-  If not set, then sync is done to a local server.
-
-### Synchronization
-
-A single TaskChampion task database is known as a "replica".
-A replica "synchronizes" its local information with other replicas via a sync server.
-Many replicas can thus share the same task history.
-
-This operation is triggered by running `task sync`.
-Typically this runs frequently in a cron task.
-Synchronization is quick, especially if no changes have occurred.
-
-Each replica expects to be synchronized frequently, even if no server is involved.
-Without periodic syncs, the storage space used for the task database will grow quickly, and performance will suffer.
-
-By default, TaskChampion syncs to a "local server", as specified by the `server_dir` configuration parameter.
-Every replica sharing a task history should have precisely the same configuration for `server_origin`, `server_client_id`, and `encryption_secret`.
-
-Synchronizing a new replica to an existing task history is easy: begin with an empty replica, configured for the remote server, and run `task sync`.
-The replica will download the entire task history.
-
-It is possible to switch a single replica to a remote server by simply configuring for the remote server and running `task sync`.
-The replica will upload the entire task history to the server.
-Once this is complete, additional replicas can be configured with the same settings in order to share the task history.
-
-## `taskchampion-sync-server`
-
-Run `taskchampion-sync-server` to start the sync server.
-Use `--port` to specify the port it should listen on, and `--data-dir` to specify the directory which it should store its data.
-It only serves HTTP; the expectation is that a frontend proxy will be used for HTTPS support.
-
-## Debugging
-
-Both `task` and `taskchampio-sync-server` use [env-logger](https://docs.rs/env_logger) and can be configured to log at various levels with the `RUST_LOG` environment variable.
-For example:
-```shell
-$ RUST_LOG=taskchampion=trace task add foo
-```

docs/src/using-task-command.md

@@ -0,0 +1,9 @@
+# Using the Task Command
+
+The main interface to your tasks is the `task` command, which supports various subcommands such as `add`, `modify`, `start`, and `done`.
+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 `task help`.
+
+> NOTE: the `task` interface does not precisely match that of TaskWarrior.

docs/src/welcome.md

@@ -3,7 +3,7 @@
 TaskChampion is a personal task-tracking tool.
 It works from the command line, with simple commands like `task add "fix the kitchen sink"`.
 It can synchronize tasks on multiple devices, and does so in an "offline" mode so you can update your tasks even when you can't reach the server.
-If you've heard of [TaskWarrior](https://taskwarrior.org/), this tool is very similar, but actively maintained and with a more reliable synchronization system.
+If you've heard of [TaskWarrior](https://taskwarrior.org/), this tool is very similar, but with some different design choices and greater reliability.
 
 ## Getting Started
 
@@ -14,16 +14,16 @@ Once you've [installed TaskChampion](./installation.md), your interface will be
 Start by adding a task:
 
 ```shell
-$ task add "learn how to use taskchampion"
+$ task add learn how to use taskchampion
 added task ba57deaf-f97b-4e9c-b9ab-04bc1ecb22b8
 ```
 
-You can see all of your pending tasks with `task pending`, or just `task` for short:
+You can see all of your pending tasks with `task next`, or just `task` for short:
 
 ```shell
 $ task
- id act description                   
+ Id Description                    Active  Tags
- 1      learn how to use taskchampion
+ 1  learn how to use taskchampion
 ```
 
 Tell TaskChampion you're working on the task, using the shorthand id:
@@ -49,13 +49,15 @@ $ task sync
 
 Typically sync is run from a crontab, on whatever schedule fits your needs.
 
-To synchronize multiple replicas of your tasks, you will need a sync server and a client ID on that server.
+To synchronize multiple replicas of your tasks, you will need a sync server and a client key for that server.
 Configure these in `~/.config/taskchampion.yml`, for example:
 
 ```yaml
-server_client_id: "f8d4d09d-f6c7-4dd2-ab50-634ed20a3ff2"
+server_client_key: "f8d4d09d-f6c7-4dd2-ab50-634ed20a3ff2"
 server_origin: "https://taskchampion.example.com"
 ```
 
 The next run of `task sync` will upload your task history to that server.
 Configuring another device identically and running `task sync` will download that task history, and continue to stay in sync with subsequent runs of the command.
+
+See [Usage](./usage.md) for more detailed information on using TaskChampion.