Commit 181b2743 authored by Bram Schoenmakers's avatar Bram Schoenmakers

Merge pull request #122 from MinchinWeb/documentation-fixes

Improve consistency of help messages.
parents 5122ef03 48a07f49
...@@ -59,7 +59,7 @@ Available commands: ...@@ -59,7 +59,7 @@ Available commands:
* sort * sort
* tag * tag
Run `topydo help <subcommand>` for command-specific help. Run `topydo help <subcommand>` for command-specific help.\
""") """)
......
...@@ -138,15 +138,14 @@ class AddCommand(Command): ...@@ -138,15 +138,14 @@ class AddCommand(Command):
def usage(self): def usage(self):
return """Synopsis: return """Synopsis:
add <text> add <TEXT>
add -f <file> add -f <FILE> | -"""
add -f -"""
def help(self): def help(self):
return """\ return """\
This subcommand automatically adds the creation date to the added item. This subcommand automatically adds the creation date to the added item.
<text> may contain: TEXT may contain:
* Priorities mid-sentence. Example: add "Water flowers (C)" * Priorities mid-sentence. Example: add "Water flowers (C)"
...@@ -156,5 +155,5 @@ This subcommand automatically adds the creation date to the added item. ...@@ -156,5 +155,5 @@ This subcommand automatically adds the creation date to the added item.
Example: add "Subtask partof:1" Example: add "Subtask partof:1"
-f : Add todo items from specified <file> or from standard input. -f : Add todo items from specified FILE or from standard input.\
""" """
...@@ -49,9 +49,9 @@ class AppendCommand(Command): ...@@ -49,9 +49,9 @@ class AppendCommand(Command):
self.error("Invalid todo number given.") self.error("Invalid todo number given.")
def usage(self): def usage(self):
return """Synopsis: append <number> <text>""" return """Synopsis: append <NUMBER> <TEXT>"""
def help(self): def help(self):
return """\ return """\
Adds the given <text> to the end of the todo indicated by <number>. Adds the given TEXT to the end of the todo indicated by NUMBER.\
""" """
...@@ -40,15 +40,15 @@ class DeleteCommand(DCommand): ...@@ -40,15 +40,15 @@ class DeleteCommand(DCommand):
def usage(self): def usage(self):
return """\ return """\
Synopsis: del [-f] <NUMBER1> [<NUMBER2> ...] Synopsis: del [-f] <NUMBER 1> [<NUMBER 2> ...]
del [-x] -e <EXPRESSION> del [-x] -e <EXPRESSION>\
""" """
def help(self): def help(self):
return """\ return """\
Deletes the todo item(s) with the given number(s) from the list. Deletes the todo item(s) with the given number(s) from the list.
It is also possible to delete items as complete with an expression using It is also possible to delete items that match EXPRESSION using the -e flag.
the -e flag. Use -x to also process todo items that are normally invisible Use -x to also process todo items that are normally invisible (as with the 'ls'
(with the 'ls' subcommand). subcommand).\
""" """
...@@ -136,9 +136,10 @@ class DepCommand(Command): ...@@ -136,9 +136,10 @@ class DepCommand(Command):
def help(self): def help(self):
return """\ return """\
* add : Adds a dependency. Using 1 before 2 creates a dependency * add : Adds a dependency. `dep add 1 2` denotes that todo item 1
from todo item 2 to 1. is dependant on todo item 2, i.e. item 2 is a subitem of
item 1.
* rm (alias: del) : Removes a dependency. * rm (alias: del) : Removes a dependency.
* ls : Lists all dependencies to or from a certain todo. * ls : Lists all dependencies to or from a certain todo.
* clean (alias: gc) : Removes redundant id or p tags. * clean (alias: gc) : Removes redundant id or p tags.\
""" """
...@@ -37,14 +37,14 @@ class DepriCommand(MultiCommand): ...@@ -37,14 +37,14 @@ class DepriCommand(MultiCommand):
def usage(self): def usage(self):
return """\ return """\
Synopsis: depri <NUMBER1> [<NUMBER2> ...] Synopsis: depri <NUMBER 1> [<NUMBER 2> ...]
depri [-x] -e <EXPRESSION> depri [-x] -e <EXPRESSION>\
""" """
def help(self): def help(self):
return """Removes the priority of the given todo item(s). return """Removes the priority of the given todo item(s).
It is also possible to deprioritize items as complete with an expression using It is also possible to deprioritize items as complete with an EXPRESSION using
the -e flag. Use -x to also process todo items that are normally invisible the -e flag. Use -x to also process todo items that are normally invisible (as
(with the 'ls' subcommand). with the 'ls' subcommand).\
""" """
...@@ -105,28 +105,28 @@ class DoCommand(DCommand): ...@@ -105,28 +105,28 @@ class DoCommand(DCommand):
def usage(self): def usage(self):
return """\ return """\
Synopsis: do [--date] [--force] [--strict] <NUMBER1> [<NUMBER2> ...] Synopsis: do [--date <DATE>] [--force] [--strict] <NUMBER 1> [<NUMBER 2> ...]
do [-x] -e <EXPRESSION> do [-x] -e <EXPRESSION>\
""" """
def help(self): def help(self):
return """Marks the todo(s) with given number(s) as complete. return """Marks the todo(s) with given NUMBER(s) as complete.
It is also possible to mark todo items as complete with an expression using the It is also possible to mark todo items as complete with an EXPRESSION using the
-e flag. Use -x to also process todo items that are normally invisible (with -e flag. Use -x to also process todo items that are normally invisible (as with
the 'ls' subcommand). the 'ls' subcommand).
In case a todo has subitems, a question is asked whether the subitems should be In case a todo has subitems (dependencies), a question is asked whether the
marked as completed as well. When --force is given, no interaction is required subitems should be marked as completed as well. When --force is given, no
and the subitems are not marked completed. interaction is required and the subitems are not marked completed.
In case a completed todo is recurring, a new todo will be added to the list, In case a completed todo is recurring, a new todo will be added to the list,
while the given todo item is marked as complete. The new date is calculated while the given todo item is marked as complete. The new date is calculated
based on the todo item's due date. If the due date is in the past, today's date based on the todo item's due date. If the due date is in the past, today's date
is used to calculate the new recurrence date. Using --strict prevents this, is used to calculate the new recurrence date. Using --strict prevents this, and
then the actual due date of the todo item is used to calculate the new then the actual due date of the todo item is used to calculate the new
recurrence date. Note that a future due date is always used as such to recurrence date. Note that a future due date is always used as such to
calculate the new due date. calculate the new due date.
Use --date to set a custom completion date. Use --date to set a custom completion date.\
""" """
...@@ -138,8 +138,8 @@ class EditCommand(MultiCommand): ...@@ -138,8 +138,8 @@ class EditCommand(MultiCommand):
def usage(self): def usage(self):
return """Synopsis: return """Synopsis:
edit edit
edit <NUMBER1> [<NUMBER2> ...] edit <NUMBER 1> [<NUMBER 2> ...]
edit -e [-x] [expression] edit -e [-x] [EXPRESSION]
edit -d""" edit -d"""
def help(self): def help(self):
...@@ -147,15 +147,15 @@ class EditCommand(MultiCommand): ...@@ -147,15 +147,15 @@ class EditCommand(MultiCommand):
Launches a text editor to edit todos. Launches a text editor to edit todos.
Without any arguments it will just open the todo.txt file. Alternatively it can Without any arguments it will just open the todo.txt file. Alternatively it can
edit todo item(s) with the given number(s) or edit relevant todos matching edit todo item(s) with the given NUMBER(s) or edit relevant todos matching
the given expression. See `topydo help ls` for more information on relevant the given EXPRESSION. See `topydo help ls` for more information on relevant
todo items. It is also possible to open the archive file. todo items. It is also possible to open the archive file.
By default it will use $EDITOR in your environment, otherwise it will fall back By default it will look to your environment variable $EDITOR, otherwise it will
to 'vi'. fall back to 'vi'.
-e : Treat the subsequent arguments as an expression. -e : Treat the subsequent arguments as an EXPRESSION.
-x : Edit *all* todos matching the expression (i.e. do not filter on -x : Edit *all* todos matching the EXPRESSION (i.e. do not filter on
dependencies or relevance). dependencies or relevance).
-d : Open the archive file. -d : Open the archive file.\
""" """
...@@ -145,20 +145,21 @@ class ListCommand(ExpressionCommand): ...@@ -145,20 +145,21 @@ class ListCommand(ExpressionCommand):
return True return True
def usage(self): def usage(self):
return """Synopsis: ls [-x] [-s <sort_expression>] [-f <output format>] return """Synopsis: ls [-x] [-s <SORT EXPRESSION>] [-f <OUTPUT FORMAT>]
[-F <format string>] [-i <item numbers>] [-N | -n <integer>] [expression]""" [-F <FORMAT STRING>] [-i <NUMBER 1>[,<NUMBER 2> ...]] [-N | -n <INTEGER>]
[EXPRESSION]"""
def help(self): def help(self):
return """\ return """\
Lists all relevant todos. A todo is relevant when: Lists all relevant todos. A todo is relevant when:
* has not been completed yet; * has not been completed yet,
* the start date (if present) has passed; * the start date (if present) has passed, and
* there are no subitems that need to be completed. * there are no subitems that need to be completed.
When an expression is given, only the todos matching that expression are shown. When an EXPRESSION is given, only the todos matching that EXPRESSION are shown.
-f : Specify the output format, being 'text' (default), 'ical' or 'json'. -f : Specify the OUTPUT FORMAT, being 'text' (default), 'ical' or 'json'.
* 'text' - Text output with colors and indentation if applicable. * 'text' - Text output with colors and indentation if applicable.
* 'ical' - iCalendar (RFC 2445). Is not supported in Python 3.2. Be aware * 'ical' - iCalendar (RFC 2445). Is not supported in Python 3.2. Be aware
...@@ -166,6 +167,7 @@ When an expression is given, only the todos matching that expression are shown. ...@@ -166,6 +167,7 @@ When an expression is given, only the todos matching that expression are shown.
an 'ical' tag with a unique ID. Completed todo items may be an 'ical' tag with a unique ID. Completed todo items may be
archived. archived.
* 'json' - Javascript Object Notation (JSON) * 'json' - Javascript Object Notation (JSON)
-F : Specify the format of the text ('text' format), which may contain -F : Specify the format of the text ('text' format), which may contain
placeholders that may be expanded if the todo has such attribute. If such placeholders that may be expanded if the todo has such attribute. If such
attribute does not exist, then it expands to an empty string. attribute does not exist, then it expands to an empty string.
...@@ -193,14 +195,14 @@ When an expression is given, only the todos matching that expression are shown. ...@@ -193,14 +195,14 @@ When an expression is given, only the todos matching that expression are shown.
Conditional characters can be added with blocks surrounded by curly Conditional characters can be added with blocks surrounded by curly
braces, they will only appear when a placeholder expanded to a value. braces, they will only appear when a placeholder expanded to a value.
E.g. %{(}p{)} will print (C) when the todo item has priority C, or '' E.g. %{(}p{)} will print '(C)' when the todo item has priority C, or ''
(empty string) when an item has no priority set. (empty string) when an item has no priority set.
A tab character serves as a marker to start right alignment. A tab character serves as a marker to start right alignment.
-i : Comma separated list of todo IDs to print. -i : Comma separated list of todo IDs to print.
-n : Number of items to display. Defaults to the value in the configuration. -n : Number of items to display. Defaults to the value in the configuration.
-N : Limit number of items displayed such that they fit on the terminal. -N : Limit number of items displayed such that they fit on the terminal.
-s : Sort the list according to a sort expression. Defaults to the expression -s : Sort the list according to a SORT EXPRESSION. Defaults to the expression
in the configuration. in the configuration.
-x : Show all todos (i.e. do not filter on dependencies or relevance). -x : Show all todos (i.e. do not filter on dependencies or relevance).\
""" """
...@@ -77,23 +77,23 @@ class PostponeCommand(MultiCommand): ...@@ -77,23 +77,23 @@ class PostponeCommand(MultiCommand):
def usage(self): def usage(self):
return """\ return """\
Synopsis: postpone [-s] <NUMBER> [<NUMBER2> ...] <PATTERN>" Synopsis: postpone [-s] <NUMBER> [<NUMBER2> ...] <PATTERN>
postpone [-x] -e <EXPRESSION> postpone [-x] -e <EXPRESSION>\
""" """
def help(self): def help(self):
return """\ return """\
Postpone the todo item(s) with the given number(s) and the given pattern. Postpone the todo item(s) with the given NUMBER(s) and the given PATTERN.
Postponing is done by adjusting the due date(s) of the todo(s), and if the -s Postponing is done by adjusting the due date(s) of the todo(s), and if the -s
flag is given, the start date accordingly. flag is given, the start date accordingly.
It is also possible to postpone items as complete with an expression using It is also possible to postpone items as complete with an EXPRESSION using
the -e flag. Use -x to also process todo items that are normally invisible the -e flag. Use -x to also process todo items that are normally invisible (as
(with the 'ls' subcommand). with the 'ls' subcommand).
The pattern is a relative date, written in the format <COUNT><PERIOD> where The PATTERN is a relative date, written in the format <COUNT> <PERIOD> where
count is a number and <PERIOD> is either 'd', 'w', 'm' or 'y', which stands for COUNT is a number and PERIOD is either 'd', 'w', 'm' or 'y', which stands for
days, weeks, months and years respectively. Example: 'postpone 1 1w' postpones days, weeks, months and years respectively. Example: 'postpone 1 2w' postpones
todo number 1 for 1 week. todo number 1 for 2 weeks.\
""" """
...@@ -56,15 +56,15 @@ class PriorityCommand(MultiCommand): ...@@ -56,15 +56,15 @@ class PriorityCommand(MultiCommand):
def usage(self): def usage(self):
return """\ return """\
Synopsis: pri <NUMBER1> [<NUMBER2> ...] <PRIORITY> Synopsis: pri <NUMBER 1> [<NUMBER 2> ...] <PRIORITY>
pri [-x] -e <EXPRESSION> pri [-x] -e <EXPRESSION>\
""" """
def help(self): def help(self):
return """\ return """\
Sets the priority of todo(s) the given number(s) to the given priority. Sets the priority of todo(s) the given NUMBER(s) to the given PRIORITY.
It is also possible to prioritize items as complete with an expression using It is also possible to prioritize items with an EXPRESSION using the -e flag.
the -e flag. Use -x to also process todo items that are normally invisible Use -x to also process todo items that are normally invisible (as with the 'ls'
(with the 'ls' subcommand). subcommand).\
""" """
...@@ -54,6 +54,4 @@ class RevertCommand(Command): ...@@ -54,6 +54,4 @@ class RevertCommand(Command):
return """Synopsis: revert""" return """Synopsis: revert"""
def help(self): def help(self):
return """\ return """Reverts the last command."""
Reverts the last command.
"""
...@@ -42,14 +42,14 @@ class SortCommand(Command): ...@@ -42,14 +42,14 @@ class SortCommand(Command):
self.todolist.replace(sorted_todos) self.todolist.replace(sorted_todos)
def usage(self): def usage(self):
return """Synopsis: sort [expression]""" return """Synopsis: sort [<EXPRESSION>]"""
def help(self): def help(self):
return """\ return """\
Sorts the file according to the expression. If no expression is given, the Sorts the todo file according to the EXPRESSION. If no EXPRESSION is given, the
expression in the configuration is used. expression in the configuration is used.
The expression is a comma separated list of attributes to sort on. The list is The EXPRESSION is a comma separated list of attributes to sort on. The list is
evaluated in order, which means that the first attribute takes higher evaluated in order, which means that the first attribute takes higher
precedence, then the second, etc. precedence, then the second, etc.
...@@ -61,12 +61,12 @@ The following sort attributes are supported: ...@@ -61,12 +61,12 @@ The following sort attributes are supported:
* importance - Sort by importance * importance - Sort by importance
* importance-avg - Sort by average importance (based on parent items) * importance-avg - Sort by average importance (based on parent items)
* text - Sort by text * text - Sort by text
* <tag> - Sort by values of the given tag * <TAG> - Sort by values of the given TAG
Each item can optionally be prefixed with asc: and desc: to specify ascending Each item can optionally be prefixed with asc: and desc: to specify ascending
or descending sort respectively. If not specified, ascending sort is assumed. or descending sort respectively. If not specified, ascending sort is assumed.
Example: Example:
desc:importance,due,desc:priority desc:importance,due,desc:priority\
""" """
...@@ -133,15 +133,15 @@ class TagCommand(Command): ...@@ -133,15 +133,15 @@ class TagCommand(Command):
self._set() self._set()
def usage(self): def usage(self):
return """Synopsis: tag [-a] [-f] <NUMBER> <tag> [<value>]""" return """Synopsis: tag [-a] [-f] <NUMBER> <TAG> [<VALUE>]"""
def help(self): def help(self):
return """\ return """\
Sets the given tag to the given todo number with the given value. If the value Sets the given TAG on the given todo NUMBER with the given VALUE. If the VALUE
is omitted, the tag is removed from the todo item. is omitted, the TAG is removed from the todo item.
-a : Do not change the current value of the tag if it exists, but add a new -a : Do not change the current value of the TAG if it exists, but add a new
value. VALUE for the given TAG.
-f : Force setting/removing all values of the tag. Prevents interaction with -f : Force setting/removing all values of the TAG. Prevents interaction with
the user. the user.\
""" """
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment