Merge pull request #122 from MinchinWeb/documentation-fixes

Improve consistency of help messages.

topydo/cli/CLIApplicationBase.py

@@ -59,7 +59,7 @@ Available commands:
 * sort
 * tag
 
-Run `topydo help <subcommand>` for command-specific help.
+Run `topydo help <subcommand>` for command-specific help.\
 """)
 
 

topydo/commands/AddCommand.py

@@ -138,15 +138,14 @@ class AddCommand(Command):
 
     def usage(self):
         return """Synopsis:
-  add <text>
-  add -f <file>
-  add -f -"""
+  add <TEXT>
+  add -f <FILE> | -"""
 
     def help(self):
         return """\
 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)"
 
@@ -156,5 +155,5 @@ This subcommand automatically adds the creation date to the added item.
 
   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.\
 """

topydo/commands/AppendCommand.py

@@ -49,9 +49,9 @@ class AppendCommand(Command):
             self.error("Invalid todo number given.")
 
     def usage(self):
-        return """Synopsis: append <number> <text>"""
+        return """Synopsis: append <NUMBER> <TEXT>"""
 
     def help(self):
         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.\
 """

topydo/commands/DeleteCommand.py

@@ -40,15 +40,15 @@ class DeleteCommand(DCommand):
 
     def usage(self):
         return """\
-Synopsis: del [-f] <NUMBER1> [<NUMBER2> ...]
-          del [-x] -e <EXPRESSION>
+Synopsis: del [-f] <NUMBER 1> [<NUMBER 2> ...]
+          del [-x] -e <EXPRESSION>\
 """
 
     def help(self):
         return """\
 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
-the -e flag. Use -x to also process todo items that are normally invisible
-(with the 'ls' subcommand).
+It is also possible to delete items that match EXPRESSION using the -e flag.
+Use -x to also process todo items that are normally invisible (as with the 'ls'
+subcommand).\
 """

topydo/commands/DepCommand.py

@@ -136,9 +136,10 @@ class DepCommand(Command):
 
     def help(self):
         return """\
-* add               : Adds a dependency. Using 1 before 2 creates a dependency
-                      from todo item 2 to 1.
+* add               : Adds a dependency. `dep add 1 2` denotes that todo item 1
+                      is dependant on todo item 2, i.e. item 2 is a subitem of
+                      item 1.
 * rm (alias: del)   : Removes a dependency.
 * 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.\
 """

topydo/commands/DepriCommand.py

@@ -37,14 +37,14 @@ class DepriCommand(MultiCommand):
 
     def usage(self):
         return """\
-Synopsis: depri <NUMBER1> [<NUMBER2> ...]
-          depri [-x] -e <EXPRESSION>
+Synopsis: depri <NUMBER 1> [<NUMBER 2> ...]
+          depri [-x] -e <EXPRESSION>\
 """
 
     def help(self):
         return """Removes the priority of the given todo item(s).
 
-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
-(with the 'ls' subcommand).
+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 (as
+with the 'ls' subcommand).\
 """

topydo/commands/DoCommand.py

@@ -105,28 +105,28 @@ class DoCommand(DCommand):
 
     def usage(self):
         return """\
-Synopsis: do [--date] [--force] [--strict] <NUMBER1> [<NUMBER2> ...]
-          do [-x] -e <EXPRESSION>
+Synopsis: do [--date <DATE>] [--force] [--strict] <NUMBER 1> [<NUMBER 2> ...]
+          do [-x] -e <EXPRESSION>\
 """
 
     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
--e flag. Use -x to also process todo items that are normally invisible (with
+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 (as with
 the 'ls' subcommand).
 
-In case a todo has subitems, a question is asked whether the subitems should be
-marked as completed as well. When --force is given, no interaction is required
-and the subitems are not marked completed.
+In case a todo has subitems (dependencies), a question is asked whether the
+subitems should be marked as completed as well. When --force is given, no
+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,
 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
-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
 recurrence date. Note that a future due date is always used as such to
 calculate the new due date.
 
-Use --date to set a custom completion date.
+Use --date to set a custom completion date.\
 """

topydo/commands/EditCommand.py

@@ -138,8 +138,8 @@ class EditCommand(MultiCommand):
     def usage(self):
         return """Synopsis:
   edit
-  edit <NUMBER1> [<NUMBER2> ...]
-  edit -e [-x] [expression]
+  edit <NUMBER 1> [<NUMBER 2> ...]
+  edit -e [-x] [EXPRESSION]
   edit -d"""
 
     def help(self):
@@ -147,15 +147,15 @@ class EditCommand(MultiCommand):
 Launches a text editor to edit todos.
 
 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
-the given expression. See `topydo help ls` for more information on relevant
+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
 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
-to 'vi'.
+By default it will look to your environment variable $EDITOR, otherwise it will
+fall back to 'vi'.
 
