- 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

@@ -0,0 +1,9 @@
+Principal Author
+  Paul Beckingham, paul@beckingham.net
+
+Contributing Authors
+
+Testers
+  David Berube
+  Stas Antons
+

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.
 

README

@@ -1,14 +1,32 @@
+Thank you for taking a look at task.
 
-Thank you
+You may want to jump straight to the TUTORIAL file, or perhaps watch the task
-GTD
+movie on YouTube:
-Based on ideas in todo.sh
+
-Movie at www.b.n/task.mov
+  http://?????????????????
-Feedback, suggestions to task@beckingham.net
+
-Patches to task@beckingham.net
+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.
 

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
+  task-1.0.0.tar.gz
-  % gunzip task-0.9.7.tar.gz
+  % gunzip task-1.0.0.tar.gz
-  % tar xf task-0.9.7.tar
+  % tar xf task-1.0.0.tar
-  % cd task-0.9.7
+  % 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
+environment variable.
-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:
 
-  % cp SAMPLE_taskrc ~/.taskrc
+Task reads a configuration file - called .taskrc in your home directory - and
-  % mkdir ~/.task
+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
+The simplest way to get a configuration file and task directory is to run task.
-belonging to user bob.  Change this entry to point to your own home directory,
+On startup, task will check to see if it can find the configuration file and
-and the .task directory you just created.  Your task program is now ready to
+task directory, and if not found, will ask you if it may create both.
-use.  Verify that task is properly installed with:
 
   % 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
+While the use of projects and priorities are not essential to benefitting from
-the list of tasks grows large.  Let's assign a project to these tasks:
+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.
+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
-Now that projects are assigned, we can look at just the Wedding project tasks:
+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 3 due:6/25/2008
-  % task 1 due:5/31/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
+   3 Family  H   6/25/2008        6 mins Send John a birthday card
-   1 Wedding H   5/31/2008        7 mins Book plane ticket
+   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=red
-  color.due=<foreground color>
+  color.due=on_blue
-  color.due=on <background color>
+  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
+

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 ());
-
+  if (file.length () > 0)
-  std::ofstream out (file.c_str ());
-  if (out.good ())
   {
-    out << "'id',"
+    std::ofstream out (file.c_str ());
-        << "'status',"
+    if (out.good ())
-        << "'tags',"
-        << "'entry',"
-        << "'start',"
-        << "'due',"
-        << "'end',"
-        << "'project',"
-        << "'priority',"
-        << "'fg',"
-        << "'bg',"
-        << "'description'"
-        << "\n";
-
-    std::vector <T> all;
-    tdb.allT (all);
-    foreach (t, all)
     {
-      out << t->composeCSV ().c_str ();
+      out << "'id',"
+          << "'status',"
+          << "'tags',"
+          << "'entry',"
+          << "'start',"
+          << "'due',"
+          << "'end',"
+          << "'project',"
+          << "'priority',"
+          << "'fg',"
+          << "'bg',"
+          << "'description'"
+          << "\n";
+
+      std::vector <T> 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.");
 }
 
 ////////////////////////////////////////////////////////////////////////////////