diplodocus.org Git - nmh/blob - man/anno.man

   1 .TH ANNO %manext1% "December 7, 2005" "%nmhversion%"
   2 .\"
   3 .\" %nmhwarning%
   4 .\"
   5 .SH NAME
   6 anno \- annotate messages
   7 .SH SYNOPSIS
   8 .HP 5
   9 .na
  10 .B anno
  11 .RB [ \-help ]
  12 .RB [ \-version ]
  13 .RI [ +folder ]
  14 .RI [ msgs ]
  15 .RB [ \-component
  16 .IR field ]
  17 .RB [ \-inplace " | " \-noinplace ]
  18 .RB [ \-date " | " \-nodate ]
  19 .RB [ \-draft ]
  20 .RB [ \-append ]
  21 .RB [ \-list ]
  22 .RB [ \-delete ]
  23 .RB [ \-number
  24 .IR [ num|all ]]
  25 .RB [ \-preserve " | " \-nopreserve ]
  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 switch specifies the field name, and the
  39 .B -text
  40 switch 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 switch.
  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 switch 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 a field name.
  86 .PP
  87 The field specified must be a valid RFC 2822-style message field name,
  88 consisting only of alphanumeric characters and dashes.
  89 The body may consist of arbitrary text.
  90 .PP
  91 Normally
  92 .B anno
  93 does the annotation in place 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 switch 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 switch 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 switch is used, the contents of the text are ignored.
 111 .PP
 112 The
 113 .B -delete
 114 switch 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 switch is used in conjunction with the
 120 .B -delete
 121 switch, 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 switch is used in conjunction with the
 129 .B -delete
 130 switch, 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 switch.
 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 annotated messages
 144 to the time of the annotation.
 145 .B anno
 146 preserves the original times if the
 147 .B -preserve
 148 switch is used.
 149 A matching
 150 .B -nopreserve
 151 switch allows time preservation to be turned off, if enabled
 152 in the profile.
 153 .SH FILES
 154 .TP 20
 155 $HOME/\&.mh\(ruprofile
 156 The user's profile.
 157 .SH "PROFILE COMPONENTS"
 158 .PD 0
 159 .TP 20
 160 Path:
 161 To determine the user's nmh directory.
 162 .TP
 163 Current\-Folder:
 164 To find the default current folder.
 165 .PD
 166 .SH "SEE ALSO"
 167 .IR dist (1),
 168 .IR forw (1),
 169 .IR repl (1)
 170 .SH DEFAULTS
 171 .PD 0
 172 .TP 20
 173 +folder
 174 The current folder.
 175 .TP
 176 msgs
 177 The current message.
 178 .TP
 179 -inplace
 180 .TP
 181 -date
 182 .PD
 183 .SH CONTEXT
 184 If a folder is given, it will become the current folder.  The first
 185 message annotated will become the current message.