Removed documentation of obsolete WHATNOW configuration option and
[mmh] / man / anno.man
1 .\"
2 .\" %nmhwarning%
3 .\"
4 .TH ANNO %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
5 .SH NAME
6 anno \- annotate messages
7 .SH SYNOPSIS
8 .HP 5
9 .na
10 .B anno
11 .RI [ +folder ]
12 .RI [ msgs ]
13 .RB [ \-component
14 .IR field ]
15 .RB [ \-inplace " | " \-noinplace ]
16 .RB [ \-date " | " \-nodate ]
17 .RB [ \-draft ]
18 .RB [ \-append ]
19 .RB [ \-list ]
20 .RB [ \-delete ]
21 .RB [ \-number
22 .IR [ num|all ]]
23 .RB [ \-preserve " | " \-nopreserve ]
24 .RB [ \-version ]
25 .RB [ \-help ]
26 .RB [ \-text
27 .IR body ]
28 .ad
29 .SH DESCRIPTION
30 .B Anno
31 manipulates header fields or
32 .I annotations
33 in messages.
34 Header fields consist of a field name and an optional field body
35 as defined by RFC-2822.
36 The
37 .B -component
38 option specifies the field name, and the
39 .B -text
40 option specifies the field body.
41 .PP
42 The messages are either the
43 .I msgs
44 in the named folder, or the draft if invoked with the
45 .B -draft
46 option.
47 .PP
48 Usually, annotation is performed by the commands
49 .BR dist ,
50 .BR forw ,
51 and
52 .BR repl ,
53 if they are given the
54 .B \-anno
55 switch.  This allows you to keep track of your distribution of,
56 forwarding of, and replies to a message.
57 .PP
58 By using
59 .BR anno ,
60 you can perform arbitrary annotations of your own.
61 Each message selected will be annotated with the lines
62 .PP
63     field:\ date
64     field:\ body
65 .PP
66 The
67 .B \-nodate
68 switch inhibits the date annotation, leaving only the
69 body annotation.
70 .PP
71 By default,
72 .B anno
73 prepends the annotations to the message.
74 Annotations are instead appended if the
75 .B -append
76 option is specified.
77 .PP
78 If a
79 .B \-component
80 .I field
81 is not specified when
82 .B anno
83 is invoked,
84 .B anno
85 will prompt the user for the name of field for the annotation.
86 .PP
87 The field specified must be a valid 2822-style message field name,
88 which means that it may only consist of alphanumerics and dashes,
89 The body specified is arbitrary text.
90 .PP
91 Normally
92 .B anno
93 does the annotation inplace in order to preserve
94 any links to the message.  You may change this by using the
95 .B \-noinplace
96 switch.
97 .PP
98 The
99 .B -list
100 option produces a listing of the field bodies for header fields with
101 names matching the specified component, one per line.
102 The listing is numbered, starting at 1, if the
103 .B -number
104 option is also used.
105 A tab character separates the number and the field body.
106 The field body is treated as if it is a file name, and only the final
107 path name component is listed.
108 The complete field body is listed if the
109 .B -text
110 option is used, the contents of the text are ignored.
111 .PP
112 The
113 .B -delete
114 option removes header fields from messages.
115 The first header field whose name matches the component is deleted if
116 no other options are specified.
117 If the
118 .B -text
119 option is used in conjunction with the
120 .B -delete
121 option, the first header field whose name matches the component and
122 whose body matches the text is deleted.
123 The text is treated as if it was a file name; if it begins with a
124 slash, the entire field body must match the text, otherwise just the
125 last path name component of the field body must match.
126 If the
127 .B -number
128 option is used in conjuction with the
129 .B -delete
130 option, header field
131 .I num
132 whose name matches the component is deleted.
133 The number matches that which is produced by the
134 .B -list
135 option.
136 The special value
137 .B all
138 can be used for the number, and causes all components that match the
139 name to be deleted.
140 .PP
141 By default,
142 .B anno
143 changes the last-accessed and last-modified times on annotate messages
144 to the time at which the annotation occurs.
145 .B Anno
146 preserves the original times if the
147 .B -preserve
148 option is used.
149 A matching
150 .B -nopreserve
151 option exists that allows time preservation to be turned off if enabled
152 in the profile.
153 .SH FILES
154 .fc ^ ~
155 .nf
156 .ta \w'%etcdir%/ExtraBigFileName  'u
157 ^$HOME/\&.mh\(ruprofile~^The user profile
158 .fi
159
160 .SH "PROFILE COMPONENTS"
161 .fc ^ ~
162 .nf
163 .ta 2.4i
164 .ta \w'ExtraBigProfileName  'u
165 ^Path:~^To determine the user's nmh directory
166 ^Current\-Folder:~^To find the default current folder
167 .fi
168
169 .SH "SEE ALSO"
170 dist(1), forw(1), repl(1)
171
172 .SH DEFAULTS
173 .nf
174 .RI ` +folder "' defaults to the current folder"
175 .RI ` msgs "' defaults to cur"
176 .RB ` \-inplace '
177 .RB ` \-date '
178 .fi
179
180 .SH CONTEXT
181 If a folder is given, it will become the current folder.  The first
182 message annotated will become the current message.