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

Properly tag monospaced text in man pages. (Improves HTML rendering) (#3509)

Browse source 
This would be immediately useful to improve the rendering of the man
pages in third-party websites such as manned.org and the arch man pagesk
- https://mankier.com/1/task
- https://man.archlinux.org/man/task.1

The regular console output, or websites which render the manpage in
monospaced fonts, will not be affected by this change.

This change could also help with eventually rendering the manpages in
the documentation website, and having a mix of monospaced and variable
width fonts.

To test the HTML output:
```bash
git clone git@github.com:jacksonp/manner.git # used by ManKier
./manner/manner.php task.1.in >| task.1.html && $BROWSER task.1.html
```

Co-authored-by: Sebastian Carlos <sebastiancarlos@gmail.com>
This commit is contained in:
Sebastian Carlos 2024-06-24 15:00:12 -03:00 • committed by GitHub
parent 71becf0185
commit 910860ae1c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 436 additions and 313 deletions
Download patch file Download diff file Expand all files Collapse all files

74
doc/man/task-color.5.in
View file

@ -8,14 +8,18 @@ It should be mentioned that Taskwarrior is aware of whether its output is going
to a terminal, or to a file or through a pipe. When Taskwarrior output goes to
a terminal, color is desirable, but consider the following command:
.nf
$ task list > file.txt
.fi
Do we really want all those color control codes in the file? Taskwarrior
assumes that you do not, and temporarily sets color to 'off' while generating
the output. This explains the output from the following command:
.nf
$ task show | grep '^color '
color off
.fi
it always returns 'off', no matter what the setting, because the output is being
sent to a pipe.
@ -23,20 +27,26 @@ sent to a pipe.
If you wanted those color codes, you can override this behavior by setting the
_forcecolor variable to on, like this:
.nf
$ task config _forcecolor on
$ task config | grep '^color '
color on
.fi
or by temporarily overriding it like this:
.nf
$ task rc._forcecolor=on config | grep '^color '
color on
.fi
.SH AVAILABLE COLORS
Taskwarrior has a 'color' command that will show all the colors it is capable of
displaying. Try this:
.nf
$ task color
.fi
The output cannot be replicated here in a man page, but you should see a set of
color samples. How many you see depends on your terminal program's ability to
@ -48,7 +58,9 @@ You should at least see the Basic colors and Effects - if you do, then you have
.SH 16-COLOR SUPPORT
The basic color support is provided through named colors:
.nf
black, red, blue, green, magenta, cyan, yellow, white
.fi
Foreground color (for text) is simply specified as one of the above colors, or
not specified at all to use the default terminal text color.
@ -56,37 +68,49 @@ not specified at all to use the default terminal text color.
Background color is specified by using the word 'on', and one of the above
colors. Some examples:
.nf
green # green text, default background color
green on yellow # green text, yellow background
on yellow # default text color, yellow background
.fi
These colors can be modified further, by making the foreground bold, or by
making the background bright. Some examples:
.nf
bold green
bold white on bright red
on bright cyan
.fi
The order of the words is not important, so the following are equivalent:
.nf
bold green
green bold
.fi
But the 'on' is important - colors before the 'on' are foreground, and colors
after 'on' are background.
There is an additional 'underline' attribute that may be used:
.nf
underline bold red on black
.fi
And an 'inverse' attribute:
.nf
inverse red
.fi
Taskwarrior has a command that helps you visualize these color combinations.
Try this:
.nf
$ task color underline bold red on black
.fi
You can use this command to see how the various color combinations work. You
will also see some sample colors displayed, like the ones above, in addition to
@ -103,11 +127,13 @@ Using 256 colors follows the same form, but the names are different, and some
colors can be referenced in different ways. First there is by color ordinal,
which is like this:
.nf
color0
color1
color2
...
color255
.fi
This gives you access to all 256 colors, but doesn't help you much. This range
is a combination of 8 basic colors (color0 - color7), then 8 brighter variations
@ -119,31 +145,43 @@ be addressed via RGB values from 0 to 5 for each component color. A value of 0
means none of this component color, and a value of 5 means the most intense
component color. For example, a bright red is specified as:
.nf
rgb500
.fi
And a darker red would be:
.nf
rgb300
.fi
Note that the three digits represent the three component values, so in this
example the 5, 0 and 0 represent red=5, green=0, blue=0. Combining intense red
with no green and no blue yields red. Similarly, blue and green are:
.nf
rgb005
rgb050
.fi
Another example - bright yellow - is a mix of bright red and bright green, but
no blue component, so bright yellow is addressed as:
.nf
rgb550
.fi
A soft pink would be addressed as:
.nf
rgb515
.fi
See if you agree, by running:
.nf
$ task color black on rgb515
.fi
You may notice that the large color block is represented as 6 squares. All
colors in the first square have a red value of 0. All colors in the 6th square
@ -163,7 +201,9 @@ will be disappointed, perhaps even appalled.
There is some limited color mapping - for example, if you were to specify this
combination:
.nf
red on gray3
.fi
you are mixing a 16-color and 256-color specification. Taskwarrior will map red
to color1, and proceed. Note that red and color1 are not quite the same tone.
@ -175,7 +215,9 @@ colors, but there is still underline available.
Taskwarrior will show examples of all defined colors used in your .taskrc, or
theme, if you run this command:
.nf
$ task color legend
.fi
This gives you an example of each of the colors, so you can see the effect,
without necessarily creating a set of tasks that meet each of the rule criteria.
@ -185,20 +227,26 @@ Taskwarrior supports colorization rules. These are configuration values that
specify a color, and the conditions under which that color is used. By example,
let us add a few tasks:
.nf
$ task add project:Home priority:H pay the bills (1)
$ task add project:Home clean the rug (2)
$ task add project:Garden clean out the garage (3)
.fi
We can add a color rule that uses a blue background for all tasks in the Home
project:
.nf
$ task config color.project.Home 'on blue'
.fi
We use quotes around 'on blue' because there are two words, but they represent
one value in the .taskrc file. Now suppose we wish to use a bold yellow text
color for all cleaning work:
.nf
$ task config color.keyword.clean 'bold yellow'
.fi
Now what happens to task 2, which belongs to project Home (blue background), and
is also a cleaning task (bold yellow foreground)? The colors are combined, and
@ -219,7 +267,9 @@ color blending.
The precedence for the color rules is determined by the configuration
variable 'rule.precedence.color', which by default contains:
.nf
deleted,completed,active,keyword.,tag.,project.,overdue,scheduled,due.today,due,blocked,blocking,recurring,tagged,uda.
.fi
These are just the color rules with the 'color.' prefix removed. The
rule 'color.deleted' has the highest precedence, and 'color.uda.' the lowest.
@ -238,50 +288,38 @@ be included.
To get a good idea of what a color theme looks like, try adding this entry to
your .taskrc file:
.RS
.nf
include dark-256.theme
.RE
.fi
You can use any of the standard Taskwarrior themes:
.RS
.nf
dark-16.theme
.br
dark-256.theme
.br
dark-blue-256.theme
.br
dark-gray-256.theme
.br
dark-green-256.theme
.br
dark-red-256.theme
.br
dark-violets-256.theme
.br
dark-yellow-green.theme
.br
light-16.theme
.br
light-256.theme
.br
solarized-dark-256.theme
.br
solarized-light-256.theme
.br
dark-default-16.theme
.br
dark-gray-blue-256.theme
.br
no-color.theme
.RE
.fi
Bear in mind that if you are using a terminal with a dark background, you will
see better results using a dark theme.
You can also see how the theme will color the various tasks with the command:
.nf
$ task color legend
.fi
Better yet, create your own, and share it. We will gladly host the theme file
on <https://taskwarrior.org>.

20
doc/man/task-sync.5.in
View file

@ -35,7 +35,9 @@ This is the default, and is appropriate for local synchronization.
For synchronization to a server, a better solution is to run
.nf
$ task sync
.fi
periodically, such as via
.BR cron (8) .
@ -52,7 +54,9 @@ For most of these, you will need an encryption secret used to encrypt and
decrypt your tasks. This can be any secret string, and must match for all
replicas sharing tasks.
.nf
$ task config sync.encryption_secret <encryption_secret>
.fi
Tools such as
.BR pwgen (1)
@ -70,8 +74,10 @@ information from the server administrator:
Configure Taskwarrior with these details:
.nf
$ task config sync.server.origin <origin>
$ task config sync.server.client_id <client_id>
.fi
Note that the origin must include the scheme, such as 'http://' or 'https://'.
@ -83,12 +89,16 @@ the bucket are adequate.
Authenticate to the project with:
.nf
$ gcloud config set project $PROJECT_NAME
$ gcloud auth application-default login
.fi
Then configure Taskwarrior with:
.nf
$ task config sync.gcp.bucket <bucket-name>
.fi
However you can bring your own service account credentials if your
`application-default` is already being used by some other application
@ -124,8 +134,10 @@ Select the following permissions:
Then configure Taskwarrior with:
.nf
$ task config sync.gcp.bucket <bucket-name>
$ task config sync.gcp.credential_path <absolute-path-to-downloaded-credentials>
.fi
.SS Local Synchronization
@ -133,7 +145,9 @@ In order to take advantage of synchronization's side effect of saving disk
space without setting up a remote server, it is possible to sync tasks locally.
To configure local sync:
.nf
$ task config sync.local.server_dir /path/to/sync
.fi
The default configuration is to sync to a database in the task directory
("data.location").
@ -162,11 +176,15 @@ invent their own "encryption_secret".
If you run multiple clients that sync to the same server, you will need to run
this command on your primary client (the one you use most often):
.nf
$ task config recurrence on
.fi
And on the other clients, run:
.nf
$ task config recurrence off
.fi
This protects you against the effects of a sync/duplication bug.
@ -185,7 +203,9 @@ modifying the same task on two machines, without an intervening sync.
Setup simply involves creating the directory and modifying your data.location
configuration variable like this:
.nf
$ task config data.location /path/to/shared/directory
.fi
Strengths:
.br

221
doc/man/task.1.in
View file

@ -24,18 +24,24 @@ descriptors), project groups, etc.
The <filter> consists of zero or more search criteria that select tasks. For
example, to list all pending tasks belonging to the 'Home' project:
.nf
task project:Home list
.fi
You can specify multiple filter terms, each of which further restricts the
result:
.nf
task project:Home +weekend garden list
.fi
This example applies three filters: the 'Home' project, the 'weekend' tag, and
the description or annotations must contain the character sequence 'garden'.
In this example, 'garden' is translated internally to:
.nf
description.contains:garden
.fi
as a convenient shortcut. The 'contains' here is an attribute modifier, which
is used to exert more control over the filter than simply absence or presence.
@ -45,24 +51,30 @@ Note that a filter may have zero terms, which means that all tasks apply to the
command. This can be dangerous, and this special case is confirmed, and
cannot be overridden. For example, this command:
.nf
task modify +work
This command has no filter, and will modify all tasks. Are you sure? (yes/no)
.fi
will add the 'work' tag to all tasks, but only after confirmation.
More filter examples:
.nf
task <command> <mods>
task 28 <command> <mods>
task +weekend <command> <mods>
task +bills due.by:eom <command> <mods>
task project:Home due.before:today <command> <mods>
task ebeeab00-ccf8-464b-8b58-f7f2d606edfb <command> <mods>
.fi
By default filter elements are combined with an implicit 'and' operator,
but 'or' and 'xor' may also be used, provided parentheses are included:
.nf
task '( /[Cc]at|[Dd]og/ or /[0-9]+/ )' <command> <mods>
.fi
The parentheses isolate the logical term from any default command filter or
implicit report filter which would be combined with an implicit 'and'.
@ -71,10 +83,12 @@ A filter may target specific tasks using ID or UUID numbers. To specify
multiple tasks use one of these forms (space-separated list of ID numbers,
UUID numbers or ID ranges):
.nf
task 1 2 3 delete
task 1-3 info
task 1 2-5 19 modify pri:H
task 4-7 ebeeab00-ccf8-464b-8b58-f7f2d606edfb info
.fi
Note that it may be necessary to properly escape special characters as well as
quotes in order to avoid their special meanings in the shell. See also the
@ -85,11 +99,13 @@ section 'SPECIFYING DESCRIPTIONS' for more information.
The <mods> consist of zero or more changes to apply to the selected tasks, such
as:
.nf
task <filter> <command> project:Home
task <filter> <command> +weekend +garden due:tomorrow
task <filter> <command> Description/annotation text
task <filter> <command> /from/to/ <- replace first match
task <filter> <command> /from/to/g <- replace all matches
.fi
.SH SUBCOMMANDS
@ -188,6 +204,7 @@ wish to save it, or pipe it to another command or script to convert it to
another format. You'll find these example scripts online at
<https://taskwarrior.org/tools/>:
.nf
export-csv.pl
export-sql.py
export-xml.py
@ -198,6 +215,7 @@ another format. You'll find these example scripts online at
export-ical.pl
export-xml.pl
export-yad.pl
.fi
.TP
.B task <filter> ghistory.annual
@ -243,12 +261,16 @@ Applies the filter then extracts only the task IDs and presents them as
a space-separated list. This is useful as input to a task command, to achieve
this:
.nf
task $(task project:Home ids) modify priority:H
.fi
This example first gets the IDs for the project:Home filter, then sets
the priority to H for each of those tasks. This can also be achieved directly:
.nf
task project:Home modify priority:H
.fi
This command is mainly of use to external scripts.
@ -258,7 +280,9 @@ Applies the filter on all tasks (even deleted and completed tasks)
then extracts only the task UUIDs and presents them as a space-separated list.
This is useful as input to a task command, to achieve this:
.nf
task $(task project:Home status:completed uuids) modify status:pending
.fi
This example first gets the UUIDs for the project:Home and status:completed
filters, then makes each of those tasks pending again.
@ -385,8 +409,10 @@ if import is to be used in automated workflows. See taskrc(5).
For importing other file formats, the standard task release comes with a
few example scripts, such as:
.nf
import-todo.sh.pl
import-yaml.pl
.fi
.TP
.B task log <mods>
@ -423,14 +449,20 @@ parses and evaluates the expression given on the command line.
Examples:
.nf
task calc 1 + 1
2
.fi
.nf
task calc now + 8d
2015-03-26T18:06:57
.fi
.nf
task calc eom
2015-03-31T23:59:59
.fi
.TP
.B task config [<name> [<value> | '']]
@ -438,16 +470,22 @@ Add, modify and remove settings directly in the Taskwarrior configuration.
This command either modifies the 'name' setting with a new value of 'value',
or adds a new entry that is equivalent to 'name=value':
.nf
task config name value
.fi
This command sets a blank value. This has the effect of suppressing any
default value:
.nf
task config name ''
.fi
Finally, this command removes any 'name=...' entry from the .taskrc file:
.nf
task config name
.fi
.TP
.B task context <name>
@ -455,7 +493,9 @@ Sets the currently active context. See the CONTEXT section.
Example:
.nf
task context work
.fi
.TP
.B task context delete <name>
@ -464,7 +504,9 @@ set as active, it will be unset.
Example:
.nf
task context delete work
.fi
.TP
.B task context define <name> <filter>
@ -473,9 +515,11 @@ does not affect the currently set context, just adds a new context definition.
Examples:
.nf
task context define work project:Work
task context define home project:Home or +home
task context define superurgent due:today and +urgent
.fi
.TP
.B task context list
@ -543,11 +587,15 @@ The sync command synchronizes data with the Taskserver, if configured.
Note: If you use multiple sync clients, make sure this setting (which is the default)
is on your primary client:
.nf
recurrence=on
.fi
and on all other clients (this is not the default):
.nf
recurrence=off
.fi
This is a workaround to avoid a recurrence bug that duplicates recurring tasks.
@ -607,7 +655,9 @@ by third-party applications.
Reports a unique set of attribute values. For example, to see all the active
projects:
.nf
task +PENDING _unique project
.fi
.TP
.B task <filter> _uuids
@ -654,6 +704,7 @@ Shows the UUIDs and descriptions of matching tasks.
Accesses and displays the DOM reference(s). Used to extract individual values
from tasks, or the system. Supported DOM references are:
.nf
rc.<name>
tw.syncneeded
tw.program
@ -669,6 +720,7 @@ from tasks, or the system. Supported DOM references are:
system.os
<id>.<attribute>
<uuid>.<attribute>
.fi
Note that the 'rc.<name>' reference may need to be escaped using '--' to prevent
the reference from being interpreted as an override.
@ -679,8 +731,10 @@ missing value, the command exits with 1.
Additionally, some components of the attributes of particular types may be
extracted by DOM references.
.nf
$ task _get 2.due.year
2015
.fi
For a full list of supported attribute-specific DOM references, consult
the online documentation at:
@ -694,10 +748,11 @@ Tasks can be specified uniquely by IDs, which are simply the indexes of the
tasks in the database. The ID of a task may therefore change, but only when
a command is run that displays IDs. When modifying tasks, it is safe to
rely on the last displayed ID. Always run a report to check you have the right
ID for a task. IDs can be given to task as a sequence, for example,
.br
.B
ID for a task. IDs can be given to task as a sequence, for example:
.nf
task 1,4-10,19 delete
.fi
.TP
.B +tag|-tag
@ -708,15 +763,18 @@ Certain tags (called 'special tags'), can be used to affect the way tasks are
treated. For example, if a task has the special tag 'nocolor', then it is
exempt from all color rules. The supported special tags are:
.nf
+nocolor Disable color rules processing for this task
+nonag Completion of this task suppresses all nag messages
+nocal This task will not appear on the calendar
+next Elevates task so it appears on 'next' report
.fi
There are also virtual tags, which represent task metadata in tag form. These
tags do not exist, but can be used to filter tasks. The supported virtual tags
are:
.nf
ACTIVE Matches if the task is started
ANNOTATED Matches if the task has annotations
BLOCKED Matches if the task is blocked
@ -748,6 +806,7 @@ are:
WEEK Matches if the task is due this week
YEAR Matches if the task is due this year
YESTERDAY Matches if the task was due sometime yesterday
.fi
.\" If you update the above list, update src/commands/CmdInfo.cpp and src/commands/CmdTags.cpp as well.
@ -853,9 +912,9 @@ calculated attributes:
For example:
.RS
.nf
task due.before:eom priority.not:L list
.RE
.fi
The
.I before
@ -875,15 +934,21 @@ The
modifier is the same as 'before', except it also includes the moment in
question. For example:
.nf
task add test due:eoy
.fi
will be found when using the inclusive filter 'by':
.nf
task due.by:eoy
.fi
but not when the non-inclusive filter 'before' is used:
.nf
task due.before:eoy
.fi
this applies equally to other named dates such as 'eom', 'eod', etc; the
modifier compares using '<=' rather than '<' like 'before' does.
@ -892,8 +957,10 @@ The
.I none
modifier requires that the attribute does not have a value. For example:
.nf
task priority: list
task priority.none: list
.fi
are equivalent, and list tasks that do not have a priority.
@ -915,8 +982,10 @@ The
.I has
modifier is used to search for a substring, such as:
.nf
task description.has:foo list
task foo list
.fi
These are equivalent and will return any task that has 'foo' in the description
or annotations.
@ -931,13 +1000,17 @@ The
.I startswith
modifier matches against the left, or beginning of an attribute, such that:
.nf
task project.startswith:H list
task project:H list
.fi
are equivalent and will match any project starting with 'H'. Matching all
projects not starting with 'H' is done with:
.nf
task project.not:H list
.fi
The
.I endswith
@ -948,7 +1021,9 @@ The
modifier requires that the attribute contain the whole word specified, such
that this:
.nf
task description.word:bar list
.fi
Will match the description 'foo bar baz' but does not match 'dog food'.
@ -962,15 +1037,19 @@ modifier.
You can use the following operators in filter expressions:
.nf
and or xor ! Logical operators
< <= = == != !== >= > Relational operators
( ) Precedence
.fi
For example:
.nf
task due.before:eom priority.not:L list
task '( due < eom or priority != L )' list
task '! ( project:Home or project:Garden )' list
.fi
The
.I =
@ -994,32 +1073,44 @@ Note that the parentheses are required when using a logical operator other than
the 'and' operator. The reason is that some reports contain filters that must
be combined with the command line. Consider this example:
.nf
task project:Home or project:Garden list
.fi
While this looks correct, it is not. The 'list' report contains a filter of:
.nf
task show report.list.filter
Config Variable Value
----------------- --------------
report.list.filter status:pending
.fi
Which means the example is really:
.nf
task status:pending project:Home or project:Garden list
.fi
The implied 'and' operator makes it:
.nf
task status:pending and project:Home or project:Garden list
.fi
This is a precedence error - the 'and' and 'or' need to be grouped using
parentheses, like this:
.nf
task status:pending and ( project:Home or project:Garden ) list
.fi
The original example therefore must be entered as:
.nf
task '( project:Home or project:Garden )' list
.fi
This includes quotes to escape the parentheses, so that the shell doesn't
interpret them and hide them from Taskwarrior.
@ -1027,11 +1118,13 @@ interpret them and hide them from Taskwarrior.
There is redundancy between operators, attribute modifiers and other syntactic
sugar. For example, the following are all equivalent:
.nf
task foo list
task /foo/ list
task description.contains:foo list
task description.has:foo list
task 'description ~ foo' list
.fi
.SH SPECIFYING DATES AND FREQUENCIES
@ -1045,92 +1138,83 @@ configuration variable
.RS
.TP
Exact specification
.nf
task ... due:7/14/2008
.fi
.TP
ISO-8601
.nf
task ... due:2013-03-14T22:30:00Z
.fi
.TP
Relative wording
.nf
task ... due:now
.br
task ... due:today
.br
task ... due:yesterday
.br
task ... due:tomorrow
.fi
.TP
Day number with ordinal
.nf
task ... due:23rd
.br
task ... due:3wks
.br
task ... due:1day
.br
task ... due:9hrs
.fi
.TP
Start of next (work) week (Monday), calendar week (Sunday or Monday), month, quarter and year
.br
.nf
task ... due:sow
.br
task ... due:soww
.br
task ... due:socw
.br
task ... due:som
.br
task ... due:soq
.br
task ... due:soy
.fi
.TP
End of current (work) week (Friday), calendar week (Saturday or Sunday), month, quarter and year
.br
.nf
task ... due:eow
.br
task ... due:eoww
.br
task ... due:eocw
.br
task ... due:eom
.br
task ... due:eoq
.br
task ... due:eoy
.fi
.TP
At some point or later
.br
.nf
task ... wait:later
.br
task ... wait:someday
.fi
This sets the wait date to 12/30/9999.
.TP
Next occurring weekday
.nf
task ... due:fri
.fi
.TP
Predictable holidays
.nf
task ... due:goodfriday
.br
task ... due:easter
.br
task ... due:eastermonday
.br
task ... due:ascension
.br
task ... due:pentecost
.br
task ... due:midsommar
.br
task ... due:midsommarafton
.br
task ... due:juhannus
.fi
.RE
.SS FREQUENCIES
@ -1181,7 +1265,8 @@ Context is a user-defined query, which is automatically applied to all commands
that filter the task list and to commands that create new tasks (add, log). For
example, any report command will have its result affected by the current
active context. Here is a list of the commands that are affected:
.IP
.nf
add
burndown
count
@ -1199,33 +1284,44 @@ active context. Here is a list of the commands that are affected:
stop
summary
tags
.fi
All other commands are NOT affected by the context.
.nf
$ task list
ID Age Project Description Urg
1 2d Sport Run 5 miles 1.42
2 1d Home Clean the dishes 1.14
.fi
.nf
$ task context home
Context 'home' set. Use 'task context none' to remove.
.fi
.nf
$ task list
ID Age Project Description Urg
2 1d Home Clean the dishes 1.14
Context 'home' set. Use 'task context none' to remove.
.fi
Task list got automatically filtered for project:Home.
.nf
$ task add Vaccuum the carpet
Created task 3.
Context 'home' set. Use 'task context none' to remove.
.fi
.nf
$ task list
ID Age Project Description Urg
2 1d Home Clean the dishes 1.14
3 5s Home Vaccuum the carpet 1.14
Context 'home' set. Use 'task context none' to remove.
.fi
Note that the newly added task "Vaccuum the carpet" has "project:Home" set
automatically.
@ -1236,22 +1332,28 @@ new context's name to the 'context' command.
To unset any context, use the 'none' subcommand.
.nf
$ task context none
Context unset.
.fi
.nf
$ task list
ID Age Project Description Urg
1 2d Sport Run 5 miles 1.42
2 1d Home Clean the dishes 1.14
3 7s Home Vaccuum the carpet 1.14
.fi
Context can be defined using the 'define' subcommand, specifying both the name
of the new context, and it's assigned filter.
.nf
$ task context define home project:Home
Are you sure you want to add 'context.home.read' with a value of 'project:Home'? (yes/no) yes
Are you sure you want to add 'context.home.write' with a value of 'project:Home'? (yes/no) yes
Context 'home' successfully defined.
.fi
Note that you were separately prompted to set the 'read' and 'write' context.
This allows you to specify contexts that only work for reporting commands or
@ -1259,13 +1361,16 @@ only for commands that create tasks.
To remove the definition, use the 'delete' subcommand.
.nf
$ task context delete home
Are you sure you want to remove 'context.home.read'? (yes/no) yes
Are you sure you want to remove 'context.home.write'? (yes/no) yes
Context 'home' deleted.
.fi
To check what is the currently active context, use the 'show' subcommand.
.nf
$ task context show
Context 'home' with
@ -1273,13 +1378,16 @@ To check what is the currently active context, use the 'show' subcommand.
* write filter: '+home'
is currently applied.
.fi
Contexts can store arbitrarily complex filters.
.nf
$ task context define family project:Family or +paul or +nancy
Are you sure you want to add 'context.family.read' with a value of 'project:Family or +paul or +nancy'? (yes/no) yes
Are you sure you want to add 'context.family.write' with a value of 'project:Family or +paul or +nancy'? (yes/no) no
Context 'family' successfully defined.
.fi
Contexts are permanent, and the currently set context name is stored in the
"context" configuration variable. The context definition is stored in the
@ -1292,13 +1400,17 @@ filter as writeable context. The reason for this decision is that the complex
filter in the example does not directly translate to a modification. In fact,
if such a context is used as a writeable context, the following happens:
.nf
$ task add Call Paul
Created task 4.
Context 'family' set. Use 'task context none' to remove.
.fi
.nf
$ task 4 list
ID Age Project Tags Description Urg
4 9min Family nancy paul or or Call Paul 0
.fi
There is no clear mapping between the complex filter used and the modifications
@ -1307,16 +1419,20 @@ operators being present in the description. Taskwarrior does not try to guess
the user intention here, and instead, the user is expected to set the
"context.<name>.write" variable to make their intention explicit, for example:
.nf
$ task config context.family.write project:Family
Are you sure you want to change the value of 'context.family.write' from 'project:Family or +paul or +nancy' to 'project:Family'? (yes/no) yes
Config file /home/tbabej/.config/task/taskrc modified.
.fi
.nf
$ task context
Name Type Definition Active
family read project:Family or +paul or +nancy yes
write project:Family yes
home read +home no
write +home no
.fi
Note how read and write contexts differ for context "family", while for context
"home" they stay the same.
@ -1325,74 +1441,75 @@ In addition, every configuration parameter can be overridden for the current
context, by specifying context.<name>.rc.<parameter>. For example, if the default
command for the family context should be displaying the family_report:
.nf
$ task config context.family.rc.default.command family_report
.fi
.SH COMMAND ABBREVIATION
All Taskwarrior commands may be abbreviated as long as a unique prefix is used,
for example:
.RS
.nf
$ task li
.RE
.fi
is an unambiguous abbreviation for
.RS
.nf
$ task list
.RE
.fi
but
.RS
.nf
$ task l
.RE
.fi
could be list, ls or long.
Note that you can restrict the minimum abbreviation size using the configuration
setting:
.RS
.nf
abbreviation.minimum=3
.RE
.fi
.SH SPECIFYING DESCRIPTIONS
Some task descriptions need to be escaped because of the shell and the special
meaning of some characters to the shell. This can be done either by adding
quotes to the description or escaping the special character:
.RS
.nf
$ task add "quoted ' quote"
.br
$ task add escaped \\' quote
.RE
.fi
The argument \-\- (a double dash) tells Taskwarrior to treat all other args
as description:
.RS
.nf
$ task add -- project:Home needs scheduling
.RE
.fi
In other situations, the shell sees spaces and breaks up arguments. For
example, this command:
.RS
.nf
$ task 123 modify /from this/to that/
.RE
.fi
is broken up into several arguments, which is corrected with quotes:
.RS
.nf
$ task 123 modify "/from this/to that/"
.RE
.fi
It is sometimes necessary to force the shell to pass quotes to Taskwarrior
intact, so you can use:
.RS
.nf
$ task add project:\\'Three Word Project\\' description
.RE
.fi
Taskwarrior supports Unicode using only the UTF8 encoding.

