GothenburgBitFactory/taskwarrior
1
0
Fork 0
mirror of https://github.com/GothenburgBitFactory/taskwarrior.git synced 2025-06-26 10:54:26 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

remove docs about taskchampion-cli

Browse source
This commit is contained in:
Dustin J. Mitchell 2022-05-22 01:46:36 +00:00 • committed by Tomas Babej
parent c0ce1fe059
commit 2f57edee51
15 changed files with 0 additions and 355 deletions
Download patch file Download diff file Expand all files Collapse all files

6
rust/README.md
View file

@ -50,9 +50,3 @@ NOTE: on Windows, the "BCrypt" library must be included when linking to taskcham
### As a Rust dependency
If you would prefer to build Taskchampion directly into your project, and have a build system capable of building Rust libraries (such as CMake), the `taskchampion-lib` crate can be referenced as an `rlib` dependency.
## Documentation Generation
The `mdbook` configuration contains a "preprocessor" implemented in the `taskchampion-cli` crate in order to reflect CLI usage information into the generated book.
This preprocessor is not built by default.
To (re)build it, run `cargo build -p taskchampion-cli --features usage-docs --bin usage-docs`.

3
rust/build-docs.sh
View file

@ -11,9 +11,6 @@ if ! [ -f "docs/src/SUMMARY.md" ]; then
exit 1
fi
# build the latest version of the mdbook plugin
cargo build -p taskchampion-cli --features usage-docs --bin usage-docs
# create a worktree of this repo, with the `gh-pages` branch checked out
git branch -f gh-pages $REMOTE/gh-pages
if ! [ -d ./docs/tmp ]; then

7
rust/docs/README.md
View file

@ -1,10 +1,3 @@
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/
```

3
rust/docs/book.toml
View file

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

10
rust/docs/src/SUMMARY.md
View file

@ -2,16 +2,6 @@
- [Welcome to TaskChampion](./welcome.md)
* [Installation](./installation.md)
* [Using the Task Command](./using-task-command.md)
* [Reports](./reports.md)
* [Tags](./tags.md)
* [Filters](./filters.md)
* [Modifications](./modifications.md)
* [Dates and Durations](./time.md)
* [Configuration](./config-file.md)
* [Environment](./environment.md)
* [Undo](./undo.md)
* [Synchronization](./task-sync.md)
* [Running the Sync Server](./running-sync-server.md)
- [Internal Details](./internals.md)
* [Data Model](./data-model.md)

66
rust/docs/src/config-file.md
View file

@ -1,66 +0,0 @@
# Configuration
The `ta` command will work out-of-the-box with no configuration file, using default values.
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.
This can be overridden by setting `TASKCHAMPION_CONFIG` to the configuration filename.
The file format is [TOML](https://toml.io/).
For example:
```toml
data_dir = "/home/myuser/.tasks"
```
## 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.
## Command-Line Preferences
* `modification_count_prompt` - when a modification will affect more than this many tasks, the `ta` command will prompt for confirmation.
A value of `0` will disable the prompts entirely.
Default: 3.
## 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.
## Snapshots
* `avoid_snapshots` - If running on a CPU-, memory-, or bandwidth-constrained
device, set this to true. The effect is that this replica will wait longer
to produce a snapshot, in the hopes that other replicas will do so first.
## Reports
* `reports` - a mapping of each report's name to its definition.
See [Reports](./reports.md) for details.
## Editing
As a shortcut, the simple, top-level configuration values can be edited from the command line:
```shell
ta config set data_dir /home/myuser/.taskchampion
```

21
rust/docs/src/environment.md
View file

@ -1,21 +0,0 @@
# Environment Variables
## Configuration
Set `TASKCHAMPION_CONFIG` to the location of a configuration file in order to override the default location.
## Terminal Output
Taskchampion uses [termcolor](https://github.com/BurntSushi/termcolor) to color its output.
This library interprets [`TERM` and `NO_COLOR`](https://github.com/BurntSushi/termcolor#automatic-color-selection) to determine how it should behave, when writing to a tty.
Set `NO_COLOR` to any value to force plain-text output.
## Debugging
Both `ta` 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 ta add foo
```
The output may provide valuable clues in debugging problems.

9
rust/docs/src/filters.md
View file

@ -1,9 +0,0 @@
# 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 -->

5
rust/docs/src/modifications.md
View file

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

79
rust/docs/src/reports.md
View file

