From 910860ae1cf8d0d0be4dd6b968d15eeaa6ec0a1f Mon Sep 17 00:00:00 2001 From: Sebastian Carlos <88276600+sebastiancarlos@users.noreply.github.com> Date: Mon, 24 Jun 2024 15:00:12 -0300 Subject: [PATCH] Properly tag monospaced text in man pages. (Improves HTML rendering) (#3509) 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 --- doc/man/task-color.5.in | 106 +++++++++----- doc/man/task-sync.5.in | 20 +++ doc/man/task.1.in | 309 +++++++++++++++++++++++++++------------ doc/man/taskrc.5.in | 314 +++++++++++++++++----------------------- 4 files changed, 436 insertions(+), 313 deletions(-) diff --git a/doc/man/task-color.5.in b/doc/man/task-color.5.in index 493fe713b..6464b8023 100644 --- a/doc/man/task-color.5.in +++ b/doc/man/task-color.5.in @@ -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 -include dark-256.theme -.RE +.nf + include dark-256.theme +.fi You can use any of the standard Taskwarrior themes: -.RS -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 +.nf + dark-16.theme + dark-256.theme + dark-blue-256.theme + dark-gray-256.theme + dark-green-256.theme + dark-red-256.theme + dark-violets-256.theme + dark-yellow-green.theme + light-16.theme + light-256.theme + solarized-dark-256.theme + solarized-light-256.theme + dark-default-16.theme + dark-gray-blue-256.theme + no-color.theme +.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 . diff --git a/doc/man/task-sync.5.in b/doc/man/task-sync.5.in index 8f9b626c7..c8d7c5a53 100644 --- a/doc/man/task-sync.5.in +++ b/doc/man/task-sync.5.in @@ -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 +.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 $ task config sync.server.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 +.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 $ task config sync.gcp.credential_path +.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 diff --git a/doc/man/task.1.in b/doc/man/task.1.in index 7b3b57c90..e26eafebc 100644 --- a/doc/man/task.1.in +++ b/doc/man/task.1.in @@ -24,18 +24,24 @@ descriptors), project groups, etc. The 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 task 28 task +weekend task +bills due.by:eom task project:Home due.before:today task ebeeab00-ccf8-464b-8b58-f7f2d606edfb +.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]+/ )' +.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 consist of zero or more changes to apply to the selected tasks, such as: +.nf task project:Home task +weekend +garden due:tomorrow task Description/annotation text task /from/to/ <- replace first match task /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 : +.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 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 @@ -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 [ [ | '']] @@ -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 @@ -455,7 +493,9 @@ Sets the currently active context. See the CONTEXT section. Example: +.nf task context work +.fi .TP .B task context delete @@ -464,7 +504,9 @@ set as active, it will be unset. Example: +.nf task context delete work +.fi .TP .B task context define @@ -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 _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. tw.syncneeded tw.program @@ -669,6 +720,7 @@ from tasks, or the system. Supported DOM references are: system.os . . +.fi Note that the 'rc.' 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 -task due.before:eom priority.not:L list -.RE +.nf + task due.before:eom priority.not:L list +.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 -task ... due:7/14/2008 +.nf + task ... due:7/14/2008 +.fi .TP ISO-8601 -task ... due:2013-03-14T22:30:00Z +.nf + task ... due:2013-03-14T22:30:00Z +.fi .TP Relative wording -task ... due:now -.br -task ... due:today -.br -task ... due:yesterday -.br -task ... due:tomorrow +.nf + task ... due:now + task ... due:today + task ... due:yesterday + task ... due:tomorrow +.fi .TP Day number with ordinal -task ... due:23rd -.br -task ... due:3wks -.br -task ... due:1day -.br -task ... due:9hrs +.nf + task ... due:23rd + task ... due:3wks + task ... due:1day + task ... due:9hrs +.fi .TP Start of next (work) week (Monday), calendar week (Sunday or Monday), month, quarter and year -.br -task ... due:sow -.br -task ... due:soww -.br -task ... due:socw -.br -task ... due:som -.br -task ... due:soq -.br -task ... due:soy +.nf + task ... due:sow + task ... due:soww + task ... due:socw + task ... due:som + task ... due:soq + task ... due:soy +.fi .TP End of current (work) week (Friday), calendar week (Saturday or Sunday), month, quarter and year -.br -task ... due:eow -.br -task ... due:eoww -.br -task ... due:eocw -.br -task ... due:eom -.br -task ... due:eoq -.br -task ... due:eoy +.nf + task ... due:eow + task ... due:eoww + task ... due:eocw + task ... due:eom + task ... due:eoq + task ... due:eoy +.fi .TP At some point or later -.br -task ... wait:later -.br -task ... wait:someday +.nf + task ... wait:later + task ... wait:someday +.fi This sets the wait date to 12/30/9999. .TP Next occurring weekday -task ... due:fri +.nf + task ... due:fri +.fi .TP Predictable holidays -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 +.nf + task ... due:goodfriday + task ... due:easter + task ... due:eastermonday + task ... due:ascension + task ... due:pentecost + task ... due:midsommar + task ... due:midsommarafton + 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..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..rc.. 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 -$ task li -.RE +.nf + $ task li +.fi is an unambiguous abbreviation for -.RS -$ task list -.RE +.nf + $ task list +.fi but -.RS -$ task l -.RE +.nf + $ task l +.fi could be list, ls or long. Note that you can restrict the minimum abbreviation size using the configuration setting: -.RS -abbreviation.minimum=3 -.RE +.nf + abbreviation.minimum=3 +.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 -$ task add "quoted ' quote" -.br -$ task add escaped \\' quote -.RE +.nf + $ task add "quoted ' quote" + $ task add escaped \\' quote +.fi The argument \-\- (a double dash) tells Taskwarrior to treat all other args as description: -.RS -$ task add -- project:Home needs scheduling -.RE +.nf + $ task add -- project:Home needs scheduling +.fi In other situations, the shell sees spaces and breaks up arguments. For example, this command: -.RS -$ task 123 modify /from this/to that/ -.RE +.nf + $ task 123 modify /from this/to that/ +.fi is broken up into several arguments, which is corrected with quotes: -.RS -$ task 123 modify "/from this/to that/" -.RE +.nf + $ task 123 modify "/from this/to that/" +.fi It is sometimes necessary to force the shell to pass quotes to Taskwarrior intact, so you can use: -.RS -$ task add project:\\'Three Word Project\\' description -.RE +.nf + $ task add project:\\'Three Word Project\\' description +.fi Taskwarrior supports Unicode using only the UTF8 encoding. diff --git a/doc/man/taskrc.5.in b/doc/man/taskrc.5.in index 53d2ac515..8926d61f5 100644 --- a/doc/man/taskrc.5.in +++ b/doc/man/taskrc.5.in @@ -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 -$HOME/.taskrc -.RE +.nf + $HOME/.taskrc +.fi The default location can be overridden using the .I rc: attribute when running task: -.RS -$ task rc:/.taskrc ... -.RE +.nf + $ task rc:/.taskrc ... +.fi or using the TASKRC environment variable: -.RS -$ TASKRC=/tmp/.taskrc task ... -.RE +.nf + $ TASKRC=/tmp/.taskrc task ... +.fi Additionally, if no ~/.taskrc exists, taskwarrior will check if the XDG_CONFIG_HOME environment variable is defined: -.RS -$ XDG_CONFIG_HOME=~/.config task ... -.RE +.nf + $ XDG_CONFIG_HOME=~/.config task ... +.fi Individual options can be overridden by using the .I rc.: attribute when running task: -.RS -$ task rc.: ... -.RE +.nf + $ task rc.: ... +.fi or -.RS -$ task rc.= ... -.RE +.nf + $ task rc.= ... +.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 - = -.RE +.nf + = +.fi There may be whitespace around , '=' and , and it is ignored. Whitespace within the 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 -include -.RE +.nf + include +.fi There may be whitespace around 'include' and . 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 -# -.RE +.nf + # +.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 - = -.RE +.nf + = +.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 -$ task config nag "You have more urgent tasks." -.RE +.nf + $ task config nag "You have more urgent tasks." +.fi To delete an entry, use this command: -.RS -$ task config nag -.RE +.nf + $ task config nag +.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 -$ task config nag "" -.RE +.nf + $ task config nag "" +.fi Taskwarrior will also display all your settings with this command: -.RS -$ task show -.RE +.nf + $ task show +.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 -include -.RE +.nf + include +.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 -include holidays.en-US.rc -.br -include dark-16.theme -.RE +.nf + include holidays.en-US.rc + include dark-16.theme +.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 -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 +.nf + m minimal-digit month, for example 1 or 12 + d minimal-digit day, for example 1 or 30 + y two-digit year, for example 09 or 12 + D two-digit day, for example 01 or 30 + M two-digit month, for example 01 or 12 + Y four-digit year, for example 2009 or 2015 + a short name of weekday, for example Mon or Wed + A long name of weekday, for example Monday or Wednesday + b short name of month, for example Jan or Aug + B long name of month, for example January or August + v minimal-digit week, for example 3 or 37 + V two-digit week, for example 03 or 37 + h minimal-digit hour, for example 3 or 21 + n minimal-digit minutes, for example 5 or 42 + s minimal-digit seconds, for example 7 or 47 + H two-digit hour, for example 03 or 21 + N two-digit minutes, for example 05 or 42 + S two-digit seconds, for example 07 or 47 + J three-digit Julian day, for example 023 or 365 + j Julian day, for example 23 or 365 + w Week day, for example 0 for Monday, 5 for Friday +.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 -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 +.nf + d/m/Y would use for input and output 24/7/2009 + yMD would use for input and output 090724 + M-D-Y would use for input and output 07-24-2009 +.fi .RS Examples for other values of dateformat.report: .RE -.RS -.RS -.br -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 +.nf + a D b Y (V) would emit "Fri 24 Jul 2009 (30)" + A, B D, Y would emit "Friday, July 24, 2009" + wV a Y-M-D would emit "w30 Fri 2009-07-24" + yMD.HN would emit "110124.2342" + m/d/Y H:N would emit "1/24/2011 10:42" + a D b Y H:N:S would emit "Mon 24 Jan 2011 11:19:42" +.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 -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 +.nf + 8/1/2013 with m/d/Y implies August 1, 2013 at midnight (inferred) + 8/1 20:40 with m/d H:N implies August 1, 2013 (inferred) at 20:40 +.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 -holiday.towel.name=Day of the towel -.br -holiday.towel.date=20100525 -.RE -.RE +.nf + holiday.towel.name=Day of the towel + holiday.towel.date=20100525 +.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 -holiday.sysadmin.name=System Administrator Appreciation Week -.br -holiday.sysadmin.start=20100730 -.br -holiday.sysadmin.end=20100805 -.RE -.RE +.nf + holiday.sysadmin.name=System Administrator Appreciation Week + holiday.sysadmin.start=20100730 + holiday.sysadmin.end=20100805 +.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 -holiday.eastersunday.name=Easter -.br -holiday.eastersunday.date=easter -.RE -.RE +.nf + holiday.eastersunday.name=Easter + holiday.eastersunday.date=easter +.fi Note that the Taskwarrior distribution contains example holiday files that can be included like this: -.RS -.RS -.br -include holidays.en-US.rc -.RE -.RE +.nf + include holidays.en-US.rc +.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 -default.command=project:foo list -.RE -.RE +.nf + default.command=project:foo list +.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 -$ task -.br -[task project:foo list] -.br -\& -.br -ID Project Pri Description - 1 foo H Design foo - 2 foo Build foo -.RE -.RE +.nf + $ task + [task project:foo list] + + ID Project Pri Description + 1 foo H Design foo + 2 foo Build foo +.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