.\"
.\" %nmhwarning%
.\"
.TH ANNO %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
.SH NAME
anno \- annotate messages
.SH SYNOPSIS
.HP 5
.na
.B anno
.RI [ +folder ]
.RI [ msgs ]
.RB [ \-component
.IR field ]
.RB [ \-text
.IR body ]
.RB [ \-append ]
.RB [ \-date " | " \-nodate ]
.RB [ \-preserve " | " \-nopreserve ]
.RB [ \-Version ]
.RB [ \-help ]
.HP
.B anno
.B \-delete
.RI [ +folder ]
.RI [ msgs ]
.RB [ \-component
.IR field ]
.RB [ \-text
.IR body ]
.RB [ \-number
.IR num " | all ]
.RB [ \-preserve " | " \-nopreserve ]
.RB [ \-Version ]
.RB [ \-help ]
.HP
.B anno
.B \-list
.RI [ +folder ]
.RI [ msgs ]
.RB [ \-component
.IR field ]
.RB [ \-number ]
.RB [ \-Version ]
.RB [ \-help ]
.ad
.SH DESCRIPTION
.B Anno
manipulates header fields or
.I annotations
in messages.
Header fields consist of a field name and an optional field body
as defined by RFC-2822.
The field name may consist of alphanumerics and dashes only.
The field body may consist of arbitrary text.
.PP
Usually, annotation is performed by the commands
.BR dist ,
.BR forw ,
and
.BR repl ,
if they are given the
.B \-anno
switch.  This allows you to keep track of your redistribution of,
forwarding of, and replies to a message.
The
.B whatnow
shell uses annoations to manage attachments, too.
.PP
By using
.BR anno
manually, you can perform arbitrary annotations of your own.
.PP
.B Anno
has three operation modes: Adding, deleting and listing of header lines.

.SS "Add mode
.PP
This is the default mode.
Historically, it had been the only mode available.
.PP
Each message selected will be annotated with the lines
.PP
.RS 5
.nf
field:\ date
field:\ body
.fi
.RE
.PP
The
.B \-component
option specifies the field name.
If no
.B \-component
.I field
is specified,
.B anno
will prompt the user for the name of field for the annotation.
.PP
The
.B \-text
option specifies the field body.
If it is missing, only the date annotation will be added.
The
.B \-nodate
switch inhibits the date annotation, leaving only the
body annotation.
.PP
By default,
.B anno
prepends the annotations to the message.
Annotations are instead appended if the
.B \-append
option is specified.
.PP
.B Anno
always does the annotation inplace in order to preserve
any links to the message.
.PP
By default,
.B anno
changes the last-accessed and last-modified times on annotate messages
to the time at which the annotation occurs.
.B Anno
preserves the original times if the
.B \-preserve
option is used.

.SS "Delete mode
.PP
The
.B \-delete
mode removes header fields from messages.
By default, the first header field whose name matches the component
is deleted.
.PP
The
.B \-component
option specifies the field name of headers to delete.
If no
.B \-component
.I field
is specified,
.B anno
will prompt the user for the name.
.PP
If the
.B \-text
option is used,
the first header field whose name matches the component and
whose body matches the text is deleted.
The text is treated as if it was a path name; if it begins with a
slash, the entire field body must match the text, otherwise just the
last path name component of the field body must match.
.PP
If the
.B \-number
option is used,
the
.IR n th
header field whose name matches the component is deleted.
The numbers are the same as those produced in
.B \-list
mode.
The special value `all' can be used for the number,
and causes all components that match the name to be deleted.
.PP
Either
.B \-text
or
.B \-number
may be specified, but not both at the same time.

.SS "List mode
.PP
The
.B \-list
mode produces a listing of the field bodies for header fields with
matching component names, one per line.
Trailing whitespace in the field body does not get printed.
If the
.B \-number
option is also used,
the listing is numbered, starting at 1.
.PP
The
.B \-component
option specifies the field name of headers to list.
If no
.B \-component
.I field
is specified,
.B anno
will prompt the user for the name.

.SH FILES
.fc ^ ~
.nf
.ta \w'%etcdir%/ExtraBigFileName  'u
^$HOME/.mmh/profile~^The user profile
.fi

.SH "PROFILE COMPONENTS"
.fc ^ ~
.nf
.ta 2.4i
.ta \w'ExtraBigProfileName  'u
^Path:~^To determine the user's mail storage
^Current\-Folder:~^To find the default current folder
.fi

.SH "SEE ALSO"
dist(1), forw(1), repl(1)

.SH DEFAULTS
.nf
.RI ` +folder "' defaults to the current folder"
.RI ` msgs "' defaults to the current message"
.RB ` \-date '
.RB ` \-nopreserve '
.fi

.SH CONTEXT
If a folder is given, it will become the current folder.  The first
message annotated will become the current message.

.SH BUGS
.PP
The
.B \-number
switch must appear after either the
.B \-list
or the
.B \-delete
mode switch, on the command line.
Otherwise it is not possible to determine if it takes an argument.