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

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