Documentation

- Updated the task-faq.5.in man page, various edits.
- Now confrms to new syntax.
- Includes new questions on multiple simultaneous installations.
- Corrected answer to the xterm title question.

doc/man/task-faq.5.in

@@ -3,26 +3,26 @@
 .SH NAME
 task-faq \- A FAQ for the task(1) command line todo manager.
 
-.SH DESCRIPTION
-Taskwarrior is a command line TODO list manager. It maintains a list of tasks
-that you want to do, allowing you to add/remove, and otherwise manipulate them.
-Taskwarrior has a rich list of commands that allow you to do various things with it.
-
 .SH WELCOME
 Welcome to the taskwarrior FAQ.  If you have would like to see a question answered
 here, please send us a note at <support@taskwarrior.org>.
 
 .TP
 .B Q: When I redirect the output to a file, I lose all the colors.  How do I fix this?
-A: Taskwarrior knows (or thinks it knows) when the output is not going directly
+Taskwarrior knows when the output is not going directly to a terminal, and
-to a terminal, and strips out all the color control characters.  This is based
+strips out all the color control characters.  This is based on the assumption
-on the assumption that the color control codes are not wanted in the file.
+that the color control codes are not wanted in the file.  Prevent this with the
-Prevent this with the following entry in your .taskrc file:
+following entry in your .taskrc file:
 
-   _forcecolor=on
+    _forcecolor=on
 
-There is an additional problem with using pagers such as 'less' and 'more'.
+or by temporarily overriding the value on the command line:
-When using less, these options will preserve the color codes:
+
+    task ... rc._forcecolor=on
+
+There is an additional problem using pagers such as 'less' and 'more', because
+color control codes are stripped.  When using less, these options will preserve
+the color codes:
 
     task ... | less -FrX
 
@@ -30,23 +30,23 @@ There have been problems reported with the Linux 'more' pager, which inserts
 newline characters.
 
 .TP
-.B Q: How do I backup my taskwarrior data files? Where are they?
+.B Q: How do I backup my taskwarrior data files?  Where are they?
-A: Taskwarrior writes all pending tasks to the file
+Taskwarrior writes all data to files in this location:
 
-    ~/.task/pending.data
+    ~/.task/
 
-and all completed and deleted tasks to
+You may have overridden this location with the 'data.location' configuration
+setting, in which case backup that instead.  All files in this location should
+be backed up.  Making sure all the files in this location are backed up, and not
+just a named subset will ensure that you properly backup future versions of
+taskwarrior, which will likely introduce more files in this location.
 
-    ~/.task/completed.data
+Don't forget there is also the ~/.taskrc file that contains your taskwarrior
-
+configuration data.
-They are text files, so they can just be copied to another location for
-safekeeping.  Don't forget there is also the ~/.taskrc file that contains your
-taskwarrior configuration data.  To be sure, and to future-proof your backup,
-consider backing up all the files in the ~/.task directory.
 
 .TP
 .B Q: How can I separate my work tasks from my home tasks? Specifically, can I keep them completely separate?
-A: You can do this by creating an alternate .taskrc file, then using shell
+You can do this by creating an alternate .taskrc file, then using shell
 aliases. Here are example Bash commands to achieve this:
 
     % cp ~/.taskrc ~/.taskrc_home
@@ -55,11 +55,11 @@ aliases. Here are example Bash commands to achieve this:
     % alias htask="task rc:~/.taskrc_home"
 
 This gives you two commands, 'wtask' and 'htask' that operate using two
-different sets of task data files.
+different sets of task data files.  Bash shell functions are a good alternative.
 
 .TP
 .B Q: Can I revert to a previous version of taskwarrior? How?
-A: Yes, you can revert to a previous version of task, simply by downloading an
+Yes, you can revert to a previous version of task, simply by downloading an
 older version and installing it. If you find a bug in task, then this may be the
 only way to work around the bug, until a patch release is made.
 
@@ -69,9 +69,26 @@ automatically upgrade the file but if you need to revert to a previous version
 of taskwarrior, there is the file format to consider. This is yet another good
 reason to back up your task data files!
 