188
doc/man/taskrc.5.in
View file

@ -18,43 +18,43 @@ obtains its configuration data from a file called
.I .taskrc
\&. This file is normally located in the user's home directory:
.RS
.nf
$HOME/.taskrc
.RE
.fi
The default location can be overridden using the
.I rc:
attribute when running task:
.RS
.nf
$ task rc:<directory-path>/.taskrc ...
.RE
.fi
or using the TASKRC environment variable:
.RS
.nf
$ TASKRC=/tmp/.taskrc task ...
.RE
.fi
Additionally, if no ~/.taskrc exists, taskwarrior will check if the XDG_CONFIG_HOME environment variable is defined:
.RS
.nf
$ XDG_CONFIG_HOME=~/.config task ...
.RE
.fi
Individual options can be overridden by using the
.I rc.<name>:
attribute when running task:
.RS
.nf
$ task rc.<name>:<value> ...
.RE
.fi
or
.RS
.nf
$ task rc.<name>=<value> ...
.RE
.fi
If
.B Taskwarrior
@ -65,9 +65,9 @@ file in the user's home directory.
The .taskrc file follows a very simple syntax defining name/value pairs:
.RS
.nf
<name> = <value>
.RE
.fi
There may be whitespace around <name>, '=' and <value>, and it is ignored.
Whitespace within the <value> is left intact.
@ -79,9 +79,9 @@ Note that Taskwarrior is flexible about the values used to represent Boolean
items. You can use "1" to enable, anything else is interpreted as disabled.
The values "on", "yes", "y" and "true" are currently supported but deprecated.
.RS
.nf
include <file>
.RE
.fi
There may be whitespace around 'include' and <file>. The file may be an
absolute or relative path, and the special character '~' is expanded to mean
@ -95,9 +95,9 @@ respect to the following directories (listed in order of precedence):
Note that environment variables are also expanded in paths (and any other
taskrc variables).
.RS
.nf
# <comment>
.RE
.fi
A comment consists of the character '#', and extends from the '#' to the end
of the line. There is no way to comment a multi-line block. There may be
@ -108,9 +108,9 @@ that makes use of every default. The contents of the .taskrc file therefore
represent overrides of the default values. To remove a default value completely
there must be an entry like this:
.RS
.nf
<name> =
.RE
.fi
This entry overrides the default value with a blank value.
@ -118,28 +118,28 @@ This entry overrides the default value with a blank value.
You can edit your .taskrc file by hand if you wish, or you can use the 'config'
command. To permanently set a value in your .taskrc file, use this command:
.RS
.nf
$ task config nag "You have more urgent tasks."
.RE
.fi
To delete an entry, use this command:
.RS
.nf
$ task config nag
.RE
.fi
Taskwarrior will then use the default value. To explicitly set a value to
blank, and therefore avoid using the default value, use this command:
.RS
.nf
$ task config nag ""
.RE
.fi
Taskwarrior will also display all your settings with this command:
.RS
.nf
$ task show
.RE
.fi
and in addition, will also perform a check of all the values in the file,
warning you of anything it finds amiss.
@ -149,20 +149,19 @@ The .taskrc can include other files containing configuration settings by using t
.B include
statement:
.RS
.nf
include <path/to/the/configuration/file/to/be/included>
.RE
.fi
By using include files you can divide your main configuration file into several
ones containing just the relevant configuration data like colors, etc.
There are two excellent uses of includes in your .taskrc, shown here:
.RS
.nf
include holidays.en-US.rc
.br
include dark-16.theme
.RE
.fi
This includes two standard files that are distributed with Taskwarrior, which
define a set of US holidays, and set up a 16-color theme to use, to color the
@ -299,6 +298,7 @@ is most readily parsed and used by shell scripts.
Alternatively, you can specify a comma-separated list of verbosity tokens that
control specific occasions when output is generated. This list may contain:
.nf
blank Inserts extra blank lines in output, for clarity
header Messages that appear before report output (this includes .taskrc/.task overrides and the "[task next]" message)
footnote Messages that appear after report output (mostly status messages and change descriptions)
@ -315,6 +315,7 @@ control specific occasions when output is generated. This list may contain:
override Notification when configuration options are overridden
recur Notification when a new recurring task instance is created
default Notifications about taskwarrior choosing to perform a default action.
.fi
The tokens "affected", "new-id", "new-uuid", "project", "override" and "recur"
imply "footnote".
@ -326,14 +327,20 @@ and the "nothing" setting is equivalent to none of the tokens being specified.
Here are the shortcut equivalents:
.nf
verbose=on
verbose=blank,header,footnote,label,new-id,affected,edit,special,project,sync,filter,override,recur
.fi
.nf
verbose=0
verbose=blank,label,new-id,edit
.fi
.nf
verbose=nothing
verbose=
.fi
Those additional comments are sent to the standard error for header, footnote
and project. The others are sent to standard output.
@ -584,51 +591,29 @@ are formatted according to dateformat.
The default value is the ISO-8601 standard: Y-M-D. The string can contain the
characters:
.RS
.RS
.nf
m minimal-digit month, for example 1 or 12
.br
d minimal-digit day, for example 1 or 30
.br
y two-digit year, for example 09 or 12
.br
D two-digit day, for example 01 or 30
.br
M two-digit month, for example 01 or 12
.br
Y four-digit year, for example 2009 or 2015
.br
a short name of weekday, for example Mon or Wed
.br
A long name of weekday, for example Monday or Wednesday
.br
b short name of month, for example Jan or Aug
.br
B long name of month, for example January or August
.br
v minimal-digit week, for example 3 or 37
.br
V two-digit week, for example 03 or 37
.br
h minimal-digit hour, for example 3 or 21
.br
n minimal-digit minutes, for example 5 or 42
.br
s minimal-digit seconds, for example 7 or 47
.br
H two-digit hour, for example 03 or 21
.br
N two-digit minutes, for example 05 or 42
.br
S two-digit seconds, for example 07 or 47
.br
J three-digit Julian day, for example 023 or 365
.br
j Julian day, for example 23 or 365
.br
w Week day, for example 0 for Monday, 5 for Friday
.RE
.RE
.fi
.RS
The characters 'v', 'V', 'a' and 'A' can only be used for formatting printed
@ -640,37 +625,24 @@ The string may also contain other characters to act as spacers, or formatting.
Examples for other values of dateformat:
.RE
.RS
.RS
.br
.nf
d/m/Y would use for input and output 24/7/2009
.br
yMD would use for input and output 090724
.br
M-D-Y would use for input and output 07-24-2009
.RE
.RE
.fi
.RS
Examples for other values of dateformat.report:
.RE
.RS
.RS
.br
.nf
a D b Y (V) would emit "Fri 24 Jul 2009 (30)"
.br
A, B D, Y would emit "Friday, July 24, 2009"
.br
wV a Y-M-D would emit "w30 Fri 2009-07-24"
.br
yMD.HN would emit "110124.2342"
.br
m/d/Y H:N would emit "1/24/2011 10:42"
.br
a D b Y H:N:S would emit "Mon 24 Jan 2011 11:19:42"
.RE
.RE
.fi
.RS
Undefined fields are put to their minimal valid values (1 for month and day and
@ -679,14 +651,10 @@ field that is set. Otherwise, they are set to the corresponding values of
"now". For example:
.RE
.RS
.RS
.br
.nf
8/1/2013 with m/d/Y implies August 1, 2013 at midnight (inferred)
.br
8/1 20:40 with m/d H:N implies August 1, 2013 (inferred) at 20:40
.RE
.RE
.fi
.TP
.B date.iso=1
@ -780,28 +748,19 @@ Holidays are entered either directly in the .taskrc file or via an include file
that is specified in .taskrc. For single-day holidays the name and the date is
required to be given:
.RS
.RS
.br
.nf
holiday.towel.name=Day of the towel
.br
holiday.towel.date=20100525
.RE
.RE
.fi
For holidays that span a range of days (i.e. vacation), you can use a start date
and an end date:
.RS
.RS
.br
.nf
holiday.sysadmin.name=System Administrator Appreciation Week
.br
holiday.sysadmin.start=20100730
.br
holiday.sysadmin.end=20100805
.RE
.RE
.fi
.RS
Dates are to be entered according to the setting in the dateformat.holiday
@ -814,24 +773,17 @@ Easter (easter), Easter Monday (eastermonday), Ascension (ascension), Pentecost
(pentecost). The date for these holidays is the given keyword:
.RE
.RS
.RS
.br
.nf
holiday.eastersunday.name=Easter
.br
holiday.eastersunday.date=easter
.RE
.RE
.fi
Note that the Taskwarrior distribution contains example holiday files that can
be included like this:
.RS
.RS
.br
.nf
include holidays.en-US.rc
.RE
.RE
.fi
.SS DEPENDENCIES
@ -919,10 +871,9 @@ Task is deleted.
.RS
To disable a coloration rule for which there is a default, set the value to
nothing, for example:
.RS
.B color.tagged=
.RE
.RE
.nf
color.tagged=
.fi
.RS
By default, colors produced by rules blend. This has the advantage of
@ -1257,30 +1208,23 @@ default.command=next
Provides a default command that is run every time Taskwarrior is invoked with no
arguments. For example, if set to:
.RS
.RS
.nf
default.command=project:foo list
.RE
.RE
.fi
.RS
then Taskwarrior will run the "project:foo list" command if no command is
specified. This means that by merely typing
.RE
.RS
.RS
.nf
$ task
.br
[task project:foo list]
.br
\&
.br
ID Project Pri Description
1 foo H Design foo
2 foo Build foo
.RE
.RE
.fi
.SS REPORTS
@ -1319,12 +1263,16 @@ specified by using the column ids post-fixed by a "+" for ascending sort order
or a "-" for descending sort order. The sort IDs are separated by commas.
For example:
.nf
report.list.sort=due+,priority-,start.active-,project+
.fi
Additionally, after the "+" or "-", there can be a solidus "/" which indicates
that there are breaks after the column values change. For example:
.nf
report.minimal.sort=project+/,description+
.fi
This sort order now specifies that there is a listing break between each
project. A listing break is simply a blank line, which provides a visual