From b34cb90709b9b5cc2cc6d9a64372ebb4038b8041 Mon Sep 17 00:00:00 2001 From: Paul Beckingham Date: Sun, 18 May 2008 00:30:12 -0400 Subject: [PATCH] - 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. --- AUTHORS | 9 +++ NEWS | 24 +++++- README | 41 ++++++---- TUTORIAL | 217 +++++++++++++++++++++++++++++++++++++++++---------- src/task.cpp | 50 ++++++------ 5 files changed, 259 insertions(+), 82 deletions(-) diff --git a/AUTHORS b/AUTHORS index e69de29bb..d2f8ac41b 100644 --- a/AUTHORS +++ b/AUTHORS @@ -0,0 +1,9 @@ +Principal Author + Paul Beckingham, paul@beckingham.net + +Contributing Authors + +Testers + David Berube + Stas Antons + diff --git a/NEWS b/NEWS index a5d1b15c1..31593bc35 100644 --- a/NEWS +++ b/NEWS @@ -1,4 +1,26 @@ -Task 1.0 is released. +Welcome to Task 1.0.0. +While Task has undergone much testing, bugs are sure to remain. If you +encounter a bug, please contact me at bugs@beckingham.net. Here is what you +could do, in order of increasing effort (to you) and usefulness (to me): + + - Do nothing. Bug probably won't get fixed. + + - Send an email to me, stating that there is a bug. Thanks, but the bug + still probably won't get fixed. + + - Send an email to bugs@beckingham.net, explaining what you saw. Now we're + getting somewhere. The bug will be addressed, and a new release will be + made. You will be a hero. + + - Send an email, and a reproducible test case in the form of the few commands + it takes to recreate the problem. The bug will be addressed, and a new + release will be made. You will be a hero. + + - If you are a developer, send a patch that fixes the problem. Your patch + will be applied and tested, and a new release will be made. You will be a + hero. + +Thank you. diff --git a/README b/README index 2d8fcad5f..015d5c169 100644 --- a/README +++ b/README @@ -1,14 +1,32 @@ +Thank you for taking a look at task. -Thank you -GTD -Based on ideas in todo.sh -Movie at www.b.n/task.mov -Feedback, suggestions to task@beckingham.net -Patches to task@beckingham.net +You may want to jump straight to the TUTORIAL file, or perhaps watch the task +movie on YouTube: + + http://????????????????? + +Either will give you a fairly good idea of what task is capable of, and whether +it fits in to your way of working. As a command line application, task is not +for everyone and some of you may prefer to not proceed. The movie or TUTORIAL +file are the quickest way for you to make that decision. + +Task is based on ideas presented in the todo.sh script, found on: + + http://todotxt.org + +Task has a few more features than todo.sh, but fundamentally, they are both +working toward the same goals, which is to help you follow basic Getting Things +Done (GTD) principles. + +All feedback is welcome, in addition to any bug reports or patches to: + + task@beckingham.net + +Got an idea for an enhancement? Send an email! -Task - a GTD utility featuring: +Task is a GTD utility featuring: - Robust C++ implementation - Tags @@ -20,15 +38,8 @@ Task - a GTD utility featuring: - Clean architecture allowing quick addition of new features - UUID for all tasks -Task is an implementation of GTD ideas, similar to todo.sh, but without many of -the limitations in todo.sh, namely: - - - There is no output formatting - - There is no way to enumerate projects, categories - - There is no file locking for multi-user access - It is intended that features, mainly in the form of reports will be added -frequently, with best practices and useful reports evolving. +frequently, with best practices and useful reports evolving from usage patterns. Task is scope-limited to GTD functionality only. diff --git a/TUTORIAL b/TUTORIAL index 45ab74ffd..abb1a51c0 100644 --- a/TUTORIAL +++ b/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= on - color.due= - color.due=on + 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 +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 - - task /from/to/ - task projects - - task tags - - task info - task active - task overdue - task calendar - - task stats - task usage - - task export - - task version + + + +% 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 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 + diff --git a/src/task.cpp b/src/task.cpp index 517b6e699..ccfc87a6f 100644 --- a/src/task.cpp +++ b/src/task.cpp @@ -2353,34 +2353,38 @@ void handleDone (const TDB& tdb, T& task, Config& conf) void handleExport (const TDB& tdb, T& task, Config& conf) { std::string file = trim (task.getDescription ()); - - std::ofstream out (file.c_str ()); - if (out.good ()) + if (file.length () > 0) { - out << "'id'," - << "'status'," - << "'tags'," - << "'entry'," - << "'start'," - << "'due'," - << "'end'," - << "'project'," - << "'priority'," - << "'fg'," - << "'bg'," - << "'description'" - << "\n"; - - std::vector all; - tdb.allT (all); - foreach (t, all) + std::ofstream out (file.c_str ()); + if (out.good ()) { - out << t->composeCSV ().c_str (); + out << "'id'," + << "'status'," + << "'tags'," + << "'entry'," + << "'start'," + << "'due'," + << "'end'," + << "'project'," + << "'priority'," + << "'fg'," + << "'bg'," + << "'description'" + << "\n"; + + std::vector all; + tdb.allT (all); + foreach (t, all) + { + out << t->composeCSV ().c_str (); + } + out.close (); } - out.close (); + else + throw std::string ("Could not write to export file."); } else - throw std::string ("Could not write to export file."); + throw std::string ("You must specify a file to write to."); } ////////////////////////////////////////////////////////////////////////////////