diff --git a/ChangeLog b/ChangeLog index b562b2a30..606cbf7ac 100644 --- a/ChangeLog +++ b/ChangeLog @@ -7,6 +7,13 @@ represents a feature release, and the Z represents a patch. ------ current release --------------------------- +1.4.1 (7/?/2008) + + Bug: Descriptions can not be altered with "task 123 New description" + + Tweak: For "task calendar" month names are now centered over the month + + Removed TUTORIAL file contents in favor of online version + +------ old releases ------------------------------ + 1.4.0 (7/10/2008) + New recurring tasks feature + "task undelete" can now undelete erroneously deleted tasks, provided no @@ -25,8 +32,6 @@ represents a feature release, and the Z represents a patch. + Bug: Adding a blank priority resulted in an assigned garbage value + Bug: Fixed parsing of date "07/08/2008" when using dateformat "m/d/Y" ------- old releases ------------------------------ - 1.3.1 (6/21/2008) + New configuration variable, "defaultwidth" that determines the width of tables when ncurses support is not available diff --git a/TUTORIAL b/TUTORIAL index 5da078140..7f635f4c2 100644 --- a/TUTORIAL +++ b/TUTORIAL @@ -1,835 +1,6 @@ -Task program tutorial, for version 1.4.0 ----------------------------------------- - - -*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-* - -This TUTORIAL file is deprecated, and does not contain all the new features in -release 1.4.0. It will not be included in future releases of task, and will be -superceded by a richer and more extensive online version that can be found at: +This TUTORIAL file has been deprecated. It is superceded by a richer and more +extensive online version that can be found at: http://www.beckingham.net/task.html -*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-* - - - -This guide shows how to quickly set up the task program, and become proficient -with it. - - Contents: - Quick Setup - Simple Usage - Advanced Usage - Interacting with the Shell - Configuring Task - Colors - - - -Quick Setup ------------ - -Build the task program according to the directions in the INSTALL file. This -transcript illustrates a typical installation: - - % ls - task-1.4.0.tar.gz - % gunzip task-1.4.0.tar.gz - % tar xf task-1.4.0.tar - % cd task-1.4.0 - % ./configure - ... - % make - ... - % make install # (may require sudo, depending on --prefix) - -You need to make sure that the installed task program is in your PATH -environment variable. - -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. - -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 whether it may create both. - - % task version - - 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 ------------- - -Let us begin by adding some tasks: - - % task add Book plane ticket - % task add Rent a tux - % task add Reserve a rental car - % task add Reserve a hotel room - -That's it. You'll notice immediately that task has a very minimalist -interface. Let us take a look at those tasks: - - % task ls - - ID Project Pri Description - 1 Book plane ticket - 2 Rent a tux - 3 Reserve a rental car - 4 Send John a birthday card - -The 'ls' command provides the most minimal list of tasks. Each task has been -given an id number, and you can see that there are no projects or priorities -assigned. Wait a minute - I own a tux, I don't need to rent one. Let us delete -task 2: - - % task 2 delete - Permanently delete task? (y/n) y - -Task wants you to confirm deletions. To remove the confirmation, edit your -.taskrc file and change the line: - - confirmation=yes - -to have a value of "no". - -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 - % task 4 project:Family - % task ls - - ID Project Pri Description - 3 Family Send John a birthday card - 2 Wedding Reserve a rental car - 1 Wedding Book plane ticket - -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. The ids change, because -task is always trying to use small numbers so that it is easy for you to enter -them correctly. - -Subprojects are supported. If you have a project "Wedding", you can specify -that a task is a subproject "Transport" of "Wedding" by assigning the project -"Wedding.Transport". Let's do this: - - % task 2 project:Wedding.Transport - % task ls - - ID Project Pri Description - 3 Family Send John a birthday card - 2 Wedding.Transport Reserve a rental car - 1 Wedding Book plane ticket - -Task matches the leftmost part of the project when searching, so projects -may be abbreviated: - - % task ls project:Wedding.Tra - - ID Project Pri Description - 2 Wedding.Transport Reserve a rental car - -This way of matching projects can be used to see all tasks under the -"Wedding" project and all subprojects: - - % task ls project:Wedding - - ID Project Pri Description - 2 Wedding.Transport Reserve a rental car - 1 Wedding Book plane ticket - -Let's reassign 2 back to the "Wedding" project: - - % task 2 project:Wedding - -Now that projects are assigned, we can look at just the Wedding project tasks: - - % task ls project:Wedding - - ID Project Pri Description - 1 Wedding Book plane ticket - 2 Wedding Reserve a rental car - -Any command arguments after the 'ls' are used for filtering the output. We -could also have requested: - - % task ls ticket plane - - ID Project Pri Description - 1 Wedding Book plane ticket - -Now let's prioritize. Priorities can be H, M or L (High, Medium, Low). - - % task ls - - ID Project Pri Description - 3 Family Send John a birthday card - 2 Wedding Reserve a rental car - 1 Wedding Book plane ticket - - % task 1 priority:H - % task 2 prior:M - % task 3 pr:H - Ambiguous attribute 'pr' - could be either of project, priority - % task 3 pri:H - % task ls - - ID Project Pri Description - 3 Family H Send John a birthday card - 1 Wedding H Book plane ticket - 2 Wedding M Reserve a rental car - -Notice that task supports the abbreviation of words such as priority, project. -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 - 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 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:6/25/2008 - % task 1 due:7/31/2008 - % task list - - ID Project Pri Due Active Age Description - 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 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=red - color.due=on_blue - color.due=red on_blue - color.due=bold_red on_blue - -Where color is one of the following: - - black - blue - red - green - cyan - magenta - yellow - white - -All colors are specified in this way. Take a look in .taskrc for all the other -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 +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 ------------- - -Here are the other commands, in some detail. Note that the command: - - % task - -with no arguments will generate a help message that lists all these commands. - - -% task projects ---------------- - - This report generates a list of all the different projects that you are using - along with a count of the pending tasks for each project. For example: - - % task projects - - Project Tasks - Errands 1 - Birthdays 3 - Car 2 - - - -% task summary --------------- - - This report lists all the projects and a summary of their task status. - - % task summary - - Project Remaining Avg age Complete 0% 100% - Errands 1 3 days 50% XXXXXXXXXXXXXXXX - Birthdays 3 7 mths 0% - Car 2 2 wks 25% XXXXXXXXX - - This shows the project, the remaining tasks, the average age of each task, - the percentage completed (remaining vs total) and a bar indicating that - percentage. - - - -% task delete ------------------- - - There are two ways of getting rid of tasks - mark them as done, or delete - them. - - - -% task undelete --------------------- - - If a task was inadvertently deleted, it may be undeleted, provided that no - reports have been run since the deletion. Ideally, the undelete command is - run immediately after the erroneous delete command. - - If a report is run (such as "task list"), then task performs a garbage - collection that removes deleted tasks, and the task cannot be undeleted. - - - -% task done ----------------- - - This is how a task is marked as done. - - - -% task list ... ---------------- - - The list report will show the active status, and age of the task in addition - to the columns that "task ls" shows. It is just a more detailed list. - - - -% task long ... ---------------- - - The long report will show the entry date and start date of a task, in - addition to the columns that the "task list" shows. - - - -% task start ------------------ - - This marks a task as started (and therefore active), which is shown in the - "list" report: - - % task list - - ID Project Pri Due Active Age Description - 12 Errand L Remember to deposit check - ... - - % task start 12 - % task list - - ID Project Pri Due Active Age Description - 12 Errand L * 3 days Remember to deposit check - ... - - - -% task active -------------- - - Shows all active tasks, that is, the tasks for which the "task start ..." - command was run, as shown above. - - - -% task overdue --------------- - - Simply lists all the task that have a due date that is past, in "list" - format. - - - -% task oldest -------------- - - Lists the oldest tasks. Shows 10 tasks by default, but can be set via the - "oldest" configuration variable. - - - -% task newest -------------- - - Lists the newest tasks. Shows 10 tasks by default, but can be set via the - "newest" configuration variable. - - - -% task history --------------- - - This report shows you an overview of how many tasks were added, completed and - deleted, by month. It looks like this: - - % task history - - Year Month Added Completed Deleted Net - 2008 March 21 16 0 5 - April 13 11 1 1 - May 8 14 3 -9 - - Average 14 13 1 -1 - - This shows that for the three months that task has been used, March and April - saw the total number of tasks increase, but in May the number decreased as - more task were completed than added. - - - -% task ghistory --------------- - - This report shows you an overview of how many tasks were added, completed and - deleted, by month, as does "task history", but as a bar chart. It looks like this: - - % task history - - Year Month Added/Completed/Deleted - 2008 March +++++++++++++++++++++XXXXXXXXXXXXXXXX - April +++++++++++++XXXXXXXXXXX- - May ++++++++XXXXXXXXXXXXXX--- - - With color enabled, the bars contain the size of each bar. - - - -% task calendar ---------------- - - This report shows a calendar of the current month, with any task due or - overdue dates marked on it. Color is used to mark these dates. - - % task calendar - - May 2008 - - Su Mo Tu We Th Fr Sa - 1 2 3 - 4 5 6 7 8 9 10 - 11 12 13 14 15 16 17 - 18 19 20 21 22 23 24 - 25 26 27 28 29 30 31 - - - -% task next ------------ - - This report shows you the tasks you should probable work on next. Task will - scan all the tasks and will pick two task from each project to report. Those - two tasks will be chosen in order of overdue, due soon, High, Medium or Low - priority. Essentially task chooses the two most important task for each - project and displays them ordered in the usual way. - - If you wish to show a different number of tasks per project, modify the entry - in .taskrc: - - next=2 - - To be your preferred number. - - - -% task ... ---------------- - - 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 ----------------- - - 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 -------------------------- - - 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 colors -------------- - - This command displays all the colors that task supports. - - - -% task usage ------------- - - If logging has been enabled by the "command.logging=on" directive in the - .taskrc file, then task will record every command that is run. When this - command is run, task will display a count of how many times each command was - used. - - This command is for the purpose of seeing whether command are actually used. - - - -% 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. - - - -% task fg:... bg:... -------------------------- - - Not strictly a command, the setting of the fg and bg (foreground and - background) attributes determines the colors used to represent the task. - Valid foreground colors are: - - bold underline bold_underline - black bold_black underline_black bold_underline_black - red bold_red underline_red bold_underline_red - green bold_green underline_green bold_underline_green - yellow bold_yellow underline_yellow bold_underline_yellow - blue bold_blue underline_blue bold_underline_blue - magenta bold_magenta underline_magenta bold_underline_magenta - cyan bold_cyan underline_cyan bold_underline_cyan - white bold_white underline_white bold_underline_white - - Valid background colors are: - - on_black on_bright_black - on_red on_bright_red - on_green on_bright_green - on_yellow on_bright_yellow - on_blue on_bright_blue - on_magenta on_bright_magenta - on_cyan on_bright_cyan - on_white on_bright_white - - Note that these are not just colors, but combinations of colors and - attributes. - - Note also that this capability does depend on whether your terminal program - can display these colors. - - - -% task rc: ... --------------------- - - By specifying rc:, it is possible to force task to use an alternate - .taskrc file. By default, task looks in your home directory, so these two - commands are essentially identical: - - % task list - % task rc:~/.taskrc list - - What this override allows, is the possibility of keeping your task lists - completely separate, say for work and home. This can be accomplished with - the following commands (valid for bash): - - % alias htask="task rc:/home/me/.taskrc_home" - % alias wtask="task rc:/home/me/.taskrc_work" - % htask list - ... - % wtask list - ... - - - -Interacting with the Shell --------------------------- - - Certain characters are interpreted by the shell. For example, the "&". If - you wish to include the & in a task description, you need to escape it, so - the shell doesn't interpret it. For example: - - % task add Buy bread & milk - - This command is an error because of the &. The shell will consider this to - be two commands: - - % task add Buy bread & - % milk - - The shell treats the & character as an indicator that the command is complete - and should be run in the background. Then the shell considers "milk" to be a - command all by itself. Which it is not. One way to get around this is to - individually escape the & character: - - % task add Buy bread \& milk - - Another is to quote the entire description, with either ' or " characters: - - % task add "Buy bread & milk" - - Task itself interprets the commands, and it too can make mistakes. For - example, any colon : character will be interpreted by task as a delimiter - between an attribute name and its value. Currently there is no workaround - for this. - - - -Configuring Task ----------------- - - Task recognizes several entries in the .taskrc file for configuration - purposes. Valid entries are of the form: - - name=value - - Valid examples are: - - data.location This is a path to the directory containing all the task - files. By default, it is set up to be ~/.task, for - example: /Users/paul/.task - - command.logging May be "on" or "off", defaulting to "off". This - determines whether task records commands. This is not - generally useful, except while developing task. - - confirmation May be "yes" or "no", and determines whether task will - ask for confirmation before deleting a task. - - nag This may be a string of text, or blank. It is used as - a prompt when a task is completed that is not considered - high priority. The "task next" command lists important - tasks, and completing one of those does not generate - this nagging. Default value is: - - Note: try to stick to high priority tasks. - See "task next". - - next Is a number, defaulting to 2, which is the number of - tasks for each project that are shown in the "task next" - command. - - curses Determines whether task uses ncurses to establish the - size of the window you are using, for text wrapping. - - blanklines May be "on" or "off". Prevents the display of - unnecessary blank lines so that task makes better use - screen real estate on small-screened devices. - - dateformat This is a string of characters that define how task - formats dates. The default value is: - - m/d/Y - - which means dates look like: - - 6/7/2008 - - The string should contain the characters: - - m minimal-digit month 1, 12 - d minimal-digit day 1, 30 - y two-digit year 08 - M two-digit month 01, 12 - D two-digit day 01, 30 - Y four-digit year 2008 - - The string may also contain other characters to act as - spacers, or formatting. Other values could include - (but are not limited to): - - d/m/Y 7/6/2008 - YMD 20080607 - m-d-y 6-7-08 - - showage May be "yes" or "no". Determines whether the "Age" - column appears on the "list" and "next" reports. - - monthsperline Determines how many months the "task calendar" command - renders across the screen. Defaults to 1. - - oldest Determines how many tasks are shown on the "oldest" - report. Defaults to 10. - - newest Determines how many tasks are shown on the "newest" - report. Defaults to 10. - - defaultwidth The width of tables used when ncurses support is not - available. Defaults to 80. - - color May be "on" or "off". Determines whether task uses - color. - - color.overdue These are the coloration rules. They correspond to a - color.due particular attribute of a task, such as it being due, or - color.pri.H being active, and specifies the automatic coloring of - color.pri.M that task. - color.pri.L - color.pri.none The value may be one optional foreground color (see - color.active below) and one optional background color. - color.tagged - For example, the value may be: - - bold_red on_bright_yellow - - color.tag.X Colors any task that has the tag X. - - color.project.X Colors any task assigned to project X. - - color.keyword.X Colors any task where the description contains X. - - -Colors ------- - - Task supports color in several places. In cases where you may specify a - color, a foreground, a background, or a combination foreground and background - color may be used. The following are valid foreground colors: - - bold underline bold_underline - black bold_black underline_black bold_underline_black - red bold_red underline_red bold_underline_red - green bold_green underline_green bold_underline_green - yellow bold_yellow underline_yellow bold_underline_yellow - blue bold_blue underline_blue bold_underline_blue - magenta bold_magenta underline_magenta bold_underline_magenta - cyan bold_cyan underline_cyan bold_underline_cyan - white bold_white underline_white bold_underline_white - - and the following are valid background colors: - - on_black on_bright_black - on_red on_bright_red - on_green on_bright_green - on_yellow on_bright_yellow - on_blue on_bright_blue - on_magenta on_bright_magenta - on_cyan on_bright_cyan - on_white on_bright_white - diff --git a/html/task.html b/html/task.html index 7014cf881..98051cd5d 100644 --- a/html/task.html +++ b/html/task.html @@ -81,9 +81,11 @@

--> -

New in version 1.4.1 (?)

+

New in version 1.4.1 (7/?/2008)

    -
  • Fixed bug whereby task descriptions could not be altered, after being entered. +
  • Fixed bug: Descriptions could not be altered with "task 123 New description" +
  • Tweak: For "task calendar" month names are now centered over the month +
  • Removed TUTORIAL file contents in favor of online version