Add synopsis and help text for todo formatting.

topydo/commands/ListCommand.py

@@ -114,7 +114,8 @@ class ListCommand(ExpressionCommand):
         return True
 
     def usage(self):
-        return """ Synopsis: ls [-x] [-s <sort_expression>] [-f <format>] [expression]"""
+        return """Synopsis: ls [-x] [-s <sort_expression>] [-f <output format>]
+[-F <format string>] [expression]"""
 
     def help(self):
         return """\
@@ -134,6 +135,34 @@ 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.
+
+         %c: Absolute creation date.
+         %C: Relative creation date.
+         %d: Absolute due date.
+         %D: Relative due date.
+         %h: Relative due and start date (due in 3 days, started 3 days ago)
+         %H: Like %h with creation date.
+         %i: Todo number.
+         %I: Todo number padded with spaces (always 3 characters wide).
+         %k: List of tags separated by spaces (excluding hidden tags).
+         %K: List of all tags separated by spaces.
+         %p: Priority.
+         %s: Todo text.
+         %S: Todo text, truncated such that an item fits on one line.
+         %t: Absolute creation date.
+         %T: Relative creation date.
+         %x: 'x' followed by absolute completion date.
+         %X: 'x' followed by relative completion date.
+         %%: Literal percent sign.
+
+     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 ''
+     (empty string) when an item has no priority set.
 -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).