MH-DRAFT(5)                                                          [nmh-1.5]                                                         MH-DRAFT(5)

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  com-
       mands

            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(5)