- Set up structure for AUTHORS file.
- Set up NEWS file, with pleas for feedback. - Added welcome message to README. - Completed a chunk of the TUTORIAL. - Added error handling for "task export" when a file name is not specified.
This commit is contained in:
Paul Beckingham
217
TUTORIAL
217
TUTORIAL
@@ -1,4 +1,4 @@
|
||||
Task program tutorial, for version 0.9.0
|
||||
Task program tutorial, for version 1.0.0
|
||||
----------------------------------------
|
||||
|
||||
This guide shows how to quickly set up the task program, and become proficient
|
||||
@@ -12,10 +12,10 @@ Build the task program according to the directions in the INSTALL file. This
|
||||
transcript illustrates a typical installation:
|
||||
|
||||
% ls
|
||||
task-0.9.7.tar.gz
|
||||
% gunzip task-0.9.7.tar.gz
|
||||
% tar xf task-0.9.7.tar
|
||||
% cd task-0.9.7
|
||||
task-1.0.0.tar.gz
|
||||
% gunzip task-1.0.0.tar.gz
|
||||
% tar xf task-1.0.0.tar
|
||||
% cd task-1.0.0
|
||||
% ./configure
|
||||
...
|
||||
% make
|
||||
@@ -23,21 +23,24 @@ transcript illustrates a typical installation:
|
||||
% make install
|
||||
|
||||
You need to make sure that the installed task program is in your PATH
|
||||
environment variable. The next step is to create a configuration file for the
|
||||
task program. This file resides in your home directory, is called .taskrc, and
|
||||
contains various configuration settings. Use the provided SAMPLE_taskrc file
|
||||
as a starting point for your own:
|
||||
environment variable.
|
||||
|
||||
% cp SAMPLE_taskrc ~/.taskrc
|
||||
% mkdir ~/.task
|
||||
Task reads a configuration file - called .taskrc in your home directory - and
|
||||
stores pending and completed tasks in in a directory specified in the
|
||||
configuration file.
|
||||
|
||||
Your .taskrc files contains an entry that points to the .task directory
|
||||
belonging to user bob. Change this entry to point to your own home directory,
|
||||
and the .task directory you just created. Your task program is now ready to
|
||||
use. Verify that task is properly installed with:
|
||||
The simplest way to get a configuration file and task directory is to run task.
|
||||
On startup, task will check to see if it can find the configuration file and
|
||||
task directory, and if not found, will ask you if it may create both.
|
||||
|
||||
% task version
|
||||
[show sample output]
|
||||
|
||||
A configuration file could not be found in /Users/paul/.taskrc
|
||||
|
||||
Would you like a sample .taskrc created, so task can proceed? (y/n) y
|
||||
Done.
|
||||
|
||||
[then task will show version information]
|
||||
|
||||
|
||||
Simple Usage
|
||||
@@ -70,14 +73,15 @@ task 2:
|
||||
Permanently delete task? (y/n) y
|
||||
|
||||
Task wants you to confirm deletions. To remove the confirmation, edit your
|
||||
.taskrc file and remove the line:
|
||||
.taskrc file and change the line:
|
||||
|
||||
confirmation=yes
|
||||
|
||||
or change the yes to no.
|
||||
to have a value of "no".
|
||||
|
||||
While projects and priorities are not necessary, they can be very useful when
|
||||
the list of tasks grows large. Let's assign a project to these tasks:
|
||||
While the use of projects and priorities are not essential to benefitting from
|
||||
task, they can be very useful when the list of tasks grows large. Let's assign
|
||||
a project to these tasks:
|
||||
|
||||
% task 1 project:Wedding
|
||||
% task 3 project:Wedding
|
||||
@@ -92,9 +96,10 @@ the list of tasks grows large. Let's assign a project to these tasks:
|
||||
Notice that the id numbers have changed. When tasks get deleted, or have their
|
||||
attributes changed (project, for example), the ids are prone to change. But the
|
||||
id numbers will remain valid until the next 'ls' command is run. You should
|
||||
only use the ids from the most recent 'ls' command.
|
||||
|
||||
Now that projects are assigned, we can look at just the Wedding project tasks:
|
||||
only use the ids from the most recent 'ls' command. The ids change, because
|
||||
task is always trying to use small numbers so that it is easy for you to enter
|
||||
them correctly. Now that projects are assigned, we can look at just the Wedding
|
||||
project tasks:
|
||||
|
||||
% task ls project:Wedding
|
||||
|
||||
@@ -136,37 +141,44 @@ Priority can be abbreviated to pri, but not pr, because it is ambiguous. Now
|
||||
that tasks have been prioritized, you can see that the tasks are being sorted
|
||||
by priority, with the highest priority tasks at the top.
|
||||
|
||||
These attributes can all be provided when the task is added, instead of
|
||||
applying them afterwards, as shown. The following command shows how to set all
|
||||
the attributes at once:
|
||||
|
||||
% task add project:Wedding priority:H Book plane ticket
|
||||
|
||||
The 'ls' command provides the least information for each task. The 'list'
|
||||
command provides more:
|
||||
|
||||
% task list
|
||||
|
||||
ID Project Pri Due Active Age Description
|
||||
ID Project Pri Due Active Age Description
|
||||
3 Family H 4 mins Send John a birthday card
|
||||
1 Wedding H 5 mins Book plane ticket
|
||||
2 Wedding M 5 mins Reserve a rental car
|
||||
|
||||
Notice that task can have a due date, and can be active. The task lists are
|
||||
Notice that a task can have a due date, and can be active. The task lists are
|
||||
sorted by due date, then priority. Let's add due dates:
|
||||
|
||||
% task 3 due:3/25/2008
|
||||
% task 1 due:5/31/2008
|
||||
% task 3 due:6/25/2008
|
||||
% task 1 due:7/31/2008
|
||||
% task list
|
||||
|
||||
ID Project Pri Due Active Age Description
|
||||
3 Family H 3/25/2008 6 mins Send John a birthday card
|
||||
1 Wedding H 5/31/2008 7 mins Book plane ticket
|
||||
3 Family H 6/25/2008 6 mins Send John a birthday card
|
||||
1 Wedding H 7/31/2008 7 mins Book plane ticket
|
||||
2 Wedding M 7 mins Reserve a rental car
|
||||
|
||||
If today's date is 3/23/2008, then task 3 is due in 2 days. It will be colored
|
||||
If today's date is 6/23/2008, then task 3 is due in 2 days. It will be colored
|
||||
yellow if your terminal supports color. To change this color, edit your
|
||||
.taskrc file, and change the line to one of these alternatives:
|
||||
|
||||
color.due=<foreground color> on <background color>
|
||||
color.due=<foreground color>
|
||||
color.due=on <background color>
|
||||
color.due=red
|
||||
color.due=on_blue
|
||||
color.due=red on_blue
|
||||
color.due=bold_red on_blue
|
||||
|
||||
Where color is one of:
|
||||
Where color is one of the following:
|
||||
|
||||
black
|
||||
blue
|
||||
@@ -178,7 +190,39 @@ Where color is one of:
|
||||
white
|
||||
|
||||
All colors are specified in this way. Take a look in .taskrc for all the other
|
||||
colors you control.
|
||||
color rules that you control.
|
||||
|
||||
Tagging tasks is a good way to group them, aside from specifying a project. To
|
||||
add a tag to a task:
|
||||
|
||||
% task <id> +tag
|
||||
|
||||
The plus sign indicates that this is a tag. Any number of tags may be applied
|
||||
to a task, and then used for searching. Tags are just single words that are
|
||||
labels.
|
||||
|
||||
% task list
|
||||
|
||||
ID Project Pri Due Active Age Description
|
||||
3 Family H 6/25/2008 8 mins Send John a birthday card
|
||||
1 Wedding H 7/31/2008 9 mins Book plane ticket
|
||||
2 Wedding M 9 mins Reserve a rental car
|
||||
|
||||
% task 1 +phone
|
||||
% task 2 +phone
|
||||
% task 3 +shopping
|
||||
% task 3 +john
|
||||
|
||||
% task list +phone
|
||||
|
||||
ID Project Pri Due Active Age Description
|
||||
1 Wedding H 7/31/2008 9 mins Book plane ticket
|
||||
2 Wedding M 9 mins Reserve a rental car
|
||||
|
||||
To remove a tag from a task, use the minus sign:
|
||||
|
||||
% task 3 -john
|
||||
|
||||
|
||||
|
||||
Advanced Use
|
||||
@@ -190,26 +234,113 @@ Commands:
|
||||
- task long
|
||||
- task ls
|
||||
- task done
|
||||
- task completed
|
||||
- task delete
|
||||
- task start
|
||||
- task summary
|
||||
- task history
|
||||
- task next
|
||||
- task <modify>
|
||||
- task /from/to/
|
||||
- task projects
|
||||
- task tags
|
||||
- task info
|
||||
- task active
|
||||
- task overdue
|
||||
- task calendar
|
||||
- task stats
|
||||
- task usage
|
||||
- task export
|
||||
- task version
|
||||
|
||||
|
||||
|
||||
% task <id> ...
|
||||
|
||||
When a task id is specified, everything applies to just that task. Suppose
|
||||
we needed to correct a task:
|
||||
|
||||
% task ls
|
||||
|
||||
ID Project Pri Description
|
||||
12 Errand L Remember to deposit chekc
|
||||
...
|
||||
|
||||
% task 12 Remember to deposit bonus check
|
||||
% task ls
|
||||
|
||||
ID Project Pri Description
|
||||
12 Errand L Remember to deposit bonus check
|
||||
...
|
||||
|
||||
|
||||
|
||||
% task /from/to/
|
||||
|
||||
If a task has been entered with a typo, it can be easily corrected by this
|
||||
command. For example:
|
||||
|
||||
% task ls
|
||||
|
||||
ID Project Pri Description
|
||||
12 Errand L Remember to deposit chekc
|
||||
...
|
||||
|
||||
% task 12 /chekc/check/
|
||||
% task ls
|
||||
|
||||
ID Project Pri Description
|
||||
12 Errand L Remember to deposit check
|
||||
...
|
||||
|
||||
This command makes single corrections to a task description.
|
||||
|
||||
|
||||
|
||||
% task tags
|
||||
|
||||
This command will generate a list of all the tags that are currently in use
|
||||
by task.
|
||||
|
||||
|
||||
|
||||
% task info <id>
|
||||
|
||||
This command gives detailed information about a single task. It will tell
|
||||
you when the task was entered, when started, its status, tags, and more.
|
||||
|
||||
|
||||
|
||||
% task stats
|
||||
|
||||
This command generates a list of statistics about your task usage, such as
|
||||
the average time it takes to complete a task, how often new tasks are added,
|
||||
and more.
|
||||
|
||||
|
||||
|
||||
% task completed
|
||||
|
||||
This generates a list of all tasks that have been completed, sorted by their
|
||||
completion date.
|
||||
|
||||
|
||||
|
||||
% task export <file name>
|
||||
|
||||
This instructs task to write out a CSV format dump of all tasks, both pending
|
||||
and completed, to the file specified. This is how you might view tasks in a
|
||||
spreadsheet.
|
||||
|
||||
|
||||
|
||||
% task version
|
||||
|
||||
This can be used to show the version number of task, and to display all the
|
||||
current configuration settings, as read from the .taskrc file.
|
||||
|
||||
|
||||
Interacting with the Shell
|
||||
--------------------------
|
||||
- Escaping shell metacharacters
|
||||
|
||||
|
||||
|
||||
Configuring Task
|
||||
----------------
|
||||
|
||||
-nag
|
||||
-confirmation
|
||||
|
||||
|
||||
Reference in New Issue
Block a user