.RI [ msgs ]
.RB [ \-component
.IR field ]
-.RB [ \-date " | " \-nodate ]
+.RB [ \-text
+.IR body ]
.RB [ \-append ]
-.RB [ \-list ]
-.RB [ \-delete ]
-.RB [ \-number
-.IR [ num|all ]]
+.RB [ \-date " | " \-nodate ]
.RB [ \-preserve " | " \-nopreserve ]
-.RB [ \-version ]
+.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
in messages.
Header fields consist of a field name and an optional field body
as defined by RFC-2822.
-The
-.B -component
-option specifies the field name, and the
-.B -text
-option specifies the field body.
-.PP
-The messages are the
-.I msgs
-in the named folder.
+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 repl ,
if they are given the
.B \-anno
-switch. This allows you to keep track of your distribution of,
+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 ,
-you can perform arbitrary annotations of your own.
+.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
- field:\ date
- field:\ body
+.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.
.B anno
prepends the annotations to the message.
Annotations are instead appended if the
-.B -append
+.B \-append
option is specified.
.PP
-If a
-.B \-component
-.I field
-is not specified when
-.B anno
-is invoked,
-.B anno
-will prompt the user for the name of field for the annotation.
-.PP
-The field specified must be a valid 2822-style message field name,
-which means that it may only consist of alphanumerics and dashes,
-The body specified is arbitrary text.
-.PP
-.B anno
+.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 -list
-option produces a listing of the field bodies for header fields with
-names matching the specified component, one per line.
-The listing is numbered, starting at 1, if the
-.B -number
-option is also used.
-A tab character separates the number and the field body.
-The field body is treated as if it is a file name, and only the final
-path name component is listed.
-The complete field body is listed if the
-.B -text
-option is used, the contents of the text are ignored.
+.B \-delete
+mode removes header fields from messages.
+By default, the first header field whose name matches the component
+is deleted.
.PP
The
-.B -delete
-option removes header fields from messages.
-The first header field whose name matches the component is deleted if
-no other options are specified.
+.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 in conjunction with the
-.B -delete
-option, the first header field whose name matches the component and
+.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 file name; if it begins with a
+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 in conjuction with the
-.B -delete
-option, header field
-.I num
-whose name matches the component is deleted.
-The number matches that which is produced by the
-.B -list
-option.
-The special value
-.B all
-can be used for the number, and causes all components that match the
-name to be deleted.
+.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
-By default,
+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.
+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
-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.
-A matching
-.B -nopreserve
-option exists that allows time preservation to be turned off if enabled
-in the profile.
+will prompt the user for the name.
+
.SH FILES
.fc ^ ~
.nf
.RI ` +folder "' defaults to the current folder"
.RI ` msgs "' defaults to cur"
.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.
projects / mmh / blobdiff