Provided by: devtodo_0.1.20-7build1_amd64 bug

NAME

       todo - a reminder/task program aimed at developers

SYNOPSIS

       todo [<options>]
              With no options, displays the items in the current directory.

       tda [-p <priority>] [-g <index>] [<text>]
              Add a new item, optionally grafting it as a child of the given item.

       tde <index>
              Edit the given item.

       tdr <indices>
              Remove the given items.

       tdd <indices>
              Mark the specified items as being done.

       todo --link [-g <index>] <database>
              Link the specified devtodo database into the current one, optionally grafting it as
              a child of the specified index.

DESCRIPTION

       todo is a program aimed  specifically  at  programmers  (but  usable  by  anybody  at  the
       terminal) to aid in day-to-day development.

       It  maintains a list of items that have yet to be completed. This allows the programmer to
       track outstanding bugs or items that need to be completed with very little effort.

       Items can be prioritised and can also be displayed in a hierarchy, so that  one  item  may
       depend on another.

       With  the  use  of  some small shell scripts (scripts.* in the doc directory of the source
       distribution), todo can also display the outstanding items in a directory  as  you  change
       into  it.  So, for example, if you cd into the source directory for todo itself you should
       see a list of outstanding items...unless all of the bugs have been fixed ;).

OPTIONS

       Options can have both a long and a short form.

       Short options can be combined into one argument by using a hyphen followed by a string  of
       short options. Parameters of short options can also be appended to this string.

       -v, --verbose
              Display verbosely

       -a, --add [<text>]
              Add a note (will prompt for a note if one is not supplied).

       -g, --graft <index>
              In conjunction with --add or --link, graft the new item to the specified item.

       -l, --link <database>
              Link  the specified todo file into the body of this one. If the linked database has
              a title set, this will be used as the  body  of  the  linking  item  otherwise  the
              directory name of the linked database will be used. Use --remove (or tdr) to remove
              linked databases ‐ this does not remove the database itself, only the link.

       -R,--reparent <index>[,<index>]
              Change the parent of the first item index to the second item index.  If  no  second
              index is given the item is reparented to the root of the tree.

       -p, --priority <priority>
              In  conjunction with --add or --edit, set the priority (default | veryhigh | high |
              medium | low | verylow)

       -e, --edit <index>
              Edit the note that is indexed by the given number.

       --remove <indices>
              Remove the note indexed by the given numbers, including any children.

       -d, --done <indices>
              Mark the specified notes (and their children) as done.

       -D, --not-done <indices>
              Mark the specified notes (and all children) as not done.

       --global-database <file>
              Specify the database to use if either the -G or --global options are specified.

       -G, --global
              Force todo to use the database specified with --global-database. If this is  placed
              in  your  ~/.todorc it will force todo to use that database to the exclusion of all
              others.

       --database <file>
              Change the database from whatever the default is (typically '.todo')  to  the  file
              specified.

       -T, --TODO
              Generate a typical TODO output text file from a Todo DB.

       -A, --all
              Shortcut for the filter '+done,+children' to show all notes.

       -f, --filter <filter>
              Display only those notes that pass the filter. Please refer the section FILTERS for
              more information.

       --colour <colours>
              Override default colours of todo items. Please refer to the section COLOUR for more
              information.

       --force-colour
              Force  use  of colour even when not outputting to a TTY. This is useful when piping
              to less(1) -R.

       --mono Remove all  ANSI  escape  sequences  from  output  -  useful  for  colour  impaired
              terminals.

       --help Display this help.

       --version
              Display version of ToDo.

       --title [<text>]
              Set the title of this directory's todo notes.

       --date-format <format>
              Format  the  display  of  time  values. The format is that used by strftime(3). The
              default format is '%c'. This option is best specified in the ~/.todorc.

       --format <identifier>=<format>
              Specify the formatting of output. Please refer to the section FORMATTING  for  more
              information.

       --use-format <builtin>=<identifier>
              Use  the  format  string  identified by <identifier> (defined with --format) as the
              format string to use when formatting with the builtin format <builtin>.

       --sort <expression>
              Sort the database with the specified expression. Refer to the section  SORTING  for
              more detailed information.

       --paranoid
              Be paranoid about some settings, including permissions.

       --database-loaders <loader list>
              Try  the database formats in the given order. Valid formats are xml and binary. eg.
              todo --database-loaders binary,xml. The default format is XML.

       --backup [<n>]
              Backup the database up to <n> times, just before it is written to. If  <n>  is  not
              specified, one backup will be made. The filenames used to store the backups are the
              default database name with their revision appended like so: .todo.1, .todo.2,  etc.
              To  actually  use  one  of  these  backups,  you  can  either mv it to .todo or use
              --database .todo.<n> to explicitly specify its use.

       -s, --summary
              Toggle "summary" mode, where long items are truncated to one line.

       -c, --comment
              Edit or show comments respectively.

       --timeout [<time>]
              If <time> is specified, the timeout between database displays is set to this number
              of  seconds.  If  no  <time> is specified, the behaviour is to display the database
              only if it has not been displayed for the number of seconds specified by  --timeout
              with  the  <time>  given.  eg.  todo  --timeout 10 --timeout would only display the
              database at most once every 10 seconds. Putting a timeout 10 in your ~/.todorc is a
              good  option,  then  the --timeout in the doc/scripts.* will mean that the database
              won't be displayed every time you cd into a directory.

       --purge [<days-old>]
              Purge all completed items older than <days-old>.  If  <days-old>  is  omitted,  all
              completed records are purged.

