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

@@ -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
+If you wanted those color codes, you can override this behavior by setting the
-disabled.  If you wanted those color codes, you can override this behavior by
+_forcecolor variable to on, like this:
-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:

doc/man/task-faq.5.in

@@ -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
+Yes.  You should back up all the files in your ~/.task directory, and probably
-file too.
+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

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.

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 <modifications>
 Adds a new task to the task list.
 
 .TP
-.B log [tags] [attrs] description
+.B log <modifications>
 Adds a new task that is already completed, to the task list.
 
 .TP
-.B annotate ID description
+.B <filter> annotate <modifications>
 Adds an annotation to an existing task.
 
 .TP
-.B denotate ID description
+.B <filter> denotate <modifications>
 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 <filter> 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 <filter> duplicate <modifications>
 Duplicates the specified task and allows modifications.
 
 .TP
-.B delete ID
+.B <filter> delete <modifications>
 Deletes the specified task from task list.
 
 .TP
-.B start ID
+.B <filter> start <modifications>
 Marks the specified task as started.
 
 .TP
-.B stop ID
+.B <filter> stop <modifications>
 Removes the
 .I start
 time from the specified task.
 
 .TP
-.B done ID [tags] [attrs] [description]
+.B <filter> done <modifications>
 Marks the specified task as done.
 
 .TP
-.B projects
+.B <filter> projects
 Lists all project names that are currently used by pending tasks, and the
 number of tasks for each.
 
 .TP
-.B tags
+.B <filter> tags
 Show a list of all tags used.  Any special tags used are highlighted.
 
 .TP
-.B summary
+.B <filter> 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 <filter> history
 Shows a report of task history by month.  Alias to history.monthly.
 
 .TP
-.B history.annual
+.B <filter> history.annual
 Shows a report of task history by year.
 
 .TP
-.B ghistory
+.B <filter> ghistory
 Shows a graphical report of task status by month.  Alias to ghistory.monthly.
 
 .TP
-.B ghistory.annual
+.B <filter> ghistory.annual
 Shows a graphical report of task status by year.
 
 .TP
-.B burndown.daily
+.B <filter> burndown.daily
 Shows a graphical burndown chart, by day.
 
 .TP
-.B burndown.weekly
+.B <filter> burndown.weekly
 Shows a graphical burndown chart, by week.
 
 .TP
-.B burndown.monthly
+.B <filter> 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 <filter> 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
+Exports all tasks in the JSON format.  export.yaml.  Redirect the output to a
-export.yaml.  Redirect the output to a file, if you wish to save it, or pipe it
+file, if you wish to save it, or pipe it to another command.
-to another command.
 
 .TP
-.B export.csv
+.B merge <URL>
-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
 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 <URL>
 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 <URL>
 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 <filter> count
 Displays only a count of tasks matching the filter.
 
 .TP
-.B ids [filter]
+.B <filter> 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 <filter> modify <modifications>
 Modifies the existing task with provided information.
 
 .TP
-.B ID /from/to/
+.B <filter> edit
-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
 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 <filter> append <modifications>
 Appends information to an existing task.
 
 .TP
-.B prepend [tags] [attrs] description
+.B <filter> prepend <modifications>
 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 <filter> active
 Shows all tasks matching the filter that are started but not completed.
 
 .TP
-.B all [filter]
+.B <filter> all
 Shows all tasks matching the filter, including parents of recurring tasks.
 
 .TP
-.B completed [filter]
+.B <filter> completed
 Shows all tasks matching the filter that are completed.
 
 .TP
-.B minimal [filter]
+.B <filter> minimal
 Provides a minimal listing of tasks matching the filter.
 
 .TP
-.B ls [filter]
+.B <filter> ls
 Provides a short listing of tasks matching the filter.
 
 .TP
-.B list [filter]
+.B <filter> list
 Provides a more detailed listing of tasks matching the filter.
 
 .TP
-.B long [filter]
+.B <filter> long
 Provides the most detailed listing of tasks with filter.
 
 .TP
-.B newest [filter]
+.B <filter> newest
 Shows the newest tasks with filter.
 
 .TP
-.B oldest [filter]
+.B <filter> oldest
 Shows the oldest tasks with filter
 
 .TP
-.B overdue [filter]
+.B <filter> overdue
 Shows all incomplete tasks matching the filter
 that are beyond their due date.
 
 .TP
-.B recurring [filter]
+.B <filter> recurring
 Shows all recurring tasks matching the filter.
 
 .TP
-.B waiting [filter]
+.B <filter> waiting
 Shows all waiting tasks matching the filter.
 
 .TP
-.B blocked [filter]
+.B <filter> blocked
 Shows all blocked tasks, that are dependent on other tasks, matching the filter.
 
 .TP
-.B unblocked [filter]
+.B <filter> unblocked
 Shows all tasks that are not blocked by dependencies, matching the filter.
 
 .TP
-.B next [filter]
+.B <filter> next
-Shows all tasks with upcoming due dates matching the filter.
+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:<color-spec>
-Specifies foreground color.
+Specifies foreground color. Deprecated.
 
 .TP
 .B bg:<color-spec>
-Specifies background color.
+Specifies background color. Deprecated.
 
 .TP
 .B limit:<number-of-rows>
@@ -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 priority:      list
-    task list priority.none:
+    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 description.has:foo list
-    task list foo
+    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 project.startswith:H list
-    task list project:H
+    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 project.~startswith:H list
-    task list project.not:H
+    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