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