PRIORITIES

       Priorities  can be specified symbolically using the words default, veryhigh, high, medium,
       low and verylow.

       The default priority has special meaning in that it will use the default priority for  any
       action.  This  means  that  when editing an existing item, its priority is preserved; when
       creating a new item, the priority will be set to medium; when grafting  a  new  item,  its
       priority  will  be  that  of  its  parent. DevTodo will not prompt for priority if this is
       specified, making it a handy feature for your todorc. As with all  options,  the  priority
       can be overridden on the command line.

FILTERS

       Filters  are  comprised  of  a  list  of  expressions  used  to  define the notes that are
       displayed.

       The general format of a filter expression is:

       ([-|=|+](all|children|done|<index>|<priority>)) | (/<search expression>)

       Generally, if a filter expression is prefixed with a '-' it will not  display  items  that
       match  the  expression,  if  prefixed  with  a  '+'  it will display items that match this
       expression in addition to others, or if prefixed with a '=' (or no prefix at all) it  will
       display  only those items that match the expression. Note that this will only search items
       not excluded by other filters, so to search the  entire  database  you  will  have  to  do
       something like: todo --filter all,/some-search-string.

       The second form of filter expression is used for searching for text in a database. <search
       expression> is a regular expression which is matched against the text body of each item.

       Filter atoms are filtered in order by done state, priority, then search.  So  first  items
       that  do  not  match  the "done" filter will be excluded, then those that do not match the
       priority filter, and so on.

       The expressions in detail:

       all    Forces all items to be displayed. The various  prefixes  have  no  effect  on  this
              expression.

       children
              Collapse  or  expand  child  items.  If  the  '-'  prefix  is  present children are
              collapsed, otherwise children are displayed.

       done   Filter on whether an item is completed or not.

       <index>
              Note indices are specified as numbers. Ranges can be given ala '1.2.10-20'.

       <priority>
              Priorities are specified as described in the PRIORITIES section. A  prefix  of  '-'
              will  display  all  items with priorities less than or equal to the given priority.
              With a '+' prefix, all items with priorities greater than or  equal  to  the  given
              priority  are  shown.  If  '=' or no prefix is given, only items with the specified
              priority are displayed.

       Examples:

       todo --filter done,-children,+low

       This will display only those items that are done and have a priority of low or higher.  In
       addition, children will be collapsed.

       todo /[Tt]he

       Display  only those items with the word 'the' in them, where the first letter can be lower
       or upper case. It may be necessary to quote the search expression to ensure the shell does
       not interpret them.