+.TP
+.B Q: Can I have two separate versions of taskwarrior installed?  How?
+Yes, and here is one simple way to do that.  Install the older version of
+taskwarrior, and then rename the 'task' binary to something like 't194' to
+reflect the version number.  Then install the newer version, which will be
+named 'task'.  Now you have 't194' and 'task' both installed, both using the
+same configuration and data.
+
+Note that the older version will not be aware of any new configuration settings
+and so will complain about them in the 'show' command.  This can be ignored.
+Likewise the newer version may complain about obsolete entries in the
+configuration.
+
+Note also that the man pages will overwrite, which is why it is suggested that
+the older version be installed first, so that you benefit from improved
+documentation.
+
 .TP
 .B Q: How do I build a Darwin 32bit version of task
-A: The taskwarrior packages will not work on a 32-bit OSX installation on Core
+The taskwarrior packages will not work on a 32-bit OSX installation on Core
 Duo hardware.  You will need to build Taskwarrior from source, and use this
 configure command:
 
@@ -82,7 +99,7 @@ See:  http://taskwarrior.org/issues/817
 
 .TP
 .B Q: How do I build taskwarrior under Cygwin?
-A: Take a look at the README.build file, where the latest information on build
+Take a look at the README.build file, where the latest information on build
 issues is kept.  Taskwarrior is built the same way everywhere. But under Cygwin,
 you'll need to make sure you have the following packages available first:
 
@@ -94,7 +111,7 @@ required.
 
 .TP
 .B Q: Do colors work under Cygwin?
-A: They do, but only in a limited way. You can use regular foreground colors
+They do, but only in a limited way. You can use regular foreground colors
 (black, red, green ...) and you can regular background colors (on_black, on_red,
 on_green ...), but underline and bold are not supported.
 
@@ -108,7 +125,7 @@ you can use.
 Note that if you install the 'mintty' shell in Cygwin, then you can use 256
 colors.
 
-See the 'man task-color' for more details on which colors can be used.
+See the 'man task-color' page for more details on which colors can be used.
 
 .TP
 .B Q: Where does taskwarrior store the data?
@@ -128,24 +145,24 @@ for you, so it is probably best to leave those files alone.
 If you delete (or rename) your .taskrc file, taskwarrior will offer to create a
 default one for you.  Another way to do this is with the command:
 
-    $ task rc:new-file version
+    task rc:new-file version
 
 Taskwarrior will create 'new-file' if it doesn't already exist.  There will not
 be much in it though - taskwarrior relies heavily on default values, which can
 be seen with this command:
 
-    $ task show
+    task show
 
-which lists all the currently known settings.  If you have just created
+This lists all the currently known settings.  If you have just created a
-new-file, then this command lists only the defaults.
+new file, then this command lists only the defaults.
 
 Note that this is a good way to learn about new configuration settings,
 particularly if your .taskrc file was created by an older version.
 
 .TP
 .B Q: Do I need to back up my taskwarrior data?
-Yes.  You should back up all the files in your ~/.task directory, and probably
+Yes you do, like all your other files.  You should back up all the files in your
-your ~/.taskrc file too.
+~/.task directory, and your ~/.taskrc file too.
 
 .TP
 .B Q: Can I share my tasks between different machines?
@@ -158,7 +175,7 @@ folder, by modifying the:
 configuration variable.  Check out DropBox at http://www.dropbox.com.
 
 .TP
-.B Q: I don't like dropbox. Is there another way to synchronize my tasks?
+.B Q: I don't want to use dropbox. Is there another way to synchronize my tasks?
 Of course. Especially if you want to modify tasks offline on both machines and
 synchronize them later on. For this purpose there is a 'merge' command which is
 is able to insert the modifications you made to one of your task databases into
@@ -166,8 +183,8 @@ a second database.
 
 Here is a basic example of the procedure:
 
-    $ task merge ssh://user@myremotehost/~/.task/
+    task merge ssh://user@myremotehost/.task/
-    $ task push ssh://user@myremotehost/~/.task/
+    task push ssh://user@myremotehost/.task/
 
 The first command fetches the undo.data file from the remote system, reads the
 changes made and updates the local database. When this merge command completes,
@@ -184,13 +201,15 @@ separator '---'.  The simplest way is to simply delete the undo.data file.  Note
 that it does not slow down taskwarrior, because it is never read until you want
 to undo.  Otherwise taskwarrior only appends to the file.
 
+It is not recommended that you delete the undo.data file.
+
 .TP
 .B Q: How do I know whether my terminal support 256 colors?
 You will need to make sure your TERM environment variable is set to xterm-color,
 otherwise the easiest way is to just try it!  With version 1.9 or later, you
 simply run
 
-    $ task color
+    task color
 
 and a full color palette is displayed.  If you see only 8 or 16 colors, perhaps
 with those colors repeated, then your terminal does not support 256 colors.
