'\" t
.\"     Title: timew-annotate
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.20
.\"      Date: 2024-02-25
.\"    Manual: User Manuals
.\"    Source: timew 1.7.1
.\"  Language: English
.\"
.TH "TIMEW\-ANNOTATE" "1" "2024-02-25" "timew 1.7.1" "User Manuals"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE pass:[blue\ R\ <\ >]
.\}
.SH "NAME"
timew-annotate \- add an annotation to intervals
.SH "SYNOPSIS"
.sp
.nf
\fBtimew annotate\fP [\fI<id>\fP\fB...\fP] \fI<annotation>\fP
.fi
.br
.SH "DESCRIPTION"
.sp
The \*(Aqannotate\*(Aq command is used to add an annotation to an interval.
.sp
See the \*(Aqsummary\*(Aq command on how to display the \fI<id>\fP and \fI<annotation>\fP of an interval.
.SH "EXAMPLES"
.sp
\fBAnnotate a single interval\fP
.RS 4
.sp
Call the command with an \fIid\fP and the \fIannotation\fP:
.sp
.if n .RS 4
.nf
.fam C
$ timew annotate @2 \*(AqLorem ipsum\*(Aq
Annotated @2 with "Lorem ipsum"
.fam
.fi
.if n .RE
.RE
.sp
\fBRemove an annotation\fP
.RS 4
.sp
Annotating an interval with an empty string removes the annotation:
.sp
.if n .RS 4
.nf
.fam C
$ timew annotate @1 \*(Aq\*(Aq
Removed annotation from @1
.fam
.fi
.if n .RE
.RE
.sp
\fBAnnotate multiple intervals\fP
.RS 4
.sp
You can annotate multiple intervals with the same \fIannotation\fP at once, by specifying their ids:
.sp
.if n .RS 4
.nf
.fam C
$ timew annotate @2 @10 @23 \*(AqLorem ipsum\*(Aq
Annotated @1 with "Lorem ipsum"
Annotated @10 with "Lorem ipsum"
Annotated @23 with "Lorem ipsum"
.fam
.fi
.if n .RE
.RE
.sp
\fBAnnotate the current open interval\fP
.RS 4
.sp
If there is active time tracking, you can omit the ID when you want to add an annotation to the current open interval:
.sp
.if n .RS 4
.nf
.fam C
$ timew start foo
\&...
$ timew annotate bar
Annotated @1 with "bar"
.fam
.fi
.if n .RE
.sp
This results in the current interval having tag \*(Aqfoo\*(Aq and annotation \*(Aqbar\*(Aq.
.RE
.SH "BUGS & LIMITATIONS"
.sp
The summary command truncates annotations longer than 15 characters.
To display longer annotations, one can use the \*(Aqexport\*(Aq command, or a custom report.
.sp
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
.sp
.if n .RS 4
.nf
.fam C
$ timew annotate @1 lorem ipsum
.fam
.fi
.if n .RE
.sp
will result in interval @1 having only \*(Aqipsum\*(Aq as its annotation.
Use quotes to avoid this.
.SH "SEE ALSO"
.sp
\fBtimew\-export\fP(1),
\fBtimew\-summary\fP(1),
\fBtimew\-tag\fP(1)