FORMATTING

       The  output  of  todo  can  be  changed  to  be  more  to your liking by defining your own
       formatting strings. These strings are similar to those used in printf(3) and strftime(3).

       The following examples,  which  can  be  placed  in  ~/.todorc,  will  mimic  the  default
       behaviour:

       # Display in default format
       format display=%i%[info]%f%2n.%[priority]%T

       # Display in default format
       format generated=%2i-%T%2i  (added %d, priority %p)\n\n

       There  are  four separate format options: display, generated, verbose-display and verbose-
       generated. The latter two are used to format  their  respective  text  when  --verbose  is
       specified as an argument to todo.

       In  addition,  users  can  create  their  own format strings by simply passing a different
       identifier to format. This can then be enabled by using --use-format. eg.

       format       full-report=%i%[info]%f%2n.%[priority]%+1T%+1i%[info]Added:       %[normal]%c
       %[info]Completed:    %[normal]%d\n%+1i%[info]Duration:    %[normal]%D     %[info]Priority:
       %[normal]%p\n\n
       # Override the display format to use "full-report".
       use-format display=full-report

       The various flags that are available are:

       %<n>>  The > flag sets the number of spaces <n> to use for all future indenting.

       %[+|-][<n>]i
              Indent to depth of current item. <n> specifies the depth to indent to.  If  <n>  is
              omitted,  the  current level is used. Relative values can be used. eg. '%+1T' would
              indent to one level higher than the current indentation level.

       %[+|-][<n>]T
              Display the text of the  item,  wrapped  at  80  characters  and  indented  to  the
              specified  level.  Semantics  of  <n>  are  as  with  %i.  Note  that  wrapped text
              automatically adds a '0 at the end of the text, whereas %t will not.

       %t     Unwrapped, unformatted text of the item.

       %s     Summary text (ie. one line only, equivalent to --summary).

       %p     The priority level of the current item.

       %c     The current items creation date, formatted according to --date-format.

       %d     The date when the item was marked as done, formatted according to --date-format.

       %D     The duration of the item, formatted according to --date-format.

       %[<n>]n
              The index number of the current item. The optional numeric value <n> specifies  the
              number of characters the number should occupy. The number is padded out with spaces
              so as to fill this number of characters.

       %f     The state flag of the current item. The displayed values  for  this  flag  are  '+'
              means children, '-' means done', '*' means done with children.

       %F     The  human  readable  state flag of the current item. The displayed values for this
              flag are 'children', 'done' means done', 'done, children' and 'open'.

       %[<colour>]
              Colours can be specified with  this  flag.  The  valid  values  for  <colour>  are:
              verylow,  low,  medium, high, veryhigh, title, info, and priority. These are fairly
              self explanatory, except priority changes to the current items priority colour. eg.
              %[priority]

       Please  note  that  when  indenting, you will typically want to use a prefix value of '+1'
       with %T. ie. %+1T. This forces the text to indent to one level  deeper  than  the  current
       level, making it sit away from any other formatting you may have used.

SORTING

       The display of items in the database can be sorted on a variety of keys. Given a series of
       keys todo sorts on each successive key, continuing to the next only if  the  previous  key
       comparison was equal. For example:

       todo --sort -done,text

       This  will  sort  firstly by whether an item is completed and secondly by their text. This
       effectively groups items into two blocks - those that are complete and those that aren't.

       The keys that are available are created, completed, text,  priority,  duration,  none  and
       done.  Each  key,  except  none  can be prefixed with a - to reverse its default order and
       multiple keys must be separated with a ,.

       If multiple --sort parameters are encountered the last one is  used.  This  means  that  a
       'sort' entry in ~/.todorc will be overridden by any on the command line.

