mirror of
https://github.com/GothenburgBitFactory/timewarrior.git
synced 2025-07-07 20:06:39 +02:00
Update man pages for annotation command and summary report
Closes #444 Signed-off-by: Thomas Lauf <thomas.lauf@tngtech.com>
This commit is contained in:
Thomas Lauf
parent
016d3a99e7
commit
2d7dd35bd5
4 changed files with 69 additions and 36 deletions
1
AUTHORS
1
AUTHORS
|
|
@ -108,3 +108,4 @@ Thanks to the following, who submitted detailed bug reports and excellent sugges
|
|||
Oivvio Polite
|
||||
Davide Crucitti
|
||||
Christian Kohlstedde
|
||||
apkawel
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Using the right ID, you can identify an interval to annotate.
|
||||
See the 'summary' command on how to display the _<id>_ and _<annotation>_ of an interval.
|
||||
|
||||
== EXAMPLES
|
||||
|
||||
For example, show the IDs:
|
||||
|
||||
*Annotate a single interval*::
|
||||
+
|
||||
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...'
|
||||
Annotated @2 with "Lorem ipsum..."
|
||||
$ timew annotate @1 ''
|
||||
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...'
|
||||
Annotated @1 with "Lorem ipsum dolor sit amet..."
|
||||
Annotated @10 with "Lorem ipsum dolor sit amet..."
|
||||
Annotated @23 with "Lorem ipsum dolor sit amet..."
|
||||
$ timew annotate @2 @10 @23 'Lorem ipsum'
|
||||
Annotated @1 with "Lorem ipsum"
|
||||
Annotated @10 with "Lorem ipsum"
|
||||
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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Accepts date ranges and tags for filtering, or shortcut hints:
|
||||
Displays a table summarizing tracked time, by default for the current day.
|
||||
Accepts date ranges, or range hints, and tags for filtering.
|
||||
|
||||
$ timew summary monday - today
|
||||
$ timew summary :week
|
||||
$ timew summary :month
|
||||
== HINTS
|
||||
Apart from range hints (see **timew-hints**(7)), the summary report adheres to the following hints:
|
||||
|
||||
The ':ids' hint adds an 'ID' column to the summary report output for interval modification.
|
||||
|
||||
The ':annotations' hint adds an 'Annotation' column to the summary report output.
|
||||
**:annotations**::
|
||||
**:no-annotations**::
|
||||
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),
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue