From d6e8a349844436db976214ead2c0f9f3936e7ff1 Mon Sep 17 00:00:00 2001 From: Paul Beckingham Date: Sun, 2 Oct 2011 14:13:42 -0400 Subject: [PATCH] Documentation - Updated task-tutorial.5.in with new syntax. - Removed examples using implicit 'info' command. - Updated examples for new syntax. - Updated copyright. - Note that the tutorial is still firmly a 1.9.3 tutorial, with no new examples other than syntax changes. --- doc/man/task-tutorial.5.in | 329 +++++++------------------------------ 1 file changed, 59 insertions(+), 270 deletions(-) diff --git a/doc/man/task-tutorial.5.in b/doc/man/task-tutorial.5.in index 2ab56f21f..736f30933 100644 --- a/doc/man/task-tutorial.5.in +++ b/doc/man/task-tutorial.5.in @@ -3,8 +3,6 @@ .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. @@ -163,7 +161,7 @@ by the 'g' at the end. You could omit the 'g', and it would only make the first substitution. .RS -$ task 7 /teh/the/g +$ task 7 modify /teh/the/g .br Modified 1 task. .br @@ -199,7 +197,7 @@ Let's assign that last task to the 'home' project. Note that a task may only belong to one project. .RS -$ task 7 project:home +$ task 7 modify project:home .br The scope of project 'home' has changed. Project 'home' is 0% complete (1 of 1 tasks remaining). .br @@ -211,11 +209,11 @@ specify a range of tasks? Taskwarrior will want to confirm bulk changes like this, but we'll accept all changes here. .RS -$ task 1-6 project:party +$ task 1-6 modify project:party .br .br -Task 1 "Select a free weekend in November" +Task 1 modify "Select a free weekend in November" .br - project will be set to 'party'. .br @@ -260,7 +258,7 @@ party 6 6 0 0 0 .br 2 projects (7 tasks) .br -$ task list project:home +$ task project:home list .br .br @@ -274,7 +272,7 @@ ID Project Pri Due Active Age Description .br 1 task .br -$ task li pro:par +$ task pro:par li .br .br @@ -304,11 +302,11 @@ Priorities are another way to organize tasks. You can use priority values of high, medium and low, and taskwarrior knows these as H, M or L. .RS -$ task 1-3,5 priority:H +$ task 1-3,5 modify priority:H .br .br -Task 1 "Select a free weekend in November" +Task 1 modify "Select a free weekend in November" .br - priority will be set to 'H'. .br @@ -350,7 +348,7 @@ ID Project Pri Due Active Age Description You can remove priorities by specifying a blank value. .RS -$ task 3 pri: +$ task 3 modify pri: .br Modified 1 task. .RE @@ -361,11 +359,11 @@ just single words associated with the task. I can go to the print shop at the mall, and do all the invitation tasks, so let's tag them all. .RS -$ task 3,5,6 +mall +$ task 3,5,6 modfy +mall .br .br -Task 3 "Mail invitations" +Task 3 modify "Mail invitations" .br - tags will be set to 'mall'. .br @@ -409,7 +407,7 @@ ID Project Pri Added Started Due Recur Countdown Age Deps Tags Descript and I can use tags as a filter to any report too. .RS -$ task list +mall +$ task +mall list .br .br @@ -432,7 +430,7 @@ I made a mistake - I can't mail out the invitations at the mall, so let's remove that tag. .RS -$ task 3 -mall +$ task 3 modify -mall .br Modified 1 task. .RE @@ -443,7 +441,7 @@ and a new description. This is also considered a bulk change, and so requires confirmation. .RS -$ task 7 Pay rent at the end of the month +$ task 7 modify Pay rent at the end of the month .br .br @@ -467,7 +465,7 @@ $ task 8 prepend Select some .br $ task 8 append for after dinner .br -$ task list dinner +$ task dinner list .br .br @@ -597,7 +595,7 @@ Modified task reverted. .SH INFO During that undo operation, taskwarrior displayed metadata that is associated -with the task. You can display this with the info command, and its shortcut. +with the task. You can display this with the info command. .RS $ task 1 info @@ -623,30 +621,6 @@ UUID 3a6881bb-628b-4f90-93d7-4da563b83d54 Entered 10/16/2010 (44 mins) .br -.br -$ task 1 -.br - -.br -Name Value -.br ------------ ------------------------------------ -.br -ID 1 -.br -Description Select a free weekend in November -.br -Status Pending -.br -Project party -.br -Priority H -.br -UUID 3a6881bb-628b-4f90-93d7-4da563b83d54 -.br -Entered 10/16/2010 (44 mins) -.RE - There are also statistics that taskwarrior gathers, which I can display. .RS @@ -745,7 +719,7 @@ ID Project Pri Due Active Age Description You can choose to display annotations in different ways. .RS -$ task list rc.annotations:full +$ task rc.annotations:full list .br .br @@ -765,7 +739,7 @@ ID Project Pri Due Active Age Description .br Configuration override annotations:full .br -$ task list rc.annotations:sparse +$ task rc.annotations:sparse list .br .br @@ -783,7 +757,7 @@ ID Project Pri Due Active Age Description .br Configuration override annotations:sparse .br -$ task list rc.annotations:none +$ task rc.annotations:none list .br .br @@ -996,7 +970,7 @@ $ task add New task .br Created task 9. .br -$ task list New task +$ task New task list .br .br @@ -1185,7 +1159,7 @@ Here is an example of an explicit override to the color rules where a specific task is given a red background. .RS -$ task 1 bg:on_red +$ task 1 modify bg:on_red .br modified 1 task. .br @@ -1219,7 +1193,7 @@ ID Project Pri Due Active Age Description .br 8 tasks .br -$ task 1 bg: +$ task 1 modify bg: .br Modified 1 task. .RE @@ -1496,7 +1470,7 @@ $ task 2 start .br Started 2 'Select and book a venue'. .br -$ task list venue +$ task venue list .br .br @@ -1516,7 +1490,7 @@ $ task 2 stop .br Stopped 2 'Select and book a venue'. .br -$ task list venue +$ task venue list .br .br @@ -1540,31 +1514,31 @@ Due dates can be specified as dates, durations into the future or past, mnemonic, ordinal or day of week. .RS -$ task 1 due:7/31/2010 +$ task 1 modify due:7/31/2010 .br Modified 1 task. .br -$ task 1 due:2wks +$ task 1 modify due:2wks .br Modified 1 task. .br -$ task 1 due:-2wks +$ task 1 modify due:-2wks .br Modified 1 task. .br -$ task 1 due:eom +$ task 1 modify due:eom .br Modified 1 task. .br -$ task 2 due:8th +$ task 2 modify due:8th .br Modified 1 task. .br -$ task 2 due:sunday +$ task 2 modify due:sunday .br Modified 1 task. .br -$ task 5 due:eow +$ task 5 modify due:eow .br Modified 1 task. .RE @@ -1843,13 +1817,13 @@ every month. Recurring tasks allow us to set up a single task that keeps coming back, just as you'd expect. .RS -$ task 7 due:eom recur:monthly +$ task 7 modify due:eom recur:monthly .br Task 7 is now a recurring task. .br Modified 1 task. .br -$ task 7 +$ task 7 info .br .br @@ -1880,7 +1854,7 @@ You can also limit the extent of the recurrence. Let's make sure the task doesn't recur after the lease ends. .RS -$ task 7 until:eoy +$ task 7 modify until:eoy .br Modified 1 task. .RE @@ -2075,7 +2049,7 @@ individual tasks. The 'nocolor' special tag causes the color rules to be bypassed. .RS -$ task 6 +nocolor +$ task 6 modify +nocolor .br Modified 1 task. .RE @@ -2104,7 +2078,7 @@ There are others - the 'nonag' special tag prevents the generation of nag messages when you work on low priority tasks when there are more important ones. .RS -$ task 6 -nocolor +$ task 6 modify -nocolor .br Modified 1 task. .RE @@ -2127,7 +2101,7 @@ and visible using the 'waiting' report. When the wait date comes, the task will just reappear in the list. .RS -$ task 10 wait:12/1/2010 +$ task 10 modify wait:12/1/2010 .br Modified 1 task. .br @@ -2188,7 +2162,7 @@ $ task add Do something in a few seconds .br Created task 11. .br -$ task 11 wait:5s +$ task 11 modify wait:5s .br Modified 1 task. .br @@ -2280,7 +2254,7 @@ Taskwarrior supports dependencies. Let's take a look at the party planning tasks, and assign dependencies. .RS -$ task list pro:party +$ task pro:party list .br .br @@ -2314,7 +2288,7 @@ ID Project Pri Due Active Age Description Let's see. I can't mail invitations until they are printed. .RS -$ task 3 depends:6 +$ task 3 modify depends:6 .br Modified 1 task. .RE @@ -2322,7 +2296,7 @@ Modified 1 task. I can't print them until I design them. .RS -$ task 6 dep:5 +$ task 6 modify dep:5 .br Modified 1 task. .RE @@ -2330,7 +2304,7 @@ Modified 1 task. I need to select a weekend before a location. .RS -$ task 2 dep:1 +$ task 2 modify dep:1 .br Modified 1 task. .RE @@ -2338,7 +2312,7 @@ Modified 1 task. Design depends on location and weekend. .RS -$ task 5 dep:1,2 +$ task 5 modify dep:1,2 .br Modified 1 task. .RE @@ -2346,7 +2320,7 @@ Modified 1 task. And the caterer needs to know where. .RS -$ task 4 dep:1 +$ task 4 modify dep:1 .br Modified 1 task. .RE @@ -2354,7 +2328,7 @@ Modified 1 task. Let's take a look. All my tasks are blocked except task 1. That makes sense. .RS -$ task long pro:party +$ task pro:party long .br .br @@ -2388,7 +2362,7 @@ ID Project Pri Added Started Due Recur Countdown Age Deps Tags Des Hmm, that double dependency isn't right. .RS -$ task 5 dep:-1 +$ task 5 modify dep:-1 .br Modified 1 task. .RE @@ -3101,7 +3075,7 @@ Now again, but with the text 'invit', which acts as a filter on the description field. .RS -$ task list invit +$ task invit list .br .br @@ -3125,7 +3099,7 @@ filtering on descriptions that contain the word fragment. Here we are using the 'contains' modifier, but there are many others. .RS -$ task list description.contains:invit +$ task description.contains:invit list .br .br @@ -3148,7 +3122,7 @@ All tasks containing the whole word 'the'. See how annotations are also searched? .RS -$ task list desc.word:the +$ task desc.word:the list .br .br @@ -3170,7 +3144,7 @@ ID Project Pri Due Active Age Description Here is a list of all tasks that do not contain the whole word 'invitations'. .RS -$ task list desc.noword:invitations +$ task desc.noword:invitations list .br .br @@ -3199,18 +3173,18 @@ there are several synonyms for modifiers, so that the filter can be written so that it reads naturally. .RS -$ task list pro:party +$ task pro:party list .br -$ task list pro.is:party +$ task pro.is:party list .br -$ task list pro.not:party +$ task pro.not:party list .RE Here the 'over' modifier is filtering on priorities that sort higher than 'Low', and also filtering on the 'party' project. There are two terms in this filter. .RS -$ task list pro:party pri.over:L +$ task pro:party pri.over:L list .br .br @@ -3234,7 +3208,7 @@ the first page of tasks. I don't have a page full of tasks here, but you get the idea. .RS -$ task list pro:party limit:2 +$ task pro:party limit:2 list .br .br @@ -3252,7 +3226,7 @@ ID Project Pri Due Active Age Description .br 2 tasks, 2 shown .br -$ task list limit:page +$ task limit:page list .br .br @@ -3275,200 +3249,17 @@ Now you can see how some of the built-in reports work. The 'list' report is just all tasks, filtered so that only the pending tasks are shown. .RS -$ task all status:pending +$ task status:pending all ... .RE The 'waiting' report is similarly defined. .RS -$ task all status:waiting +$ task status:waiting all ... .RE -.SH IMPORT/EXPORT -You can export your tasks. Here you see all tasks being exported in CSV format. - -.RS -$ task export.csv -.br -\'uuid','status','tags','entry','start','due','recur','end','project','priority','fg','bg','description' -.br -\'3a6881bb-628b-4f90-93d7-4da563b83d54','pending','',1287237300,,1288497600,,,'party','H',,,'Select a free weekend in November' -.br -\'4a1de9aa-9b00-41ec-8d00-e0d0131e0e0d','pending','',1287237365,,,,,'party',,,,'Mail invitations' -.br -\'2a65e922-ff18-4db1-b867-dbe745b9626a','pending','',1287237372,,,,,'party',,,,'Select a caterer' -.br - ... -.RE - -Let's just export one task in CSV format... - -.RS -$ task export.csv venue -.br -\'uuid','status','tags','entry','start','due','recur','end','project','priority','fg','bg','description' -.br -\'773c2b02-919e-4527-95f0-814c19dd198a','completed','',1287237350,,1287288000,,1287250285,'party','H',,,'Select and book a venue' -.RE - -Or in VCalendar format... - -.RS -$ task export.vcalendar venue -.br -BEGIN:VCALENDAR -.br -VERSION:2.0 -.br -PRODID:-//GBF//task 1.9.4.beta1//EN -.br -BEGIN:VTODO -.br -UID:773c2b02-919e-4527-95f0-814c19dd198a -.br -DTSTAMP:20101016T135550Z -.br -DUE:20101017T040000Z -.br -COMPLETED:20101016T173125Z -.br -SUMMARY:Select and book a venue -.br -CLASS:PRIVATE -.br -PRIORITY:1 -.br -STATUS:COMPLETED -.br -COMMENT:Started task -.br -COMMENT:Stopped task -.br -END:VTODO -.br -END:VCALENDAR -.RE - -Or YAML. - -.RS -$ task export.yaml venue -.br -%YAML 1.1 -.br ---- -.br - task: -.br - depends: 3a6881bb-628b-4f90-93d7-4da563b83d54 -.br - description: Select and book a venue -.br - due: 1287288000 -.br - end: 1287250285 -.br - entry: 1287237350 -.br - priority: H -.br - project: party -.br - status: completed -.br - uuid: 773c2b02-919e-4527-95f0-814c19dd198a -.br - annotation: -.br - entry: 1287242411 -.br - description: Started task -.br - annotation: -.br - entry: 1287242506 -.br - description: Stopped task -.br - ... -.RE - -I can also import. Here I am importing simple lines of text. Taskwarrior -recognizes the format by looking inside the file and making a guess, then -confirms. - -.RS -$ cat file.text -.br -Remember to read the task man page -.br -$ task import file.text -.br -This looks like a text file with one task per line. Okay to proceed? (y/n) y -.br -Imported 1 tasks successfully, with 0 errors. -.RE - -Here is a YAML example. Taskwarrior can read several formats, including old -versions of its data files. Using YAML, you can round-trip the data without -loss, which means you can export and import without any missing information. -This also means that 'export.yaml' is good for making a backup copy of your -tasks. - -.RS -$ cat file.yaml -.br -%YAML 1.1 -.br ---- -.br - task: -.br - description: Visit http://taskwarrior.org -.br - due: 1281844800 -.br - entry: 1281289630 -.br - priority: H -.br - project: work -.br - status: pending -.br - uuid: 23afada0-a446-8d5a-c213-30d99d52c4b0 -.br - ... -.br -$ task import file.yaml -.br -This looks like a YAML file. Okay to proceed? (y/n) y -.br -Imported 1 tasks successfully. -.RE - -Here are the imported tasks. - -.RS -$ task new limit:2 -.br - -.br -ID Project Pri Due Active Age Description -.br --- ------- --- ---------- ------ ----- ------------------------------------ -.br -11 work H 8/15/2010 9 wks Visit http://taskwarrior.org -.br -10 1 min Remember to read the task man page -.br - -.br -9 tasks, 2 shown -.RE - .SH HELP You'll find a quick reference page built in, with the 'help' command, or perhaps you'll want to take a look at the several man pages installed. @@ -3479,9 +3270,7 @@ $ task help .RE .SH "CREDITS & COPYRIGHTS" -task was written by P. Beckingham . -.br -Copyright (C) 2006 \- 2011 P. Beckingham +Copyright (C) 2006 \- 2011 P. Beckingham, F. Hernandez. This man page was originally written by Federico Hernandez, and has been modified and supplemented by Paul Beckingham.