@@ -206,22 +225,9 @@ See the task-color(5) man page for an in-depth explanation of the color rules.
 
 .TP
 .B Q: How can I make taskwarrior put the command in the terminal window title?
-You cannot.  But you can make the shell do it, and you can make the shell
+Just set the following value in your .taskrc file:
-call the task program.  Here is a Bash script that does this:
 
-    #! /bin/bash
+    xterm.title=on
-
-    printf "\\033]0;task $*\a"
-    /usr/local/bin/task $*
-
-You just need to run the script, and let the script run task.  Here is a Bash
-function that does the same thing:
-
-    t ()
-    {
-      printf "\\033]0;task $*\a"
-      /usr/local/bin/task $*
-    }
 
 .TP
 .B Q: Taskwarrior searches in a case-sensitive fashion - can I change that?
@@ -231,13 +237,13 @@ You can.  Just set the following value in your .taskrc file:
 
 This will affect searching for keywords:
 
-    $ task list Document
+    task Document list
 
 taskwarrior will perform a caseless search in the description and any
 annotations for the keyword 'Document'.  It also affects description and
 annotation substitutions:
 
-    $ task 1 /teh/the/
+    task 1 modify /teh/the/
 
 The pattern on the left will now be a caseless search term.
 
@@ -252,10 +258,10 @@ incorrectly, because there are more digits.
 When you run a report (such as "list"), the numbers are assigned before display.
 For example, you can do this:
 
-    $ task list
+    task list
-    $ task 12 done
+    task 12 done
-    $ task add Pay the rent
+    task add Pay the rent
-    $ task 31 delete
+    task 31 delete
 
 Those id numbers are then good until the next report is run.  This is because
 taskwarrior performs a garbage-collect operation on the pending tasks file when
@@ -268,16 +274,21 @@ efficiency.
 
 .TP
 .B Q: How do I list tasks that are either priority 'H' or 'M', but not 'L'?
-Taskwarrior's filters are all combined with and implicit logical AND operator, so
+Taskwarrior's filters are all by default combined with and implicit logical AND
-if you were to try this:
+operator, so if you were to try this:
 
-    $ task list priority:H priority:M
+    task priority:H priority:M list
 
 There would be no results, because the priority could not simultaneously be 'H'
-AND 'M'.  What is required is some way to use OR instead of an AND operator. The
+AND 'M'.  Instead, you have a choice.  You can do this:
-solution is to invert the filter in this way:
 
-    $ task list priority.not:L priority.any:
+    task '(priority:H or priority:M)' list
+
+Note that the quotes are one way of escaping the ( ) characters that are
+otherwise interpreted by the shell before taskwarrior sees them.  You can also
+do this:
+
+    task priority.not:L priority.any: list
 
 This filter states that the priority must not be 'L', AND there must be a
 priority assigned.  This filter then properly lists tasks that are 'H' or 'M',
@@ -293,21 +304,21 @@ to construct task filters.
 Taskwarrior now has a 'denotate' command to remove annotations.  Here is an
 example:
 
-    $ task add Original task
+    task add Original task
-    $ task 1 annotate foo
+    task 1 annotate foo
-    $ task 1 annotate bar
+    task 1 annotate bar
-    $ task 1 annotate foo bar
+    task 1 annotate foo bar
 
 Now to delete the first annotation, use:
 
-    $ task 1 denotate foo
+    task 1 denotate foo
 
 This takes the fragment 'foo' and compares it to each of the annotations. In
 this example, it will remove the first annotation, not the third, because it is
 an exact match.  If there are no exact matches, it will remove the first
 non-exact match:
 
-    $ task 1 denotate ar
+    task 1 denotate ar
 
 This will remove the second annotation - the first non-exact match.
 
@@ -333,14 +344,11 @@ There are lots of ways.  Here are some:
  - Contribute to our Wiki
  - Suggest features
  - Write unit tests
+ - Write add-on scripts, and share them
  - Fix bugs
 
 .SH "CREDITS & COPYRIGHTS"
-Taskwarrior was written by P. Beckingham <paul@beckingham.net>.
+Copyright (C) 2006 \- 2011 P. Beckingham, F. Hernandez.
-.br
-Copyright (C) 2006 \- 2011 P. Beckingham
-
-This man page was originally written by P. Beckingham.
 
 Taskwarrior is distributed under the GNU General Public License.  See
 http://www.gnu.org/licenses/gpl-2.0.txt for more information.