CMake

- the version number in the man pages is now set automatically via
  the ${PACKAGE_STRING} cmake variable

doc/man/task.1.in

@@ -0,0 +1,773 @@
+.TH task 1 2010-11-08 "${PACKAGE_STRING}" "User Manuals"
+
+.SH NAME
+task \- A command line todo manager.
+
+.SH SYNOPSIS
+.B task [subcommand] [args]
+
+.SH DESCRIPTION
+Taskwarrior is a command line todo list manager. It maintains a list of tasks
+that you want to do, allowing you to add/remove, and otherwise manipulate them.
+Task has a rich list of subcommands that allow you to do various things with it.
+
+At the core, taskwarrior is a list processing program. You add text and
+additional related parameters and redisplay the information in a nice way.  It
+turns into a todo list program when you add due dates and recurrence. It turns
+into an organized todo list program when you add priorities, tags (one word
+descriptors), project groups, etc.  Taskwarrior turns into an organized to do
+list program when you modify the configuration file to have the output displayed
+the way you want to see it.
+
+.SH SUBCOMMANDS
+
+.TP
+.B add [tags] [attrs] description
+Adds a new task to the task list.
+
+.TP
+.B log [tags] [attrs] description
+Adds a new task that is already completed, to the task list.
+
+.TP
+.B annotate ID description
+Adds an annotation to an existing task.
+
+.TP
+.B denotate ID description
+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 info ID
+Shows all data and metadata for the specified task.
+
+.TP
+.B ID
+With an ID but no specific command, taskwarrior runs the "info" command.
+
+.TP
+.B undo
+Reverts the most recent action.
+
+.TP
+.B shell
+Launches an interactive shell with all the task commands available.
+
+.TP
+.B duplicate ID [tags] [attrs] [description]
+Duplicates the specified task and allows modifications.
+
+.TP
+.B delete ID
+Deletes the specified task from task list.
+
+.TP
+.B start ID
+Marks the specified task as started.
+
+.TP
+.B stop ID
+Removes the
+.I start
+time from the specified task.
+
+.TP
+.B done ID [tags] [attrs] [description]
+Marks the specified task as done.
+
+.TP
+.B projects
+Lists all project names that are currently used by pending tasks, and the
+number of tasks for each.
+
+.TP
+.B tags
+Show a list of all tags used.  Any special tags used are highlighted.
+
+.TP
+.B summary
+Shows a report of task status by project.
+
+.TP
+.B timesheet [weeks]
+Shows a weekly report of tasks completed and started.
+
+.TP
+.B history
+Shows a report of task history by month.  Alias to history.monthly.
+
+.TP
+.B history.annual
+Shows a report of task history by year.
+
+.TP
+.B ghistory
+Shows a graphical report of task status by month.  Alias to ghistory.monthly.
+
+.TP
+.B ghistory.annual
+Shows a graphical report of task status by year.
+
+.TP
+.B burndown.daily
+Shows a graphical burndown chart, by day.
+
+.TP
+.B burndown.weekly
+Shows a graphical burndown chart, by week.
+
+.TP
+.B burndown.monthly
+Shows a graphical burndown chart, by month.
+
+.TP
+.B calendar [ y | due [y] | month year [y] | year ]
+Shows a monthly calendar with due tasks marked.
+
+.TP
+.B stats
+Shows task database statistics.
+
+.TP
+.B import \fIfile
+Imports tasks from a variety of formats.
+
+.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.
+
+.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
+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:
+
+	ssh://[user@]host.xz[:port]/path/to/undo.data
+
+	rsync://[user@]host.xz[:port]/path/to/undo.data
+
+	[user@]host.xz:path/to/undo.data
+
+	/path/to/local/undo.data
+
+You can set aliases for frequently used URLs in the .taskrc.
+
+.TP
+.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
+Overwrites the task database with those files found at the URL.
+
+(See annotations above for valid URL syntaxes.)
+
+.TP
+.B color [sample | legend]
+Displays all possible colors, a named sample, or a legend containing all
+currently defined colors.
+
+.TP
+.B count [filter]
+Displays only a count of tasks matching the filter.
+
+.TP
+.B version
+Shows the taskwarrior version number
+
+.TP
+.B help
+Shows the long usage text.
+
+.TP 
+.B show [all | substring]"
+Shows all the current settings in the taskwarrior configuration file. If a
+substring is specified just the settings containing that substring will be
+displayed.
+
+.TP
+.B config [name [value | '']]
+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':
+
+    task config name value
+
+This command sets a blank value.  This has the effect of suppressing any
+default value:
+
+    task config name ''
+
+Finally, this command removes any 'name=...' entry from the .taskrc file:
+
+    task config name
+
+.SH MODIFYING SUBCOMMANDS
+
+.TP
+.B ID [tags] [attrs] [description]
+Modifies the existing task with provided information.
+
+.TP
+.B ID /from/to/
+Performs one substitution on task description and annotation for fixing
+mistakes.
+
+.TP
+.B ID /from/to/g
+Performs all substitutions on task description and annotation for fixing
+mistakes.
+
+.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
+Appends information to an existing task.
+
+.TP
+.B prepend [tags] [attrs] description
+Prepends information to an existing task.
+
+.SH REPORT SUBCOMMANDS
+
+A report is a listing of information from the task database. There are several
+reports currently predefined in taskwarrior. The output and sort behavior of
+these reports can be configured in the configuration file. See also the man page
+taskrc(5).
+
+.TP
+.B active [filter]
+Shows all tasks matching the filter that are started but not completed.
+
+.TP
+.B all [filter]
+Shows all tasks matching the filter.
+
+.TP
+.B completed [filter]
+Shows all tasks matching the filter that are completed.
+
+.TP
+.B minimal [filter]
+Provides a minimal listing of tasks matching the filter.
+
+.TP
+.B ls [filter]
+Provides a short listing of tasks matching the filter.
+
+.TP
+.B list [filter]
+Provides a more detailed listing of tasks matching the filter.
+
+.TP
+.B long [filter]
+Provides the most detailed listing of tasks with filter.
+
+.TP
+.B newest [filter]
+Shows the newest tasks with filter.
+
+.TP
+.B oldest [filter]
+Shows the oldest tasks with filter
+
+.TP
+.B overdue [filter]
+Shows all incomplete tasks matching the filter
+that are beyond their due date.
+
+.TP
+.B recurring [filter]
+Shows all recurring tasks matching the filter.
+
+.TP
+.B waiting [filter]
+Shows all waiting tasks matching the filter.
+
+.TP
+.B blocked [filter]
+Shows all blocked tasks, that are dependent on other tasks, matching the filter.
+
+.TP
+.B unblocked [filter]
+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.
+
+.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
+
+You can specify multiple filters, each of which further restrict the results:
+
+    task list project:Home +weekend garden
+
+This example applies three filters: the 'Home' project, the 'weekend' tag, and
+the description or annotations must contain the characters 'garden'.  In this
+example, 'garden' is translated internally to:
+
+    description.contains:garden
+
+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.
+See 'ATTRIBUTE MODIFIERS' for a complete list of modifiers.
+
+.SH ATTRIBUTES AND METADATA
+
+.TP
+.B ID
+Tasks can be specified uniquely by IDs, which are simply the index of the
+task in a report. Be careful, as the IDs of tasks may change after a
+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
+
+.TP
+.B +tag|-tag
+Tags are arbitrary words associated with a task. Use + to add a tag and - to
+remove a tag from a task. A task can have any quantity of tags.
+
+Certain tags (called 'special tags'), can be used to affect the way tasks are
+treated.  For example, is a task has the special tag 'nocolor', then it is
+exempt from all color rules.  The supported special tags are:
+
+    +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
+
+.TP
+.B project:<project-name>
+Specifies the project to which a task is related to.
+
+.TP
+.B priority:H|M|L|N
+Specifies High, Medium, Low and No priority for a task.
+
+.TP
+.B due:<due-date>
+Specifies the due-date of a task.
+
+.TP
+.B recur:<frequency>
+Specifies the frequency of a recurrence of a task.
+
+.TP
+.B until:<end-date-of-recurrence>
+Specifies the Recurrence end-date of a task.
+
+.TP
+.B fg:<color-spec>
+Specifies foreground color.
+
+.TP
+.B bg:<color-spec>
+Specifies background color.
+
+.TP
+.B limit:<number-of-rows>
+Specifies the desired number of tasks a report should show, if a positive
+integer is given.  The value 'page' may also be used, and will limit the
+report output to as many lines of text as will fit on screen.  This defaults
+to 25 lines.
+
+.TP
+.B wait:<wait-date>
+Date until task becomes pending.
+
+.TP
+.B depends:<id1,id2 ...>
+Declares this task to be dependent on id1 and id2.  This means that the tasks
+id1 and id2 should be completed before this task.  Consequently, this task will
+then show up on the 'blocked' report.
+
+.SH ATTRIBUTE MODIFIERS
+Attribute modifiers improve filters.  Supported modifiers are:
+
+.RS
+.B before     (synonyms under, below)
+.br
+.B  after      (synonyms over, above)
+.br
+.B  none
+.br
+.B  any
+.br
+.B  is         (synonym equals)
+.br
+.B  isnt       (synonym not)
+.br
+.B  has        (synonym contains)
+.br
+.B  hasnt
+.br
+.B  startswith (synonym left)
+.br
+.B  endswith   (synonym right)
+.br
+.B  word
+.br
+.B  noword
+.RE
+
+For example:
+
+.RS
+task list due.before:eom priority.not:L
+.RE
+
+The
+.I before
+modifier is used to compare values, preserving semantics, so project.before:B
+list all projects that begin with 'A'.  Priority 'L' is before 'M', and
+due:2011-01-01 is before due:2011-01-02.  The synonyms 'under' and 'below' are
+included to allow filters that read more naturally.
+
+The
+.I after
+modifier is the inverse of the
+.I before
+modifier.
+
+The
+.I none
+modifier requires that the attribute does not have a value.  For example:
+
+    task list priority:
+    task list priority.none:
+
+are equivalent, and list tasks that do not have a priority.
+
+The
+.I any
+modifier requires that the attribute has a value, but any value will suffice.
+
+The
+.I is
+modifier requires an exact match with the value.
+
+The
+.I isnt
+modifier is the inverse of the
+.I is
+modifier.
+
+The
+.I has
+modifier is used to search for a substring, such as:
+
+    task list description.has:foo
+    task list foo
+
+which are equivalent and will return any task that has 'foo' in the description
+or annotations.
+
+The
+.I hasnt
+modifier is the inverse of the
+.I has
+modifier.
+
+The
+.I startswith
+modifier matches against the left, or beginning of an attribute, such that:
+
+    task list project.startswith:H
+    task list project:H
+
+are equivalent and will match any project starting with 'H'.
+
+The
+.I endswith
+modifier matches against the right, or end of an attribute.
+
+The
+.I word
+modifier requires that the attribute contain the whole word specified, such
+that this:
+
+    task list description.word:bar
+
+will match the description 'foo bar baz' but does not match 'dog food'.
+
+The
+.I noword
+modifier is the inverse of the
+.I word
+modifier.
+
+.SH SPECIFYING DATES AND FREQUENCIES
+
+.SS DATES
+Taskwarrior reads dates from the command line and displays dates in the
+reports.  The expected and desired date format is determined by the
+configuration variable
+.I dateformat
+in the taskwarrior configuration file.
+
+.RS
+.TP
+Exact specification
+task ... due:7/14/2008
+
+.TP
+Relative wording
+task ... due:today
+.br
+task ... due:yesterday
+.br
+task ... due:tomorrow
+
+.TP
+Day number with ordinal
+task ... due:23rd
+.br
+task ... due:3wks
+.br
+task ... due:1day
+.br
+task ... due:9hrs
+
+.TP
+Start of (work) week (Monday), calendar week (Sunday or Monday), month and year
+.br
+task ... due:sow
+.br
+task ... due:soww
+.br
+task ... due:socw
+.br
+task ... due:som
+.br
+task ... due:soy
+
+.TP
+End of (work) week (Friday), calendar week (Saturday or Sunday), month and year
+.br
+task ... due:eow
+.br
+task ... due:eoww
+.br
+task ... due:eocw
+.br
+task ... due:eom
+.br
+task ... due:eoy
+
+.TP
+Next occurring weekday
+task ... due:fri
+.RE
+
+.SS FREQUENCIES
+Recurrence periods. Taskwarrior supports several ways of specifying the
+.I frequency
+of recurring tasks.
+
+.RS
+.TP
+daily, day, 1d, 2d, ...
+Every day or a number of days.
+
+.TP
+weekdays
+Mondays, Tuesdays, Wednesdays, Thursdays, Fridays and skipping weekend days.
+
+.TP
+weekly, 1w, 2w, ...
+Every week or a number of weeks.
+
+.TP
+biweekly, fortnight
+Every two weeks.
+
+.TP
+quarterly, 1q, 2q, ...
+Every three months, a quarter, or a number of quarters.
+
+.TP
+semiannual
+Every six months.
+
+.TP
+annual, yearly, 1y, 2y, ...
+Every year or a number of years.
+
+.TP
+biannual, biyearly, 2y
+Every two years.
+.RE
+
+
+.SH COMMAND ABBREVIATION
+All taskwarrior commands may be abbreviated as long as a unique prefix is used,
+for example:
+
+.RS
+$ task li
+.RE
+
+is an unambiguous abbreviation for
+
+.RS
+$ task list
+.RE
+
+but
+
+.RS
+$ task l
+.RE
+
+could be list, ls or long.
+
+.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
+
+The argument \-\- (a double dash) tells taskwarrior to treat all other args
+as description:
+
+.RS
+$ task add -- project:Home needs scheduling
+.RE
+
+In other situations, the shell sees spaces and breaks up arguments.  For
+example, this command:
+
+.RS
+$ task 123 /from this/to that/
+.RE
+
+is broken up into several arguments, which is corrected with quotes:
+
+.RS
+$ task 123 "/from this/to that/"
+.RE
+
+.SH CONFIGURATION FILE AND OVERRIDE OPTIONS
+Taskwarrior stores its configuration in a file in the user's home directory:
+~/.taskrc . The default configuration file can be overridden with
+
+.TP
+.B task rc:<path-to-alternate-file>
+Specifies an alternate configuration file.
+
+.TP
+.B task rc.<name>:<value> ...
+Specifies individual configuration file overrides.
+
+.SH EXAMPLES
+
+For examples please see the task tutorial man page at
+
+.RS
+man task-tutorial
+.RE
+
+or the online documentation starting at
+
+.RS
+<http://taskwarrior.org/wiki/taskwarrior/Simple>
+.RE
+
+.SH FILES
+
+.TP
+~/.taskrc User configuration file - see also taskrc(5).
+
+.TP
+~/.task The default directory where task stores its data files. The location
+can be configured in the configuration file.
+
+.TP
+~/.task/pending.data The file that contains the tasks that are not yet done.
+
+.TP
+~/.task/completed.data The file that contains the completed "done" tasks.
+
+.TP
+~/.task/undo.data The file that contains the information to the "undo" command.
+
+.SH "CREDITS & COPYRIGHTS"
+Taskwarrior was written by P. Beckingham <paul@beckingham.net>.
+.br
+Copyright (C) 2006 \- 2011 P. Beckingham
+
+This man page was originally written by P.C. Shyamshankar, and has been modified
+and supplemented by Federico Hernandez.
+
+Thank also to T. Charles Yun.
+
+Taskwarrior is distributed under the GNU General Public License.  See
+http://www.gnu.org/licenses/gpl-2.0.txt for more information.
+
+.SH SEE ALSO
+.BR taskrc(5),
+.BR task-tutorial(5),
+.BR task-faq(5),
+.BR task-color(5),
+.BR task-sync(5)
+
+For more information regarding taskwarrior, the following may be referenced:
+
+.TP
+The official site at
+<http://taskwarrior.org>
+
+.TP
+The official code repository at
+<git://tasktools.org/task.git/>
+
+.TP
+You can contact the project by writing an email to
+<support@taskwarrior.org>
+
+.SH REPORTING BUGS
+.TP
+Bugs in taskwarrior may be reported to the issue-tracker at
+<http://taskwarrior.org>