From 6e52194ab0dce66f05174f615c71863bdc81d156 Mon Sep 17 00:00:00 2001 From: Paul Beckingham Date: Tue, 13 Sep 2011 18:33:14 -0400 Subject: [PATCH] Documentation - While the man pages were not exactly updated for 2.0, the harmful and obsolete stuff was removed. --- doc/man/task-color.5.in | 51 ++++++----- doc/man/task-faq.5.in | 12 +-- doc/man/task-tutorial.5.in | 2 + doc/man/task.1.in | 173 +++++++++++++++---------------------- 4 files changed, 107 insertions(+), 131 deletions(-) diff --git a/doc/man/task-color.5.in b/doc/man/task-color.5.in index e4769758a..9c7460128 100644 --- a/doc/man/task-color.5.in +++ b/doc/man/task-color.5.in @@ -41,14 +41,14 @@ 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: - $ task config | grep '^color ' + $ task show | grep '^color ' color off -it always returns 'off', no matter what the setting. +it always returns 'off', no matter what the setting, because the output is being +sent to a pipe. -The reason is that the taskwarrior output gets piped into grep, and the color is -disabled. If you wanted those color codes, you can override this behavior by -setting the _forcecolor variable to on, like this: +If you wanted those color codes, you can override this behavior by setting the +_forcecolor variable to on, like this: $ task config _forcecolor on $ task config | grep '^color ' @@ -121,7 +121,7 @@ the sample requested. Some combinations look very nice, some look terrible. Different terminal programs do implement slightly different versions of 'red', for example, so you -may see some unwanted variation due to the program. The brightness of your +may see some unexpected variation across machines. The brightness of your display is also a factor. .SH 256-COLOR SUPPORT @@ -193,7 +193,7 @@ combination: red on gray3 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. +to color1, and proceed. Note that red and color1 are not quite the same tone. Note also that there is no bold or bright attributes when dealing with 256 colors, but there is still underline available. @@ -210,7 +210,7 @@ without necessarily creating a set of tasks that meet each of the rule criteria. .SH RULES Taskwarrior supports colorization rules. These are configuration values that specify a color, and the conditions under which that color is used. By example, -let's add a few tasks: +let us add a few tasks: $ task add project:Home priority:H pay the bills (1) $ task add project:Home clean the rug (2) @@ -219,13 +219,13 @@ let's add a few tasks: We can add a color rule that uses a blue background for all tasks in the Home project: - $ task config color.project.Home on blue + $ task config color.project.Home 'on blue' -We use quotes around "on blue" because there are two words, but they represent +We use quotes around 'on blue' because there are two words, but they represent one value in the .taskrc file. Now suppose we which to use a bold yellow text color for all cleaning work: - $ task config color.keyword.clean bold yellow + $ task config color.keyword.clean 'bold yellow' 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 @@ -243,16 +243,17 @@ be a visual mess. Beware! The precedence for the color rules is determined by the configuration variable 'rule.precedence.color', which by default contains: - due.today,active,blocked,overdue,due,keyword,project,tag,recurring,pri,tagged + due.today,active,blocked,overdue,due,keyword,project,tag,recurring,pri,tagged,completed,deleted These are just the color rules with the 'color.' prefix removed. The -rule 'color.due.today' is the highest precedence, and 'color.tagged' is the lowest. +rule 'color.due.today' is the highest precedence, and 'color.deleted' is the lowest. The keyword rule shown here as 'keyword' corresponds to a wildcard pattern, meaning 'color.keyword.*', or in other words all the keyword rules. Similarly for the 'color.tag.*' and 'color.project.*' rules. -There is also 'color.project.none', 'color.tag.none' and 'color.pri.none'. +There is also 'color.project.none', 'color.tag.none' and 'color.pri.none' to +specifically represent missing data. .SH THEMES Taskwarrior supports themes. What this really means is that with the ability to @@ -269,19 +270,29 @@ include /usr/local/share/doc/task/rc/dark-256.theme You can use any of the standard taskwarrior themes: .RS -light-16.theme -.br -light-256.theme -.br dark-16.theme .br dark-256.theme .br -dark-red-256.theme +dark-blue-256.theme +.br +dark-gray-256.theme .br dark-green-256.theme .br -dark-blue-256.theme +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 .RE You can also see how the theme will color the various tasks with the command: diff --git a/doc/man/task-faq.5.in b/doc/man/task-faq.5.in index 61782abb2..9e2053be3 100644 --- a/doc/man/task-faq.5.in +++ b/doc/man/task-faq.5.in @@ -51,8 +51,8 @@ aliases. Here are example Bash commands to achieve this: % cp ~/.taskrc ~/.taskrc_home % (now edit .taskrc_home to change the value of data.location) - % alias wtask="task" - % alias htask="task rc:~/.taskrc_home" + % alias wtask="task" + % alias htask="task rc:~/.taskrc_home" This gives you two commands, 'wtask' and 'htask' that operate using two different sets of task data files. @@ -144,8 +144,8 @@ particularly if your .taskrc file was created by an older version. .TP .B Q: Do I need to back up my taskwarrior data? -Yes. You should back up your ~/.task directory, and probably your ~/.taskrc -file too. +Yes. You should back up all the files in your ~/.task directory, and probably +your ~/.taskrc file too. .TP .B Q: Can I share my tasks between different machines? @@ -253,9 +253,9 @@ When you run a report (such as "list"), the numbers are assigned before display. For example, you can do this: $ task list - $ task do 12 + $ task 12 done $ task add Pay the rent - $ task delete 31 + $ task 31 delete Those id numbers are then good until the next report is run. This is because taskwarrior performs a garbage-collect operation on the pending tasks file when diff --git a/doc/man/task-tutorial.5.in b/doc/man/task-tutorial.5.in index 968314497..2ab56f21f 100644 --- a/doc/man/task-tutorial.5.in +++ b/doc/man/task-tutorial.5.in @@ -3,6 +3,8 @@ .SH NAME task-tutorial \- A tutorial for the task(1) command line todo manager. +NOTE THAT THIS DOCUMENT HAS NOT YET BEEN UPDATED FOR THE 2.0 RELEASE. + .SH DESCRIPTION This tutorial contains a narrative and a series of commands that lead you through different scenarios and illustrate the capabilities of taskwarrior. diff --git a/doc/man/task.1.in b/doc/man/task.1.in index 179d260c1..724671296 100644 --- a/doc/man/task.1.in +++ b/doc/man/task.1.in @@ -3,6 +3,8 @@ .SH NAME task \- A command line todo manager. +NOTE THAT THIS DOCUMENT HAS NOT BEEN FULLY UPDATED FOR THE 2.0 RELEASE. + .SH SYNOPSIS .B task [subcommand] [args] @@ -22,32 +24,28 @@ the way you want to see it. .SH SUBCOMMANDS .TP -.B add [tags] [attrs] description +.B add Adds a new task to the task list. .TP -.B log [tags] [attrs] description +.B log Adds a new task that is already completed, to the task list. .TP -.B annotate ID description +.B annotate Adds an annotation to an existing task. .TP -.B denotate ID description +.B denotate Deletes an annotation for the specified task. If the provided description matches an annotation exactly, the corresponding annotation is deleted. If the provided description matches annotations partly, the first partly matched annotation is deleted. .TP -.B information ID +.B information Shows all data and metadata for the specified task. -.TP -.B ID -With an ID but no specific command, taskwarrior runs the "information" command. - .TP .B undo Reverts the most recent action. Obeys the confirmation setting. @@ -57,38 +55,38 @@ Reverts the most recent action. Obeys the confirmation setting. Launches an interactive shell with all the task commands available. .TP -.B duplicate ID [tags] [attrs] [description] +.B duplicate Duplicates the specified task and allows modifications. .TP -.B delete ID +.B delete Deletes the specified task from task list. .TP -.B start ID +.B start Marks the specified task as started. .TP -.B stop ID +.B stop Removes the .I start time from the specified task. .TP -.B done ID [tags] [attrs] [description] +.B done Marks the specified task as done. .TP -.B projects +.B projects Lists all project names that are currently used by pending tasks, and the number of tasks for each. .TP -.B tags +.B tags Show a list of all tags used. Any special tags used are highlighted. .TP -.B summary +.B summary Shows a report of task status by project. .TP @@ -96,31 +94,31 @@ Shows a report of task status by project. Shows a weekly report of tasks completed and started. .TP -.B history +.B history Shows a report of task history by month. Alias to history.monthly. .TP -.B history.annual +.B history.annual Shows a report of task history by year. .TP -.B ghistory +.B ghistory Shows a graphical report of task status by month. Alias to ghistory.monthly. .TP -.B ghistory.annual +.B ghistory.annual Shows a graphical report of task status by year. .TP -.B burndown.daily +.B burndown.daily Shows a graphical burndown chart, by day. .TP -.B burndown.weekly +.B burndown.weekly Shows a graphical burndown chart, by week. .TP -.B burndown.monthly +.B burndown.monthly Shows a graphical burndown chart, by month. .TP @@ -128,7 +126,7 @@ Shows a graphical burndown chart, by month. Shows a monthly calendar with due tasks marked. .TP -.B stats +.B stats Shows task database statistics. .TP @@ -137,30 +135,11 @@ Imports tasks in a variety of formats, from file or URL. .TP .B export -Exports all tasks in the default format. This is an alias to the command -export.yaml. Redirect the output to a file, if you wish to save it, or pipe it -to another command. +Exports all tasks in the JSON format. export.yaml. Redirect the output to a +file, if you wish to save it, or pipe it to another command. .TP -.B export.csv -Exports all tasks in CSV format. -Redirect the output to a file, if you wish to save it, or pipe it to another -command. - -.TP -.B export.ical -Exports all tasks in iCalendar format. -Redirect the output to a file, if you wish to save it, or pipe it to another -command. - -.TP -.B export.yaml -Exports all tasks in YAML 1.1 format. -Redirect the output to a file, if you wish to save it, or pipe it to another -command. - -.TP -.B merge URL +.B merge Merges two task databases by comparing the modifications that are stored in the undo.data files. The location of the second undo.data file must be passed on as argument. URL may have the following syntaxes: @@ -177,14 +156,14 @@ You can set aliases for frequently used URLs in the .taskrc. Further documentati can be found in task-sync(5) manpage. .TP -.B push URL +.B push Pushes the task database to a remote another location for distributing the changes made by the merge command. (See annotations above for valid URL syntaxes.) .TP -.B pull URL +.B pull Overwrites the task database with those files found at the URL. (See annotations above for valid URL syntaxes.) @@ -195,16 +174,16 @@ Displays all possible colors, a named sample, or a legend containing all currently defined colors. .TP -.B count [filter] +.B count Displays only a count of tasks matching the filter. .TP -.B ids [filter] +.B ids Applies the filter then extracts only the task IDs and presents them as a range, for example: 1-4,12. This is useful as input to a task command, to achieve this: - task priority:H $(task ids project:Home) + task modify priority:H $(task project:Home ids) This example first gets the IDs for the project:Home filter, then sets the priority to H for each of those tasks. @@ -249,37 +228,21 @@ Finally, this command removes any 'name=...' entry from the .taskrc file: .SH MODIFYING SUBCOMMANDS .TP -.B ID [tags] [attrs] [description] +.B modify Modifies the existing task with provided information. .TP -.B ID /from/to/ -Performs one substitution on task description and annotation for fixing -mistakes. - -If either 'from' or 'to' contain spaces, you will need to put quotes around -the whole thing. - -.TP -.B ID /from/to/g -Performs all substitutions on task description and annotation for fixing -mistakes. - -If either 'from' or 'to' contain spaces, you will need to put quotes around -the whole thing. - -.TP -.B edit ID +.B edit Launches an editor to let you modify all aspects of a task directly. In general, this is not the recommended method of modifying tasks, but is provided for exceptional circumstances. Use carefully. .TP -.B append [tags] [attrs] description +.B append Appends information to an existing task. .TP -.B prepend [tags] [attrs] description +.B prepend Prepends information to an existing task. .SH REPORT SUBCOMMANDS @@ -290,76 +253,76 @@ these reports can be configured in the configuration file. See also the man page taskrc(5). .TP -.B active [filter] +.B active Shows all tasks matching the filter that are started but not completed. .TP -.B all [filter] +.B all Shows all tasks matching the filter, including parents of recurring tasks. .TP -.B completed [filter] +.B completed Shows all tasks matching the filter that are completed. .TP -.B minimal [filter] +.B minimal Provides a minimal listing of tasks matching the filter. .TP -.B ls [filter] +.B ls Provides a short listing of tasks matching the filter. .TP -.B list [filter] +.B list Provides a more detailed listing of tasks matching the filter. .TP -.B long [filter] +.B long Provides the most detailed listing of tasks with filter. .TP -.B newest [filter] +.B newest Shows the newest tasks with filter. .TP -.B oldest [filter] +.B oldest Shows the oldest tasks with filter .TP -.B overdue [filter] +.B overdue Shows all incomplete tasks matching the filter that are beyond their due date. .TP -.B recurring [filter] +.B recurring Shows all recurring tasks matching the filter. .TP -.B waiting [filter] +.B waiting Shows all waiting tasks matching the filter. .TP -.B blocked [filter] +.B blocked Shows all blocked tasks, that are dependent on other tasks, matching the filter. .TP -.B unblocked [filter] +.B unblocked Shows all tasks that are not blocked by dependencies, matching the filter. .TP -.B next [filter] -Shows all tasks with upcoming due dates matching the filter. +.B next +Shows a page of the most urgent tasks. Urgency is a calculated value. .SH FILTERS A filter is a set of search criteria that the report applies before displaying the results. For example, to list all tasks belonging to the 'Home' project: - task list project:Home + task project:Home list You can specify multiple filters, each of which further restrict the results: - task list project:Home +weekend garden + task project:Home +weekend garden list This example applies three filters: the 'Home' project, the 'weekend' tag, and the description or annotations must contain the characters 'garden'. In this @@ -381,7 +344,7 @@ modification to the database. Always run a report to check you have the right ID for a task. IDs can be given to task as a sequences, for example, .br .B -task del 1,4-10,19 +task 1,4-10,19 del .TP .B +tag|-tag @@ -418,11 +381,11 @@ Specifies the Recurrence end-date of a task. .TP .B fg: -Specifies foreground color. +Specifies foreground color. Deprecated. .TP .B bg: -Specifies background color. +Specifies background color. Deprecated. .TP .B limit: @@ -480,7 +443,7 @@ the complementary set of items. Supported modifiers are: For example: .RS -task list due.before:eom priority.not:L +task due.before:eom priority.not:L list .RE The @@ -500,8 +463,8 @@ The .I none modifier requires that the attribute does not have a value. For example: - task list priority: - task list priority.none: + task priority: list + task priority.none: list are equivalent, and list tasks that do not have a priority. @@ -523,8 +486,8 @@ The .I has modifier is used to search for a substring, such as: - task list description.has:foo - task list foo + task description.has:foo list + task foo list which are equivalent and will return any task that has 'foo' in the description or annotations. @@ -539,14 +502,14 @@ The .I startswith modifier matches against the left, or beginning of an attribute, such that: - task list project.startswith:H - task list project:H + task project.startswith:H list + task project:H list are equivalent and will match any project starting with 'H'. Matching all projects not starting with 'H' is done with: - task list project.~startswith:H - task list project.not:H + task project.~startswith:H list + task project.not:H list The .I endswith @@ -557,7 +520,7 @@ The modifier requires that the attribute contain the whole word specified, such that this: - task list description.word:bar + task description.word:bar list will match the description 'foo bar baz' but does not match 'dog food'. @@ -728,13 +691,13 @@ In other situations, the shell sees spaces and breaks up arguments. For example, this command: .RS -$ task 123 /from this/to that/ +$ task 123 modify /from this/to that/ .RE is broken up into several arguments, which is corrected with quotes: .RS -$ task 123 "/from this/to that/" +$ task 123 modify "/from this/to that/" .RE .SH CONFIGURATION FILE AND OVERRIDE OPTIONS