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