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

   1 .TH REFILE %manext1% "March 18, 2013" "%nmhversion%"
   2 .\"
   3 .\" %nmhwarning%
   4 .\"
   5 .SH NAME
   6 refile \- file message in other folders
   7 .SH SYNOPSIS
   8 .HP 5
   9 .na
  10 .B refile
  11 .RI [ msgs ]
  12 .RB [ \-draft ]
  13 .RB [ \-link " | " \-nolink ]
  14 .RB [ \-preserve " | " \-nopreserve ]
  15 .RB [ \-retainsequences " | " \-noretainsequences ]
  16 .RB [ \-unlink " | " \-nounlink ]
  17 .RB [ \-src
  18 .IR +folder ]
  19 .RB [ \-file
  20 .IR file ]
  21 .RB [ \-rmmproc
  22 .IR program ]
  23 .RB [ \-normmproc ]
  24 .I +folder1
  25 \&...
  26 .RB [ \-version ]
  27 .RB [ \-help ]
  28 .ad
  29 .SH DESCRIPTION
  30 .B Refile
  31 moves (see
  32 .IR mv (1))
  33 or links (see
  34 .IR ln (1))
  35 messages
  36 from a source folder into one or more destination folders.
  37 .PP
  38 If you think of a message as a sheet of paper, this operation is not
  39 unlike filing the sheet of paper (or copies) in file cabinet folders.
  40 When a message is filed, it is linked into the destination folder(s)
  41 if possible, and is copied otherwise.  As long as the destination
  42 folders are all on the same file system, multiple filing causes little
  43 storage overhead.  This facility provides a good way to cross\-file or
  44 multiply\-index messages.  For example, if a message is received from
  45 Jones about the ARPA Map Project, the command
  46 .PP
  47 .RS 5
  48 refile\0cur\0+jones\0+Map
  49 .RE
  50 .PP
  51 would allow the message to be found in either of the two folders `jones'
  52 or `Map'.
  53 .PP
  54 You may specify the source folder using
  55 .B \-src
  56 .IR +folder .
  57 If this is
  58 not given, the current folder is used by default.  If no message is
  59 specified, then `cur' is used by default.
  60 .PP
  61 The option
  62 .B \-file
  63 .I file
  64 directs
  65 .B refile
  66 to use the specified file
  67 as the source message to be filed, rather than a message from a folder.
  68 Note that the file should be a validly formatted message, just like
  69 any other
  70 .B nmh
  71 message.  It should
  72 .B NOT
  73 be in mail drop format
  74 (to convert a file in mail drop format to a folder of
  75 .B nmh
  76 messages,
  77 see
  78 .IR inc (1)).
  79 .PP
  80 If a destination folder doesn't exist,
  81 .B refile
  82 will ask if you want
  83 to create it.  A negative response will abort the file operation.  If the
  84 standard input for
  85 .B refile
  86 is
  87 .B not
  88 a tty, then
  89 .B refile
  90 will not ask any questions and will proceed as if the user answered
  91 \*(lqyes\*(rq to all questions.
  92 .PP
  93 The option
  94 .B \-link
  95 preserves the source folder copy of the message (i.e.,
  96 it does a
  97 .IR ln (1)
  98 rather than a
  99 .IR mv (1)),
 100 whereas,
 101 .B \-nolink
 102 (the default) deletes the filed messages from the source folder.
 103 .PP
 104 Normally when a message is refiled, for each destination folder it
 105 is assigned the number which is one above the current highest message
 106 number in that folder.  Use of the
 107 .B \-preserve
 108 switch will override
 109 this message renaming, and try to preserve the number of the message.
 110 If a conflict for a particular folder occurs when using the
 111 .B \-preserve
 112 switch, then
 113 .B refile
 114 will use the next available message number
 115 which is above the message number you wish to preserve.
 116 .PP
 117 The
 118 .B \-retainsequences
 119 switch causes the memberships in sequences, except \*(lqcur\*(rq, of
 120 the refiled messages to be carried over to each destination folder.
 121 .PP
 122 If
 123 .B \-link
 124 is not specified (or
 125 .B \-nolink
 126 is specified), the filed
 127 messages will be removed from the source folder.  The default is to
 128 remove these messages by renaming them with a site-dependent prefix
 129 (usually a comma).  Such files will then need to be removed in some
 130 manner after a certain amount of time.  Many sites arrange for
 131 .B cron
 132 to remove these files once a day, so check with your
 133 system administrator.
 134 .PP
 135 Alternately, if you wish for
 136 .B refile
 137 to really remove the files
 138 representing these messages from the source folder, you can use the
 139 .B -unlink
 140 switch (not to be confused with the
 141 .B \-link
 142 switch).  But
 143 messages removed by this method cannot be later recovered.
 144 .PP
 145 If you prefer a more sophisticated method of `removing' the messages
 146 from the source folder, you can define the
 147 .B rmmproc
 148 profile
 149 component.  For example, you can add a profile component such as
 150 .PP
 151 .RS 5
 152 rmmproc:        /home/coleman/bin/rmm_msgs
 153 .RE
 154 .PP
 155 then
 156 .B refile
 157 will instead call the named program or script to
 158 handle the message files.
 159 .PP
 160 The user may specify
 161 .B \-rmmproc
 162 .I program
 163 on the command line to
 164 override this profile specification.  The
 165 .B \-normmproc
 166 option forces
 167 the message files to be deleted by renaming or unlinking them as
 168 described above.
 169 .PP
 170 The
 171 .B \-draft
 172 switch tells
 173 .B refile
 174 to file the <mh\-dir>/draft.
 175 .SH FILES
 176 .fc ^ ~
 177 .nf
 178 .ta \w'%etcdir%/ExtraBigFileName  'u
 179 ^$HOME/\&.mh\(ruprofile~^The user profile
 180 .fi
 181 .SH "PROFILE COMPONENTS"
 182 .fc ^ ~
 183 .nf
 184 .ta 2.4i
 185 .ta \w'ExtraBigProfileName  'u
 186 ^Path:~^To determine the user's nmh directory
 187 ^Current\-Folder:~^To find the default current folder
 188 ^Folder\-Protect:~^To set mode when creating a new folder
 189 ^rmmproc:~^Program to delete the message
 190 .fi
 191 .SH "SEE ALSO"
 192 .IR folder (1),
 193 .IR mh-sequence (5),
 194 .IR rmf (1),
 195 .IR rmm (1)
 196 .SH DEFAULTS
 197 .nf
 198 .RB ` "\-src\ +folder" "' defaults to the current folder"
 199 .RB ` msgs "' defaults to cur"
 200 .RB ` \-nolink '
 201 .RB ` \-nounlink '
 202 .RB ` \-nopreserve '
 203 .RB ` \-noretainsequences '
 204 .fi
 205 .SH CONTEXT
 206 If
 207 .B \-src
 208 .I +folder
 209 is given, it will become the current folder.
 210 If neither
 211 .B \-link
 212 nor `all' is specified, the current message in the
 213 source folder will be set to the last message specified; otherwise, the
 214 current message won't be changed.
 215 .PP
 216 If the \*(lqPrevious\-Sequence\*(rq profile entry is set, in addition to defining
 217 the named sequences from the source folder,
 218 .B refile
 219 will also define
 220 those sequences for the destination folders.  See
 221 .B mh\-sequence (5)
 222 for information concerning the previous sequence.
 223 .SH BUGS
 224 Since
 225 .B refile
 226 and
 227 .B rmm
 228 use your
 229 .I rmmproc
 230 to delete the message,
 231 the
 232 .I rmmproc
 233 must
 234 .B NOT
 235 call
 236 .B refile
 237 or
 238 .B rmm
 239 without specifying
 240 .BR \-normmproc ,
 241 or you will create an infinite loop.