--e : Treat the subsequent arguments as an expression.
--x : Edit *all* todos matching the expression (i.e. do not filter on
+-e : Treat the subsequent arguments as an EXPRESSION.
+-x : Edit *all* todos matching the EXPRESSION (i.e. do not filter on
      dependencies or relevance).
--d : Open the archive file.
+-d : Open the archive file.\
 """

topydo/commands/ListCommand.py

@@ -145,20 +145,21 @@ class ListCommand(ExpressionCommand):
         return True
 
     def usage(self):
-        return """Synopsis: ls [-x] [-s <sort_expression>] [-f <output format>]
-[-F <format string>] [-i <item numbers>] [-N | -n <integer>] [expression]"""
+        return """Synopsis: ls [-x] [-s <SORT EXPRESSION>] [-f <OUTPUT FORMAT>]
+[-F <FORMAT STRING>] [-i <NUMBER 1>[,<NUMBER 2> ...]] [-N | -n <INTEGER>]
+[EXPRESSION]"""
 
     def help(self):
         return """\
 Lists all relevant todos. A todo is relevant when:
 
-* has not been completed yet;
-* the start date (if present) has passed;
+* has not been completed yet,
+* the start date (if present) has passed, and
 * 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.
      * '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.
                 an 'ical' tag with a unique ID. Completed todo items may be
                 archived.
      * 'json' - Javascript Object Notation (JSON)
+
 -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
      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.
      Conditional characters can be added with blocks surrounded by curly
      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.
 
      A tab character serves as a marker to start right alignment.
 -i : Comma separated list of todo IDs to print.
 -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.
--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.
--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).\
 """

topydo/commands/PostponeCommand.py

@@ -77,23 +77,23 @@ class PostponeCommand(MultiCommand):
 
     def usage(self):
         return """\
-Synopsis: postpone [-s] <NUMBER> [<NUMBER2> ...] <PATTERN>"
-          postpone [-x] -e <EXPRESSION>
+Synopsis: postpone [-s] <NUMBER> [<NUMBER2> ...] <PATTERN>
+          postpone [-x] -e <EXPRESSION>\
 """
 
     def help(self):
         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
 flag is given, the start date accordingly.
 
-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
-(with the 'ls' subcommand).
+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 (as
+with the 'ls' subcommand).
 
-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
-days, weeks, months and years respectively. Example: 'postpone 1 1w' postpones
-todo number 1 for 1 week.
+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
+days, weeks, months and years respectively. Example: 'postpone 1 2w' postpones
+todo number 1 for 2 weeks.\
 """

topydo/commands/PriorityCommand.py

@@ -56,15 +56,15 @@ class PriorityCommand(MultiCommand):
 
     def usage(self):
         return """\
-Synopsis: pri <NUMBER1> [<NUMBER2> ...] <PRIORITY>
-          pri [-x] -e <EXPRESSION>
+Synopsis: pri <NUMBER 1> [<NUMBER 2> ...] <PRIORITY>
+          pri [-x] -e <EXPRESSION>\
 """
 
     def help(self):
         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
-the -e flag. Use -x to also process todo items that are normally invisible
-(with the 'ls' subcommand).
+It is also possible to prioritize items with an EXPRESSION using the -e flag.
+Use -x to also process todo items that are normally invisible (as with the 'ls'
+subcommand).\
 """

topydo/commands/RevertCommand.py

@@ -54,6 +54,4 @@ class RevertCommand(Command):
         return """Synopsis: revert"""
 
     def help(self):
-        return """\
-Reverts the last command.
-"""
+        return """Reverts the last command."""

topydo/commands/SortCommand.py

@@ -42,14 +42,14 @@ class SortCommand(Command):
         self.todolist.replace(sorted_todos)
 
     def usage(self):
-        return """Synopsis: sort [expression]"""
+        return """Synopsis: sort [<EXPRESSION>]"""
 
     def help(self):
         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.
 
-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
 precedence, then the second, etc.
 
@@ -61,12 +61,12 @@ The following sort attributes are supported:
 * importance     - Sort by importance
 * importance-avg - Sort by average importance (based on parent items)
 * 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
 or descending sort respectively. If not specified, ascending sort is assumed.
 
 Example:
 
-    desc:importance,due,desc:priority
+    desc:importance,due,desc:priority\
 """

topydo/commands/TagCommand.py

@@ -133,15 +133,15 @@ class TagCommand(Command):
             self._set()
 
     def usage(self):
-        return """Synopsis: tag [-a] [-f] <NUMBER> <tag> [<value>]"""
+        return """Synopsis: tag [-a] [-f] <NUMBER> <TAG> [<VALUE>]"""
 
     def help(self):
         return """\
-Sets the given tag to the given todo number with the given value. If the value
-is omitted, the tag is removed from the todo item.
+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.
 
--a : Do not change the current value of the tag if it exists, but add a new
-     value.
--f : Force setting/removing all values of the tag. Prevents interaction with
-     the user.
+-a : Do not change the current value of the TAG if it exists, but add a new
+     VALUE for the given TAG.
+-f : Force setting/removing all values of the TAG. Prevents interaction with
+     the user.\
 """