@ -1,79 +0,0 @@
# 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
$ ta
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.
These IDs are easy to type, such as to mark task 2 done (`ta 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` 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 (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` 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.
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
<!-- 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:
<!-- INSERT GENERATED DOCUMENTATION - report-columns -->

26
rust/docs/src/tags.md
View file

@ -1,26 +0,0 @@
# Tags
Each task has a collection of associated tags.
Tags are short words that categorize tasks, typically written with a leading `+`, such as `+next` or `+jobsearch`.
Tags are useful for filtering tasks in reports or on the command line.
For example, when it's time to continue the job search, `ta +jobsearch` will show pending tasks with the `jobsearch` tag.
## Allowed Tags
Specifically, tags must be at least one character long and cannot contain whitespace or any of the characters `+-*/(<>^! %=~`.
The first character cannot be a digit, and `:` is not allowed after the first character.
All-capital tags are reserved for synthetic tags (below) and cannot be added or removed from tasks.
## Synthetic Tags
Synthetic tags are present on tasks that meet specific criteria, that are commonly used for filtering.
For example, `WAITING` is set for tasks that are currently waiting.
These tags cannot be added or removed from a task, but appear and disappear as the task changes.
The following synthetic tags are defined:
* `WAITING` - set if the task is waiting (has a `wait` property with a date in the future)
* `ACTIVE` - set if the task is active (has been started and not stopped)
* `PENDING` - set if the task is pending (not completed or deleted)
* `COMPLETED` - set if the task has been completed
* `DELETED` - set if the task has been deleted (but not yet flushed from the task list)

49
rust/docs/src/task-sync.md
View file

@ -1,49 +0,0 @@
# 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 `ta 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.
## Local Sync
By default, TaskChampion syncs to a "local server", as specified by the `server_dir` configuration parameter.
This defaults to `taskchampion-sync-server` in your [data directory](https://docs.rs/dirs-next/2.0.0/dirs_next/fn.data_dir.html), but can be customized in the configuration file.
## Remote Sync
For remote synchronization, you will need a few pieces of information.
From the server operator, you will need an origin and a client key.
Configure these with
```shell
ta config set server_origin "<origin from server operator>"
ta config set server_client_key "<client key from server operator>"
```
You will need to generate your own encryption secret.
This is used to encrypt your task history, so treat it as a password.
The following will use the `openssl` utility to generate a suitable value:
```shell
ta config set encryption_secret $(openssl rand -hex 35)
```
Every replica sharing a task history should have precisely the same configuration for `server_origin`, `server_client_key`, and `encryption_secret`.
### Adding a New Replica
Synchronizing a new replica to an existing task history is easy: begin with an empty replica, configured for the remote server, and run `ta sync`.
The replica will download the entire task history.
### Upgrading a Locally-Sync'd Replica
It is possible to switch a single replica to a remote server by simply configuring for the remote server and running `ta 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.

48
rust/docs/src/time.md
View file

@ -1,48 +0,0 @@
## Timestamps
Times may be specified in a wide variety of convenient formats.
* [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) timestamps, such as `2019-10-12 07:20:50.12Z`
* A date of the format `YYYY-MM-DD` is interpreted as the _local_ midnight at the beginning of the given date.
Single-digit month and day are accepted, but the year must contain four digits.
* `now` refers to the exact current time
* `yesterday`, `today`, and `tomorrow` refer to the _local_ midnight at the beginning of the given day
* Any duration (described below) may be used as a timestamp, and is considered relative to the current time.
Times are stored internally as UTC.
## Durations
Durations can be given in a dizzying array of units.
Each can be preceded by a whole number or a decimal multiplier, e.g., `3days`.
The multiplier is optional with the singular forms of the units; for example `day` is allowed.
Some of the units allow an adjectival form, such as `daily` or `annually`; this form is more readable in some cases, but otherwise has the same meaning.
* `s`, `second`, or `seconds`
* `min`, `mins`, `minute`, or `minutes` (note that `m` not allowed, as it might also mean `month`)
* `h`, `hour`, or `hours`
* `d`, `day`, or `days`
* `w`, `week`, or `weeks`
* `mo`, or `months` (always 30 days, regardless of calendar month)
* `y`, `year`, or `years` (365 days, regardless of leap days)
[ISO 8601 standard durations](https://en.wikipedia.org/wiki/ISO_8601#Durations) are also allowed.
While the standard does not specify the length of "P1Y" or "P1M", Taskchampion treats those as 365 and 30 days, respectively.
## Named Timestamps
Some commonly used named timestamps
* `today` Start of today
* `yesterday` Start of yesterday
* `tomorrow` Start of tomorrow
* `sod` Start of today
* `eod` End of today
* `sow` Start of the next week
* `eow` End of the week
* `eoww` End of work week
* `soww` Start of the next work week
![named timestamp](images/name_timestamp.png)

7
rust/docs/src/undo.md
View file

@ -1,7 +0,0 @@
# Undo
It's easy to make a mistake: mark the wrong task as done, or hit enter before noticing a typo in a tag name.
The `ta undo` command makes it just as easy to fix the mistake, by effectively reversing the most recent change.
Multiple invocations of `ta undo` can be used to undo multiple changes.
The limit of this functionality is that changes which have been synchronized to the server (via `ta sync`) cannot be undone.

16
rust/docs/src/using-task-command.md
View file

@ -1,16 +0,0 @@
# Using the Task Command
The main interface to your tasks is the `ta` 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).
> 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 -->