xemacs-beta: man/vm.texi comparison

comparison man/vm.texi @ 0:376386a54a3c r19-14

Import from CVS: tag r19-14

author	cvs
date	Mon, 13 Aug 2007 08:45:50 +0200
parents
children	49a24b4fd526

comparison

equal deleted inserted replaced

--1:000000000000
+:376386a54a3c
+\input texinfo  @comment -*-Texinfo-*-
+@setfilename ../info/vm.info
+@settitle VM User's Manual
+@iftex
+@finalout
+@end iftex
+@c @setchapternewpage odd		% For book style double sided manual.
+@c      @smallbook
+@tex
+\overfullrule=0pt
+%\global\baselineskip 30pt      % For printing in double spaces
+@end tex
+@ifinfo
+This file documents the VM mail reader.
+Copyright (C) 1989, 1991 Kyle E. Jones
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+@end ifinfo
+@c
+@titlepage
+@sp 6
+@center @titlefont{VM User's Manual}
+@sp 4
+@center Second Edition, VM Version 5
+@sp 1
+@center June 1991
+@sp 5
+@center Kyle E. Jones
+@center @t{kyle@@uunet.uu.net}
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1989, 1991 Kyle E. Jones
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+@end titlepage
+@page
+@ifinfo
+@node Top, Introduction, (dir), (dir)
+This manual documents the VM mail reader, a Lisp program which runs as a
+subsystem under Emacs.  The manual is divided into the following
+chapters.
+@menu
+* Introduction::	Overview of the VM interface.
+* Starting Up::		What happens when your start VM.
+* Selecting Messages::	How to select messages for reading.
+* Reading Messages::	Previewing and paging through a message.
+* Sending Messages::	How to send messages from within VM.
+* Saving Messages::	How to save messages.
+* Deleting Messages::	How to delete, undelete and expunge messages
+* Editing Messages::    How to alter the text and headers of a message.
+* Message Marks::	Running VM commands on arbitrary subsets of messages.
+* Undoing::		How to undo changes to message attributes.
+* Grouping Messages::	How to make VM present similar message together.
+* Reading Digests::	How to read digests under VM.
+* Summaries::		How to view and customize the summary of a folder.
+* Miscellaneous::	Various customization variables undescribed elsewhere.
+* License::             The GNU General Public License
+Indices:
+* Key Index::		Menus of command keys and their references.
+* Command Index::	Menus of commands and their references.
+* Variable Index::	Menus of variables and their references.
+@end menu
+@end ifinfo
+@node License, , , Top
+@unnumbered License
+@unnumbered GNU GENERAL PUBLIC LICENSE
+@center Version 1, February 1989
+@cindex license to copy Emacs
+@cindex General Public License
+@display
+Copyright @copyright{} 1989 Free Software Foundation, Inc.
+675 Mass Ave, Cambridge, MA 02139, USA
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+@unnumberedsec Preamble
+The license agreements of most software companies try to keep users
+at the mercy of those companies.  By contrast, our General Public
+License is intended to guarantee your freedom to share and change free
+software---to make sure the software is free for all its users.  The
+General Public License applies to the Free Software Foundation's
+software and to any other program whose authors commit to using it.
+You can use it for your programs, too.
+When we speak of free software, we are referring to freedom, not
+price.  Specifically, the General Public License is designed to make
+sure that you have the freedom to give away or sell copies of free
+software, that you receive source code or can get it if you want it,
+that you can change the software or use pieces of it in new free
+programs; and that you know you can do these things.
+To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+For example, if you distribute copies of a such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must tell them their rights.
+We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+The precise terms and conditions for copying, distribution and
+modification follow.
+@iftex
+@unnumberedsec TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center TERMS AND CONDITIONS
+@end ifinfo
+@enumerate
+@item
+This License Agreement applies to any program or other work which
+contains a notice placed by the copyright holder saying it may be
+distributed under the terms of this General Public License.  The
+``Program'', below, refers to any such program or work, and a ``work based
+on the Program'' means either the Program or any work containing the
+Program or a portion of it, either verbatim or with modifications.  Each
+licensee is addressed as ``you''.
+@item
+@cindex Distribution
+You may copy and distribute verbatim copies of the Program's source
+code as you receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice and
+disclaimer of warranty; keep intact all the notices that refer to this
+General Public License and to the absence of any warranty; and give any
+other recipients of the Program a copy of this General Public License
+along with the Program.  You may charge a fee for the physical act of
+transferring a copy.
+@item
+You may modify your copy or copies of the Program or any portion of
+it, and copy and distribute such modifications under the terms of Paragraph
+1 above, provided that you also do the following:
+@itemize @bullet
+@item
+cause the modified files to carry prominent notices stating that
+you changed the files and the date of any change; and
+@item
+cause the whole of any work that you distribute or publish, that
+in whole or in part contains the Program or any part thereof, either
+with or without modifications, to be licensed at no charge to all
+third parties under the terms of this General Public License (except
+that you may choose to grant warranty protection to some or all
+third parties, at your option).
+@item
+If the modified program normally reads commands interactively when
+run, you must cause it, when started running for such interactive use
+in the simplest and most usual way, to print or display an
+announcement including an appropriate copyright notice and a notice
+that there is no warranty (or else, saying that you provide a
+warranty) and that users may redistribute the program under these
+conditions, and telling the user how to view a copy of this General
+Public License.
+@item
+You may charge a fee for the physical act of transferring a
+copy, and you may at your option offer warranty protection in
+exchange for a fee.
+@end itemize
+Mere aggregation of another independent work with the Program (or its
+derivative) on a volume of a storage or distribution medium does not bring
+the other work under the scope of these terms.
+@item
+You may copy and distribute the Program (or a portion or derivative of
+it, under Paragraph 2) in object code or executable form under the terms of
+Paragraphs 1 and 2 above provided that you also do one of the following:
+@itemize @bullet
+@item
+accompany it with the complete corresponding machine-readable
+source code, which must be distributed under the terms of
+Paragraphs 1 and 2 above; or,
+@item
+accompany it with a written offer, valid for at least three
+years, to give any third party free (except for a nominal charge
+for the cost of distribution) a complete machine-readable copy of the
+corresponding source code, to be distributed under the terms of
+Paragraphs 1 and 2 above; or,
+@item
+accompany it with the information you received as to where the
+corresponding source code may be obtained.  (This alternative is
+allowed only for noncommercial distribution and only if you
+received the program in object code or executable form alone.)
+@end itemize
+Source code for a work means the preferred form of the work for making
+modifications to it.  For an executable file, complete source code means
+all the source code for all modules it contains; but, as a special
+exception, it need not include source code for modules which are standard
+libraries that accompany the operating system on which the executable
+file runs, or for standard header files or definitions files that
+accompany that operating system.
+@item
+You may not copy, modify, sublicense, distribute or transfer the
+Program except as expressly provided under this General Public License.
+Any attempt otherwise to copy, modify, sublicense, distribute or transfer
+the Program is void, and will automatically terminate your rights to use
+the Program under this License.  However, parties who have received
+copies, or rights to use copies, from you under this General Public
+License will not have their licenses terminated so long as such parties
+remain in full compliance.
+@item
+By copying, distributing or modifying the Program (or any work based
+on the Program) you indicate your acceptance of this license to do so,
+and all its terms and conditions.
+@item
+Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the original
+licensor to copy, distribute or modify the Program subject to these
+terms and conditions.  You may not impose any further restrictions on the
+recipients' exercise of the rights granted herein.
+@item
+The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of the license which applies to it and ``any
+later version'', you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+the license, you may choose any version ever published by the Free Software
+Foundation.
+@item
+If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+@iftex
+@heading NO WARRANTY
+@end iftex
+@ifinfo
+@center NO WARRANTY
+@end ifinfo
+@item
+BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+@item
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL
+ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
+ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT
+LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES
+SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE
+WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+@end enumerate
+@iftex
+@heading END OF TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center END OF TERMS AND CONDITIONS
+@end ifinfo
+@page
+@unnumberedsec Appendix: How to Apply These Terms to Your New Programs
+If you develop a new program, and you want it to be of the greatest
+possible use to humanity, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+To do so, attach the following notices to the program.  It is safest to
+attach them to the start of each source file to most effectively convey
+the exclusion of warranty; and each file should have at least the
+``copyright'' line and a pointer to where the full notice is found.
+@smallexample
+@var{one line to give the program's name and a brief idea of what it does.}
+Copyright (C) 19@var{yy}  @var{name of author}
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 1, or (at your option)
+any later version.
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+@end smallexample
+Also add information on how to contact you by electronic and paper mail.
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+@smallexample
+Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
+Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+This is free software, and you are welcome to redistribute it
+under certain conditions; type `show c' for details.
+@end smallexample
+The hypothetical commands `show w' and `show c' should show the
+appropriate parts of the General Public License.  Of course, the
+commands you use may be called something other than `show w' and `show
+c'; they could even be mouse-clicks or menu items---whatever suits your
+program.
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a ``copyright disclaimer'' for the program, if
+necessary.  Here a sample; alter the names:
+@example
+Yoyodyne, Inc., hereby disclaims all copyright interest in the
+program `Gnomovision' (a program to direct compilers to make passes
+at assemblers) written by James Hacker.
+@var{signature of Ty Coon}, 1 April 1989
+Ty Coon, President of Vice
+@end example
+That's all there is to it!
+@node Introduction, Starting Up, Top, Top
+@unnumbered Introduction
+VM (View Mail) is an Emacs subsystem that allows UNIX mail to be read
+and disposed of within Emacs.  Commands exist to do the normal things
+expected of a mail user agent, such as generating replies, saving
+messages to folders, deleting messages and so on.  There are other more
+advanced commands that do tasks like bursting and creating digests,
+message forwarding, and organizing message presentation according to
+various criteria.
+To invoke VM simply type @kbd{M-x vm}.  VM gathers any mail that has
+arrived in your system mailbox and appends it to a file known as your
+@dfn{primary inbox}, and visits that file for reading.  @xref{Starting Up}.
+A file visited for reading by VM is called the @dfn{current folder}.@refill
+@findex vm-scroll-forward
+@findex vm-scroll-backward
+@kindex SPC
+@kindex b
+@kindex DEL
+If there are any messages in the primary inbox, VM selects the first new
+or unread message, and previews it.  @dfn{Previewing} is VM's way of
+showing you part of message and allowing you to decide whether you want
+to read it.  @xref{Previewing}.  By default VM shows you the message's
+sender, recipient, subject and date headers.  Typing @key{SPC}
+(@code{vm-scroll-forward}) exposes the body of the message and flags the
+message as read.  Subsequent @key{SPC}'s scroll forward through the
+message, @kbd{b} or @key{DEL} scrolls backward.  When you reach the end
+of a message, typing @key{SPC} or @kbd{n} moves you forward to preview
+the next message.  @xref{Paging}.@refill
+If you do not want to read a message that's being previewed, just type
+@kbd{n} and VM will move on to the next message (if there is one).
+@xref{Selecting Messages}.@refill
+To save a message to a mail folder use @kbd{s} (@code{vm-save-message}).
+VM will prompt you for the folder name in the minibuffer.
+@xref{Saving Messages}.@refill
+Messages are deleted by typing @kbd{d} (@code{vm-delete-message}) while
+previewing or reading them.  The message is not deleted right away; it
+is simply flagged for deletion.  If you change your mind about deleting a
+message just select it and type @kbd{u} (@code{vm-undelete-message}),
+and the message will be undeleted.  @xref{Deleting Messages}.  The
+actual removal of deleted messages from the current folder is called
+@dfn{expunging} and it is accomplished by typing @kbd{#}
+(@code{vm-expunge-folder}).  The message is still present in the on-disk
+version of the folder until the folder is saved.@refill
+Typing @kbd{h} (@code{vm-summarize}) causes VM to pop up a window
+containing a summary of the contents of the current folder.  The summary is
+presented one line per message, by message number, listing each message's
+author, date sent, line and byte count, and subject.  Also, various
+letters appear beside the message number to indicate that a message is
+new, unread, flagged for deletion, etc.  An arrow @samp{->} appears to
+the left of the line summarizing the current message.  The summary
+format is user configurable, @pxref{Summaries}.@refill
+@findex vm-save-folder
+@kindex S
+When you are finished reading mail the current folder must be saved, so
+that the next time the folder is visited VM will know which messages have
+been already read, replied to and so on.  Typing @kbd{S}
+(@code{vm-save-folder}) expunges all deleted messages and saves the
+folder.  @kbd{C-x C-s} saves the folder without expunging deleted
+messages but the messages are still flagged deleted.  The next time the
+folder is visited these messages will still be flagged for deletion.@refill
+@findex vm-quit
+@findex vm-quit-no-change
+@kindex q
+@kindex x
+To quit VM you can type @kbd{q} (@code{vm-quit}) or @kbd{x}
+(@code{vm-quit-no-change}).  Typing @kbd{q} expunges and saves the
+current folder before quitting.  Also, any messages flagged new are
+changed to be flagged unread, before saving.  The @kbd{x} command quits
+VM without expunging, saving or otherwise modifying the current folder.
+Quitting is not required; you can simply switch to another Emacs buffer
+when you've finished reading mail.@refill
+@findex vm-get-new-mail
+@kindex g
+At any time while reading mail in the primary inbox you can type @kbd{g}
+(@code{vm-get-new-mail}) to check to see if new mail has arrived.  If new
+mail has arrived it will be moved from the system spool area and merged into
+the primary inbox.  If you are not in the middle of another message, VM
+will also jump to the first new message.
+If @code{vm-get-new-mail} is given a prefix argument, it will prompt for
+another file from which to gather messages instead of the usual spool
+files.  In this case the source folder is copied but not deleted.
+@node Starting Up, Selecting Messages, Introduction, Top
+@chapter Starting Up
+@findex vm-load-rc
+@kindex L
+There are three ways to start VM: @kbd{M-x vm}, @kbd{M-x vm-visit-folder}
+and @code{vm-mode}.  The first time VM is started in an Emacs session (by
+any of these methods), it attempts to load the file @file{~/.vm}.  If
+present this file should contain Lisp code, much like the @file{.emacs}
+file.  Since VM has in excess of forty configuration variables, use of
+the @file{~/.vm} can considerably reduce clutter in the @file{.emacs}
+file.  You can force the reloading of this file on demand by typing
+@kbd{L} (@code{vm-load-init-file}) from within VM.@refill
+@findex vm
+@vindex vm-primary-inbox
+@kbd{M-x vm} causes VM to gather any mail present in your system mailbox
+and append it to a file known as your @dfn{primary inbox}, creating
+this file if necessary.  The default name of this file is
+@file{~/INBOX}, but VM will use whatever file is named by the variable
+@code{vm-primary-inbox}.@refill
+@vindex vm-crash-box
+VM transfers the mail from the system mailbox to the primary inbox via a
+temporary file known as the @dfn{crash box}.  The variable
+@code{vm-crash-box} names the crash box file.  VM first copies the mail
+to the crash box, deletes the system mailbox, merges the crash box
+contents into the primary inbox, and then deletes the crash box.  If the
+system or Emacs should crash in the midst of this transfer, any message
+not present in the primary inbox will be either in the system mailbox or
+the crash box.  Some messages may be duplicated but no mail will be
+lost.@refill
+If the file named by @code{vm-crash-box} already exists when VM is
+started up, VM will merge that with the primary inbox before getting any
+new messages from the system mailbox.@refill
+@vindex vm-spool-files
+By default, the location of the system mailbox is determined
+heuristically based on what type of system you're using.  VM can
+be told explicitly where the system mailbox is through the variable
+@code{vm-spool-files}.  The value of this variable should be a list of
+strings naming files VM should try when searching for newly arrived
+mail.  Multiple mailboxes can be specified if you receive mail in
+more than one place.  The value of @code{vm-spool-files} will be inherited
+from the shell environmental variables MAILPATH or MAIL if either of
+these variables are defined.@refill
+@findex vm-visit-folder
+@kindex v
+@kbd{M-x vm-visit-folder} (@kbd{v} from within VM) allows you to visit
+some other mail folder than the primary inbox.  The folder name will be
+prompted for in the minibuffer.@refill
+Once VM has read the folder, the first new or unread message will be
+selected.  If there is no such message, the first message in the folder
+is selected.
+@findex vm-mode
+@kbd{M-x vm-mode} can be used on a buffer already loaded into Emacs to put
+it into the VM major mode so that VM commands can be executed from within
+it.  This command is suitable for use in Lisp programs, and for inclusion in
+@code{auto-mode-alist} to automatically start VM on a file based on a
+particular filename suffix.  @code{vm-mode} foregoes some of VM's startup
+procedures (e.g. starting up a summary) to facilitate noninteractive use.
+@vindex vm-startup-with-summary
+The variable @code{vm-startup-with-summary} controls whether VM
+automatically displays a summary of the folder's contents at startup.  A
+value of @code{nil} gives no summary; a value of @code{t} gives a full
+frame summary.  A value that is neither @code{t} nor @code{nil} splits
+the frame between the summary and the folder display.  The latter only
+works if the variable @code{pop-up-windows}'s value is non-@code{nil},
+and the value of @code{vm-mutable-windows} is non-@code{nil}.  The
+default value of @code{vm-startup-with-summary} is @code{nil}.@refill
+@vindex vm-mail-window-percentage
+The variable @code{vm-mail-window-percentage} tells VM what percentage of
+the frame should be given to the folder display when both it and the
+folder summary are being displayed.  Note that Emacs enforces a minimum
+window size limit, so a very high or very low value for this variable
+may squeeze out one of the displays entirely.  This variable's default
+value is 75, which works with Emacs' default minimum window size limit,
+on a 24 line terminal.  Note that the value of @code{vm-mutable-windows}
+must be @code{t} or VM will not do window resizing regardless of the
+value of @code{vm-mail-window-percentage}.@refill
+@vindex vm-inhibit-startup-message
+A non-@code{nil} value for the variable @code{vm-inhibit-startup-message}
+disables the display of the VM's copyright, copying and warranty
+disclaimer.  If you must, set this variable in your own @file{.emacs} file;
+don't set it globally for everyone.  Users should be told their rights.
+The startup messages abort at the first keystroke after startup, so they do not
+impede mail reading.@refill
+@node Selecting Messages, Reading Messages, Starting Up, Top
+@chapter Selecting Messages
+@findex vm-next-message
+@findex vm-previous-message
+@kindex n
+@kindex p
+@vindex vm-skip-deleted-messages
+@vindex vm-skip-read-messages
+The primary commands for selecting messages in VM are @kbd{n}
+(@code{vm-next-message}) and @kbd{p} (@code{vm-previous-message}).
+These commands move forward and backward through the current folder.
+When they go beyond the end or beginning of the folder they wrap to the
+beginning and end respectively.  By default, these commands skip messages
+flagged for deletion.  This behavior can be disabled by setting the value
+of the variable @code{vm-skip-deleted-messages} to @code{nil}.  These
+commands can also be made to skip messages that have been read; set
+@code{vm-skip-read-messages} to @code{t} to do this.
+The commands @kbd{n} and @kbd{p} also take prefix arguments that specify
+the number of messages to move forward or backward.  If the magnitude of
+the prefix argument is greater than 1, no message skipping will be done
+regardless of the settings of the previously mentioned skip control
+variables.@refill
+@vindex vm-circular-folders
+The variable @code{vm-circular-folders} determines whether VM folders
+will be considered circular by various commands.  @dfn{Circular} means VM
+will wrap from the end of the folder to the start and vice versa when
+moving the message pointer, deleting, undeleting or saving messages
+before or after the current message.@refill
+A value of @code{t} causes all VM commands to consider folders circular.
+A value of @code{nil} causes all of VM commands to signal an error if
+the start or end of the folder would have to be passed to complete the
+command.  For movement commands, this occurs after the message pointer
+has been moved as far it can go.  For other commands the error occurs
+before any part of the command has been executed, i.e. no deletions, saves,
+etc. will be done unless they can be done in their entirety.  A value
+other than @code{nil} or @code{t} causes only VM's movement
+commands to consider folders circular.  Saves, deletes and undeletes
+will behave as if the value is @code{nil}.  The default value of
+@code{vm-circular-folders} is @code{0}.@refill
+Other commands to select messages:
+@table @kbd
+@findex vm-goto-message
+@kindex RET
+@item RET (@code{vm-goto-message})
+Go to message number @var{n}.  @var{n} is the prefix argument, if
+provided, otherwise it is prompted for in the minibuffer.
+@findex vm-goto-message
+@kindex TAB
+@item TAB (@code{vm-goto-message-last-seen})
+Go to message last previewed or read.
+@findex vm-Next-message
+@findex vm-Previous-message
+@kindex N
+@kindex P
+@item N (@code{vm-Next-message})
+@itemx P (@code{vm-Previous-message})
+Go to the next (previous) message, ignoring the settings of the skip
+control variables.
+@findex vm-next-unread-message
+@findex vm-previous-unread-message
+@kindex M-n
+@kindex M-p
+@item M-n (@code{vm-next-unread-message})
+@itemx M-p (@code{vm-previous-unread-message})
+Move forward (backward) to the nearest new or unread message.  If no
+such message exists then these commands work like @kbd{n} and @kbd{p}.
+@findex vm-isearch-forward
+@findex vm-isearch-backward
+@kindex M-s
+@comment @kindex M-r
+@vindex vm-search-using-regexps
+@item M-s (@code{vm-isearch-forward})
+@itemx M-x vm-isearch-backward
+These work just like Emacs' normal forward and backward incremental
+search commands, except that when the search ends, VM selects the
+message containing point.  If the value of the variable
+@code{vm-search-using-regexps} is non-@code{nil}, a regular expression
+may be used instead of a fixed string for the search pattern; VM
+defaults to the fixed string search.  If a prefix argument is given,
+the value of @code{vm-search-using-regexps} is temporarily toggled for
+the search.
+@xref{Incremental Search,,,emacs, the GNU Emacs Manual}.@refill
+@end table
+@node Reading Messages, Sending Messages, Selecting Messages, Top
+@chapter Reading Messages
+Once a message has been selected, VM will present it to you.  By default,
+presentation is done in two stages: @dfn{previewing} and @dfn{paging}.
+@menu
+* Previewing::	Customizing message previews.
+* Paging::	Scrolling and paging through the current message.
+@end menu
+@node Previewing, Paging, Reading Messages, Reading Messages
+@section Previewing
+@dfn{Previewing} is VM's way of showing you a small portion of a message
+and allowing you to decide whether you want to read it.  Typing
+@key{SPC} exposes the body of the message, and from there you can
+repeatedly type @key{SPC} to page through the message.
+By default, the sender, recipient, subject and date headers are shown
+when previewing; the rest of the message is hidden.  This behavior may
+be altered by changing the settings of three variables:
+@code{vm-visible-headers}, @code{vm-invisible-header-regexp} and
+@code{vm-preview-lines}.@refill
+@vindex vm-preview-lines
+The value of @code{vm-preview-lines} should be a number that tells VM
+how many lines of the text of the message should be visible.  The default
+value of this variable is 0.  If @code{vm-preview-lines} is @code{nil},
+then previewing is not done at all; when a message is first presented it
+is immediately exposed in its entirety and is flagged as read.@refill
+@vindex vm-visible-headers
+The value of @code{vm-visible-headers} should be a list of regular
+expressions matching the beginnings of headers that should be made
+visible when a message is presented.  The regexps should be listed in
+the preferred presentation order of the headers they match.@refill
+@vindex vm-invisible-header-regexp
+If non-@code{nil}, the variable @code{vm-invisible-header-regexp}
+specifies what headers should @emph{not} be displayed.  Its value should
+be a string containing a regular expression that matches all headers you
+do not want to see.  Setting this variable non-@code{nil} implies that
+you want to see all headers not matched by it; therefore the value of
+@code{vm-visible-headers} is only used to determine the order of the
+visible headers in this case.  Headers not matched by
+@code{vm-invisible-header-regexp} or @code{vm-visible-headers} are
+displayed last.@refill
+If you change the value of either @code{vm-visible-headers} or
+@code{vm-invisible-header-regexp} in the middle of a VM session the
+effects will not be immediate.  You will need to use the command
+@code{vm-discard-cached-data} on each message (bound to @kbd{j} by
+default) to force VM rearrange the message headers.  A good way to do
+this is to mark all the messages in the folder and apply
+@code{vm-discard-cached-data} to the marked messages.  @xref{Message
+Marks}.@refill
+@vindex vm-highlighted-header-regexp
+Another variable of interest is @code{vm-highlighted-header-regexp}.  The
+value of this variable should be a single regular expression that
+matches the beginnings of any header that should be presented in inverse
+video when previewing.  For example, a value of @samp{"^From\\|^Subject"}
+causes the From and Subject headers to be highlighted.@refill
+@vindex vm-preview-read-messages
+By default, VM previews all messages, even if they have already been read.
+To have VM preview only those messages that have not been read, set the
+value of @code{vm-preview-read-messages} to @code{nil}.
+@findex vm-expose-hidden-headers
+Typing @kbd{t} (@code{vm-expose-hidden-headers}) makes VM toggle
+between exposing and hiding headers that would ordinarily be hidden.@refill
+@node Paging,, Previewing, Reading Messages
+@section Paging
+@vindex vm-auto-next-message
+Typing @key{SPC} during a message preview exposes the body of the
+message.  If the message was new or previously unread, it will be flagged
+``read''.  At this point you can use @key{SPC} to scroll forward, and
+@kbd{b} or @key{DEL} to scroll backward a windowful of text at a time.
+Typing space at the end of a message moves you to the next message.  If
+the value of @code{vm-auto-next-message} is @code{nil}, @key{SPC} will
+not move to the next message; you must type @kbd{n} explicitly.
+If the value of @code{vm-honor-page-delimiters} is non-@code{nil}, VM
+will recognize and honor page delimiters.  This means that when you
+scroll through a document, VM will display text only up to the next page
+delimiter.  Text after the delimiter will be hidden until you type
+another @key{SPC}, at which point the text preceding the delimiter will
+become hidden.  The Emacs variable @code{page-delimiter} determines what
+VM will consider to be a page delimiter.
+You can ``unread'' a message (so to speak) by typing @kbd{U}
+(@code{vm-unread-message}).  The current message will be flagged unread.
+@node Sending Messages, Saving Messages, Reading Messages, Top
+@chapter Sending Messages
+When sending messages from within VM, you will be using the standard
+Mail major mode provided with GNU Emacs.  @xref{Mail Mode,,,emacs, the
+GNU Emacs Manual}.
+However, @samp{*mail*} buffers created by VM have extra command keys:
+@table @kbd
+@findex vm-yank-message
+@kindex C-c C-y
+@item C-c C-y (@code{vm-yank-message})
+Copies a message from the current folder into the @samp{*mail*} buffer.
+The message number is read from the minibuffer.  By default, each line of
+the copy is prepended with the value of the variable
+@code{vm-included-text-prefix}.  All message headers are yanked along
+with the text.  Point is left before the inserted text, the mark after.
+Any hook functions bound to mail-yank-hooks are run, after inserting
+the text and setting point and mark.  If a prefix argument is given,
+this tells VM to ignore mail-yank-hooks, don't set the mark, don't prepend the
+value of vm-included-text-prefix to every yanked line, and don't yank
+any headers other than those specified in
+vm-visible-headers/vm-invisible-headers.@refill
+@kindex C-c y
+@findex vm-yank-message-other-folder
+@item C-c y (@code{vm-yank-message-other-folder})
+Work like @code{vm-yank-message}, but it first prompts for the name of a
+folder from which to yank the message.@refill
+@kindex C-c C-v
+@item C-c C-v <Any VM command key>
+All VM commands may be accessed in the @samp{*mail*} buffer by prefixing them
+with C-c C-v.
+@end table
+@findex vm-mail
+@kindex m
+The simplest command is @kbd{m} (@code{vm-mail}) which sends a mail
+message much as @kbd{M-x mail} does but allows the added commands
+described above.
+@code{vm-mail} can be invoked outside of VM by typing @kbd{M-x vm-mail}.
+However, of the above commands, only @kbd{C-c y}
+(@code{vm-yank-message-other-folder}) will work; all the other commands
+require a parent folder.@refill
+If you send a message and it is returned by the mail system because it
+was undeliverable, you can easily resend the message by typing @kbd{M-r}
+(@code{vm-resend-bounced-message}).  VM will extract the old message and
+its pertinent headers from the returned message, and place you in a
+@samp{*mail*} buffer.  You can then change the recipient addresses or do
+whatever is necessary to correct the original problem and resend the
+message.@refill
+@menu
+* Replying::		Describes the various ways to reply to a message.
+* Forwarding Messages::	How to forward a message to a third party.
+@end menu
+@node Replying, Forwarding Messages, Sending Messages, Sending Messages
+@section Replying
+@vindex vm-reply-subject-prefix
+VM has special commands that make it easy to reply to a message.  When a
+reply command is invoked, VM fills in the subject and recipient headers
+for you, since it is apparent to whom the message should be sent and
+what the subject should be.  There is an old convention of prepending
+the string @samp{"Re: "} to the subject of replies if the string isn't
+present already.  VM supports this indirectly by providing the variable
+@code{vm-reply-subject-prefix}.  Its value should be a string to prepend
+to the subject of replies, if the said string isn't present already.  A
+@code{nil} value means don't prepend anything to the subject (this is
+the default).  In any case you can edit any of the message headers
+manually, if you wish.@refill
+@vindex vm-included-text-prefix
+VM also helps you quote material from a message to which you are
+replying by providing @dfn{included text} as a feature of some of the
+commands.  @dfn{Included text} is a copy of the message being replied to with
+some fixed string prepended to each line so that included text can be
+distinguished from the text of the reply.  The variable
+@code{vm-included-text-prefix} specifies what the prepended string will
+be.@refill
+@vindex vm-included-text-attribution-format
+The variable @code{vm-included-text-attribution-format} specifies the
+format for the attribution of included text.  This attribution is a line
+of text that tells who wrote the text that is to be included; it will be
+inserted before the included text.  If non-@code{nil}, the value of
+@code{vm-included-text-attribution-format} should be a string format
+specification similar to @code{vm-summary-format}.  @xref{Summaries}.  A
+@code{nil} value causes the attribution to be omitted.@refill
+@vindex vm-in-reply-to-format
+The variable @code{vm-in-reply-to-format} specifies the format of the
+In-Reply-To header that is inserted into header section of the reply
+buffer.  Like @code{vm-included-text-attribution-format},
+@code{vm-in-reply-to-format} should be a string similar to that of
+@code{vm-summary-format}.  A @code{nil} value causes the In-Reply-To
+header to be omitted.@refill
+@vindex vm-strip-reply-headers
+The recipient headers generated for reply messages are created by
+simply copying the appropriate headers for the message to which you are
+replying.  This includes any full name information, comments, etc. in
+these headers.  If the variable @code{vm-strip-reply-headers} is
+non-@code{nil}, the reply headers will stripped of all information but
+the actual addresses.
+The reply commands are:
+@table @kbd
+@findex vm-reply
+@kindex r
+@item r (@code{vm-reply})
+Replies to the author of the current message.
+@findex vm-reply-include-text
+@kindex R
+@item R (@code{vm-reply-include-text})
+Replies to the author of the current message and provides included text.
+@findex vm-followup
+@kindex f
+@item f (@code{vm-followup})
+Replies to the all recipients of the current message.
+@findex vm-followup-include-text
+@kindex F
+@item F (@code{vm-followup-include-text})
+Replies to the all recipients of the current message and provides
+included text.
+@end table
+These commands all accept a numeric prefix argument @var{n}, which if
+present, causes VM to reply to the next (or previous if the argument is
+negative) @var{n-1} message as well as the current message.  Also all
+the reply commands set the ``replied'' attribute of the messages to
+which you are responding, but only when the reply is actually sent.  The
+reply commands can also be applied to marked messages,
+@pxref{Message Marks}.@refill
+@vindex vm-reply-ignored-addresses
+If you are one of multiple recipients of a message and you use @kbd{f}
+and @kbd{F}, your address will be included in the recipients of the
+reply.  You can avoid this by judicious use of the variable
+@code{vm-reply-ignored-addresses}.  Its value should be a list of
+regular expressions that match addresses that VM should automatically
+remove from the recipient headers of replies.
+@node Forwarding Messages,, Replying, Sending Messages
+@section Forwarding Messages
+VM has two commands to forward messages: @kbd{z}
+(@code{vm-forward-message}) and @key{@@} (@code{vm-send-digest}).@refill
+@findex vm-forward-message
+@kindex z
+@vindex vm-rfc934-forwarding
+@vindex vm-forwarding-subject-format
+Typing @kbd{z} puts you into a @samp{*mail*} buffer just like @kbd{m},
+except the current message appears as the body of the message in the
+@samp{*mail*} buffer. The forwarded message is surrounded by RFC 934
+compliant message delimiters.  If the variable
+@code{vm-rfc934-forwarding} is non-@code{nil}, "^-" to "- -" character
+stuffing is done to the forwarded message (this is the default).  This
+behavior is required if the recipient of the forwarded message wants to
+use a RFC 934 standard bursting agent to access the message.  If the
+variable @code{vm-forwarding-subject-format} is non-@code{nil} it should
+specify the format of the Subject header of the forwarded message.  This
+subject will be used as the contents of the Subject header automatically
+inserted into the @samp{*mail*} buffer.  A @code{nil} value causes the
+Subject header to be left blank.  The forwarded message is flagged
+``forwarded''.@refill
+@findex vm-send-digest
+@vindex vm-digest-preamble-format
+@vindex vm-digest-center-preamble
+@kindex @@
+The command @key{@@} (@code{vm-send-digest}) works like @kbd{z} except
+that a digest of all the messages in the current folder is made and
+inserted into the @samp{*mail*} buffer.  Also, @code{vm-send-digest} can
+be applied to marked messages.  @xref{Message Marks}.  When applied to
+marked messages, @code{vm-send-digest} will only bundle marked messages,
+as opposed to the usual bundling of all messages in the current folder.
+If you give @code{vm-send-digest} a prefix argument, VM will insert a
+list of preamble lines at the beginning of the digest, one line per
+digestified message.  The variable @code{vm-digest-preamble-format}
+determines the format of the preamble lines.  If the value of
+@code{vm-digest-center-preamble} is non-@code{nil}, the preamble lines
+will be centered.@refill
+@node Saving Messages, Deleting Messages, Sending Messages, Top
+@chapter Saving Messages
+Mail messages are normally saved to files that contain only mail
+messages.  Such files are called @dfn{folders}.
+@findex vm-save-message
+@kindex s
+The VM command to save a message to a folder is @kbd{s}
+(@code{vm-save-message}); invoking this command causes the current
+message to be saved to a folder whose name you specify in the
+minibuffer.  If @code{vm-save-message} is given a prefix argument
+@var{n}, the current message plus the next @var{n-1} message are saved.
+If @var{n} is negative, the current message and the previous @var{n-1}
+messages are saved.  Messages saved with @code{vm-save-message} are
+flagged ``filed''.@refill
+@vindex vm-confirm-new-folders
+If the value of the variable @code{vm-confirm-new-folders} is
+non-@code{nil}, VM will ask for confirmation before creating a new
+folder on interactive saves.@refill
+@vindex vm-folder-directory
+If you have a directory where you keep all your mail folders, you should
+set the variable @code{vm-folder-directory} to point to it.  If this
+variable is set, @code{vm-save-message} will insert this directory name
+into the minibuffer before prompting you for a folder name; this will save
+you some typing.@refill
+@vindex vm-auto-folder-alist
+Another aid to selecting folders in which to save mail is the variable
+@code{vm-auto-folder-alist}.  The value of this variable should be a
+list of the form,@refill
+@display
+((@var{header-name}
+(@var{regexp} . @var{folder-name}) ...)
+...)
+@end display
+where @var{header-name} and @var{regexp} are strings, and
+@var{folder-name} is a string or an s-expression that evaluates to a
+string.@refill
+If any part of the contents of the message header named by
+@var{header-name} is matched by the regular expression @var{regexp}, VM
+will evaluate the corresponding @var{folder-name} and use the result as
+the default when prompting for a folder to save the message in.  If
+the resulting folder name is a relative pathname it resolves to the directory
+named by @code{vm-folder-directory}, or the @code{default-directory} of
+the currently visited folder if @code{vm-folder-directory} is @code{nil}.@refill
+When @var{folder-name} is evaluated, the current buffer will contain only
+the contents of the header named by @var{header-name}.  It is safe to
+modify this buffer.  You can use the match data from any @samp{\( @dots{}
+\)} grouping constructs in @var{regexp} along with the function
+@code{buffer-substring} to build a folder name based on the header information.
+If the result of evaluating @var{folder-name} is a list, then the list will
+be treated as another auto-folder-alist and will be descended
+recursively.@refill
+@vindex vm-auto-folder-case-fold-search
+Whether matching is case sensitive depends on the value of the variable
+@code{vm-auto-folder-case-fold-search}.  A non-@code{nil} value makes
+matching case insensitive.  The default value is @code{t}, which means
+matching is case sensitive.  Note that the matching of header names is
+always case insensitive because RFC 822 specifies that header names are
+case indistinct.
+@vindex vm-visit-when-saving
+VM can save messages to a folder in two distinct ways.  The message can be
+appended directly to the folder on disk, or the folder can be visited as
+Emacs would visit any other file and the message be appended to that
+buffer.  In the latter method you must save the buffer yourself to change
+the on-disk copy of the folder.  The variable @code{vm-visit-when-saving}
+controls which method is used.  A value of @code{t} causes VM to always
+visit a folder before saving message to it.  A @code{nil} value causes VM
+to always append directly to the folder file.  In this case VM will not
+save messages to the disk copy of a folder that is being visited.  This
+restriction is necessary to insure that the buffer and on-disk copies of
+the folder are consistent. If the value of @var{vm-visit-when-saving} is
+not @code{nil} and not @code{t} (e.g. 0, the default), VM will append to
+the folder's buffer if the buffer is currently being visited, otherwise VM
+will append to the file itself.@refill
+@vindex vm-delete-after-saving
+After a message is saved to a folder, the usual thing to do next is to
+delete it.  If the variable @code{vm-delete-after-saving} is
+non-@code{nil}, VM will flag messages for deletion automatically after
+saving them.  This applies only to saves to folders, not for the @kbd{w}
+command (see below).@refill
+Other commands:
+@table @kbd
+@findex vm-save-message-sans-headers
+@kindex w
+@item w (@code{vm-save-message-sans-headers})
+Saves a message or messages to a file without their headers.  This
+command responds to a prefix argument exactly as @code{vm-save-message}
+does.  Messages saved this way are flagged ``written''.
+@findex vm-auto-archive-messages
+@kindex A
+@item A (@code{vm-auto-archive-messages})
+Save all unfiled messages that auto-match a folder via
+@code{vm-auto-folder-alist} to their appropriate folders.  Messages that
+are flagged for deletion are not saved by this command.  If invoked with a
+prefix argument, confirmation will be requested for each save.
+@findex vm-pipe-message-to-command
+@kindex |
+@item | (@code{vm-pipe-message-to-command})
+Runs a shell command with some or all of the current message as input.
+By default, the entire message is used.@*
+@*
+If invoked with one @t{C-u} the text portion of the message is used.@*
+If invoked with two @t{C-u}'s the header portion of the message is used.@*
+@*
+If the shell command generates any output, it is displayed in a
+@samp{*Shell Command Output*} buffer.  The message itself is not altered.
+@end table
+@node Deleting Messages, Editing Messages, Saving Messages, Top
+@chapter Deleting Messages
+In VM, messages are flagged for deletion, and then are subsequently
+@dfn{expunged} or removed from the folder.  The messages are not removed
+from the on-disk copy of the folder until the folder is saved.
+@table @kbd
+@findex vm-delete-message
+@kindex d
+@item d (@code{vm-delete-message})
+Flags the current message for deletion.  A prefix argument @var{n}
+causes the current message and the next @var{n-1} messages to be flagged.
+A negative @var{n} causes the current message and the previous @var{n-1}
+messages to be flagged.
+@findex vm-undelete-message
+@kindex u
+@item u (@code{vm-undelete-message})
+Removes the deletion flag from the current message.  A prefix argument @var{n}
+causes the current message and the next @var{n-1} messages to be undeleted.
+A negative @var{n} causes the current message and the previous @var{n-1}
+messages to be undeleted.
+@findex vm-kill-subject
+@kindex k
+@item k (@code{vm-kill-subject})
+Flags all messages with the same subject as the current message (ignoring
+``Re:'') for deletion.
+@findex vm-expunge-folder
+@kindex #
+@item # (@code{vm-expunge-folder})
+Does the actual removal of messages flagged for deletion in the current
+folder.
+@end table
+@vindex vm-move-after-deleting
+@vindex vm-move-after-undeleting
+Setting the variable @code{vm-move-after-deleting} non-@code{nil} causes
+VM to move past the messages after flagging them for deletion.  Setting
+@code{vm-move-after-undeleting} non-@code{nil} causes similar movement after undeletes.@refill
+@node Editing Messages, Message Marks, Deleting Messages, Top
+@chapter Editing Messages
+To edit a message, type @kbd{e} (@code{vm-edit-message}).  The current
+message is copied into a temporary buffer, and this buffer is selected
+for editing.  The major mode of this buffer is controlled by the
+variable @code{vm-edit-message-mode}.  The default is Text mode.@refill
+Use @kbd{C-c ESC} (@code{vm-edit-message-end}) when you have finished
+editing the message.  The message will be inserted into its folder,
+replacing the old version of the message.  If you want to quit the edit
+without your edited version replacing the original, use @kbd{C-c C-]}
+(@code{vm-edit-message-abort}), or you can just kill the edit buffer
+with @kbd{C-x k} (@code{kill-buffer}).@refill
+If you give a prefix argument to @code{vm-edit-message}, then the
+current message will be flagged unedited.@refill
+As with VM @samp{*mail*} buffers, all VM commands can be accessed from
+the edit buffer through the command prefix @kbd{C-c C-v}.@refill
+@node Message Marks, Undoing, Editing Messages, Top
+@chapter Message Marks
+VM provides general purpose @dfn{marks} that may be applied to any and
+all messages within a given folder.  Certain VM commands can be
+subsequently invoked only on those message that are marked.
+To mark the current message, type @kbd{C-c C-@@}
+(@code{vm-mark-message}).  If you give a numeric prefix argument
+@var{n}, the next @var{n-1} messages will be marked as well.  A negative
+prefix argument means mark the previous @var{n-1}.  An asterisk
+(@samp{*}) will appear to the right of the message numbers of all marked
+messages in the summary window.@refill
+To remove a mark from the current message, use @kbd{C-c SPC}
+(@code{vm-unmark-message}).  Prefix arguments work as with
+@code{vm-mark-message}.@refill
+Use @kbd{C-c C-a} to mark all messages in the current folder; @kbd{C-c a}
+removes marks from all messages.
+To apply a VM command to all marked message you must prefix it with the
+key sequence @kbd{C-c RET} (@code{vm-next-command-uses-marks}).  The
+next VM command will apply to all marked messages, provided the
+command can be applied to such messages in a meaningful and useful way.
+The current commands that can be applied to marked messages are:
+@code{vm-delete-message}, @code{vm-discard-cached-data},
+@code{vm-followup}, @code{vm-followup-include-text}, @code{vm-reply},
+@code{vm-reply-include-text}, @code{vm-save-message},
+@code{vm-save-message-sans-headers}, @code{vm-send-digest},
+@code{vm-undelete-message}, and @code{vm-unread-message}.@refill
+@node Undoing, Grouping Messages, Message Marks, Top
+@chapter Undoing
+VM provides a special form of undo which allows changes to message attributes
+to be undone.
+@findex vm-undo
+@kindex C-x u
+@kindex C-_
+Typing @kbd{C-x u} or @key{C-_} (@code{vm-undo}) undoes the last
+attribute change.  Consecutive @code{vm-undo}'s undo further and further
+back.  Any intervening command breaks the undo chain, after which the
+undos themselves become undoable by subsequent invocations of
+@code{vm-undo}.@refill
+Note that expunges, saves and message edits are @emph{not} undoable.
+@node Grouping Messages, Reading Digests, Undoing, Top
+@chapter Grouping Messages
+@findex vm-group-messages
+@kindex G
+In order to make numerous related messages easier to cope with, VM
+provides the command @kbd{G} (@code{vm-group-messages}), which groups
+all messages in a folder according to some criterion.  @dfn{Grouping}
+causes messages that are related in some way to be presented
+consecutively.  The actual order of the folder is not altered;
+the messages are simply numbered and presented differently.  Grouping
+should not be confused with sorting; grouping only moves messages that
+occur later in the folder backward to ``clump'' with other related
+messages.@refill
+The grouping criteria currently supported are:
+@table @samp
+@item subject
+Messages with the same subject (ignoring ``Re:'' prefixes) are grouped
+together.
+@item author
+Messages with the same author are grouped together.
+@item recipient
+Message with the same recipients are grouped together.
+@item date-sent
+Messages sent on the same day are grouped together.
+@item physical-order
+Message presentation reverts to physical message order of the folder (the
+default).
+@end table
+@vindex vm-group-by
+If the variable @code{vm-group-by} has a non-@code{nil} value it
+specifies the default grouping that will be used for all folders.  So if
+you like having your mail presented to you grouped by subject, then put
+@code{(setq vm-group-by "subject")} in your @file{.vm} or @file{.emacs}
+file to get this behavior.@refill
+@node Reading Digests, Summaries, Grouping Messages, Top
+@chapter Reading Digests
+A @dfn{digest} is one or more mail messages encapsulated in a single message.
+VM supports digests by providing a command to ``burst'' them into their
+individual messages.  These messages can then be handled like any other
+messages under VM.
+@findex vm-burst-digest
+@kindex *
+The command @kbd{*} (@code{vm-burst-digest}) bursts a digest into its
+individual messages and appends them to the current folder.  These
+messages are then assimilated into the current folder using the default
+grouping.  @xref{Grouping Messages}.  The original digest message is not
+altered, and the messages extracted from it are not part of the on-disk copy
+of the folder until a save is done.@refill
+If you give a prefix argument to @code{vm-burst-digest}, it will attempt
+to cope with non-RFC 934 compliant digests.  If @code{vm-burst-digest}
+seems to be breaking digests at inappropriate places, most likely the
+digest is not compliant with the standard.  In this case try using the
+prefix arg.
+@node Summaries, Miscellaneous, Reading Digests, Top
+@chapter Summaries
+@findex vm-summarize
+@vindex vm-auto-center-summary
+@kindex h
+Typing @kbd{h} (@code{vm-summarize}) causes VM to display a summary of
+contents of the current folder.  The information in the summary is
+automatically updated as changes are made to the current folder.  An
+arrow @samp{->} appears to the left of the line summarizing the current
+message.  The variable @code{vm-auto-center-summary} controls whether VM
+will keep the summary arrow vertically centered within the summary
+window.  A value of @code{t} causes VM to always keep the arrow
+centered.  A value of @code{nil} (the default) means VM will never
+bother centering the arrow.  A value that is not @code{nil} and not
+@code{t} causes VM to center the arrow only if the summary window is not
+the only existing window.@refill
+@vindex vm-summary-format
+The variable @code{vm-summary-format} controls the format of each
+message's summary.  Its value should be a string.  This string should
+contain printf-like ``%'' conversion specifiers which substitute
+information about the message into the final summary.
+Recognized specifiers are:
+@display
+a - attribute indicators (always four characters wide)
+The first char is  `D', `N', `U' or ` ' for deleted, new, unread
+and read messages respectively.
+The second char is `F', `W' or ` ' for filed (saved) or written
+messages.
+The third char is `R', `Z' or ` ' for messages replied to,
+and forwarded messages.
+The fourth char is `E' if the message has been edited,
+` ' otherwise.
+A - longer version of attributes indicators (six characters wide)
+The first char is  `D', `N', `U' or ` ' for deleted, new, unread
+and read messages respectively.
+The second is `r' or ` ', for message replied to.
+The third is `z' or ` ', for messages forwarded.
+The fourth is `f' or ` ', for messages filed.
+The fifth is `w' or ` ', for messages written.
+The sixth is `e' or ` ', for messages that have been edited.
+c - number of characters in message (ignoring headers)
+d - numeric day of month message sent
+f - author's address
+F - author's full name (same as f if full name not found)
+h - hour message sent
+i - message ID
+l - number of lines in message (ignoring headers)
+m - month message sent
+M - numeric month message sent (January = 1)
+n - message number
+s - message subject
+t - addresses of the recipients of the message, in a comma-separated list
+T - full names of the recipients of the message, in a comma-separated list
+If a full name cannot be found, the corresponding address is used
+instead.
+w - day of the week message sent
+y - year message sent
+z - timezone of date when the message was sent
+* - `*' if the current message is marked, ` ' otherwise
+@end display
+Use ``%%'' to get a single ``%''.
+A numeric field width may be specified between the ``%'' and the
+specifier; this causes right justification of the substituted string.  A
+negative field width causes left justification.  The field width may be
+followed by a ``.'' and a number specifying the maximum allowed length
+of the substituted string.  If the string is longer than this value, it
+is truncated.
+The summary format need not be one line per message but it must end with
+a newline, otherwise the message pointer will not be displayed correctly
+in the summary window.
+You can have a summary generated automatically at startup,
+@pxref{Starting Up}.@refill
+@vindex vm-follow-summary-cursor
+All VM commands are available in the summary buffer just as they are in
+the folder buffer itself.  If you set @code{vm-follow-summary-cursor}
+non-@code{nil}, VM will select the message under the cursor in the
+summary window before executing commands that operate on the current
+message.  Note that this occurs @emph{only} when executing a command
+from the summary buffer window.@refill
+@node Miscellaneous,, Summaries, Top
+@chapter Miscellaneous
+Here are some VM customization variables that don't really fit into the
+other chapters.
+@table @code
+@vindex vm-confirm-quit
+@item vm-confirm-quit
+A value of @code{t} causes VM to always ask for confirmation before
+ending a VM visit of a folder.  A @code{nil} value means VM will ask
+only when messages will be lost unwittingly by quitting, i.e. not
+removed by intentional delete and expunge.  A value that is neither
+@code{nil} nor @code{t} causes VM to ask only when there are unsaved
+changes to message attributes or message will be lost.
+@vindex vm-berkeley-mail-compatibility
+@item vm-berkeley-mail-compatibility
+A non-@code{nil} value means to read and write BSD @i{Mail(1)} style Status:
+headers.  This makes sense if you plan to use VM to read mail archives
+created by @i{Mail}.
+@vindex vm-gargle-uucp
+@item vm-gargle-uucp
+A non-@code{nil} value means to use a crufty regular expression that
+does surprisingly well at beautifying UUCP addresses that are substituted
+for %f and %t as part of summary and attribution formats.
+@vindex vm-mode-hooks
+@item vm-mode-hooks
+A non-@code{nil} value should be a list of hook functions to run when a
+buffer enters vm-mode.  These hook functions should generally be used to
+set key bindings and local variables.  Mucking about in the folder
+buffer is certainly possible, but it is not encouraged.
+@vindex vm-delete-empty-folders
+@item vm-delete-empty-folders
+A non-@code{nil} value for this variable causes VM to remove empty (zero
+length) folder files after saving them.
+@vindex vm-mutable-windows
+@item vm-mutable-windows
+This variable's value controls VM's window usage.  A value of @code{t} gives VM
+free run of the Emacs display; it will commandeer the entire frame for
+its purposes.  A value of @code{nil} restricts VM's window usage to the window
+from which it was invoked.  VM will not create, delete, or use any other
+windows, nor will it resize its own window.  A value that is neither @code{t}
+nor @code{nil} allows VM to use other windows, but it will not create new ones,
+or resize or delete the current ones.@refill
+@vindex mail-yank-hooks
+@item mail-yank-hooks
+Value should be a list of functions to be called after a message is
+yanked into a @samp{*mail*} buffer via @code{vm-yank-message}.  When
+each hook function is called, point will be at the beginning of the
+yanked text and mark at the end.
+This is not a VM specific variable, but rather an external variable that
+VM honors so that citation packages such as @i{SUPERCITE} can be
+used with VM.
+@end table
+@node Key Index, Command Index, Top, Top
+@unnumbered Key Index
+@printindex ky
+@node Command Index, Variable Index, Key Index, Top
+@unnumbered Command Index
+@printindex fn
+@node Variable Index, , Command Index, Top
+@unnumbered Variable Index
+@printindex vr
+@summarycontents
+@contents
+@bye

Mercurial > hg > xemacs-beta

comparison man/vm.texi @ 0:376386a54a3c r19-14