Path: utzoo!utgpu!jarvis.csri.toronto.edu!rutgers!tut.cis.ohio-state.edu!UUNET.UU.NET!talos!kjones
From: talos!kjones@UUNET.UU.NET (Kyle Jones)
Newsgroups: gnu.emacs
Subject: VM - a mail reader for GNU Emacs (3 of 3)
Message-ID: <8905232132.AA24632@talos.uucp>
Date: 23 May 89 21:32:35 GMT
Sender: daemon@tut.cis.ohio-state.edu
Distribution: gnu
Organization: GNUs Not Usenet
Lines: 1030

#!/bin/sh
# shar:	Shell Archiver  (v1.22)
#
#	Run the following text with /bin/sh to create:
#	  vm-license.el
#	  vm.texinfo
#	  COPYING
#	  README
#
sed 's/^X//' << 'SHAR_EOF' > vm-license.el &&
X;;; Code to show VM's warranty and copying restrictions
X;;; Copyright (C) 1989 Kyle E. Jones
X;;;
X;;; This program is free software; you can redistribute it and/or modify
X;;; it under the terms of the GNU General Public License as published by
X;;; the Free Software Foundation; either version 1, or (at your option)
X;;; any later version.
X;;;
X;;; This program is distributed in the hope that it will be useful,
X;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
X;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
X;;; GNU General Public License for more details.
X;;;
X;;; You should have received a copy of the GNU General Public License
X;;; along with this program; if not, write to the Free Software
X;;; Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
X
X(require 'vm)
X
X(defconst vm-license-buffer-name "*GNU General Public License*")
X
X(defconst vm-license-string
X"		    GNU GENERAL PUBLIC LICENSE
X		     Version 1, February 1989
X
X Copyright (C) 1989 Free Software Foundation, Inc.
X                    675 Mass Ave, Cambridge, MA 02139, USA
X Everyone is permitted to copy and distribute verbatim copies
X of this license document, but changing it is not allowed.
X
X			    Preamble
X
X  The license agreements of most software companies try to keep users
Xat the mercy of those companies.  By contrast, our General Public
XLicense is intended to guarantee your freedom to share and change free
Xsoftware--to make sure the software is free for all its users.  The
XGeneral Public License applies to the Free Software Foundation's
Xsoftware and to any other program whose authors commit to using it.
XYou can use it for your programs, too.
X
X  When we speak of free software, we are referring to freedom, not
Xprice.  Specifically, the General Public License is designed to make
Xsure that you have the freedom to give away or sell copies of free
Xsoftware, that you receive source code or can get it if you want it,
Xthat you can change the software or use pieces of it in new free
Xprograms; and that you know you can do these things.
X
X  To protect your rights, we need to make restrictions that forbid
Xanyone to deny you these rights or to ask you to surrender the rights.
XThese restrictions translate to certain responsibilities for you if you
Xdistribute copies of the software, or if you modify it.
X
X  For example, if you distribute copies of a such a program, whether
Xgratis or for a fee, you must give the recipients all the rights that
Xyou have.  You must make sure that they, too, receive or can get the
Xsource code.  And you must tell them their rights.
X
X  We protect your rights with two steps: (1) copyright the software, and
X(2) offer you this license which gives you legal permission to copy,
Xdistribute and/or modify the software.
X
X  Also, for each author's protection and ours, we want to make certain
Xthat everyone understands that there is no warranty for this free
Xsoftware.  If the software is modified by someone else and passed on, we
Xwant its recipients to know that what they have is not the original, so
Xthat any problems introduced by others will not reflect on the original
Xauthors' reputations.
X
X  The precise terms and conditions for copying, distribution and
Xmodification follow.
X
X		    GNU GENERAL PUBLIC LICENSE
X   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
X
X  0. This License Agreement applies to any program or other work which
Xcontains a notice placed by the copyright holder saying it may be
Xdistributed under the terms of this General Public License.  The
X\"Program\", below, refers to any such program or work, and a \"work based
Xon the Program\" means either the Program or any work containing the
XProgram or a portion of it, either verbatim or with modifications.  Each
Xlicensee is addressed as \"you\".
X
X  1. You may copy and distribute verbatim copies of the Program's source
Xcode as you receive it, in any medium, provided that you conspicuously and
Xappropriately publish on each copy an appropriate copyright notice and
Xdisclaimer of warranty; keep intact all the notices that refer to this
XGeneral Public License and to the absence of any warranty; and give any
Xother recipients of the Program a copy of this General Public License
Xalong with the Program.  You may charge a fee for the physical act of
Xtransferring a copy.
X
X  2. You may modify your copy or copies of the Program or any portion of
Xit, and copy and distribute such modifications under the terms of Paragraph
X1 above, provided that you also do the following:
X
X    a) cause the modified files to carry prominent notices stating that
X    you changed the files and the date of any change; and
X
X    b) cause the whole of any work that you distribute or publish, that
X    in whole or in part contains the Program or any part thereof, either
X    with or without modifications, to be licensed at no charge to all
X    third parties under the terms of this General Public License (except
X    that you may choose to grant warranty protection to some or all
X    third parties, at your option).
X
X    c) If the modified program normally reads commands interactively when
X    run, you must cause it, when started running for such interactive use
X    in the simplest and most usual way, to print or display an
X    announcement including an appropriate copyright notice and a notice
X    that there is no warranty (or else, saying that you provide a
X    warranty) and that users may redistribute the program under these
X    conditions, and telling the user how to view a copy of this General
X    Public License.
X
X    d) You may charge a fee for the physical act of transferring a
X    copy, and you may at your option offer warranty protection in
X    exchange for a fee.
X
XMere aggregation of another independent work with the Program (or its
Xderivative) on a volume of a storage or distribution medium does not bring
Xthe other work under the scope of these terms.
X
X  3. You may copy and distribute the Program (or a portion or derivative of
Xit, under Paragraph 2) in object code or executable form under the terms of
XParagraphs 1 and 2 above provided that you also do one of the following:
X
X    a) accompany it with the complete corresponding machine-readable
X    source code, which must be distributed under the terms of
X    Paragraphs 1 and 2 above; or,
X
X    b) accompany it with a written offer, valid for at least three
X    years, to give any third party free (except for a nominal charge
X    for the cost of distribution) a complete machine-readable copy of the
X    corresponding source code, to be distributed under the terms of
X    Paragraphs 1 and 2 above; or,
X
X    c) accompany it with the information you received as to where the
X    corresponding source code may be obtained.  (This alternative is
X    allowed only for noncommercial distribution and only if you
X    received the program in object code or executable form alone.)
X
XSource code for a work means the preferred form of the work for making
Xmodifications to it.  For an executable file, complete source code means
Xall the source code for all modules it contains; but, as a special
Xexception, it need not include source code for modules which are standard
Xlibraries that accompany the operating system on which the executable
Xfile runs, or for standard header files or definitions files that
Xaccompany that operating system.
X
X  4. You may not copy, modify, sublicense, distribute or transfer the
XProgram except as expressly provided under this General Public License.
XAny attempt otherwise to copy, modify, sublicense, distribute or transfer
Xthe Program is void, and will automatically terminate your rights to use
Xthe Program under this License.  However, parties who have received
Xcopies, or rights to use copies, from you under this General Public
XLicense will not have their licenses terminated so long as such parties
Xremain in full compliance.
X
X  5. By copying, distributing or modifying the Program (or any work based
Xon the Program) you indicate your acceptance of this license to do so,
Xand all its terms and conditions.
X
X  6. Each time you redistribute the Program (or any work based on the
XProgram), the recipient automatically receives a license from the original
Xlicensor to copy, distribute or modify the Program subject to these
Xterms and conditions.  You may not impose any further restrictions on the
Xrecipients' exercise of the rights granted herein.
X
X  7. The Free Software Foundation may publish revised and/or new versions
Xof the General Public License from time to time.  Such new versions will
Xbe similar in spirit to the present version, but may differ in detail to
Xaddress new problems or concerns.
X
XEach version is given a distinguishing version number.  If the Program
Xspecifies a version number of the license which applies to it and \"any
Xlater version\", you have the option of following the terms and conditions
Xeither of that version or of any later version published by the Free
XSoftware Foundation.  If the Program does not specify a version number of
Xthe license, you may choose any version ever published by the Free Software
XFoundation.
X
X  8. If you wish to incorporate parts of the Program into other free
Xprograms whose distribution conditions are different, write to the author
Xto ask for permission.  For software which is copyrighted by the Free
XSoftware Foundation, write to the Free Software Foundation; we sometimes
Xmake exceptions for this.  Our decision will be guided by the two goals
Xof preserving the free status of all derivatives of our free software and
Xof promoting the sharing and reuse of software generally.
X
X			    NO WARRANTY
X
X  9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
XFOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
XOTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
XPROVIDE THE PROGRAM \"AS IS\" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
XOR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
XMERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
XTO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
XPROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
XREPAIR OR CORRECTION.
X
X  10. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
XWILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
XREDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
XINCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
XOUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
XTO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
XYOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
XPROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
XPOSSIBILITY OF SUCH DAMAGES.
X
X		     END OF TERMS AND CONDITIONS
X")
X
X(defun vm-show-copying-restrictions (&optional warranty)
X  "Display the GNU General Public License."
X  (interactive)
X  (if (get-buffer vm-license-buffer-name)
X      (progn
X	(if (get-buffer-window (get-buffer vm-license-buffer-name))
X	    (select-window (get-buffer-window
X			    (get-buffer vm-license-buffer-name)))
X	  (switch-to-buffer vm-license-buffer-name t))
X	(goto-char (point-min))
X	(if warranty
X	    (progn
X	      (search-forward "NO WARRANTY\n" nil t)
X	      (forward-line -1)
X	      (set-window-start (selected-window) (point)))))
X    (save-excursion
X      (switch-to-buffer (get-buffer-create vm-license-buffer-name) t)
X      (insert vm-license-string)
X      (goto-char (point-min))
X      (if warranty
X	  (progn
X	    (search-forward "NO WARRANTY\n" nil t)
X	    (forward-line -1)
X	    (set-window-start (selected-window) (point))))
X      (set-buffer-modified-p nil))
X    ;; This goes into a recursive edit!
X    (view-buffer vm-license-buffer-name)
X    (condition-case () (kill-buffer vm-license-buffer-name) (error nil))))
X
X(defun vm-show-no-warranty ()
X  "Display \"NO WARRANTY\" section of the GNU General Public License."
X  (interactive)
X  (vm-show-copying-restrictions t))
SHAR_EOF
chmod 0664 vm-license.el || echo "restore of vm-license.el fails"
sed 's/^X//' << 'SHAR_EOF' > vm.texinfo &&
X@comment -*-Texinfo-*-
X@setfilename vm.info
X@ignore
XThis file documents the VM mail reader.
X
XCopyright (C) 1989 Kyle E. Jones
X
XPermission is granted to make and distribute verbatim copies of
Xthis manual provided the copyright notice and this permission notice
Xare preserved on all copies.
X@end ignore
X
X@node Top, Introduction,, (DIR)
X
XThis manual documents the VM mail reader.  It is divided into the
Xfollowing chapters.
X
X@menu
X* Introduction::	Overview of the VM interface.
X* Starting Up::		What happens when your start VM.
X* Selecting Messages::	How to select messages for reading.
X* Sending Messages::	How to send messages from within VM.
X* Saving Messages::	How to save messages.
X* Deleting Messages::	How to delete, undelete and expunge messages
X* Undoing::		How to undo changes to message attributes.
X* Grouping Messages::	How to make VM present messages
X* Reading Digests::	How to read digests under VM.
X* Summaries::		How to view and customize the summary of a folder.
X* Miscellaneous::	Various customization variables undescribed elsewhere.
X@end menu
X
X@node Introduction, Starting Up, Top, Top
X@chapter Introduction
X
XVM (View Mail) is an Emacs subsystem that allows UNIX mail to be read
Xand disposed of within Emacs.  Commands exist to do the normal things
Xexpected of a mail user agent, such as generating replies, saving
Xmessages to folders, deleting messages and so on.  There are other more
Xadvanced commands that do tasks like bursting and creating digests,
Xmessage forwarding, and organizing message presentation according to
Xvarious criteria.
X
XTo invoke VM simply type @kbd{M-x vm}.  VM gathers any mail that has
Xarrived in your system mailbox and appends it to a file known as your
X@dfn{primary inbox}, and visits that file for reading.  A file visited
Xfor reading by VM is called the @dfn{current folder}.@refill
X
XIf there are any messages in the primary inbox, VM selects the first new
Xor unread message, and previews it.  @dfn{Previewing} is VM's way of
Xshowing you part of message and allowing you to decide whether you want
Xto read it.  @xref{Previewing}.  By default VM shows you the message's
Xsender, recipient, subject and date headers.  Typing @key{SPC}
X(@code{vm-scroll-forward}) exposes the body of the message and marks the
Xmessage as read.  Subsequent @key{SPC}'s scroll forward through the
Xmessage, @kbd{b} scrolls backward.  When you reach the end of a message,
Xtyping a @key{SPC} or @kbd{n} moves you forward to preview the next
Xmessage.@refill
X
XIf you do not want to read a message that's being previewed, just type
X@kbd{n} and VM will move on to the next message (if there is one).
X@xref{Selecting Messages}.@refill
X
XTo save a message to a mail folder use @kbd{s} (@code{vm-save-message}).
XVM will prompt you for the folder name in the minibuffer.
X@xref{Saving Messages}.@refill
X
XMessages are deleted by typing @key{d} (@code{vm-delete-message}) while
Xpreviewing or reading them.  The message is not deleted right away; it
Xis simply marked for deletion.  If you change your mind about deleting a
Xmessage just select it and type @kbd{u} (@code{vm-undelete-message}),
Xand the message will be undeleted.  @xref{Deleting Messages}.  The
Xactual removal of deleted messages from the current folder is called
X@dfn{expunging} and it is accomplished by typing @kbd{#} (@code{vm-expunge-folder}).  The message is still present in the on-disk
Xversion of the folder until the folder is saved.  @xref{Saving Folders}.@refill
X
XTyping @kbd{h} (@code{vm-summarize}) causes VM to pop up a window
Xcontaining a summary of contents of the current folder.  Each message is
Xsumamrized, one per line, by message number listing its author, date
Xsent, line and byte count, and subject.  Also various letters appear
Xbeside the message number to indicate that a message is new, unread,
Xmarked for deletion, etc.  An arrow @samp{->} appears to the left of the
Xline summarizing the current messge.  The summary format is user
Xconfigurable, @pxref{Summaries}.@refill
X
XWhen you are finished reading mail the current folder must be saved, so
Xthat the next time the folder is visited VM will know which message have
Xbeen already read, replied to and so on.  Typing @kbd{S}
X(@code{vm-save-folder}) expunges all deleted message and saves the
Xfolder.  @kbd{C-x C-s} saves the folder without expunging deleted
Xmessages but the message are still marked deleted.  The next time the
Xfolder is visited these messages will still be marked for deletion.@refill
X
XTo quit VM you can type @kbd{q} (@code{vm-quit}) or @kbd{x}
X(@code{vm-quit-no-change}).  Typing @kbd{q} expunges and saves the
Xcurrent folder before quitting.  If there were any changes to save,
X@kbd{q} also changes any messages marked new to be marked unread, before
Xsaving.  The @kbd{x} command quits VM without expunging, saving or
Xotherwise modifying the current folder.  Quitting is not required; you
Xcan simply switch to another Emacs buffer when you've finished reading
Xmail.@refill
X
X@node Starting Up, Selecting Messages, Introduction, Top
X@chapter Starting Up
X
XThere are two ways to start VM: @kbd{M-x vm} and @kbd{M-x vm-visit-folder}.
X
X@kbd{M-x vm} causes VM to gather any mail present in your system mailbox
Xand append it to a file known as your @dfn{primary inbox}, creating
Xthis file if necessary.  The default name of this file is
X@file{~/INBOX}, but VM will use whatever file is named by the variable
X@code{vm-primary-inbox}.@refill
X
XVM transfers the mail from the system mailbox to the primary inbox via a
Xtemporary file known as the @dfn{crash box}.  The variable
X@code{vm-crash-box} names the crash box file.  VM first copies the mail
Xto the crash box, deletes the system mailbox, merges the crash box
Xcontents into the primary inbox, and then deletes the crash box.  If the
Xsystem or Emacs should crash in the midst of this transfer, any message
Xno present in the primary inbox will be either in the system mailbox or
Xthe crash box.  Some messages may be duplicated but no mail will be
Xlost.@refill
X
XIf the file named by @code{vm-crash-box} already exists when VM is
Xstarted up, VM will merge that with the primary inbox before getting any
Xnew messages from the system mailbox.@refill
X
X@kbd{M-x vm-visit-folder} allows you to visit some other mail folder
Xthan the primary inbox.  The folder name will be prompted for in the
Xminibuffer.@refill
X
XOnce VM has read the folder, the first new or unread message will be
Xselected.  If there is no such message, the first message in the folder
Xis selected.
X
XThe variable @code{vm-startup-with-summary} controls whether VM automatically
Xdisplays a summary of the folder's contents at startup.  A value of
X@code{nil} gives no summary; a value of @code{t} gives a full screen
Xsummary.  A value that is neither @code{t} nor @code{nil} splits the
Xscreen between the summary and the folder display.@refill
X
XThe variable @{vm-mail-window-percentage} tells VM what percentage of
Xthe screen should be given the folder display when both it and the
Xfolder summary are being displayed.  Note that Emacs enforces a minimum
Xwindow sizew limit, so a very high or very low value for this variable
Xmay squeeze out one of the displays entirely.  This variable's default
Xvalue is 75, which works with Emacs' default minimum window size limit,
Xon a 24 line terminal.@refill
X
XA non-@code{nil} value for the variable @{vm-inhibit-startup-message}
Xdisables the display of the VM's copyright, copying and warranty
Xdisclaimer.  If you must, set this variable in your own .emacs file;
Xdon't set it globally for everyone.  Users should be told their rights.
XThe startup messages abort at the first press of a key so they do not
Ximpede mail reading.
X
X@node Selecting Messages, Sending Messages, Starting Up, Top
X@chapter Selecting Messages
X
XThe primary commands for selecting messages in VM are @kbd{n}
X(@code{vm-next-message}) and @kbd{p} (@code{vm-previous-message}).
XThese command move forward and backward through the current folder.
XWhen they go beyond the end or beginning of the folder they wrap to the
Xbeginning and end respectively.  By default these commands skip messages
Xmarked for deletion.  This behavior can be disabled by setting the value
Xof the variable @code{vm-skip-deleted-messages} to @code{nil}.  These
Xcommands can also be made to skip message that have been read; set
X@code{vm-skip-read-messages} to @code{t} to do this.  If all the message
Xis the current folder would be skipped (i.e all are read and/or
Xdeleted), @kbd{n} and @kbd{p} simply move to the next message.@refill
X
XThe command @kbd{n} and @kbd{p} also take prefix arguments that specify
Xthe number of message to move forward or backward.  If the magnitude of
Xthe prefix argument is greater than 1, no message skipping will be done
Xregardless of the settings of the previously mentioned skip control
Xvariables.
X
XOther commands to select messages:
X
X@table @key
X@item RET (@code{vm-goto-message})
XGo to message number @var{n}.  @var{n} is the prefix argument, if
Xprovided, otherwise it is prompted for in the minibuffer.
X@item N (@code{vm-Next-message})
X@itemx P (@code{vm-Previous-message})
XGo to the next (previous) message, ignoring the settings of the skip
Xcontrol variables.
X@item M-n (@code{vm-next-unread-message})
X@itemx M-p (@code{vm-previous-unread-message})
XMove forward (backward) to the nearest new or unread message.  If no
Xsuch message exists then these commands work like @kbd{n} and @kbd{p}.
X@item M-s (@code{vm-isearch-forward})
XThis works just like Emacs' normal incrmenetal search except that when
Xth search ends, VM selects the message containing point.
X@xref{Incremental Search,,,emacs, the GNU Emacs Manual}.
X@end table
X
XSelecting a message within VM normally causes VM to preview it.
X@iftex
X@xref{Previewing}.
X@end iftex
X
X@menu
X* Previewing:: Customizing message previews.
X@end menu
X
X@node Previewing,, Selecting Messages, Selecting Messages
X@section Previewing
X
X@dfn{Previewing} is VM's way of showing you a small portion of a message
Xand allowing you to decide whether you want to read it.
X
XBy default the sender, recipient, subject and date headers are shown and
Xthe rest of the message is hidden.  This behavior may be augmented by
Xthe settings of two variables: @code{vm-visible-headers} and
X@code{vm-preview-lines}.@refill
X
XThe value of @code{vm-preview-lines} should be a number that tells VM
Xhow many lines of the text of the message should be visible.  The default
Xvalue of this variable is 0.  If @code{vm-preview-lines} is @code{nil},
Xthen previewing is not done at all; when a message is first presented it
Xis immediately exposed in its entirety and is marked as read.@refill
X
XThe value of @code{vm-visible-headers} should be a list of regular
Xexpressions matching the beginnings of headers that should be made
Xvisible when a message is presented.  The regexps should be listed in
Xthe preferred order of presentation for the headers they match.@refill
X
XAnother variable of interest is @code{vm-highlighted-headers}.  The
Xvalue of this variable should be a single regular expression that
Xmatches the beginnings of any header that should be presented in inverse
Xvideo when previewing.  For example, a value of @samp{"^From\\|^Subject"}
Xcauses the From and Subject headers to be highlighted.@refill
X
X@node Sending Messages, Saving Messages, Selecting Messages, Top
X@chapter Sending Messages
X
XWhen sending messages from within VM, you will always use the standard
XMail major mode provided with GNU Emacs.
X@xref{Mail Mode,,,emacs, the GNU Emacs Manual}.
XHowever, ``*mail*'' buffers created by VM have extra command keys:@refill
X
X@table @key
X@item C-c C-y
XCopies a message from the current folder into the *mail* buffer.  The message
Xnumber is read from the minibuffer.  By default each line of the copy is
Xprepend with the value of the variable @code{vm-included-text-prefix}.
XIf a prefix argument is given, this prepending is not done.@refill
X@item C-c C-v <Any VM command key>
XAll VM commands may be accessed in the *mail* buffer by prefixing them
Xwith C-c C-v.
X@end table
X
XThe simplest command is @kbd{m} (@code{vm-mail}) which sends a mail
Xmessage much as @kbd{M-x mail} does but allows the added commands
Xdescribed above.@refill
X
X@menu
X* Replying::		Describes the various way to reply to a message.
X* Forwarding Messages::	How to forward a message to a third party.
X@end menu
X
X@node Replying, Forwarding Messages, Sending Messages, Sending Messages
X@section Replying
X
XVM has special commands that make it easy to reply to a message.  When a
Xreply command is invoked VM fills in the subject and recipient headers
Xfor you, since it is apparent to whom the message should be sent.  You
Xcan change these header manually if you wish.
X
XVM also helps you quote material from a message to which you are
Xreplying by provided @dfn{included text} as a feature of some of the
Xcommands.  Included text is a copy of the message being replied to with
Xsome fixed string prepended to each line so that included text can be
Xdistinguished from the text of the reply.  The variable
X@code{vm-included-text-prefix} specifies what the prepended string will
Xbe.@refill
X
XThe variable @code{vm-included-text-attribution-format} specifies the
Xformat for the attribution of included text.  This attribution is a line
Xof text that tells who wrote the text that is to be included; it will be
Xinserted before the included text.  If non-@code{nil} the value of
X@code{vm-included-text-attribution-format} should be a string of the
Xsame format as @code{vm-summary-format}.  @xref{Summaries}.  A
X@code{nil} value causes the attribution to be omitted.
X
XThe reply command are:
X
X@table @key
X@item r (@code{vm-reply})
XReplies to the author of the current message.
X@item R (@code{vm-reply-include-text})
XReplies to the author of the current message and provides included text.
X@item f (@code{vm-folloup})
XReplies to the all recipients of the current message.
X@item F (@code{vm-folloup-include-text})
XReplies to the all recipients of the current message and provides
Xincluded text.
X@end table
X
XAll the reply commands mark the message to which you are responding as
X'`replied'' when the reply is actually sent.@refill
X
X@node Forwarding Messages,, Replying, Sending Messages
X@section Forwarding Messages
X
XVM has two commands to forward messages: @kbd{z}
X(@code{vm-forward-message}) and @key{@@} (@code{vm-send-digest}).@refill
X
XTyping @kbd{z} puts you into a *mail* buffer just like @kbd{m}, except
Xthe current message appears as the body of the message in the *mail*
Xbuffer. The forwarded message is surrounded by RFC 934 complaint message
Xdelimiters.  If the variable @code{vm-rfc934-forwarding} is
Xnon-@code{nil} "^-" to "- -" character stuffing is done to the forwarded
Xmessage (this is the default).  This behavior is required if the
Xrecipient of the forwarded message wants to use a RFC 934 standard
Xbursting agent to access the message.@refill
X
XThe command @key{@@} (@code{vm-send-digest}) works like @kbd{z} except
Xthat a digest of all the messages in the current folder is made and
Xinserted into the *mail* buffer.@refill
X
X@node Saving Messages, Deleting Messages, Sending Messages, Top
X@chapter Saving Messages
X
XMail messages are normally saved to files that contain only mail
Xmessages.  Such files are called @dfn{folders}.
X
XThe VM command to save a message to a folder is @kbd{s}
X(@code{vm-save-message}); invoking this command causes the current
Xmesage to be saved to a folder that whose name you specify in the
Xminibuffer.  If @code{vm-save-message} is given a prefix argument
X@var{n}, the current message plus the next @var{n}-1 message are saved.
XIf @var{n} is negative, the current message and the previous @var{n}-1
Xmessages are saved.  Messages saved with @code{vm-save-message} are
Xmarked ``filed''.@refill
X
XIf you have a directory where you keep all your mail folders, you should
Xset the variable @code{vm-folder-directory} to point to it.  If this
Xvariable is set, @code{vm-save-message} will insert this directory name
Xinto the minibuffer before prompting you for a folder name; this will save
Xyou some typing.@refill
X
XAnother aid to selecting folders in which to save mail is the variable
X@code{vm-auto-folder-alist}.  The value of this variable should be a
Xlist of the form,@refill
X
X((@var{header-name}
X   (@var{regexp} . @var{folder-name}) ...
X  ...))
Xwhere @var{header-name}, @var{regexp}, and @var{folder-name} are all strings.
X
XIf any part of the contents of the message header named by
X@var{header-name} is matched by the regular expression @var{regexp}, VM
Xwill use the corresponding @var{folder-name} as the default when
Xprompting for a folder to save the message in.  If @var{folder-name} is
Xa relative pathname it resolves to the directory named by
X@code{vm-folder-directory}, or the @code{default-directory} of the
Xcurrently visited folder if @var{vm-folder-directory} is nil.@refill
X
XAll @code{vm-auto-folder-alist} matching is case sensitive.
X
XVM can save messages to a folder in two distinct ways.  The message can
Xbe appended directly to the folder on disk, or the folder can be visited
Xas Emacs would visit any other file and the message be appended to that
Xbuffer.  In the latter method you must save the buffer yourself to
Xchange the on-disk copy of the folder.  The variable
X@code{vm-visit-when-saving} controls which method is used.  A @code{nil}
Xvalue (the default) causes VM to append directly to the folder file, a
Xnon-@code{nil} value makes VM load the file into a buffer and append to
Xthat.@refill
X
XOther commands:
X
X@table @key
X@item w (@code{vm-save-message-sans-headers})
XSaves a message or messages to a file without their headers.  this
Xcommand responds to a prefix argument exactly as @code{vm-save-message}
Xdoes.  Messages saved this way are @emph{not} marked as filed, as ``filed''
Xis meant to mean saved to a folder.  You should @strong{not} use this
Xcommand to save to mail folders.
X@item A (@code{vm-auto-archive-messages})
XSave all unfiled messages that auto-match a folder via
X@code{vm-auto-folder-alist} to their appropriate folders.
X@item | (@code{vm-pipe-message-to-command})
XRuns a shell command with the some or all of the current message as input.
XBy default the entire message is used.@*
X@*
XIf invoked with one @key{C-u} the text portion of the message is used.@*
XIf invoked with two @key{C-u}'s the header portion of the message is used.@*
X@*
XOutput is discarded.  The message is not altered or marked as filed.
X@end table
X
X@node Deleting Messages, Undoing, Saving Messages, Top
X@chapter Deleting Messages
X
XIn VM messages are marked for deletion, and then are subsequently
X@dfn{expunged} or removed from the folder.  The messages are not removed
Xfrom the on-disk copy of the folder until the folder is saved.
X
X@table @key
X@item d (@code{vm-delete-message})
XMarks the current message for deletion.  A prefix argument @var{n}
Xcasues the current message and the next @var{n}-1 message to be marked.
XA ngeative @var{n} causes the current message and the previous @var{n}-1
Xmessages to be marked.
X@item u (@code{vm-delete-message})
XRemoves the deletion mark from the current message.  A prefix argument @var{n}
Xcauses the current message and the next @var{n}-1 messages to be unmarked.
XA negative @var{n} causes the current message and the previous @var{n}-1
Xmessages to be unmarked.
X@item # (@code{vm-expunge-folder})
XDoes the actual removal of messages marked for deletion in the current
Xfolder.
X@end table
X
X@node Undoing, Grouping Messages, Deleting Messages, Top
X@chapter Undoing
X
XVM provides a special form of undo which allows message attribute
Xchanges to be undone.
X
XTyping @kbd{C-x u} or @key{C-_} (@code{vm-undo}) undoes the last
Xattribute change.  Consecutive @code{vm-undo}'s undo further and further
Xback.  Any intervening command breaks the undo chain, after which the
Xundos themselves become undoable by subsequent invocations of
X@code{vm-undo}.@refill
X
XNote that expunges and saves are @emph{not} undoable.
X
X@node Grouping Messages, Reading Digests, Undoing, Top
X@chapter Grouping Messages
X
XIn order to make numerous related messages easier to cope with, VM
Xprovides the command @kbd{G} (@code{vm-group-messages}), which groups
Xall message in a folder according to some criterion.  @dfn{Grouping}
Xcauses messages that are related in some way to be to be presented
Xconsecutively.  The actual order of the physical folder is not altered,
Xjust the presentation order and message numbering are changed.  Grouping
Xshould not be confused with sorting; grouping only moves messages that
Xoccur later in the folder backward to ``clump'' with other related
Xmessages.@refill
X
XThe grouping criteria currently supported are:
X@table @samp
X@item subject
XMessages with the same subject (ignoring ``Re:'' prefixes) are grouped
Xtogether.
X@item author
XMessages with the same author are grouped together.
X@item date-sent
XMessages sent on the same day are grouped together.
X@item arrival-time
XMessage presentation reverts to arrival time ordering (the default).
X@end table
X
XIf the variable @code{vm-group-by} has a non-@code{nil} value it
Xspecifies the default grouping that will be used for all folders.  So if
Xyou like having your mail presented to you grouped by subject, then
X@code{(setq vm-group-by "subject")} in your .emacs file to get this
Xbehavior.@refill
X
X@node Reading Digests, Summaries, Grouping Messages, Top
X@chapter Reading Digests
X
XA @dfn{digest} is a one or more mail messages encapsulated in a single message.
X
XVM supports digests by providing a command to ``burst'' them into their
Xindividual messages.  These message can then be handled like any other
Xmessage under VM.
X
XThe command @kbd{*} (@code{vm-burst-digest}) bursts a digest into its
Xindividual messages and appends these messages to current folder.  These
Xmessages are then assimilated into the current folder using the default
Xgrouping.  @xref{Grouping Messages}.  The original digest message is not
Xaltered, and the messages extracted from it are not part of the on-disk copy
Xof the folder until a save is done.@refill
X
X@node Summaries, Miscellaneous, Reading Digests, Top
X@chapter Summaries
X
XTyping @kbd{h} (@code{vm-summarize}) causes VM to pop up a window
Xcontaining a summary of contents of the current folder.  An arrow
X@samp{->} appears to the left of the line summarizing the current
Xmessage.  The information in the summary is automatically updated as
Xchanges are made to the current folder.@refill
X
XThe variable @code{vm-summary-format} controls the format of each
Xmessage's summary.  Its value should be a string.  This string may
Xcontain the printf-like ``%'' conversion specifiers which substitute
Xinformation about the message into the final summary.
X
XRecognized specifiers are:
X@display
X   a - attribute indicators (always three characters wide)
X       The first char is  `D', `N', `U' or ` ' for deleted, new, unread
X       and read message respectively.
X       The second char is `F' for filed (saved) messages.
X       The third char is `R' if the message has been replied to.
X   c - number of characters in message (ignoring headers)
X   d - date of month message sent
X   f - author's address
X   F - author's full name (same as f if full name not found)
X   h - hour message sent
X   i - message ID
X   l - number of lines in message (ignoring headers)
X   m - month message sent
X   n - message number
X   s - message subject
X   w - day of the week message sent
X   y - year message sent
X   z - timezone of date when the message was sent
X@end display
X
XUse ``%%'' to get a single ``%''.
X
XA numeric field width may be specified between the ``%'' and the
Xspecifier; this causes right justification of the substituted string.  A
Xnegative field width causes left justification.  The field width may be
Xfollowed by a ``.'' and a number specifying the maximum allowed length
Xof the substituted string.  If the string is longer than this value it
Xis truncated.
X
XThe summary format need not be one line per message but it must end with
Xa newline, otherwise the message pointer will not be displayed correctly
Xin the summary window.
X
XYou can have a summary generated automatically at startup,
X@pxref{Starting Up}.@refill
X
XAll VM commands are available in the summary buffer just as they
Xare in the folder buffer itself.
X
X@node Miscellaneous,, Summaries, Top
X@chapter Miscellaneous
X
XHere are some VM customization variables that don't really fit into the
Xother chapters.
X
X@table @code
X@item vm-berkeley-mail-compatibility
XA non-@code{nil} value means to read and write BSD Mail(1) style Status:
Xheaders.  This makes sense if you plan to use VM to read mail archives
Xcreated by Mail.
X@item vm-gargle-uucp
XA non-@code{nil} value means to use a crufty regular expression that
Xdoes surprisingly well at beautifying UUCP addresses that are substitued
Xfor %f as part of summary and attribution formats.
X@item vm-mode-hooks
XA non-@code{nil} value should be a list of hook functions to run when a
Xbuffer enters vm-mode.  These hook functions should generally be used to
Xset key bindings and local variables.  Mucking about in the folder
Xbuffer is certainly possible but it is not encouraged.
X@end table
SHAR_EOF
chmod 0664 vm.texinfo || echo "restore of vm.texinfo fails"
sed 's/^X//' << 'SHAR_EOF' > COPYING &&
X		    GNU GENERAL PUBLIC LICENSE
X		     Version 1, February 1989
X
X Copyright (C) 1989 Free Software Foundation, Inc.
X                    675 Mass Ave, Cambridge, MA 02139, USA
X Everyone is permitted to copy and distribute verbatim copies
X of this license document, but changing it is not allowed.
X
X			    Preamble
X
X  The license agreements of most software companies try to keep users
Xat the mercy of those companies.  By contrast, our General Public
XLicense is intended to guarantee your freedom to share and change free
Xsoftware--to make sure the software is free for all its users.  The
XGeneral Public License applies to the Free Software Foundation's
Xsoftware and to any other program whose authors commit to using it.
XYou can use it for your programs, too.
X
X  When we speak of free software, we are referring to freedom, not
Xprice.  Specifically, the General Public License is designed to make
Xsure that you have the freedom to give away or sell copies of free
Xsoftware, that you receive source code or can get it if you want it,
Xthat you can change the software or use pieces of it in new free
Xprograms; and that you know you can do these things.
X
X  To protect your rights, we need to make restrictions that forbid
Xanyone to deny you these rights or to ask you to surrender the rights.
XThese restrictions translate to certain responsibilities for you if you
Xdistribute copies of the software, or if you modify it.
X
X  For example, if you distribute copies of a such a program, whether
Xgratis or for a fee, you must give the recipients all the rights that
Xyou have.  You must make sure that they, too, receive or can get the
Xsource code.  And you must tell them their rights.
X
X  We protect your rights with two steps: (1) copyright the software, and
X(2) offer you this license which gives you legal permission to copy,
Xdistribute and/or modify the software.
X
X  Also, for each author's protection and ours, we want to make certain
Xthat everyone understands that there is no warranty for this free
Xsoftware.  If the software is modified by someone else and passed on, we
Xwant its recipients to know that what they have is not the original, so
Xthat any problems introduced by others will not reflect on the original
Xauthors' reputations.
X
X  The precise terms and conditions for copying, distribution and
Xmodification follow.
X
X		    GNU GENERAL PUBLIC LICENSE
X   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
X
X  0. This License Agreement applies to any program or other work which
Xcontains a notice placed by the copyright holder saying it may be
Xdistributed under the terms of this General Public License.  The
X"Program", below, refers to any such program or work, and a "work based
Xon the Program" means either the Program or any work containing the
XProgram or a portion of it, either verbatim or with modifications.  Each
Xlicensee is addressed as "you".
X
X  1. You may copy and distribute verbatim copies of the Program's source
Xcode as you receive it, in any medium, provided that you conspicuously and
Xappropriately publish on each copy an appropriate copyright notice and
Xdisclaimer of warranty; keep intact all the notices that refer to this
XGeneral Public License and to the absence of any warranty; and give any
Xother recipients of the Program a copy of this General Public License
Xalong with the Program.  You may charge a fee for the physical act of
Xtransferring a copy.
X
X  2. You may modify your copy or copies of the Program or any portion of
Xit, and copy and distribute such modifications under the terms of Paragraph
X1 above, provided that you also do the following:
X
X    a) cause the modified files to carry prominent notices stating that
X    you changed the files and the date of any change; and
X
X    b) cause the whole of any work that you distribute or publish, that
X    in whole or in part contains the Program or any part thereof, either
X    with or without modifications, to be licensed at no charge to all
X    third parties under the terms of this General Public License (except
X    that you may choose to grant warranty protection to some or all
X    third parties, at your option).
X
X    c) If the modified program normally reads commands interactively when
X    run, you must cause it, when started running for such interactive use
X    in the simplest and most usual way, to print or display an
X    announcement including an appropriate copyright notice and a notice
X    that there is no warranty (or else, saying that you provide a
X    warranty) and that users may redistribute the program under these
X    conditions, and telling the user how to view a copy of this General
X    Public License.
X
X    d) You may charge a fee for the physical act of transferring a
X    copy, and you may at your option offer warranty protection in
X    exchange for a fee.
X
XMere aggregation of another independent work with the Program (or its
Xderivative) on a volume of a storage or distribution medium does not bring
Xthe other work under the scope of these terms.
X
X  3. You may copy and distribute the Program (or a portion or derivative of
Xit, under Paragraph 2) in object code or executable form under the terms of
XParagraphs 1 and 2 above provided that you also do one of the following:
X
X    a) accompany it with the complete corresponding machine-readable
X    source code, which must be distributed under the terms of
X    Paragraphs 1 and 2 above; or,
X
X    b) accompany it with a written offer, valid for at least three
X    years, to give any third party free (except for a nominal charge
X    for the cost of distribution) a complete machine-readable copy of the
X    corresponding source code, to be distributed under the terms of
X    Paragraphs 1 and 2 above; or,
X
X    c) accompany it with the information you received as to where the
X    corresponding source code may be obtained.  (This alternative is
X    allowed only for noncommercial distribution and only if you
X    received the program in object code or executable form alone.)
X
XSource code for a work means the preferred form of the work for making
Xmodifications to it.  For an executable file, complete source code means
Xall the source code for all modules it contains; but, as a special
Xexception, it need not include source code for modules which are standard
Xlibraries that accompany the operating system on which the executable
Xfile runs, or for standard header files or definitions files that
Xaccompany that operating system.
X
X  4. You may not copy, modify, sublicense, distribute or transfer the
XProgram except as expressly provided under this General Public License.
XAny attempt otherwise to copy, modify, sublicense, distribute or transfer
Xthe Program is void, and will automatically terminate your rights to use
Xthe Program under this License.  However, parties who have received
Xcopies, or rights to use copies, from you under this General Public
XLicense will not have their licenses terminated so long as such parties
Xremain in full compliance.
X
X  5. By copying, distributing or modifying the Program (or any work based
Xon the Program) you indicate your acceptance of this license to do so,
Xand all its terms and conditions.
X
X  6. Each time you redistribute the Program (or any work based on the
XProgram), the recipient automatically receives a license from the original
Xlicensor to copy, distribute or modify the Program subject to these
Xterms and conditions.  You may not impose any further restrictions on the
Xrecipients' exercise of the rights granted herein.
X
X  7. The Free Software Foundation may publish revised and/or new versions
Xof the General Public License from time to time.  Such new versions will
Xbe similar in spirit to the present version, but may differ in detail to
Xaddress new problems or concerns.
X
XEach version is given a distinguishing version number.  If the Program
Xspecifies a version number of the license which applies to it and "any
Xlater version", you have the option of following the terms and conditions
Xeither of that version or of any later version published by the Free
XSoftware Foundation.  If the Program does not specify a version number of
Xthe license, you may choose any version ever published by the Free Software
XFoundation.
X
X  8. If you wish to incorporate parts of the Program into other free
Xprograms whose distribution conditions are different, write to the author
Xto ask for permission.  For software which is copyrighted by the Free
XSoftware Foundation, write to the Free Software Foundation; we sometimes
Xmake exceptions for this.  Our decision will be guided by the two goals
Xof preserving the free status of all derivatives of our free software and
Xof promoting the sharing and reuse of software generally.
X
X			    NO WARRANTY
X
X  9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
XFOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
XOTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
XPROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
XOR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
XMERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
XTO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
XPROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
XREPAIR OR CORRECTION.
X
X  10. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
XWILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
XREDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
XINCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
XOUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
XTO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
XYOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
XPROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
XPOSSIBILITY OF SUCH DAMAGES.
X
X		     END OF TERMS AND CONDITIONS
SHAR_EOF
chmod 0444 COPYING || echo "restore of COPYING fails"
sed 's/^X//' << 'SHAR_EOF' > README &&
XHow to setup VM:
X
X1) Install all the source modules in a Lisp directory that Emacs knows
X   about.
X
X2) Startup an Emacs session.
X
X3) Byte-compile vm.el.
X
X4) Byte-compile the other modules.
X
X5) Visit the vm.texinfo file and execute `M-x texinfo-format-buffer'.
X   Save the resulting "vm.info" buffer and copy the "vm.info" file into
X   Emacs' info directory under the name "vm".  Edit the "dir" file in
X   that directory and add a menu entry for VM.
X
XSend bug reports to kyle@cs.odu.edu.
SHAR_EOF
chmod 0664 README || echo "restore of README fails"
exit 0