INDICES

       Indicies are used as options to a variety of command line arguments. Multiple note indices
       are separated with commas (spaces are not allowed). Children are scoped using a '.'.

       For example, given the following notes:

       1. Do man pages
          1. Make them more beautiful.
          2. Make HTML documentation as well.

       The second sub-item would be represented like this: 1.2

       The wildcard '*' can be used to represent all children of a node. eg. 1.*

       Ranges of notes can be specified by using '<a>-<b>'. For example, to  mark  notes  10.1.2,
       10.1.3 and 10.3.4 as done, you could do: todo --done 10.1.2-4

COLOUR

       Various  items can be colourised. Items that can are veryhigh, high, medium, low, verylow,
       title and info. info is used for displaying item numbers and general information.

       These items can be set to one of eight colours.  Those  colours  are  black,  red,  green,
       yellow,  blue, magenta, cyan, white and default. The colour default is used to specify the
       default foreground terminal colour.

       Colours are specified like so:

       <item>=[+]<colour>

       If the optional + in this expression is used it will cause the item to become bold.

       For example, a line in your ~/.todorc might look like:

       colour    medium=+white

       Which would make medium text bold white.

TODORC

       todo can load options from a number of resource files. The order in which these are parsed
       is as follows:

       1.  The  file  specified  in  the  environment variable TODORC or, if that does not exist,
       /etc/todorc.
       2. ~/.todorc

       Options are cumulative in that those loaded from $TODORC will be overridden or added to by
       those in ~/.todorc.

       These options are specified as key/value pairs, one per line The key is the long name of a
       command line argument and the value is the parameter to that argument,if any. In addition,
       environment variables are expanded.

       For  example,  the  --filter  command  line  argument accepts a parameter that is a filter
       expression. A default filter could be added to the ~/.todorc file like so:

       # Don't display child items by default
       filter -children

       The only difference between options specified in the rc file and those on the command line
       is that options in the rc file are not prefixed by --.

       In addition, there are two commands available in the RC file that are not available on the
       command line. They are:

       The first command, on, is used to conditionally add specific commands. The format of  this
       command  is: on <event> <command> [<arguments>]. Valid events are add, remove, view, edit,
       generate, done, notdone, title, reparent, load, save, link,  create  and  purge.  Multiple
       commands  can  be passed to on by enclosing them in braces (whitespace is required between
       tokens). Full example below.

       The second command is exec <shell command>. This command will execute the argument  it  is
       given  in  a  shell. The environment variable $TODODB contains the filename of the current
       database. eg. exec chmod 600 $TODODB

       There is an example rc file in the doc subdirectory of the source distribution.

EXAMPLES

       To display any outstanding items in the current directory, simply type:

            todo

       To remove notes 1, 2 and 4:

            todo --remove 1,2,4

       To display ALL items:

            todo all

       To display only the top-level items and not their children:

            todo -children

       (even though -children is not a valid argument, this works  because  todo  interprets  any
       command line arguments it doesn't recognise as being part of a filter expression)

       A  more  complex example. This adds a new item, with the text of the item specified on the
       command line, with a priority of high as a child of the third child of the second item (if
       that makes any sense):

            todo -a "Fix the man page" -p high -g 2.3

       This  is  an  example of how to use the TODO feature of todo. It makes todo generate a new
       TODO file from the information stored in the database. This particular example outputs all
       items to the TODO file, even those marked as done.

            todo --filter all --TODO

       This  example  shows  a  nice use of the event triggers. When a new database is created it
       will force its permissions to 0600.

            on create {
                 verbose
                 exec chmod 600 .todo
            }

FILES

        .todo Items are stored as XML in this file.

       /etc/todorc
              Default options can be specified in this file. Please refer to the  section  TODORC
              for more information.

       ~/.todorc
              User-specific  options  are  specified  in  this  file. Please refer to the section
              TODORC for more information.

AUTHORS

       Alec Thomas <alec@swapoff.org>

SEE ALSO

       phpsat <http://sourceforge.net/projects/phpsat>