xemacs-beta / man / vm.texi

   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
\input texinfo  @comment -*-Texinfo-*-
@setfilename 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)

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.

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, Introduction, Variable Index, 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, License, 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, Introduction, Command Index, Top
@unnumbered Variable Index
@printindex vr

@summarycontents
@contents
@bye
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.