NAME

       mh-draft - draft folder facility for nmh message system

SYNOPSIS

       any nmh command

DESCRIPTION

       There are a number of interesting advanced facilities for the composition of outgoing mail.

   The Draft Folder
       The  comp,  dist,  forw,  repl,  and whom commands have two additional switches, -draftfolder +folder and
       -draftmessage msg which allow you to manipulate the various draft messages you are composing.

       If -draftfolder +folder is used, these commands  are  directed  to  construct  a  draft  message  in  the
       indicated  folder.   (The  “Draft-Folder” profile entry may be used to declare a default draft folder for
       use with comp, dist, forw, repl, and whom ).

       If the swith -draftmessage msg is given, the  specified  draft  is  used  to  compose  the  message.   If
       -draftmessage  msg  is  not  used,  then the draft defaults to `new' (create a new draft) unless the user
       invokes comp with -use, in which case the default is `cur'.

       Hence, the user may have several message compositions in progress simultaneously.  Now, all  of  the  nmh
       tools  are  available  on  each of the user's message drafts (e.g.  show, scan, pick, and so on).  If the
       folder does not exist, the user is asked if it should be created (just like with refile).  Also, the last
       draft message the user was composing is known as `cur' in the draft folder.

       Furthermore, the send command has these switches as well.  Hence, from the shell, the user can  send  off
       whatever  drafts  desired using the standard nmh `msgs' convention with -draftmessage msgs.  If no `msgs'
       are given, it defaults to `cur'.

       In addition, all five programs have  a  -nodraftfolder  switch,  which  undoes  the  last  occurrence  of
       -draftfolder folder (useful if the latter occurs in the user's nmh profile).

       If  the user does not give the -draftfolder +folder switch, then all these commands act “normally”.  Note
       that the -draft switch to send and show still refers to  the  file  called  `draft'  in  the  user's  nmh
       directory.   In  the interests of economy of expression, when using comp or send, the user needn't prefix
       the draft `msg' or `msgs' with -draftmessage.   Both  of  these  commands  accept  a  `file'  or  `files'
       argument,  and  they  will, if given -draftfolder +folder treat these arguments as `msg' or `msgs'. (This
       may appear to be inconsistent, at first, but it saves a lot of typing) Hence,

              send -draftfolder +drafts first

       is the same as

              send -draftfolder +drafts -draftmessage first

       To make all this a bit more clear, here are some examples.  Let's assume that the following  entries  are
       in the nmh profile:

            Draft-Folder: +drafts
            sendf: -draftfolder +drafts

       Furthermore,  let's assume that the program sendf is a (symbolic) link in the user's $HOME/bin/ directory
       to send.  Then, any of the commands

            comp
            dist
            forw
            repl

       constructs the message draft in the `draft' folder using the `new'  message  number.   Furthermore,  they
       each  define  `cur'  in this folder to be that message draft.  If the user were to use the quit option at
       `What now?' level, then later on, if no other draft composition was done, the draft could  be  sent  with
       simply

            sendf

       Or, if more editing was required, the draft could be edited with

            comp -use

       Instead,  if  other  drafts  had  been composed in the meantime, so that this message draft was no longer
       known as `cur' in the `draft' folder, then the user could scan the folder to see which message  draft  in
       the  folder  should be used for editing or sending.  Clever users could even employ a back-quoted pick to
       do the work:

            comp -use `pick +drafts -to nmh-workers`

       or

            sendf `pick +drafts -to nmh-workers`

       Note that in the comp example, the output from pick must resolve to a single message draft (it  makes  no
       sense  to talk about composing two or more drafts with one invocation of comp).  In contrast, in the send
       example, as many message drafts as desired can appear, since send doesn't  mind  sending  more  than  one
       draft at a time.

       Note  that  the  argument  -draftfolder +folder is not included in the profile entry for send, since when
       comp, et. al., invoke send directly, they supply send with the UNIX pathname of the  message  draft,  and
       not a -draftmessage msg argument. As far as send is concerned, a draft folder is not being used.

       It  is  important  to  realize  that nmh treats the draft folder like a standard nmh folder in nearly all
       respects.  There are two exceptions:

       First, under no circumstancs will the -draftfolder folder switch cause the named  folder  to  become  the
       current folder.

       Obviously, if the folder appeared in the context of a standard +folder argument to an nmh program, as in

            scan +drafts

       it might become the current folder, depending on the context changes of the nmh program in question.

       Second,  although  conceptually  send  deletes  the  `msgs'  named  in the draft folder, it does not call
       delete-prog to perform the deletion.

   What Happens if the Draft Exists
       When the comp, dist, forw, and repl commands are invoked and the  draft  you  indicated  already  exists,
       these programs will prompt the user for a reponse directing the program's action.  The prompt is

            Draft ``/home/foobar/nmhbox/draft'' exists (xx bytes).
            Disposition?

       The appropriate responses and their meanings are:

            replace - deletes the draft and starts afresh
            list    - lists the draft
            refile  - files the draft into a folder and starts afresh
            quit    - leaves the draft intact and exits

       In  addition,  if  you  specified  -draftfolder  folder  to  the command, then one other response will be
       accepted:

            new     - finds a new draft

       just as if -draftmessage new had been given.  Finally, the comp command will accept one more response:

            use     - re-uses the draft

       just as if -use had been given.

CONTEXT

       None

MH.6.8                                            11 June 2012                                     MH-DRAFT(5mh)