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 .RB [ \-help ]
  12 .RB [ \-version ]
  13 .RI [ msgs ]
  14 .RB [ \-draft ]
  15 .RB [ \-link " | " \-nolink ]
  16 .RB [ \-preserve " | " \-nopreserve ]
  17 .RB [ \-retainsequences " | " \-noretainsequences ]
  18 .RB [ \-unlink " | " \-nounlink ]
  19 .RB [ \-src
  20 .IR +folder ]
  21 .RB [ \-file
  22 .IR file ]
  23 .RB [ \-rmmproc
  24 .IR program ]
  25 .RB [ \-normmproc ]
  26 .I +folder1
  27 \&...
  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 As message sequences are folder-specific,
 118 moving the message from the source folder removes it from all its
 119 sequences in that folder.
 120 .B \-retainsequences
 121 adds it to those same sequences in the destination folder,
 122 creating any that don't exist.
 123 This adding does not apply for the \*(lqcur\*(rq sequence.
 124 .PP
 125 If
 126 .B \-link
 127 is not specified (or
 128 .B \-nolink
 129 is specified), the filed
 130 messages will be removed from the source folder.  The default is to
 131 remove these messages by renaming them with a site-dependent prefix
 132 (usually a comma).  Such files will then need to be removed in some
 133 manner after a certain amount of time.  Many sites arrange for
 134 .B cron
 135 to remove these files once a day, so check with your
 136 system administrator.
 137 .PP
 138 Alternately, if you wish for
 139 .B refile
 140 to really remove the files
 141 representing these messages from the source folder, you can use the
 142 .B -unlink
 143 switch (not to be confused with the
 144 .B \-link
 145 switch).  But
 146 messages removed by this method cannot be later recovered.
 147 .PP
 148 If you prefer a more sophisticated method of `removing' the messages
 149 from the source folder, you can define the
 150 .B rmmproc
 151 profile
 152 component.  For example, you can add a profile component such as
 153 .PP
 154 .RS 5
 155 rmmproc:        /home/coleman/bin/rmm_msgs
 156 .RE
 157 .PP
 158 then
 159 .B refile
 160 will instead call the named program or script to
 161 handle the message files.
 162 .PP
 163 The user may specify
 164 .B \-rmmproc
 165 .I program
 166 on the command line to
 167 override this profile specification.  The
 168 .B \-normmproc
 169 option forces
 170 the message files to be deleted by renaming or unlinking them as
 171 described above.
 172 .PP
 173 The
 174 .B \-draft
 175 switch tells
 176 .B refile
 177 to file the <mh\-dir>/draft.
 178 .SH FILES
 179 .fc ^ ~
 180 .nf
 181 .ta \w'%nmhetcdir%/ExtraBigFileName  'u
 182 ^$HOME/\&.mh\(ruprofile~^The user profile
 183 .fi
 184 .SH "PROFILE COMPONENTS"
 185 .fc ^ ~
 186 .nf
 187 .ta 2.4i
 188 .ta \w'ExtraBigProfileName  'u
 189 ^Path:~^To determine the user's nmh directory
 190 ^Current\-Folder:~^To find the default current folder
 191 ^Folder\-Protect:~^To set mode when creating a new folder
 192 ^rmmproc:~^Program to delete the message
 193 .fi
 194 .SH "SEE ALSO"
 195 .IR folder (1),
 196 .IR mh-sequence (5),
 197 .IR rmf (1),
 198 .IR rmm (1)
 199 .SH DEFAULTS
 200 .nf
 201 .RB ` "\-src\ +folder" "' defaults to the current folder"
 202 .RB ` msgs "' defaults to cur"
 203 .RB ` \-nolink '
 204 .RB ` \-nounlink '
 205 .RB ` \-nopreserve '
 206 .RB ` \-noretainsequences '
 207 .fi
 208 .SH CONTEXT
 209 If
 210 .B \-src
 211 .I +folder
 212 is given, it will become the current folder.
 213 If neither
 214 .B \-link
 215 nor `all' is specified, the current message in the
 216 source folder will be set to the last message specified; otherwise, the
 217 current message won't be changed.
 218 .PP
 219 If the \*(lqPrevious\-Sequence\*(rq profile entry is set, in addition to defining
 220 the named sequences from the source folder,
 221 .B refile
 222 will also define
 223 those sequences for the destination folders.  See
 224 .B mh\-sequence (5)
 225 for information concerning the previous sequence.
 226 .SH BUGS
 227 Since
 228 .B refile
 229 and
 230 .B rmm
 231 use your
 232 .I rmmproc
 233 to delete the message,
 234 the
 235 .I rmmproc
 236 must
 237 .B NOT
 238 call
 239 .B refile
 240 or
 241 .B rmm
 242 without specifying
 243 .BR \-normmproc ,
 244 or you will create an infinite loop.