Update man pages for annotation command and summary report

Closes #444

Signed-off-by: Thomas Lauf <thomas.lauf@tngtech.com>

AUTHORS

@@ -108,3 +108,4 @@ Thanks to the following, who submitted detailed bug reports and excellent sugges
   Oivvio Polite
   Davide Crucitti
   Christian Kohlstedde
+  apkawel

ChangeLog

@@ -15,6 +15,8 @@
 - #439    Show error message if command track is called with an id
 - #441    Return report return code
           (thanks to lospatchos)
+- #444    Improve documentation on annotations
+          (Thanks to apkawel, Shaun Ruffel)
 - #450    Report 'totals.py' does not display data when no time range specified
           (thanks to squirrellyDave)
 - #458    Add man documentation for configuring tag colors.

doc/man1/timew-annotate.1.adoc

@@ -5,43 +5,50 @@ timew-annotate - add an annotation to intervals
 
 == SYNOPSIS
 [verse]
-*timew annotate* [_<id>_**...**] _<annotation>_**...**
+*timew annotate* [_<id>_**...**] _<annotation>_
 
 == DESCRIPTION
 The 'annotate' command is used to add an annotation to an interval.
 
-Using the 'summary' command, and specifying the ':ids' hint shows interval IDs.
+See the 'summary' command on how to display the _<id>_ and _<annotation>_ of an interval.
-Using the right ID, you can identify an interval to annotate.
 
 == EXAMPLES
-
+*Annotate a single interval*::
-For example, show the IDs:
++
-
+Call the command with an _id_ and the _annotation_:
++
 [source]
 ----
-$ timew summary :week :ids
+$ timew annotate @2 'Lorem ipsum'
+Annotated @2 with "Lorem ipsum"
 ----
 
-Then having selected e.g. '@2' as the interval you wish to annotate:
+*Remove an annotation*::
-
++
+Annotating an interval with an empty string removes the annotation:
++
 [source]
 ----
-$ timew annotate @2 'Lorem ipsum...'
+$ timew annotate @1 ''
-Annotated @2 with "Lorem ipsum..."
+Removed annotation from @1
 ----
 
-Note that you can annotate multiple intervals with the same annotation:
+*Annotate multiple intervals*::
-
++
+You can annotate multiple intervals with the same _annotation_ at once, by specifying their ids:
++
 [source]
 ----
-$ timew annotate @2 @10 @23 'Lorem ipsum dolor sit amet...'
+$ timew annotate @2 @10 @23 'Lorem ipsum'
-Annotated @1 with "Lorem ipsum dolor sit amet..."
+Annotated @1 with "Lorem ipsum"
-Annotated @10 with "Lorem ipsum dolor sit amet..."
+Annotated @10 with "Lorem ipsum"
-Annotated @23 with "Lorem ipsum dolor sit amet..."
+Annotated @23 with "Lorem ipsum"
 ----
 
-If there is active time tracking, you can omit the ID when you want to add annotations to the current open interval:
+*Annotate the current open interval*::
-
++
+If there is active time tracking, you can omit the ID when you want to add an annotation to the current open interval:
++
 [source]
 ----
 $ timew start foo
@@ -49,22 +56,25 @@ $ timew start foo
 $ timew annotate bar
 Annotated @1 with "bar"
 ----
-
++
-This results in the current interval having annotations 'foo' and 'bar'.
+This results in the current interval having tag 'foo' and annotation 'bar'.
 
 == pass:[BUGS & LIMITATIONS]
 The summary command truncates annotations longer than 15 characters.
-To display longer annotations, one can use the export command, or a custom report.
+To display longer annotations, one can use the 'export' command, or a custom report.
 
 Currently, the annotation command picks the last token from the command line and uses it as annotation.
 I.e. using no quotes in an annotation command like
 
 [source]
 ----
-$ timew annotate @1 lorem ipsum dolor
+$ timew annotate @1 lorem ipsum
 ----
 
-will result in interval @1 having only 'dolor' as its annotation.
+will result in interval @1 having only 'ipsum' as its annotation.
+Use quotes to avoid this.
 
 == SEE ALSO
+**timew-export**(1),
+**timew-summary**(1),
 **timew-tag**(1)

doc/man1/timew-summary.1.adoc

@@ -8,38 +8,57 @@ timew-summary - display a time-tracking summary
 *timew summary* [_<range>_] [_<tag>_**...**]
 
 == DESCRIPTION
-Displays a report summarizing tracked and untracked time for the current day by default.
+Displays a table summarizing tracked time, by default for the current day.
-Accepts date ranges and tags for filtering, or shortcut hints:
+Accepts date ranges, or range hints, and tags for filtering.
 
-    $ timew summary monday - today
+== HINTS
-    $ timew summary :week
+Apart from range hints (see **timew-hints**(7)), the summary report adheres to the following hints:
-    $ timew summary :month
 
-The ':ids' hint adds an 'ID' column to the summary report output for interval modification.
+**:annotations**::
-
+**:no-annotations**::
-The ':annotations' hint adds an 'Annotation' column to the summary report output.
+Toggle the display of annotations in the summary report.
+Can be used on the command line to override the configured setting.
+The ':annotations' hint adds an 'Annotation' column to the summary table.
 The annotation column is limited to 15 characters.
 Longer values in this column are truncated to 12 characters and shown with an ellipsis attached.
 
+**:holidays**::
+**:no-holidays**::
+Toggle the display of holidays in the summary report.
+Can be used on the command line to override the configured setting.
+
+**:ids**::
+**:no-ids**::
+Toggle the display of ids in the summary report.
+Can be used on the command line to override the configured setting.
+The ':ids' hint adds an 'ID' column to the summary table.
+Those ids can be used for interval modification.
+
+**:tags**::
+**:no-tags**::
+Toggle the display of tags in the summary report.
+Can be used on the command line to override the configured setting.
+The ':tags' hint adds a 'Tags' column to the summary table.
+
 == CONFIGURATION
 **reports.summary.annotations**::
 Determines whether the annotation column is shown in the summary.
-Can be overridden by the ':annotations' and ':no-annotations' hint, respectively.
+Can be overridden by the ':annotations' or ':no-annotations' hint, respectively.
 Default value is 'no'
 
 **reports.summary.holidays**::
 Determines whether relevant holidays are shown beneath the report.
-Can be overridden by the ':holidays' and ':no-holidays' hint, respectively.
+Can be overridden by the ':holidays' or ':no-holidays' hint, respectively.
 Default value is 'yes'.
 
 **reports.summary.ids**::
 Determines whether the id column is shown in the summary.
-Can be overridden by the ':ids' and ':no-ids' hint, respectively.
+Can be overridden by the ':ids' or ':no-ids' hint, respectively.
 Default value is 'no'.
 
 **reports.summary.tags**::
 Determines whether the tags column is shown in the summary.
-Can be overridden by the ':tags' and ':no-tags' hint, respectively.
+Can be overridden by the ':tags' or ':no-tags' hint, respectively.
 Default value is 'yes'.
 
 **reports.summary.range**::
@@ -61,6 +80,7 @@ Examples of valid colors include 'white', 'gray8', 'black on yellow', and 'rgb34
 
 == SEE ALSO
 **timew-day**(1),
+**timew-hints**(7),
 **timew-lengthen**(1),
 **timew-modify**(1),
 **timew-month**(1),