From 0ab1dc0c9c3a4ac2acad9ee07ca90692838ea3a3 Mon Sep 17 00:00:00 2001 From: Tomas Babej Date: Sun, 22 Feb 2015 18:02:34 +0100 Subject: [PATCH] man: Update task and taskrc manpages with the information about context --- doc/man/task.1.in | 104 ++++++++++++++++++++++++++++++++++++++++++++ doc/man/taskrc.5.in | 20 +++++++++ 2 files changed, 124 insertions(+) diff --git a/doc/man/task.1.in b/doc/man/task.1.in index a55df9d67..65352f5d4 100644 --- a/doc/man/task.1.in +++ b/doc/man/task.1.in @@ -396,6 +396,46 @@ Finally, this command removes any 'name=...' entry from the .taskrc file: task config name +.TP +.B task context +Sets the currectly active context. See the CONTEXT section. + +Example: + + task context work + +.TP +.B task context delete +Deletes the context with the name . If the context being deleted is currently +set as active, it will be unset. + +Example: + + task context delete work + +.TP +.B task context define +Defines a new context with name and definition . This command +does not affect the currently set context, just adds a new context definition. + +Examples: + + task context define work project:Work + task context define home project:Home or +home + task context define superurgent due:today and +urgent + +.TP +.B task context list +Outputs a list of available contexts along with their definitions. + +.TP +.B task context none +Unsets the currently active context, if any was set. + +.TP +.B task context none +Shows the currently active context, along with its definition. + .TP .B task diagnostics Shows diagnostic information, of the kind needed when reporting a problem. @@ -474,6 +514,10 @@ Generates a list of all commands, for autocompletion purposes. .B task _config Lists all supported configuration variables, for completion purposes. +.TP +.B task _context +Lists all available context variables, for completion purposes. + .TP .B task _ids Shows only the IDs of matching tasks, in the form of a list. @@ -962,6 +1006,66 @@ biannual, biyearly, 2yr Every two years. .RE +.SH CONTEXT +Context is a user-defined filter, which is automatically applied to all commands +that filter the task list. In particular, any report command will have its +result affected by the current active context. + + $ task list + ID Age Project Description Urg + 1 2d Sport Run 5 miles 1.42 + 2 1d Home Clean the dishes 1.14 + + $ task context home + Context 'home' applied. + + $ task list + ID Age Project Description Urg + 2 1d Home Clean the dishes 1.14 + Context 'home' applied. + +As seen in the example above, context is applied by specifying its name to the +"context" command. To change the currently applied context, just pass the +new context's name to the 'context' command. + +To unset any context, use the 'none' subcommand. + + $ task context none + Context unset. + + $ task list + ID Age Project Description Urg + 1 2d Sport Run 5 miles 1.42 + 2 1d Home Clean the dishes 1.14 + +Context can be defined using the 'define' subcommand, specifying both the name +of the new context, and it's assigned filter. + + $ task context define home + Are you sure you want to add 'context.home' with a value of 'project:Home'? (yes/no) yes + Context 'home' successfully defined. + +To remove the definition, use the 'delete' subcommand. + + $ task context delete home + Are you sure you want to remove 'context.home'? (yes/no) yes + Context 'home' successfully undefined. + +To check what is the currently active context, use the 'show' subcommand. + + $ task context show + Context 'home' with filter 'project:Home' is currently applied. + +Contexts can store arbitrarily complex filters. + + $ task context define family project:Family or +paul or +nancy + Are you sure you want to add 'context.home' with a value of 'project:Family or +paul or +nancy'? (yes/no) yes + Context 'family' successfully defined. + +Contexts are permanent, and the currently set context name is stored in the +"context" configuration variable. The context definition is stored in the +"context." configuration variable. + .SH COMMAND ABBREVIATION All taskwarrior commands may be abbreviated as long as a unique prefix is used, for example: diff --git a/doc/man/taskrc.5.in b/doc/man/taskrc.5.in index f9a76a931..b0fa4cf79 100644 --- a/doc/man/taskrc.5.in +++ b/doc/man/taskrc.5.in @@ -1351,6 +1351,26 @@ of a task. .B uda.estimate.values=trivial,small,medium,large,huge .RE +.SS CONTEXT +Context setting is a mechanism which allows the user to set a permanent filter, +thus avoiding the need to specify one filter repeatedly. More details on usage +can be found in the task(1) manpage. + +The current context is stored in the taskrc file, along with definitions for +all user provided contexts. + +.TP +.B context= +.RS +Stores the value of the currently active context. +.RE + +.TP +.B context.= +.RS +Stores the definition of the context with the name . +.RE + .SS SYNC These configuration settings are used to connect and sync tasks with the task