diff options
Diffstat (limited to 'man')
52 files changed, 86258 insertions, 0 deletions
diff --git a/man/ChangeLog b/man/ChangeLog new file mode 100644 index 00000000000..490c6e06cc5 --- /dev/null +++ b/man/ChangeLog @@ -0,0 +1,465 @@ +1999-07-12 Richard Stallman <rms@gnu.org> + + * Version 20.4 released. + +1999-02-22 Andreas Schwab <schwab@gnu.org> + + * gnus.texi: Fix punctuation after @xref. + +1999-01-18 Eli Zaretskii <eliz@gnu.org> + + * msdog.texi (MS-DOS and MULE): dos-unsupported-character-glyph is + a triangle by default, not a solid box. + +1999-01-17 Andrew Innes <andrewi@gnu.org> + + * msdog.texi (MS-DOS Printing): Rewrite section. + + * emacs.texi (Top): Include Windows 98 in the MS-DOS section. + +1998-12-04 Markus Rost <rost@delysid.gnu.org> + + * Makefile.in (INFO_TARGETS): Delete customize.info. + (DVI_TARGETS): Delete customize.dvi. + (../info/customize, customize.dvi): Targets deleted. + +1998-11-18 Richard Stallman <rms@psilocin.ai.mit.edu> + + * customize.texi: File deleted. + +1998-11-08 Eli Zaretskii <eliz@mescaline.gnu.org> + + * frames.texi: Change @xref to @pxref and add comma after @xref. + * custom.texi (Locals): Likewise. + * programs.texi (Fortran Autofill): Likewise. + * text.texi (TeX Editing): Likewise. + * viper.texi: Likewise. + +1998-08-24 Andreas Schwab <schwab@delysid.gnu.org> + + * reftex.texi: Fix info file name. + + * forms.texi (Forms Commands): Change @item to @itemx for + secondary items. + * viper.texi (Groundwork): Likewise. + (Commands): Remove extra Top from @node. + +1998-08-19 Richard Stallman <rms@psilocin.ai.mit.edu> + + * Version 20.3 released. + +1998-08-10 Carsten Dominik <cd@delysid.gnu.org> + + * reftex.texi: Updated to the latest RefTeX version. + +1998-05-06 Richard Stallman <rms@psilocin.gnu.org> + + * Makefile.in (EMACSSOURCES): Add mule.texi. + Add msdog.texi, ack.texi. Remove gnu1.texi. + +1998-04-06 Andreas Schwab <schwab@gnu.org> + + * Makefile.in (ENVADD): Enviroment vars to pass to texi2dvi. Use + it in dvi targets. + (../etc/GNU): Change to $(srcdir) first. + +1998-03-11 Carsten Dominik <cd@delysid.gnu.org> + + * reftex.texi Updated for RefTeX version 3.22. + +1998-02-08 Richard Stallman <rms@psilocin.gnu.org> + + * Makefile.in (reftex.dvi, ../info/reftex): New targets. + (INFO_TARGETS, DVI_TARGETS): Add the new targets. + +1997-09-23 Paul Eggert <eggert@twinsun.com> + + * Makefile.in: Merge changes mistakenly made to `Makefile'. + (INFO_TARGETS): Change ../info/custom to ../info/customize. + (../info/customize): Renamed from ../info/custom. + (../info/viper, viper.dvi): Remove dependency on viper-cmd.texi. + +1997-09-19 Richard Stallman <rms@psilocin.gnu.ai.mit.edu> + + * Version 20.2 released. + +1997-09-15 Richard Stallman <rms@psilocin.gnu.ai.mit.edu> + + * Version 20.1 released. + +1997-08-24 Richard Stallman <rms@psilocin.gnu.ai.mit.edu> + + * Makefile (../info/customize, customize.dvi): New targets. + (INFO_TARGETS): Add ../info/customize. + (DVI_TARGETS): Add customize.dvi. + +1997-07-10 Richard Stallman <rms@psilocin.gnu.ai.mit.edu> + + * Makefile (../info/viper, viper.dvi): Delete viper-cmd.texi dep. + +1996-08-11 Richard Stallman <rms@psilocin.gnu.ai.mit.edu> + + * Version 19.33 released. + +1996-07-31 Richard Stallman <rms@psilocin.gnu.ai.mit.edu> + + * Version 19.32 released. + +1996-06-27 Lars Magne Ingebrigtsen <larsi@ifi.uio.no> + + * Makefile.in: Add rules for the Message manual. + +1996-06-26 Lars Magne Ingebrigtsen <larsi@ifi.uio.no> + + * gnus.texi: New version. + + * message.texi: New manual. + +1996-06-20 Richard Stallman <rms@psilocin.gnu.ai.mit.edu> + + * Makefile.in (All info targets): cd $(srcdir) to do the work. + +1996-06-19 Richard Stallman <rms@psilocin.gnu.ai.mit.edu> + + * Makefile.in (All info targets): Specify $(srcdir) in input files. + Specify -I option. + (All dvi targets): Set the TEXINPUTS variable. + +1996-05-25 Karl Heuer <kwzh@gnu.ai.mit.edu> + + * Version 19.31 released. + +1996-01-07 Richard Stallman <rms@whiz-bang.gnu.ai.mit.edu> + + * Makefile.in (../info/ccmode): Renamed from ../info/cc-mode. + (INFO_TARGETS): Use new name. This avoids name conflict on MSDOS. + +1995-11-29 Richard Stallman <rms@mole.gnu.ai.mit.edu> + + * Makefile.in (../info/cc-mode, cc-mode.dvi): New targets. + (INFO_TARGETS): Add ../info/cc-mode. + (DVI_TARGETS): Add cc-mode.dvi. + +1995-11-24 Richard Stallman <rms@mole.gnu.ai.mit.edu> + + * Version 19.30 released. + +1995-11-04 Lars Magne Ingebrigtsen <larsi@ifi.uio.no> + + * gnus.texi: New file. + +1995-11-04 Erik Naggum <erik@naggum.no> + + * gnus.texi: File deleted. + +1995-11-02 Stephen Gildea <gildea@x.org> + + * mh-e.texi: "Function Index" -> "Command Index" to work with + Emacs 19.30 C-h C-k support of separately-documented commands. + +1995-06-26 Richard Stallman <rms@mole.gnu.ai.mit.edu> + + * Makefile.in (../info/ediff, ediff.dvi): New targets. + (INFO_TARGETS, DVI_TARGETS): Add those new targets. + +1995-04-24 Richard Stallman <rms@mole.gnu.ai.mit.edu> + + * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add viper targets. + (../info/viper, viper.dvi): New targets. + +1995-04-20 Kevin Rodgers <kevinr@ihs.com> + + * dired-x.texi (Installation): Change the example to set + buffer-local variables like dired-omit-files-p in + dired-mode-hook. + +1995-04-17 Richard Stallman <rms@mole.gnu.ai.mit.edu> + + * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add mh-e targets. + (../info/mh-e, mh-e.dvi): New targets. + +1995-02-07 Richard Stallman <rms@pogo.gnu.ai.mit.edu> + + * Makefile.in (maintainer-clean): Renamed from realclean. + +1994-11-23 Richard Stallman <rms@mole.gnu.ai.mit.edu> + + * Makefile.in: New file. + * Makefile: File deleted. + +1994-11-19 Richard Stallman <rms@mole.gnu.ai.mit.edu> + + * Makefile (TEXINDEX_OBJS): Variable deleted. + (texindex, texindex.o, getopt.o): Rules deleted. + All deps on texindex deleted. + (distclean): Don't delete texindex. + (mostlyclean): Don't delete *.o. + * texindex.c, getopt.c: Files deleted. + +1994-09-07 Richard Stallman <rms@mole.gnu.ai.mit.edu> + + * Version 19.26 released. + +1994-07-02 Richard Stallman (rms@gnu.ai.mit.edu) + + * Makefile (EMACSSOURCES): Exclude undo.texi. + +1994-05-30 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.25 released. + +1994-05-23 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.24 released. + +1994-05-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.23 released. + +1994-04-17 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile: Delete spurious tab. + +1994-02-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile (.SUFFIXES): New rule. + +1994-01-15 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile (dired-x.dvi, ../info/dired-x): New targets. + (INFO_TARGETS, DVI_TARGETS): Add the new targets. + +1994-01-08 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile (../info/sc): Renamed frin sc.info. + (../info/cl): Likewise. + (INFO_TARGETS): Use new names. + +1993-12-04 Richard Stallman (rms@srarc2) + + * getopt.c: New file. + * Makefile (TEXINDEX_OBJS): Use getopt.o in this dir, not ../lib-src. + (getopt.o): New rule. + (dvi): Don't depend on texindex. + (emacs.dvi, cl.dvi, forms.dvi, vip.dvi, gnus.dvi, sc.dvi): + Depend on texindex. + +1993-12-03 Richard Stallman (rms@srarc2) + + * Makefile (../info/sc.info): Renamed from ../info/sc. + (TEXI2DVI): New variable. + (emacs.dvi, cl.dvi forms.dvi, sc.dvi, vip.dvi, gnus.dvi, info.dvi): + Add explicit commands. + (TEXINDEX_OBJS): Delete duplicate getopt.o. + +1993-11-27 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.22 released. + +1993-11-18 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile (TEXINDEX_OBJS): Delete spurious period. + +1993-11-16 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.21 released. + +1993-11-15 Paul Eggert (eggert@twinsun.com) + + * man/Makefile (../info/cl.info): Renamed from ../info/cl. + +1993-11-15 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile (../etc/GNU): New target. + (EMACSSOURCES): Add gnu1.texi. + +1993-11-14 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile (realclean): Don't delete the Info files. + +1993-10-25 Brian Fox (bfox@albert.gnu.ai.mit.edu) + + * forms.texi: Fix forms.texi so that it will format correctly. + Added missing `@end iftex', fixed bad reference. + + * info.texi, info-stn.texi: New files implement texinfo version of + `info' file. + + * frames.texi (Creating Frames): Mention `C-x 5' instead of `C-x + 4' where appropriate. + +1993-10-20 Brian Fox (bfox@ai.mit.edu) + + * Makefile: Fix targets for texindex, new info.texi files. + * info-stnd.texi: New file implements info for standalone info + reader. + * info.texi: Updated to include recent changes to "../info/info". + New source file for ../info/info; includes info-stnd.texi. + + * texindex.c: Include "../src/config.h" if building in emacs. + + * Makefile: Change all files to FILENAME.texi, force all targets + to be FILENAME, not FILENAME.info. This changes sc.texinfo, + vip.texinfo, forms.texinfo, cl.texinfo. + Add target to build texindex.c, defining `emacs'. + + * forms.texi: Install new file to match version 2.3 of forms.el. + +1993-08-14 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.19 released. + +1993-08-10 Simon Leinen (simon@lia.di.epfl.ch) + + * sc.texinfo: Fix info file name. + + * Makefile (info): Added gnus and sc. + (dvi): Added gnus.dvi and sc.dvi. + (../info/sc, sc.dvi): New targets. + +1993-08-08 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.18 released. + +1993-07-20 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Makefile: Fix source file names of the separate manuals. + (gnus.dvi, ../info/gnus): New targets. + +1993-07-18 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * Version 19.17 released. + +1993-07-10 Richard Stallman (rms@mole.gnu.ai.mit.edu) + + * split-man: Fix typos in last change. + +1993-07-06 Jim Blandy (jimb@geech.gnu.ai.mit.edu) + + * Version 19.16 released. + +1993-06-19 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * version 19.15 released. + +1993-06-18 Jim Blandy (jimb@geech.gnu.ai.mit.edu) + + * Makefile (distclean): It's rm, not rf. + +1993-06-17 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * Version 19.14 released. + +1993-06-16 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * Makefile: New file. + +1993-06-08 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * Version 19.13 released. + +1993-05-27 Jim Blandy (jimb@geech.gnu.ai.mit.edu) + + * Version 19.9 released. + +1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * Version 19.8 released. + +1993-05-25 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * cmdargs.texi: Document the -i, -itype, and -iconic options. + + * trouble.texi: It's `enable-flow-control-on', not + `evade-flow-control-on'. + +1993-05-24 Jim Blandy (jimb@wookumz.gnu.ai.mit.edu) + + * display.texi: Document standard-display-european. + +1993-05-22 Jim Blandy (jimb@geech.gnu.ai.mit.edu) + + * Version 19.7 released. + + * emacs.texi: Add a sentence to the top menu mentioning the + specific version of Emacs this manual applies to. + +1993-04-25 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) + + * basic.texi: Documented next-line-add-lines variable used to + implement down-arrow. + + * killing.texi: Documented kill-whole-line. + +1993-04-18 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu) + + * text.texi: Updated unix TeX ordering information. + +1993-03-26 Eric S. Raymond (eric@geech.gnu.ai.mit.edu) + + * news.texi: Mentioned fill-rectangle in keybinding list. + + * killing.texi: Documented fill-rectangle. + +1993-03-17 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) + + * vc.texi: Brought the docs up to date with VC 5.2. + +1992-01-10 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) + + * emacs.tex: Mentioned blackbox and gomoku under Amusements. + Assembler mode is now mentioned and appropriately + indexed under Programming Modes. + +1991-02-15 Robert J. Chassell (bob at wookumz.ai.mit.edu) + + * emacs.tex: Updated TeX ordering information. + +1990-08-30 David Lawrence (tale at pogo.ai.mit.edu) + + * gnus.texinfo: New file. Removed installation instructions. + +1990-06-26 David Lawrence (tale at geech) + + * emacs.tex: Noted that completion-ignored-extensions is not used + to filter out names when all completions are displayed in + *Completions*. + +1990-05-25 Richard Stallman (rms at sugar-bombs.ai.mit.edu) + + * texindex.tex: If USG, include sys/types.h and sys/fcntl.h. + +1990-03-21 Jim Kingdon (kingdon at pogo.ai.mit.edu) + + * emacs.tex: Add @findex grep. + +1989-01-17 Robert J. Chassell (bob at rice-chex.ai.mit.edu) + + * texinfo.tex: Changed spelling of `\sc' font to `\smallcaps' and + then defined `\sc' as the command for smallcaps in Texinfo. This + measns that the @sc command will produce small caps. bfox has + made the corresponding change to makeinfo and texinfm.el. + +1988-08-16 Robert J. Chassell (bob at frosted-flakes.ai.mit.edu) + + * emacs.tex: Corrected two typos. No other changes before + Version 19 will be made. + + * vip.texinfo: Removed menu entry Adding Lisp Code in node + Customization since the menu entry did not point to anything. + Also added an @finalout command to remove overfull hboxes from the + printed output. + + * cl.texinfo: Added @bye, \input line and @settitle to file. + This file is clearly intended to be a chapter of some other work, + but the other work does not yet exist. + +1988-07-25 Robert J. Chassell (bob at frosted-flakes.ai.mit.edu) + + * texinfo.texinfo: Three typos corrected. + +1988-05-23 Robert J. Chassell (bob at frosted-flakes.ai.mit.edu) + + * emacs.tex: Update information for obtaining TeX distribution from the + University of Washington. + diff --git a/man/abbrevs.texi b/man/abbrevs.texi new file mode 100644 index 00000000000..2c7062c3ea9 --- /dev/null +++ b/man/abbrevs.texi @@ -0,0 +1,420 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Abbrevs, Picture, Building, Top +@chapter Abbrevs +@cindex abbrevs +@cindex expansion (of abbrevs) + + A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert +it, into some different text. Abbrevs are defined by the user to expand +in specific ways. For example, you might define @samp{foo} as an abbrev +expanding to @samp{find outer otter}. Then you would be able to insert +@samp{find outer otter } into the buffer by typing @kbd{f o o +@key{SPC}}. + + A second kind of abbreviation facility is called @dfn{dynamic abbrev +expansion}. You use dynamic abbrev expansion with an explicit command +to expand the letters in the buffer before point by looking for other +words in the buffer that start with those letters. @xref{Dynamic +Abbrevs}. + +@menu +* Abbrev Concepts:: Fundamentals of defined abbrevs. +* Defining Abbrevs:: Defining an abbrev, so it will expand when typed. +* Expanding Abbrevs:: Controlling expansion: prefixes, canceling expansion. +* Editing Abbrevs:: Viewing or editing the entire list of defined abbrevs. +* Saving Abbrevs:: Saving the entire list of abbrevs for another session. +* Dynamic Abbrevs:: Abbreviations for words already in the buffer. +* Dabbrev Customization:: What is a word, for dynamic abbrevs. Case handling. +@end menu + +@node Abbrev Concepts +@section Abbrev Concepts + + An @dfn{abbrev} is a word which has been defined to @dfn{expand} into +a specified @dfn{expansion}. When you insert a word-separator character +following the abbrev, that expands the abbrev---replacing the abbrev +with its expansion. For example, if @samp{foo} is defined as an abbrev +expanding to @samp{find outer otter}, then you can insert @samp{find +outer otter.} into the buffer by typing @kbd{f o o .}. + +@findex abbrev-mode +@vindex abbrev-mode +@cindex Abbrev mode +@cindex mode, Abbrev + Abbrevs expand only when Abbrev mode (a minor mode) is enabled. +Disabling Abbrev mode does not cause abbrev definitions to be forgotten, +but they do not expand until Abbrev mode is enabled again. The command +@kbd{M-x abbrev-mode} toggles Abbrev mode; with a numeric argument, it +turns Abbrev mode on if the argument is positive, off otherwise. +@xref{Minor Modes}. @code{abbrev-mode} is also a variable; Abbrev mode is +on when the variable is non-@code{nil}. The variable @code{abbrev-mode} +automatically becomes local to the current buffer when it is set. + + Abbrev definitions can be @dfn{mode-specific}---active only in one major +mode. Abbrevs can also have @dfn{global} definitions that are active in +all major modes. The same abbrev can have a global definition and various +mode-specific definitions for different major modes. A mode-specific +definition for the current major mode overrides a global definition. + + Abbrevs can be defined interactively during the editing session. Lists +of abbrev definitions can also be saved in files and reloaded in later +sessions. Some users keep extensive lists of abbrevs that they load in +every session. + +@node Defining Abbrevs +@section Defining Abbrevs + +@table @kbd +@item C-x a g +Define an abbrev, using one or more words before point as its expansion +(@code{add-global-abbrev}). +@item C-x a l +Similar, but define an abbrev specific to the current major mode +(@code{add-mode-abbrev}). +@item C-x a i g +Define a word in the buffer as an abbrev (@code{inverse-add-global-abbrev}). +@item C-x a i l +Define a word in the buffer as a mode-specific abbrev +(@code{inverse-add-mode-abbrev}). +@item M-x kill-all-abbrevs +This command discards all abbrev definitions currently in effect, +leaving a blank slate. +@end table + +@kindex C-x a g +@findex add-global-abbrev + The usual way to define an abbrev is to enter the text you want the +abbrev to expand to, position point after it, and type @kbd{C-x a g} +(@code{add-global-abbrev}). This reads the abbrev itself using the +minibuffer, and then defines it as an abbrev for one or more words before +point. Use a numeric argument to say how many words before point should be +taken as the expansion. For example, to define the abbrev @samp{foo} as +mentioned above, insert the text @samp{find outer otter} and then type +@kbd{C-u 3 C-x a g f o o @key{RET}}. + + An argument of zero to @kbd{C-x a g} means to use the contents of the +region as the expansion of the abbrev being defined. + +@kindex C-x a l +@findex add-mode-abbrev + The command @kbd{C-x a l} (@code{add-mode-abbrev}) is similar, but +defines a mode-specific abbrev. Mode-specific abbrevs are active only in a +particular major mode. @kbd{C-x a l} defines an abbrev for the major mode +in effect at the time @kbd{C-x a l} is typed. The arguments work the same +as for @kbd{C-x a g}. + +@kindex C-x a i g +@findex inverse-add-global-abbrev +@kindex C-x a i l +@findex inverse-add-mode-abbrev + If the text already in the buffer is the abbrev, rather than its +expansion, use command @kbd{C-x a i g} +(@code{inverse-add-global-abbrev}) instead of @kbd{C-x a g}, or use +@kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) instead of @kbd{C-x a +l}. These commands are called ``inverse'' because they invert the +meaning of the two text strings they use (one from the buffer and one +read with the minibuffer). + + To change the definition of an abbrev, just define a new definition. +When the abbrev has a prior definition, the abbrev definition commands +ask for confirmation for replacing it. + + To remove an abbrev definition, give a negative argument to the abbrev +definition command: @kbd{C-u - C-x a g} or @kbd{C-u - C-x a l}. The +former removes a global definition, while the latter removes a +mode-specific definition. + +@findex kill-all-abbrevs + @kbd{M-x kill-all-abbrevs} removes all the abbrev definitions there +are, both global and local. + +@node Expanding Abbrevs +@section Controlling Abbrev Expansion + + An abbrev expands whenever it is present in the buffer just before +point and you type a self-inserting whitespace or punctuation character +(@key{SPC}, comma, etc.@:). More precisely, any character that is not a +word constituent expands an abbrev, and any word-constituent character +can be part of an abbrev. The most common way to use an abbrev is to +insert it and then insert a punctuation character to expand it. + +@vindex abbrev-all-caps + Abbrev expansion preserves case; thus, @samp{foo} expands into @samp{find +outer otter}; @samp{Foo} into @samp{Find outer otter}, and @samp{FOO} into +@samp{FIND OUTER OTTER} or @samp{Find Outer Otter} according to the +variable @code{abbrev-all-caps} (a non-@code{nil} value chooses the first +of the two expansions). + + These commands are used to control abbrev expansion: + +@table @kbd +@item M-' +Separate a prefix from a following abbrev to be expanded +(@code{abbrev-prefix-mark}). +@item C-x a e +@findex expand-abbrev +Expand the abbrev before point (@code{expand-abbrev}). +This is effective even when Abbrev mode is not enabled. +@item M-x expand-region-abbrevs +Expand some or all abbrevs found in the region. +@end table + +@kindex M-' +@findex abbrev-prefix-mark + You may wish to expand an abbrev with a prefix attached; for example, +if @samp{cnst} expands into @samp{construction}, you might want to use +it to enter @samp{reconstruction}. It does not work to type +@kbd{recnst}, because that is not necessarily a defined abbrev. What +you can do is use the command @kbd{M-'} (@code{abbrev-prefix-mark}) in +between the prefix @samp{re} and the abbrev @samp{cnst}. First, insert +@samp{re}. Then type @kbd{M-'}; this inserts a hyphen in the buffer to +indicate that it has done its work. Then insert the abbrev @samp{cnst}; +the buffer now contains @samp{re-cnst}. Now insert a non-word character +to expand the abbrev @samp{cnst} into @samp{construction}. This +expansion step also deletes the hyphen that indicated @kbd{M-'} had been +used. The result is the desired @samp{reconstruction}. + + If you actually want the text of the abbrev in the buffer, rather than +its expansion, you can accomplish this by inserting the following +punctuation with @kbd{C-q}. Thus, @kbd{foo C-q ,} leaves @samp{foo,} in +the buffer. + +@findex unexpand-abbrev + If you expand an abbrev by mistake, you can undo the expansion and +bring back the abbrev itself by typing @kbd{C-_} to undo (@pxref{Undo}). +This also undoes the insertion of the non-word character that expanded +the abbrev. If the result you want is the terminating non-word +character plus the unexpanded abbrev, you must reinsert the terminating +character, quoting it with @kbd{C-q}. You can also use the command +@kbd{M-x unexpand-abbrev} to cancel the last expansion without +deleting the terminating character. + +@findex expand-region-abbrevs + @kbd{M-x expand-region-abbrevs} searches through the region for defined +abbrevs, and for each one found offers to replace it with its expansion. +This command is useful if you have typed in text using abbrevs but forgot +to turn on Abbrev mode first. It may also be useful together with a +special set of abbrev definitions for making several global replacements at +once. This command is effective even if Abbrev mode is not enabled. + + Expanding an abbrev runs the hook @code{pre-abbrev-expand-hook} +(@pxref{Hooks}). + +@need 1500 +@node Editing Abbrevs +@section Examining and Editing Abbrevs + +@table @kbd +@item M-x list-abbrevs +Display a list of all abbrev definitions. +@item M-x edit-abbrevs +Edit a list of abbrevs; you can add, alter or remove definitions. +@end table + +@findex list-abbrevs + The output from @kbd{M-x list-abbrevs} looks like this: + +@example +(lisp-mode-abbrev-table) +"dk" 0 "define-key" +(global-abbrev-table) +"dfn" 0 "definition" +@end example + +@noindent +(Some blank lines of no semantic significance, and some other abbrev +tables, have been omitted.) + + A line containing a name in parentheses is the header for abbrevs in a +particular abbrev table; @code{global-abbrev-table} contains all the global +abbrevs, and the other abbrev tables that are named after major modes +contain the mode-specific abbrevs. + + Within each abbrev table, each nonblank line defines one abbrev. The +word at the beginning of the line is the abbrev. The number that +follows is the number of times the abbrev has been expanded. Emacs +keeps track of this to help you see which abbrevs you actually use, so +that you can eliminate those that you don't use often. The string at +the end of the line is the expansion. + +@findex edit-abbrevs +@kindex C-c C-c @r{(Edit Abbrevs)} + @kbd{M-x edit-abbrevs} allows you to add, change or kill abbrev +definitions by editing a list of them in an Emacs buffer. The list has +the same format described above. The buffer of abbrevs is called +@samp{*Abbrevs*}, and is in Edit-Abbrevs mode. Type @kbd{C-c C-c} in +this buffer to install the abbrev definitions as specified in the +buffer---and delete any abbrev definitions not listed. + + The command @code{edit-abbrevs} is actually the same as +@code{list-abbrevs} except that it selects the buffer @samp{*Abbrevs*} +whereas @code{list-abbrevs} merely displays it in another window. + +@node Saving Abbrevs +@section Saving Abbrevs + + These commands allow you to keep abbrev definitions between editing +sessions. + +@table @kbd +@item M-x write-abbrev-file @key{RET} @var{file} @key{RET} +Write a file @var{file} describing all defined abbrevs. +@item M-x read-abbrev-file @key{RET} @var{file} @key{RET} +Read the file @var{file} and define abbrevs as specified therein. +@item M-x quietly-read-abbrev-file @key{RET} @var{file} @key{RET} +Similar but do not display a message about what is going on. +@item M-x define-abbrevs +Define abbrevs from definitions in current buffer. +@item M-x insert-abbrevs +Insert all abbrevs and their expansions into current buffer. +@end table + +@findex write-abbrev-file + @kbd{M-x write-abbrev-file} reads a file name using the minibuffer and +then writes a description of all current abbrev definitions into that +file. This is used to save abbrev definitions for use in a later +session. The text stored in the file is a series of Lisp expressions +that, when executed, define the same abbrevs that you currently have. + +@findex read-abbrev-file +@findex quietly-read-abbrev-file +@vindex abbrev-file-name + @kbd{M-x read-abbrev-file} reads a file name using the minibuffer and +then reads the file, defining abbrevs according to the contents of the +file. @kbd{M-x quietly-read-abbrev-file} is the same except that it +does not display a message in the echo area saying that it is doing its +work; it is actually useful primarily in the @file{.emacs} file. If an +empty argument is given to either of these functions, they use the file +name specified in the variable @code{abbrev-file-name}, which is by +default @code{"~/.abbrev_defs"}. + +@vindex save-abbrevs + Emacs will offer to save abbrevs automatically if you have changed any of +them, whenever it offers to save all files (for @kbd{C-x s} or @kbd{C-x +C-c}). This feature can be inhibited by setting the variable +@code{save-abbrevs} to @code{nil}. + +@findex insert-abbrevs +@findex define-abbrevs + The commands @kbd{M-x insert-abbrevs} and @kbd{M-x define-abbrevs} are +similar to the previous commands but work on text in an Emacs buffer. +@kbd{M-x insert-abbrevs} inserts text into the current buffer before point, +describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses +the entire current buffer and defines abbrevs accordingly.@refill + +@node Dynamic Abbrevs +@section Dynamic Abbrev Expansion + + The abbrev facility described above operates automatically as you insert +text, but all abbrevs must be defined explicitly. By contrast, +@dfn{dynamic abbrevs} allow the meanings of abbrevs to be determined +automatically from the contents of the buffer, but dynamic abbrev expansion +happens only when you request it explicitly. + +@kindex M-/ +@kindex C-M-/ +@findex dabbrev-expand +@findex dabbrev-completion +@table @kbd +@item M-/ +Expand the word in the buffer before point as a @dfn{dynamic abbrev}, +by searching in the buffer for words starting with that abbreviation +(@code{dabbrev-expand}). + +@item C-M-/ +Complete the word before point as a dynamic abbrev +(@code{dabbrev-completion}). +@end table + +@vindex dabbrev-limit + For example, if the buffer contains @samp{does this follow } and you +type @kbd{f o M-/}, the effect is to insert @samp{follow} because that +is the last word in the buffer that starts with @samp{fo}. A numeric +argument to @kbd{M-/} says to take the second, third, etc.@: distinct +expansion found looking backward from point. Repeating @kbd{M-/} +searches for an alternative expansion by looking farther back. After +scanning all the text before point, it searches the text after point. +The variable @code{dabbrev-limit}, if non-@code{nil}, specifies how far +in the buffer to search for an expansion. + +@vindex dabbrev-check-all-buffers + After scanning the current buffer, @kbd{M-/} normally searches other +buffers, unless you have set @code{dabbrev-check-all-buffers} to +@code{nil}. + + A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says to +search first for expansions after point, and second for expansions +before point. If you repeat the @kbd{M-/} to look for another +expansion, do not specify an argument. This tries all the expansions +after point and then the expansions before point. + + After you have expanded a dynamic abbrev, you can copy additional +words that follow the expansion in its original context. Simply type +@kbd{@key{SPC} M-/} for each word you want to copy. The spacing and +punctuation between words is copied along with the words. + + The command @kbd{C-M-/} (@code{dabbrev-completion}) performs +completion of a dynamic abbreviation. Instead of trying the possible +expansions one by one, it finds all of them, then inserts the text that +they have in common. If they have nothing in common, @kbd{C-M-/} +displays a list of completions, from which you can select a choice in +the usual manner. @xref{Completion}. + + Dynamic abbrev expansion is completely independent of Abbrev mode; the +expansion of a word with @kbd{M-/} is completely independent of whether +it has a definition as an ordinary abbrev. + +@node Dabbrev Customization +@section Customizing Dynamic Abbreviation + + Normally, dynamic abbrev expansion ignores case when searching for +expansions. That is, the expansion need not agree in case with the word +you are expanding. + +@vindex dabbrev-case-fold-search + This feature is controlled by the variable +@code{dabbrev-case-fold-search}. If it is @code{t}, case is ignored in +this search; if @code{nil}, the word and the expansion must match in +case. If the value of @code{dabbrev-case-fold-search} is +@code{case-fold-search}, which is true by default, then the variable +@code{case-fold-search} controls whether to ignore case while searching +for expansions. + +@vindex dabbrev-case-replace + Normally, dynamic abbrev expansion preserves the case pattern @emph{of +the abbrev you have typed}, by converting the expansion to that case +pattern. + +@vindex dabbrev-case-fold-search + The variable @code{dabbrev-case-replace} controls whether to preserve +the case pattern of the abbrev. If it is @code{t}, the abbrev's case +pattern is preserved in most cases; if @code{nil}, the expansion is +always copied verbatim. If the value of @code{dabbrev-case-replace} is +@code{case-replace}, which is true by default, then the variable +@code{case-replace} controls whether to copy the expansion verbatim. + + However, if the expansion contains a complex mixed case pattern, and +the abbrev matches this pattern as far as it goes, then the expansion is +always copied verbatim, regardless of those variables. Thus, for +example, if the buffer contains @code{variableWithSillyCasePattern}, and +you type @kbd{v a M-/}, it copies the expansion verbatim including its +case pattern. + +@vindex dabbrev-abbrev-char-regexp + The variable @code{dabbrev-abbrev-char-regexp}, if non-@code{nil}, +controls which characters are considered part of a word, for dynamic expansion +purposes. The regular expression must match just one character, never +two or more. The same regular expression also determines which +characters are part of an expansion. The value @code{nil} has a special +meaning: abbreviations are made of word characters, but expansions are +made of word and symbol characters. + +@vindex dabbrev-abbrev-skip-leading-regexp + In shell scripts and makefiles, a variable name is sometimes prefixed +with @samp{$} and sometimes not. Major modes for this kind of text can +customize dynamic abbreviation to handle optional prefixes by setting +the variable @code{dabbrev-abbrev-skip-leading-regexp}. Its value +should be a regular expression that matches the optional prefix that +dynamic abbreviation should ignore. diff --git a/man/ack.texi b/man/ack.texi new file mode 100644 index 00000000000..a6125e8610e --- /dev/null +++ b/man/ack.texi @@ -0,0 +1,902 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1994, 1995, 1996, 1997, 1999 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Acknowledgments, Screen, Concept Index, Top +@chapter Acknowledgments + +Many people have contributed code included in the Free Software +Foundation's distribution of GNU Emacs. To show our appreciation for +their public spirit, we list here those who have written substantial +portions. + +@itemize @bullet +@item +Per Abrahamsen wrote the customization buffer facilities, as well as +@file{double.el} for typing accented characters not normally available +from the keyboard, @file{xt-mouse.el} which handles mouse commands +through Xterm, and @file{cpp.el} which hides or highlights parts of C +programs according to preprocessor conditionals. + +@item +Jay K. Adams wrote @file{jka-compr.el}, providing automatic +decompression and recompression for compressed files. + +@item +Joe Arceneaux wrote the original text property implementation, and +implemented support for X11. + +@item +Boaz Ben-Zvi wrote @file{profile.el}, to time Emacs Lisp functions. + +@item +Jim Blandy wrote Emacs 19's input system, brought its configuration and +build process up to the GNU coding standards, and contributed to the +frame support and multi-face support. + +@item +Terrence M. Brannon wrote @file{landmark.el}, a neural-network robot +that learns landmarks. + +@item +Frank Bresz wrote @file{diff.el}, a program to display @code{diff} +output. + +@item +Peter Breton implemented @file{dirtrack} which does better tracking of +directory changes in shell buffers, @file{filecache.el} which records +which directories your files are in, @file{locate.el} which interfaces +to the @code{locate} command, @file{net-utils.el}, and the ``generic +mode'' feature. + +@item +Kevin Broadey wrote @file{foldout.el}, providing folding extensions to +Emacs's outline modes. + +@item +Vincent Broman wrote @file{ada.el}, a mode for editing Ada code +(since replaced by @file{ada-mode.el}). + +@item +David M. Brown wrote @file{array.el}, for editing arrays and other +tabular data. + +@item +Bill Carpenter provided @file{feedmail.el}. + +@item +Hans Chalupsky wrote @file{advice.el}, an overloading mechanism for +Emacs Lisp functions, and @file{trace.el}, a tracing facility for Emacs +Lisp. + +@item +Bob Chassell wrote @file{texnfo-upd.el} and @file{makeinfo.el}, modes +and utilities for working with Texinfo files. + +@item +James Clark wrote @file{sgml-mode.el}, a mode for editing SGML +documents, and contributed to Emacs's dumping procedures. + +@item +Mike Clarkson wrote @file{edt.el}, an emulation of DEC's EDT editor. + +@item +Glynn Clements provided @file{gamegrid.el} and a couple of games that +use it, Snake and Tetris. + +@item +Andrew Csillag wrote M4 mode (@file{m4-mode.el}). + +@item +Doug Cutting and Jamie Zawinski wrote @file{disass.el}, a disassembler +for compiled Emacs Lisp code. + +@item +Michael DeCorte wrote @file{emacs.csh}, a C-shell script that starts a +new Emacs job, or restarts a paused Emacs if one exists. + +@item +Gary Delp wrote @file{mailpost.el}, an interface between RMAIL and the +@file{/usr/uci/post} mailer. + +@item +Matthieu Devin wrote @file{delsel.el}, a package to make newly-typed +text replace the current selection. + +@item +Eric Ding contributed @file{goto-addr.el}, + +@item +Carsten Dominik wrote @file{reftex.el}, a package for setting up +labels and cross-references for La@TeX{}. + +@item +Scott Draves wrote @file{tq.el}, help functions for maintaining +transaction queues between Emacs and its subprocesses. + +@item +Viktor Dukhovni wrote support for dumping under SunOS version 4. + +@item +John Eaton co-wrote Octave mode (@file{octave.el} and related files). + +@item +Rolf Ebert co-wrote Ada mode (@file{ada-mode.el}). + +@item +Stephen Eglen implemented @file{mspools.el}, for use with Procmail, +which tells you which mail folders have mail waiting in them, and +@file{iswitchb.el}, a feature for incremental reading and completion of +buffer names. + +@item +@c iftex +Torbj@"orn +@c end iftex +@c ifinfo +@c Torbjorn +@c end ifinfo +Einarsson contributed F90 mode (@file{f90.el}). + +@item +Tsugutomo Enami co-wrote the support for international character sets. + +@item +Hans Henrik Eriksen wrote @file{simula.el}, a mode for editing SIMULA 87 +code. + +@item +Michael Ernst wrote @file{reposition.el}, a command for recentering a +function's source code and preceding comment on the screen. + +@item +Ata Etemadi wrote @file{cdl.el}, functions for working with Common Data +Language source code. + +@item +Frederick Farnback implemented @file{morse.el}, which converts text to +morse code. + +@item +Fred Fish wrote the support for dumping COFF executable files. + +@item +Karl Fogel wrote: +@itemize @bullet +@item +@file{bookmark.el}, for creating named placeholders, saving them and +jumping to them later, +@item +@file{mail-hist.el}, a history mechanism for outgoing mail messages, and +@item +@file{saveplace.el}, for preserving point's location in files between +editing sessions. +@end itemize + +@item +Gary Foster wrote the emulation for CRiSP: @file{crisp.el} and +@file{scroll-lock.el}. + +@item +Noah Friedman wrote @file{rlogin.el}, an interface to Rlogin, and +@file{type-break.el}, which reminds you to take periodic breaks from +typing. With Roland McGrath, he wrote @file{rsz-mini.el}, a minor mode +to automatically resize the minibuffer to fit the text it contains. + +@item +Keith Gabryelski wrote @file{hexl.el}, a mode for editing binary files. + +@item +Kevin Gallagher rewrote and enhanced the EDT emulation, and wrote +@file{flow-ctrl.el}, a package for coping with unsuppressible XON/XOFF +flow control. + +@item +Kevin Gallo added multiple-frame support for Windows NT. + +@item +Howard Gayle wrote: +@itemize @bullet +@item +the C and lisp code for display tables and case tables, +@item +@file{rot13.el}, a command to display the plaintext form of a buffer +encoded with the Caesar cipher, +@item +much of the support for the ISO-8859 European character set (which +includes @file{iso-ascii.el}, @file{iso-insert.el}, @file{iso-swed.el}, +@file{iso-syntax.el}, @file{iso-transl.el}, and @file{swedish.el}), and +@item +@file{vt100-led.el}, a package for controlling the LED's on +VT100-compatible terminals. +@end itemize + +@item +Stephen Gildea made the Emacs quick reference card. + +@item +David Gillespie wrote: +@itemize @bullet +@item +Emacs 19's Common Lisp compatibility packages, replacing the old package +by Cesar Augusto Quiroz Gonzalez, +@item +@file{complete.el}, a partial completion mechanism, and +@item +@file{edmacro.el}, a package for editing keyboard macros. +@end itemize + +@item +Bob Glickstein contributed the @file{sregex.el} feature. + +@item +Boris Goldowsky wrote @file{avoid.el}, a package to keep the mouse +cursor out of the way of the text cursor; @file{shadowfile.el}, a +package for keeping identical copies of files in more than one place; +@file{enriched.el}, a package for saving text properties in files; +and @file{facemenu.el}, a package for specifying faces. + +@item +Michelangelo Grigni wrote @file{ffap.el} which visits a file, +taking the file name from the buffer. + +@item +Odd Gripenstam wrote @file{dcl-mode.el}. + +@item +Michael Gschwind wrote @file{iso-cvt.el}, a package to convert between +the ISO 8859-1 character set and the notations for non-@code{ASCII} +characters used by @TeX{} and net tradition. + +@item +Henry Guillaume wrote @file{find-file.el}, a package to visit files +related to the currently visited file. + +@item +Doug Gwyn wrote the portable @code{alloca} implementation. + +@item +Ken'ichi Handa implemented most of the support for international +character sets. + +@item +Chris Hanson wrote @file{netuname.el}, a package to use HP-UX's Remote +File Access facility from Emacs. + +@item +K. Shane Hartman wrote: +@itemize @bullet +@item +@file{chistory.el} and @file{echistory.el}, packages for browsing +command history lists, +@item +@file{electric.el} and @file{helper.el}, providing an alternative +command loop and appropriate help facilities, +@item +@file{emacsbug.el}, a package for reporting Emacs bugs, +@item +@file{picture.el}, a mode for editing ASCII pictures, and +@item +@file{view.el}, a package for perusing files and buffers without editing +them. +@end itemize + +@item +John Heidemann wrote @file{mouse-copy.el} and @file{mouse-drag.el}, +which provide alternative mouse-based editing and scrolling features. + +@item +Markus Heritsch co-wrote Ada mode (@file{ada-mode.el}). + +@item +Karl Heuer wrote the original blessmail script, implemented the +@code{intangible} text property, and rearranged the structure of the +@code{Lisp_Object} type to allow for more data bits. + +@item +Manabu Higashida ported Emacs to the MS-DOS operating system. + +@item +Anders Holst wrote @file{hippie-exp.el}, a versatile completion and +expansion package. + +@item +Kurt Hornik co-wrote Octave mode (@file{octave.el} and related files). + +@item +Tom Houlder wrote @file{mantemp.el}, which generates manual C++ template +instantiations. + +@item +Lars Ingebrigtsen did a major redesign of the GNUS newsreader. + +@item +Andrew Innes contributed extensively to the Windows NT support. + +@item +Kyle Jones wrote @file{life.el}, a package to play Conway's ``life'' game, +and @file{mldrag.el}, a package which allows the user to resize windows +by dragging mode lines and vertical window separators with the mouse. + +@item +Tomoji Kagatani implemented @file{smtpmail.el}, used for sending out +mail with SMTP. + +@item +David Kaufman wrote @file{yow.c}, an essential utility program for the +hopelessly pinheaded. + +@item +Henry Kautz wrote @file{bib-mode.el}, a mode for maintaining +bibliography databases compatible with @code{refer} (the @code{troff} +version) and @code{lookbib}, and @file{refbib.el}, a package to convert +those databases to the format used by the LaTeX text formatting package. + +@item +Howard Kaye wrote @file{sort.el}, commands to sort text in Emacs +buffers. + +@item +Michael Kifer wrote @file{ediff.el}, an interactive interface to the +@code{diff} and @code{patch} programs, and Viper, the newest emulation +for VI. + +@item +Richard King wrote the first version of @file{userlock.el} and +@file{filelock.c}, which provide simple support for multiple users +editing the same file. +@c We're not using his backquote.el any more. + +@item +Larry K. Kolodney wrote @file{cvtmail.c}, a program to convert the mail +directories used by Gosling Emacs into RMAIL format. + +@item +Robert Krawitz wrote the original @file{xmenu.c}, part of Emacs's pop-up +menu support. + +@item +Sebastian Kremer wrote Emacs 19's @code{dired-mode}, with contributions +by Lawrence R. Dodd. + +@item +Geoff Kuenning wrote Emacs 19's @file{ispell.el}, based on work by Ken +Stevens and others. + +@item +David K@ringaccent{a}gedal wrote @file{tempo.el}, providing support for +easy insertion of boilerplate text and other common constructions. + +@item +Daniel LaLiberte wrote: +@itemize @bullet +@item +@file{edebug.el}, a source-level debugger for Emacs Lisp, +@item +@file{cl-specs.el}, specifications to help @code{edebug} debug code +written using David Gillespie's Common Lisp support, +@item +@file{cust-print.el}, a customizable package for printing lisp objects, +@item +@file{eval-reg.el}, a re-implementation of @code{eval-region} in Emacs +Lisp, and +@item +@file{isearch.el}, Emacs 19's incremental search minor mode. +@end itemize + +@item +James R. Larus wrote @file{mh-e.el}, an interface to the MH mail system. + +@item +Frederic Lepied contributed @file{expand.el}, which uses the abbrev +mechanism for inserting programming constructs. + +@item +Lars Lindberg wrote @file{msb.el}, which provides more flexible menus +for buffer selection, and rewrote @file{dabbrev.el}. + +@item +Eric Ludlam wrote the Speedbar package and @file{checkdoc.el}. + +@item +Neil M. Mager wrote @file{appt.el}, functions to notify users of their +appointments. It finds appointments recorded in the diary files +generated by Edward M. Reingold's @code{calendar} package. + +@item +Ken Manheimer wrote @file{allout.el}, a mode for manipulating and +formatting outlines, and @file{icomplete.el}, which provides incremental +completion feedback in the minibuffer. + +@item +Bill Mann wrote @file{perl-mode.el}, a mode for editing Perl code. + +@item +Brian Marick and Daniel LaLiberte wrote @file{hideif.el}, support for +hiding selected code within C @code{#ifdef} clauses. + +@item +Simon Marshall wrote: +@itemize @bullet +@item +@file{fast-lock.el}, which caches the face data computed by Font Lock mode, +@item +@file{lazy-lock.el}, which delays fontification in Font Lock mode +until text is actually displayed, and +@item +@file{regexp-opt.el}, which generates a regular expression from a list +of strings. +@end itemize + +@item +Bengt Martensson, Mark Shapiro, Mike Newton, Aaron Larson, and Stefan +Schoef, wrote @file{bibtex.el}, a mode for editing Bib@TeX{} +bibliography files. + +@item +Charlie Martin wrote @file{autoinsert.el}, which provides automatic +mode-sensitive insertion of text into new files. + +@item +Thomas May wrote @file{blackbox.el}, a version of the traditional +blackbox game. + +@item +Roland McGrath wrote: +@itemize @bullet +@item +@file{compile.el}, a package for running compilations in a buffer, and +then visiting the locations reported in error messages, +@item +@file{etags.el}, a package for jumping to function definitions and +searching or replacing in all the files mentioned in a @file{TAGS} file, +@item +@file{find-dired.el}, for using @code{dired} commands on output from the +@code{find} program, with Sebastian Kremer, +@item +@file{map-ynp.el}, a general purpose boolean question-asker, +@item +@file{autoload.el}, providing semi-automatic maintenance of autoload +files, and +@item +@file{upd-copyr.el}, providing semi-automatic maintenance of copyright +notices in source code. +@end itemize + +@item +David Megginson wrote @file{derived.el}, which allows one to define new +major modes by inheriting key bindings and commands from existing major +modes. + +@item +Wayne Mesard wrote @file{hscroll.el} which does horizontal scrolling +automatically. + +@item +Richard Mlynarik wrote: +@itemize @bullet +@item +@file{cl-indent.el}, a package for indenting Common Lisp code, +@item +@file{ebuff-menu.el}, an ``electric'' browser for buffer listings, +@item +@file{ehelp.el}, bindings for browsing help screens, +@item +@file{rfc822.el}, a parser for E-mail addresses in the RFC-822 format, +used in mail messages and news articles, +@item +@file{terminal.el}, a terminal emulator for Emacs subprocesses, and +@item +@file{yow.el}, an essential utility (try @kbd{M-x yow}). +@end itemize + +@item +Keith Moore wrote @file{aixcc.lex}, a pre-processor designed to help +Emacs parse the error messages produced by the AIX C compiler. + +@item +Erik Naggum wrote the time-conversion functions, and has tested the +latest source code daily. + +@item +Thomas Neumann and Eric Raymond wrote @file{makefile.el}, a mode for +editing makefiles. + +@item +Jurgen Nickelsen wrote @file{ws-mode.el}, providing WordStar emulation. + +@item +Jeff Norden wrote @file{kermit.el}, a package to help the Kermit +dialup communications program run comfortably in an Emacs shell buffer. + +@item +Andrew Norman wrote @file{ange-ftp.el}, providing transparent FTP support. + +@item +Jeff Peck wrote: +@itemize @bullet +@item +@file{emacstool.c}, support for running Emacs under SunView/Sun Windows, +@item +@file{sun-curs.el}, cursor definitions for Sun Windows, and +@item +@file{sun-fns.el}, providing mouse support for Sun Windows. +@end itemize + +@item +Damon Anton Permezel wrote @file{hanoi.el}, an animated demonstration of +the ``Towers of Hanoi'' puzzle. + +@item +Jens Petersen wrote @file{find-func.el}, which makes it easy to find +the source code for an Emacs Lisp function or variable. + +@item +Daniel Pfeiffer wrote: +@itemize @bullet +@item +@file{executable.el} +@item +@file{sh-script.el}, a mode for editing shell scripts, +@item +@file{skeleton.el}, implementing a concise language for writing +statement skeletons, and +@item +@file{two-column.el}, a minor mode for simultaneous two-column editing. +@end itemize + +@item +Fred Pierresteguy and Paul Reilly made Emacs work with X Toolkit +widgets. + +@item +Christian Plaunt wrote @file{soundex.el}, an implementation of the +Soundex algorithm for comparing English words by their pronunciation. + +@item +Francesco A. Potorti wrote @file{cmacexp.el}, providing a command which +runs the C preprocessor on a region of a file and displays the results. + +@item +Michael D. Prange and Steven A. Wood wrote @file{fortran.el}, a mode for +editing FORTRAN code. +@c We're not distributing his tex-mode.el anymore; we're using Ed Reingold's. + +@item +Ashwin Ram wrote @file{refer.el}, commands to look up references in +bibliography files by keyword. + +@item +Eric S. Raymond wrote: +@itemize @bullet +@item +@file{vc.el}, an interface to the RCS and SCCS source code version +control systems, with Paul Eggert, +@item +@file{gud.el}, a package for running source-level debuggers like GDB +and SDB in Emacs, +@item +@file{asm-mode.el}, a mode for editing assembly language code, +@item +@file{cookie1.el}, support for ``fortune-cookie'' programs like +@file{yow.el} and @file{spook.el}, +@item +@file{finder.el}, a package for finding Emacs Lisp packages by keyword +and topic, +@item +@file{lisp-mnt.el}, functions for working with the special headers used +in Emacs Lisp library files, and +@item +code to set and make use of the @code{load-history} lisp variable, which +records the source file from which each lisp function loaded into Emacs +came. +@end itemize + +@item +Edward M. Reingold wrote the extensive calendar and diary support (try +@kbd{M-x calendar}), with contributions from Stewart Clamen, Paul +Eggert, and Lara Rios. Andy Oram contributed to its documentation. +Reingold has also contributed to @file{tex-mode.el}, a mode for editing +@TeX{} files, as have William F. Schelter, Dick King, Stephen Gildea, +Michael Prange, and Jacob Gore. + +@item +Rob Riepel contributed @file{tpu-edt.el} and its associated files, +providing an emulation of the VMS TPU text editor emulating the VMS EDT +editor, and @file{vt-control.el}, providing some control functions for +the DEC VT line of terminals. + +@item +Roland B. Roberts contributed much of the VMS support distributed with +Emacs 19, along with Joseph M. Kelsey, and @file{vms-pmail.el}, support +for using Emacs within VMS MAIL. + +@item +John Robinson wrote @file{bg-mouse.el}, support for the mouse on the BBN +Bitgraph terminal. + +@item +Danny Roozendaal implemented @file{handwrite.el}, which converts text +into ``handwriting.'' + +@item +William Rosenblatt wrote @file{float.el}, implementing a floating-point +numeric type using Lisp cons cells and integers. + +@item +Guillermo J. Rozas wrote @file{scheme.el}, a mode for editing Scheme +code, and @file{fakemail.c}, an interface to the System V mailer. + +@item +Ivar Rummelhoff provided @file{winner.el}, which records +recent window configurations so you can move back to them. + +@item +Wolfgang Rupprecht contributed Emacs 19's floating-point support +(including @file{float-sup.el} and @file{floatfns.c}), and +@file{sup-mouse.el}, support for the Supdup mouse on lisp machines. + +@item +James B. Salem and Brewster Kahle wrote @file{completion.el}, providing +dynamic word completion. + +@item +Masahiko Sato wrote @file{vip.el}, an emulation of the VI editor. + +@item +William Schelter wrote @file{telnet.el}, support for @code{telnet} +sessions within Emacs. + +@item +Ralph Schleicher contributed @file{battery.el}, a package for displaying +laptop computer battery status, and @file{info-look.el}, a package for +looking up Info documentation for symbols in the buffer. + +@item +Gregor Schmid wrote @file{tcl.el}, a mode for editing Tcl/Tk scripts. + +@item +Michael Schmidt and Tom Perrine wrote @file{modula2.el}, a mode for +editing Modula-2 code, based on work by Mick Jordan and Peter Robinson. + +@item +Ronald S. Schnell wrote @file{dunnet.el}, a text adventure game. + +@item +Philippe Schnoebelen wrote @file{gomoku.el}, a Go Moku game played +against Emacs, and @file{mpuz.el}, a multiplication puzzle. + +@item +Randal Schwartz wrote @file{pp.el}, a pretty-printer for lisp objects. + +@item +Manuel Serrano contributed the Flyspell package that does spell checking +as you type. + +@item +Stanislav Shalunov wrote @file{uce.el}, for responding to unsolicited +commercial email. + +@item +Richard Sharman contributed @file{hilit-chg.el}, which uses colors +to inclidate recent editing changes. + +@item +Olin Shivers wrote: +@itemize @bullet +@item +@file{comint.el}, a library for modes running interactive command-line- +oriented subprocesses, +@item +@file{cmuscheme.el}, for running inferior Scheme processes, +@item +@file{inf-lisp.el}, for running inferior Lisp process, and +@item +@file{shell.el}, for running inferior shells. +@end itemize + +@item +Sam Shteingold wrote @file{gulp.el}. + +@item +Espen Skoglund wrote @file{pascal.el}, a mode for editing Pascal code. + +@item +Rick Sladkey wrote @file{backquote.el}, a lisp macro for creating +mostly-constant data. + +@item +Lynn Slater wrote @file{help-macro.el}, a macro for writing interactive +help for key bindings. + +@item +Chris Smith wrote @file{icon.el}, a mode for editing Icon code. + +@item +David Smith wrote @file{ielm.el}, a mode for interacting with the Emacs +Lisp interpreter as a subprocess. + +@item +Paul D. Smith wrote @file{snmp-mode.el}. + +@item +William Sommerfeld wrote @file{scribe.el}, a mode for editing Scribe +files, and @file{server.el}, a package allowing programs to send files +to an extant Emacs job to be edited. + +@item +Michael Staats wrote @file{pc-select.el}, which rebinds keys for +selecting regions to follow many other systems. + +@item +Ake Stenhoff and Lars Lindberg wrote @file{imenu.el}, a framework for +browsing indices made from buffer contents. + +@item +Peter Stephenson contributed @file{vcursor.el}, which implements a +``virtual cursor'' that you can move with the keyboard and use for +copying text. + +@item +Sam Steingold wrote @file{midnight.el}. + +@item +Jonathan Stigelman wrote @file{hilit19.el}, a package providing +automatic highlighting in source code buffers, mail readers, and other +contexts. + +@item +Steve Strassman did not write @file{spook.el}, and even if he did, he +really didn't mean for you to use it in an anarchistic way. + +@item +Jens T. Berger Thielemann wrote @file{word-help.el}, which is +part of the basis for @file{info-look.el}. + +@item +Spencer Thomas wrote the original @file{dabbrev.el}, providing a command +which completes the partial word before point, based on other nearby +words for which it is a prefix. He also wrote the original dumping +support. + +@item +Jim Thompson wrote @file{ps-print.el}, which converts +Emacs text to Postscript. + +@item +Masanobu Umeda wrote: +@itemize @bullet +@item +GNUS, a featureful reader for Usenet news, +@item +@file{prolog.el}, a mode for editing Prolog code, +@item +@file{rmailsort.el}, a package for sorting messages in RMAIL folders, +@item +@file{metamail.el}, an interface to the Metamail program, +@item +@file{tcp.el}, emulation of the @code{open-network-stream} function for +some Emacs configurations which lack it, and +@item +@file{timezone.el}, providing functions for dealing with time zones. +@end itemize + +@item +Neil W. Van Dyke wrote @file{webjump.el}, a ``hot links'' package. + +@item +Ulrik Vieth implemented @file{meta-mode.el}, for editing MetaFont code. + +@item +Geoffrey Voelker wrote the Windows NT support. + +@item +Johan Vromans wrote @file{forms.el} and its associated files, defining a +mode for filling in forms, and @file{iso-acc.el}, a minor mode providing +electric accent keys for text using the ISO-8859 character set. + +@item +Barry Warsaw wrote: +@itemize @bullet +@item +@file{assoc.el}, a set of utility functions for working with association +lists, +@item +@file{cc-mode.el}, a major mode for editing C and C++ code, based on +earlier work by Dave Detlefs, Stewart Clamen, and Richard Stallman, +@item +@file{elp.el}, a new profiler for Emacs Lisp programs. +@item +@file{man.el}, a mode for reading UNIX manual pages, +@item +@file{regi.el}, providing an AWK-like control structure for +use in lisp programs, and +@item +@file{reporter.el}, providing customizable bug reporting for lisp +packages. +@item +@file{supercite.el}, a minor mode for quoting sections of mail messages +and news articles, +@end itemize + +@item +Morten Welinder wrote: +@itemize @bullet +@item +@file{desktop.el}, facilities for saving some of Emacs's state between +sessions, +@item +@file{s-region.el}, commands for setting the region using the shift key +and motion commands, and +@item +@file{dos-fns.el}, functions for use under MS-DOS. +@end itemize + +He also helped port Emacs to MS-DOS. + +@item +Joseph Brian Wells wrote: +@itemize @bullet +@item +@file{apropos.el}, a command to find commands, functions, and variables +whose names contain matches for a regular expression, +@item +@file{resume.el}, support for processing command-line arguments after +resuming a suspended Emacs job, and +@item +@file{mail-extr.el}, a package for extracting names and addresses from +mail headers, with contributions from Jamie Zawinski. +@end itemize + +@item +Rodney Whitby and Reto Zimmermann wrote @file{vhdl-mode.el}. + +@item +Ed Wilkinson wrote @file{b2m.c}, a program to convert mail files from +RMAIL format to Unix @code{mbox} format. + +@item +Mike Williams wrote @file{mouse-sel.el}, providing enhanced mouse +selection, and @file{thingatpt.el}, a library of functions for finding +the ``thing'' (word, line, s-expression) containing point. + +@item +Dale R. Worley wrote @file{emerge.el}, a package for interactively +merging two versions of a file. + +@item +Tom Wurgler wrote @file{emacs-lock.el}, which makes it harder +to exit with valuable buffers unsaved. + +@item +Eli Zaretskii made many standard Emacs features work on MS-DOS. + +@item +Jamie Zawinski wrote: +@itemize @bullet +@item +Emacs 19's optimizing byte compiler, with Hallvard Furuseth, +@item +much of the support for faces and X selections, +@item +@file{mailabbrev.el}, a package providing automatic expansion of mail +aliases, and +@item +@file{tar-mode.el}, providing simple viewing and editing commands for +tar files. +@end itemize + +@item +Ian T. Zimmerman wrote @file{gametree.el}. + +@item +Neal Ziring and Felix S. T. Wu wrote @file{vi.el}, an emulation of the +VI text editor. +@end itemize + +Others too numerous to mention have reported and fixed bugs, and added +features to many parts of Emacs. We thank them for their generosity as +well. + +This list intended to mention every contributor of a major package or +feature we currently distribute; if you know of someone we have omitted, +please report that as a manual bug. diff --git a/man/anti.texi b/man/anti.texi new file mode 100644 index 00000000000..e493dff8dce --- /dev/null +++ b/man/anti.texi @@ -0,0 +1,166 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1997, 1999 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. + +@node Antinews, MS-DOS, Command Arguments, Top +@appendix Emacs 19 Antinews + + For those users who live backwards in time, here is information about +downgrading to Emacs version 19. We hope you will enjoy the greater +simplicity that results from the absence of certain Emacs 20 features. + +@itemize @bullet +@item +The multibyte character and end-of-line conversion support have been +eliminated entirely. (Some users consider this a tremendous +improvement.) Character codes are limited to the range 0 through 255 +and files imported onto Unix-like systems may have a ^M at the end of +each line to remind you to control MS-DOG type files. + +@item +Fontsets, coding systems and input methods have been eliminated as well. + +@item +The mode line normally displays the string @samp{Emacs}, in case you +forget what editor you are using. + +@item +Scroll bars always appear on the right-hand side of the window. +This clearly separates them from the text in the window. + +@item +The @kbd{M-x customize} feature has been replaced with a very simple +feature, @kbd{M-x edit-options}. This shows you @emph{all} the user +options right from the start, so you don't have to hunt for the ones you +want. It also provides a few commands, such as @kbd{s} and @kbd{x}, to +set a user option. + +@item +The @key{DELETE} key does nothing special in Emacs 19 when you use it +after selecting a region with the mouse. It does exactly the same thing +in that situation as it does at all other times: delete one character +backwards. + +@item +@kbd{C-x C-w} no longer changes the major mode according to the new file +name. If you want to change the mode, use @kbd{M-x normal-mode}. + +@item +In Transient Mark mode, each window displays highlighting for the region +as it exists in that window. + +@item +Outline mode doesn't use overlay properties; instead, it hides a line by +converting the preceding newline into code 015. Magically, however, if +you save the file, the 015 character appears in the file as a newline. + +@item +There is now a clever way you can activate the minibuffer recursively +even if @code{enable-recursive-minibuffers} is @code{nil}. All you have +to do is @emph{switch windows} to a non-minibuffer window, and then use a +minibuffer command. You can pile up any number of minibuffer levels +this way, but @kbd{M-x top-level} will get you out of all of them. + +@item +We have removed the limit on the length of minibuffer history lists; +they now contain all the minibuffer arguments you have used since the +beginning of the session. + +@item +Dynamic abbrev expansion now handles case conversion in a very simple +and straightforward way. If you have requested preserving case, it +always converts the entire expansion to the case pattern of the abbrev +that you have typed in. + +@item +The @code{compose-mail} command does not exist; @kbd{C-x m} now +runs @code{mail} directly. + +@item +There is no way to quote a file name with special characters in it. +What you see is what you get: if the name looks remote, it is remote. + +@item +@kbd{M-x grep-find} has been eliminated, because @code{grep} has never +been lost. + +@ignore +@item +Truth in advertising: @kbd{M-x grep} by default uses @code{grep}, the +whole @code{grep}, and nothing but the @code{grep}. If you want it to +use @code{zgrep}, you'll have to edit the search command by hand. +@end ignore + +@item +Some Dired commands have been rearranged: two-character sequences +have been replaced with quick single-character commands: + +@itemize @bullet +@item +For @code{dired-mark-executables}, type @kbd{*}. +@item +For @code{dired-mark-directories}, type @kbd{/}. +@item +For @code{dired-mark-symlinks}, type @kbd{@@}. +@item +For @code{dired-change-marks}, type @kbd{c}. +@item +For @code{dired-unmark-all-files}, type @kbd{C-M-?}. +@item +For @code{dired-unmark-all-marks}, type @kbd{C-M-? @key{RET}}. +@end itemize + +But if you want to use @code{dired-flag-garbage-files}, @kbd{&}, you'll +just have to stop living in the past. + +@item +In C mode, you can now specify your preferred style for block comments. +If you want to use the style + +@example +/* +blah +blah +*/ +@end example + +@noindent +then you should set the variable @code{c-block-comments-indent-p} to +@code{t}. + +@item +To customize faces used by Font Lock mode, use the variable +@code{font-lock-face-attributes}. See its documentation string for +details. + +@item +For efficiency, Font Lock mode now uses by default the minimum supported +level of decoration for the selected major mode. + +@item +If you kill a buffer, any registers holding saved positions in that +buffer are changed to point into limbo. + +@item +The function @code{set-frame-font} has been renamed to +@code{set-default-font}. + +@item +The variable @code{tex-main-file} doesn't exist. Of course, you can +create the variable by setting it, but that won't do anything special. + +@item +The @code{scroll-preserve-screen-position} variable has been eliminated; +and so has the feature that it controls. + +@item +We have eliminated the functions @code{add-untranslated-filesystem} and +@code{remove-untranslated-filesystem}, and replaced them with a simpler +function, @code{using-unix-filesystems}. + +@item +To keep up with decreasing computer memory capacity, many other +functions and files have been eliminated in Emacs 19. There's no need +to mention them all here. If you try to use one of them, you'll get an +error message to tell you that it is undefined or unbound. +@end itemize diff --git a/man/basic.texi b/man/basic.texi new file mode 100644 index 00000000000..f1819d83723 --- /dev/null +++ b/man/basic.texi @@ -0,0 +1,721 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Basic, Minibuffer, Exiting, Top +@chapter Basic Editing Commands + +@kindex C-h t +@findex help-with-tutorial + We now give the basics of how to enter text, make corrections, and +save the text in a file. If this material is new to you, you might +learn it more easily by running the Emacs learn-by-doing tutorial. To +use the tutorial, run Emacs and type @kbd{Control-h t} +(@code{help-with-tutorial}). + + To clear the screen and redisplay, type @kbd{C-l} (@code{recenter}). + +@menu + +* Inserting Text:: Inserting text by simply typing it. +* Moving Point:: How to move the cursor to the place where you want to + change something. +* Erasing:: Deleting and killing text. +* Undo:: Undoing recent changes in the text. +* Files: Basic Files. Visiting, creating, and saving files. +* Help: Basic Help. Asking what a character does. +* Blank Lines:: Commands to make or delete blank lines. +* Continuation Lines:: Lines too wide for the screen. +* Position Info:: What page, line, row, or column is point on? +* Arguments:: Numeric arguments for repeating a command. +* Repeating:: A short-cut for repeating the previous command. +@end menu + +@node Inserting Text +@section Inserting Text + +@cindex insertion +@cindex graphic characters + To insert printing characters into the text you are editing, just type +them. This inserts the characters you type into the buffer at the +cursor (that is, at @dfn{point}; @pxref{Point}). The cursor moves +forward, and any text after the cursor moves forward too. If the text +in the buffer is @samp{FOOBAR}, with the cursor before the @samp{B}, +then if you type @kbd{XX}, you get @samp{FOOXXBAR}, with the cursor +still before the @samp{B}. + + To @dfn{delete} text you have just inserted, use @key{DEL}. @key{DEL} +deletes the character @emph{before} the cursor (not the one that the cursor +is on top of or under; that is the character @var{after} the cursor). The +cursor and all characters after it move backwards. Therefore, if you type +a printing character and then type @key{DEL}, they cancel out. + +@kindex RET +@cindex newline + To end a line and start typing a new one, type @key{RET}. This +inserts a newline character in the buffer. If point is in the middle of +a line, @key{RET} splits the line. Typing @key{DEL} when the cursor is +at the beginning of a line deletes the preceding newline, thus joining +the line with the preceding line. + + Emacs can split lines automatically when they become too long, if you +turn on a special minor mode called @dfn{Auto Fill} mode. +@xref{Filling}, for how to use Auto Fill mode. + + If you prefer to have text characters replace (overwrite) existing +text rather than shove it to the right, you can enable Overwrite mode, +a minor mode. @xref{Minor Modes}. + +@cindex quoting +@kindex C-q +@findex quoted-insert + Direct insertion works for printing characters and @key{SPC}, but other +characters act as editing commands and do not insert themselves. If you +need to insert a control character or a character whose code is above 200 +octal, you must @dfn{quote} it by typing the character @kbd{Control-q} +(@code{quoted-insert}) first. (This character's name is normally written +@kbd{C-q} for short.) There are two ways to use @kbd{C-q}:@refill + +@itemize @bullet +@item +@kbd{C-q} followed by any non-graphic character (even @kbd{C-g}) +inserts that character. + +@item +@kbd{C-q} followed by a sequence of octal digits inserts the character +with the specified octal character code. You can use any number of +octal digits; any non-digit terminates the sequence. If the terminating +character is @key{RET}, it serves only to terminate the sequence; any +other non-digit is itself used as input after terminating the sequence. +(The use of octal sequences is disabled in ordinary non-binary Overwrite +mode, to give you a convenient way to insert a digit instead of +overwriting with it.) +@end itemize + +@noindent +When multibyte characters are enabled, octal codes 0200 through 0377 are +not valid as characters; if you specify a code in this range, @kbd{C-q} +assumes that you intend to use some ISO Latin-@var{n} character set, and +converts the specified code to the corresponding Emacs character code. +@xref{Enabling Multibyte}. You select @emph{which} ISO Latin character +set though your choice of language environment (@pxref{Language +Environments}). + +@vindex read-quoted-char-radix +To use decimal or hexadecimal instead of octal, set the variable +@code{read-quoted-char-radix} to 10 or 16. If the radix is greater than +10, some letters starting with @kbd{a} serve as part of a character +code, just like digits. + +A numeric argument to @kbd{C-q} specifies how many copies of the +quoted character should be inserted (@pxref{Arguments}). + +@findex newline +@findex self-insert + Customization information: @key{DEL} in most modes runs the command +@code{delete-backward-char}; @key{RET} runs the command @code{newline}, and +self-inserting printing characters run the command @code{self-insert}, +which inserts whatever character was typed to invoke it. Some major modes +rebind @key{DEL} to other commands. + +@node Moving Point +@section Changing the Location of Point + +@cindex arrow keys +@kindex LEFT +@kindex RIGHT +@kindex UP +@kindex DOWN +@cindex moving point +@cindex movement +@cindex cursor motion +@cindex moving the cursor + To do more than insert characters, you have to know how to move point +(@pxref{Point}). The simplest way to do this is with arrow keys, or by +clicking the left mouse button where you want to move to. + + There are also control and meta characters for cursor motion. Some +are equivalent to the arrow keys (these date back to the days before +terminals had arrow keys, and are usable on terminals which don't have +them). Others do more sophisticated things. + +@kindex C-a +@kindex C-e +@kindex C-f +@kindex C-b +@kindex C-n +@kindex C-p +@kindex M-> +@kindex M-< +@kindex M-r +@findex beginning-of-line +@findex end-of-line +@findex forward-char +@findex backward-char +@findex next-line +@findex previous-line +@findex beginning-of-buffer +@findex end-of-buffer +@findex goto-char +@findex goto-line +@findex move-to-window-line +@table @kbd +@item C-a +Move to the beginning of the line (@code{beginning-of-line}). +@item C-e +Move to the end of the line (@code{end-of-line}). +@item C-f +Move forward one character (@code{forward-char}). +@item C-b +Move backward one character (@code{backward-char}). +@item M-f +Move forward one word (@code{forward-word}). +@item M-b +Move backward one word (@code{backward-word}). +@item C-n +Move down one line, vertically (@code{next-line}). This command +attempts to keep the horizontal position unchanged, so if you start in +the middle of one line, you end in the middle of the next. When on +the last line of text, @kbd{C-n} creates a new line and moves onto it. +@item C-p +Move up one line, vertically (@code{previous-line}). +@item M-r +Move point to left margin, vertically centered in the window +(@code{move-to-window-line}). Text does not move on the screen. + +A numeric argument says which screen line to place point on. It counts +screen lines down from the top of the window (zero for the top line). A +negative argument counts lines from the bottom (@minus{}1 for the bottom +line). +@item M-< +Move to the top of the buffer (@code{beginning-of-buffer}). With +numeric argument @var{n}, move to @var{n}/10 of the way from the top. +@xref{Arguments}, for more information on numeric arguments.@refill +@item M-> +Move to the end of the buffer (@code{end-of-buffer}). +@item M-x goto-char +Read a number @var{n} and move point to buffer position @var{n}. +Position 1 is the beginning of the buffer. +@item M-x goto-line +Read a number @var{n} and move point to line number @var{n}. Line 1 +is the beginning of the buffer. +@item C-x C-n +@findex set-goal-column +@kindex C-x C-n +Use the current column of point as the @dfn{semipermanent goal column} for +@kbd{C-n} and @kbd{C-p} (@code{set-goal-column}). Henceforth, those +commands always move to this column in each line moved into, or as +close as possible given the contents of the line. This goal column remains +in effect until canceled. +@item C-u C-x C-n +Cancel the goal column. Henceforth, @kbd{C-n} and @kbd{C-p} once +again try to stick to a fixed horizontal position, as usual. +@end table + +@vindex track-eol + If you set the variable @code{track-eol} to a non-@code{nil} value, +then @kbd{C-n} and @kbd{C-p} when at the end of the starting line move +to the end of another line. Normally, @code{track-eol} is @code{nil}. +@xref{Variables}, for how to set variables such as @code{track-eol}. + +@vindex next-line-add-newlines + Normally, @kbd{C-n} on the last line of a buffer appends a newline to +it. If the variable @code{next-line-add-newlines} is @code{nil}, then +@kbd{C-n} gets an error instead (like @kbd{C-p} on the first line). + +@node Erasing +@section Erasing Text + +@table @kbd +@item @key{DEL} +Delete the character before point (@code{delete-backward-char}). +@item C-d +Delete the character after point (@code{delete-char}). +@item C-k +Kill to the end of the line (@code{kill-line}). +@item M-d +Kill forward to the end of the next word (@code{kill-word}). +@item M-@key{DEL} +Kill back to the beginning of the previous word +(@code{backward-kill-word}). +@end table + +@cindex killing characters and lines +@cindex deleting characters and lines +@cindex erasing characters and lines + You already know about the @key{DEL} key which deletes the character +before point (that is, before the cursor). Another key, @kbd{Control-d} +(@kbd{C-d} for short), deletes the character after point (that is, the +character that the cursor is on). This shifts the rest of the text on +the line to the left. If you type @kbd{C-d} at the end of a line, it +joins together that line and the next line. + + To erase a larger amount of text, use the @kbd{C-k} key, which kills a +line at a time. If you type @kbd{C-k} at the beginning or middle of a +line, it kills all the text up to the end of the line. If you type +@kbd{C-k} at the end of a line, it joins that line and the next line. + + @xref{Killing}, for more flexible ways of killing text. + +@node Undo +@section Undoing Changes +@cindex undo +@cindex changes, undoing + + You can undo all the recent changes in the buffer text, up to a +certain point. Each buffer records changes individually, and the undo +command always applies to the current buffer. Usually each editing +command makes a separate entry in the undo records, but some commands +such as @code{query-replace} make many entries, and very simple commands +such as self-inserting characters are often grouped to make undoing less +tedious. + +@table @kbd +@item C-x u +Undo one batch of changes---usually, one command worth (@code{undo}). +@item C-_ +The same. +@item C-u C-x u +Undo one batch of changes in the region. +@end table + +@kindex C-x u +@kindex C-_ +@findex undo + The command @kbd{C-x u} or @kbd{C-_} is how you undo. The first time +you give this command, it undoes the last change. Point moves back to +where it was before the command that made the change. + + Consecutive repetitions of @kbd{C-_} or @kbd{C-x u} undo earlier and +earlier changes, back to the limit of the undo information available. +If all recorded changes have already been undone, the undo command +prints an error message and does nothing. + + Any command other than an undo command breaks the sequence of undo +commands. Starting from that moment, the previous undo commands become +ordinary changes that you can undo. Thus, to redo changes you have +undone, type @kbd{C-f} or any other command that will harmlessly break +the sequence of undoing, then type more undo commands. + +@cindex selective undo +@kindex C-u C-x u + Ordinary undo applies to all changes made in the current buffer. You +can also perform @dfn{selective undo}, limited to the current region. +To do this, specify the region you want, then run the @code{undo} +command with a prefix argument (the value does not matter): @kbd{C-u C-x +u} or @kbd{C-u C-_}. This undoes the most recent change in the region. +To undo further changes in the same region, repeat the @code{undo} +command (no prefix argument is needed). In Transient Mark mode, any use +of @code{undo} when there is an active region performs selective undo; +you do not need a prefix argument. + + If you notice that a buffer has been modified accidentally, the +easiest way to recover is to type @kbd{C-_} repeatedly until the stars +disappear from the front of the mode line. At this time, all the +modifications you made have been canceled. Whenever an undo command +makes the stars disappear from the mode line, it means that the buffer +contents are the same as they were when the file was last read in or +saved. + + If you do not remember whether you changed the buffer deliberately, +type @kbd{C-_} once. When you see the last change you made undone, you +will see whether it was an intentional change. If it was an accident, +leave it undone. If it was deliberate, redo the change as described +above. + + Not all buffers record undo information. Buffers whose names start with +spaces don't; these buffers are used internally by Emacs and its extensions +to hold text that users don't normally look at or edit. + + You cannot undo mere cursor motion; only changes in the buffer +contents save undo information. However, some cursor motion commands +set the mark, so if you use these commands from time to time, you can +move back to the neighborhoods you have moved through by popping the +mark ring (@pxref{Mark Ring}). + +@vindex undo-limit +@vindex undo-strong-limit +@cindex undo limit + When the undo information for a buffer becomes too large, Emacs +discards the oldest undo information from time to time (during garbage +collection). You can specify how much undo information to keep by +setting two variables: @code{undo-limit} and @code{undo-strong-limit}. +Their values are expressed in units of bytes of space. + + The variable @code{undo-limit} sets a soft limit: Emacs keeps undo +data for enough commands to reach this size, and perhaps exceed it, but +does not keep data for any earlier commands beyond that. Its default +value is 20000. The variable @code{undo-strong-limit} sets a stricter +limit: the command which pushes the size past this amount is itself +forgotten. Its default value is 30000. + + Regardless of the values of those variables, the most recent change is +never discarded, so there is no danger that garbage collection occurring +right after an unintentional large change might prevent you from undoing +it. + + The reason the @code{undo} command has two keys, @kbd{C-x u} and +@kbd{C-_}, set up to run it is that it is worthy of a single-character +key, but on some keyboards it is not obvious how to type @kbd{C-_}. +@kbd{C-x u} is an alternative you can type straightforwardly on any +terminal. + +@node Basic Files +@section Files + + The commands described above are sufficient for creating and altering +text in an Emacs buffer; the more advanced Emacs commands just make +things easier. But to keep any text permanently you must put it in a +@dfn{file}. Files are named units of text which are stored by the +operating system for you to retrieve later by name. To look at or use +the contents of a file in any way, including editing the file with +Emacs, you must specify the file name. + + Consider a file named @file{/usr/rms/foo.c}. In Emacs, to begin editing +this file, type + +@example +C-x C-f /usr/rms/foo.c @key{RET} +@end example + +@noindent +Here the file name is given as an @dfn{argument} to the command @kbd{C-x +C-f} (@code{find-file}). That command uses the @dfn{minibuffer} to +read the argument, and you type @key{RET} to terminate the argument +(@pxref{Minibuffer}).@refill + + Emacs obeys the command by @dfn{visiting} the file: creating a buffer, +copying the contents of the file into the buffer, and then displaying +the buffer for you to edit. If you alter the text, you can @dfn{save} +the new text in the file by typing @kbd{C-x C-s} (@code{save-buffer}). +This makes the changes permanent by copying the altered buffer contents +back into the file @file{/usr/rms/foo.c}. Until you save, the changes +exist only inside Emacs, and the file @file{foo.c} is unaltered. + + To create a file, just visit the file with @kbd{C-x C-f} as if it +already existed. This creates an empty buffer in which you can insert +the text you want to put in the file. The file is actually created when +you save this buffer with @kbd{C-x C-s}. + + Of course, there is a lot more to learn about using files. @xref{Files}. + +@node Basic Help +@section Help + +@cindex getting help with keys + If you forget what a key does, you can find out with the Help +character, which is @kbd{C-h} (or @key{F1}, which is an alias for +@kbd{C-h}). Type @kbd{C-h k} followed by the key you want to know +about; for example, @kbd{C-h k C-n} tells you all about what @kbd{C-n} +does. @kbd{C-h} is a prefix key; @kbd{C-h k} is just one of its +subcommands (the command @code{describe-key}). The other subcommands of +@kbd{C-h} provide different kinds of help. Type @kbd{C-h} twice to get +a description of all the help facilities. @xref{Help}.@refill + +@node Blank Lines +@section Blank Lines + +@cindex inserting blank lines +@cindex deleting blank lines + Here are special commands and techniques for putting in and taking out +blank lines. + +@c widecommands +@table @kbd +@item C-o +Insert one or more blank lines after the cursor (@code{open-line}). +@item C-x C-o +Delete all but one of many consecutive blank lines +(@code{delete-blank-lines}). +@end table + +@kindex C-o +@kindex C-x C-o +@cindex blank lines +@findex open-line +@findex delete-blank-lines + When you want to insert a new line of text before an existing line, you +can do it by typing the new line of text, followed by @key{RET}. +However, it may be easier to see what you are doing if you first make a +blank line and then insert the desired text into it. This is easy to do +using the key @kbd{C-o} (@code{open-line}), which inserts a newline +after point but leaves point in front of the newline. After @kbd{C-o}, +type the text for the new line. @kbd{C-o F O O} has the same effect as +@w{@kbd{F O O @key{RET}}}, except for the final location of point. + + You can make several blank lines by typing @kbd{C-o} several times, or +by giving it a numeric argument to tell it how many blank lines to make. +@xref{Arguments}, for how. If you have a fill prefix, then @kbd{C-o} +command inserts the fill prefix on the new line, when you use it at the +beginning of a line. @xref{Fill Prefix}. + + The easy way to get rid of extra blank lines is with the command +@kbd{C-x C-o} (@code{delete-blank-lines}). @kbd{C-x C-o} in a run of +several blank lines deletes all but one of them. @kbd{C-x C-o} on a +solitary blank line deletes that blank line. When point is on a +nonblank line, @kbd{C-x C-o} deletes any blank lines following that +nonblank line. + +@node Continuation Lines +@section Continuation Lines + +@cindex continuation line +@cindex wrapping +@cindex line wrapping + If you add too many characters to one line without breaking it with +@key{RET}, the line will grow to occupy two (or more) lines on the screen, +with a @samp{\} at the extreme right margin of all but the last of them. +The @samp{\} says that the following screen line is not really a distinct +line in the text, but just the @dfn{continuation} of a line too long to fit +the screen. Continuation is also called @dfn{line wrapping}. + + Sometimes it is nice to have Emacs insert newlines automatically when +a line gets too long. Continuation on the screen does not do that. Use +Auto Fill mode (@pxref{Filling}) if that's what you want. + +@vindex truncate-lines +@cindex truncation + As an alternative to continuation, Emacs can display long lines by +@dfn{truncation}. This means that all the characters that do not fit in +the width of the screen or window do not appear at all. They remain in +the buffer, temporarily invisible. @samp{$} is used in the last column +instead of @samp{\} to inform you that truncation is in effect. + + Truncation instead of continuation happens whenever horizontal +scrolling is in use, and optionally in all side-by-side windows +(@pxref{Windows}). You can enable truncation for a particular buffer by +setting the variable @code{truncate-lines} to non-@code{nil} in that +buffer. (@xref{Variables}.) Altering the value of +@code{truncate-lines} makes it local to the current buffer; until that +time, the default value is in effect. The default is initially +@code{nil}. @xref{Locals}. + + @xref{Display Vars}, for additional variables that affect how text is +displayed. + +@node Position Info +@section Cursor Position Information + + Here are commands to get information about the size and position of +parts of the buffer, and to count lines. + +@table @kbd +@item M-x what-page +Print page number of point, and line number within page. +@item M-x what-line +Print line number of point in the buffer. +@item M-x line-number-mode +Toggle automatic display of current line number. +@item M-= +Print number of lines in the current region (@code{count-lines-region}). +@xref{Mark}, for information about the region. +@item C-x = +Print character code of character after point, character position of +point, and column of point (@code{what-cursor-position}). +@end table + +@findex what-page +@findex what-line +@cindex line number commands +@cindex location of point +@cindex cursor location +@cindex point location + There are two commands for working with line numbers. @kbd{M-x +what-line} computes the current line number and displays it in the echo +area. To go to a given line by number, use @kbd{M-x goto-line}; it +prompts you for the number. These line numbers count from one at the +beginning of the buffer. + + You can also see the current line number in the mode line; @xref{Mode +Line}. If you narrow the buffer, then the line number in the mode line +is relative to the accessible portion (@pxref{Narrowing}). By contrast, +@code{what-line} shows both the line number relative to the narrowed +region and the line number relative to the whole buffer. + + By contrast, @kbd{M-x what-page} counts pages from the beginning of +the file, and counts lines within the page, printing both numbers. +@xref{Pages}. + +@kindex M-= +@findex count-lines-region + While on this subject, we might as well mention @kbd{M-=} (@code{count-lines-region}), +which prints the number of lines in the region (@pxref{Mark}). +@xref{Pages}, for the command @kbd{C-x l} which counts the lines in the +current page. + +@kindex C-x = +@findex what-cursor-position + The command @kbd{C-x =} (@code{what-cursor-position}) can be used to find out +the column that the cursor is in, and other miscellaneous information about +point. It prints a line in the echo area that looks like this: + +@smallexample +Char: c (0143, 99, 0x63) point=21044 of 26883(78%) column 53 +@end smallexample + +@noindent +(In fact, this is the output produced when point is before the +@samp{column} in the example.) + + The four values after @samp{Char:} describe the character that follows +point, first by showing it and then by giving its character code in +octal, decimal and hex. For a non-ASCII multibyte character, these are +followed by @samp{ext} and the character's representation, in hex, in +the buffer's coding system, if that coding system encodes the character +safely and with a single byte (@pxref{Coding Systems}). If the +character's encoding is longer than one byte, Emacs shows @samp{ext ...}. + + @samp{point=} is followed by the position of point expressed as a character +count. The front of the buffer counts as position 1, one character later +as 2, and so on. The next, larger, number is the total number of characters +in the buffer. Afterward in parentheses comes the position expressed as a +percentage of the total size. + + @samp{column} is followed by the horizontal position of point, in +columns from the left edge of the window. + + If the buffer has been narrowed, making some of the text at the +beginning and the end temporarily inaccessible, @kbd{C-x =} prints +additional text describing the currently accessible range. For example, it +might display this: + +@smallexample +Char: C (0103, 67, 0x43) point=252 of 889(28%) <231 - 599> column 0 +@end smallexample + +@noindent +where the two extra numbers give the smallest and largest character +position that point is allowed to assume. The characters between those +two positions are the accessible ones. @xref{Narrowing}. + + If point is at the end of the buffer (or the end of the accessible +part), the @w{@kbd{C-x =}} output does not describe a character after +point. The output might look like this: + +@smallexample +point=26957 of 26956(100%) column 0 +@end smallexample + + @w{@kbd{C-u C-x =}} displays additional information about a character, +in place of the buffer coordinates and column: the character set name +and the codes that identify the character within that character set; +ASCII characters are identified as belonging to the @code{ASCII} +character set. In addition, the full character encoding, even if it +takes more than a single byte, is shown after @samp{ext}. Here's an +example for a Latin-1 character A with a grave accent in a buffer whose +coding system is iso-2022-7bit@footnote{On terminals that support +Latin-1 characters, the character shown after @samp{Char:} is displayed +as the actual glyph of A with grave accent.}: + +@example +Char: @`A (04300, 2240, 0x8c0, ext ESC , A @@) (latin-iso8859-1 64) +@end example + +@node Arguments +@section Numeric Arguments +@cindex numeric arguments +@cindex prefix arguments +@cindex arguments, numeric +@cindex arguments, prefix + + In mathematics and computer usage, the word @dfn{argument} means +``data provided to a function or operation.'' You can give any Emacs +command a @dfn{numeric argument} (also called a @dfn{prefix argument}). +Some commands interpret the argument as a repetition count. For +example, @kbd{C-f} with an argument of ten moves forward ten characters +instead of one. With these commands, no argument is equivalent to an +argument of one. Negative arguments tell most such commands to move or +act in the opposite direction. + +@kindex M-1 +@kindex M-@t{-} +@findex digit-argument +@findex negative-argument + If your terminal keyboard has a @key{META} key, the easiest way to +specify a numeric argument is to type digits and/or a minus sign while +holding down the @key{META} key. For example, +@example +M-5 C-n +@end example +@noindent +would move down five lines. The characters @kbd{Meta-1}, @kbd{Meta-2}, +and so on, as well as @kbd{Meta--}, do this because they are keys bound +to commands (@code{digit-argument} and @code{negative-argument}) that +are defined to contribute to an argument for the next command. Digits +and @kbd{-} modified with Control, or Control and Meta, also specify +numeric arguments. + +@kindex C-u +@findex universal-argument + Another way of specifying an argument is to use the @kbd{C-u} +(@code{universal-argument}) command followed by the digits of the +argument. With @kbd{C-u}, you can type the argument digits without +holding down modifier keys; @kbd{C-u} works on all terminals. To type a +negative argument, type a minus sign after @kbd{C-u}. Just a minus sign +without digits normally means @minus{}1. + + @kbd{C-u} followed by a character which is neither a digit nor a minus +sign has the special meaning of ``multiply by four.'' It multiplies the +argument for the next command by four. @kbd{C-u} twice multiplies it by +sixteen. Thus, @kbd{C-u C-u C-f} moves forward sixteen characters. This +is a good way to move forward ``fast,'' since it moves about 1/5 of a line +in the usual size screen. Other useful combinations are @kbd{C-u C-n}, +@kbd{C-u C-u C-n} (move down a good fraction of a screen), @kbd{C-u C-u +C-o} (make ``a lot'' of blank lines), and @kbd{C-u C-k} (kill four +lines).@refill + + Some commands care only about whether there is an argument, and not about +its value. For example, the command @kbd{M-q} (@code{fill-paragraph}) with +no argument fills text; with an argument, it justifies the text as well. +(@xref{Filling}, for more information on @kbd{M-q}.) Plain @kbd{C-u} is a +handy way of providing an argument for such commands. + + Some commands use the value of the argument as a repeat count, but do +something peculiar when there is no argument. For example, the command +@kbd{C-k} (@code{kill-line}) with argument @var{n} kills @var{n} lines, +including their terminating newlines. But @kbd{C-k} with no argument is +special: it kills the text up to the next newline, or, if point is right at +the end of the line, it kills the newline itself. Thus, two @kbd{C-k} +commands with no arguments can kill a nonblank line, just like @kbd{C-k} +with an argument of one. (@xref{Killing}, for more information on +@kbd{C-k}.)@refill + + A few commands treat a plain @kbd{C-u} differently from an ordinary +argument. A few others may treat an argument of just a minus sign +differently from an argument of @minus{}1. These unusual cases are +described when they come up; they are always for reasons of convenience +of use of the individual command. + + You can use a numeric argument to insert multiple copies of a +character. This is straightforward unless the character is a digit; for +example, @kbd{C-u 6 4 a} inserts 64 copies of the character @samp{a}. +But this does not work for inserting digits; @kbd{C-u 6 4 1} specifies +an argument of 641, rather than inserting anything. To separate the +digit to insert from the argument, type another @kbd{C-u}; for example, +@kbd{C-u 6 4 C-u 1} does insert 64 copies of the character @samp{1}. + + We use the term ``prefix argument'' as well as ``numeric argument'' to +emphasize that you type the argument before the command, and to +distinguish these arguments from minibuffer arguments that come after +the command. + +@node Repeating +@section Repeating a Command +@cindex repeating a command + +@kindex C-x z +@findex repeat + The command @kbd{C-x z} (@code{repeat}) provides another way to repeat +an Emacs command many times. This command repeats the previous Emacs +command, whatever that was. Repeating a command uses the same arguments +that were used before; it does not read new arguments each time. + + To repeat the command more than once, type additional @kbd{z}'s: each +@kbd{z} repeats the command one more time. Repetition ends when you +type a character other than @kbd{z}, or press a mouse button. + + For example, suppose you type @kbd{C-u 2 0 C-d} to delete 20 +characters. You can repeat that command (including its argument) three +additional times, to delete a total of 80 characters, by typing @kbd{C-x +z z z}. The first @kbd{C-x z} repeats the command once, and each +subsequent @kbd{z} repeats it once again. + diff --git a/man/buffers.texi b/man/buffers.texi new file mode 100644 index 00000000000..f333f9ae1b1 --- /dev/null +++ b/man/buffers.texi @@ -0,0 +1,413 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Buffers, Windows, Files, Top +@chapter Using Multiple Buffers + +@cindex buffers + The text you are editing in Emacs resides in an object called a +@dfn{buffer}. Each time you visit a file, a buffer is created to hold the +file's text. Each time you invoke Dired, a buffer is created to hold the +directory listing. If you send a message with @kbd{C-x m}, a buffer named +@samp{*mail*} is used to hold the text of the message. When you ask for a +command's documentation, that appears in a buffer called @samp{*Help*}. + +@cindex selected buffer +@cindex current buffer + At any time, one and only one buffer is @dfn{selected}. It is also +called the @dfn{current buffer}. Often we say that a command operates on +``the buffer'' as if there were only one; but really this means that the +command operates on the selected buffer (most commands do). + + When Emacs has multiple windows, each window has a chosen buffer which +is displayed there, but at any time only one of the windows is selected and +its chosen buffer is the selected buffer. Each window's mode line displays +the name of the buffer that the window is displaying (@pxref{Windows}). + + Each buffer has a name, which can be of any length, and you can select +any buffer by giving its name. Most buffers are made by visiting files, +and their names are derived from the files' names. But you can also create +an empty buffer with any name you want. A newly started Emacs has a buffer +named @samp{*scratch*} which can be used for evaluating Lisp expressions in +Emacs. The distinction between upper and lower case matters in buffer +names. + + Each buffer records individually what file it is visiting, whether it is +modified, and what major mode and minor modes are in effect in it +(@pxref{Major Modes}). Any Emacs variable can be made @dfn{local to} a +particular buffer, meaning its value in that buffer can be different from +the value in other buffers. @xref{Locals}. + +@menu +* Select Buffer:: Creating a new buffer or reselecting an old one. +* List Buffers:: Getting a list of buffers that exist. +* Misc Buffer:: Renaming; changing read-onlyness; copying text. +* Kill Buffer:: Killing buffers you no longer need. +* Several Buffers:: How to go through the list of all buffers + and operate variously on several of them. +* Indirect Buffers:: An indirect buffer shares the text of another buffer. +@end menu + +@node Select Buffer +@section Creating and Selecting Buffers +@cindex change buffers +@cindex switch buffers + +@table @kbd +@item C-x b @var{buffer} @key{RET} +Select or create a buffer named @var{buffer} (@code{switch-to-buffer}). +@item C-x 4 b @var{buffer} @key{RET} +Similar, but select @var{buffer} in another window +(@code{switch-to-buffer-other-window}). +@item C-x 5 b @var{buffer} @key{RET} +Similar, but select @var{buffer} in a separate frame +(@code{switch-to-buffer-other-frame}). +@end table + +@kindex C-x 4 b +@findex switch-to-buffer-other-window +@kindex C-x 5 b +@findex switch-to-buffer-other-frame +@kindex C-x b +@findex switch-to-buffer + To select the buffer named @var{bufname}, type @kbd{C-x b @var{bufname} +@key{RET}}. This runs the command @code{switch-to-buffer} with argument +@var{bufname}. You can use completion on an abbreviation for the buffer +name you want (@pxref{Completion}). An empty argument to @kbd{C-x b} +specifies the most recently selected buffer that is not displayed in any +window.@refill + + Most buffers are created by visiting files, or by Emacs commands that +want to display some text, but you can also create a buffer explicitly +by typing @kbd{C-x b @var{bufname} @key{RET}}. This makes a new, empty +buffer that is not visiting any file, and selects it for editing. Such +buffers are used for making notes to yourself. If you try to save one, +you are asked for the file name to use. The new buffer's major mode is +determined by the value of @code{default-major-mode} (@pxref{Major +Modes}). + + Note that @kbd{C-x C-f}, and any other command for visiting a file, +can also be used to switch to an existing file-visiting buffer. +@xref{Visiting}. + + Emacs uses buffer names that start with a space for internal purposes. +It treats these buffers specially in minor ways---for example, by +default they do not record undo information. It is best to avoid using +such buffer names yourself. + +@node List Buffers +@section Listing Existing Buffers + +@table @kbd +@item C-x C-b +List the existing buffers (@code{list-buffers}). +@end table + +@cindex listing current buffers +@kindex C-x C-b +@findex list-buffers + To display a list of all the buffers that exist, type @kbd{C-x C-b}. +Each line in the list shows one buffer's name, major mode and visited +file. The buffers are listed in the order that they were current; the +buffers that were current most recently come first. + + @samp{*} at the beginning of a line indicates the buffer is ``modified.'' +If several buffers are modified, it may be time to save some with @kbd{C-x s} +(@pxref{Saving}). @samp{%} indicates a read-only buffer. @samp{.} marks the +selected buffer. Here is an example of a buffer list:@refill + +@smallexample + MR Buffer Size Mode File + -- ------ ---- ---- ---- +.* emacs.tex 383402 Texinfo /u2/emacs/man/emacs.tex + *Help* 1287 Fundamental + files.el 23076 Emacs-Lisp /u2/emacs/lisp/files.el + % RMAIL 64042 RMAIL /u/rms/RMAIL + *% man 747 Dired /u2/emacs/man/ + net.emacs 343885 Fundamental /u/rms/net.emacs + fileio.c 27691 C /u2/emacs/src/fileio.c + NEWS 67340 Text /u2/emacs/etc/NEWS + *scratch* 0 Lisp Interaction +@end smallexample + +@noindent +Note that the buffer @samp{*Help*} was made by a help request; it is not +visiting any file. The buffer @code{man} was made by Dired on the +directory @file{/u2/emacs/man/}. + +@need 2000 +@node Misc Buffer +@section Miscellaneous Buffer Operations + +@table @kbd +@item C-x C-q +Toggle read-only status of buffer (@code{vc-toggle-read-only}). +@item M-x rename-buffer @key{RET} @var{name} @key{RET} +Change the name of the current buffer. +@item M-x rename-uniquely +Rename the current buffer by adding @samp{<@var{number}>} to the end. +@item M-x view-buffer @key{RET} @var{buffer} @key{RET} +Scroll through buffer @var{buffer}. +@end table + +@kindex C-x C-q +@findex vc-toggle-read-only +@vindex buffer-read-only +@cindex read-only buffer + A buffer can be @dfn{read-only}, which means that commands to change +its contents are not allowed. The mode line indicates read-only buffers +with @samp{%%} or @samp{%*} near the left margin. Read-only buffers are +usually made by subsystems such as Dired and Rmail that have special +commands to operate on the text; also by visiting a file whose access +control says you cannot write it. + + If you wish to make changes in a read-only buffer, use the command +@kbd{C-x C-q} (@code{vc-toggle-read-only}). It makes a read-only buffer +writable, and makes a writable buffer read-only. In most cases, this +works by setting the variable @code{buffer-read-only}, which has a local +value in each buffer and makes the buffer read-only if its value is +non-@code{nil}. If the file is maintained with version control, +@kbd{C-x C-q} works through the version control system to change the +read-only status of the file as well as the buffer. @xref{Version +Control}. + +@findex rename-buffer + @kbd{M-x rename-buffer} changes the name of the current buffer. Specify +the new name as a minibuffer argument. There is no default. If you +specify a name that is in use for some other buffer, an error happens and +no renaming is done. + + @kbd{M-x rename-uniquely} renames the current buffer to a similar name +with a numeric suffix added to make it both different and unique. This +command does not need an argument. It is useful for creating multiple +shell buffers: if you rename the @samp{*Shell*} buffer, then do @kbd{M-x +shell} again, it makes a new shell buffer named @samp{*Shell*}; +meanwhile, the old shell buffer continues to exist under its new name. +This method is also good for mail buffers, compilation buffers, and most +Emacs features that create special buffers with particular names. + +@findex view-buffer + @kbd{M-x view-buffer} is much like @kbd{M-x view-file} (@pxref{Misc +File Ops}) except that it examines an already existing Emacs buffer. +View mode provides commands for scrolling through the buffer +conveniently but not for changing it. When you exit View mode with +@kbd{q}, that switches back to the buffer (and the position) which was +previously displayed in the window. Alternatively, if you exit View +mode with @kbd{e}, the buffer and the value of point that resulted from +your perusal remain in effect. + + The commands @kbd{M-x append-to-buffer} and @kbd{M-x insert-buffer} +can be used to copy text from one buffer to another. @xref{Accumulating +Text}.@refill + +@node Kill Buffer +@section Killing Buffers + +@cindex killing buffers + If you continue an Emacs session for a while, you may accumulate a +large number of buffers. You may then find it convenient to @dfn{kill} +the buffers you no longer need. On most operating systems, killing a +buffer releases its space back to the operating system so that other +programs can use it. Here are some commands for killing buffers: + +@c WideCommands +@table @kbd +@item C-x k @var{bufname} @key{RET} +Kill buffer @var{bufname} (@code{kill-buffer}). +@item M-x kill-some-buffers +Offer to kill each buffer, one by one. +@end table + +@findex kill-buffer +@findex kill-some-buffers +@kindex C-x k + + @kbd{C-x k} (@code{kill-buffer}) kills one buffer, whose name you +specify in the minibuffer. The default, used if you type just @key{RET} +in the minibuffer, is to kill the current buffer. If you kill the +current buffer, another buffer is selected; one that has been selected +recently but does not appear in any window now. If you ask to kill a +file-visiting buffer that is modified (has unsaved editing), then you +must confirm with @kbd{yes} before the buffer is killed. + + The command @kbd{M-x kill-some-buffers} asks about each buffer, one by +one. An answer of @kbd{y} means to kill the buffer. Killing the current +buffer or a buffer containing unsaved changes selects a new buffer or asks +for confirmation just like @code{kill-buffer}. + + The buffer menu feature (@pxref{Several Buffers}) is also convenient +for killing various buffers. + +@vindex kill-buffer-hook + If you want to do something special every time a buffer is killed, you +can add hook functions to the hook @code{kill-buffer-hook} (@pxref{Hooks}). + +@findex clean-buffer-list + If you run one Emacs session for a period of days, as many people do, +it can fill up with buffers that you used several days ago. The command +@kbd{M-x clean-buffer-list} is a convenient way to purge them; it kills +all the unmodified buffers that you have not used for a long time. An +ordinary buffer is killed if it has not been displayed for three days; +however, you can specify certain buffers that should never be killed +automatically, and others that should be killed if they have been unused +for a mere hour. + +@cindex Midnight mode +@vindex midnight-mode +@vindex midnight-hook + You can also have this buffer purging done for you, every day at +midnight, by enabling Midnight mode. Midnight mode operates each day at +midnight; at that time, it runs @code{clean-buffer-list}, or whichever +functions you have placed in the normal hook @code{midnight-hook} +(@pxref{Hooks}). + + To enable Midnight mode, use the Customization buffer to set the +variable @code{midnight-mode} to @code{t}. @xref{Easy Customization}. + +@node Several Buffers +@section Operating on Several Buffers +@cindex buffer menu + + The @dfn{buffer-menu} facility is like a ``Dired for buffers''; it allows +you to request operations on various Emacs buffers by editing an Emacs +buffer containing a list of them. You can save buffers, kill them +(here called @dfn{deleting} them, for consistency with Dired), or display +them. + +@table @kbd +@item M-x buffer-menu +Begin editing a buffer listing all Emacs buffers. +@end table + +@findex buffer-menu + The command @code{buffer-menu} writes a list of all Emacs buffers into +the buffer @samp{*Buffer List*}, and selects that buffer in Buffer Menu +mode. The buffer is read-only, and can be changed only through the +special commands described in this section. The usual Emacs cursor +motion commands can be used in the @samp{*Buffer List*} buffer. The +following commands apply to the buffer described on the current line. + +@table @kbd +@item d +Request to delete (kill) the buffer, then move down. The request +shows as a @samp{D} on the line, before the buffer name. Requested +deletions take place when you type the @kbd{x} command. +@item C-d +Like @kbd{d} but move up afterwards instead of down. +@item s +Request to save the buffer. The request shows as an @samp{S} on the +line. Requested saves take place when you type the @kbd{x} command. +You may request both saving and deletion for the same buffer. +@item x +Perform previously requested deletions and saves. +@item u +Remove any request made for the current line, and move down. +@item @key{DEL} +Move to previous line and remove any request made for that line. +@end table + + The @kbd{d}, @kbd{C-d}, @kbd{s} and @kbd{u} commands to add or remove +flags also move down (or up) one line. They accept a numeric argument +as a repeat count. + + These commands operate immediately on the buffer listed on the current +line: + +@table @kbd +@item ~ +Mark the buffer ``unmodified.'' The command @kbd{~} does this +immediately when you type it. +@item % +Toggle the buffer's read-only flag. The command @kbd{%} does +this immediately when you type it. +@item t +Visit the buffer as a tags table. @xref{Select Tags Table}. +@end table + + There are also commands to select another buffer or buffers: + +@table @kbd +@item q +Quit the buffer menu---immediately display the most recent formerly +visible buffer in its place. +@item @key{RET} +@itemx f +Immediately select this line's buffer in place of the @samp{*Buffer +List*} buffer. +@item o +Immediately select this line's buffer in another window as if by +@kbd{C-x 4 b}, leaving @samp{*Buffer List*} visible. +@item C-o +Immediately display this line's buffer in another window, but don't +select the window. +@item 1 +Immediately select this line's buffer in a full-screen window. +@item 2 +Immediately set up two windows, with this line's buffer in one, and the +previously selected buffer (aside from the buffer @samp{*Buffer List*}) +in the other. +@item b +Bury the buffer listed on this line. +@item m +Mark this line's buffer to be displayed in another window if you exit +with the @kbd{v} command. The request shows as a @samp{>} at the +beginning of the line. (A single buffer may not have both a delete +request and a display request.) +@item v +Immediately select this line's buffer, and also display in other windows +any buffers previously marked with the @kbd{m} command. If you have not +marked any buffers, this command is equivalent to @kbd{1}. +@end table + + All that @code{buffer-menu} does directly is create and switch to a +suitable buffer, and turn on Buffer Menu mode. Everything else +described above is implemented by the special commands provided in +Buffer Menu mode. One consequence of this is that you can switch from +the @samp{*Buffer List*} buffer to another Emacs buffer, and edit there. +You can reselect the @samp{*Buffer List*} buffer later, to perform the +operations already requested, or you can kill it, or pay no further +attention to it. + + The only difference between @code{buffer-menu} and @code{list-buffers} +is that @code{buffer-menu} switches to the @samp{*Buffer List*} buffer +in the selected window; @code{list-buffers} displays it in another +window. If you run @code{list-buffers} (that is, type @kbd{C-x C-b}) +and select the buffer list manually, you can use all of the commands +described here. + + The buffer @samp{*Buffer List*} is not updated automatically when +buffers are created and killed; its contents are just text. If you have +created, deleted or renamed buffers, the way to update @samp{*Buffer +List*} to show what you have done is to type @kbd{g} +(@code{revert-buffer}) or repeat the @code{buffer-menu} command. + +@node Indirect Buffers +@section Indirect Buffers +@cindex indirect buffer +@cindex base buffer + + An @dfn{indirect buffer} shares the text of some other buffer, which +is called the @dfn{base buffer} of the indirect buffer. In some ways it +is the analogue, for buffers, of a symbolic link between files. + +@table @kbd +@findex make-indirect-buffer +@item M-x make-indirect-buffer @var{base-buffer} @key{RET} @var{indirect-name} @key{RET} +Create an indirect buffer named @var{indirect-name} whose base buffer +is @var{base-buffer}. +@end table + + The text of the indirect buffer is always identical to the text of its +base buffer; changes made by editing either one are visible immediately +in the other. But in all other respects, the indirect buffer and its +base buffer are completely separate. They have different names, +different values of point, different narrowing, different markers, +different major modes, and different local variables. + + An indirect buffer cannot visit a file, but its base buffer can. If +you try to save the indirect buffer, that actually works by saving the +base buffer. Killing the base buffer effectively kills the indirect +buffer, but killing an indirect buffer has no effect on its base buffer. + + One way to use indirect buffers is to display multiple views of an +outline. @xref{Outline Views}. diff --git a/man/building.texi b/man/building.texi new file mode 100644 index 00000000000..d42f7686e8c --- /dev/null +++ b/man/building.texi @@ -0,0 +1,796 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Building, Abbrevs, Programs, Top +@chapter Compiling and Testing Programs +@cindex building programs +@cindex program building +@cindex running Lisp functions + + The previous chapter discusses the Emacs commands that are useful for +making changes in programs. This chapter deals with commands that assist +in the larger process of developing and maintaining programs. + +@menu +* Compilation:: Compiling programs in languages other + than Lisp (C, Pascal, etc.). +* Grep Searching:: Running grep as if it were a compiler. +* Compilation Mode:: The mode for visiting compiler errors. +* Compilation Shell:: Customizing your shell properly + for use in the compilation buffer. +* Debuggers:: Running symbolic debuggers for non-Lisp programs. +* Executing Lisp:: Various modes for editing Lisp programs, + with different facilities for running + the Lisp programs. +* Libraries: Lisp Libraries. Creating Lisp programs to run in Emacs. +* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer. +* Eval: Lisp Eval. Executing a single Lisp expression in Emacs. +* External Lisp:: Communicating through Emacs with a separate Lisp. +@end menu + +@node Compilation +@section Running Compilations under Emacs +@cindex inferior process +@cindex make +@cindex compilation errors +@cindex error log + + Emacs can run compilers for noninteractive languages such as C and +Fortran as inferior processes, feeding the error log into an Emacs buffer. +It can also parse the error messages and show you the source lines where +compilation errors occurred. + +@table @kbd +@item M-x compile +Run a compiler asynchronously under Emacs, with error messages to +@samp{*compilation*} buffer. +@item M-x grep +Run @code{grep} asynchronously under Emacs, with matching lines +listed in the buffer named @samp{*grep*}. +@item M-x grep-find +Run @code{grep} via @code{find}, with user-specified arguments, and +collect output in the buffer named @samp{*grep*}. +@item M-x kill-compilation +@itemx M-x kill-grep +Kill the running compilation or @code{grep} subprocess. +@end table + +@findex compile + To run @code{make} or another compilation command, do @kbd{M-x +compile}. This command reads a shell command line using the minibuffer, +and then executes the command in an inferior shell, putting output in +the buffer named @samp{*compilation*}. The current buffer's default +directory is used as the working directory for the execution of the +command; normally, therefore, the compilation happens in this +directory. + +@vindex compile-command + When the shell command line is read, the minibuffer appears containing +a default command line, which is the command you used the last time you +did @kbd{M-x compile}. If you type just @key{RET}, the same command +line is used again. For the first @kbd{M-x compile}, the default is +@samp{make -k}. The default compilation command comes from the variable +@code{compile-command}; if the appropriate compilation command for a +file is something other than @samp{make -k}, it can be useful for the +file to specify a local value for @code{compile-command} (@pxref{File +Variables}). + + Starting a compilation displays the buffer @samp{*compilation*} in +another window but does not select it. The buffer's mode line tells you +whether compilation is finished, with the word @samp{run} or @samp{exit} +inside the parentheses. You do not have to keep this buffer visible; +compilation continues in any case. While a compilation is going on, the +string @samp{Compiling} appears in the mode lines of all windows. When +this string disappears, the compilation is finished. + + If you want to watch the compilation transcript as it appears, switch +to the @samp{*compilation*} buffer and move point to the end of the +buffer. When point is at the end, new compilation output is inserted +above point, which remains at the end. If point is not at the end of +the buffer, it remains fixed while more compilation output is added at +the end of the buffer. + +@vindex compilation-scroll-output + If you set the variable @code{compilation-scroll-output} to a +non-@code{nil} value, then the compilation buffer always scrolls to +follow output as it comes in. + +@findex kill-compilation + To kill the compilation process, do @kbd{M-x kill-compilation}. When +the compiler process terminates, the mode line of the +@samp{*compilation*} buffer changes to say @samp{signal} instead of +@samp{run}. Starting a new compilation also kills any running +compilation, as only one can exist at any time. However, @kbd{M-x +compile} asks for confirmation before actually killing a compilation +that is running. + +@node Grep Searching +@section Searching with Grep under Emacs + +@findex grep + Just as you can run a compiler from Emacs and then visit the lines +where there were compilation errors, you can also run @code{grep} and +then visit the lines on which matches were found. This works by +treating the matches reported by @code{grep} as if they were ``errors.'' + + To do this, type @kbd{M-x grep}, then enter a command line that +specifies how to run @code{grep}. Use the same arguments you would give +@code{grep} when running it normally: a @code{grep}-style regexp +(usually in single-quotes to quote the shell's special characters) +followed by file names, which may use wildcards. The output from +@code{grep} goes in the @samp{*grep*} buffer. You can find the +corresponding lines in the original files using @kbd{C-x `} and +@key{RET}, as with compilation errors. + + If you specify a prefix argument for @kbd{M-x grep}, it figures out +the tag (@pxref{Tags}) around point, and puts that into the default +@code{grep} command. + +@findex grep-find + The command @kbd{M-x grep-find} is similar to @kbd{M-x grep}, but it +supplies a different initial default for the command---one that runs +both @code{find} and @code{grep}, so as to search every file in a +directory tree. See also the @code{find-grep-dired} command, +in @ref{Dired and Find}. + +@node Compilation Mode +@section Compilation Mode + +@findex compile-goto-error +@cindex Compilation mode +@cindex mode, Compilation + The @samp{*compilation*} buffer uses a special major mode, Compilation +mode, whose main feature is to provide a convenient way to look at the +source line where the error happened. + +@table @kbd +@item C-x ` +Visit the locus of the next compiler error message or @code{grep} match. +@item @key{RET} +Visit the locus of the error message that point is on. +This command is used in the compilation buffer. +@item Mouse-2 +Visit the locus of the error message that you click on. +@end table + +@kindex C-x ` +@findex next-error + You can visit the source for any particular error message by moving +point in @samp{*compilation*} to that error message and typing @key{RET} +(@code{compile-goto-error}). Or click @kbd{Mouse-2} on the error message; +you need not switch to the @samp{*compilation*} buffer first. + + To parse the compiler error messages sequentially, type @kbd{C-x `} +(@code{next-error}). The character following the @kbd{C-x} is the +backquote or ``grave accent,'' not the single-quote. This command is +available in all buffers, not just in @samp{*compilation*}; it displays +the next error message at the top of one window and source location of +the error in another window. + + The first time @kbd{C-x `} is used after the start of a compilation, +it moves to the first error's location. Subsequent uses of @kbd{C-x `} +advance down to subsequent errors. If you visit a specific error +message with @key{RET} or @kbd{Mouse-2}, subsequent @kbd{C-x `} +commands advance from there. When @kbd{C-x `} gets to the end of the +buffer and finds no more error messages to visit, it fails and signals +an Emacs error. + + @kbd{C-u C-x `} starts scanning from the beginning of the compilation +buffer. This is one way to process the same set of errors again. + + Compilation mode also redefines the keys @key{SPC} and @key{DEL} to +scroll by screenfuls, and @kbd{M-n} and @kbd{M-p} to move to the next or +previous error message. You can also use @kbd{M-@{} and @kbd{M-@}} to +move up or down to an error message for a different source file. + + The features of Compilation mode are also available in a minor mode +called Compilation Minor mode. This lets you parse error messages in +any buffer, not just a normal compilation output buffer. Type @kbd{M-x +compilation-minor-mode} to enable the minor mode. This defines the keys +@key{RET} and @kbd{Mouse-2}, as in the Compilation major mode. + + Compilation minor mode works in any buffer, as long as the contents +are in a format that it understands. In an Rlogin buffer (@pxref{Remote +Host}), Compilation minor mode automatically accesses remote source +files by FTP (@pxref{File Names}). + +@node Compilation Shell +@section Subshells for Compilation + + Emacs uses a shell to run the compilation command, but specifies +the option for a noninteractive shell. This means, in particular, that +the shell should start with no prompt. If you find your usual shell +prompt making an unsightly appearance in the @samp{*compilation*} +buffer, it means you have made a mistake in your shell's init file by +setting the prompt unconditionally. (This init file's name may be +@file{.bashrc}, @file{.profile}, @file{.cshrc}, @file{.shrc}, or various +other things, depending on the shell you use.) The shell init file +should set the prompt only if there already is a prompt. In csh, here +is how to do it: + +@example +if ($?prompt) set prompt = @dots{} +@end example + +@noindent +And here's how to do it in bash: + +@example +if [ "$@{PS1+set@}" = set ] +then PS1=@dots{} +fi +@end example + + There may well be other things that your shell's init file +ought to do only for an interactive shell. You can use the same +method to conditionalize them. + + The MS-DOS ``operating system'' does not support asynchronous +subprocesses; to work around this lack, @kbd{M-x compile} runs the +compilation command synchronously on MS-DOS. As a consequence, you must +wait until the command finishes before you can do anything else in +Emacs. @xref{MS-DOS}. + +@node Debuggers +@section Running Debuggers Under Emacs +@cindex debuggers +@cindex GUD library +@cindex GDB +@cindex DBX +@cindex SDB +@cindex XDB +@cindex Perldb +@cindex JDB +@cindex PDB + +@c Do you believe in GUD? +The GUD (Grand Unified Debugger) library provides an interface to +various symbolic debuggers from within Emacs. We recommend the debugger +GDB, which is free software, but you can also run DBX, SDB or XDB if you +have them. GUD can also serve as an interface to the Perl's debugging +mode, the Python debugger PDB, and to JDB, the Java Debugger. + +@menu +* Starting GUD:: How to start a debugger subprocess. +* Debugger Operation:: Connection between the debugger and source buffers. +* Commands of GUD:: Key bindings for common commands. +* GUD Customization:: Defining your own commands for GUD. +@end menu + +@node Starting GUD +@subsection Starting GUD + + There are several commands for starting a debugger, each corresponding +to a particular debugger program. + +@table @kbd +@item M-x gdb @key{RET} @var{file} @key{RET} +@findex gdb +Run GDB as a subprocess of Emacs. This command creates a buffer for +input and output to GDB, and switches to it. If a GDB buffer already +exists, it just switches to that buffer. + +@item M-x dbx @key{RET} @var{file} @key{RET} +@findex dbx +Similar, but run DBX instead of GDB. + +@item M-x xdb @key{RET} @var{file} @key{RET} +@findex xdb +@vindex gud-xdb-directories +Similar, but run XDB instead of GDB. Use the variable +@code{gud-xdb-directories} to specify directories to search for source +files. + +@item M-x sdb @key{RET} @var{file} @key{RET} +@findex sdb +Similar, but run SDB instead of GDB. + + Some versions of SDB do not mention source file names in their +messages. When you use them, you need to have a valid tags table +(@pxref{Tags}) in order for GUD to find functions in the source code. +If you have not visited a tags table or the tags table doesn't list one +of the functions, you get a message saying @samp{The sdb support +requires a valid tags table to work}. If this happens, generate a valid +tags table in the working directory and try again. + +@item M-x perldb @key{RET} @var{file} @key{RET} +@findex perldb +Run the Perl interpreter in debug mode to debug @var{file}, a Perl program. + +@item M-x jdb @key{RET} @var{file} @key{RET} +@findex jdb +Run the Java debugger to debug @var{file}. + +@item M-x pdb @key{RET} @var{file} @key{RET} +@findex pdb +Run the Python debugger to debug @var{file}. +@end table + + Each of these commands takes one argument: a command line to invoke +the debugger. In the simplest case, specify just the name of the +executable file you want to debug. You may also use options that the +debugger supports. However, shell wildcards and variables are not +allowed. GUD assumes that the first argument not starting with a +@samp{-} is the executable file name. + + Emacs can only run one debugger process at a time. + +@node Debugger Operation +@subsection Debugger Operation + + When you run a debugger with GUD, the debugger uses an Emacs buffer +for its ordinary input and output. This is called the GUD buffer. The +debugger displays the source files of the program by visiting them in +Emacs buffers. An arrow (@samp{=>}) in one of these buffers indicates +the current execution line. Moving point in this buffer does not move +the arrow. + + You can start editing these source files at any time in the buffers +that were made to display them. The arrow is not part of the file's +text; it appears only on the screen. If you do modify a source file, +keep in mind that inserting or deleting lines will throw off the arrow's +positioning; GUD has no way of figuring out which line corresponded +before your changes to the line number in a debugger message. Also, +you'll typically have to recompile and restart the program for your +changes to be reflected in the debugger's tables. + + If you wish, you can control your debugger process entirely through the +debugger buffer, which uses a variant of Shell mode. All the usual +commands for your debugger are available, and you can use the Shell mode +history commands to repeat them. @xref{Shell Mode}. + +@node Commands of GUD +@subsection Commands of GUD + + The GUD interaction buffer uses a variant of Shell mode, so the +commands of Shell mode are available (@pxref{Shell Mode}). GUD mode +also provides commands for setting and clearing breakpoints, for +selecting stack frames, and for stepping through the program. These +commands are available both in the GUD buffer and globally, but with +different key bindings. + + The breakpoint commands are usually used in source file buffers, +because that is the way to specify where to set or clear the breakpoint. +Here's the global command to set a breakpoint: + +@table @kbd +@item C-x @key{SPC} +@kindex C-x SPC +Set a breakpoint on the source line that point is on. +@end table + +@kindex C-x C-a @r{(GUD)} + Here are the other special commands provided by GUD. The keys +starting with @kbd{C-c} are available only in the GUD interaction +buffer. The key bindings that start with @kbd{C-x C-a} are available in +the GUD interaction buffer and also in source files. + +@table @kbd +@item C-c C-l +@kindex C-c C-l @r{(GUD)} +@itemx C-x C-a C-l +@findex gud-refresh +Display in another window the last line referred to in the GUD +buffer (that is, the line indicated in the last location message). +This runs the command @code{gud-refresh}. + +@item C-c C-s +@kindex C-c C-s @r{(GUD)} +@itemx C-x C-a C-s +@findex gud-step +Execute a single line of code (@code{gud-step}). If the line contains +a function call, execution stops after entering the called function. + +@item C-c C-n +@kindex C-c C-n @r{(GUD)} +@itemx C-x C-a C-n +@findex gud-next +Execute a single line of code, stepping across entire function calls +at full speed (@code{gud-next}). + +@item C-c C-i +@kindex C-c C-i @r{(GUD)} +@itemx C-x C-a C-i +@findex gud-stepi +Execute a single machine instruction (@code{gud-stepi}). + +@need 3000 +@item C-c C-r +@kindex C-c C-r @r{(GUD)} +@itemx C-x C-a C-r +@findex gud-cont +Continue execution without specifying any stopping point. The program +will run until it hits a breakpoint, terminates, or gets a signal that +the debugger is checking for (@code{gud-cont}). + +@need 1000 +@item C-c C-d +@kindex C-c C-d @r{(GUD)} +@itemx C-x C-a C-d +@findex gud-remove +Delete the breakpoint(s) on the current source line, if any +(@code{gud-remove}). If you use this command in the GUD interaction +buffer, it applies to the line where the program last stopped. + +@item C-c C-t +@kindex C-c C-t @r{(GUD)} +@itemx C-x C-a C-t +@findex gud-tbreak +Set a temporary breakpoint on the current source line, if any. +If you use this command in the GUD interaction buffer, +it applies to the line where the program last stopped. +@end table + + The above commands are common to all supported debuggers. If you are +using GDB or (some versions of) DBX, these additional commands are available: + +@table @kbd +@item C-c < +@kindex C-c < @r{(GUD)} +@itemx C-x C-a < +@findex gud-up +Select the next enclosing stack frame (@code{gud-up}). This is +equivalent to the @samp{up} command. + +@item C-c > +@kindex C-c > @r{(GUD)} +@itemx C-x C-a > +@findex gud-down +Select the next inner stack frame (@code{gud-down}). This is +equivalent to the @samp{down} command. +@end table + + If you are using GDB, these additional key bindings are available: + +@table @kbd +@item @key{TAB} +@kindex TAB @r{(GUD)} +@findex gud-gdb-complete-command +With GDB, complete a symbol name (@code{gud-gdb-complete-command}). +This key is available only in the GUD interaction buffer, and requires +GDB versions 4.13 and later. + +@item C-c C-f +@kindex C-c C-f @r{(GUD)} +@itemx C-x C-a C-f +@findex gud-finish +Run the program until the selected stack frame returns (or until it +stops for some other reason). +@end table + + These commands interpret a numeric argument as a repeat count, when +that makes sense. + + Because @key{TAB} serves as a completion command, you can't use it to +enter a tab as input to the program you are debugging with GDB. +Instead, type @kbd{C-q @key{TAB}} to enter a tab. + +@node GUD Customization +@subsection GUD Customization + +@vindex gdb-mode-hook +@vindex dbx-mode-hook +@vindex sdb-mode-hook +@vindex xdb-mode-hook +@vindex perldb-mode-hook +@vindex pdb-mode-hook +@vindex jdb-mode-hook + On startup, GUD runs one of the following hooks: @code{gdb-mode-hook}, +if you are using GDB; @code{dbx-mode-hook}, if you are using DBX; +@code{sdb-mode-hook}, if you are using SDB; @code{xdb-mode-hook}, if you +are using XDB; @code{perldb-mode-hook}, for Perl debugging mode; +@code{jdb-mode-hook}, for PDB; @code{jdb-mode-hook}, for JDB. You can +use these hooks to define custom key bindings for the debugger +interaction buffer. @xref{Hooks}. + + Here is a convenient way to define a command that sends a particular +command string to the debugger, and set up a key binding for it in the +debugger interaction buffer: + +@findex gud-def +@example +(gud-def @var{function} @var{cmdstring} @var{binding} @var{docstring}) +@end example + + This defines a command named @var{function} which sends +@var{cmdstring} to the debugger process, and gives it the documentation +string @var{docstring}. You can use the command thus defined in any +buffer. If @var{binding} is non-@code{nil}, @code{gud-def} also binds +the command to @kbd{C-c @var{binding}} in the GUD buffer's mode and to +@kbd{C-x C-a @var{binding}} generally. + + The command string @var{cmdstring} may contain certain +@samp{%}-sequences that stand for data to be filled in at the time +@var{function} is called: + +@table @samp +@item %f +The name of the current source file. If the current buffer is the GUD +buffer, then the ``current source file'' is the file that the program +stopped in. +@c This said, ``the name of the file the program counter was in at the last breakpoint.'' +@c But I suspect it is really the last stop file. + +@item %l +The number of the current source line. If the current buffer is the GUD +buffer, then the ``current source line'' is the line that the program +stopped in. + +@item %e +The text of the C lvalue or function-call expression at or adjacent to point. + +@item %a +The text of the hexadecimal address at or adjacent to point. + +@item %p +The numeric argument of the called function, as a decimal number. If +the command is used without a numeric argument, @samp{%p} stands for the +empty string. + +If you don't use @samp{%p} in the command string, the command you define +ignores any numeric argument. +@end table + +@node Executing Lisp +@section Executing Lisp Expressions + + Emacs has several different major modes for Lisp and Scheme. They are +the same in terms of editing commands, but differ in the commands for +executing Lisp expressions. Each mode has its own purpose. + +@table @asis +@item Emacs-Lisp mode +The mode for editing source files of programs to run in Emacs Lisp. +This mode defines @kbd{C-M-x} to evaluate the current defun. +@xref{Lisp Libraries}. +@item Lisp Interaction mode +The mode for an interactive session with Emacs Lisp. It defines +@kbd{C-j} to evaluate the sexp before point and insert its value in the +buffer. @xref{Lisp Interaction}. +@item Lisp mode +The mode for editing source files of programs that run in Lisps other +than Emacs Lisp. This mode defines @kbd{C-M-x} to send the current defun +to an inferior Lisp process. @xref{External Lisp}. +@item Inferior Lisp mode +The mode for an interactive session with an inferior Lisp process. +This mode combines the special features of Lisp mode and Shell mode +(@pxref{Shell Mode}). +@item Scheme mode +Like Lisp mode but for Scheme programs. +@item Inferior Scheme mode +The mode for an interactive session with an inferior Scheme process. +@end table + + Most editing commands for working with Lisp programs are in fact +available globally. @xref{Programs}. + +@node Lisp Libraries +@section Libraries of Lisp Code for Emacs +@cindex libraries +@cindex loading Lisp code + + Lisp code for Emacs editing commands is stored in files whose names +conventionally end in @file{.el}. This ending tells Emacs to edit them in +Emacs-Lisp mode (@pxref{Executing Lisp}). + +@findex load-file + To execute a file of Emacs Lisp code, use @kbd{M-x load-file}. This +command reads a file name using the minibuffer and then executes the +contents of that file as Lisp code. It is not necessary to visit the +file first; in any case, this command reads the file as found on disk, +not text in an Emacs buffer. + +@findex load +@findex load-library + Once a file of Lisp code is installed in the Emacs Lisp library +directories, users can load it using @kbd{M-x load-library}. Programs can +load it by calling @code{load-library}, or with @code{load}, a more primitive +function that is similar but accepts some additional arguments. + + @kbd{M-x load-library} differs from @kbd{M-x load-file} in that it +searches a sequence of directories and tries three file names in each +directory. Suppose your argument is @var{lib}; the three names are +@file{@var{lib}.elc}, @file{@var{lib}.el}, and lastly just +@file{@var{lib}}. If @file{@var{lib}.elc} exists, it is by convention +the result of compiling @file{@var{lib}.el}; it is better to load the +compiled file, since it will load and run faster. + + If @code{load-library} finds that @file{@var{lib}.el} is newer than +@file{@var{lib}.elc} file, it prints a warning, because it's likely that +somebody made changes to the @file{.el} file and forgot to recompile +it. + + Because the argument to @code{load-library} is usually not in itself +a valid file name, file name completion is not available. Indeed, when +using this command, you usually do not know exactly what file name +will be used. + +@vindex load-path + The sequence of directories searched by @kbd{M-x load-library} is +specified by the variable @code{load-path}, a list of strings that are +directory names. The default value of the list contains the directory where +the Lisp code for Emacs itself is stored. If you have libraries of +your own, put them in a single directory and add that directory +to @code{load-path}. @code{nil} in this list stands for the current default +directory, but it is probably not a good idea to put @code{nil} in the +list. If you find yourself wishing that @code{nil} were in the list, +most likely what you really want to do is use @kbd{M-x load-file} +this once. + +@cindex autoload + Often you do not have to give any command to load a library, because +the commands defined in the library are set up to @dfn{autoload} that +library. Trying to run any of those commands calls @code{load} to load +the library; this replaces the autoload definitions with the real ones +from the library. + +@cindex byte code + Emacs Lisp code can be compiled into byte-code which loads faster, +takes up less space when loaded, and executes faster. @xref{Byte +Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual}. +By convention, the compiled code for a library goes in a separate file +whose name consists of the library source file with @samp{c} appended. +Thus, the compiled code for @file{foo.el} goes in @file{foo.elc}. +That's why @code{load-library} searches for @samp{.elc} files first. + +@node Lisp Eval +@section Evaluating Emacs-Lisp Expressions +@cindex Emacs-Lisp mode +@cindex mode, Emacs-Lisp + +@findex emacs-lisp-mode + Lisp programs intended to be run in Emacs should be edited in +Emacs-Lisp mode; this happens automatically for file names ending in +@file{.el}. By contrast, Lisp mode itself is used for editing Lisp +programs intended for other Lisp systems. To switch to Emacs-Lisp mode +explicitly, use the command @kbd{M-x emacs-lisp-mode}. + + For testing of Lisp programs to run in Emacs, it is often useful to +evaluate part of the program as it is found in the Emacs buffer. For +example, after changing the text of a Lisp function definition, +evaluating the definition installs the change for future calls to the +function. Evaluation of Lisp expressions is also useful in any kind of +editing, for invoking noninteractive functions (functions that are +not commands). + +@table @kbd +@item M-: +Read a single Lisp expression in the minibuffer, evaluate it, and print +the value in the echo area (@code{eval-expression}). +@item C-x C-e +Evaluate the Lisp expression before point, and print the value in the +echo area (@code{eval-last-sexp}). +@item C-M-x +Evaluate the defun containing or after point, and print the value in +the echo area (@code{eval-defun}). +@item M-x eval-region +Evaluate all the Lisp expressions in the region. +@item M-x eval-current-buffer +Evaluate all the Lisp expressions in the buffer. +@end table + +@kindex M-: +@findex eval-expression + @kbd{M-:} (@code{eval-expression}) is the most basic command for evaluating +a Lisp expression interactively. It reads the expression using the +minibuffer, so you can execute any expression on a buffer regardless of +what the buffer contains. When the expression is evaluated, the current +buffer is once again the buffer that was current when @kbd{M-:} was +typed. + +@kindex C-M-x @r{(Emacs-Lisp mode)} +@findex eval-defun + In Emacs-Lisp mode, the key @kbd{C-M-x} is bound to the command +@code{eval-defun}, which parses the defun containing or following point +as a Lisp expression and evaluates it. The value is printed in the echo +area. This command is convenient for installing in the Lisp environment +changes that you have just made in the text of a function definition. + + @kbd{C-M-x} treats @code{defvar} expressions specially. Normally, +evaluating a @code{defvar} expression does nothing if the variable it +defines already has a value. But @kbd{C-M-x} unconditionally resets the +variable to the initial value specified in the @code{defvar} expression. +This special feature is convenient for debugging Lisp programs. + +@kindex C-x C-e +@findex eval-last-sexp + The command @kbd{C-x C-e} (@code{eval-last-sexp}) evaluates the Lisp +expression preceding point in the buffer, and displays the value in the +echo area. It is available in all major modes, not just Emacs-Lisp +mode. It does not treat @code{defvar} specially. + + If @kbd{C-M-x}, @kbd{C-x C-e}, or @kbd{M-:} is given a numeric +argument, it inserts the value into the current buffer at point, rather +than displaying it in the echo area. The argument's value does not +matter. + +@findex eval-region +@findex eval-current-buffer + The most general command for evaluating Lisp expressions from a buffer +is @code{eval-region}. @kbd{M-x eval-region} parses the text of the +region as one or more Lisp expressions, evaluating them one by one. +@kbd{M-x eval-current-buffer} is similar but evaluates the entire +buffer. This is a reasonable way to install the contents of a file of +Lisp code that you are just ready to test. Later, as you find bugs and +change individual functions, use @kbd{C-M-x} on each function that you +change. This keeps the Lisp world in step with the source file. + +@node Lisp Interaction +@section Lisp Interaction Buffers + + The buffer @samp{*scratch*} which is selected when Emacs starts up is +provided for evaluating Lisp expressions interactively inside Emacs. + + The simplest way to use the @samp{*scratch*} buffer is to insert Lisp +expressions and type @kbd{C-j} after each expression. This command +reads the Lisp expression before point, evaluates it, and inserts the +value in printed representation before point. The result is a complete +typescript of the expressions you have evaluated and their values. + + The @samp{*scratch*} buffer's major mode is Lisp Interaction mode, which +is the same as Emacs-Lisp mode except for the binding of @kbd{C-j}. + +@findex lisp-interaction-mode + The rationale for this feature is that Emacs must have a buffer when +it starts up, but that buffer is not useful for editing files since a +new buffer is made for every file that you visit. The Lisp interpreter +typescript is the most useful thing I can think of for the initial +buffer to do. Type @kbd{M-x lisp-interaction-mode} to put the current +buffer in Lisp Interaction mode. + +@findex ielm + An alternative way of evaluating Emacs Lisp expressions interactively +is to use Inferior Emacs-Lisp mode, which provides an interface rather +like Shell mode (@pxref{Shell Mode}) for evaluating Emacs Lisp +expressions. Type @kbd{M-x ielm} to create an @samp{*ielm*} buffer +which uses this mode. + +@node External Lisp +@section Running an External Lisp + + Emacs has facilities for running programs in other Lisp systems. You can +run a Lisp process as an inferior of Emacs, and pass expressions to it to +be evaluated. You can also pass changed function definitions directly from +the Emacs buffers in which you edit the Lisp programs to the inferior Lisp +process. + +@findex run-lisp +@vindex inferior-lisp-program +@kindex C-x C-z + To run an inferior Lisp process, type @kbd{M-x run-lisp}. This runs +the program named @code{lisp}, the same program you would run by typing +@code{lisp} as a shell command, with both input and output going through +an Emacs buffer named @samp{*lisp*}. That is to say, any ``terminal +output'' from Lisp will go into the buffer, advancing point, and any +``terminal input'' for Lisp comes from text in the buffer. (You can +change the name of the Lisp executable file by setting the variable +@code{inferior-lisp-program}.) + + To give input to Lisp, go to the end of the buffer and type the input, +terminated by @key{RET}. The @samp{*lisp*} buffer is in Inferior Lisp +mode, which combines the special characteristics of Lisp mode with most +of the features of Shell mode (@pxref{Shell Mode}). The definition of +@key{RET} to send a line to a subprocess is one of the features of Shell +mode. + +@findex lisp-mode + For the source files of programs to run in external Lisps, use Lisp +mode. This mode can be selected with @kbd{M-x lisp-mode}, and is used +automatically for files whose names end in @file{.l}, @file{.lsp}, or +@file{.lisp}, as most Lisp systems usually expect. + +@kindex C-M-x @r{(Lisp mode)} +@findex lisp-eval-defun + When you edit a function in a Lisp program you are running, the easiest +way to send the changed definition to the inferior Lisp process is the key +@kbd{C-M-x}. In Lisp mode, this runs the function @code{lisp-eval-defun}, +which finds the defun around or following point and sends it as input to +the Lisp process. (Emacs can send input to any inferior process regardless +of what buffer is current.) + + Contrast the meanings of @kbd{C-M-x} in Lisp mode (for editing programs +to be run in another Lisp system) and Emacs-Lisp mode (for editing Lisp +programs to be run in Emacs): in both modes it has the effect of installing +the function definition that point is in, but the way of doing so is +different according to where the relevant Lisp environment is found. +@xref{Executing Lisp}. diff --git a/man/calendar.texi b/man/calendar.texi new file mode 100644 index 00000000000..9d9ae5547ed --- /dev/null +++ b/man/calendar.texi @@ -0,0 +1,1438 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Calendar/Diary, Gnus, Dired, Top +@chapter The Calendar and the Diary +@cindex calendar +@findex calendar + + Emacs provides the functions of a desk calendar, with a diary of +planned or past events. To enter the calendar, type @kbd{M-x calendar}; +this displays a three-month calendar centered on the current month, with +point on the current date. With a numeric argument, as in @kbd{C-u M-x +calendar}, it prompts you for the month and year to be the center of the +three-month calendar. The calendar uses its own buffer, whose major +mode is Calendar mode. + + @kbd{Mouse-2} in the calendar brings up a menu of operations on a +particular date; @kbd{C-Mouse-3} brings up a menu of commonly used +calendar features that are independent of any particular date. To exit +the calendar, type @kbd{q}. @xref{Calendar, Customizing the Calendar +and Diary,, elisp, The Emacs Lisp Reference Manual}, for customization +information about the calendar and diary. + +@menu +* Calendar Motion:: Moving through the calendar; selecting a date. +* Scroll Calendar:: Bringing earlier or later months onto the screen. +* Counting Days:: How many days are there between two dates? +* General Calendar:: Exiting or recomputing the calendar. +* LaTeX Calendar:: Print a calendar using LaTeX. +* Holidays:: Displaying dates of holidays. +* Sunrise/Sunset:: Displaying local times of sunrise and sunset. +* Lunar Phases:: Displaying phases of the moon. +* Other Calendars:: Converting dates to other calendar systems. +* Diary:: Displaying events from your diary. +* Appointments:: Reminders when it's time to do something. +* Daylight Savings:: How to specify when daylight savings time is active. +@end menu + +@node Calendar Motion +@section Movement in the Calendar + +@cindex moving inside the calendar + Calendar mode lets you move through the calendar in logical units of +time such as days, weeks, months, and years. If you move outside the +three months originally displayed, the calendar display ``scrolls'' +automatically through time to make the selected date visible. Moving to +a date lets you view its holidays or diary entries, or convert it to other +calendars; moving longer time periods is also useful simply to scroll the +calendar. + +@menu +* Calendar Unit Motion:: Moving by days, weeks, months, and years. +* Move to Beginning or End:: Moving to start/end of weeks, months, and years. +* Specified Dates:: Moving to the current date or another + specific date. +@end menu + +@node Calendar Unit Motion +@subsection Motion by Standard Lengths of Time + + The commands for movement in the calendar buffer parallel the +commands for movement in text. You can move forward and backward by +days, weeks, months, and years. + +@table @kbd +@item C-f +Move point one day forward (@code{calendar-forward-day}). +@item C-b +Move point one day backward (@code{calendar-backward-day}). +@item C-n +Move point one week forward (@code{calendar-forward-week}). +@item C-p +Move point one week backward (@code{calendar-backward-week}). +@item M-@} +Move point one month forward (@code{calendar-forward-month}). +@item M-@{ +Move point one month backward (@code{calendar-backward-month}). +@item C-x ] +Move point one year forward (@code{calendar-forward-year}). +@item C-x [ +Move point one year backward (@code{calendar-backward-year}). +@end table + +@kindex C-f @r{(Calendar mode)} +@findex calendar-forward-day +@kindex C-b @r{(Calendar mode)} +@findex calendar-backward-day +@kindex C-n @r{(Calendar mode)} +@findex calendar-forward-week +@kindex C-p @r{(Calendar mode)} +@findex calendar-backward-week + The day and week commands are natural analogues of the usual Emacs +commands for moving by characters and by lines. Just as @kbd{C-n} +usually moves to the same column in the following line, in Calendar +mode it moves to the same day in the following week. And @kbd{C-p} +moves to the same day in the previous week. + + The arrow keys are equivalent to @kbd{C-f}, @kbd{C-b}, @kbd{C-n} and +@kbd{C-p}, just as they normally are in other modes. + +@kindex M-@} @r{(Calendar mode)} +@findex calendar-forward-month +@kindex M-@{ @r{(Calendar mode)} +@findex calendar-backward-month +@kindex C-x ] @r{(Calendar mode)} +@findex calendar-forward-year +@kindex C-x [ @r{(Calendar mode)} +@findex calendar-forward-year + The commands for motion by months and years work like those for +weeks, but move a larger distance. The month commands @kbd{M-@}} and +@kbd{M-@{} move forward or backward by an entire month's time. The +year commands @kbd{C-x ]} and @w{@kbd{C-x [}} move forward or backward a +whole year. + + The easiest way to remember these commands is to consider months and +years analogous to paragraphs and pages of text, respectively. But the +commands themselves are not quite analogous. The ordinary Emacs paragraph +commands move to the beginning or end of a paragraph, whereas these month +and year commands move by an entire month or an entire year, which usually +involves skipping across the end of a month or year. + + All these commands accept a numeric argument as a repeat count. +For convenience, the digit keys and the minus sign specify numeric +arguments in Calendar mode even without the Meta modifier. For example, +@kbd{100 C-f} moves point 100 days forward from its present location. + +@node Move to Beginning or End +@subsection Beginning or End of Week, Month or Year + + A week (or month, or year) is not just a quantity of days; we think of +weeks (months, years) as starting on particular dates. So Calendar mode +provides commands to move to the beginning or end of a week, month or +year: + +@table @kbd +@kindex C-a @r{(Calendar mode)} +@findex calendar-beginning-of-week +@item C-a +Move point to start of week (@code{calendar-beginning-of-week}). +@kindex C-e @r{(Calendar mode)} +@findex calendar-end-of-week +@item C-e +Move point to end of week (@code{calendar-end-of-week}). +@kindex M-a @r{(Calendar mode)} +@findex calendar-beginning-of-month +@item M-a +Move point to start of month (@code{calendar-beginning-of-month}). +@kindex M-e @r{(Calendar mode)} +@findex calendar-end-of-month +@item M-e +Move point to end of month (@code{calendar-end-of-month}). +@kindex M-< @r{(Calendar mode)} +@findex calendar-beginning-of-year +@item M-< +Move point to start of year (@code{calendar-beginning-of-year}). +@kindex M-> @r{(Calendar mode)} +@findex calendar-end-of-year +@item M-> +Move point to end of year (@code{calendar-end-of-year}). +@end table + + These commands also take numeric arguments as repeat counts, with the +repeat count indicating how many weeks, months, or years to move +backward or forward. + +@vindex calendar-week-start-day +@cindex weeks, which day they start on +@cindex calendar, first day of week + By default, weeks begin on Sunday. To make them begin on Monday +instead, set the variable @code{calendar-week-start-day} to 1. + +@node Specified Dates +@subsection Specified Dates + + Calendar mode provides commands for moving to a particular date +specified in various ways. + +@table @kbd +@item g d +Move point to specified date (@code{calendar-goto-date}). +@item o +Center calendar around specified month (@code{calendar-other-month}). +@item . +Move point to today's date (@code{calendar-goto-today}). +@end table + +@kindex g d @r{(Calendar mode)} +@findex calendar-goto-date + @kbd{g d} (@code{calendar-goto-date}) prompts for a year, a month, and a day +of the month, and then moves to that date. Because the calendar includes all +dates from the beginning of the current era, you must type the year in its +entirety; that is, type @samp{1990}, not @samp{90}. + +@kindex o @r{(Calendar mode)} +@findex calendar-other-month + @kbd{o} (@code{calendar-other-month}) prompts for a month and year, +then centers the three-month calendar around that month. + +@kindex . @r{(Calendar mode)} +@findex calendar-goto-today + You can return to today's date with @kbd{.}@: +(@code{calendar-goto-today}). + +@node Scroll Calendar +@section Scrolling in the Calendar + +@cindex scrolling in the calendar + The calendar display scrolls automatically through time when you move out +of the visible portion. You can also scroll it manually. Imagine that the +calendar window contains a long strip of paper with the months on it. +Scrolling it means moving the strip so that new months become visible in +the window. + +@table @kbd +@item C-x < +Scroll calendar one month forward (@code{scroll-calendar-left}). +@item C-x > +Scroll calendar one month backward (@code{scroll-calendar-right}). +@item C-v +@itemx @key{NEXT} +Scroll calendar three months forward +(@code{scroll-calendar-left-three-months}). +@item M-v +@itemx @key{PRIOR} +Scroll calendar three months backward +(@code{scroll-calendar-right-three-months}). +@end table + +@kindex C-x < @r{(Calendar mode)} +@findex scroll-calendar-left +@kindex C-x > @r{(Calendar mode)} +@findex scroll-calendar-right + The most basic calendar scroll commands scroll by one month at a +time. This means that there are two months of overlap between the +display before the command and the display after. @kbd{C-x <} scrolls +the calendar contents one month to the left; that is, it moves the +display forward in time. @kbd{C-x >} scrolls the contents to the +right, which moves backwards in time. + +@kindex C-v @r{(Calendar mode)} +@findex scroll-calendar-left-three-months +@kindex M-v @r{(Calendar mode)} +@findex scroll-calendar-right-three-months + The commands @kbd{C-v} and @kbd{M-v} scroll the calendar by an entire +``screenful''---three months---in analogy with the usual meaning of +these commands. @kbd{C-v} makes later dates visible and @kbd{M-v} makes +earlier dates visible. These commands take a numeric argument as a +repeat count; in particular, since @kbd{C-u} multiplies the next command +by four, typing @kbd{C-u C-v} scrolls the calendar forward by a year and +typing @kbd{C-u M-v} scrolls the calendar backward by a year. + + The function keys @key{NEXT} and @key{PRIOR} are equivalent to +@kbd{C-v} and @kbd{M-v}, just as they are in other modes. + +@node Counting Days +@section Counting Days + +@table @kbd +@item M-= +Display the number of days in the current region +(@code{calendar-count-days-region}). +@end table + +@kindex M-= @r{(Calendar mode)} +@findex calendar-count-days-region + To determine the number of days in the region, type @kbd{M-=} +(@code{calendar-count-days-region}). The numbers of days printed is +@emph{inclusive}; that is, it includes the days specified by mark and +point. + +@node General Calendar +@section Miscellaneous Calendar Commands + +@table @kbd +@item p d +Display day-in-year (@code{calendar-print-day-of-year}). +@item C-c C-l +Regenerate the calendar window (@code{redraw-calendar}). +@item SPC +Scroll the next window (@code{scroll-other-window}). +@item q +Exit from calendar (@code{exit-calendar}). +@end table + +@kindex p d @r{(Calendar mode)} +@cindex day of year +@findex calendar-print-day-of-year + To print the number of days elapsed since the start of the year, or +the number of days remaining in the year, type the @kbd{p d} command +(@code{calendar-print-day-of-year}). This displays both of those +numbers in the echo area. The number of days elapsed includes the +selected date. The number of days remaining does not include that +date. + +@kindex C-c C-l @r{(Calendar mode)} +@findex redraw-calendar + If the calendar window text gets corrupted, type @kbd{C-c C-l} +(@code{redraw-calendar}) to redraw it. (This can only happen if you use +non-Calendar-mode editing commands.) + +@kindex SPC @r{(Calendar mode)} + In Calendar mode, you can use @kbd{SPC} (@code{scroll-other-window}) +to scroll the other window. This is handy when you display a list of +holidays or diary entries in another window. + +@kindex q @r{(Calendar mode)} +@findex exit-calendar + To exit from the calendar, type @kbd{q} (@code{exit-calendar}). This +buries all buffers related to the calendar, selecting other buffers. +(If a frame contains a dedicated calendar window, exiting from the +calendar iconifies that frame.) + +@node LaTeX Calendar +@section LaTeX Calendar +@cindex calendar and La@TeX{} + + The Calendar La@TeX{} commands produce a buffer of La@TeX{} code that +prints as a calendar. Depending on the command you use, the printed +calendar covers the day, week, month or year that point is in. + +@kindex t @r{(Calendar mode)} +@table @kbd +@item t m +Generate a one-month calendar (@code{cal-tex-cursor-month}). +@item t M +Generate a sideways-printing one-month calendar +(@code{cal-tex-cursor-month-landscape}). +@item t d +Generate a one-day calendar +(@code{cal-tex-cursor-day}). +@item t w 1 +Generate a one-page calendar for one week +(@code{cal-tex-cursor-week}). +@item t w 2 +Generate a two-page calendar for one week +(@code{cal-tex-cursor-week2}). +@item t w 3 +Generate an ISO-style calendar for one week +(@code{cal-tex-cursor-week-iso}). +@item t w 4 +Generate a calendar for one Monday-starting week +(@code{cal-tex-cursor-week-monday}). +@item t f w +Generate a Filofax-style two-weeks-at-a-glance calendar +(@code{cal-tex-cursor-filofax-2week}). +@item t f W +Generate a Filofax-style one-week-at-a-glance calendar +(@code{cal-tex-cursor-filofax-week}). +@item t y +Generate a calendar for one year +(@code{cal-tex-cursor-year}). +@item t Y +Generate a sideways-printing calendar for one year +(@code{cal-tex-cursor-year-landscape}). +@item t f y +Generate a Filofax-style calendar for one year +(@code{cal-tex-cursor-filofax-year}). +@end table + + Some of these commands print the calendar sideways (in ``landscape +mode''), so it can be wider than it is long. Some of them use Filofax +paper size (3.75in x 6.75in). All of these commands accept a prefix +argument which specifies how many days, weeks, months or years to print +(starting always with the selected one). + + If the variable @code{cal-tex-holidays} is non-@code{nil} (the default), +then the printed calendars show the holidays in @code{calendar-holidays}. +If the variable @code{cal-tex-diary} is non-@code{nil} (the default is +@code{nil}), diary entries are included also (in weekly and monthly +calendars only). If the variable @code{cal-tex-rules} is non-@code{nil} +(the default is @code{nil}), the calendar styles with sufficient room +have ruled pages. + +@node Holidays +@section Holidays +@cindex holidays + + The Emacs calendar knows about all major and many minor holidays, +and can display them. + +@table @kbd +@item h +Display holidays for the selected date +(@code{calendar-cursor-holidays}). +@item Mouse-2 Holidays +Display any holidays for the date you click on. +@item x +Mark holidays in the calendar window (@code{mark-calendar-holidays}). +@item u +Unmark calendar window (@code{calendar-unmark}). +@item a +List all holidays for the displayed three months in another window +(@code{list-calendar-holidays}). +@item M-x holidays +List all holidays for three months around today's date in another +window. +@item M-x list-holidays +List holidays in another window for a specified range of years. +@end table + +@kindex h @r{(Calendar mode)} +@findex calendar-cursor-holidays + To see if any holidays fall on a given date, position point on that +date in the calendar window and use the @kbd{h} command. Alternatively, +click on that date with @kbd{Mouse-2} and then choose @kbd{Holidays} +from the menu that appears. Either way, this displays the holidays for +that date, in the echo area if they fit there, otherwise in a separate +window. + +@kindex x @r{(Calendar mode)} +@findex mark-calendar-holidays +@kindex u @r{(Calendar mode)} +@findex calendar-unmark + To view the distribution of holidays for all the dates shown in the +calendar, use the @kbd{x} command. This displays the dates that are +holidays in a different face (or places a @samp{*} after these dates, if +display with multiple faces is not available). The command applies both +to the currently visible months and to other months that subsequently +become visible by scrolling. To turn marking off and erase the current +marks, type @kbd{u}, which also erases any diary marks (@pxref{Diary}). + +@kindex a @r{(Calendar mode)} +@findex list-calendar-holidays + To get even more detailed information, use the @kbd{a} command, which +displays a separate buffer containing a list of all holidays in the +current three-month range. You can use @key{SPC} in the calendar window +to scroll that list. + +@findex holidays + The command @kbd{M-x holidays} displays the list of holidays for the +current month and the preceding and succeeding months; this works even +if you don't have a calendar window. If you want the list of holidays +centered around a different month, use @kbd{C-u M-x holidays}, which +prompts for the month and year. + + The holidays known to Emacs include United States holidays and the +major Christian, Jewish, and Islamic holidays; also the solstices and +equinoxes. + +@findex list-holidays + The command @kbd{M-x list-holidays} displays the list of holidays for +a range of years. This function asks you for the starting and stopping +years, and allows you to choose all the holidays or one of several +categories of holidays. You can use this command even if you don't have +a calendar window. + + The dates used by Emacs for holidays are based on @emph{current +practice}, not historical fact. Historically, for instance, the start +of daylight savings time and even its existence have varied from year to +year, but present United States law mandates that daylight savings time +begins on the first Sunday in April. When the daylight savings rules +are set up for the United States, Emacs always uses the present +definition, even though it is wrong for some prior years. + +@node Sunrise/Sunset +@section Times of Sunrise and Sunset +@cindex sunrise and sunset + + Special calendar commands can tell you, to within a minute or two, the +times of sunrise and sunset for any date. + +@table @kbd +@item S +Display times of sunrise and sunset for the selected date +(@code{calendar-sunrise-sunset}). +@item Mouse-2 Sunrise/Sunset +Display times of sunrise and sunset for the date you click on. +@item M-x sunrise-sunset +Display times of sunrise and sunset for today's date. +@item C-u M-x sunrise-sunset +Display times of sunrise and sunset for a specified date. +@end table + +@kindex S @r{(Calendar mode)} +@findex calendar-sunrise-sunset +@findex sunrise-sunset + Within the calendar, to display the @emph{local times} of sunrise and +sunset in the echo area, move point to the date you want, and type +@kbd{S}. Alternatively, click @kbd{Mouse-2} on the date, then choose +@kbd{Sunrise/Sunset} from the menu that appears. The command @kbd{M-x +sunrise-sunset} is available outside the calendar to display this +information for today's date or a specified date. To specify a date +other than today, use @kbd{C-u M-x sunrise-sunset}, which prompts for +the year, month, and day. + + You can display the times of sunrise and sunset for any location and +any date with @kbd{C-u C-u M-x sunrise-sunset}. This asks you for a +longitude, latitude, number of minutes difference from Coordinated +Universal Time, and date, and then tells you the times of sunrise and +sunset for that location on that date. + + Because the times of sunrise and sunset depend on the location on +earth, you need to tell Emacs your latitude, longitude, and location +name before using these commands. Here is an example of what to set: + +@vindex calendar-location-name +@vindex calendar-longitude +@vindex calendar-latitude +@example +(setq calendar-latitude 40.1) +(setq calendar-longitude -88.2) +(setq calendar-location-name "Urbana, IL") +@end example + +@noindent +Use one decimal place in the values of @code{calendar-latitude} and +@code{calendar-longitude}. + + Your time zone also affects the local time of sunrise and sunset. +Emacs usually gets time zone information from the operating system, but +if these values are not what you want (or if the operating system does +not supply them), you must set them yourself. Here is an example: + +@vindex calendar-time-zone +@vindex calendar-standard-time-zone-name +@vindex calendar-daylight-time-zone-name +@example +(setq calendar-time-zone -360) +(setq calendar-standard-time-zone-name "CST") +(setq calendar-daylight-time-zone-name "CDT") +@end example + +@noindent +The value of @code{calendar-time-zone} is the number of minutes +difference between your local standard time and Coordinated Universal +Time (Greenwich time). The values of +@code{calendar-standard-time-zone-name} and +@code{calendar-daylight-time-zone-name} are the abbreviations used in +your time zone. Emacs displays the times of sunrise and sunset +@emph{corrected for daylight savings time}. @xref{Daylight Savings}, +for how daylight savings time is determined. + + As a user, you might find it convenient to set the calendar location +variables for your usual physical location in your @file{.emacs} file. +And when you install Emacs on a machine, you can create a +@file{default.el} file which sets them properly for the typical location +of most users of that machine. @xref{Init File}. + +@node Lunar Phases +@section Phases of the Moon +@cindex phases of the moon +@cindex moon, phases of + + These calendar commands display the dates and times of the phases of +the moon (new moon, first quarter, full moon, last quarter). This +feature is useful for debugging problems that ``depend on the phase of +the moon.'' + +@table @kbd +@item M +Display the dates and times for all the quarters of the moon for the +three-month period shown (@code{calendar-phases-of-moon}). +@item M-x phases-of-moon +Display dates and times of the quarters of the moon for three months around +today's date. +@end table + +@kindex M @r{(Calendar mode)} +@findex calendar-phases-of-moon + Within the calendar, use the @kbd{M} command to display a separate +buffer of the phases of the moon for the current three-month range. The +dates and times listed are accurate to within a few minutes. + +@findex phases-of-moon + Outside the calendar, use the command @kbd{M-x phases-of-moon} to +display the list of the phases of the moon for the current month and the +preceding and succeeding months. For information about a different +month, use @kbd{C-u M-x phases-of-moon}, which prompts for the month and +year. + + The dates and times given for the phases of the moon are given in +local time (corrected for daylight savings, when appropriate); but if +the variable @code{calendar-time-zone} is void, Coordinated Universal +Time (the Greenwich time zone) is used. @xref{Daylight Savings}. + +@node Other Calendars +@section Conversion To and From Other Calendars + +@cindex Gregorian calendar + The Emacs calendar displayed is @emph{always} the Gregorian calendar, +sometimes called the ``new style'' calendar, which is used in most of +the world today. However, this calendar did not exist before the +sixteenth century and was not widely used before the eighteenth century; +it did not fully displace the Julian calendar and gain universal +acceptance until the early twentieth century. The Emacs calendar can +display any month since January, year 1 of the current era, but the +calendar displayed is the Gregorian, even for a date at which the +Gregorian calendar did not exist. + + While Emacs cannot display other calendars, it can convert dates to +and from several other calendars. + +@menu +* Calendar Systems:: The calendars Emacs understands + (aside from Gregorian). +* To Other Calendar:: Converting the selected date to various calendars. +* From Other Calendar:: Moving to a date specified in another calendar. +* Mayan Calendar:: Moving to a date specified in a Mayan calendar. +@end menu + +@node Calendar Systems +@subsection Supported Calendar Systems + +@cindex ISO commercial calendar + The ISO commercial calendar is used largely in Europe. + +@cindex Julian calendar + The Julian calendar, named after Julius Caesar, was the one used in Europe +throughout medieval times, and in many countries up until the nineteenth +century. + +@cindex Julian day numbers +@cindex astronomical day numbers + Astronomers use a simple counting of days elapsed since noon, Monday, +January 1, 4713 B.C. on the Julian calendar. The number of days elapsed +is called the @emph{Julian day number} or the @emph{Astronomical day number}. + +@cindex Hebrew calendar + The Hebrew calendar is used by tradition in the Jewish religion. The +Emacs calendar program uses the Hebrew calendar to determine the dates +of Jewish holidays. Hebrew calendar dates begin and end at sunset. + +@cindex Islamic calendar + The Islamic calendar is used in many predominantly Islamic countries. +Emacs uses it to determine the dates of Islamic holidays. There is no +universal agreement in the Islamic world about the calendar; Emacs uses +a widely accepted version, but the precise dates of Islamic holidays +often depend on proclamation by religious authorities, not on +calculations. As a consequence, the actual dates of observance can vary +slightly from the dates computed by Emacs. Islamic calendar dates begin +and end at sunset. + +@cindex French Revolutionary calendar + The French Revolutionary calendar was created by the Jacobins after the 1789 +revolution, to represent a more secular and nature-based view of the annual +cycle, and to install a 10-day week in a rationalization measure similar to +the metric system. The French government officially abandoned this +calendar at the end of 1805. + +@cindex Mayan calendar + The Maya of Central America used three separate, overlapping calendar +systems, the @emph{long count}, the @emph{tzolkin}, and the @emph{haab}. +Emacs knows about all three of these calendars. Experts dispute the +exact correlation between the Mayan calendar and our calendar; Emacs uses the +Goodman-Martinez-Thompson correlation in its calculations. + +@cindex Coptic calendar +@cindex Ethiopic calendar + The Copts use a calendar based on the ancient Egyptian solar calendar. +Their calendar consists of twelve 30-day months followed by an extra +five-day period. Once every fourth year they add a leap day to this +extra period to make it six days. The Ethiopic calendar is identical in +structure, but has different year numbers and month names. + +@cindex Persian calendar + The Persians use a solar calendar based on a design of Omar Khayyam. +Their calendar consists of twelve months of which the first six have 31 +days, the next five have 30 days, and the last has 29 in ordinary years +and 30 in leap years. Leap years occur in a complicated pattern every +four or five years. + +@cindex Chinese calendar + The Chinese calendar is a complicated system of lunar months arranged +into solar years. The years go in cycles of sixty, each year containing +either twelve months in an ordinary year or thirteen months in a leap +year; each month has either 29 or 30 days. Years, ordinary months, and +days are named by combining one of ten ``celestial stems'' with one of +twelve ``terrestrial branches'' for a total of sixty names that are +repeated in a cycle of sixty. + +@node To Other Calendar +@subsection Converting To Other Calendars + + The following commands describe the selected date (the date at point) +in various other calendar systems: + +@table @kbd +@item Mouse-2 Other Calendars +Display the date that you click on, expressed in various other calendars. +@kindex p @r{(Calendar mode)} +@findex calendar-print-iso-date +@item p c +Display ISO commercial calendar equivalent for selected day +(@code{calendar-print-iso-date}). +@findex calendar-print-julian-date +@item p j +Display Julian date for selected day (@code{calendar-print-julian-date}). +@findex calendar-print-astro-day-number +@item p a +Display astronomical (Julian) day number for selected day +(@code{calendar-print-astro-day-number}). +@findex calendar-print-hebrew-date +@item p h +Display Hebrew date for selected day (@code{calendar-print-hebrew-date}). +@findex calendar-print-islamic-date +@item p i +Display Islamic date for selected day (@code{calendar-print-islamic-date}). +@findex calendar-print-french-date +@item p f +Display French Revolutionary date for selected day +(@code{calendar-print-french-date}). +@findex calendar-print-chinese-date +@item p C +Display Chinese date for selected day +(@code{calendar-print-chinese-date}). +@findex calendar-print-coptic-date +@item p k +Display Coptic date for selected day +(@code{calendar-print-coptic-date}). +@findex calendar-print-ethiopic-date +@item p e +Display Ethiopic date for selected day +(@code{calendar-print-ethiopic-date}). +@findex calendar-print-persian-date +@item p p +Display Persian date for selected day +(@code{calendar-print-persian-date}). +@findex calendar-print-mayan-date +@item p m +Display Mayan date for selected day (@code{calendar-print-mayan-date}). +@end table + + If you are using X, the easiest way to translate a date into other +calendars is to click on it with @kbd{Mouse-2}, then choose @kbd{Other +Calendars} from the menu that appears. This displays the equivalent +forms of the date in all the calendars Emacs understands, in the form of +a menu. (Choosing an alternative from this menu doesn't actually do +anything---the menu is used only for display.) + + Put point on the desired date of the Gregorian calendar, then type the +appropriate keys. The @kbd{p} is a mnemonic for ``print'' since Emacs +``prints'' the equivalent date in the echo area. + +@node From Other Calendar +@subsection Converting From Other Calendars + + You can use the other supported calendars to specify a date to move +to. This section describes the commands for doing this using calendars +other than Mayan; for the Mayan calendar, see the following section. + +@kindex g @var{char} @r{(Calendar mode)} +@findex calendar-goto-iso-date +@findex calendar-goto-julian-date +@findex calendar-goto-astro-day-number +@findex calendar-goto-hebrew-date +@findex calendar-goto-islamic-date +@findex calendar-goto-french-date +@findex calendar-goto-chinese-date +@findex calendar-goto-persian-date +@findex calendar-goto-coptic-date +@findex calendar-goto-ethiopic-date +@table @kbd +@item g c +Move to a date specified in the ISO commercial calendar +(@code{calendar-goto-iso-date}). +@item g j +Move to a date specified in the Julian calendar +(@code{calendar-goto-julian-date}). +@item g a +Move to a date specified in astronomical (Julian) day number +(@code{calendar-goto-astro-day-number}). +@item g h +Move to a date specified in the Hebrew calendar +(@code{calendar-goto-hebrew-date}). +@item g i +Move to a date specified in the Islamic calendar +(@code{calendar-goto-islamic-date}). +@item g f +Move to a date specified in the French Revolutionary calendar +(@code{calendar-goto-french-date}). +@item g C +Move to a date specified in the Chinese calendar +(@code{calendar-goto-chinese-date}). +@item g p +Move to a date specified in the Persian calendar +(@code{calendar-goto-persian-date}). +@item g k +Move to a date specified in the Coptic calendar +(@code{calendar-goto-coptic-date}). +@item g e +Move to a date specified in the Ethiopic calendar +(@code{calendar-goto-ethiopic-date}). +@end table + + These commands ask you for a date on the other calendar, move point to +the Gregorian calendar date equivalent to that date, and display the +other calendar's date in the echo area. Emacs uses strict completion +(@pxref{Completion}) whenever it asks you to type a month name, so you +don't have to worry about the spelling of Hebrew, Islamic, or French names. + +@findex list-yahrzeit-dates +@cindex yahrzeits + One common question concerning the Hebrew calendar is the computation +of the anniversary of a date of death, called a ``yahrzeit.'' The Emacs +calendar includes a facility for such calculations. If you are in the +calendar, the command @kbd{M-x list-yahrzeit-dates} asks you for a +range of years and then displays a list of the yahrzeit dates for those +years for the date given by point. If you are not in the calendar, +this command first asks you for the date of death and the range of +years, and then displays the list of yahrzeit dates. + +@node Mayan Calendar +@subsection Converting from the Mayan Calendar + + Here are the commands to select dates based on the Mayan calendar: + +@table @kbd +@item g m l +Move to a date specified by the long count calendar +(@code{calendar-goto-mayan-long-count-date}). +@item g m n t +Move to the next occurrence of a place in the +tzolkin calendar (@code{calendar-next-tzolkin-date}). +@item g m p t +Move to the previous occurrence of a place in the +tzolkin calendar (@code{calendar-previous-tzolkin-date}). +@item g m n h +Move to the next occurrence of a place in the +haab calendar (@code{calendar-next-haab-date}). +@item g m p h +Move to the previous occurrence of a place in the +haab calendar (@code{calendar-previous-haab-date}). +@item g m n c +Move to the next occurrence of a place in the +calendar round (@code{calendar-next-calendar-round-date}). +@item g m p c +Move to the previous occurrence of a place in the +calendar round (@code{calendar-previous-calendar-round-date}). +@end table + +@cindex Mayan long count + To understand these commands, you need to understand the Mayan calendars. +The @dfn{long count} is a counting of days with these units: + +@display +1 kin = 1 day@ @ @ 1 uinal = 20 kin@ @ @ 1 tun = 18 uinal +1 katun = 20 tun@ @ @ 1 baktun = 20 katun +@end display + +@kindex g m @r{(Calendar mode)} +@findex calendar-goto-mayan-long-count-date +@noindent +Thus, the long count date 12.16.11.16.6 means 12 baktun, 16 katun, 11 +tun, 16 uinal, and 6 kin. The Emacs calendar can handle Mayan long +count dates as early as 7.17.18.13.1, but no earlier. When you use the +@kbd{g m l} command, type the Mayan long count date with the baktun, +katun, tun, uinal, and kin separated by periods. + +@findex calendar-previous-tzolkin-date +@findex calendar-next-tzolkin-date +@cindex Mayan tzolkin calendar + The Mayan tzolkin calendar is a cycle of 260 days formed by a pair of +independent cycles of 13 and 20 days. Since this cycle repeats +endlessly, Emacs provides commands to move backward and forward to the +previous or next point in the cycle. Type @kbd{g m p t} to go to the +previous tzolkin date; Emacs asks you for a tzolkin date and moves point +to the previous occurrence of that date. Similarly, type @kbd{g m n t} +to go to the next occurrence of a tzolkin date. + +@findex calendar-previous-haab-date +@findex calendar-next-haab-date +@cindex Mayan haab calendar + The Mayan haab calendar is a cycle of 365 days arranged as 18 months +of 20 days each, followed a 5-day monthless period. Like the tzolkin +cycle, this cycle repeats endlessly, and there are commands to move +backward and forward to the previous or next point in the cycle. Type +@kbd{g m p h} to go to the previous haab date; Emacs asks you for a haab +date and moves point to the previous occurrence of that date. +Similarly, type @kbd{g m n h} to go to the next occurrence of a haab +date. + +@c This is omitted because it is too long for smallbook format. +@c @findex calendar-previous-calendar-round-date +@findex calendar-next-calendar-round-date +@cindex Mayan calendar round + The Maya also used the combination of the tzolkin date and the haab +date. This combination is a cycle of about 52 years called a +@emph{calendar round}. If you type @kbd{g m p c}, Emacs asks you for +both a haab and a tzolkin date and then moves point to the previous +occurrence of that combination. Use @kbd{g m n c} to move point to the +next occurrence of a combination. These commands signal an error if the +haab/tzolkin date combination you have typed is impossible. + + Emacs uses strict completion (@pxref{Strict Completion}) whenever it +asks you to type a Mayan name, so you don't have to worry about +spelling. + +@node Diary +@section The Diary +@cindex diary + + The Emacs diary keeps track of appointments or other events on a daily +basis, in conjunction with the calendar. To use the diary feature, you +must first create a @dfn{diary file} containing a list of events and +their dates. Then Emacs can automatically pick out and display the +events for today, for the immediate future, or for any specified +date. + + By default, Emacs uses @file{~/diary} as the diary file. This is the +same file that the @code{calendar} utility uses. A sample +@file{~/diary} file is: + +@example +12/22/1988 Twentieth wedding anniversary!! +&1/1. Happy New Year! +10/22 Ruth's birthday. +* 21, *: Payday +Tuesday--weekly meeting with grad students at 10am + Supowit, Shen, Bitner, and Kapoor to attend. +1/13/89 Friday the thirteenth!! +&thu 4pm squash game with Lloyd. +mar 16 Dad's birthday +April 15, 1989 Income tax due. +&* 15 time cards due. +@end example + +@noindent +This example uses extra spaces to align the event descriptions of most +of the entries. Such formatting is purely a matter of taste. + + Although you probably will start by creating a diary manually, Emacs +provides a number of commands to let you view, add, and change diary +entries. + +@menu +* Diary Commands:: Viewing diary entries and associated calendar dates. +* Format of Diary File:: Entering events in your diary. +* Date Formats:: Various ways you can specify dates. +* Adding to Diary:: Commands to create diary entries. +* Special Diary Entries:: Anniversaries, blocks of dates, cyclic entries, etc. +@end menu + +@node Diary Commands +@subsection Commands Displaying Diary Entries + + Once you have created a @file{~/diary} file, you can use the calendar +to view it. You can also view today's events outside of Calendar mode. + +@table @kbd +@item d +Display all diary entries for the selected date +(@code{view-diary-entries}). +@item Mouse-2 Diary +Display all diary entries for the date you click on. +@item s +Display the entire diary file (@code{show-all-diary-entries}). +@item m +Mark all visible dates that have diary entries +(@code{mark-diary-entries}). +@item u +Unmark the calendar window (@code{calendar-unmark}). +@item M-x print-diary-entries +Print hard copy of the diary display as it appears. +@item M-x diary +Display all diary entries for today's date. +@item M-x diary-mail-entries +Mail yourself email reminders about upcoming diary entries. +@end table + +@kindex d @r{(Calendar mode)} +@findex view-diary-entries + Displaying the diary entries with @kbd{d} shows in a separate window +the diary entries for the selected date in the calendar. The mode line +of the new window shows the date of the diary entries and any holidays +that fall on that date. If you specify a numeric argument with @kbd{d}, +it shows all the diary entries for that many successive days. Thus, +@kbd{2 d} displays all the entries for the selected date and for the +following day. + + Another way to display the diary entries for a date is to click +@kbd{Mouse-2} on the date, and then choose @kbd{Diary} from the menu +that appears. + +@kindex m @r{(Calendar mode)} +@findex mark-diary-entries + To get a broader view of which days are mentioned in the diary, use +the @kbd{m} command. This displays the dates that have diary entries +in a different face (or places a @samp{+} after these dates, if +display with multiple faces is not available). The command applies both +to the currently visible months and to other months that subsequently +become visible by scrolling. To turn marking off and erase the current +marks, type @kbd{u}, which also turns off holiday marks +(@pxref{Holidays}). + +@kindex s @r{(Calendar mode)} +@findex show-all-diary-entries + To see the full diary file, rather than just some of the entries, use +the @kbd{s} command. + + Display of selected diary entries uses the selective display feature +to hide entries that don't apply. + + The diary buffer as you see it is an illusion, so simply printing the +buffer does not print what you see on your screen. There is a special +command to print hard copy of the diary buffer @emph{as it appears}; +this command is @kbd{M-x print-diary-entries}. It sends the data +directly to the printer. You can customize it like @code{lpr-region} +(@pxref{Hardcopy}). + +@findex diary + The command @kbd{M-x diary} displays the diary entries for the current +date, independently of the calendar display, and optionally for the next +few days as well; the variable @code{number-of-diary-entries} specifies +how many days to include. @xref{Calendar, Customizing the Calendar +and Diary,, elisp, The Emacs Lisp Reference Manual}. + + If you put @code{(diary)} in your @file{.emacs} file, this +automatically displays a window with the day's diary entries, when you +enter Emacs. The mode line of the displayed window shows the date and +any holidays that fall on that date. + +@findex diary-mail-entries +@vindex diary-mail-days + Many users like to receive notice of events in their diary as email. +To send such mail to yourself, use the command @kbd{M-x +diary-mail-entries}. A prefix argument specifies how many days +(starting with today) to check; otherwise, the variable +@code{diary-mail-days} says how many days. + +@node Format of Diary File +@subsection The Diary File +@cindex diary file + +@vindex diary-file + Your @dfn{diary file} is a file that records events associated with +particular dates. The name of the diary file is specified by the +variable @code{diary-file}; @file{~/diary} is the default. The +@code{calendar} utility program supports a subset of the format allowed +by the Emacs diary facilities, so you can use that utility to view the +diary file, with reasonable results aside from the entries it cannot +understand. + + Each entry in the diary file describes one event and consists of one +or more lines. An entry always begins with a date specification at the +left margin. The rest of the entry is simply text to describe the +event. If the entry has more than one line, then the lines after the +first must begin with whitespace to indicate they continue a previous +entry. Lines that do not begin with valid dates and do not continue a +preceding entry are ignored. + + You can inhibit the marking of certain diary entries in the calendar +window; to do this, insert an ampersand (@samp{&}) at the beginning of +the entry, before the date. This has no effect on display of the entry +in the diary window; it affects only marks on dates in the calendar +window. Nonmarking entries are especially useful for generic entries +that would otherwise mark many different dates. + + If the first line of a diary entry consists only of the date or day +name with no following blanks or punctuation, then the diary window +display doesn't include that line; only the continuation lines appear. +For example, this entry: + +@example +02/11/1989 + Bill B. visits Princeton today + 2pm Cognitive Studies Committee meeting + 2:30-5:30 Liz at Lawrenceville + 4:00pm Dentist appt + 7:30pm Dinner at George's + 8:00-10:00pm concert +@end example + +@noindent +appears in the diary window without the date line at the beginning. +This style of entry looks neater when you display just a single day's +entries, but can cause confusion if you ask for more than one day's +entries. + + You can edit the diary entries as they appear in the window, but it is +important to remember that the buffer displayed contains the @emph{entire} +diary file, with portions of it concealed from view. This means, for +instance, that the @kbd{C-f} (@code{forward-char}) command can put point +at what appears to be the end of the line, but what is in reality the +middle of some concealed line. + + @emph{Be careful when editing the diary entries!} Inserting +additional lines or adding/deleting characters in the middle of a +visible line cannot cause problems, but editing at the end of a line may +not do what you expect. Deleting a line may delete other invisible +entries that follow it. Before editing the diary, it is best to display +the entire file with @kbd{s} (@code{show-all-diary-entries}). + +@node Date Formats +@subsection Date Formats + + Here are some sample diary entries, illustrating different ways of +formatting a date. The examples all show dates in American order +(month, day, year), but Calendar mode supports European order (day, +month, year) as an option. + +@example +4/20/93 Switch-over to new tabulation system +apr. 25 Start tabulating annual results +4/30 Results for April are due +*/25 Monthly cycle finishes +Friday Don't leave without backing up files +@end example + + The first entry appears only once, on April 20, 1993. The second and +third appear every year on the specified dates, and the fourth uses a +wildcard (asterisk) for the month, so it appears on the 25th of every +month. The final entry appears every week on Friday. + + You can use just numbers to express a date, as in +@samp{@var{month}/@var{day}} or @samp{@var{month}/@var{day}/@var{year}}. +This must be followed by a nondigit. In the date itself, @var{month} +and @var{day} are numbers of one or two digits. The optional @var{year} +is also a number, and may be abbreviated to the last two digits; that +is, you can use @samp{11/12/1989} or @samp{11/12/89}. + + Dates can also have the form @samp{@var{monthname} @var{day}} or +@samp{@var{monthname} @var{day}, @var{year}}, where the month's name can +be spelled in full or abbreviated to three characters (with or without a +period). Case is not significant. + + A date may be @dfn{generic}; that is, partially unspecified. Then the +entry applies to all dates that match the specification. If the date +does not contain a year, it is generic and applies to any year. +Alternatively, @var{month}, @var{day}, or @var{year} can be a @samp{*}; +this matches any month, day, or year, respectively. Thus, a diary entry +@samp{3/*/*} matches any day in March of any year; so does @samp{march +*}. + +@vindex european-calendar-style +@findex european-calendar +@findex american-calendar + If you prefer the European style of writing dates---in which the day +comes before the month---type @kbd{M-x european-calendar} while in the +calendar, or set the variable @code{european-calendar-style} to @code{t} +@emph{before} using any calendar or diary command. This mode interprets +all dates in the diary in the European manner, and also uses European +style for displaying diary dates. (Note that there is no comma after +the @var{monthname} in the European style.) To go back to the (default) +American style of writing dates, type @kbd{M-x american-calendar}. + + You can use the name of a day of the week as a generic date which +applies to any date falling on that day of the week. You can abbreviate +the day of the week to three letters (with or without a period) or spell +it in full; case is not significant. + +@node Adding to Diary +@subsection Commands to Add to the Diary + + While in the calendar, there are several commands to create diary +entries: + +@table @kbd +@item i d +Add a diary entry for the selected date (@code{insert-diary-entry}). +@item i w +Add a diary entry for the selected day of the week (@code{insert-weekly-diary-entry}). +@item i m +Add a diary entry for the selected day of the month (@code{insert-monthly-diary-entry}). +@item i y +Add a diary entry for the selected day of the year (@code{insert-yearly-diary-entry}). +@end table + +@kindex i d @r{(Calendar mode)} +@findex insert-diary-entry + You can make a diary entry for a specific date by selecting that date +in the calendar window and typing the @kbd{i d} command. This command +displays the end of your diary file in another window and inserts the +date; you can then type the rest of the diary entry. + +@kindex i w @r{(Calendar mode)} +@findex insert-weekly-diary-entry +@kindex i m @r{(Calendar mode)} +@findex insert-monthly-diary-entry +@kindex i y @r{(Calendar mode)} +@findex insert-yearly-diary-entry + If you want to make a diary entry that applies to a specific day of +the week, select that day of the week (any occurrence will do) and type +@kbd{i w}. This inserts the day-of-week as a generic date; you can then +type the rest of the diary entry. You can make a monthly diary entry in +the same fashion. Select the day of the month, use the @kbd{i m} +command, and type rest of the entry. Similarly, you can insert a yearly +diary entry with the @kbd{i y} command. + + All of the above commands make marking diary entries by default. To +make a nonmarking diary entry, give a numeric argument to the command. +For example, @kbd{C-u i w} makes a nonmarking weekly diary entry. + + When you modify the diary file, be sure to save the file before +exiting Emacs. + +@node Special Diary Entries +@subsection Special Diary Entries + + In addition to entries based on calendar dates, the diary file can +contain @dfn{sexp entries} for regular events such as anniversaries. +These entries are based on Lisp expressions (sexps) that Emacs evaluates +as it scans the diary file. Instead of a date, a sexp entry contains +@samp{%%} followed by a Lisp expression which must begin and end with +parentheses. The Lisp expression determines which dates the entry +applies to. + + Calendar mode provides commands to insert certain commonly used +sexp entries: + +@table @kbd +@item i a +Add an anniversary diary entry for the selected date +(@code{insert-anniversary-diary-entry}). +@item i b +Add a block diary entry for the current region +(@code{insert-block-diary-entry}). +@item i c +Add a cyclic diary entry starting at the date +(@code{insert-cyclic-diary-entry}). +@end table + +@kindex i a @r{(Calendar mode)} +@findex insert-anniversary-diary-entry + If you want to make a diary entry that applies to the anniversary of a +specific date, move point to that date and use the @kbd{i a} command. +This displays the end of your diary file in another window and inserts +the anniversary description; you can then type the rest of the diary +entry. The entry looks like this: + +@findex diary-anniversary +@example +%%(diary-anniversary 10 31 1948) Arthur's birthday +@end example + +@noindent +This entry applies to October 31 in any year after 1948; @samp{10 31 +1948} specifies the date. (If you are using the European calendar +style, the month and day are interchanged.) The reason this expression +requires a beginning year is that advanced diary functions can use it to +calculate the number of elapsed years. + + A @dfn{block} diary entry applies to a specified range of consecutive +dates. Here is a block diary entry that applies to all dates from June +24, 1990 through July 10, 1990: + +@findex diary-block +@example +%%(diary-block 6 24 1990 7 10 1990) Vacation +@end example + +@noindent +The @samp{6 24 1990} indicates the starting date and the @samp{7 10 1990} +indicates the stopping date. (Again, if you are using the European calendar +style, the month and day are interchanged.) + +@kindex i b @r{(Calendar mode)} +@findex insert-block-diary-entry + To insert a block entry, place point and the mark on the two +dates that begin and end the range, and type @kbd{i b}. This command +displays the end of your diary file in another window and inserts the +block description; you can then type the diary entry. + +@kindex i c @r{(Calendar mode)} +@findex insert-cyclic-diary-entry + @dfn{Cyclic} diary entries repeat after a fixed interval of days. To +create one, select the starting date and use the @kbd{i c} command. The +command prompts for the length of interval, then inserts the entry, +which looks like this: + +@findex diary-cyclic +@example +%%(diary-cyclic 50 3 1 1990) Renew medication +@end example + +@noindent +This entry applies to March 1, 1990 and every 50th day following; +@samp{3 1 1990} specifies the starting date. (If you are using the +European calendar style, the month and day are interchanged.) + + All three of these commands make marking diary entries. To insert a +nonmarking entry, give a numeric argument to the command. For example, +@kbd{C-u i a} makes a nonmarking anniversary diary entry. + + Marking sexp diary entries in the calendar is @emph{extremely} +time-consuming, since every date visible in the calendar window must be +individually checked. So it's a good idea to make sexp diary entries +nonmarking (with @samp{&}) when possible. + + Another sophisticated kind of sexp entry, a @dfn{floating} diary entry, +specifies a regularly occurring event by offsets specified in days, +weeks, and months. It is comparable to a crontab entry interpreted by +the @code{cron} utility. Here is a nonmarking, floating diary entry +that applies to the last Thursday in November: + +@findex diary-float +@example +&%%(diary-float 11 4 -1) American Thanksgiving +@end example + +@noindent +The 11 specifies November (the eleventh month), the 4 specifies Thursday +(the fourth day of the week, where Sunday is numbered zero), and the +@minus{}1 specifies ``last'' (1 would mean ``first,'' 2 would mean +``second,'' @minus{}2 would mean ``second-to-last,'' and so on). The +month can be a single month or a list of months. Thus you could change +the 11 above to @samp{'(1 2 3)} and have the entry apply to the last +Thursday of January, February, and March. If the month is @code{t}, the +entry applies to all months of the year.@refill + + Most generally, sexp diary entries can perform arbitrary +computations to determine when they apply. @xref{Sexp Diary Entries,, +Sexp Diary Entries, elisp, The Emacs Lisp Reference Manual}. + +@node Appointments +@section Appointments +@cindex appointment notification + + If you have a diary entry for an appointment, and that diary entry +begins with a recognizable time of day, Emacs can warn you, several +minutes beforehand, that that appointment is pending. Emacs alerts you +to the appointment by displaying a message in the mode line. + +@vindex diary-hook +@findex appt-make-list + To enable appointment notification, you must enable the time display +feature of Emacs, @kbd{M-x display-time} (@pxref{Mode Line}). You must +also add the function @code{appt-make-list} to the +@code{diary-hook}, like this: + +@example +(add-hook 'diary-hook 'appt-make-list) +@end example + +@noindent +Adding this text to your @file{.emacs} file does the whole job: + +@example +(display-time) +(add-hook 'diary-hook 'appt-make-list) +(diary 0) +@end example + + With these preparations done, when you display the diary (either with +the @kbd{d} command in the calendar window or with the @kbd{M-x diary} +command), it sets up an appointment list of all the diary entries found +with recognizable times of day, and reminds you just before each of +them. + + For example, suppose the diary file contains these lines: + +@example +Monday + 9:30am Coffee break + 12:00pm Lunch +@end example + +@noindent +Then on Mondays, after you have displayed the diary, you will be +reminded at 9:20am about your coffee break and at 11:50am about lunch. + + You can write times in am/pm style (with @samp{12:00am} standing +for midnight and @samp{12:00pm} standing for noon), or 24-hour +European/military style. You need not be consistent; your diary file +can have a mixture of the two styles. + +@vindex appt-display-diary + Emacs updates the appointments list automatically just after +midnight. This also displays the next day's diary entries in the diary +buffer, unless you set @code{appt-display-diary} to @code{nil}. + +@findex appt-add +@findex appt-delete +@cindex alarm clock + You can also use the appointment notification facility like an alarm +clock. The command @kbd{M-x appt-add} adds entries to the appointment +list without affecting your diary file. You delete entries from the +appointment list with @kbd{M-x appt-delete}. + +@vindex appt-issue-message + You can turn off the appointment notification feature at any time by +setting @code{appt-issue-message} to @code{nil}. + +@node Daylight Savings +@section Daylight Savings Time +@cindex daylight savings time + + Emacs understands the difference between standard time and daylight +savings time---the times given for sunrise, sunset, solstices, +equinoxes, and the phases of the moon take that into account. The rules +for daylight savings time vary from place to place and have also varied +historically from year to year. To do the job properly, Emacs needs to +know which rules to use. + +@vindex calendar-daylight-savings-starts +@vindex calendar-daylight-savings-ends + Some operating systems keep track of the rules that apply to the place +where you are; on these systems, Emacs gets the information it needs +from the system automatically. If some or all of this information is +missing, Emacs fills in the gaps with the rules currently used in +Cambridge, Massachusetts. If the resulting rules are not what you want, +you can tell Emacs the rules to use by setting certain variables: +@code{calendar-daylight-savings-starts} and +@code{calendar-daylight-savings-ends}. + + These values should be Lisp expressions that refer to the variable +@code{year}, and evaluate to the Gregorian date on which daylight +savings time starts or (respectively) ends, in the form of a list +@code{(@var{month} @var{day} @var{year})}. The values should be +@code{nil} if your area does not use daylight savings time. + + Emacs uses these expressions to determine the starting date of +daylight savings time for the holiday list and for correcting times of +day in the solar and lunar calculations. + + The values for Cambridge, Massachusetts are as follows: + +@example +(calendar-nth-named-day 1 0 4 year) +(calendar-nth-named-day -1 0 10 year) +@end example + +@noindent +That is, the first 0th day (Sunday) of the fourth month (April) in +the year specified by @code{year}, and the last Sunday of the tenth month +(October) of that year. If daylight savings time were +changed to start on October 1, you would set +@code{calendar-daylight-savings-starts} to this: + +@example +(list 10 1 year) +@end example + + If there is no daylight savings time at your location, or if you want +all times in standard time, set @code{calendar-daylight-savings-starts} +and @code{calendar-daylight-savings-ends} to @code{nil}. + +@vindex calendar-daylight-time-offset + The variable @code{calendar-daylight-time-offset} specifies the +difference between daylight savings time and standard time, measured in +minutes. The value for Cambridge, Massachusetts is 60. + +@c @vindex calendar-daylight-savings-starts-time too long! +@vindex calendar-daylight-savings-ends-time + The two variables @code{calendar-daylight-savings-starts-time} and +@code{calendar-daylight-savings-ends-time} specify the number of minutes +after midnight local time when the transition to and from daylight +savings time should occur. For Cambridge, Massachusetts both variables' +values are 120. diff --git a/man/cc-mode.texi b/man/cc-mode.texi new file mode 100644 index 00000000000..c515e28c7be --- /dev/null +++ b/man/cc-mode.texi @@ -0,0 +1,3560 @@ +\input texinfo + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment %**start of header (This is for running Texinfo on a region) +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@setfilename ../info/ccmode +@settitle CC MODE Version 5 Documentation +@footnotestyle end + +@dircategory Editors +@direntry +* CC mode: (ccmode). The GNU Emacs mode for editing C, C++, Objective-C + and Java code. +@end direntry + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment @setchapternewpage odd !! we don't want blank pages !! +@comment %**end of header (This is for running Texinfo on a region) +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment +@comment Texinfo manual for CC Mode +@comment Generated from the original README file by Krishna Padmasola +@comment <krishna@earth-gw.njit.edu> +@comment +@comment Maintained by Barry A. Warsaw <cc-mode-help@python.org> +@comment +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment The following line inserts the copyright notice +@comment into the Info file. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@ifinfo +Copyright @copyright{} 1995,96,97,98 Free Software Foundation, Inc. +@end ifinfo + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment !!!The titlepage section does not appear in the Info file.!!! +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@titlepage +@sp 10 + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment The title is printed in a large font. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@center @titlefont{CC Mode 5.21} +@sp 2 +@center @subtitlefont{A GNU Emacs mode for editing C and C-like languages} +@sp 2 +@center Barry A. Warsaw + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment The following two commands start the copyright page +@comment for the printed manual. This will not appear in the Info file. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1995,96,97,98 Free Software Foundation, Inc. +@end titlepage + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment The Top node contains the master menu for the Info file. +@comment This appears only in the Info file, not the printed manual. +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@node Top, Introduction, (dir), (dir) +@comment node-name, next, previous, up + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@menu +* Introduction:: +* Getting Connected:: +* New Indentation Engine:: +* Minor Modes:: +* Commands:: +* Customizing Indentation:: +* Syntactic Symbols:: +* Performance Issues:: +* Frequently Asked Questions:: +* Getting the latest CC Mode release:: +* Sample .emacs File:: +* Limitations and Known Bugs:: +* Mailing Lists and Submitting Bug Reports:: +* Concept Index:: +* Command Index:: Command Index +* Key Index:: Key Index +* Variable Index:: Variable Index +@end menu + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@node Introduction, Getting Connected, Top, Top +@comment node-name, next, previous, up +@chapter Introduction +@cindex Introduction + +@macro ccmode +CC Mode +@end macro + +@cindex BOCM + +Welcome to @ccmode{}. This is a GNU Emacs mode for editing files +containing C, C++, Objective-C, Java, and CORBA IDL code. This +incarnation of the mode is descendant from @file{c-mode.el} (also called +"Boring Old C Mode" or BOCM @code{:-)}, and @file{c++-mode.el} version +2, which I have been maintaining since 1992. @ccmode{} represents a +significant milestone in the mode's life. It has been fully merged back +with Emacs 19's @file{c-mode.el}. Also a new, more intuitive and +flexible mechanism for controlling indentation has been developed. + +@ccmode{} supports the editing of K&R and ANSI C, @dfn{ARM} +@footnote{``The Annotated C++ Reference Manual'', by Ellis and +Stroustrup.} C++, Objective-C, Java and CORBA's Interface +Definition Language files. In this way, you can +easily set up consistent coding styles for use in editing all C, C++, +Objective-C, Java and IDL programs. @ccmode{} does @emph{not} handle +font-locking (a.k.a. syntax coloring, keyword highlighting) or anything +of that nature, for any of these modes. Font-locking is handled by other +Emacs packages. + +This manual will describe the following: + +@itemize @bullet +@item +How to get started using @ccmode{}. + +@item +How the new indentation engine works. + +@item +How to customize the new indentation engine. + +@end itemize + +@findex c-mode +@findex c++-mode +@findex objc-mode +@findex java-mode +@findex idl-mode +Note that the name of this package is ``@ccmode{}'', but there is no top +level @code{cc-mode} entry point. All of the variables, commands, and +functions in @ccmode{} are prefixed with @code{c-@var{<thing>}}, and +@code{c-mode}, @code{c++-mode}, @code{objc-mode}, @code{java-mode}, and +@code{idl-mode} entry points are provided. This file is intended to be +a replacement for @file{c-mode.el} and @file{c++-mode.el}. + +@cindex @file{cc-compat.el} file +This distribution also contains a file +called @file{cc-compat.el} which should ease your transition from BOCM +to @ccmode{}. If you have a BOCM configuration you are really happy +with, and want to postpone learning how to configure @ccmode{}, take a +look at that file. It maps BOCM configuration variables to @ccmode{}'s +new indentation model. It is not actively supported so for the long +run, you should learn how to customize @ccmode{} to support your coding +style. + +A special word of thanks goes to Krishna Padmasola for his work in +converting the original @file{README} file to Texinfo format. I'd also +like to thank all the @ccmode{} victims who help enormously during the +early beta stages of @ccmode{}'s development. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@node Getting Connected, New Indentation Engine, Introduction, Top +@comment node-name, next, previous, up +@chapter Getting Connected +@cindex Getting Connected + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +If you got this version of @ccmode{} with Emacs or XEmacs, it should +work just fine right out of the box. Note however that you may not have +the latest @ccmode{} release and may want to upgrade your copy. + +If you are upgrading an existing @ccmode{} installation, please see the +@file{README} file for installation details. @ccmode{} may not work +with older versions of Emacs or XEmacs. See the @ccmode{} release notes +Web pages for the latest information on Emacs version and package +compatibility (see @ref{Getting the latest CC Mode release}). + +@cindex @file{cc-mode-18.el} file +@emph{Note that @ccmode{} no longer works with Emacs 18!} The +@file{cc-mode-18.el} file is no longer distributed with @ccmode{}. If +you haven't upgraded from Emacs 18 by now, you are out of luck. + +@findex c-version +@findex version (c-) +You can find out what version of @ccmode{} you are using by visiting a C +file and entering @kbd{M-x c-version RET}. You should see this message in +the echo area: +@example + +Using CC Mode version 5.XX + +@end example + +@noindent +where @samp{XX} is the minor release number. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node New Indentation Engine, Minor Modes, Getting Connected, Top +@comment node-name, next, previous, up + +@chapter New Indentation Engine +@cindex New Indentation Engine +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@ccmode{} has a new indentation engine, providing a simplified, yet +flexible and general mechanism for customizing indentation. It separates +indentation calculation into two steps: first, @ccmode{} analyzes the +line of code being indented to determine the kind of language construct +it's looking at, then it applies user defined offsets to the current +line based on this analysis. + +This section will briefly cover how indentation is calculated in +@ccmode{}. It is important to understand the indentation model +being used so that you will know how to customize @ccmode{} for +your personal coding style. + +@menu +* Syntactic Analysis:: +* Indentation Calculation:: +@end menu + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Syntactic Analysis, Indentation Calculation, , New Indentation Engine +@comment node-name, next, previous,up +@section Syntactic Analysis +@cindex Syntactic Analysis +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@vindex c-offsets-alist +@vindex offsets-alist (c-) +@cindex relative buffer position +@cindex syntactic symbol +@cindex syntactic component +@cindex syntactic component list +@cindex relative buffer position +The first thing @ccmode{} does when indenting a line of code, is to +analyze the line, determining the @dfn{syntactic component list} of the +construct on that line. A syntactic component consists of a pair +of information (in lisp parlance, a @emph{cons cell}), where the first +part is a @dfn{syntactic symbol}, and the second part is a @dfn{relative +buffer position}. Syntactic symbols describe elements of C code +@footnote{or C++, Objective-C, Java or IDL code. In general, for the rest +of this manual I'll use the term ``C code'' to refer to all the C-like +dialects, unless otherwise noted.}, e.g. @code{statement}, +@code{substatement}, @code{class-open}, @code{class-close}, etc. +@xref{Syntactic Symbols}, for a complete list of currently recognized +syntactic symbols and their semantics. The variable +@code{c-offsets-alist} also contains the list of currently supported +syntactic symbols. + +Conceptually, a line of C code is always indented relative to the +indentation of some line higher up in the buffer. This is represented +by the relative buffer position in the syntactic component. + +Here is an example. Suppose we had the following code as the only thing +in a @code{c++-mode} buffer @footnote{The line numbers in this and +future examples don't actually appear in the buffer, of course!}: +@example +@group + + 1: void swap( int& a, int& b ) + 2: @{ + 3: int tmp = a; + 4: a = b; + 5: b = tmp; + 6: @} + +@end group +@end example + +@kindex C-c C-s +@findex c-show-syntactic-information +@findex show-syntactic-information (c-) +We can use the command @kbd{C-c C-s} +(@code{c-show-syntactic-information}) to simply report what the +syntactic analysis is for the current line. Running this command on +line 4 of this example, we'd see in the echo area@footnote{With a universal +argument (i.e. @kbd{C-u C-c C-s}) the analysis is inserted into the +buffer as a comment +on the current line.}: +@example + +((statement . 35)) + +@end example + +This tells us that the line is a statement and it is indented relative +to buffer position 35, which happens to be the @samp{i} in @code{int} on +line 3. If you were to move point to line 3 and hit @kbd{C-c C-s}, you +would see: +@example + +((defun-block-intro . 29)) + +@end example + +This indicates that the @samp{int} line is the first statement in a top +level function block, and is indented relative to buffer position 29, +which is the brace just after the function header. + +Here's another example: +@example +@group + + 1: int add( int val, int incr, int doit ) + 2: @{ + 3: if( doit ) + 4: @{ + 5: return( val + incr ); + 6: @} + 7: return( val ); + 8: @} + +@end group +@end example + +@noindent +Hitting @kbd{C-c C-s} on line 4 gives us: +@example + +((substatement-open . 46)) + +@end example + +@cindex substatement +@cindex substatment block +@noindent +which tells us that this is a brace that @emph{opens} a substatement +block. @footnote{A @dfn{substatement} is the line after a +conditional statement, such as @code{if}, @code{else}, @code{while}, +@code{do}, @code{switch}, etc. A @dfn{substatement +block} is a brace block following one of these conditional statements.} + +@cindex comment-only line +Syntactic component lists can contain more than one component, and +individual syntactic components need not have relative buffer positions. +The most common example of this is a line that contains a @dfn{comment +only line}. +@example +@group + + 1: void draw_list( List<Drawables>& drawables ) + 2: @{ + 3: // call the virtual draw() method on each element in list + 4: for( int i=0; i < drawables.count(), ++i ) + 5: @{ + 6: drawables[i].draw(); + 7: @} + 8: @} + +@end group +@end example + +@noindent +Hitting @kbd{C-c C-s} on line 3 of this example gives: +@example + +((comment-intro) (defun-block-intro . 46)) + +@end example + +@noindent +and you can see that the syntactic component list contains two syntactic +components. Also notice that the first component, +@samp{(comment-intro)} has no relative buffer position. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Indentation Calculation, , Syntactic Analysis, New Indentation Engine +@comment node-name, next, previous,up +@section Indentation Calculation +@cindex Indentation Calculation +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@vindex c-offsets-alist +@vindex offsets-alist (c-) +Indentation for a line is calculated using the syntactic +component list derived in step 1 above (see @ref{Syntactic Analysis}). +Each component contributes to the final total indentation of the line in +two ways. + +First, the syntactic symbols are looked up in the @code{c-offsets-alist} +variable, which is an association list of syntactic symbols and the +offsets to apply for those symbols. These offsets are added to a +running total. + +Second, if the component has a relative buffer position, @ccmode{} +adds the column number of that position to the running total. By adding +up the offsets and columns for every syntactic component on the list, +the final total indentation for the current line is computed. + +Let's use our two code examples above to see how this works. Here is +our first example again: +@example +@group + + 1: void swap( int& a, int& b ) + 2: @{ + 3: int tmp = a; + 4: a = b; + 5: b = tmp; + 6: @} + +@end group +@end example + +@kindex TAB +Let's say point is on line 3 and we hit the @kbd{TAB} key to re-indent +the line. Remember that the syntactic component list for that +line is: +@example + +((defun-block-intro . 29)) + +@end example + +@noindent +@ccmode{} looks up @code{defun-block-intro} in the +@code{c-offsets-alist} variable. Let's say it finds the value @samp{4}; +it adds this to the running total (initialized to zero), yielding a +running total indentation of 4 spaces. + +Next @ccmode{} goes to buffer position 29 and asks for the current +column. This brace is in column zero, so @ccmode{} +adds @samp{0} to the running total. Since there is only one syntactic +component on the list for this line, indentation calculation is +complete, and the total indentation for the line +is 4 spaces. + +Here's another example: +@example +@group + + 1: int add( int val, int incr, int doit ) + 2: @{ + 3: if( doit ) + 4: @{ + 5: return( val + incr ); + 6: @} + 7: return( val ); + 8: @} + +@end group +@end example + +If we were to hit @kbd{TAB} on line 4 in the above example, the same +basic process is performed, despite the differences in the syntactic +component list. Remember that the list for this line is: +@example + +((substatement-open . 46)) + +@end example + +Here, @ccmode{} first looks up the @code{substatement-open} symbol +in @code{c-offsets-alist}. Let's say it finds the value @samp{4}. This +yields a running total of 4. @ccmode{} then goes to +buffer position 46, which is the @samp{i} in @code{if} on line 3. This +character is in the fourth column on that line so adding this to the +running total yields an indentation for the line of 8 spaces. + +Simple, huh? + +Actually, the mode usually just does The Right Thing without you having +to think about it in this much detail. But when customizing +indentation, it's helpful to understand the general indentation model +being used. + +@vindex c-echo-syntactic-information-p +@vindex echo-syntactic-information-p (c-) +@cindex TAB +As you configure @ccmode{}, you might want to set the variable +@code{c-echo-syntactic-information-p} to non-@code{nil} so that the +syntactic component list and calculated offset will always be echoed in +the minibuffer when you hit @kbd{TAB}. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Minor Modes, Commands, New Indentation Engine, Top +@comment node-name, next, previous,up + +@chapter Minor Modes +@cindex Minor Modes +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@ccmode{} contains two minor-mode-like features that you should +find useful while you enter new C code. The first is called +@dfn{auto-newline} mode, and the second is called @dfn{hungry-delete} +mode. These minor modes can be toggled on and off independently, and +@ccmode{} can be configured so that it starts up with any +combination of these minor modes. By default, both of these minor modes +are turned off. + +The state of the minor modes is always reflected in the minor mode list +on the modeline of the @ccmode{} buffer. When auto-newline mode is +enabled, you will see @samp{C/a} on the mode line @footnote{Remember +that the @samp{C} could be replaced with @samp{C++}, @samp{ObjC}, +@samp{Java} or @samp{IDL}.}. When hungry delete mode is enabled you +would see @samp{C/h} and when both modes are enabled, you'd see +@samp{C/ah}. + +@kindex C-c C-a +@kindex C-c C-d +@kindex C-c C-t +@findex c-toggle-hungry-state +@findex c-toggle-auto-state +@findex c-toggle-auto-hungry-state +@findex toggle-hungry-state (c-) +@findex toggle-auto-state (c-) +@findex toggle-auto-hungry-state (c-) +@ccmode{} provides keybindings which allow you to toggle the minor +modes on the fly while editing code. To toggle just the auto-newline +state, hit @kbd{C-c C-a} (@code{c-toggle-auto-state}). When you do +this, you should see the @samp{a} indicator either appear or disappear +on the modeline. Similarly, to toggle just the hungry-delete state, use +@kbd{C-c C-d} (@code{c-toggle-hungry-state}), and to toggle both states, +use @kbd{C-c C-t} (@code{c-toggle-auto-hungry-state}). + +To set up the auto-newline and hungry-delete states to your preferred +values, you would need to add some lisp to your @file{.emacs} file that +called one of the @code{c-toggle-*-state} functions directly. When +called programmatically, each function takes a numeric value, where +a positive number enables the minor mode, a negative number disables the +mode, and zero toggles the current state of the mode. + +So for example, if you wanted to enable both auto-newline and +hungry-delete for all your C file editing, you could add the following +to your @file{.emacs} file: +@example + +(add-hook 'c-mode-common-hook + '(lambda () (c-toggle-auto-hungry-state 1))) + +@end example + + +@cindex electric characters + +@menu +* Auto-newline insertion:: +* Hungry-deletion of whitespace:: +* Auto-fill mode interaction:: +@end menu + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Auto-newline insertion, Hungry-deletion of whitespace, , Minor Modes +@comment node-name, next, previous,up + +@section Auto-newline insertion +@cindex Auto-newline insertion +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@cindex electric commands +Auto-newline minor mode works by enabling certain @dfn{electric +commands}. Electric commands are typically bound to special characters +such as the left and right braces, colons, semi-colons, etc., which when +typed, perform some magic formatting in addition to inserting the typed +character. As a general rule, electric commands are only electric when +the following conditions apply: + +@itemize @bullet +@item +Auto-newline minor mode is enabled, as evidenced by a @samp{C/a} or +@samp{C/ah} indicator on the modeline. + +@cindex literal +@cindex syntactic whitespace +@item +The character was not typed inside of a literal @footnote{A +@dfn{literal} is defined as any comment, string, or C preprocessor macro +definition. These constructs are also known as @dfn{syntactic +whitespace} since they are usually ignored when scanning C code.}. + +@item +@kindex C-u +No numeric argument was supplied to the command (i.e. it was typed as +normal, with no @kbd{C-u} prefix). + +@end itemize + +@menu +* Hanging Braces:: +* Hanging Colons:: +* Hanging Semi-colons and commas:: +* Other electric commands:: +* Clean-ups:: +@end menu + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Hanging Braces, Hanging Colons, , Auto-newline insertion +@comment node-name, next, previous,up + +@subsection Hanging Braces +@cindex Hanging Braces +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@findex c-electric-brace +@findex electric-brace (c-) +@vindex c-hanging-braces-alist +@vindex hanging-braces-alist (c-) +@vindex c-offsets-alist +@vindex offsets-alist (c-) +When you type either an open or close brace (i.e. @kbd{@{} or @kbd{@}}), +the electric command @code{c-electric-brace} gets run. This command has +two electric formatting behaviors. First, it will perform some +re-indentation of the line the brace was typed on, and second, it will +add various newlines before and/or after the typed brace. +Re-indentation occurs automatically whenever the electric behavior is +enabled. If the brace ends up on a line other than the one it was typed +on, then that line is also re-indented. + +@cindex class-open syntactic symbol +@cindex class-close syntactic symbol +@cindex defun-open syntactic symbol +@cindex defun-close syntactic symbol +@cindex inline-open syntactic symbol +@cindex inline-close syntactic symbol +@cindex brace-list-open syntactic symbol +@cindex brace-list-close syntactic symbol +@cindex brace-list-intro syntactic symbol +@cindex brace-list-entry syntactic symbol +@cindex block-open syntactic symbol +@cindex block-close syntactic symbol +@cindex substatement-open syntactic symbol +@cindex statement-case-open syntactic symbol +@cindex extern-lang-open syntactic symbol +@cindex extern-lang-close syntactic symbol +@cindex namespace-open symbol +@cindex namespace-close symbol + +The insertion of newlines is controlled by the +@code{c-hanging-braces-alist} variable. This variable contains a +mapping between syntactic symbols related to braces, and a list of +places to insert a newline. The syntactic symbols that are useful for +this list are: @code{class-open}, @code{class-close}, @code{defun-open}, +@code{defun-close}, @code{inline-open}, @code{inline-close}, +@code{brace-list-open}, @code{brace-list-close}, +@code{brace-list-intro}, @code{brace-list-entry}, @code{block-open}, +@code{block-close}, @code{substatement-open}, +@code{statement-case-open}, +@code{extern-lang-open}, @code{extern-lang-close}, +@code{namespace-open}, and @code{namespace-close}. +@xref{Syntactic Symbols} for a more +detailed description of these syntactic symbols. + +@cindex Custom Indentation Functions +The value associated with each syntactic symbol in this association list +is called an @var{ACTION} which can be either a function or a list. +@xref{Custom Brace and Colon Hanging} for a more detailed discussion of +using a function as a brace hanging @var{ACTION}. + +When the @var{ACTION} is a list, it can contain any combination of the +symbols @code{before} and @code{after}, directing @ccmode{} where to +put newlines in relationship to the brace being inserted. Thus, if the +list contains only the symbol @code{after}, then the brace is said to +@dfn{hang} on the right side of the line, as in: +@example +@group + +// here, open braces always `hang' +void spam( int i ) @{ + if( i == 7 ) @{ + dosomething(i); + @} +@} + + +@end group +@end example + +When the list contains both @code{after} and @code{before}, the braces +will appear on a line by themselves, as shown by the close braces in the +above example. The list can also be empty, in which case no newlines +are added either before or after the brace. + +For example, the default value of @code{c-hanging-braces-alist} is: +@example +@group + +(defvar c-hanging-braces-alist '((brace-list-open) + (substatement-open after) + (block-close . c-snug-do-while) + (extern-lang-open after))) + +@end group +@end example + +@noindent +which says that @code{brace-list-open} braces should both hang on the +right side, and allow subsequent text to follow on the same line as the +brace. Also, @code{substatement-open} and @code{extern-lang-open} +braces should hang on the right side, but subsequent text should follow +on the next line. Here, in the @code{block-close} entry, you also see +an example of using a function as an @var{ACTION}. + +A word of caution: it is not a good idea to hang top-level construct +introducing braces, such as @code{class-open} or @code{defun-open}. +Emacs makes an assumption that such braces will always appear in column +zero, hanging such braces can introduce performance problems. +@xref{Performance Issues} for more information. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Hanging Colons, Hanging Semi-colons and commas, Hanging Braces, Auto-newline insertion +@comment node-name, next, previous,up + +@subsection Hanging Colons +@cindex Hanging Colons +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@vindex hanging-colons-alist (c-) +@vindex c-hanging-colons-alist +Using a mechanism similar to brace hanging (see @ref{Hanging Braces}), +colons can also be made to hang using the variable +@code{c-hanging-colons-alist}. The syntactic symbols appropriate for +this assocation list are: @code{case-label}, @code{label}, +@code{access-label}, @code{member-init-intro}, and @code{inher-intro}. +Note however that for @code{c-hanging-colons-alist}, @var{ACTION}s as +functions are not supported. See also @ref{Custom Brace and Colon +Hanging} for details. + +@cindex Clean-ups +In C++, double-colons are used as a scope operator but because these +colons always appear right next to each other, newlines before and after +them are controlled by a different mechanism, called @dfn{clean-ups} in +@ccmode{}. @xref{Clean-ups} for details. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Hanging Semi-colons and commas, Other electric commands, Hanging Colons, Auto-newline insertion +@comment node-name, next, previous,up + +@subsection Hanging Semi-colons and commas +@cindex Hanging Semi-colons and commas +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Semicolons and commas are also electric in @ccmode{}, but since +these characters do not correspond directly to syntactic symbols, a +different mechanism is used to determine whether newlines should be +automatically inserted after these characters. @xref{Customizing +Semi-colons and Commas} for details. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Other electric commands, Clean-ups, Hanging Semi-colons and commas, Auto-newline insertion +@comment node-name, next, previous,up + +@subsection Other electric commands +@cindex Other electric commands +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@kindex # +@findex c-electric-pound +@vindex c-electric-pound-behavior +@findex electric-pound (c-) +@vindex electric-pound-behavior (c-) +@vindex c-offsets-alist +@vindex offsets-alist (c-) +A few other keys also provide electric behavior. For example +@kbd{#} (@code{c-electric-pound}) is electric when typed as +the first non-whitespace character on a line. In this case, the +variable @code{c-electric-pound-behavior} is consulted for the electric +behavior. This variable takes a list value, although the only element +currently defined is @code{alignleft}, which tells this command to force +the @samp{#} character into column zero. This is useful for entering +C preprocessor macro definitions. + +@findex c-electric-star +@findex c-electric-slash +@findex electric-star (c-) +@findex electric-slash (c-) +@cindex comment-only line +Stars and slashes (i.e. @kbd{*} and @kbd{/}, @code{c-electric-star} and +@code{c-electric-slash} respectively) are also electric under +certain circumstances. If a star is inserted as the second character of +a C style block comment on a @dfn{comment-only} line, then the comment +delimiter is indented as defined by @code{c-offsets-alist}. A +comment-only line is defined as a line which contains only a comment, as +in: +@example +@group + +void spam( int i ) +@{ + // this is a comment-only line... + if( i == 7 ) // but this is not + @{ + dosomething(i); + @} +@} + +@end group +@end example + +Likewise, if a slash is inserted as the second slash in a C++ style line +comment (also only on a comment-only line), then the line is indented as +defined by @code{c-offsets-alist}. + +@findex c-electric-lt-gt +@findex electric-lt-gt (c-) +@kindex < +@kindex > +Less-than and greater-than signs (@code{c-electric-lt-gt}) are also +electric, but only in C++ mode. Hitting the second of two @kbd{<} or +@kbd{>} keys re-indents the line if it is a C++ style stream operator. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Clean-ups, , Other electric commands, Auto-newline insertion +@comment node-name, next, previous,up + +@subsection Clean-ups +@cindex Clean-ups +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@dfn{Clean-ups} are a mechanism complementary to colon and brace +hanging. On the surface, it would seem that clean-ups overlap the +functionality provided by the @code{c-hanging-*-alist} variables, and +similarly, clean-ups are only enabled when auto-newline minor mode is +enabled. Clean-ups are used however to adjust code ``after-the-fact'', +i.e. to eliminate some whitespace that is inserted by electric +commands, or whitespace that contains intervening constructs. + +@cindex literal +You can configure @ccmode{}'s clean-ups by setting the variable +@code{c-cleanup-list}, which is a list of clean-up symbols. By default, +@ccmode{} cleans up only the @code{scope-operator} construct, which +is necessary for proper C++ support. Note that clean-ups are only +performed when the construct does not occur within a literal (see +@ref{Auto-newline insertion}), and when there is nothing but whitespace +appearing between the individual components of the construct. + +@vindex c-cleanup-list +@vindex cleanup-list (c-) +There are currently only five specific constructs that @ccmode{} +can clean up, as indicated by these symbols: + +@itemize @bullet +@item +@code{brace-else-brace} --- cleans up @samp{@} else @{} constructs by +placing the entire construct on a single line. Clean-up occurs when the +open brace after the @samp{else} is typed. So for example, this: +@example +@group + +void spam(int i) +@{ + if( i==7 ) + @{ + dosomething(); + @} + else + @{ + +@end group +@end example +@noindent +appears like this after the open brace is typed: +@example +@group + +void spam(int i) +@{ + if( i==7 ) @{ + dosomething(); + @} else @{ + +@end group +@end example + +@item +@code{brace-elseif-brace} --- similar to the @code{brace-else-brace} +clean-up, but this cleans up @samp{@} else if (...) @{} constructs. For +example: +@example +@group + +void spam(int i) +@{ + if( i==7 ) + @{ + dosomething(); + @} + else if( i==3 ) @{ + +@end group +@end example +@noindent +appears like this after the open brace is typed: +@example +@group + +void spam(int i) +@{ + if( i==7 ) @{ + dosomething(); + @} else if( i==3 ) @{ + +@end group +@end example + +@item +@code{empty-defun-braces} --- cleans up braces following a top-level +function or class definition that contains no body. Clean up occurs +when the closing brace is typed. Thus the following: +@example +@group + +class Spam +@{ +@} + +@end group +@end example +@noindent +is transformed into this when the close brace is typed: +@example +@group + +class Spam +@{@} + +@end group +@end example + +@item +@code{defun-close-semi} --- cleans up the terminating semi-colon on +top-level function or class definitions when they follow a close +brace. Clean up occurs when the semi-colon is typed. +So for example, the following: +@example +@group + +class Spam +@{ +@} +; + +@end group +@end example +@noindent +is transformed into this when the semi-colon is typed: + +@example +@group + +class Spam +@{ +@}; + +@end group +@end example + +@item +@code{list-close-comma} --- cleans up commas following braces in array +and aggregate initializers. Clean up occurs when the comma is typed. + +@item +@code{scope-operator} --- cleans up double colons which may designate a +C++ scope operator split across multiple lines@footnote{Certain C++ +constructs introduce ambiguous situations, so @code{scope-operator} +clean-ups may not always be correct. This usually only occurs when +scoped identifiers appear in switch label tags.}. Clean up occurs when +the second colon is typed. You will always want @code{scope-operator} +in the @code{c-cleanup-list} when you are editing C++ code. + +@end itemize + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Hungry-deletion of whitespace, Auto-fill mode interaction, Auto-newline insertion, Minor Modes +@comment node-name, next, previous,up + +@section Hungry-deletion of whitespace +@cindex Hungry-deletion of whitespace +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Hungry deletion of whitespace, or as it more commonly called, +@dfn{hungry-delete mode}, is a simple feature that some people find +extremely useful. In fact, you might find yourself wanting +hungry-delete in @strong{all} your editing modes! + +@kindex DEL +@kindex Backspace +In a nutshell, when hungry-delete mode is enabled, hitting the +@key{Backspace} key@footnote{I say ``hit the @key{Backspace} key'' but +what I really mean is ``when Emacs receives the @code{BackSpace} key +event''. The difference usually isn't significant to most users, but +advanced users will realize that under window systems such as X, any +physical key (keycap) on the keyboard can be configured to generate any +keysym, and thus any Emacs key event. Also, the use of Emacs on TTYs +will affect which keycap generates which key event. From a pedantic +point of view, here we are only concerned with the key event that +Emacs receives.} will consume all preceding whitespace, including +newlines and tabs. This can really cut down on the number of +@key{Backspace}'s you have to type if, for example you made a mistake on +the preceding line. + +@findex c-electric-backspace +@findex electric-backspace (c-) +@vindex c-backspace-function +@vindex backspace-function (c-) + +@findex c-electric-delete +@findex electric-delete (c-) +@vindex c-delete-function +@vindex delete-function (c-) +@cindex literal + +@findex backward-delete-char-untabify + +By default, when you hit the @key{Backspace} key +@ccmode{} runs the command @code{c-electric-backspace}, which deletes +text in the backwards direction. When deleting a single character, or +when @key{Backspace} is hit in a literal +(see @ref{Auto-newline insertion}), +or when hungry-delete mode is disabled, the function +contained in the @code{c-backspace-function} variable is called with one +argument (the number of characters to delete). This variable is set to +@code{backward-delete-char-untabify} by default. + +@vindex delete-key-deletes-forward +@findex delete-char + +Similarly, hitting the @key{Delete} key runs the command +@code{c-electric-delete}. When deleting a single character, or when +@key{Delete} is hit in a literal, or when hungry-delete mode is +disabled, the function contained in the @code{c-delete-function} +variable is called with one argument (the number of characters to +delete). This variable is set to @code{delete-char} by default. + +However, if @code{delete-key-deletes-forward} is @code{nil}, or your +Emacs does not support separation of @key{Backspace} and @key{DEL}, then +@code{c-electric-delete} simply calls @code{c-electric-backspace}. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Auto-fill mode interaction, , Hungry-deletion of whitespace, Minor Modes +@comment node-name, next, previous,up + +@section Auto-fill mode interaction +@cindex Auto-fill mode interaction +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +One other note about minor modes is worth mentioning here. CC Mode now +works much better with auto-fill mode (a standard Emacs minor mode) by +correctly auto-filling both line (e.g. C++ style) and block (e.g. C +style) oriented comments. When @code{auto-fill-mode} is enabled, line +oriented comments will also be auto-filled by inserting a newline at the +line break, and inserting @samp{//} at the start of the next line. + +@vindex c-comment-continuation-stars +@vindex comment-continuation-stars (c-) +@vindex comment-line-break-function +When auto-filling block oriented comments, the behavior is dependent on +the value of the variable @code{c-comment-continuation-stars}. When +this variable is @code{nil}, the old behavior for auto-filling C +comments is in effect. In this case, the line is broken by closing the +comment and starting a new comment on the next line. + +If you set @code{c-comment-continuation-stars} to a string, then a long +C block comment line is broken by inserting a newline at the line break +position, and inserting this string at the beginning of the next comment +line. The default value for @code{c-comment-continuation-stars} is +@samp{* } (a star followed by a single space)@footnote{To get block +comment continuation lines indented under the block comment starter +(e.g. the @samp{/*}), it is not enough to set +@code{c-comment-continuation-stars} to the empty string. You need to do +this, but you also need to set the offset for the @code{c} syntactic +symbol to be zero.}. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Commands, Customizing Indentation, Minor Modes, Top +@comment node-name, next, previous,up + +@chapter Commands +@cindex Commands +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@menu +* Indentation Commands:: +* Other Commands:: +@end menu + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Indentation Commands, Other Commands, , Commands +@comment node-name, next, previous,up + +@section Indentation Commands +@cindex Indentation Commands +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Various commands are provided which allow you to conveniently re-indent +C constructs. There are several things to +note about these indentation commands. First, when you +change your programming style, either interactively or through some +other means, your file does @emph{not} automatically get re-indented. +When you change style parameters, you will typically need to reformat +the line, expression, or buffer to see the effects of your changes. + +@cindex c-hanging- functions +@findex c-hanging-braces-alist +@findex hanging-braces-alist (c-) +Second, changing some variables have no effect on existing code, even +when you do re-indent. For example, the @code{c-hanging-*} variables +and @code{c-cleanup-list} only affect new code as it is typed in +on-the-fly, so changing @code{c-hanging-braces-alist} and re-indenting +the buffer will not adjust placement of braces already in the file. + +@vindex c-progress-interval +@vindex progress-interval (c-) +Third, re-indenting large portions of code is currently rather +inefficient. Improvements have been made since previous releases of +@ccmode{}, and much more radical improvements are planned, but for now +you need to be aware of this @footnote{In particular, I have had people +complain about the speed with which @code{lex(1)} output is re-indented. +Lex, yacc, and other code generators usually output some pretty +perversely formatted code. @emph{Don't} try to indent this stuff!}. +Some provision has been made to at least inform you as to the progress +of the re-indentation. The variable @code{c-progress-interval} controls +how often a progress message is displayed. Set this variable to +@code{nil} to inhibit progress messages, including messages normally +printed when indentation is started and completed. + +Also, except as noted below, re-indentation is always driven by the +same mechanisms that control on-the-fly indentation of code. @xref{New +Indentation Engine} for details. + +@findex c-indent-command +@findex indent-command (c-) +@vindex c-tab-always-indent +@vindex tab-always-indent (c-) +@kindex TAB +@cindex literal +@vindex indent-tabs-mode +@vindex c-insert-tab-function +@vindex insert-tab-function (c-) +@findex tab-to-tab-stop +To indent a single line of code, use @kbd{TAB} +(@code{c-indent-command}). The behavior of this command is controlled +by the variable @code{c-tab-always-indent}. When this variable is +@code{t}, @kbd{TAB} always just indents the current line. When +@code{nil}, the line is indented only if point is at the left margin, or +on or before the first non-whitespace character on the line, otherwise +@emph{something else happens}@footnote{Actually what happens is that the +function stored in @code{c-insert-tab-function} is called. +Normally this just inserts a real tab character, or the equivalent +number of spaces, depending on the setting of the variable +@code{indent-tabs-mode}. If you preferred, you could set +@code{c-insert-tab-function} to @code{tab-to-tab-stop} for example.}. +If the value of @code{c-tab-always-indent} is something other than +@code{t} or @code{nil} (e.g. @code{'other}), then a real tab +character@footnote{The caveat about @code{indent-tabs-mode} in the +previous footnote also applies here.} is inserted only when point is +inside a literal (see @ref{Auto-newline insertion}), otherwise the line +is indented. + +@kindex M-C-q +@findex c-indent-exp +@findex indent-exp (c-) +To indent an entire balanced brace or parenthesis expression, use +@kbd{M-C-q} (@code{c-indent-exp}). Note that point should be on +the opening brace or parenthesis of the expression you want to indent. + +@kindex C-c C-q +@findex c-indent-defun +@findex indent-defun (c-) +Another very convenient keystroke is @kbd{C-c C-q} +(@code{c-indent-defun}) when re-indents the entire top-level function or +class definition that encompasses point. It leaves point at the +same position within the buffer. + +@kindex M-C-\ +@findex indent-region +To indent any arbitrary region of code, use @kbd{M-C-\} +(@code{indent-region}). This is a standard Emacs command, specially +tailored for C code in a @ccmode{} buffer. Note that of course, +point and mark must delineate the region you +want to indent. + +@kindex M-C-h +@findex c-mark-function +@findex mark-function (c-) +While not strictly an indentation function, @kbd{M-C-h} +(@code{c-mark-function}) is useful for marking the current top-level +function or class definition as the current region. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Other Commands, , Indentation Commands, Commands +@comment node-name, next, previous,up + +@section Other Commands +@cindex Other Commands +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@ccmode{} contains other useful command for moving around in C +code. + +@table @code +@findex c-beginning-of-defun +@findex beginning-of-defun (c-) +@findex beginning-of-defun +@item M-x c-beginning-of-defun +Moves point back to the least-enclosing brace. This function is +analogous to the Emacs built-in command @code{beginning-of-defun}, +except it eliminates the constraint that the top-level opening brace +must be in column zero. See @code{beginning-of-defun} for more +information. + +Depending on the coding style being used, you might prefer +@code{c-beginning-of-defun} to @code{beginning-of-defun}. If so, +consider binding @kbd{C-M-a} to the former instead. For backwards +compatibility reasons, the default binding remains in effect. + +@findex c-end-of-defun +@findex end-of-defun (c-) +@findex end-of-defun +@item M-x c-end-of-defun +Moves point to the end of the current top-level definition. This +function is analogous to the Emacs built-in command @code{end-of-defun}, +except it eliminates the constraint that the top-level opening brace of +the defun must be in column zero. See @code{beginning-of-defun} for more +information. + +Depending on the coding style being used, you might prefer +@code{c-end-of-defun} to @code{end-of-defun}. If so, +consider binding @kbd{C-M-e} to the former instead. For backwards +compatibility reasons, the default binding remains in effect. + +@kindex C-c C-u +@findex c-up-conditional +@findex up-conditional (c-) +@item C-c C-u (c-up-conditional) +Move point back to the containing preprocessor conditional, leaving the +mark behind. A prefix argument acts as a repeat count. With a negative +argument, move point forward to the end of the containing +preprocessor conditional. When going backwards, @code{#elif} is treated +like @code{#else} followed by @code{#if}. When going forwards, +@code{#elif} is ignored.@refill + +@kindex C-c C-p +@findex c-backward-conditional +@findex backward-conditional (c-) +@item C-c C-p (c-backward-conditional) +Move point back over a preprocessor conditional, leaving the mark +behind. A prefix argument acts as a repeat count. With a negative +argument, move forward. + +@kindex C-c C-n +@findex c-forward-conditional +@findex forward-conditional (c-) +@item C-c C-n (c-forward-conditional) +Move point forward across a preprocessor conditional, leaving the mark +behind. A prefix argument acts as a repeat count. With a negative +argument, move backward. + +@kindex ESC a +@findex c-beginning-of-statement +@findex beginning-of-statement (c-) +@item M-a (c-beginning-of-statement) +Move point to the beginning of the innermost C statement. If point is +already at the beginning of a statement, it moves to the beginning of +the closest preceding statement, even if that means moving into a block +(you can use @kbd{M-C-b} to move over a balanced block). With prefix +argument @var{n}, move back @var{n} @minus{} 1 statements. + +If point is within a comment, or next to a comment, this command moves +by sentences instead of statements. + +When called from a program, this function takes three optional +arguments: the numeric prefix argument, a buffer position limit (used as +a starting point for syntactic parsing and as a limit for backward +movement), and a flag to indicate whether movement should be by +statements (if @code{nil}) or sentence (if non-@code{nil}). + +@kindex ESC e +@findex c-end-of-statement +@findex end-of-statement (c-) +@item M-e (c-end-of-statement) +Move point to the end of the innermost C statement. If point is at the +end of a statement, move to the end of the next statement, even if it's +inside a nested block (use @kbd{M-C-f} to move to the other side of the +block). With prefix argument @var{n}, move forward @var{n} @minus{} 1 +statements. + +If point is within a comment, or next to a comment, this command moves +by sentences instead of statements. + +When called from a program, this function takes three optional +arguments: the numeric prefix argument, a buffer position limit (used as +a starting point for syntactic parsing and as a limit for backward +movement), and a flag to indicate whether movement should be by +statements (if @code{nil}) or sentence (if non-@code{nil}). + +@findex c-forward-into-nomenclature +@findex forward-into-nomenclature (c-) +@item M-x c-forward-into-nomenclature +A popular programming style, especially for object-oriented languages +such as C++ is to write symbols in a mixed case format, where the first +letter of each word is capitalized, and not separated by underscores. +E.g. @samp{SymbolsWithMixedCaseAndNoUnderlines}. + +This command moves point forward to next capitalized word. With prefix +argument @var{n}, move @var{n} times. + +@findex c-backward-into-nomenclature +@findex backward-into-nomenclature (c-) +@item M-x c-backward-into-nomenclature +Move point backward to beginning of the next capitalized +word. With prefix argument @var{n}, move @var{n} times. If +@var{n} is negative, move forward. + +@kindex C-c : +@findex c-scope-operator +@findex scope-operator (c-) +@item C-c : (c-scope-operator) +In C++, it is also sometimes desirable to insert the double-colon scope +operator without performing the electric behavior of colon insertion. +@kbd{C-c :} does just this. + +@kindex ESC q +@findex fill-paragraph +@vindex c-hanging-comment-starter-p +@vindex c-hanging-comment-ender-p +@vindex hanging-comment-starter-p (c-) +@vindex hanging-comment-ender-p (c-) +@item M-q (fill-paragraph) +The command is used to fill a block style (C) or line style (C++) +comment, in much the same way that text in the various text modes can be +filled@footnote{You should not use specialized filling packages such as +@code{filladapt} with CC Mode. They don't work as well for filling as +@code{c-fill-paragraph}}. You should never attempt to fill non-comment +code sections; you'll end up with garbage! Two variables control how C +style block comments are filled, specifically how the comment start and +end delimiters are handled. + +The variable @code{c-hanging-comment-starter-p} controls whether comment +start delimiters which appear on a line by themselves, end up on a line +by themselves after the fill. When the value is @code{nil}, the comment +starter will remain on its own line@footnote{It will not be placed on a +separate line if it is not already on a separate line.}. Otherwise, +text on the next line will be put on the same line as the comment +starter. This is called @dfn{hanging} because the following text hangs +on the line with the comment starter@footnote{This variable is @code{t} +by default, except in @code{java-mode}. Hanging comment starters mess +up Javadoc style comments.} + +The variable @code{c-hanging-comment-ender-p} controls the analogous +behavior for the block comment end delimiter. When the value is +@code{nil}, the comment ender will remain on its own line after the +file@footnote{The same caveat as above holds true.}. Otherwise, the +comment end delimiter will be placed at the end of the previous line. + +@end table + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Customizing Indentation, Syntactic Symbols, Commands, Top +@comment node-name, next, previous,up + +@chapter Customizing Indentation +@cindex Customizing Indentation +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@vindex c-offsets-alist +@vindex offsets-alist (c-) +@cindex c-set-offset +@cindex set-offset (c-) +The variable @code{c-offsets-alist} contains the mappings between +syntactic symbols and the offsets to apply for those symbols. You +should never modify this variable directly though. Use the function +@code{c-set-offset} instead (see below for details). + +The @code{c-offsets-alist} variable is where you customize all your +indentations. You simply need to decide what additional offset you want +to add for every syntactic symbol. You can use the command @kbd{C-c +C-o} (@code{c-set-offset}) as the way to set offsets, both interactively +and from your mode hook. Also, you can set up @emph{styles} of +indentatio. Most likely, you'll +find one of the pre-defined styles will suit your needs, but if not, +this section will describe how to set up basic editing configurations. +@xref{Styles} for an explanation of how to set up named styles. + +@cindex c-basic-offset +@cindex basic-offset (c-) +As mentioned previously, the variable @code{c-offsets-alist} is an +association list of syntactic symbols and the offsets to be applied for +those symbols. In fact, these offset values can be any of an integer, a +function or lambda expression, a variable name, or one of the following +symbols: @code{+}, @code{-}, @code{++}, @code{--}, @code{*}, or +@code{/}. These symbols describe offset in multiples of the value of +the variable @code{c-basic-offset}. By defining a style's indentation +in terms of this fundamental variable, you can change the amount of +whitespace given to an indentation level while leaving the same +relationship between levels. Here are the values that the special +symbols correspond to: + +@table @code + +@item + +@code{c-basic-offset} times 1 +@item - +@code{c-basic-offset} times -1 +@item ++ +@code{c-basic-offset} times 2 +@item -- +@code{c-basic-offset} times -2 +@item * +@code{c-basic-offset} times 0.5 +@item / +@code{c-basic-offset} times -0.5 + +@end table + +@vindex c-style-variables-are-local-p +@vindex style-variables-are-local-p (c-) +@noindent +So, for example, because most of the default offsets are defined in +terms of @code{+}, @code{-}, and @code{0}, if you like the general +indentation style, but you use 4 spaces instead of 2 spaces per level, +you can probably achieve your style just by changing +@code{c-basic-offset} like so (in your @file{.emacs} file): +@example + +(setq c-basic-offset 4) + +@end example + +@noindent +This would change +@example +@group + +int add( int val, int incr, int doit ) +@{ + if( doit ) + @{ + return( val + incr ); + @} + return( val ); +@} + +@end group +@end example +@noindent +to +@example +@group + +int add( int val, int incr, int doit ) +@{ + if( doit ) + @{ + return( val + incr ); + @} + return( val ); +@} + +@end group +@end example + + +To change indentation styles more radically, you will want to change the +value associated with the syntactic symbols in the +@code{c-offsets-alist} variable. First, I'll show you how to do that +interactively, then I'll describe how to make changes to your +@file{.emacs} file so that your changes are more permanent. + +@menu +* Interactive Customization:: +* Permanent Customization:: +* Styles:: +* Advanced Customizations:: +@end menu + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Interactive Customization, Permanent Customization, , Customizing Indentation +@comment node-name, next, previous,up + +@section Interactive Customization +@cindex Interactive Customization +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +As an example of how to customize indentation, let's change the +style of this example@footnote{In this an subsequent examples, the +original code is formatted using the @samp{gnu} style unless otherwise +indicated. @xref{Styles}.}: +@example +@group + +1: int add( int val, int incr, int doit ) +2: @{ +3: if( doit ) +4: @{ +5: return( val + incr ); +6: @} +7: return( val ); +8: @} + +@end group +@end example +@noindent +to: +@example +@group + +1: int add( int val, int incr, int doit ) +2: @{ +3: if( doit ) +4: @{ +5: return( val + incr ); +6: @} +7: return( val ); +8: @} + +@end group +@end example + +In other words, we want to change the indentation of braces that open a +block following a condition so that the braces line up under the +conditional, instead of being indented. Notice that the construct we +want to change starts on line 4. To change the indentation of a line, +we need to see which syntactic components affect the offset calculations +for that line. Hitting @kbd{C-c C-s} on line 4 yields: +@example + +((substatement-open . 44)) + +@end example + +@findex c-set-offset +@findex set-offset (c-) +@kindex C-c C-o +@noindent +so we know that to change the offset of the open brace, we need to +change the indentation for the @code{substatement-open} syntactic +symbol. To do this interactively, just hit @kbd{C-c C-o} +(@code{c-set-offset}). This prompts you for the syntactic symbol to +change, providing a reasonable default. In this case, the default is +@code{substatement-open}, which is just the syntactic symbol we want to +change! + +After you hit return, @ccmode{} will then prompt you for the new +offset value, with the old value as the default. The default in this +case is @samp{+}, but we want no extra indentation so enter +@samp{0} and @kbd{RET}. This will associate the offset 0 with the +syntactic symbol @code{substatement-open} in the @code{c-offsets-alist} +variable. + +@findex c-indent-defun +@findex indent-defun (c-) +@kindex C-c C-q +To check your changes quickly, just hit @kbd{C-c C-q} +(@code{c-indent-defun}) to reindent the entire function. The example +should now look like: +@example +@group + +1: int add( int val, int incr, int doit ) +2: @{ +3: if( doit ) +4: @{ +5: return( val + incr ); +6: @} +7: return( val ); +8: @} + +@end group +@end example + +Notice how just changing the open brace offset on line 4 is all we +needed to do. Since the other affected lines are indented relative to +line 4, they are automatically indented the way you'd expect. For more +complicated examples, this may not always work. The general approach to +take is to always start adjusting offsets for lines higher up in the +file, then re-indent and see if any following lines need further +adjustments. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Permanent Customization, Styles, Interactive Customization, Customizing Indentation +@comment node-name, next, previous,up + +@section Permanent Customization +@cindex Permanent Customization +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@vindex c-mode-common-hook +@vindex c-mode-hook +@vindex c++-mode-hook +@vindex objc-mode-hook +@vindex java-mode-hook +@vindex idl-mode-hook +@vindex c-initialization-hook +@vindex initialization-hook (c-) +@cindex hooks +To make your changes permanent, you need to add some lisp code to your +@file{.emacs} file, but first you need to decide whether your styles +should be global in every buffer, or local to each specific buffer. + +If you edit primarily one style of code, you may want to make the +@ccmode{} style variables have global values so that every buffer will +share the style settings. This will allow you to set the @ccmode{} +variables at the top level of your @file{.emacs} file, and is the +way @ccmode{} works by default. + +@vindex c-mode-common-hook +@vindex mode-common-hook (c-) +@vindex c-style-variables-are-local-p +@vindex style-variables-are-local-p (c-) +If you edit many different styles of code at +the same time, you might want to make the @ccmode{} style variables +have buffer local values. If you do this, then you will need to set any +@ccmode{} style variables in a hook function (e.g. off of +@code{c-mode-common-hook} instead of at the top level of your +@file{.emacs} file). The recommended way to do this is to set the +variable @code{c-style-variables-are-local-p} to @code{t} +@strong{before} @ccmode{} is loaded into your Emacs session. + +@ccmode{} provides several hooks that you can +use to customize the mode according to your coding style. Each language +mode has its own hook, adhering to standard Emacs major mode +conventions. There is also one general hook and one package +initialization hook: + +@itemize @bullet + +@item +@code{c-mode-hook} --- for C buffers only +@item +@code{c++-mode-hook} --- for C++ buffers only +@item +@code{objc-mode-hook} --- for Objective-C buffers only +@item +@code{java-mode-hook} --- for Java buffers only +@item +@code{idl-mode-hook} --- for IDL buffers only +@item +@code{c-mode-common-hook} --- common across all languages +@item +@code{c-initialization-hook} --- hook run only once per Emacs session, +when @ccmode{} is initialized. + +@end itemize + +The language hooks get run as the last thing when you enter that +language mode. The @code{c-mode-common-hook} is run by all +supported modes @emph{before} the language specific hook, and thus can +contain customizations that are common across all languages. Most of +the examples in this section will assume you are using the common +hook@footnote{The interaction between @code{java-mode} and the hook +variables is slightly different than for the other modes. +@code{java-mode} sets the style (see @ref{Styles}) of the buffer to +@samp{java} @emph{before} running the @code{c-mode-common-hook} or +@code{java-mode-hook}. You need to be aware of this so that style +settings in @code{c-mode-common-hook} don't clobber your Java style.}. + +Here's a simplified example of what you can add to your @file{.emacs} +file to make the changes described in the previous section +(@ref{Interactive Customization}) more permanent. See the Emacs manuals +for more information on customizing Emacs via hooks. @xref{Sample +.emacs File} for a more complete sample @file{.emacs} file. +@example +@group + +(defun my-c-mode-common-hook () + ;; my customizations for all of c-mode and related modes + (c-set-offset 'substatement-open 0) + ;; other customizations can go here + ) +(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) + +@end group +@end example + +For complex customizations, you will probably want to set up a +@emph{style} that groups all your customizations under a single +name. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Styles, Advanced Customizations, Permanent Customization, Customizing Indentation +@comment node-name, next, previous,up + +@section Styles +@cindex Styles +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +Most people only need to edit code formatted in just a few well-defined +and consistent styles. For example, their organization might impose a +``blessed'' style that all its programmers must conform to. Similarly, +people who work on GNU software will have to use the GNU coding style on +C code. Some shops are more lenient, allowing a variety of coding +styles, and as programmers come and go, there could be a number of +styles in use. For this reason, @ccmode{} makes it convenient for +you to set up logical groupings of customizations called @dfn{styles}, +associate a single name for any particular style, and pretty easily +start editing new or existing code using these styles. + +@menu +* Built-in Styles:: +* Adding Styles:: +* File Styles:: +@end menu + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Built-in Styles, Adding Styles, , Styles +@comment node-name, next, previous,up + +@subsection Built-in Styles +@cindex Built-in Styles +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +If you're lucky, one of @ccmode{}'s built-in styles might be just +what you're looking for. These include: + +@itemize @bullet +@cindex GNU style +@item +@code{gnu} --- coding style blessed by the Free Software Foundation +for C code in GNU programs. This is the default style for all newly +created buffers, but you can change this by setting the variable +@code{c-default-style}. + +@cindex K&R style +@item +@code{k&r} --- The classic Kernighan and Ritchie style for C code. + +@cindex BSD style +@item +@code{bsd} --- Also known as ``Allman style'' after Eric Allman. + +@cindex Whitesmith style +@item +@code{whitesmith} --- Popularized by the examples that came with +Whitesmiths C, an early commercial C compiler. + +@cindex Stroustrup style +@item +@code{stroustrup} --- The classic Stroustrup style for C++ code. + +@cindex Ellemtel style +@item +@code{ellemtel} --- Popular C++ coding standards as defined by +``Programming in C++, Rules and Recommendations'', Erik Nyquist and Mats +Henricson, Ellemtel @footnote{This document is ftp'able from +@code{euagate.eua.ericsson.se}}. + +@cindex Linux style +@item +@code{linux} --- C coding standard for Linux development. + +@cindex Python style +@item +@code{python} --- C coding standard for Python extension +modules@footnote{Python is a high level scripting language with a C/C++ +foreign function interface. For more information, see +@code{<http://www.python.org/>}.}. + +@cindex Java style +@cindex java-mode +@item +@code{java} --- The style for editing Java code. Note that this style is +automatically installed when you enter @code{java-mode}. + +@cindex User style +@cindex .emacs file +@vindex c-default-style +@vindex default-style (c-) +@item +@code{user} --- This is a special style for several reasons. First, if +you customize @ccmode{} by using either the new Custom interface or by +doing @code{setq}'s at the top level of your @file{.emacs} file, these +settings will be captured in the @code{user} style. Also, all other +styles implicitly inherit their settings from @code{user} style. This +means that for any styles you add via @code{c-add-style} (@xref{Adding +Styles}) you need only define the differences between your new style and +@code{user} style. + +Note however that @code{user} style is @emph{not} the default style. +@code{gnu} is the default style for all newly created buffers, but you +can change this by setting variable @code{c-default-style}. Be careful +if you customize @ccmode{} as described above; since your changes will +be captured in the @code{user} style, you will also have to change +@code{c-default-style} to "user" to see the effect of your +customizations. + +@end itemize + +@findex c-set-style +@findex set-style (c-) +@kindex C-c . +If you'd like to experiment with these built-in styles you can simply +type the following in a @ccmode{} buffer: +@example +@group + +@kbd{C-c . @var{STYLE-NAME} RET} + +@end group +@end example +@noindent +@kbd{C-c .} runs the command @code{c-set-style}. Note that all style +names are case insensitive, even the ones you define. + +Setting a style in this way does @emph{not} automatically re-indent your +file. For commands that you can use to view the effect of your changes, +see @ref{Commands}. + +Once you find a built-in style you like, you can make the change +permanent by adding some lisp to your @file{.emacs} file. Let's say for +example that you want to use the @samp{ellemtel} style in all your +files. You would add this: +@example +@group + +(defun my-c-mode-common-hook () + ;; use Ellemtel style for all C like languages + (c-set-style "ellemtel") + ;; other customizations can go here + ) +(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) + +@end group +@end example + +@vindex c-indentation-style +@vindex indentation-style (c-) +Note that for BOCM compatibility, @samp{gnu} is the default +style, and any non-style based customizations you make (i.e. in +@code{c-mode-common-hook} in your +@file{.emacs} file) will be based on @samp{gnu} style unless you do +a @code{c-set-style} as the first thing in your hook. The variable +@code{c-indentation-style} always contains the buffer's current style name, +as a string. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Adding Styles, File Styles, Built-in Styles, Styles +@comment node-name, next, previous,up + +@subsection Adding Styles +@cindex Adding Styles +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@vindex c-style-alist +@vindex style-alist (c-) +@findex c-add-style +@findex add-style (c-) +If none of the built-in styles is appropriate, you'll probably want to +add a new @dfn{style definition}. Styles are kept in the +@code{c-style-alist} variable, but you should never modify this variable +directly. Instead, @ccmode{} provides the function +@code{c-add-style} that you can use to easily add new styles or change +existing styles. This function takes two arguments, a @var{stylename} +string, and an association list @var{description} of style +customizations. If @var{stylename} is not already in +@code{c-style-alist}, the new style is added, otherwise the style is +changed to the new @var{description}. +This function also takes an optional third argument, which if +non-@code{nil}, automatically applies the new style to the current +buffer. + +@comment TBD: The next paragraph is bogus. I really need to better +@comment document adding styles, including setting up inherited styles. + +The sample @file{.emacs} file provides a concrete example of how a new +style can be added and automatically set. @xref{Sample .emacs File}. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node File Styles, , Adding Styles, Styles +@comment node-name, next, previous,up + +@subsection File Styles +@cindex File Styles +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@cindex local variables + +The Emacs manual describes how you can customize certain variables on a +per-file basis by including a @dfn{Local Variable} block at the end of +the file. So far, you've only seen a functional interface to @ccmode{} +customization, which is highly inconvenient for use in a Local Variable +block. @ccmode{} provides two variables that make it easier for you to +customize your style on a per-file basis. +It works via the standard Emacs hook variable +@code{hack-local-variables-hook}. + +@vindex c-file-style +@vindex file-style (c-) +@vindex c-file-offsets +@vindex file-offsets (c-) + +The variable @code{c-file-style} can be set to a style name string. +When the file is visited, @ccmode{} will automatically set the +file's style to this style using @code{c-set-style}. + +@vindex c-offsets-alist +@vindex offsets-alist (c-) +@findex c-set-offset +@findex set-offset (c-) +Another variable, @code{c-file-offsets}, takes an association list +similar to what is allowed in @code{c-offsets-alist}. When the file is +visited, @ccmode{} will automatically institute these offets using +@code{c-set-offset}. + +Note that file style settings (i.e. @code{c-file-style}) are applied +before file offset settings (i.e. @code{c-file-offsets}). Also, if +either of these are set in a file's local variable section, all the +style variable values are made local to that buffer. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Advanced Customizations, , Styles, Customizing Indentation +@comment node-name, next, previous,up + +@section Advanced Customizations +@cindex Advanced Customizations +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@vindex c-style-alist +@vindex style-alist (c-) +@vindex c-basic-offset +@vindex basic-offset (c-) +For most users, @ccmode{} will support their coding styles with +very little need for more advanced customizations. Usually, one of the +standard styles defined in @code{c-style-alist} will do the trick. At +most, perhaps one of the syntactic symbol offsets will need to be +tweaked slightly, or maybe @code{c-basic-offset} will need to be +changed. However, some styles require a more flexible framework for +customization, and one of the real strengths of @ccmode{} is that +the syntactic analysis model provides just such a framework. This allows +you to implement custom indentation calculations for situations not +handled by the mode directly. + +@vindex c-style-variables-are-local-p +@vindex style-variables-are-local-p +Note that the style controlling variables can either have global values, +or can be buffer local (e.g. different in every buffer). If all the C +files you edit tend to have the same style, you might want to keep the +variables global. If you tend to edit files with many different styles, +you will have to make the variables buffer local. The variable +@code{c-style-variables-are-local-p} controls this. + +When @code{c-style-variables-are-local-p} is non-nil, then the style +variables will have a different settable value for each buffer, +otherwise all buffers will share the same values. By default, its value +is @code{nil} (i.e. global values). You @strong{must} set this variable +before @ccmode{} is loaded into your Emacs session, and once the +variables are made buffer local, they cannot be made global again +(unless you restart Emacs of course!) + +@menu +* Custom Indentation Functions:: +* Custom Brace and Colon Hanging:: +* Customizing Semi-colons and Commas:: +* Other Special Indentations:: +@end menu + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Custom Indentation Functions, Custom Brace and Colon Hanging, , Advanced Customizations +@comment node-name, next, previous,up + +@subsection Custom Indentation Functions +@cindex Custom Indentation Functions +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@cindex Custom Indentation Functions +The most flexible way to customize @ccmode{} is by writing @dfn{custom +indentation functions} and associating them with specific syntactic +symbols (see @ref{Syntactic Symbols}). @ccmode{} itself uses custom +indentation functions to provide more sophisticated indentation, for +example when lining up C++ stream operator blocks: +@example +@group + +1: void main(int argc, char**) +2: @{ +3: cout << "There were " +4: << argc +5: << "arguments passed to the program" +6: << endl; +7: @} + +@end group +@end example + +In this example, lines 4 through 6 are assigned the @code{stream-op} +syntactic symbol. Here, @code{stream-op} has an offset of @code{+}, and +with a @code{c-basic-offset} of 2, you can see that lines 4 through 6 +are simply indented two spaces to the right of line 3. But perhaps we'd +like @ccmode{} to be a little more intelligent so that it aligns +all the @samp{<<} symbols in lines 3 through 6. To do this, we have +to write a custom indentation function which finds the column of first +stream operator on the first line of the statement. Here is sample +lisp code implementing this: +@example +@group + +(defun c-lineup-streamop (langelem) + ;; lineup stream operators + (save-excursion + (let* ((relpos (cdr langelem)) + (curcol (progn (goto-char relpos) + (current-column)))) + (re-search-forward "<<\\|>>" (c-point 'eol) 'move) + (goto-char (match-beginning 0)) + (- (current-column) curcol)))) + +@end group +@end example +@noindent +Custom indent functions take a single argument, which is a syntactic +component cons cell (see @ref{Syntactic Analysis}). The +function returns an integer offset value that will be added to the +running total indentation for the line. Note that what actually gets +returned is the difference between the column that the first stream +operator is on, and the column of the buffer relative position passed in +the function's argument. Remember that @ccmode{} automatically +adds in the column of the component's relative buffer position and we +don't the column offset added in twice. + +@cindex stream-op syntactic symbol +@findex c-lineup-streamop +@findex lineup-streamop (c-) +Now, to associate the function @code{c-lineup-streamop} with the +@code{stream-op} syntactic symbol, we can add something like the +following to our @code{c++-mode-hook}@footnote{It probably makes more +sense to add this to @code{c++-mode-hook} than @code{c-mode-common-hook} +since stream operators are only relevent for C++.}: +@example + +(c-set-offset 'stream-op 'c-lineup-streamop) + +@end example + +@kindex C-c C-q +Now the function looks like this after re-indenting (using @kbd{C-c +C-q}): +@example +@group + +1: void main(int argc, char**) +2: @{ +3: cout << "There were " +4: << argc +5: << "arguments passed to the program" +6: << endl; +7: @} + +@end group +@end example + +@vindex c-offsets-alist +@vindex offsets-alist (c-) +Custom indentation functions can be as simple or as complex as you like, +and any syntactic symbol that appears in @code{c-offsets-alist} can have +a custom indentation function associated with it. @ccmode{} comes +with several standard custom indentation functions, not all of which are +used by the default styles. + +@itemize @bullet +@findex c-lineup-arglist +@findex lineup-arglist (c-) +@item +@code{c-lineup-arglist} --- lines up function argument lines under the +argument on the previous line. + +@findex c-lineup-arglist-intro-after-paren +@findex lineup-arglist-intro-after-paren (c-) +@item +@code{c-lineup-arglist-intro-after-paren} --- similar to +@code{c-lineup-arglist}, but works for argument lists that begin with an +open parenthesis followed by a newline. + +@findex c-lineup-arglist-close-under-paren +@findex lineup-arglist-close-under-paren (c-) +@item +@code{c-lineup-arglist-close-under-paren} --- set your +@code{arglist-close} syntactic symbol to this line-up function so that +parentheses that close argument lists will line up under the parenthesis +that opened the argument list. + +@findex c-lineup-close-paren +@findex lineup-close-paren (c-) +@item +@code{c-lineup-close-paren} --- lines up the closing parenthesis under +its corresponding open parenthesis if that one is followed by code. +Otherwise, if the open parenthesis ends its line, no indentation is +added. Works with any @code{@dots{}-close} symbol. + +@findex c-lineup-streamop +@findex lineup-streamop (c-) +@item +@code{c-lineup-streamop} --- lines up C++ stream operators +(e.g. @samp{<<} and @samp{>>}). + +@findex c-lineup-multi-inher +@findex lineup-multi-inher (c-) +@item +@code{c-lineup-multi-inher} --- lines up multiple inheritance lines. + +@findex c-indent-one-line-block +@findex indent-one-line-block (c-) +@item +@code{c-indent-one-line-block} --- adds @code{c-basic-offset} to the +indentation if the line is a one line block, otherwise 0. Intended to +be used with any opening brace symbol, e.g. @code{substatement-open}. + +@findex c-lineup-C-comments +@findex lineup-C-comments (c-) +@item +@code{c-lineup-C-comments} --- lines up C block comment continuation +lines. + +@findex c-lineup-comment +@findex lineup-comment (c-) +@vindex c-comment-only-line-offset +@vindex comment-only-line-offset (c-) +@item +@code{c-lineup-comment} --- lines up comment only lines according to +the variable @code{c-comment-only-line-offset}. + +@findex c-lineup-runin-statements +@findex lineup-runin-statements (c-) +@item +@code{c-lineup-runin-statements} --- lines up @code{statement}s for coding +standards which place the first statement in a block on the same line as +the block opening brace@footnote{Run-in style doesn't really work too +well. You might need to write your own custom indentation functions to +better support this style.}. + +@findex c-lineup-math +@findex lineup-math (c-) +@item +@code{c-lineup-math} --- lines up math @code{statement-cont} lines under +the previous line after the equals sign. + +@findex c-lineup-ObjC-method-call +@findex lineup-ObjC-method-call (c-) +@item +@code{c-lineup-ObjC-method-call} --- for Objective-C code, lines up +selector arguments just after the message receiver. + +@findex c-lineup-ObjC-method-args +@findex lineup-ObjC-method-args (c-) +@item +@code{c-lineup-ObjC-method-args} --- for Objective-C code, lines up the +colons that separate arguments by aligning colons vertically. + +@findex c-lineup-ObjC-method-args-2 +@findex lineup-ObjC-method-args-2 (c-) +@item +@code{c-lineup-ObjC-method-args-2} --- similar to +@code{c-lineup-ObjC-method-args} but lines up the colon on the current +line with the colon on the previous line. + +@findex c-lineup-dont-change +@findex lineup-dont-change (c-) +@item +@code{c-lineup-dont-change} --- this lineup function returns the +indentation of the current line. Think of it as an identity function +for lineups; it is used for @code{cpp-macro-cont} lines. + +@end itemize + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Custom Brace and Colon Hanging, Customizing Semi-colons and Commas, Custom Indentation Functions, Advanced Customizations +@comment node-name, next, previous,up + +@subsection Custom Brace and Colon Hanging +@cindex Custom Brace and Colon Hanging +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@vindex c-hanging-braces-alist +@vindex hanging-braces-alist (c-) +Syntactic symbols aren't the only place where you can customize +@ccmode{} with the lisp equivalent of callback functions. Brace +``hanginess'' can also be determined by custom functions associated with +syntactic symbols on the @code{c-hanging-braces-alist} variable. +Remember that @var{ACTION}'s are typically a list containing some +combination of the symbols @code{before} and @code{after} (see +@ref{Hanging Braces}). However, an @var{ACTION} can also be a function +which gets called when a brace matching that syntactic symbol is +entered. + +@cindex customizing brace hanging +These @var{ACTION} functions are called with two arguments: the +syntactic symbol for the brace, and the buffer position at which the +brace was inserted. The @var{ACTION} function is expected to return a +list containing some combination of @code{before} and @code{after}. The +function can also return @code{nil}. This return value has the normal +brace hanging semantics. + +As an example, @ccmode{} itself uses this feature to dynamically +determine the hanginess of braces which close ``do-while'' +constructs: +@example +@group + +void do_list( int count, char** atleast_one_string ) +@{ + int i=0; + do @{ + handle_string( atleast_one_string[i] ); + i++; + @} while( i < count ); +@} + +@end group +@end example + +@findex c-snug-do-while +@findex snug-do-while (c-) +@ccmode{} assigns the @code{block-close} syntactic symbol to the +brace that closes the @code{do} construct, and normally we'd like the +line that follows a @code{block-close} brace to begin on a separate +line. However, with ``do-while'' constructs, we want the +@code{while} clause to follow the closing brace. To do this, we +associate the @code{block-close} symbol with the @var{ACTION} function +@code{c-snug-do-while}: +@example + +(defun c-snug-do-while (syntax pos) + "Dynamically calculate brace hanginess for do-while statements. +Using this function, `while' clauses that end a `do-while' block will +remain on the same line as the brace that closes that block. + +See `c-hanging-braces-alist' for how to utilize this function as an +ACTION associated with `block-close' syntax." + (save-excursion + (let (langelem) + (if (and (eq syntax 'block-close) + (setq langelem (assq 'block-close c-syntactic-context)) + (progn (goto-char (cdr langelem)) + (if (= (following-char) ?@{) + (forward-sexp -1)) + (looking-at "\\<do\\>[^_]"))) + '(before) + '(before after))))) + +@end example + +This function simply looks to see if the brace closes a ``do-while'' +clause and if so, returns the list @samp{(before)} indicating +that a newline should be inserted before the brace, but not after it. +In all other cases, it returns the list @samp{(before after)} so +that the brace appears on a line by itself. + +@vindex c-syntactic-context +@vindex syntactic-context (c-) +During the call to the brace hanging @var{ACTION} function, the variable +@code{c-syntactic-context} is bound to the full syntactic analysis list. + +@cindex customizing colon hanging +@vindex c-hanging-colon-alist +@vindex hanging-colon-alist (c-) +Note that for symmetry, colon hanginess should be customizable by +allowing function symbols as @var{ACTION}s on the +@code{c-hanging-colon-alist} variable. Since no use has actually been +found for this feature, it isn't currently implemented! + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Customizing Semi-colons and Commas, Other Special Indentations, Custom Brace and Colon Hanging, Advanced Customizations +@comment node-name, next, previous,up + +@subsection Customizing Semi-colons and Commas +@cindex Customizing Semi-colons and Commas +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@cindex Customizing Semi-colons and Commas +@vindex c-hanging-semi&comma-criteria +@vindex hanging-semi&comma-criteria (c-) +You can also customize the insertion of newlines after semi-colons and +commas, when the auto-newline minor mode is enabled (see @ref{Minor +Modes}). This is controlled by the variable +@code{c-hanging-semi&comma-criteria}, which contains a list of functions +that are called in the order they appear. Each function is called with +zero arguments, and is expected to return one of the following values: + +@itemize @bullet +@item +non-@code{nil} --- A newline is inserted, and no more functions from the +list are called. + +@item +@code{stop} --- No more functions from the list are called, but no +newline is inserted. + +@item +@code{nil} --- No determination is made, and the next function in the +list is called. + +@end itemize + +If every function in the list is called without a determination being +made, then no newline is added. The default value for this variable is a +list containing a single function which inserts newlines only after +semi-colons which do not appear inside parenthesis lists (i.e. those +that separate @code{for}-clause statements). + +@findex c-semi&comma-no-newlines-before-nonblanks +@findex semi&comma-no-newlines-before-nonblanks (c-) +Here's an example of a criteria function, provided by @ccmode{}, that +will prevent newlines from being inserted after semicolons when there is +a non-blank following line. Otherwise, it makes no determination. To +use, add this to the front of the @code{c-hanging-semi&comma-criteria} +list. + +@example +@group + +(defun c-semi&comma-no-newlines-before-nonblanks () + (save-excursion + (if (and (eq last-command-char ?\;) + (zerop (forward-line 1)) + (not (looking-at "^[ \t]*$"))) + 'stop + nil))) + +@end group +@end example + +@findex c-semi&comma-inside-parenlist +@findex c-semi&comma-no-newlines-for-oneline-inliners +@findex semi&comma-inside-parenlist (c-) +@findex semi&comma-no-newlines-for-oneline-inliners (c-) +The default value of @code{c-hanging-semi&comma-criteria} is a list +containing just the function @code{c-semi&comma-inside-parenlist}, which +suppresses newlines after semicolons inside parenthesis lists +(e.g. @code{for}-loops). In addition to +@code{c-semi&comma-no-newlines-before-nonblanks} described above, +@ccmode{} also comes with the criteria function +@code{c-semi&comma-no-newlines-for-oneline-inliners}, which suppresses +newlines after semicolons inside one-line inline method definitions +(i.e. in C++ or Java). + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Other Special Indentations, , Customizing Semi-colons and Commas, Advanced Customizations +@comment node-name, next, previous,up + +@subsection Other Special Indentations +@cindex Customizing Semi-colons and Commas +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@vindex c-label-minimum-indentation +@vindex label-minimum-indentation (c-) +In @samp{gnu} style (see @ref{Built-in Styles}), a minimum indentation +is imposed on lines inside top-level constructs. This minimum +indentation is controlled by the variable +@code{c-label-minimum-indentation}. The default value for this variable +is 1. + +@vindex c-special-indent-hook +@vindex special-indent-hook (c-) +One other customization variable is available in @ccmode{}: +@code{c-special-indent-hook}. This is a standard hook variable that is +called after every line is indented by @ccmode{}. You can use it +to do any special indentation or line adjustments your style dictates, +such as adding extra indentation to constructors or destructor +declarations in a class definition, etc. Note however, that you should +not change point or mark inside your @code{c-special-indent-hook} +functions (i.e. you'll probably want to wrap your function in a +@code{save-excursion}). + +Setting @code{c-special-indent-hook} in your style definition is handled +slightly differently than other variables. In your style definition, +you should set the value for +@code{c-special-indent-hook} to a function or list of functions, which +will be appended to @code{c-special-indent-hook} using @code{add-hook}. +That way, the current setting for the buffer local value of +@code{c-special-indent-hook} won't be overridden. + +@kindex M-; +@findex indent-for-comment +@vindex c-indent-comments-syntactically-p +@vindex indent-comments-syntactically-p (c-) +@vindex comment-column + +Normally, the standard Emacs command @kbd{M-;} +(@code{indent-for-comment}) will indent comment only lines to +@code{comment-column}. Some users however, prefer that @kbd{M-;} act +just like @kbd{TAB} for purposes of indenting comment-only lines; +i.e. they want the comments to always indent as they would for normal +code, regardless of whether @kbd{TAB} or @kbd{M-;} were used. This +behavior is controlled by the variable +@code{c-indent-comments-syntactically-p}. When @code{nil} (the +default), @kbd{M-;} indents comment-only lines to @code{comment-column}, +otherwise, they are indented just as they would be if @kbd{TAB} were +typed. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Syntactic Symbols, Performance Issues, Customizing Indentation, Top +@comment node-name, next, previous,up + +@chapter Syntactic Symbols +@cindex Syntactic Symbols +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@vindex c-offsets-alist +@vindex offsets-alist (c-) + +Here is a complete list of the recognized syntactic symbols as described +in the @code{c-offsets-alist} variable, along with a brief description. +More detailed descriptions follow below. + +@itemize @bullet +@item +@code{string} --- inside multi-line string +@item +@code{c} --- inside a multi-line C style block comment +@item +@code{defun-open} --- brace that opens a function definition +@item +@code{defun-close} --- brace that closes a function definition +@item +@code{defun-block-intro} --- the first line in a top-level defun +@item +@code{class-open} --- brace that opens a class definition +@item +@code{class-close} --- brace that closes a class definition +@item +@code{inline-open} --- brace that opens an in-class inline method +@item +@code{inline-close} --- brace that closes an in-class inline method +@item +@code{func-decl-cont} --- the region between a function definition's +argument list and the function opening brace (excluding K&R argument +declarations). In C, you cannot put anything but whitespace and comments +between them; in C++ and Java, @code{throws} declarations and other +things can appear in this context. +@item +@code{knr-argdecl-intro} --- first line of a K&R C argument declaration +@item +@code{knr-argdecl} --- subsequent lines in a K&R C argument declaration +@item +@code{topmost-intro} --- the first line in a topmost definition +@item +@code{topmost-intro-cont} --- topmost definition continuation lines +@item +@code{member-init-intro} --- first line in a member initialization list +@item +@code{member-init-cont} --- subsequent member initialization list lines +@item +@code{inher-intro} --- first line of a multiple inheritance list +@item +@code{inher-cont} --- subsequent multiple inheritance lines +@item +@code{block-open} --- statement block open brace +@item +@code{block-close} --- statement block close brace +@item +@code{brace-list-open} --- open brace of an enum or static array list +@item +@code{brace-list-close} --- close brace of an enum or static array list +@item +@code{brace-list-intro} --- first line in an enum or static array list +@item +@code{brace-list-entry} --- subsequent lines in an enum or static array list +@item +@code{statement} --- a C statement +@item +@code{statement-cont} --- a continuation of a C statement +@item +@code{statement-block-intro} --- the first line in a new statement block +@item +@code{statement-case-intro} --- the first line in a case `block' +@item +@code{statement-case-open} --- the first line in a case block starting +with brace +@item +@code{substatement} --- the first line after a conditional +@item +@code{substatement-open} --- the brace that opens a substatement block +@item +@code{case-label} --- a case or default label +@item +@code{access-label} --- C++ access control label +@item +@code{label} --- any non-special C label +@item +@code{do-while-closure} --- the `while' that ends a +@code{do}-@code{while} construct +@item +@code{else-clause} --- the `else' of an @code{if}-@code{else} construct +@item +@code{comment-intro} --- a line containing only a comment introduction +@item +@code{arglist-intro} --- the first line in an argument list +@item +@code{arglist-cont} --- subsequent argument list lines when no arguments +follow on the same line as the the arglist opening paren +@item +@code{arglist-cont-nonempty} --- subsequent argument list lines when at +least one argument follows on the same line as the arglist opening paren +@item +@code{arglist-close} --- the solo close paren of an argument list +@item +@code{stream-op} --- lines continuing a stream operator +@item +@code{inclass} --- the line is nested inside a class definition +@item +@code{cpp-macro} --- the start of a C preprocessor macro definition +@item +@code{cpp-macro-cont} --- subsequent lines of a multi-line C +preprocessor macro definition +@item +@code{friend} --- a C++ friend declaration +@item +@code{objc-method-intro} --- the first line of an Objective-C method definition +@item +@code{objc-method-args-cont} --- lines continuing an Objective-C method +definition +@item +@code{objc-method-call-cont} --- lines continuing an Objective-C method call +@item +@code{extern-lang-open} --- brace that opens an external language block +@item +@code{extern-lang-close} --- brace that closes an external language block +@item +@code{inextern-lang} --- analogous to `inclass' syntactic symbol, but +used inside external language blocks (e.g. @code{extern "C" @{}). +@item +@code{namespace-open} --- brace that opens a C++ namespace block. +@item +@code{namespace-close} --- brace that closes a C++ namespace block. +@item +@code{innamespace} --- analogous to `inextern-lang' syntactic symbol, +but used inside C++ namespace blocks. +@item +@code{template-args-cont} --- C++ template argument list continuations +@end itemize + +@cindex -open syntactic symbols +@cindex -close syntactic symbols +Most syntactic symbol names follow a general naming convention. When a +line begins with an open or close brace, the syntactic symbol will +contain the suffix @code{-open} or @code{-close} respectively. + +@cindex -intro syntactic symbols +@cindex -cont syntactic symbols +@cindex -block-intro syntactic symbols +Usually, a distinction is made between the first line that introduces a +construct and lines that continue a construct, and the syntactic symbols +that represent these lines will contain the suffix @code{-intro} or +@code{-cont} respectively. As a sub-classification of this scheme, a +line which is the first of a particular brace block construct will +contain the suffix @code{-block-intro}. + +@kindex C-c C-s +Let's look at some examples to understand how this works. Remember that +you can check the syntax of any line by using @kbd{C-c C-s}. +@example +@group + + 1: void + 2: swap( int& a, int& b ) + 3: @{ + 4: int tmp = a; + 5: a = b; + 6: b = tmp; + 7: int ignored = + 8: a + b; + 9: @} + +@end group +@end example + +@cindex topmost-intro syntactic symbol +@cindex topmost-intro-cont syntactic symbol +@cindex defun-open syntactic symbol +@cindex defun-close syntactic symbol +@cindex defun-block-intro syntactic symbol +Line 1 shows a @code{topmost-intro} since it is the first line that +introduces a top-level construct. Line 2 is a continuation of the +top-level construct introduction so it has the syntax +@code{topmost-intro-cont}. Line 3 shows a @code{defun-open} since it is +the brace that opens a top-level function definition. Line 9 is a +@code{defun-close} since it contains the brace that closes the top-level +function definition. Line 4 is a @code{defun-block-intro}, i.e. it is +the first line of a brace-block, enclosed in a +top-level function definition. + +@cindex statement syntactic symbol +@cindex statement-cont syntactic symbol +Lines 5, 6, and 7 are all given @code{statement} syntax since there +isn't much special about them. Note however that line 8 is given +@code{statement-cont} syntax since it continues the statement begun +on the previous line. + +Here's another example, which illustrates some C++ class syntactic +symbols: +@example +@group + + 1: class Bass + 2: : public Guitar, + 3: public Amplifiable + 4: @{ + 5: public: + 6: Bass() + 7: : eString( new BassString( 0.105 )), + 8: aString( new BassString( 0.085 )), + 9: dString( new BassString( 0.065 )), + 10: gString( new BassString( 0.045 )) + 11: @{ + 12: eString.tune( 'E' ); + 13: aString.tune( 'A' ); + 14: dString.tune( 'D' ); + 15: gString.tune( 'G' ); + 16: @} + 17: friend class Luthier; + 18: @} + +@end group +@end example + +@cindex class-open syntactic symbol +@cindex class-close syntactic symbol +As in the previous example, line 1 has the @code{topmost-intro} syntax. +Here however, the brace that opens a C++ class definition on line 4 is +assigned the @code{class-open} syntax. Note that in C++, classes, +structs, and unions are essentially equivalent syntactically (and are +very similar semantically), so replacing the @code{class} keyword in the +example above with @code{struct} or @code{union} would still result in a +syntax of @code{class-open} for line 4 @footnote{This is the case even +for C and Objective-C. For consistency, structs in all supported +languages are syntactically equivalent to classes. Note however that +the keyword @code{class} is meaningless in C and Objective-C.}. +Similarly, line 18 is assigned @code{class-close} syntax. + +@cindex inher-intro syntactic symbol +@cindex inher-cont syntactic symbol +Line 2 introduces the inheritance list for the class so it is assigned +the @code{inher-intro} syntax, and line 3, which continues the +inheritance list is given @code{inher-cont} syntax. + +@cindex access-label syntactic symbol +@cindex inclass syntactic symbol +Hitting @kbd{C-c C-s} on line 5 shows the following analysis: + +@example +@group + +@code{((inclass . 1) (access-label . 67))} + +@end group +@end example + +@noindent +The primary syntactic symbol for this line is @code{access-label} as +this a label keyword that specifies access protection in C++. However, +because this line is also a top-level construct inside a class +definition, the analysis actually shows two syntactic symbols. The +other syntactic symbol assigned to this line is @code{inclass}. +Similarly, line 6 is given both @code{inclass} and @code{topmost-intro} +syntax: + +@example +@group + +@code{((inclass . 58) (topmost-intro . 60))} + +@end group +@end example + +@cindex member-init-intro syntactic symbol +@cindex member-init-cont syntactic symbol +Line 7 introduces a C++ member initialization list and as such is given +@code{member-init-intro} syntax. Note that in this case it is +@emph{not} assigned @code{inclass} since this is not considered a +top-level construct. Lines 8 through 10 are all assigned +@code{member-init-cont} since they continue the member initialization +list started on line 7. + +@cindex in-class inline methods +@cindex inline-open syntactic symbol +@cindex inline-close syntactic symbol +Line 11's analysis is a bit more complicated: + +@example +@group + +@code{((inclass . 1) (inline-open))} + +@end group +@end example + +This line is assigned a syntax of both @code{inline-open} and +@code{inclass} because it opens an @dfn{in-class} C++ inline method +definition. This is distinct from, but related to, the C++ notion of an +inline function in that its definition occurs inside an enclosing class +definition, which in C++ implies that the function should be inlined. +If though, the definition of the @code{Bass} constructor appeared +outside the class definition, the construct would be given the +@code{defun-open} syntax, even if the keyword @code{inline} appeared +before the method name, as in: +@example +@group + +class Bass + : public Guitar, + public Amplifiable +@{ +public: + Bass(); +@} + +inline +Bass::Bass() + : eString( new BassString( 0.105 )), + aString( new BassString( 0.085 )), + dString( new BassString( 0.065 )), + gString( new BassString( 0.045 )) +@{ + eString.tune( 'E' ); + aString.tune( 'A' ); + dString.tune( 'D' ); + gString.tune( 'G' ); +@} + +@end group +@end example + +@cindex friend syntactic symbol +Returning to the previous example, line 16 is given @code{inline-close} +syntax, while line 12 is given @code{defun-block-open} syntax, and lines +13 through 15 are all given @code{statement} syntax. Line 17 is +interesting in that its syntactic analysis list contains three +elements: + +@example + +@code{((friend) (inclass . 58) (topmost-intro . 380))} + +@end example + +The @code{friend} syntactic symbol is a modifier that typically does not +have a relative buffer position. + +Template definitions introduce yet another syntactic symbol: + +@example +@group + + 1: ThingManager <int, + 2: Framework::Callback *, + 3: Mutex> framework_callbacks; + +@end group +@end example + +Here, line 1 is analyzed as a @code{topmost-intro}, but lines 2 and 3 +are both analyzed as @code{template-args-cont} lines. + +Here is another (totally contrived) example which illustrates how syntax +is assigned to various conditional constructs: +@example +@group + + 1: void spam( int index ) + 2: @{ + 3: for( int i=0; i<index; i++ ) + 4: @{ + 5: if( i == 10 ) + 6: @{ + 7: do_something_special(); + 8: @} + 9: else + 10: do_something( i ); + 11: @} + 12: do @{ + 13: another_thing( i-- ); + 14: @} + 15: while( i > 0 ); + 16: @} + + +@end group +@end example + +@noindent +Only the lines that illustrate new syntactic symbols will be discussed. + +@cindex substatement-open syntactic symbol +@cindex substatement-block-intro syntactic symbol +@cindex block-close syntactic symbol +Line 4 has a brace which opens a conditional's substatement block. It +is thus assigned @code{substatement-open} syntax, and since line 5 is +the first line in the substatement block, it is assigned +@code{substatement-block-intro} syntax. Lines 6 and 7 are assigned +similar syntax. Line 8 contains the brace that closes the inner +substatement block. It is given the syntax @code{block-close}, +as are lines 11 and 14. + +@cindex else-clause syntactic symbol +@cindex substatement syntactic symbol +Line 9 is a little different --- since it contains the keyword +@code{else} matching the @code{if} statement introduced on line 5, it is +given the @code{else-clause} syntax. Note also that line 10 is slightly +different too. Because @code{else} is considered a conditional +introducing keyword @footnote{The list of conditional keywords are (in +C, C++, Objective-C, and Java): @code{for}, @code{if}, @code{do}, +@code{else}, @code{while}, and @code{switch}. C++ and Java have two +additional conditional keywords: @code{try} and @code{catch}. Java also +has the @code{finally} and @code{synchronized} keywords.}, and because +the following substatement is not a brace block, line 10 is assigned the +@code{substatement} syntax. + +@cindex do-while-closure syntactic symbol +One other difference is seen on line 15. The @code{while} construct +that closes a @code{do} conditional is given the special syntax +@code{do-while-closure} if it appears on a line by itself. Note that if +the @code{while} appeared on the same line as the preceding close brace, +that line would have been assigned @code{block-close} syntax instead. + +Switch statements have their own set of syntactic symbols. Here's an +example: +@example +@group + + 1: void spam( enum Ingredient i ) + 2: @{ + 3: switch( i ) @{ + 4: case Ham: + 5: be_a_pig(); + 6: break; + 7: case Salt: + 8: drink_some_water(); + 9: break; + 10: default: + 11: @{ + 12: what_is_it(); + 13: break; + 14: @} + 15: @} + 14: @} + +@end group +@end example + +@cindex case-label syntactic symbol +@cindex statement-case-intro syntactic symbol +@cindex statement-case-open syntactic symbol +Here, lines 4, 7, and 10 are all assigned @code{case-label} syntax, +while lines 5 and 8 are assigned @code{statement-case-intro}. Line 11 +is treated slightly differently since it contains a brace that opens a +block --- it is given @code{statement-case-open} syntax. + +@cindex brace lists +There are a set of syntactic symbols that are used to recognize +constructs inside of brace lists. A brace list is defined as an +@code{enum} or aggregate initializer list, such as might statically +initialize an array of structs. For example: +@example +@group + + 1: static char* ingredients[] = + 2: @{ + 3: "Ham", + 4: "Salt", + 5: NULL + 6: @} + +@end group +@end example + +@cindex brace-list-open syntactic symbol +@cindex brace-list-intro syntactic symbol +@cindex brace-list-close syntactic symbol +@cindex brace-list-entry syntactic symbol +Following convention, line 2 in this example is assigned +@code{brace-list-open} syntax, and line 3 is assigned +@code{brace-list-intro} syntax. Likewise, line 6 is assigned +@code{brace-list-close} syntax. Lines 4 and 5 however, are assigned +@code{brace-list-entry} syntax, as would all subsequent lines in this +initializer list. + +External language definition blocks also have their own syntactic +symbols. In this example: +@example +@group + + 1: extern "C" + 2: @{ + 3: int thing_one( int ); + 4: int thing_two( double ); + 5: @} + +@end group +@end example + +@cindex extern-lang-open syntactic symbol +@cindex extern-lang-close syntactic symbol +@cindex inextern-lang syntactic symbol +@cindex inclass syntactic symbol +@noindent +line 2 is given the @code{extern-lang-open} syntax, while line 5 is given +the @code{extern-lang-close} syntax. The analysis for line 3 yields: +@code{((inextern-lang) (topmost-intro . 14))}, where +@code{inextern-lang} is a modifier similar in purpose to @code{inclass}. + +Similarly, C++ namespace constructs have their own associated syntactic +symbols. In this example: +@example +@group + + 1: namespace foo + 2: @{ + 3: void xxx() @{@} + 4: @} + +@end group +@end example + +@cindex namespace-open syntactic-symbol +@cindex namespace-close syntactic-symbol +@cindex innamespace syntactic-symbol +@noindent +line 2 is given the @code{namespace-open} syntax, while line 4 is given +the @code{namespace-close} syntax. The analysis for line 3 yields: +@code{((innamespace) (topmost-intro . 17))}, where @code{innamespace} is +a modifier similar in purpose to @code{inextern-lang} and @code{inclass}. + +A number of syntactic symbols are associated with parenthesis lists, +a.k.a argument lists, as found in function declarations and function +calls. This example illustrates these: +@example +@group + + 1: void a_function( int line1, + 2: int line2 ); + 3: + 4: void a_longer_function( + 5: int line1, + 6: int line2 + 7: ); + 8: + 9: void call_them( int line1, int line2 ) + 10: @{ + 11: a_function( + 12: line1, + 13: line2 + 14: ); + 15: + 16: a_longer_function( line1, + 17: line2 ); + 18: @} + +@end group +@end example + +@cindex arglist-intro syntactic symbol +@cindex arglist-close syntactic symbol +Lines 5 and 12 are assigned @code{arglist-intro} syntax since they are +the first line following the open parenthesis, and lines 7 and 14 are +assigned @code{arglist-close} syntax since they contain the parenthesis +that closes the argument list. + +@cindex arglist-cont-nonempty syntactic symbol +@cindex arglist-cont syntactic symbol +Lines that continue argument lists can be assigned one of two syntactic +symbols. For example, Lines 2 and 17 +are assigned @code{arglist-cont-nonempty} syntax. What this means +is that they continue an argument list, but that the line containing the +parenthesis that opens the list is @emph{not empty} following the open +parenthesis. Contrast this against lines 6 and 13 which are assigned +@code{arglist-cont} syntax. This is because the parenthesis that opens +their argument lists is the last character on that line. + +Note that there is no @code{arglist-open} syntax. This is because any +parenthesis that opens an argument list, appearing on a separate line, +is assigned the @code{statement-cont} syntax instead. + +A few miscellaneous syntactic symbols that haven't been previously +covered are illustrated by this C++ example: +@example +@group + + 1: void Bass::play( int volume ) + 2: const + 3: @{ + 4: /* this line starts a multi-line + 5: * comment. This line should get `c' syntax */ + 6: + 7: char* a_multiline_string = "This line starts a multi-line \ + 8: string. This line should get `string' syntax."; + 9: + 10: note: + 11: @{ + 12: #ifdef LOCK + 13: Lock acquire(); + 14: #endif // LOCK + 15: slap_pop(); + 16: cout << "I played " + 17: << "a note\n"; + 18: @} + 19: @} + +@end group +@end example + +@cindex modifier syntactic symbol +The lines to note in this example include: + +@itemize @bullet + +@cindex func-decl-cont syntactic symbol +@item +line 2, assigned the @code{func-decl-cont} syntax; + +@cindex comment-intro syntactic symbol +@item +line 4, assigned both @code{defun-block-intro} @emph{and} +@code{comment-intro} syntax; + +@cindex c syntactic symbol +@item +line 5, assigned @code{c} syntax; + +@item +@cindex syntactic whitespace +line 6 which, even though it contains nothing but whitespace, is +assigned @code{defun-block-intro}. Note that the appearance of the +comment on lines 4 and 5 do not cause line 6 to be assigned +@code{statement} syntax because comments are considered to be +@dfn{syntactic whitespace}, which are ignored when analyzing +code; + +@cindex string syntactic symbol +@item +line 8, assigned @code{string} syntax; + +@cindex label syntactic symbol +@item +line 10, assigned @code{label} syntax; + +@cindex block-open syntactic symbol +@item +line 11, assigned @code{block-open} syntax; + +@cindex cpp-macro syntactic symbol +@cindex cpp-macro-cont syntactic symbol +@item +lines 12 and 14, assigned @code{cpp-macro} syntax. + +@cindex stream-op syntactic symbol +@item +line 17, assigned @code{stream-op} syntax. + +@end itemize + +@cindex multi-line macros +@cindex syntactic whitespace +Multi-line C preprocessor macros are now (somewhat) supported. At least +CC Mode now recognizes the fact that it is inside a multi-line macro, +and it properly skips such macros as syntactic whitespace. In this +example: +@example +@group + + 1: #define LIST_LOOP(cons, listp) \ + 2: for (cons = listp; !NILP (cons); cons = XCDR (cons)) \ + 3: if (!CONSP (cons)) \ + 4: signal_error ("Invalid list format", listp); \ + 5: else + +@end group +@end example +@noindent +line 1 is given the syntactic symbol @code{cpp-macro}. This first line +of a macro is always given this symbol. The second and subsequent lines +(e.g. lines 2 through 5) are given the @code{cpp-macro-cont} syntactic +symbol, with a relative buffer position pointing to the @code{#} which +starts the macro definition. + +In Objective-C buffers, there are three additional syntactic symbols +assigned to various message calling constructs. Here's an example +illustrating these: +@example +@group + + 1: - (void)setDelegate:anObject + 2: withStuff:stuff + 3: @{ + 4: [delegate masterWillRebind:self + 5: toDelegate:anObject + 6: withExtraStuff:stuff]; + 7: @} + +@end group +@end example + +@cindex objc-method-intro syntactic symbol +@cindex objc-method-args-cont syntactic symbol +@cindex objc-method-call-cont syntactic symbol +Here, line 1 is assigned @code{objc-method-intro} syntax, and line 2 is +assigned @code{objc-method-args-cont} syntax. Lines 5 and 6 are both +assigned @code{objc-method-call-cont} syntax. + +@cindex knr-argdecl-intro syntactic symbol +@cindex knr-argdecl syntactic symbol +Two other syntactic symbols can appear in old style, non-prototyped C +code @footnote{a.k.a. K&R C, or Kernighan & Ritchie C}: +@example +@group + + 1: int add_three_integers(a, b, c) + 2: int a; + 3: int b; + 4: int c; + 5: @{ + 6: return a + b + c; + 7: @} + +@end group +@end example + +Here, line 2 is the first line in an argument declaration list and so is +given the @code{knr-argdecl-intro} syntactic symbol. Subsequent lines +(i.e. lines 3 and 4 in this example), are given @code{knr-argdecl} +syntax. + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Performance Issues, Frequently Asked Questions, Syntactic Symbols, Top +@comment node-name, next, previous,up + +@chapter Performance Issues +@cindex Performance Issues +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +C and its derivative languages are highly complex creatures. Often, +ambiguous code situations arise that require @ccmode{} to scan +large portions of the buffer to determine syntactic context. Such +pathological code@footnote{such as the output of @code{lex(1)}!} +can cause @ccmode{} to perform fairly badly. +This section identifies some of the coding styles to watch out for, and +suggests some workarounds that you can use to improve performance. + +Because @ccmode{} has to scan the buffer backwards from the current +insertion point, and because C's syntax is fairly difficult to parse in +the backwards direction, @ccmode{} often tries to find the nearest +position higher up in the buffer from which to begin a forward scan. +The farther this position is from the current insertion point, the +slower the mode gets. Some coding styles can even force @ccmode{} +to scan from the beginning of the buffer for every line of code! + +@findex beginning-of-defun +@findex defun-prompt-regexp +One of the simplest things you can do to reduce scan time, is make sure +any brace that opens a top-level construct@footnote{e.g. a function in +C, or outermost class definition in C++ or Java.} always appears in the +leftmost column. This is actually an Emacs constraint, as embodied in +the @code{beginning-of-defun} function which @ccmode{} uses +heavily. If you insist on hanging top-level open braces on the right +side of the line, then you might want to set the variable +@code{defun-prompt-regexp} to something reasonable @footnote{Note that +this variable is only defined in Emacs 19.}, however that ``something +reasonable'' is difficult to define, so @ccmode{} doesn't do it +for you. + +@vindex c-Java-defun-prompt-regexp +@vindex Java-defun-prompt-regexp (c-) +A special note about @code{defun-prompt-regexp} in Java mode: while much +of the early sample Java code seems to encourage a style where the brace +that opens a class is hung on the right side of the line, this is not a +good style to pursue in Emacs. @ccmode{} comes with a variable +@code{c-Java-defun-prompt-regexp} which tries to define a regular +expression usable for this style, but there are problems with it. In +some cases it can cause @code{beginning-of-defun} to hang@footnote{This +has been observed in Emacs 19.34 and XEmacs 19.15.}. For this reason, +it is not used by default, but if you feel adventurous, you can set +@code{defun-prompt-regexp} to it in your mode hook. In any event, +setting and rely on @code{defun-prompt-regexp} will definitely slow +things down! + +You will probably notice pathological behavior from @ccmode{} when +working in files containing large amounts of C preprocessor macros. +This is because Emacs cannot skip backwards over these lines as quickly +as it can comment. + +@vindex c-recognize-knr-p +@vindex recognize-knr-p (c-) +Previous versions of @ccmode{} had potential performance problems +when recognizing K&R style function argument declarations. This was +because there are ambiguities in the C syntax when K&R style argument +lists are used@footnote{It is hard to distinguish them from top-level +declarations.}. @ccmode{} has adopted BOCM's convention for +limiting the search: it assumes that argdecls are indented at least one +space, and that the function headers are not indented at all. With +current versions of @ccmode{}, user customization of +@code{c-recognize-knr-p} is deprecated. Just don't put argdecls in +column zero! + +@cindex @file{cc-lobotomy.el} file +@vindex cc-lobotomy-pith-list +You might want to investigate the speed-ups contained in the +file @file{cc-lobotomy.el}, which comes as part of the @ccmode{} +distribution, but is completely unsupported. +As mentioned previous, @ccmode{} always trades speed for accuracy, +however it is recognized that sometimes you need speed and can sacrifice +some accuracy in indentation. The file @file{cc-lobotomy.el} contains +hacks that will ``dumb down'' @ccmode{} in some specific ways, making +that trade-off of accurancy for speed. I won't go into details of its +use here; you should read the comments at the top of the file, and look +at the variable @code{cc-lobotomy-pith-list} for details. + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Frequently Asked Questions, Getting the latest CC Mode release, Performance Issues, Top +@comment node-name, next, previous,up + +@chapter Frequently Asked Questions +@cindex Frequently Asked Questions +@comment FAQ +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@kindex C-x h +@kindex ESC C-\ +@kindex ESC C-x +@kindex C-c C-q +@kindex ESC C-q +@kindex ESC C-u +@kindex RET +@kindex C-j +@findex newline-and-indent +@quotation + +@strong{Q.} @emph{How do I re-indent the whole file?} + +@strong{A.} Visit the file and hit @kbd{C-x h} to mark the whole +buffer. Then hit @kbd{ESC C-\}. +@sp 1 + +@strong{Q.} @emph{How do I re-indent the entire function? +@kbd{ESC C-x} doesn't work.} + +@strong{A.} @kbd{ESC C-x} is reserved for future Emacs use. +To re-indent the entire function hit @kbd{C-c C-q}. +@sp 1 + +@strong{Q.} @emph{How do I re-indent the current block?} + +@strong{A.} First move to the brace which opens the block with +@kbd{ESC C-u}, then re-indent that expression with +@kbd{ESC C-q}. +@sp 1 + +@strong{Q.} @emph{Why doesn't the @kbd{RET} key indent the line to +where the new text should go after inserting the newline?} + +@strong{A.} Emacs' convention is that @kbd{RET} just adds a newline, +and that @kbd{C-j} adds a newline and indents it. You can make +@kbd{RET} do this too by adding this to your +@code{c-mode-common-hook} (see the sample @file{.emacs} file +@ref{Sample .emacs File}): +@example + +(define-key c-mode-base-map "\C-m" 'newline-and-indent) + +@end example + +This is a very common question. If you want this to be the default +behavior, don't lobby me, lobby RMS! @code{:-)} +@sp 1 + +@strong{Q.} @emph{I put @code{(c-set-offset 'substatement-open 0)} +in my @file{.emacs} file but I get an error saying that +@code{c-set-offset}'s function definition is void.} + +@strong{A.} This means that @ccmode{} wasn't loaded into your +Emacs session by the time the @code{c-set-offset} call was reached, +mostly likely because @ccmode{} is being autoloaded. Instead +of putting the @code{c-set-offset} line in your top-level +@file{.emacs} file, put it in your @code{c-mode-common-hook}, or +simply add the following to the top of your @file{.emacs} file: +@example + +(require 'cc-mode) + +@end example + +See the sample @file{.emacs} file @ref{Sample .emacs File} for +details. + +@sp 1 +@strong{Q.} @emph{How do I make strings, comments, keywords, and other +constructs appear in different colors, or in bold face, etc.?} + +@strong{A.} ``Syntax Colorization'' is a standard Emacs feature, +controlled by @code{font-lock-mode}. It is not part of @ccmode{}. + +@sp 1 +@strong{Q.} @emph{@kbd{M-a} and @kbd{M-e} used to move over entire +balanced brace lists, but now they move into blocks. How do I get the +old behavior back?} + +@strong{A.} Use @kbd{C-M-f} and @kbd{C-M-b} to move over balanced brace +blocks. Use @kbd{M-a} and @kbd{M-e} to move by statements, which will +move into blocks. + +@end quotation + + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Getting the latest CC Mode release, Sample .emacs File, Frequently Asked Questions, Top +@comment node-name, next, previous,up + +@chapter Getting the latest CC Mode release +@cindex Getting the latest CC Mode release +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@ccmode{} is now standard with the latest versions of Emacs 19 and +XEmacs 19. It is also the standard for Emacs 20 and XEmacs 20. You +would typically just use the version that comes with your X/Emacs. +These may be slightly out of date due to release schedule skew, so you +should always check the canonical site for the latest version. + +@example +@group + + World Wide Web: + + @code{http://www.python.org/ftp/emacs/} + + Anonymous FTP: + + @code{ftp://ftp.python.org/pub/emacs/} + +@end group +@end example + +There are many files under these directories; you can pick up the entire +distribution (named @code{cc-mode.tar.gz}; a gzip'd tar file), or any of +the individual files, including PostScript documentation. + +If you do not have World Wide Web, or anonymous ftp access, you can get +the distribution through an anonymous ftp-to-mail gateway, such as the +one run by DEC at: +@example + +@code{ftpmail@@decwrl.dec.com} + +@end example +To get @ccmode{} via email, send the following message in the body of +your mail to that address: +@example + +reply <a valid net address back to you> +connect ftp.python.org +binary +uuencode +chdir pub/emacs +get cc-mode.tar.gz + +@end example +@noindent +or just send the message "help" for more information on ftpmail. +Response times will vary with the number of requests in the queue. I am +in no way connected to this service, so I make no claims or guarantees +about its availability! + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Sample .emacs File, Limitations and Known Bugs, Getting the latest CC Mode release, Top +@comment node-name, next, previous,up + +@chapter Sample .emacs file +@cindex Sample .emacs file +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@example +;; Here's a sample .emacs file that might help you along the way. Just +;; copy this region and paste it into your .emacs file. You may want to +;; change some of the actual values. + +(defconst my-c-style + '((c-tab-always-indent . t) + (c-comment-only-line-offset . 4) + (c-hanging-braces-alist . ((substatement-open after) + (brace-list-open))) + (c-hanging-colons-alist . ((member-init-intro before) + (inher-intro) + (case-label after) + (label after) + (access-label after))) + (c-cleanup-list . (scope-operator + empty-defun-braces + defun-close-semi)) + (c-offsets-alist . ((arglist-close . c-lineup-arglist) + (substatement-open . 0) + (case-label . 4) + (block-open . 0) + (knr-argdecl-intro . -))) + (c-echo-syntactic-information-p . t) + ) + "My C Programming Style") + +;; Customizations for all of c-mode, c++-mode, and objc-mode +(defun my-c-mode-common-hook () + ;; add my personal style and set it for the current buffer + (c-add-style "PERSONAL" my-c-style t) + ;; offset customizations not in my-c-style + (c-set-offset 'member-init-intro '++) + ;; other customizations + (setq tab-width 8 + ;; this will make sure spaces are used instead of tabs + indent-tabs-mode nil) + ;; we like auto-newline and hungry-delete + (c-toggle-auto-hungry-state 1) + ;; keybindings for all supported languages. We can put these in + ;; c-mode-base-map because c-mode-map, c++-mode-map, objc-mode-map, + ;; java-mode-map, and idl-mode-map inherit from it. + (define-key c-mode-base-map "\C-m" 'newline-and-indent) + ) + +(add-hook 'c-mode-common-hook 'my-c-mode-common-hook) +@end example + +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Limitations and Known Bugs, Mailing Lists and Submitting Bug Reports, Sample .emacs File, Top +@comment node-name, next, previous,up +@chapter Limitations and Known Bugs +@cindex Limitations and Known Bugs +@comment * Limitations and Known Bugs +@comment !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@itemize @bullet +@item +Re-indenting large regions or expressions can be slow. + +@item +Add-on fill packages may not work as well as @ccmode{}'s built-in +filling routines. I no longer recommend you use @code{filladapt} to +fill comments. + +@cindex c-indent-exp +@cindex indent-exp (c-) +@item +@code{c-indent-exp} has not been fully optimized. It essentially +equivalent to hitting @kbd{TAB} (@code{c-indent-command}) on every +line. Some information is cached from line to line, but such caching +invariable causes inaccuracies in analysis in some bizarre situations. + +@end itemize + +@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Mailing Lists and Submitting Bug Reports, Concept Index, Limitations and Known Bugs, Top +@comment node-name, next, previous,up +@chapter Mailing Lists and Submitting Bug Reports +@cindex Mailing Lists and Submitting Bug Reports +@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@kindex C-c C-b +@findex c-submit-bug-report +@findex submit-bug-report (c-) +@cindex beta testers mailing list +@cindex announcement mailing list +To report bugs, use the @kbd{C-c C-b} (@code{c-submit-bug-report}) +command. This provides vital information I need to reproduce your +problem. Make sure you include a concise, but complete code example. +Please try to boil your example down to just the essential code needed +to reproduce the problem, and include an exact recipe of steps needed to +expose the bug. Be especially sure to include any code that appears +@emph{before} your bug example, if you think it might affect my ability +to reproduce it. + +Bug reports are now sent to the following email addresses: +@code{cc-mode-help@@python.org} and +@code{bug-gnu-emacs@@gnu.org}; the latter is mirrored on the +Usenet newsgroup @code{gnu.emacs.bug}. You can send other questions and +suggestions (kudos? @code{;-)} to @code{cc-mode-help@@python.org}, or +@code{help-gnu-emacs@@gnu.org} which is mirrored on newsgroup +@code{gnu.emacs.help}. + +If you want to get announcements of new CC Mode releases, send the +word @emph{subscribe} in the body of a message to +@code{cc-mode-announce-request@@python.org}. Announcements will also be +posted to the Usenet newsgroup @code{gnu.emacs.sources}. Note that the +@code{cc-mode-victims@@python.org} mailing list was recently +decommissioned. + +@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Concept Index, Command Index, Mailing Lists and Submitting Bug Reports, Top +@comment node-name, next, previous, up +@unnumbered Concept Index +@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@printindex cp + + +@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Command Index, Key Index, Concept Index, Top +@comment node-name, next, previous, up +@unnumbered Command Index +@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@ifinfo + +@end ifinfo +Since all @ccmode{} commands are prepended with the string +@samp{c-}, each appears under its @code{c-@var{<thing>}} name and its +@code{@var{<thing>} (c-)} name. +@iftex +@sp 2 +@end iftex +@printindex fn + + +@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Key Index, Variable Index, Command Index, Top +@comment node-name, next, previous, up +@unnumbered Key Index +@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@printindex ky + + +@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +@node Variable Index, , Key Index, Top +@comment node-name, next, previous, up +@unnumbered Variable Index +@c !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +@ifinfo + +@end ifinfo +Since all @ccmode{} variables are prepended with the string +@samp{c-}, each appears under its @code{c-@var{<thing>}} name and its +@code{@var{<thing>} (c-)} name. +@iftex +@sp 2 +@end iftex +@printindex vr +@page +@summarycontents +@contents +@bye + diff --git a/man/cl.texi b/man/cl.texi new file mode 100644 index 00000000000..18e06567724 --- /dev/null +++ b/man/cl.texi @@ -0,0 +1,5701 @@ +\input texinfo @c -*-texinfo-*- +@setfilename ../info/cl +@settitle Common Lisp Extensions + +@dircategory Editors +@direntry +* CL: (cl). Partial Common Lisp support for Emacs Lisp. +@end direntry + +@iftex +@finalout +@end iftex + +@ifinfo +This file documents the GNU Emacs Common Lisp emulation package. + +Copyright (C) 1993 Free Software Foundation, Inc. + +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 +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +section entitled ``GNU General Public License'' is included exactly as +in the original, and provided that the entire resulting derived work is +distributed under the terms of a permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the section entitled ``GNU General Public License'' may be +included in a translation approved by the author instead of in the +original English. +@end ifinfo + +@titlepage +@sp 6 +@center @titlefont{Common Lisp Extensions} +@sp 4 +@center For GNU Emacs Lisp +@sp 1 +@center Version 2.02 +@sp 5 +@center Dave Gillespie +@center daveg@@synaptics.com +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1993 Free Software Foundation, Inc. + +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 +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +section entitled ``GNU General Public License'' is included exactly as +in the original, and provided that the entire resulting derived work is +distributed under the terms of a permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the section entitled ``GNU General Public License'' may be +included in a translation approved by the author instead of in the +original English. +@end titlepage + +@node Top, Overview,, (dir) +@chapter Common Lisp Extensions + +@noindent +This document describes a set of Emacs Lisp facilities borrowed from +Common Lisp. All the facilities are described here in detail. While +this document does not assume any prior knowledge of Common Lisp, it +does assume a basic familiarity with Emacs Lisp. + +@menu +* Overview:: Installation, usage, etc. +* Program Structure:: Arglists, `eval-when', `defalias' +* Predicates:: `typep', `eql', and `equalp' +* Control Structure:: `setf', `do', `loop', etc. +* Macros:: Destructuring, `define-compiler-macro' +* Declarations:: `proclaim', `declare', etc. +* Symbols:: Property lists, `gensym' +* Numbers:: Predicates, functions, random numbers +* Sequences:: Mapping, functions, searching, sorting +* Lists:: `cadr', `sublis', `member*', `assoc*', etc. +* Hash Tables:: `make-hash-table', `gethash', etc. +* Structures:: `defstruct' +* Assertions:: `check-type', `assert', `ignore-errors'. + +* Efficiency Concerns:: Hints and techniques +* Common Lisp Compatibility:: All known differences with Steele +* Old CL Compatibility:: All known differences with old cl.el +* Porting Common Lisp:: Hints for porting Common Lisp code + +* Function Index:: +* Variable Index:: +@end menu + +@node Overview, Program Structure, Top, Top +@ifinfo +@chapter Overview +@end ifinfo +@iftex +@section Overview +@end iftex + +@noindent +Common Lisp is a huge language, and Common Lisp systems tend to be +massive and extremely complex. Emacs Lisp, by contrast, is rather +minimalist in the choice of Lisp features it offers the programmer. +As Emacs Lisp programmers have grown in number, and the applications +they write have grown more ambitious, it has become clear that Emacs +Lisp could benefit from many of the conveniences of Common Lisp. + +The @dfn{CL} package adds a number of Common Lisp functions and +control structures to Emacs Lisp. While not a 100% complete +implementation of Common Lisp, @dfn{CL} adds enough functionality +to make Emacs Lisp programming significantly more convenient. + +Some Common Lisp features have been omitted from this package +for various reasons: + +@itemize @bullet +@item +Some features are too complex or bulky relative to their benefit +to Emacs Lisp programmers. CLOS and Common Lisp streams are fine +examples of this group. + +@item +Other features cannot be implemented without modification to the +Emacs Lisp interpreter itself, such as multiple return values, +lexical scoping, case-insensitive symbols, and complex numbers. +The @dfn{CL} package generally makes no attempt to emulate these +features. + +@item +Some features conflict with existing things in Emacs Lisp. For +example, Emacs' @code{assoc} function is incompatible with the +Common Lisp @code{assoc}. In such cases, this package usually +adds the suffix @samp{*} to the function name of the Common +Lisp version of the function (e.g., @code{assoc*}). +@end itemize + +The package described here was written by Dave Gillespie, +@file{daveg@@synaptics.com}. It is a total rewrite of the original +1986 @file{cl.el} package by Cesar Quiroz. Most features of the +the Quiroz package have been retained; any incompatibilities are +noted in the descriptions below. Care has been taken in this +version to ensure that each function is defined efficiently, +concisely, and with minimal impact on the rest of the Emacs +environment. + +@menu +* Usage:: How to use the CL package +* Organization:: The package's five component files +* Installation:: Compiling and installing CL +* Naming Conventions:: Notes on CL function names +@end menu + +@node Usage, Organization, Overview, Overview +@section Usage + +@noindent +Lisp code that uses features from the @dfn{CL} package should +include at the beginning: + +@example +(require 'cl) +@end example + +@noindent +If you want to ensure that the new (Gillespie) version of @dfn{CL} +is the one that is present, add an additional @code{(require 'cl-19)} +call: + +@example +(require 'cl) +(require 'cl-19) +@end example + +@noindent +The second call will fail (with ``@file{cl-19.el} not found'') if +the old @file{cl.el} package was in use. + +It is safe to arrange to load @dfn{CL} at all times, e.g., +in your @file{.emacs} file. But it's a good idea, for portability, +to @code{(require 'cl)} in your code even if you do this. + +@node Organization, Installation, Usage, Overview +@section Organization + +@noindent +The Common Lisp package is organized into four files: + +@table @file +@item cl.el +This is the ``main'' file, which contains basic functions +and information about the package. This file is relatively +compact---about 700 lines. + +@item cl-extra.el +This file contains the larger, more complex or unusual functions. +It is kept separate so that packages which only want to use Common +Lisp fundamentals like the @code{cadr} function won't need to pay +the overhead of loading the more advanced functions. + +@item cl-seq.el +This file contains most of the advanced functions for operating +on sequences or lists, such as @code{delete-if} and @code{assoc*}. + +@item cl-macs.el +This file contains the features of the packages which are macros +instead of functions. Macros expand when the caller is compiled, +not when it is run, so the macros generally only need to be +present when the byte-compiler is running (or when the macros are +used in uncompiled code such as a @file{.emacs} file). Most of +the macros of this package are isolated in @file{cl-macs.el} so +that they won't take up memory unless you are compiling. +@end table + +The file @file{cl.el} includes all necessary @code{autoload} +commands for the functions and macros in the other three files. +All you have to do is @code{(require 'cl)}, and @file{cl.el} +will take care of pulling in the other files when they are +needed. + +There is another file, @file{cl-compat.el}, which defines some +routines from the older @file{cl.el} package that are no longer +present in the new package. This includes internal routines +like @code{setelt} and @code{zip-lists}, deprecated features +like @code{defkeyword}, and an emulation of the old-style +multiple-values feature. @xref{Old CL Compatibility}. + +@node Installation, Naming Conventions, Organization, Overview +@section Installation + +@noindent +Installation of the @dfn{CL} package is simple: Just put the +byte-compiled files @file{cl.elc}, @file{cl-extra.elc}, +@file{cl-seq.elc}, @file{cl-macs.elc}, and @file{cl-compat.elc} +into a directory on your @code{load-path}. + +There are no special requirements to compile this package: +The files do not have to be loaded before they are compiled, +nor do they need to be compiled in any particular order. + +You may choose to put the files into your main @file{lisp/} +directory, replacing the original @file{cl.el} file there. Or, +you could put them into a directory that comes before @file{lisp/} +on your @code{load-path} so that the old @file{cl.el} is +effectively hidden. + +Also, format the @file{cl.texinfo} file and put the resulting +Info files in the @file{info/} directory or another suitable place. + +You may instead wish to leave this package's components all in +their own directory, and then add this directory to your +@code{load-path} and (Emacs 19 only) @code{Info-directory-list}. +Add the directory to the front of the list so the old @dfn{CL} +package and its documentation are hidden. + +@node Naming Conventions, , Installation, Overview +@section Naming Conventions + +@noindent +Except where noted, all functions defined by this package have the +same names and calling conventions as their Common Lisp counterparts. + +Following is a complete list of functions whose names were changed +from Common Lisp, usually to avoid conflicts with Emacs. In each +case, a @samp{*} has been appended to the Common Lisp name to obtain +the Emacs name: + +@example +defun* defsubst* defmacro* function* +member* assoc* rassoc* get* +remove* delete* mapcar* sort* +floor* ceiling* truncate* round* +mod* rem* random* last* +@end example + +Internal function and variable names in the package are prefixed +by @code{cl-}. Here is a complete list of functions @emph{not} +prefixed by @code{cl-} which were not taken from Common Lisp: + +@example +member delete remove remq +rassoc floatp-safe lexical-let lexical-let* +callf callf2 letf letf* +defsubst* defalias add-hook eval-when-compile +@end example + +@noindent +(Most of these are Emacs 19 features provided to Emacs 18 users, +or introduced, like @code{remq}, for reasons of symmetry +with similar features.) + +The following simple functions and macros are defined in @file{cl.el}; +they do not cause other components like @file{cl-extra} to be loaded. + +@example +eql floatp-safe abs endp +evenp oddp plusp minusp +butlast nbutlast caar .. cddddr +list* ldiff rest first .. tenth +member [1] copy-list subst mapcar* [2] +adjoin [3] acons pairlis pop [4] +push [4] pushnew [3,4] incf [4] decf [4] +proclaim declaim +@end example + +@noindent +[1] This is the Emacs 19-compatible function, not @code{member*}. + +@noindent +[2] Only for one sequence argument or two list arguments. + +@noindent +[3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified, +and @code{:key} is not used. + +@noindent +[4] Only when @var{place} is a plain variable name. + +@iftex +@chapno=4 +@end iftex + +@node Program Structure, Predicates, Overview, Top +@chapter Program Structure + +@noindent +This section describes features of the @dfn{CL} package which have to +do with programs as a whole: advanced argument lists for functions, +and the @code{eval-when} construct. + +@menu +* Argument Lists:: `&key', `&aux', `defun*', `defmacro*'. +* Time of Evaluation:: The `eval-when' construct. +* Function Aliases:: The `defalias' function. +@end menu + +@iftex +@secno=1 +@end iftex + +@node Argument Lists, Time of Evaluation, Program Structure, Program Structure +@section Argument Lists + +@noindent +Emacs Lisp's notation for argument lists of functions is a subset of +the Common Lisp notation. As well as the familiar @code{&optional} +and @code{&rest} markers, Common Lisp allows you to specify default +values for optional arguments, and it provides the additional markers +@code{&key} and @code{&aux}. + +Since argument parsing is built-in to Emacs, there is no way for +this package to implement Common Lisp argument lists seamlessly. +Instead, this package defines alternates for several Lisp forms +which you must use if you need Common Lisp argument lists. + +@defspec defun* name arglist body... +This form is identical to the regular @code{defun} form, except +that @var{arglist} is allowed to be a full Common Lisp argument +list. Also, the function body is enclosed in an implicit block +called @var{name}; @pxref{Blocks and Exits}. +@end defspec + +@defspec defsubst* name arglist body... +This is just like @code{defun*}, except that the function that +is defined is automatically proclaimed @code{inline}, i.e., +calls to it may be expanded into in-line code by the byte compiler. +This is analogous to the @code{defsubst} form in Emacs 19; +@code{defsubst*} uses a different method (compiler macros) which +works in all version of Emacs, and also generates somewhat more +efficient inline expansions. In particular, @code{defsubst*} +arranges for the processing of keyword arguments, default values, +etc., to be done at compile-time whenever possible. +@end defspec + +@defspec defmacro* name arglist body... +This is identical to the regular @code{defmacro} form, +except that @var{arglist} is allowed to be a full Common Lisp +argument list. The @code{&environment} keyword is supported as +described in Steele. The @code{&whole} keyword is supported only +within destructured lists (see below); top-level @code{&whole} +cannot be implemented with the current Emacs Lisp interpreter. +The macro expander body is enclosed in an implicit block called +@var{name}. +@end defspec + +@defspec function* symbol-or-lambda +This is identical to the regular @code{function} form, +except that if the argument is a @code{lambda} form then that +form may use a full Common Lisp argument list. +@end defspec + +Also, all forms (such as @code{defsetf} and @code{flet}) defined +in this package that include @var{arglist}s in their syntax allow +full Common Lisp argument lists. + +Note that it is @emph{not} necessary to use @code{defun*} in +order to have access to most @dfn{CL} features in your function. +These features are always present; @code{defun*}'s only +difference from @code{defun} is its more flexible argument +lists and its implicit block. + +The full form of a Common Lisp argument list is + +@example +(@var{var}... + &optional (@var{var} @var{initform} @var{svar})... + &rest @var{var} + &key ((@var{keyword} @var{var}) @var{initform} @var{svar})... + &aux (@var{var} @var{initform})...) +@end example + +Each of the five argument list sections is optional. The @var{svar}, +@var{initform}, and @var{keyword} parts are optional; if they are +omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}. + +The first section consists of zero or more @dfn{required} arguments. +These arguments must always be specified in a call to the function; +there is no difference between Emacs Lisp and Common Lisp as far as +required arguments are concerned. + +The second section consists of @dfn{optional} arguments. These +arguments may be specified in the function call; if they are not, +@var{initform} specifies the default value used for the argument. +(No @var{initform} means to use @code{nil} as the default.) The +@var{initform} is evaluated with the bindings for the preceding +arguments already established; @code{(a &optional (b (1+ a)))} +matches one or two arguments, with the second argument defaulting +to one plus the first argument. If the @var{svar} is specified, +it is an auxiliary variable which is bound to @code{t} if the optional +argument was specified, or to @code{nil} if the argument was omitted. +If you don't use an @var{svar}, then there will be no way for your +function to tell whether it was called with no argument, or with +the default value passed explicitly as an argument. + +The third section consists of a single @dfn{rest} argument. If +more arguments were passed to the function than are accounted for +by the required and optional arguments, those extra arguments are +collected into a list and bound to the ``rest'' argument variable. +Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp. +Common Lisp accepts @code{&body} as a synonym for @code{&rest} in +macro contexts; this package accepts it all the time. + +The fourth section consists of @dfn{keyword} arguments. These +are optional arguments which are specified by name rather than +positionally in the argument list. For example, + +@example +(defun* foo (a &optional b &key c d (e 17))) +@end example + +@noindent +defines a function which may be called with one, two, or more +arguments. The first two arguments are bound to @code{a} and +@code{b} in the usual way. The remaining arguments must be +pairs of the form @code{:c}, @code{:d}, or @code{:e} followed +by the value to be bound to the corresponding argument variable. +(Symbols whose names begin with a colon are called @dfn{keywords}, +and they are self-quoting in the same way as @code{nil} and +@code{t}.) + +For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five +arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword +appears more than once in the function call, the first occurrence +takes precedence over the later ones. Note that it is not possible +to specify keyword arguments without specifying the optional +argument @code{b} as well, since @code{(foo 1 :c 2)} would bind +@code{b} to the keyword @code{:c}, then signal an error because +@code{2} is not a valid keyword. + +If a @var{keyword} symbol is explicitly specified in the argument +list as shown in the above diagram, then that keyword will be +used instead of just the variable name prefixed with a colon. +You can specify a @var{keyword} symbol which does not begin with +a colon at all, but such symbols will not be self-quoting; you +will have to quote them explicitly with an apostrophe in the +function call. + +Ordinarily it is an error to pass an unrecognized keyword to +a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask +Lisp to ignore unrecognized keywords, either by adding the +marker @code{&allow-other-keys} after the keyword section +of the argument list, or by specifying an @code{:allow-other-keys} +argument in the call whose value is non-@code{nil}. If the +function uses both @code{&rest} and @code{&key} at the same time, +the ``rest'' argument is bound to the keyword list as it appears +in the call. For example: + +@smallexample +(defun* find-thing (thing &rest rest &key need &allow-other-keys) + (or (apply 'member* thing thing-list :allow-other-keys t rest) + (if need (error "Thing not found")))) +@end smallexample + +@noindent +This function takes a @code{:need} keyword argument, but also +accepts other keyword arguments which are passed on to the +@code{member*} function. @code{allow-other-keys} is used to +keep both @code{find-thing} and @code{member*} from complaining +about each others' keywords in the arguments. + +As a (significant) performance optimization, this package +implements the scan for keyword arguments by calling @code{memq} +to search for keywords in a ``rest'' argument. Technically +speaking, this is incorrect, since @code{memq} looks at the +odd-numbered values as well as the even-numbered keywords. +The net effect is that if you happen to pass a keyword symbol +as the @emph{value} of another keyword argument, where that +keyword symbol happens to equal the name of a valid keyword +argument of the same function, then the keyword parser will +become confused. This minor bug can only affect you if you +use keyword symbols as general-purpose data in your program; +this practice is strongly discouraged in Emacs Lisp. + +The fifth section of the argument list consists of @dfn{auxiliary +variables}. These are not really arguments at all, but simply +variables which are bound to @code{nil} or to the specified +@var{initforms} during execution of the function. There is no +difference between the following two functions, except for a +matter of stylistic taste: + +@example +(defun* foo (a b &aux (c (+ a b)) d) + @var{body}) + +(defun* foo (a b) + (let ((c (+ a b)) d) + @var{body})) +@end example + +Argument lists support @dfn{destructuring}. In Common Lisp, +destructuring is only allowed with @code{defmacro}; this package +allows it with @code{defun*} and other argument lists as well. +In destructuring, any argument variable (@var{var} in the above +diagram) can be replaced by a list of variables, or more generally, +a recursive argument list. The corresponding argument value must +be a list whose elements match this recursive argument list. +For example: + +@example +(defmacro* dolist ((var listform &optional resultform) + &rest body) + ...) +@end example + +This says that the first argument of @code{dolist} must be a list +of two or three items; if there are other arguments as well as this +list, they are stored in @code{body}. All features allowed in +regular argument lists are allowed in these recursive argument lists. +In addition, the clause @samp{&whole @var{var}} is allowed at the +front of a recursive argument list. It binds @var{var} to the +whole list being matched; thus @code{(&whole all a b)} matches +a list of two things, with @code{a} bound to the first thing, +@code{b} bound to the second thing, and @code{all} bound to the +list itself. (Common Lisp allows @code{&whole} in top-level +@code{defmacro} argument lists as well, but Emacs Lisp does not +support this usage.) + +One last feature of destructuring is that the argument list may be +dotted, so that the argument list @code{(a b . c)} is functionally +equivalent to @code{(a b &rest c)}. + +If the optimization quality @code{safety} is set to 0 +(@pxref{Declarations}), error checking for wrong number of +arguments and invalid keyword arguments is disabled. By default, +argument lists are rigorously checked. + +@node Time of Evaluation, Function Aliases, Argument Lists, Program Structure +@section Time of Evaluation + +@noindent +Normally, the byte-compiler does not actually execute the forms in +a file it compiles. For example, if a file contains @code{(setq foo t)}, +the act of compiling it will not actually set @code{foo} to @code{t}. +This is true even if the @code{setq} was a top-level form (i.e., not +enclosed in a @code{defun} or other form). Sometimes, though, you +would like to have certain top-level forms evaluated at compile-time. +For example, the compiler effectively evaluates @code{defmacro} forms +at compile-time so that later parts of the file can refer to the +macros that are defined. + +@defspec eval-when (situations...) forms... +This form controls when the body @var{forms} are evaluated. +The @var{situations} list may contain any set of the symbols +@code{compile}, @code{load}, and @code{eval} (or their long-winded +ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel}, +and @code{:execute}). + +The @code{eval-when} form is handled differently depending on +whether or not it is being compiled as a top-level form. +Specifically, it gets special treatment if it is being compiled +by a command such as @code{byte-compile-file} which compiles files +or buffers of code, and it appears either literally at the +top level of the file or inside a top-level @code{progn}. + +For compiled top-level @code{eval-when}s, the body @var{forms} are +executed at compile-time if @code{compile} is in the @var{situations} +list, and the @var{forms} are written out to the file (to be executed +at load-time) if @code{load} is in the @var{situations} list. + +For non-compiled-top-level forms, only the @code{eval} situation is +relevant. (This includes forms executed by the interpreter, forms +compiled with @code{byte-compile} rather than @code{byte-compile-file}, +and non-top-level forms.) The @code{eval-when} acts like a +@code{progn} if @code{eval} is specified, and like @code{nil} +(ignoring the body @var{forms}) if not. + +The rules become more subtle when @code{eval-when}s are nested; +consult Steele (second edition) for the gruesome details (and +some gruesome examples). + +Some simple examples: + +@example +;; Top-level forms in foo.el: +(eval-when (compile) (setq foo1 'bar)) +(eval-when (load) (setq foo2 'bar)) +(eval-when (compile load) (setq foo3 'bar)) +(eval-when (eval) (setq foo4 'bar)) +(eval-when (eval compile) (setq foo5 'bar)) +(eval-when (eval load) (setq foo6 'bar)) +(eval-when (eval compile load) (setq foo7 'bar)) +@end example + +When @file{foo.el} is compiled, these variables will be set during +the compilation itself: + +@example +foo1 foo3 foo5 foo7 ; `compile' +@end example + +When @file{foo.elc} is loaded, these variables will be set: + +@example +foo2 foo3 foo6 foo7 ; `load' +@end example + +And if @file{foo.el} is loaded uncompiled, these variables will +be set: + +@example +foo4 foo5 foo6 foo7 ; `eval' +@end example + +If these seven @code{eval-when}s had been, say, inside a @code{defun}, +then the first three would have been equivalent to @code{nil} and the +last four would have been equivalent to the corresponding @code{setq}s. + +Note that @code{(eval-when (load eval) @dots{})} is equivalent +to @code{(progn @dots{})} in all contexts. The compiler treats +certain top-level forms, like @code{defmacro} (sort-of) and +@code{require}, as if they were wrapped in @code{(eval-when +(compile load eval) @dots{})}. +@end defspec + +Emacs 19 includes two special forms related to @code{eval-when}. +One of these, @code{eval-when-compile}, is not quite equivalent to +any @code{eval-when} construct and is described below. This package +defines a version of @code{eval-when-compile} for the benefit of +Emacs 18 users. + +The other form, @code{(eval-and-compile @dots{})}, is exactly +equivalent to @samp{(eval-when (compile load eval) @dots{})} and +so is not itself defined by this package. + +@defspec eval-when-compile forms... +The @var{forms} are evaluated at compile-time; at execution time, +this form acts like a quoted constant of the resulting value. Used +at top-level, @code{eval-when-compile} is just like @samp{eval-when +(compile eval)}. In other contexts, @code{eval-when-compile} +allows code to be evaluated once at compile-time for efficiency +or other reasons. + +This form is similar to the @samp{#.} syntax of true Common Lisp. +@end defspec + +@defspec load-time-value form +The @var{form} is evaluated at load-time; at execution time, +this form acts like a quoted constant of the resulting value. + +Early Common Lisp had a @samp{#,} syntax that was similar to +this, but ANSI Common Lisp replaced it with @code{load-time-value} +and gave it more well-defined semantics. + +In a compiled file, @code{load-time-value} arranges for @var{form} +to be evaluated when the @file{.elc} file is loaded and then used +as if it were a quoted constant. In code compiled by +@code{byte-compile} rather than @code{byte-compile-file}, the +effect is identical to @code{eval-when-compile}. In uncompiled +code, both @code{eval-when-compile} and @code{load-time-value} +act exactly like @code{progn}. + +@example +(defun report () + (insert "This function was executed on: " + (current-time-string) + ", compiled on: " + (eval-when-compile (current-time-string)) + ;; or '#.(current-time-string) in real Common Lisp + ", and loaded on: " + (load-time-value (current-time-string)))) +@end example + +@noindent +Byte-compiled, the above defun will result in the following code +(or its compiled equivalent, of course) in the @file{.elc} file: + +@example +(setq --temp-- (current-time-string)) +(defun report () + (insert "This function was executed on: " + (current-time-string) + ", compiled on: " + '"Wed Jun 23 18:33:43 1993" + ", and loaded on: " + --temp--)) +@end example +@end defspec + +@node Function Aliases, , Time of Evaluation, Program Structure +@section Function Aliases + +@noindent +This section describes a feature from GNU Emacs 19 which this +package makes available in other versions of Emacs. + +@defun defalias symbol function +This function sets @var{symbol}'s function cell to @var{function}. +It is equivalent to @code{fset}, except that in GNU Emacs 19 it also +records the setting in @code{load-history} so that it can be undone +by a later @code{unload-feature}. + +In other versions of Emacs, @code{defalias} is a synonym for +@code{fset}. +@end defun + +@node Predicates, Control Structure, Program Structure, Top +@chapter Predicates + +@noindent +This section describes functions for testing whether various +facts are true or false. + +@menu +* Type Predicates:: `typep', `deftype', and `coerce' +* Equality Predicates:: `eql' and `equalp' +@end menu + +@node Type Predicates, Equality Predicates, Predicates, Predicates +@section Type Predicates + +@noindent +The @dfn{CL} package defines a version of the Common Lisp @code{typep} +predicate. + +@defun typep object type +Check if @var{object} is of type @var{type}, where @var{type} is a +(quoted) type name of the sort used by Common Lisp. For example, +@code{(typep foo 'integer)} is equivalent to @code{(integerp foo)}. +@end defun + +The @var{type} argument to the above function is either a symbol +or a list beginning with a symbol. + +@itemize @bullet +@item +If the type name is a symbol, Emacs appends @samp{-p} to the +symbol name to form the name of a predicate function for testing +the type. (Built-in predicates whose names end in @samp{p} rather +than @samp{-p} are used when appropriate.) + +@item +The type symbol @code{t} stands for the union of all types. +@code{(typep @var{object} t)} is always true. Likewise, the +type symbol @code{nil} stands for nothing at all, and +@code{(typep @var{object} nil)} is always false. + +@item +The type symbol @code{null} represents the symbol @code{nil}. +Thus @code{(typep @var{object} 'null)} is equivalent to +@code{(null @var{object})}. + +@item +The type symbol @code{real} is a synonym for @code{number}, and +@code{fixnum} is a synonym for @code{integer}. + +@item +The type symbols @code{character} and @code{string-char} match +integers in the range from 0 to 255. + +@item +The type symbol @code{float} uses the @code{floatp-safe} predicate +defined by this package rather than @code{floatp}, so it will work +correctly even in Emacs versions without floating-point support. + +@item +The type list @code{(integer @var{low} @var{high})} represents all +integers between @var{low} and @var{high}, inclusive. Either bound +may be a list of a single integer to specify an exclusive limit, +or a @code{*} to specify no limit. The type @code{(integer * *)} +is thus equivalent to @code{integer}. + +@item +Likewise, lists beginning with @code{float}, @code{real}, or +@code{number} represent numbers of that type falling in a particular +range. + +@item +Lists beginning with @code{and}, @code{or}, and @code{not} form +combinations of types. For example, @code{(or integer (float 0 *))} +represents all objects that are integers or non-negative floats. + +@item +Lists beginning with @code{member} or @code{member*} represent +objects @code{eql} to any of the following values. For example, +@code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)}, +and @code{(member nil)} is equivalent to @code{null}. + +@item +Lists of the form @code{(satisfies @var{predicate})} represent +all objects for which @var{predicate} returns true when called +with that object as an argument. +@end itemize + +The following function and macro (not technically predicates) are +related to @code{typep}. + +@defun coerce object type +This function attempts to convert @var{object} to the specified +@var{type}. If @var{object} is already of that type as determined by +@code{typep}, it is simply returned. Otherwise, certain types of +conversions will be made: If @var{type} is any sequence type +(@code{string}, @code{list}, etc.) then @var{object} will be +converted to that type if possible. If @var{type} is +@code{character}, then strings of length one and symbols with +one-character names can be coerced. If @var{type} is @code{float}, +then integers can be coerced in versions of Emacs that support +floats. In all other circumstances, @code{coerce} signals an +error. +@end defun + +@defspec deftype name arglist forms... +This macro defines a new type called @var{name}. It is similar +to @code{defmacro} in many ways; when @var{name} is encountered +as a type name, the body @var{forms} are evaluated and should +return a type specifier that is equivalent to the type. The +@var{arglist} is a Common Lisp argument list of the sort accepted +by @code{defmacro*}. The type specifier @samp{(@var{name} @var{args}...)} +is expanded by calling the expander with those arguments; the type +symbol @samp{@var{name}} is expanded by calling the expander with +no arguments. The @var{arglist} is processed the same as for +@code{defmacro*} except that optional arguments without explicit +defaults use @code{*} instead of @code{nil} as the ``default'' +default. Some examples: + +@example +(deftype null () '(satisfies null)) ; predefined +(deftype list () '(or null cons)) ; predefined +(deftype unsigned-byte (&optional bits) + (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits))))) +(unsigned-byte 8) @equiv{} (integer 0 255) +(unsigned-byte) @equiv{} (integer 0 *) +unsigned-byte @equiv{} (integer 0 *) +@end example + +@noindent +The last example shows how the Common Lisp @code{unsigned-byte} +type specifier could be implemented if desired; this package does +not implement @code{unsigned-byte} by default. +@end defspec + +The @code{typecase} and @code{check-type} macros also use type +names. @xref{Conditionals}. @xref{Assertions}. The @code{map}, +@code{concatenate}, and @code{merge} functions take type-name +arguments to specify the type of sequence to return. @xref{Sequences}. + +@node Equality Predicates, , Type Predicates, Predicates +@section Equality Predicates + +@noindent +This package defines two Common Lisp predicates, @code{eql} and +@code{equalp}. + +@defun eql a b +This function is almost the same as @code{eq}, except that if @var{a} +and @var{b} are numbers of the same type, it compares them for numeric +equality (as if by @code{equal} instead of @code{eq}). This makes a +difference only for versions of Emacs that are compiled with +floating-point support, such as Emacs 19. Emacs floats are allocated +objects just like cons cells, which means that @code{(eq 3.0 3.0)} +will not necessarily be true---if the two @code{3.0}s were allocated +separately, the pointers will be different even though the numbers are +the same. But @code{(eql 3.0 3.0)} will always be true. + +The types of the arguments must match, so @code{(eql 3 3.0)} is +still false. + +Note that Emacs integers are ``direct'' rather than allocated, which +basically means @code{(eq 3 3)} will always be true. Thus @code{eq} +and @code{eql} behave differently only if floating-point numbers are +involved, and are indistinguishable on Emacs versions that don't +support floats. + +There is a slight inconsistency with Common Lisp in the treatment of +positive and negative zeros. Some machines, notably those with IEEE +standard arithmetic, represent @code{+0} and @code{-0} as distinct +values. Normally this doesn't matter because the standard specifies +that @code{(= 0.0 -0.0)} should always be true, and this is indeed +what Emacs Lisp and Common Lisp do. But the Common Lisp standard +states that @code{(eql 0.0 -0.0)} and @code{(equal 0.0 -0.0)} should +be false on IEEE-like machines; Emacs Lisp does not do this, and in +fact the only known way to distinguish between the two zeros in Emacs +Lisp is to @code{format} them and check for a minus sign. +@end defun + +@defun equalp a b +This function is a more flexible version of @code{equal}. In +particular, it compares strings case-insensitively, and it compares +numbers without regard to type (so that @code{(equalp 3 3.0)} is +true). Vectors and conses are compared recursively. All other +objects are compared as if by @code{equal}. + +This function differs from Common Lisp @code{equalp} in several +respects. First, Common Lisp's @code{equalp} also compares +@emph{characters} case-insensitively, which would be impractical +in this package since Emacs does not distinguish between integers +and characters. In keeping with the idea that strings are less +vector-like in Emacs Lisp, this package's @code{equalp} also will +not compare strings against vectors of integers. Finally, Common +Lisp's @code{equalp} compares hash tables without regard to +ordering, whereas this package simply compares hash tables in +terms of their underlying structure (which means vectors for Lucid +Emacs 19 hash tables, or lists for other hash tables). +@end defun + +Also note that the Common Lisp functions @code{member} and @code{assoc} +use @code{eql} to compare elements, whereas Emacs Lisp follows the +MacLisp tradition and uses @code{equal} for these two functions. +In Emacs, use @code{member*} and @code{assoc*} to get functions +which use @code{eql} for comparisons. + +@node Control Structure, Macros, Predicates, Top +@chapter Control Structure + +@noindent +The features described in the following sections implement +various advanced control structures, including the powerful +@code{setf} facility and a number of looping and conditional +constructs. + +@menu +* Assignment:: The `psetq' form +* Generalized Variables:: `setf', `incf', `push', etc. +* Variable Bindings:: `progv', `lexical-let', `flet', `macrolet' +* Conditionals:: `case', `typecase' +* Blocks and Exits:: `block', `return', `return-from' +* Iteration:: `do', `dotimes', `dolist', `do-symbols' +* Loop Facility:: The Common Lisp `loop' macro +* Multiple Values:: `values', `multiple-value-bind', etc. +@end menu + +@node Assignment, Generalized Variables, Control Structure, Control Structure +@section Assignment + +@noindent +The @code{psetq} form is just like @code{setq}, except that multiple +assignments are done in parallel rather than sequentially. + +@defspec psetq [symbol form]@dots{} +This special form (actually a macro) is used to assign to several +variables simultaneously. Given only one @var{symbol} and @var{form}, +it has the same effect as @code{setq}. Given several @var{symbol} +and @var{form} pairs, it evaluates all the @var{form}s in advance +and then stores the corresponding variables afterwards. + +@example +(setq x 2 y 3) +(setq x (+ x y) y (* x y)) +x + @result{} 5 +y ; @r{@code{y} was computed after @code{x} was set.} + @result{} 15 +(setq x 2 y 3) +(psetq x (+ x y) y (* x y)) +x + @result{} 5 +y ; @r{@code{y} was computed before @code{x} was set.} + @result{} 6 +@end example + +The simplest use of @code{psetq} is @code{(psetq x y y x)}, which +exchanges the values of two variables. (The @code{rotatef} form +provides an even more convenient way to swap two variables; +@pxref{Modify Macros}.) + +@code{psetq} always returns @code{nil}. +@end defspec + +@node Generalized Variables, Variable Bindings, Assignment, Control Structure +@section Generalized Variables + +@noindent +A ``generalized variable'' or ``place form'' is one of the many places +in Lisp memory where values can be stored. The simplest place form is +a regular Lisp variable. But the cars and cdrs of lists, elements +of arrays, properties of symbols, and many other locations are also +places where Lisp values are stored. + +The @code{setf} form is like @code{setq}, except that it accepts +arbitrary place forms on the left side rather than just +symbols. For example, @code{(setf (car a) b)} sets the car of +@code{a} to @code{b}, doing the same operation as @code{(setcar a b)} +but without having to remember two separate functions for setting +and accessing every type of place. + +Generalized variables are analogous to ``lvalues'' in the C +language, where @samp{x = a[i]} gets an element from an array +and @samp{a[i] = x} stores an element using the same notation. +Just as certain forms like @code{a[i]} can be lvalues in C, there +is a set of forms that can be generalized variables in Lisp. + +@menu +* Basic Setf:: `setf' and place forms +* Modify Macros:: `incf', `push', `rotatef', `letf', `callf', etc. +* Customizing Setf:: `define-modify-macro', `defsetf', `define-setf-method' +@end menu + +@node Basic Setf, Modify Macros, Generalized Variables, Generalized Variables +@subsection Basic Setf + +@noindent +The @code{setf} macro is the most basic way to operate on generalized +variables. + +@defspec setf [place form]@dots{} +This macro evaluates @var{form} and stores it in @var{place}, which +must be a valid generalized variable form. If there are several +@var{place} and @var{form} pairs, the assignments are done sequentially +just as with @code{setq}. @code{setf} returns the value of the last +@var{form}. + +The following Lisp forms will work as generalized variables, and +so may legally appear in the @var{place} argument of @code{setf}: + +@itemize @bullet +@item +A symbol naming a variable. In other words, @code{(setf x y)} is +exactly equivalent to @code{(setq x y)}, and @code{setq} itself is +strictly speaking redundant now that @code{setf} exists. Many +programmers continue to prefer @code{setq} for setting simple +variables, though, purely for stylistic or historical reasons. +The macro @code{(setf x y)} actually expands to @code{(setq x y)}, +so there is no performance penalty for using it in compiled code. + +@item +A call to any of the following Lisp functions: + +@smallexample +car cdr caar .. cddddr +nth rest first .. tenth +aref elt nthcdr +symbol-function symbol-value symbol-plist +get get* getf +gethash subseq +@end smallexample + +@noindent +Note that for @code{nthcdr} and @code{getf}, the list argument +of the function must itself be a valid @var{place} form. For +example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself +to 7. Note that @code{push} and @code{pop} on an @code{nthcdr} +place can be used to insert or delete at any position in a list. +The use of @code{nthcdr} as a @var{place} form is an extension +to standard Common Lisp. + +@item +The following Emacs-specific functions are also @code{setf}-able. +(Some of these are defined only in Emacs 19 or only in Lucid Emacs.) + +@smallexample +buffer-file-name marker-position +buffer-modified-p match-data +buffer-name mouse-position +buffer-string overlay-end +buffer-substring overlay-get +current-buffer overlay-start +current-case-table point +current-column point-marker +current-global-map point-max +current-input-mode point-min +current-local-map process-buffer +current-window-configuration process-filter +default-file-modes process-sentinel +default-value read-mouse-position +documentation-property screen-height +extent-data screen-menubar +extent-end-position screen-width +extent-start-position selected-window +face-background selected-screen +face-background-pixmap selected-frame +face-font standard-case-table +face-foreground syntax-table +face-underline-p window-buffer +file-modes window-dedicated-p +frame-height window-display-table +frame-parameters window-height +frame-visible-p window-hscroll +frame-width window-point +get-register window-start +getenv window-width +global-key-binding x-get-cut-buffer +keymap-parent x-get-cutbuffer +local-key-binding x-get-secondary-selection +mark x-get-selection +mark-marker +@end smallexample + +Most of these have directly corresponding ``set'' functions, like +@code{use-local-map} for @code{current-local-map}, or @code{goto-char} +for @code{point}. A few, like @code{point-min}, expand to longer +sequences of code when they are @code{setf}'d (@code{(narrow-to-region +x (point-max))} in this case). + +@item +A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])}, +where @var{subplace} is itself a legal generalized variable whose +current value is a string, and where the value stored is also a +string. The new string is spliced into the specified part of the +destination string. For example: + +@example +(setq a (list "hello" "world")) + @result{} ("hello" "world") +(cadr a) + @result{} "world" +(substring (cadr a) 2 4) + @result{} "rl" +(setf (substring (cadr a) 2 4) "o") + @result{} "o" +(cadr a) + @result{} "wood" +a + @result{} ("hello" "wood") +@end example + +The generalized variable @code{buffer-substring}, listed above, +also works in this way by replacing a portion of the current buffer. + +@item +A call of the form @code{(apply '@var{func} @dots{})} or +@code{(apply (function @var{func}) @dots{})}, where @var{func} +is a @code{setf}-able function whose store function is ``suitable'' +in the sense described in Steele's book; since none of the standard +Emacs place functions are suitable in this sense, this feature is +only interesting when used with places you define yourself with +@code{define-setf-method} or the long form of @code{defsetf}. + +@item +A macro call, in which case the macro is expanded and @code{setf} +is applied to the resulting form. + +@item +Any form for which a @code{defsetf} or @code{define-setf-method} +has been made. +@end itemize + +Using any forms other than these in the @var{place} argument to +@code{setf} will signal an error. + +The @code{setf} macro takes care to evaluate all subforms in +the proper left-to-right order; for example, + +@example +(setf (aref vec (incf i)) i) +@end example + +@noindent +looks like it will evaluate @code{(incf i)} exactly once, before the +following access to @code{i}; the @code{setf} expander will insert +temporary variables as necessary to ensure that it does in fact work +this way no matter what setf-method is defined for @code{aref}. +(In this case, @code{aset} would be used and no such steps would +be necessary since @code{aset} takes its arguments in a convenient +order.) + +However, if the @var{place} form is a macro which explicitly +evaluates its arguments in an unusual order, this unusual order +will be preserved. Adapting an example from Steele, given + +@example +(defmacro wrong-order (x y) (list 'aref y x)) +@end example + +@noindent +the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will +evaluate @var{b} first, then @var{a}, just as in an actual call +to @code{wrong-order}. +@end defspec + +@node Modify Macros, Customizing Setf, Basic Setf, Generalized Variables +@subsection Modify Macros + +@noindent +This package defines a number of other macros besides @code{setf} +that operate on generalized variables. Many are interesting and +useful even when the @var{place} is just a variable name. + +@defspec psetf [place form]@dots{} +This macro is to @code{setf} what @code{psetq} is to @code{setq}: +When several @var{place}s and @var{form}s are involved, the +assignments take place in parallel rather than sequentially. +Specifically, all subforms are evaluated from left to right, then +all the assignments are done (in an undefined order). +@end defspec + +@defspec incf place &optional x +This macro increments the number stored in @var{place} by one, or +by @var{x} if specified. The incremented value is returned. For +example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and +@code{(incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}. + +Once again, care is taken to preserve the ``apparent'' order of +evaluation. For example, + +@example +(incf (aref vec (incf i))) +@end example + +@noindent +appears to increment @code{i} once, then increment the element of +@code{vec} addressed by @code{i}; this is indeed exactly what it +does, which means the above form is @emph{not} equivalent to the +``obvious'' expansion, + +@example +(setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong! +@end example + +@noindent +but rather to something more like + +@example +(let ((temp (incf i))) + (setf (aref vec temp) (1+ (aref vec temp)))) +@end example + +@noindent +Again, all of this is taken care of automatically by @code{incf} and +the other generalized-variable macros. + +As a more Emacs-specific example of @code{incf}, the expression +@code{(incf (point) @var{n})} is essentially equivalent to +@code{(forward-char @var{n})}. +@end defspec + +@defspec decf place &optional x +This macro decrements the number stored in @var{place} by one, or +by @var{x} if specified. +@end defspec + +@defspec pop place +This macro removes and returns the first element of the list stored +in @var{place}. It is analogous to @code{(prog1 (car @var{place}) +(setf @var{place} (cdr @var{place})))}, except that it takes care +to evaluate all subforms only once. +@end defspec + +@defspec push x place +This macro inserts @var{x} at the front of the list stored in +@var{place}. It is analogous to @code{(setf @var{place} (cons +@var{x} @var{place}))}, except for evaluation of the subforms. +@end defspec + +@defspec pushnew x place @t{&key :test :test-not :key} +This macro inserts @var{x} at the front of the list stored in +@var{place}, but only if @var{x} was not @code{eql} to any +existing element of the list. The optional keyword arguments +are interpreted in the same way as for @code{adjoin}. +@xref{Lists as Sets}. +@end defspec + +@defspec shiftf place@dots{} newvalue +This macro shifts the @var{place}s left by one, shifting in the +value of @var{newvalue} (which may be any Lisp expression, not just +a generalized variable), and returning the value shifted out of +the first @var{place}. Thus, @code{(shiftf @var{a} @var{b} @var{c} +@var{d})} is equivalent to + +@example +(prog1 + @var{a} + (psetf @var{a} @var{b} + @var{b} @var{c} + @var{c} @var{d})) +@end example + +@noindent +except that the subforms of @var{a}, @var{b}, and @var{c} are actually +evaluated only once each and in the apparent order. +@end defspec + +@defspec rotatef place@dots{} +This macro rotates the @var{place}s left by one in circular fashion. +Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to + +@example +(psetf @var{a} @var{b} + @var{b} @var{c} + @var{c} @var{d} + @var{d} @var{a}) +@end example + +@noindent +except for the evaluation of subforms. @code{rotatef} always +returns @code{nil}. Note that @code{(rotatef @var{a} @var{b})} +conveniently exchanges @var{a} and @var{b}. +@end defspec + +The following macros were invented for this package; they have no +analogues in Common Lisp. + +@defspec letf (bindings@dots{}) forms@dots{} +This macro is analogous to @code{let}, but for generalized variables +rather than just symbols. Each @var{binding} should be of the form +@code{(@var{place} @var{value})}; the original contents of the +@var{place}s are saved, the @var{value}s are stored in them, and +then the body @var{form}s are executed. Afterwards, the @var{places} +are set back to their original saved contents. This cleanup happens +even if the @var{form}s exit irregularly due to a @code{throw} or an +error. + +For example, + +@example +(letf (((point) (point-min)) + (a 17)) + ...) +@end example + +@noindent +moves ``point'' in the current buffer to the beginning of the buffer, +and also binds @code{a} to 17 (as if by a normal @code{let}, since +@code{a} is just a regular variable). After the body exits, @code{a} +is set back to its original value and point is moved back to its +original position. + +Note that @code{letf} on @code{(point)} is not quite like a +@code{save-excursion}, as the latter effectively saves a marker +which tracks insertions and deletions in the buffer. Actually, +a @code{letf} of @code{(point-marker)} is much closer to this +behavior. (@code{point} and @code{point-marker} are equivalent +as @code{setf} places; each will accept either an integer or a +marker as the stored value.) + +Since generalized variables look like lists, @code{let}'s shorthand +of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would +be ambiguous in @code{letf} and is not allowed. + +However, a @var{binding} specifier may be a one-element list +@samp{(@var{place})}, which is similar to @samp{(@var{place} +@var{place})}. In other words, the @var{place} is not disturbed +on entry to the body, and the only effect of the @code{letf} is +to restore the original value of @var{place} afterwards. (The +redundant access-and-store suggested by the @code{(@var{place} +@var{place})} example does not actually occur.) + +In most cases, the @var{place} must have a well-defined value on +entry to the @code{letf} form. The only exceptions are plain +variables and calls to @code{symbol-value} and @code{symbol-function}. +If the symbol is not bound on entry, it is simply made unbound by +@code{makunbound} or @code{fmakunbound} on exit. +@end defspec + +@defspec letf* (bindings@dots{}) forms@dots{} +This macro is to @code{letf} what @code{let*} is to @code{let}: +It does the bindings in sequential rather than parallel order. +@end defspec + +@defspec callf @var{function} @var{place} @var{args}@dots{} +This is the ``generic'' modify macro. It calls @var{function}, +which should be an unquoted function name, macro name, or lambda. +It passes @var{place} and @var{args} as arguments, and assigns the +result back to @var{place}. For example, @code{(incf @var{place} +@var{n})} is the same as @code{(callf + @var{place} @var{n})}. +Some more examples: + +@example +(callf abs my-number) +(callf concat (buffer-name) "<" (int-to-string n) ">") +(callf union happy-people (list joe bob) :test 'same-person) +@end example + +@xref{Customizing Setf}, for @code{define-modify-macro}, a way +to create even more concise notations for modify macros. Note +again that @code{callf} is an extension to standard Common Lisp. +@end defspec + +@defspec callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{} +This macro is like @code{callf}, except that @var{place} is +the @emph{second} argument of @var{function} rather than the +first. For example, @code{(push @var{x} @var{place})} is +equivalent to @code{(callf2 cons @var{x} @var{place})}. +@end defspec + +The @code{callf} and @code{callf2} macros serve as building +blocks for other macros like @code{incf}, @code{pushnew}, and +@code{define-modify-macro}. The @code{letf} and @code{letf*} +macros are used in the processing of symbol macros; +@pxref{Macro Bindings}. + +@node Customizing Setf, , Modify Macros, Generalized Variables +@subsection Customizing Setf + +@noindent +Common Lisp defines three macros, @code{define-modify-macro}, +@code{defsetf}, and @code{define-setf-method}, that allow the +user to extend generalized variables in various ways. + +@defspec define-modify-macro name arglist function [doc-string] +This macro defines a ``read-modify-write'' macro similar to +@code{incf} and @code{decf}. The macro @var{name} is defined +to take a @var{place} argument followed by additional arguments +described by @var{arglist}. The call + +@example +(@var{name} @var{place} @var{args}...) +@end example + +@noindent +will be expanded to + +@example +(callf @var{func} @var{place} @var{args}...) +@end example + +@noindent +which in turn is roughly equivalent to + +@example +(setf @var{place} (@var{func} @var{place} @var{args}...)) +@end example + +For example: + +@example +(define-modify-macro incf (&optional (n 1)) +) +(define-modify-macro concatf (&rest args) concat) +@end example + +Note that @code{&key} is not allowed in @var{arglist}, but +@code{&rest} is sufficient to pass keywords on to the function. + +Most of the modify macros defined by Common Lisp do not exactly +follow the pattern of @code{define-modify-macro}. For example, +@code{push} takes its arguments in the wrong order, and @code{pop} +is completely irregular. You can define these macros ``by hand'' +using @code{get-setf-method}, or consult the source file +@file{cl-macs.el} to see how to use the internal @code{setf} +building blocks. +@end defspec + +@defspec defsetf access-fn update-fn +This is the simpler of two @code{defsetf} forms. Where +@var{access-fn} is the name of a function which accesses a place, +this declares @var{update-fn} to be the corresponding store +function. From now on, + +@example +(setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value}) +@end example + +@noindent +will be expanded to + +@example +(@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value}) +@end example + +@noindent +The @var{update-fn} is required to be either a true function, or +a macro which evaluates its arguments in a function-like way. Also, +the @var{update-fn} is expected to return @var{value} as its result. +Otherwise, the above expansion would not obey the rules for the way +@code{setf} is supposed to behave. + +As a special (non-Common-Lisp) extension, a third argument of @code{t} +to @code{defsetf} says that the @code{update-fn}'s return value is +not suitable, so that the above @code{setf} should be expanded to +something more like + +@example +(let ((temp @var{value})) + (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp) + temp) +@end example + +Some examples of the use of @code{defsetf}, drawn from the standard +suite of setf methods, are: + +@example +(defsetf car setcar) +(defsetf symbol-value set) +(defsetf buffer-name rename-buffer t) +@end example +@end defspec + +@defspec defsetf access-fn arglist (store-var) forms@dots{} +This is the second, more complex, form of @code{defsetf}. It is +rather like @code{defmacro} except for the additional @var{store-var} +argument. The @var{forms} should return a Lisp form which stores +the value of @var{store-var} into the generalized variable formed +by a call to @var{access-fn} with arguments described by @var{arglist}. +The @var{forms} may begin with a string which documents the @code{setf} +method (analogous to the doc string that appears at the front of a +function). + +For example, the simple form of @code{defsetf} is shorthand for + +@example +(defsetf @var{access-fn} (&rest args) (store) + (append '(@var{update-fn}) args (list store))) +@end example + +The Lisp form that is returned can access the arguments from +@var{arglist} and @var{store-var} in an unrestricted fashion; +macros like @code{setf} and @code{incf} which invoke this +setf-method will insert temporary variables as needed to make +sure the apparent order of evaluation is preserved. + +Another example drawn from the standard package: + +@example +(defsetf nth (n x) (store) + (list 'setcar (list 'nthcdr n x) store)) +@end example +@end defspec + +@defspec define-setf-method access-fn arglist forms@dots{} +This is the most general way to create new place forms. When +a @code{setf} to @var{access-fn} with arguments described by +@var{arglist} is expanded, the @var{forms} are evaluated and +must return a list of five items: + +@enumerate +@item +A list of @dfn{temporary variables}. + +@item +A list of @dfn{value forms} corresponding to the temporary variables +above. The temporary variables will be bound to these value forms +as the first step of any operation on the generalized variable. + +@item +A list of exactly one @dfn{store variable} (generally obtained +from a call to @code{gensym}). + +@item +A Lisp form which stores the contents of the store variable into +the generalized variable, assuming the temporaries have been +bound as described above. + +@item +A Lisp form which accesses the contents of the generalized variable, +assuming the temporaries have been bound. +@end enumerate + +This is exactly like the Common Lisp macro of the same name, +except that the method returns a list of five values rather +than the five values themselves, since Emacs Lisp does not +support Common Lisp's notion of multiple return values. + +Once again, the @var{forms} may begin with a documentation string. + +A setf-method should be maximally conservative with regard to +temporary variables. In the setf-methods generated by +@code{defsetf}, the second return value is simply the list of +arguments in the place form, and the first return value is a +list of a corresponding number of temporary variables generated +by @code{gensym}. Macros like @code{setf} and @code{incf} which +use this setf-method will optimize away most temporaries that +turn out to be unnecessary, so there is little reason for the +setf-method itself to optimize. +@end defspec + +@defun get-setf-method place &optional env +This function returns the setf-method for @var{place}, by +invoking the definition previously recorded by @code{defsetf} +or @code{define-setf-method}. The result is a list of five +values as described above. You can use this function to build +your own @code{incf}-like modify macros. (Actually, it is +better to use the internal functions @code{cl-setf-do-modify} +and @code{cl-setf-do-store}, which are a bit easier to use and +which also do a number of optimizations; consult the source +code for the @code{incf} function for a simple example.) + +The argument @var{env} specifies the ``environment'' to be +passed on to @code{macroexpand} if @code{get-setf-method} should +need to expand a macro in @var{place}. It should come from +an @code{&environment} argument to the macro or setf-method +that called @code{get-setf-method}. + +See also the source code for the setf-methods for @code{apply} +and @code{substring}, each of which works by calling +@code{get-setf-method} on a simpler case, then massaging +the result in various ways. +@end defun + +Modern Common Lisp defines a second, independent way to specify +the @code{setf} behavior of a function, namely ``@code{setf} +functions'' whose names are lists @code{(setf @var{name})} +rather than symbols. For example, @code{(defun (setf foo) @dots{})} +defines the function that is used when @code{setf} is applied to +@code{foo}. This package does not currently support @code{setf} +functions. In particular, it is a compile-time error to use +@code{setf} on a form which has not already been @code{defsetf}'d +or otherwise declared; in newer Common Lisps, this would not be +an error since the function @code{(setf @var{func})} might be +defined later. + +@iftex +@secno=4 +@end iftex + +@node Variable Bindings, Conditionals, Generalized Variables, Control Structure +@section Variable Bindings + +@noindent +These Lisp forms make bindings to variables and function names, +analogous to Lisp's built-in @code{let} form. + +@xref{Modify Macros}, for the @code{letf} and @code{letf*} forms which +are also related to variable bindings. + +@menu +* Dynamic Bindings:: The `progv' form +* Lexical Bindings:: `lexical-let' and lexical closures +* Function Bindings:: `flet' and `labels' +* Macro Bindings:: `macrolet' and `symbol-macrolet' +@end menu + +@node Dynamic Bindings, Lexical Bindings, Variable Bindings, Variable Bindings +@subsection Dynamic Bindings + +@noindent +The standard @code{let} form binds variables whose names are known +at compile-time. The @code{progv} form provides an easy way to +bind variables whose names are computed at run-time. + +@defspec progv symbols values forms@dots{} +This form establishes @code{let}-style variable bindings on a +set of variables computed at run-time. The expressions +@var{symbols} and @var{values} are evaluated, and must return lists +of symbols and values, respectively. The symbols are bound to the +corresponding values for the duration of the body @var{form}s. +If @var{values} is shorter than @var{symbols}, the last few symbols +are made unbound (as if by @code{makunbound}) inside the body. +If @var{symbols} is shorter than @var{values}, the excess values +are ignored. +@end defspec + +@node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings +@subsection Lexical Bindings + +@noindent +The @dfn{CL} package defines the following macro which +more closely follows the Common Lisp @code{let} form: + +@defspec lexical-let (bindings@dots{}) forms@dots{} +This form is exactly like @code{let} except that the bindings it +establishes are purely lexical. Lexical bindings are similar to +local variables in a language like C: Only the code physically +within the body of the @code{lexical-let} (after macro expansion) +may refer to the bound variables. + +@example +(setq a 5) +(defun foo (b) (+ a b)) +(let ((a 2)) (foo a)) + @result{} 4 +(lexical-let ((a 2)) (foo a)) + @result{} 7 +@end example + +@noindent +In this example, a regular @code{let} binding of @code{a} actually +makes a temporary change to the global variable @code{a}, so @code{foo} +is able to see the binding of @code{a} to 2. But @code{lexical-let} +actually creates a distinct local variable @code{a} for use within its +body, without any effect on the global variable of the same name. + +The most important use of lexical bindings is to create @dfn{closures}. +A closure is a function object that refers to an outside lexical +variable. For example: + +@example +(defun make-adder (n) + (lexical-let ((n n)) + (function (lambda (m) (+ n m))))) +(setq add17 (make-adder 17)) +(funcall add17 4) + @result{} 21 +@end example + +@noindent +The call @code{(make-adder 17)} returns a function object which adds +17 to its argument. If @code{let} had been used instead of +@code{lexical-let}, the function object would have referred to the +global @code{n}, which would have been bound to 17 only during the +call to @code{make-adder} itself. + +@example +(defun make-counter () + (lexical-let ((n 0)) + (function* (lambda (&optional (m 1)) (incf n m))))) +(setq count-1 (make-counter)) +(funcall count-1 3) + @result{} 3 +(funcall count-1 14) + @result{} 17 +(setq count-2 (make-counter)) +(funcall count-2 5) + @result{} 5 +(funcall count-1 2) + @result{} 19 +(funcall count-2) + @result{} 6 +@end example + +@noindent +Here we see that each call to @code{make-counter} creates a distinct +local variable @code{n}, which serves as a private counter for the +function object that is returned. + +Closed-over lexical variables persist until the last reference to +them goes away, just like all other Lisp objects. For example, +@code{count-2} refers to a function object which refers to an +instance of the variable @code{n}; this is the only reference +to that variable, so after @code{(setq count-2 nil)} the garbage +collector would be able to delete this instance of @code{n}. +Of course, if a @code{lexical-let} does not actually create any +closures, then the lexical variables are free as soon as the +@code{lexical-let} returns. + +Many closures are used only during the extent of the bindings they +refer to; these are known as ``downward funargs'' in Lisp parlance. +When a closure is used in this way, regular Emacs Lisp dynamic +bindings suffice and will be more efficient than @code{lexical-let} +closures: + +@example +(defun add-to-list (x list) + (mapcar (function (lambda (y) (+ x y))) list)) +(add-to-list 7 '(1 2 5)) + @result{} (8 9 12) +@end example + +@noindent +Since this lambda is only used while @code{x} is still bound, +it is not necessary to make a true closure out of it. + +You can use @code{defun} or @code{flet} inside a @code{lexical-let} +to create a named closure. If several closures are created in the +body of a single @code{lexical-let}, they all close over the same +instance of the lexical variable. + +The @code{lexical-let} form is an extension to Common Lisp. In +true Common Lisp, all bindings are lexical unless declared otherwise. +@end defspec + +@defspec lexical-let* (bindings@dots{}) forms@dots{} +This form is just like @code{lexical-let}, except that the bindings +are made sequentially in the manner of @code{let*}. +@end defspec + +@node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings +@subsection Function Bindings + +@noindent +These forms make @code{let}-like bindings to functions instead +of variables. + +@defspec flet (bindings@dots{}) forms@dots{} +This form establishes @code{let}-style bindings on the function +cells of symbols rather than on the value cells. Each @var{binding} +must be a list of the form @samp{(@var{name} @var{arglist} +@var{forms}@dots{})}, which defines a function exactly as if +it were a @code{defun*} form. The function @var{name} is defined +accordingly for the duration of the body of the @code{flet}; then +the old function definition, or lack thereof, is restored. + +While @code{flet} in Common Lisp establishes a lexical binding of +@var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The +result is that @code{flet} affects indirect calls to a function as +well as calls directly inside the @code{flet} form itself. + +You can use @code{flet} to disable or modify the behavior of a +function in a temporary fashion. This will even work on Emacs +primitives, although note that some calls to primitive functions +internal to Emacs are made without going through the symbol's +function cell, and so will not be affected by @code{flet}. For +example, + +@example +(flet ((message (&rest args) (push args saved-msgs))) + (do-something)) +@end example + +This code attempts to replace the built-in function @code{message} +with a function that simply saves the messages in a list rather +than displaying them. The original definition of @code{message} +will be restored after @code{do-something} exits. This code will +work fine on messages generated by other Lisp code, but messages +generated directly inside Emacs will not be caught since they make +direct C-language calls to the message routines rather than going +through the Lisp @code{message} function. + +Functions defined by @code{flet} may use the full Common Lisp +argument notation supported by @code{defun*}; also, the function +body is enclosed in an implicit block as if by @code{defun*}. +@xref{Program Structure}. +@end defspec + +@defspec labels (bindings@dots{}) forms@dots{} +The @code{labels} form is like @code{flet}, except that it +makes lexical bindings of the function names rather than +dynamic bindings. (In true Common Lisp, both @code{flet} and +@code{labels} make lexical bindings of slightly different sorts; +since Emacs Lisp is dynamically bound by default, it seemed +more appropriate for @code{flet} also to use dynamic binding. +The @code{labels} form, with its lexical binding, is fully +compatible with Common Lisp.) + +Lexical scoping means that all references to the named +functions must appear physically within the body of the +@code{labels} form. References may appear both in the body +@var{forms} of @code{labels} itself, and in the bodies of +the functions themselves. Thus, @code{labels} can define +local recursive functions, or mutually-recursive sets of +functions. + +A ``reference'' to a function name is either a call to that +function, or a use of its name quoted by @code{quote} or +@code{function} to be passed on to, say, @code{mapcar}. +@end defspec + +@node Macro Bindings, , Function Bindings, Variable Bindings +@subsection Macro Bindings + +@noindent +These forms create local macros and ``symbol macros.'' + +@defspec macrolet (bindings@dots{}) forms@dots{} +This form is analogous to @code{flet}, but for macros instead of +functions. Each @var{binding} is a list of the same form as the +arguments to @code{defmacro*} (i.e., a macro name, argument list, +and macro-expander forms). The macro is defined accordingly for +use within the body of the @code{macrolet}. + +Because of the nature of macros, @code{macrolet} is lexically +scoped even in Emacs Lisp: The @code{macrolet} binding will +affect only calls that appear physically within the body +@var{forms}, possibly after expansion of other macros in the +body. +@end defspec + +@defspec symbol-macrolet (bindings@dots{}) forms@dots{} +This form creates @dfn{symbol macros}, which are macros that look +like variable references rather than function calls. Each +@var{binding} is a list @samp{(@var{var} @var{expansion})}; +any reference to @var{var} within the body @var{forms} is +replaced by @var{expansion}. + +@example +(setq bar '(5 . 9)) +(symbol-macrolet ((foo (car bar))) + (incf foo)) +bar + @result{} (6 . 9) +@end example + +A @code{setq} of a symbol macro is treated the same as a @code{setf}. +I.e., @code{(setq foo 4)} in the above would be equivalent to +@code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}. + +Likewise, a @code{let} or @code{let*} binding a symbol macro is +treated like a @code{letf} or @code{letf*}. This differs from true +Common Lisp, where the rules of lexical scoping cause a @code{let} +binding to shadow a @code{symbol-macrolet} binding. In this package, +only @code{lexical-let} and @code{lexical-let*} will shadow a symbol +macro. + +There is no analogue of @code{defmacro} for symbol macros; all symbol +macros are local. A typical use of @code{symbol-macrolet} is in the +expansion of another macro: + +@example +(defmacro* my-dolist ((x list) &rest body) + (let ((var (gensym))) + (list 'loop 'for var 'on list 'do + (list* 'symbol-macrolet (list (list x (list 'car var))) + body)))) + +(setq mylist '(1 2 3 4)) +(my-dolist (x mylist) (incf x)) +mylist + @result{} (2 3 4 5) +@end example + +@noindent +In this example, the @code{my-dolist} macro is similar to @code{dolist} +(@pxref{Iteration}) except that the variable @code{x} becomes a true +reference onto the elements of the list. The @code{my-dolist} call +shown here expands to + +@example +(loop for G1234 on mylist do + (symbol-macrolet ((x (car G1234))) + (incf x))) +@end example + +@noindent +which in turn expands to + +@example +(loop for G1234 on mylist do (incf (car G1234))) +@end example + +@xref{Loop Facility}, for a description of the @code{loop} macro. +This package defines a nonstandard @code{in-ref} loop clause that +works much like @code{my-dolist}. +@end defspec + +@node Conditionals, Blocks and Exits, Variable Bindings, Control Structure +@section Conditionals + +@noindent +These conditional forms augment Emacs Lisp's simple @code{if}, +@code{and}, @code{or}, and @code{cond} forms. + +@defspec case keyform clause@dots{} +This macro evaluates @var{keyform}, then compares it with the key +values listed in the various @var{clause}s. Whichever clause matches +the key is executed; comparison is done by @code{eql}. If no clause +matches, the @code{case} form returns @code{nil}. The clauses are +of the form + +@example +(@var{keylist} @var{body-forms}@dots{}) +@end example + +@noindent +where @var{keylist} is a list of key values. If there is exactly +one value, and it is not a cons cell or the symbol @code{nil} or +@code{t}, then it can be used by itself as a @var{keylist} without +being enclosed in a list. All key values in the @code{case} form +must be distinct. The final clauses may use @code{t} in place of +a @var{keylist} to indicate a default clause that should be taken +if none of the other clauses match. (The symbol @code{otherwise} +is also recognized in place of @code{t}. To make a clause that +matches the actual symbol @code{t}, @code{nil}, or @code{otherwise}, +enclose the symbol in a list.) + +For example, this expression reads a keystroke, then does one of +four things depending on whether it is an @samp{a}, a @samp{b}, +a @key{RET} or @kbd{C-j}, or anything else. + +@example +(case (read-char) + (?a (do-a-thing)) + (?b (do-b-thing)) + ((?\r ?\n) (do-ret-thing)) + (t (do-other-thing))) +@end example +@end defspec + +@defspec ecase keyform clause@dots{} +This macro is just like @code{case}, except that if the key does +not match any of the clauses, an error is signaled rather than +simply returning @code{nil}. +@end defspec + +@defspec typecase keyform clause@dots{} +This macro is a version of @code{case} that checks for types +rather than values. Each @var{clause} is of the form +@samp{(@var{type} @var{body}...)}. @xref{Type Predicates}, +for a description of type specifiers. For example, + +@example +(typecase x + (integer (munch-integer x)) + (float (munch-float x)) + (string (munch-integer (string-to-int x))) + (t (munch-anything x))) +@end example + +The type specifier @code{t} matches any type of object; the word +@code{otherwise} is also allowed. To make one clause match any of +several types, use an @code{(or ...)} type specifier. +@end defspec + +@defspec etypecase keyform clause@dots{} +This macro is just like @code{typecase}, except that if the key does +not match any of the clauses, an error is signaled rather than +simply returning @code{nil}. +@end defspec + +@node Blocks and Exits, Iteration, Conditionals, Control Structure +@section Blocks and Exits + +@noindent +Common Lisp @dfn{blocks} provide a non-local exit mechanism very +similar to @code{catch} and @code{throw}, but lexically rather than +dynamically scoped. This package actually implements @code{block} +in terms of @code{catch}; however, the lexical scoping allows the +optimizing byte-compiler to omit the costly @code{catch} step if the +body of the block does not actually @code{return-from} the block. + +@defspec block name forms@dots{} +The @var{forms} are evaluated as if by a @code{progn}. However, +if any of the @var{forms} execute @code{(return-from @var{name})}, +they will jump out and return directly from the @code{block} form. +The @code{block} returns the result of the last @var{form} unless +a @code{return-from} occurs. + +The @code{block}/@code{return-from} mechanism is quite similar to +the @code{catch}/@code{throw} mechanism. The main differences are +that block @var{name}s are unevaluated symbols, rather than forms +(such as quoted symbols) which evaluate to a tag at run-time; and +also that blocks are lexically scoped whereas @code{catch}/@code{throw} +are dynamically scoped. This means that functions called from the +body of a @code{catch} can also @code{throw} to the @code{catch}, +but the @code{return-from} referring to a block name must appear +physically within the @var{forms} that make up the body of the block. +They may not appear within other called functions, although they may +appear within macro expansions or @code{lambda}s in the body. Block +names and @code{catch} names form independent name-spaces. + +In true Common Lisp, @code{defun} and @code{defmacro} surround +the function or expander bodies with implicit blocks with the +same name as the function or macro. This does not occur in Emacs +Lisp, but this package provides @code{defun*} and @code{defmacro*} +forms which do create the implicit block. + +The Common Lisp looping constructs defined by this package, +such as @code{loop} and @code{dolist}, also create implicit blocks +just as in Common Lisp. + +Because they are implemented in terms of Emacs Lisp @code{catch} +and @code{throw}, blocks have the same overhead as actual +@code{catch} constructs (roughly two function calls). However, +Zawinski and Furuseth's optimizing byte compiler (standard in +Emacs 19) will optimize away the @code{catch} if the block does +not in fact contain any @code{return} or @code{return-from} calls +that jump to it. This means that @code{do} loops and @code{defun*} +functions which don't use @code{return} don't pay the overhead to +support it. +@end defspec + +@defspec return-from name [result] +This macro returns from the block named @var{name}, which must be +an (unevaluated) symbol. If a @var{result} form is specified, it +is evaluated to produce the result returned from the @code{block}. +Otherwise, @code{nil} is returned. +@end defspec + +@defspec return [result] +This macro is exactly like @code{(return-from nil @var{result})}. +Common Lisp loops like @code{do} and @code{dolist} implicitly enclose +themselves in @code{nil} blocks. +@end defspec + +@node Iteration, Loop Facility, Blocks and Exits, Control Structure +@section Iteration + +@noindent +The macros described here provide more sophisticated, high-level +looping constructs to complement Emacs Lisp's basic @code{while} +loop. + +@defspec loop forms@dots{} +The @dfn{CL} package supports both the simple, old-style meaning of +@code{loop} and the extremely powerful and flexible feature known as +the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced +facility is discussed in the following section; @pxref{Loop Facility}. +The simple form of @code{loop} is described here. + +If @code{loop} is followed by zero or more Lisp expressions, +then @code{(loop @var{exprs}@dots{})} simply creates an infinite +loop executing the expressions over and over. The loop is +enclosed in an implicit @code{nil} block. Thus, + +@example +(loop (foo) (if (no-more) (return 72)) (bar)) +@end example + +@noindent +is exactly equivalent to + +@example +(block nil (while t (foo) (if (no-more) (return 72)) (bar))) +@end example + +If any of the expressions are plain symbols, the loop is instead +interpreted as a Loop Macro specification as described later. +(This is not a restriction in practice, since a plain symbol +in the above notation would simply access and throw away the +value of a variable.) +@end defspec + +@defspec do (spec@dots{}) (end-test [result@dots{}]) forms@dots{} +This macro creates a general iterative loop. Each @var{spec} is +of the form + +@example +(@var{var} [@var{init} [@var{step}]]) +@end example + +The loop works as follows: First, each @var{var} is bound to the +associated @var{init} value as if by a @code{let} form. Then, in +each iteration of the loop, the @var{end-test} is evaluated; if +true, the loop is finished. Otherwise, the body @var{forms} are +evaluated, then each @var{var} is set to the associated @var{step} +expression (as if by a @code{psetq} form) and the next iteration +begins. Once the @var{end-test} becomes true, the @var{result} +forms are evaluated (with the @var{var}s still bound to their +values) to produce the result returned by @code{do}. + +The entire @code{do} loop is enclosed in an implicit @code{nil} +block, so that you can use @code{(return)} to break out of the +loop at any time. + +If there are no @var{result} forms, the loop returns @code{nil}. +If a given @var{var} has no @var{step} form, it is bound to its +@var{init} value but not otherwise modified during the @code{do} +loop (unless the code explicitly modifies it); this case is just +a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})} +around the loop. If @var{init} is also omitted it defaults to +@code{nil}, and in this case a plain @samp{@var{var}} can be used +in place of @samp{(@var{var})}, again following the analogy with +@code{let}. + +This example (from Steele) illustrates a loop which applies the +function @code{f} to successive pairs of values from the lists +@code{foo} and @code{bar}; it is equivalent to the call +@code{(mapcar* 'f foo bar)}. Note that this loop has no body +@var{forms} at all, performing all its work as side effects of +the rest of the loop. + +@example +(do ((x foo (cdr x)) + (y bar (cdr y)) + (z nil (cons (f (car x) (car y)) z))) + ((or (null x) (null y)) + (nreverse z))) +@end example +@end defspec + +@defspec do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{} +This is to @code{do} what @code{let*} is to @code{let}. In +particular, the initial values are bound as if by @code{let*} +rather than @code{let}, and the steps are assigned as if by +@code{setq} rather than @code{psetq}. + +Here is another way to write the above loop: + +@example +(do* ((xp foo (cdr xp)) + (yp bar (cdr yp)) + (x (car xp) (car xp)) + (y (car yp) (car yp)) + z) + ((or (null xp) (null yp)) + (nreverse z)) + (push (f x y) z)) +@end example +@end defspec + +@defspec dolist (var list [result]) forms@dots{} +This is a more specialized loop which iterates across the elements +of a list. @var{list} should evaluate to a list; the body @var{forms} +are executed with @var{var} bound to each element of the list in +turn. Finally, the @var{result} form (or @code{nil}) is evaluated +with @var{var} bound to @code{nil} to produce the result returned by +the loop. The loop is surrounded by an implicit @code{nil} block. +@end defspec + +@defspec dotimes (var count [result]) forms@dots{} +This is a more specialized loop which iterates a specified number +of times. The body is executed with @var{var} bound to the integers +from zero (inclusive) to @var{count} (exclusive), in turn. Then +the @code{result} form is evaluated with @var{var} bound to the total +number of iterations that were done (i.e., @code{(max 0 @var{count})}) +to get the return value for the loop form. The loop is surrounded +by an implicit @code{nil} block. +@end defspec + +@defspec do-symbols (var [obarray [result]]) forms@dots{} +This loop iterates over all interned symbols. If @var{obarray} +is specified and is not @code{nil}, it loops over all symbols in +that obarray. For each symbol, the body @var{forms} are evaluated +with @var{var} bound to that symbol. The symbols are visited in +an unspecified order. Afterward the @var{result} form, if any, +is evaluated (with @var{var} bound to @code{nil}) to get the return +value. The loop is surrounded by an implicit @code{nil} block. +@end defspec + +@defspec do-all-symbols (var [result]) forms@dots{} +This is identical to @code{do-symbols} except that the @var{obarray} +argument is omitted; it always iterates over the default obarray. +@end defspec + +@xref{Mapping over Sequences}, for some more functions for +iterating over vectors or lists. + +@node Loop Facility, Multiple Values, Iteration, Control Structure +@section Loop Facility + +@noindent +A common complaint with Lisp's traditional looping constructs is +that they are either too simple and limited, such as Common Lisp's +@code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and +obscure, like Common Lisp's @code{do} loop. + +To remedy this, recent versions of Common Lisp have added a new +construct called the ``Loop Facility'' or ``@code{loop} macro,'' +with an easy-to-use but very powerful and expressive syntax. + +@menu +* Loop Basics:: `loop' macro, basic clause structure +* Loop Examples:: Working examples of `loop' macro +* For Clauses:: Clauses introduced by `for' or `as' +* Iteration Clauses:: `repeat', `while', `thereis', etc. +* Accumulation Clauses:: `collect', `sum', `maximize', etc. +* Other Clauses:: `with', `if', `initially', `finally' +@end menu + +@node Loop Basics, Loop Examples, Loop Facility, Loop Facility +@subsection Loop Basics + +@noindent +The @code{loop} macro essentially creates a mini-language within +Lisp that is specially tailored for describing loops. While this +language is a little strange-looking by the standards of regular Lisp, +it turns out to be very easy to learn and well-suited to its purpose. + +Since @code{loop} is a macro, all parsing of the loop language +takes place at byte-compile time; compiled @code{loop}s are just +as efficient as the equivalent @code{while} loops written longhand. + +@defspec loop clauses@dots{} +A loop construct consists of a series of @var{clause}s, each +introduced by a symbol like @code{for} or @code{do}. Clauses +are simply strung together in the argument list of @code{loop}, +with minimal extra parentheses. The various types of clauses +specify initializations, such as the binding of temporary +variables, actions to be taken in the loop, stepping actions, +and final cleanup. + +Common Lisp specifies a certain general order of clauses in a +loop: + +@example +(loop @var{name-clause} + @var{var-clauses}@dots{} + @var{action-clauses}@dots{}) +@end example + +The @var{name-clause} optionally gives a name to the implicit +block that surrounds the loop. By default, the implicit block +is named @code{nil}. The @var{var-clauses} specify what +variables should be bound during the loop, and how they should +be modified or iterated throughout the course of the loop. The +@var{action-clauses} are things to be done during the loop, such +as computing, collecting, and returning values. + +The Emacs version of the @code{loop} macro is less restrictive about +the order of clauses, but things will behave most predictably if +you put the variable-binding clauses @code{with}, @code{for}, and +@code{repeat} before the action clauses. As in Common Lisp, +@code{initially} and @code{finally} clauses can go anywhere. + +Loops generally return @code{nil} by default, but you can cause +them to return a value by using an accumulation clause like +@code{collect}, an end-test clause like @code{always}, or an +explicit @code{return} clause to jump out of the implicit block. +(Because the loop body is enclosed in an implicit block, you can +also use regular Lisp @code{return} or @code{return-from} to +break out of the loop.) +@end defspec + +The following sections give some examples of the Loop Macro in +action, and describe the particular loop clauses in great detail. +Consult the second edition of Steele's @dfn{Common Lisp, the Language}, +for additional discussion and examples of the @code{loop} macro. + +@node Loop Examples, For Clauses, Loop Basics, Loop Facility +@subsection Loop Examples + +@noindent +Before listing the full set of clauses that are allowed, let's +look at a few example loops just to get a feel for the @code{loop} +language. + +@example +(loop for buf in (buffer-list) + collect (buffer-file-name buf)) +@end example + +@noindent +This loop iterates over all Emacs buffers, using the list +returned by @code{buffer-list}. For each buffer @code{buf}, +it calls @code{buffer-file-name} and collects the results into +a list, which is then returned from the @code{loop} construct. +The result is a list of the file names of all the buffers in +Emacs' memory. The words @code{for}, @code{in}, and @code{collect} +are reserved words in the @code{loop} language. + +@example +(loop repeat 20 do (insert "Yowsa\n")) +@end example + +@noindent +This loop inserts the phrase ``Yowsa'' twenty times in the +current buffer. + +@example +(loop until (eobp) do (munch-line) (forward-line 1)) +@end example + +@noindent +This loop calls @code{munch-line} on every line until the end +of the buffer. If point is already at the end of the buffer, +the loop exits immediately. + +@example +(loop do (munch-line) until (eobp) do (forward-line 1)) +@end example + +@noindent +This loop is similar to the above one, except that @code{munch-line} +is always called at least once. + +@example +(loop for x from 1 to 100 + for y = (* x x) + until (>= y 729) + finally return (list x (= y 729))) +@end example + +@noindent +This more complicated loop searches for a number @code{x} whose +square is 729. For safety's sake it only examines @code{x} +values up to 100; dropping the phrase @samp{to 100} would +cause the loop to count upwards with no limit. The second +@code{for} clause defines @code{y} to be the square of @code{x} +within the loop; the expression after the @code{=} sign is +reevaluated each time through the loop. The @code{until} +clause gives a condition for terminating the loop, and the +@code{finally} clause says what to do when the loop finishes. +(This particular example was written less concisely than it +could have been, just for the sake of illustration.) + +Note that even though this loop contains three clauses (two +@code{for}s and an @code{until}) that would have been enough to +define loops all by themselves, it still creates a single loop +rather than some sort of triple-nested loop. You must explicitly +nest your @code{loop} constructs if you want nested loops. + +@node For Clauses, Iteration Clauses, Loop Examples, Loop Facility +@subsection For Clauses + +@noindent +Most loops are governed by one or more @code{for} clauses. +A @code{for} clause simultaneously describes variables to be +bound, how those variables are to be stepped during the loop, +and usually an end condition based on those variables. + +The word @code{as} is a synonym for the word @code{for}. This +word is followed by a variable name, then a word like @code{from} +or @code{across} that describes the kind of iteration desired. +In Common Lisp, the phrase @code{being the} sometimes precedes +the type of iteration; in this package both @code{being} and +@code{the} are optional. The word @code{each} is a synonym +for @code{the}, and the word that follows it may be singular +or plural: @samp{for x being the elements of y} or +@samp{for x being each element of y}. Which form you use +is purely a matter of style. + +The variable is bound around the loop as if by @code{let}: + +@example +(setq i 'happy) +(loop for i from 1 to 10 do (do-something-with i)) +i + @result{} happy +@end example + +@table @code +@item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3} +This type of @code{for} clause creates a counting loop. Each of +the three sub-terms is optional, though there must be at least one +term so that the clause is marked as a counting clause. + +The three expressions are the starting value, the ending value, and +the step value, respectively, of the variable. The loop counts +upwards by default (@var{expr3} must be positive), from @var{expr1} +to @var{expr2} inclusively. If you omit the @code{from} term, the +loop counts from zero; if you omit the @code{to} term, the loop +counts forever without stopping (unless stopped by some other +loop clause, of course); if you omit the @code{by} term, the loop +counts in steps of one. + +You can replace the word @code{from} with @code{upfrom} or +@code{downfrom} to indicate the direction of the loop. Likewise, +you can replace @code{to} with @code{upto} or @code{downto}. +For example, @samp{for x from 5 downto 1} executes five times +with @code{x} taking on the integers from 5 down to 1 in turn. +Also, you can replace @code{to} with @code{below} or @code{above}, +which are like @code{upto} and @code{downto} respectively except +that they are exclusive rather than inclusive limits: + +@example +(loop for x to 10 collect x) + @result{} (0 1 2 3 4 5 6 7 8 9 10) +(loop for x below 10 collect x) + @result{} (0 1 2 3 4 5 6 7 8 9) +@end example + +The @code{by} value is always positive, even for downward-counting +loops. Some sort of @code{from} value is required for downward +loops; @samp{for x downto 5} is not a legal loop clause all by +itself. + +@item for @var{var} in @var{list} by @var{function} +This clause iterates @var{var} over all the elements of @var{list}, +in turn. If you specify the @code{by} term, then @var{function} +is used to traverse the list instead of @code{cdr}; it must be a +function taking one argument. For example: + +@example +(loop for x in '(1 2 3 4 5 6) collect (* x x)) + @result{} (1 4 9 16 25 36) +(loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x)) + @result{} (1 9 25) +@end example + +@item for @var{var} on @var{list} by @var{function} +This clause iterates @var{var} over all the cons cells of @var{list}. + +@example +(loop for x on '(1 2 3 4) collect x) + @result{} ((1 2 3 4) (2 3 4) (3 4) (4)) +@end example + +With @code{by}, there is no real reason that the @code{on} expression +must be a list. For example: + +@example +(loop for x on first-animal by 'next-animal collect x) +@end example + +@noindent +where @code{(next-animal x)} takes an ``animal'' @var{x} and returns +the next in the (assumed) sequence of animals, or @code{nil} if +@var{x} was the last animal in the sequence. + +@item for @var{var} in-ref @var{list} by @var{function} +This is like a regular @code{in} clause, but @var{var} becomes +a @code{setf}-able ``reference'' onto the elements of the list +rather than just a temporary variable. For example, + +@example +(loop for x in-ref my-list do (incf x)) +@end example + +@noindent +increments every element of @code{my-list} in place. This clause +is an extension to standard Common Lisp. + +@item for @var{var} across @var{array} +This clause iterates @var{var} over all the elements of @var{array}, +which may be a vector or a string. + +@example +(loop for x across "aeiou" + do (use-vowel (char-to-string x))) +@end example + +@item for @var{var} across-ref @var{array} +This clause iterates over an array, with @var{var} a @code{setf}-able +reference onto the elements; see @code{in-ref} above. + +@item for @var{var} being the elements of @var{sequence} +This clause iterates over the elements of @var{sequence}, which may +be a list, vector, or string. Since the type must be determined +at run-time, this is somewhat less efficient than @code{in} or +@code{across}. The clause may be followed by the additional term +@samp{using (index @var{var2})} to cause @var{var2} to be bound to +the successive indices (starting at 0) of the elements. + +This clause type is taken from older versions of the @code{loop} macro, +and is not present in modern Common Lisp. The @samp{using (sequence ...)} +term of the older macros is not supported. + +@item for @var{var} being the elements of-ref @var{sequence} +This clause iterates over a sequence, with @var{var} a @code{setf}-able +reference onto the elements; see @code{in-ref} above. + +@item for @var{var} being the symbols [of @var{obarray}] +This clause iterates over symbols, either over all interned symbols +or over all symbols in @var{obarray}. The loop is executed with +@var{var} bound to each symbol in turn. The symbols are visited in +an unspecified order. + +As an example, + +@example +(loop for sym being the symbols + when (fboundp sym) + when (string-match "^map" (symbol-name sym)) + collect sym) +@end example + +@noindent +returns a list of all the functions whose names begin with @samp{map}. + +The Common Lisp words @code{external-symbols} and @code{present-symbols} +are also recognized but are equivalent to @code{symbols} in Emacs Lisp. + +Due to a minor implementation restriction, it will not work to have +more than one @code{for} clause iterating over symbols, hash tables, +keymaps, overlays, or intervals in a given @code{loop}. Fortunately, +it would rarely if ever be useful to do so. It @emph{is} legal to mix +one of these types of clauses with other clauses like @code{for ... to} +or @code{while}. + +@item for @var{var} being the hash-keys of @var{hash-table} +This clause iterates over the entries in @var{hash-table}. For each +hash table entry, @var{var} is bound to the entry's key. If you write +@samp{the hash-values} instead, @var{var} is bound to the values +of the entries. The clause may be followed by the additional +term @samp{using (hash-values @var{var2})} (where @code{hash-values} +is the opposite word of the word following @code{the}) to cause +@var{var} and @var{var2} to be bound to the two parts of each +hash table entry. + +@item for @var{var} being the key-codes of @var{keymap} +This clause iterates over the entries in @var{keymap}. In GNU Emacs +18 and 19, keymaps are either alists or vectors, and key-codes are +integers or symbols. In Lucid Emacs 19, keymaps are a special new +data type, and key-codes are symbols or lists of symbols. The +iteration does not enter nested keymaps or inherited (parent) keymaps. +You can use @samp{the key-bindings} to access the commands bound to +the keys rather than the key codes, and you can add a @code{using} +clause to access both the codes and the bindings together. + +@item for @var{var} being the key-seqs of @var{keymap} +This clause iterates over all key sequences defined by @var{keymap} +and its nested keymaps, where @var{var} takes on values which are +strings in Emacs 18 or vectors in Emacs 19. The strings or vectors +are reused for each iteration, so you must copy them if you wish to keep +them permanently. You can add a @samp{using (key-bindings ...)} +clause to get the command bindings as well. + +@item for @var{var} being the overlays [of @var{buffer}] @dots{} +This clause iterates over the Emacs 19 ``overlays'' or Lucid +Emacs ``extents'' of a buffer (the clause @code{extents} is synonymous +with @code{overlays}). Under Emacs 18, this clause iterates zero +times. If the @code{of} term is omitted, the current buffer is used. +This clause also accepts optional @samp{from @var{pos}} and +@samp{to @var{pos}} terms, limiting the clause to overlays which +overlap the specified region. + +@item for @var{var} being the intervals [of @var{buffer}] @dots{} +This clause iterates over all intervals of a buffer with constant +text properties. The variable @var{var} will be bound to conses +of start and end positions, where one start position is always equal +to the previous end position. The clause allows @code{of}, +@code{from}, @code{to}, and @code{property} terms, where the latter +term restricts the search to just the specified property. The +@code{of} term may specify either a buffer or a string. This +clause is useful only in GNU Emacs 19; in other versions, all +buffers and strings consist of a single interval. + +@item for @var{var} being the frames +This clause iterates over all frames, i.e., X window system windows +open on Emacs files. This clause works only under Emacs 19. The +clause @code{screens} is a synonym for @code{frames}. The frames +are visited in @code{next-frame} order starting from +@code{selected-frame}. + +@item for @var{var} being the windows [of @var{frame}] +This clause iterates over the windows (in the Emacs sense) of +the current frame, or of the specified @var{frame}. (In Emacs 18 +there is only ever one frame, and the @code{of} term is not +allowed there.) + +@item for @var{var} being the buffers +This clause iterates over all buffers in Emacs. It is equivalent +to @samp{for @var{var} in (buffer-list)}. + +@item for @var{var} = @var{expr1} then @var{expr2} +This clause does a general iteration. The first time through +the loop, @var{var} will be bound to @var{expr1}. On the second +and successive iterations it will be set by evaluating @var{expr2} +(which may refer to the old value of @var{var}). For example, +these two loops are effectively the same: + +@example +(loop for x on my-list by 'cddr do ...) +(loop for x = my-list then (cddr x) while x do ...) +@end example + +Note that this type of @code{for} clause does not imply any sort +of terminating condition; the above example combines it with a +@code{while} clause to tell when to end the loop. + +If you omit the @code{then} term, @var{expr1} is used both for +the initial setting and for successive settings: + +@example +(loop for x = (random) when (> x 0) return x) +@end example + +@noindent +This loop keeps taking random numbers from the @code{(random)} +function until it gets a positive one, which it then returns. +@end table + +If you include several @code{for} clauses in a row, they are +treated sequentially (as if by @code{let*} and @code{setq}). +You can instead use the word @code{and} to link the clauses, +in which case they are processed in parallel (as if by @code{let} +and @code{psetq}). + +@example +(loop for x below 5 for y = nil then x collect (list x y)) + @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4)) +(loop for x below 5 and y = nil then x collect (list x y)) + @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3)) +@end example + +@noindent +In the first loop, @code{y} is set based on the value of @code{x} +that was just set by the previous clause; in the second loop, +@code{x} and @code{y} are set simultaneously so @code{y} is set +based on the value of @code{x} left over from the previous time +through the loop. + +Another feature of the @code{loop} macro is @dfn{destructuring}, +similar in concept to the destructuring provided by @code{defmacro}. +The @var{var} part of any @code{for} clause can be given as a list +of variables instead of a single variable. The values produced +during loop execution must be lists; the values in the lists are +stored in the corresponding variables. + +@example +(loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y)) + @result{} (5 9 13) +@end example + +In loop destructuring, if there are more values than variables +the trailing values are ignored, and if there are more variables +than values the trailing variables get the value @code{nil}. +If @code{nil} is used as a variable name, the corresponding +values are ignored. Destructuring may be nested, and dotted +lists of variables like @code{(x . y)} are allowed. + +@node Iteration Clauses, Accumulation Clauses, For Clauses, Loop Facility +@subsection Iteration Clauses + +@noindent +Aside from @code{for} clauses, there are several other loop clauses +that control the way the loop operates. They might be used by +themselves, or in conjunction with one or more @code{for} clauses. + +@table @code +@item repeat @var{integer} +This clause simply counts up to the specified number using an +internal temporary variable. The loops + +@example +(loop repeat n do ...) +(loop for temp to n do ...) +@end example + +@noindent +are identical except that the second one forces you to choose +a name for a variable you aren't actually going to use. + +@item while @var{condition} +This clause stops the loop when the specified condition (any Lisp +expression) becomes @code{nil}. For example, the following two +loops are equivalent, except for the implicit @code{nil} block +that surrounds the second one: + +@example +(while @var{cond} @var{forms}@dots{}) +(loop while @var{cond} do @var{forms}@dots{}) +@end example + +@item until @var{condition} +This clause stops the loop when the specified condition is true, +i.e., non-@code{nil}. + +@item always @var{condition} +This clause stops the loop when the specified condition is @code{nil}. +Unlike @code{while}, it stops the loop using @code{return nil} so that +the @code{finally} clauses are not executed. If all the conditions +were non-@code{nil}, the loop returns @code{t}: + +@example +(if (loop for size in size-list always (> size 10)) + (some-big-sizes) + (no-big-sizes)) +@end example + +@item never @var{condition} +This clause is like @code{always}, except that the loop returns +@code{t} if any conditions were false, or @code{nil} otherwise. + +@item thereis @var{condition} +This clause stops the loop when the specified form is non-@code{nil}; +in this case, it returns that non-@code{nil} value. If all the +values were @code{nil}, the loop returns @code{nil}. +@end table + +@node Accumulation Clauses, Other Clauses, Iteration Clauses, Loop Facility +@subsection Accumulation Clauses + +@noindent +These clauses cause the loop to accumulate information about the +specified Lisp @var{form}. The accumulated result is returned +from the loop unless overridden, say, by a @code{return} clause. + +@table @code +@item collect @var{form} +This clause collects the values of @var{form} into a list. Several +examples of @code{collect} appear elsewhere in this manual. + +The word @code{collecting} is a synonym for @code{collect}, and +likewise for the other accumulation clauses. + +@item append @var{form} +This clause collects lists of values into a result list using +@code{append}. + +@item nconc @var{form} +This clause collects lists of values into a result list by +destructively modifying the lists rather than copying them. + +@item concat @var{form} +This clause concatenates the values of the specified @var{form} +into a string. (It and the following clause are extensions to +standard Common Lisp.) + +@item vconcat @var{form} +This clause concatenates the values of the specified @var{form} +into a vector. + +@item count @var{form} +This clause counts the number of times the specified @var{form} +evaluates to a non-@code{nil} value. + +@item sum @var{form} +This clause accumulates the sum of the values of the specified +@var{form}, which must evaluate to a number. + +@item maximize @var{form} +This clause accumulates the maximum value of the specified @var{form}, +which must evaluate to a number. The return value is undefined if +@code{maximize} is executed zero times. + +@item minimize @var{form} +This clause accumulates the minimum value of the specified @var{form}. +@end table + +Accumulation clauses can be followed by @samp{into @var{var}} to +cause the data to be collected into variable @var{var} (which is +automatically @code{let}-bound during the loop) rather than an +unnamed temporary variable. Also, @code{into} accumulations do +not automatically imply a return value. The loop must use some +explicit mechanism, such as @code{finally return}, to return +the accumulated result. + +It is legal for several accumulation clauses of the same type to +accumulate into the same place. From Steele: + +@example +(loop for name in '(fred sue alice joe june) + for kids in '((bob ken) () () (kris sunshine) ()) + collect name + append kids) + @result{} (fred bob ken sue alice joe kris sunshine june) +@end example + +@node Other Clauses, , Accumulation Clauses, Loop Facility +@subsection Other Clauses + +@noindent +This section describes the remaining loop clauses. + +@table @code +@item with @var{var} = @var{value} +This clause binds a variable to a value around the loop, but +otherwise leaves the variable alone during the loop. The following +loops are basically equivalent: + +@example +(loop with x = 17 do ...) +(let ((x 17)) (loop do ...)) +(loop for x = 17 then x do ...) +@end example + +Naturally, the variable @var{var} might be used for some purpose +in the rest of the loop. For example: + +@example +(loop for x in my-list with res = nil do (push x res) + finally return res) +@end example + +This loop inserts the elements of @code{my-list} at the front of +a new list being accumulated in @code{res}, then returns the +list @code{res} at the end of the loop. The effect is similar +to that of a @code{collect} clause, but the list gets reversed +by virtue of the fact that elements are being pushed onto the +front of @code{res} rather than the end. + +If you omit the @code{=} term, the variable is initialized to +@code{nil}. (Thus the @samp{= nil} in the above example is +unnecessary.) + +Bindings made by @code{with} are sequential by default, as if +by @code{let*}. Just like @code{for} clauses, @code{with} clauses +can be linked with @code{and} to cause the bindings to be made by +@code{let} instead. + +@item if @var{condition} @var{clause} +This clause executes the following loop clause only if the specified +condition is true. The following @var{clause} should be an accumulation, +@code{do}, @code{return}, @code{if}, or @code{unless} clause. +Several clauses may be linked by separating them with @code{and}. +These clauses may be followed by @code{else} and a clause or clauses +to execute if the condition was false. The whole construct may +optionally be followed by the word @code{end} (which may be used to +disambiguate an @code{else} or @code{and} in a nested @code{if}). + +The actual non-@code{nil} value of the condition form is available +by the name @code{it} in the ``then'' part. For example: + +@example +(setq funny-numbers '(6 13 -1)) + @result{} (6 13 -1) +(loop for x below 10 + if (oddp x) + collect x into odds + and if (memq x funny-numbers) return (cdr it) end + else + collect x into evens + finally return (vector odds evens)) + @result{} [(1 3 5 7 9) (0 2 4 6 8)] +(setq funny-numbers '(6 7 13 -1)) + @result{} (6 7 13 -1) +(loop <@r{same thing again}>) + @result{} (13 -1) +@end example + +Note the use of @code{and} to put two clauses into the ``then'' +part, one of which is itself an @code{if} clause. Note also that +@code{end}, while normally optional, was necessary here to make +it clear that the @code{else} refers to the outermost @code{if} +clause. In the first case, the loop returns a vector of lists +of the odd and even values of @var{x}. In the second case, the +odd number 7 is one of the @code{funny-numbers} so the loop +returns early; the actual returned value is based on the result +of the @code{memq} call. + +@item when @var{condition} @var{clause} +This clause is just a synonym for @code{if}. + +@item unless @var{condition} @var{clause} +The @code{unless} clause is just like @code{if} except that the +sense of the condition is reversed. + +@item named @var{name} +This clause gives a name other than @code{nil} to the implicit +block surrounding the loop. The @var{name} is the symbol to be +used as the block name. + +@item initially [do] @var{forms}... +This keyword introduces one or more Lisp forms which will be +executed before the loop itself begins (but after any variables +requested by @code{for} or @code{with} have been bound to their +initial values). @code{initially} clauses can appear anywhere; +if there are several, they are executed in the order they appear +in the loop. The keyword @code{do} is optional. + +@item finally [do] @var{forms}... +This introduces Lisp forms which will be executed after the loop +finishes (say, on request of a @code{for} or @code{while}). +@code{initially} and @code{finally} clauses may appear anywhere +in the loop construct, but they are executed (in the specified +order) at the beginning or end, respectively, of the loop. + +@item finally return @var{form} +This says that @var{form} should be executed after the loop +is done to obtain a return value. (Without this, or some other +clause like @code{collect} or @code{return}, the loop will simply +return @code{nil}.) Variables bound by @code{for}, @code{with}, +or @code{into} will still contain their final values when @var{form} +is executed. + +@item do @var{forms}... +The word @code{do} may be followed by any number of Lisp expressions +which are executed as an implicit @code{progn} in the body of the +loop. Many of the examples in this section illustrate the use of +@code{do}. + +@item return @var{form} +This clause causes the loop to return immediately. The following +Lisp form is evaluated to give the return value of the @code{loop} +form. The @code{finally} clauses, if any, are not executed. +Of course, @code{return} is generally used inside an @code{if} or +@code{unless}, as its use in a top-level loop clause would mean +the loop would never get to ``loop'' more than once. + +The clause @samp{return @var{form}} is equivalent to +@samp{do (return @var{form})} (or @code{return-from} if the loop +was named). The @code{return} clause is implemented a bit more +efficiently, though. +@end table + +While there is no high-level way to add user extensions to @code{loop} +(comparable to @code{defsetf} for @code{setf}, say), this package +does offer two properties called @code{cl-loop-handler} and +@code{cl-loop-for-handler} which are functions to be called when +a given symbol is encountered as a top-level loop clause or +@code{for} clause, respectively. Consult the source code in +file @file{cl-macs.el} for details. + +This package's @code{loop} macro is compatible with that of Common +Lisp, except that a few features are not implemented: @code{loop-finish} +and data-type specifiers. Naturally, the @code{for} clauses which +iterate over keymaps, overlays, intervals, frames, windows, and +buffers are Emacs-specific extensions. + +@node Multiple Values, , Loop Facility, Control Structure +@section Multiple Values + +@noindent +Common Lisp functions can return zero or more results. Emacs Lisp +functions, by contrast, always return exactly one result. This +package makes no attempt to emulate Common Lisp multiple return +values; Emacs versions of Common Lisp functions that return more +than one value either return just the first value (as in +@code{compiler-macroexpand}) or return a list of values (as in +@code{get-setf-method}). This package @emph{does} define placeholders +for the Common Lisp functions that work with multiple values, but +in Emacs Lisp these functions simply operate on lists instead. +The @code{values} form, for example, is a synonym for @code{list} +in Emacs. + +@defspec multiple-value-bind (var@dots{}) values-form forms@dots{} +This form evaluates @var{values-form}, which must return a list of +values. It then binds the @var{var}s to these respective values, +as if by @code{let}, and then executes the body @var{forms}. +If there are more @var{var}s than values, the extra @var{var}s +are bound to @code{nil}. If there are fewer @var{var}s than +values, the excess values are ignored. +@end defspec + +@defspec multiple-value-setq (var@dots{}) form +This form evaluates @var{form}, which must return a list of values. +It then sets the @var{var}s to these respective values, as if by +@code{setq}. Extra @var{var}s or values are treated the same as +in @code{multiple-value-bind}. +@end defspec + +The older Quiroz package attempted a more faithful (but still +imperfect) emulation of Common Lisp multiple values. The old +method ``usually'' simulated true multiple values quite well, +but under certain circumstances would leave spurious return +values in memory where a later, unrelated @code{multiple-value-bind} +form would see them. + +Since a perfect emulation is not feasible in Emacs Lisp, this +package opts to keep it as simple and predictable as possible. + +@node Macros, Declarations, Control Structure, Top +@chapter Macros + +@noindent +This package implements the various Common Lisp features of +@code{defmacro}, such as destructuring, @code{&environment}, +and @code{&body}. Top-level @code{&whole} is not implemented +for @code{defmacro} due to technical difficulties. +@xref{Argument Lists}. + +Destructuring is made available to the user by way of the +following macro: + +@defspec destructuring-bind arglist expr forms@dots{} +This macro expands to code which executes @var{forms}, with +the variables in @var{arglist} bound to the list of values +returned by @var{expr}. The @var{arglist} can include all +the features allowed for @code{defmacro} argument lists, +including destructuring. (The @code{&environment} keyword +is not allowed.) The macro expansion will signal an error +if @var{expr} returns a list of the wrong number of arguments +or with incorrect keyword arguments. +@end defspec + +This package also includes the Common Lisp @code{define-compiler-macro} +facility, which allows you to define compile-time expansions and +optimizations for your functions. + +@defspec define-compiler-macro name arglist forms@dots{} +This form is similar to @code{defmacro}, except that it only expands +calls to @var{name} at compile-time; calls processed by the Lisp +interpreter are not expanded, nor are they expanded by the +@code{macroexpand} function. + +The argument list may begin with a @code{&whole} keyword and a +variable. This variable is bound to the macro-call form itself, +i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}. +If the macro expander returns this form unchanged, then the +compiler treats it as a normal function call. This allows +compiler macros to work as optimizers for special cases of a +function, leaving complicated cases alone. + +For example, here is a simplified version of a definition that +appears as a standard part of this package: + +@example +(define-compiler-macro member* (&whole form a list &rest keys) + (if (and (null keys) + (eq (car-safe a) 'quote) + (not (floatp-safe (cadr a)))) + (list 'memq a list) + form)) +@end example + +@noindent +This definition causes @code{(member* @var{a} @var{list})} to change +to a call to the faster @code{memq} in the common case where @var{a} +is a non-floating-point constant; if @var{a} is anything else, or +if there are any keyword arguments in the call, then the original +@code{member*} call is left intact. (The actual compiler macro +for @code{member*} optimizes a number of other cases, including +common @code{:test} predicates.) +@end defspec + +@defun compiler-macroexpand form +This function is analogous to @code{macroexpand}, except that it +expands compiler macros rather than regular macros. It returns +@var{form} unchanged if it is not a call to a function for which +a compiler macro has been defined, or if that compiler macro +decided to punt by returning its @code{&whole} argument. Like +@code{macroexpand}, it expands repeatedly until it reaches a form +for which no further expansion is possible. +@end defun + +@xref{Macro Bindings}, for descriptions of the @code{macrolet} +and @code{symbol-macrolet} forms for making ``local'' macro +definitions. + +@node Declarations, Symbols, Macros, Top +@chapter Declarations + +@noindent +Common Lisp includes a complex and powerful ``declaration'' +mechanism that allows you to give the compiler special hints +about the types of data that will be stored in particular variables, +and about the ways those variables and functions will be used. This +package defines versions of all the Common Lisp declaration forms: +@code{declare}, @code{locally}, @code{proclaim}, @code{declaim}, +and @code{the}. + +Most of the Common Lisp declarations are not currently useful in +Emacs Lisp, as the byte-code system provides little opportunity +to benefit from type information, and @code{special} declarations +are redundant in a fully dynamically-scoped Lisp. A few +declarations are meaningful when the optimizing Emacs 19 byte +compiler is being used, however. Under the earlier non-optimizing +compiler, these declarations will effectively be ignored. + +@defun proclaim decl-spec +This function records a ``global'' declaration specified by +@var{decl-spec}. Since @code{proclaim} is a function, @var{decl-spec} +is evaluated and thus should normally be quoted. +@end defun + +@defspec declaim decl-specs@dots{} +This macro is like @code{proclaim}, except that it takes any number +of @var{decl-spec} arguments, and the arguments are unevaluated and +unquoted. The @code{declaim} macro also puts an @code{(eval-when +(compile load eval) ...)} around the declarations so that they will +be registered at compile-time as well as at run-time. (This is vital, +since normally the declarations are meant to influence the way the +compiler treats the rest of the file that contains the @code{declaim} +form.) +@end defspec + +@defspec declare decl-specs@dots{} +This macro is used to make declarations within functions and other +code. Common Lisp allows declarations in various locations, generally +at the beginning of any of the many ``implicit @code{progn}s'' +throughout Lisp syntax, such as function bodies, @code{let} bodies, +etc. Currently the only declaration understood by @code{declare} +is @code{special}. +@end defspec + +@defspec locally declarations@dots{} forms@dots{} +In this package, @code{locally} is no different from @code{progn}. +@end defspec + +@defspec the type form +Type information provided by @code{the} is ignored in this package; +in other words, @code{(the @var{type} @var{form})} is equivalent +to @var{form}. Future versions of the optimizing byte-compiler may +make use of this information. + +For example, @code{mapcar} can map over both lists and arrays. It is +hard for the compiler to expand @code{mapcar} into an in-line loop +unless it knows whether the sequence will be a list or an array ahead +of time. With @code{(mapcar 'car (the vector foo))}, a future +compiler would have enough information to expand the loop in-line. +For now, Emacs Lisp will treat the above code as exactly equivalent +to @code{(mapcar 'car foo)}. +@end defspec + +Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or +@code{declare} should be a list beginning with a symbol that says +what kind of declaration it is. This package currently understands +@code{special}, @code{inline}, @code{notinline}, @code{optimize}, +and @code{warn} declarations. (The @code{warn} declaration is an +extension of standard Common Lisp.) Other Common Lisp declarations, +such as @code{type} and @code{ftype}, are silently ignored. + +@table @code +@item special +Since all variables in Emacs Lisp are ``special'' (in the Common +Lisp sense), @code{special} declarations are only advisory. They +simply tell the optimizing byte compiler that the specified +variables are intentionally being referred to without being +bound in the body of the function. The compiler normally emits +warnings for such references, since they could be typographical +errors for references to local variables. + +The declaration @code{(declare (special @var{var1} @var{var2}))} is +equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the +optimizing compiler, or to nothing at all in older compilers (which +do not warn for non-local references). + +In top-level contexts, it is generally better to write +@code{(defvar @var{var})} than @code{(declaim (special @var{var}))}, +since @code{defvar} makes your intentions clearer. But the older +byte compilers can not handle @code{defvar}s appearing inside of +functions, while @code{(declare (special @var{var}))} takes care +to work correctly with all compilers. + +@item inline +The @code{inline} @var{decl-spec} lists one or more functions +whose bodies should be expanded ``in-line'' into calling functions +whenever the compiler is able to arrange for it. For example, +the Common Lisp function @code{cadr} is declared @code{inline} +by this package so that the form @code{(cadr @var{x})} will +expand directly into @code{(car (cdr @var{x}))} when it is called +in user functions, for a savings of one (relatively expensive) +function call. + +The following declarations are all equivalent. Note that the +@code{defsubst} form is a convenient way to define a function +and declare it inline all at once, but it is available only in +Emacs 19. + +@example +(declaim (inline foo bar)) +(eval-when (compile load eval) (proclaim '(inline foo bar))) +(proclaim-inline foo bar) ; Lucid Emacs only +(defsubst foo (...) ...) ; instead of defun; Emacs 19 only +@end example + +@strong{Note:} This declaration remains in effect after the +containing source file is done. It is correct to use it to +request that a function you have defined should be inlined, +but it is impolite to use it to request inlining of an external +function. + +In Common Lisp, it is possible to use @code{(declare (inline @dots{}))} +before a particular call to a function to cause just that call to +be inlined; the current byte compilers provide no way to implement +this, so @code{(declare (inline @dots{}))} is currently ignored by +this package. + +@item notinline +The @code{notinline} declaration lists functions which should +not be inlined after all; it cancels a previous @code{inline} +declaration. + +@item optimize +This declaration controls how much optimization is performed by +the compiler. Naturally, it is ignored by the earlier non-optimizing +compilers. + +The word @code{optimize} is followed by any number of lists like +@code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several +optimization ``qualities''; this package ignores all but @code{speed} +and @code{safety}. The value of a quality should be an integer from +0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.'' +The default level for both qualities is 1. + +In this package, with the Emacs 19 optimizing compiler, the +@code{speed} quality is tied to the @code{byte-compile-optimize} +flag, which is set to @code{nil} for @code{(speed 0)} and to +@code{t} for higher settings; and the @code{safety} quality is +tied to the @code{byte-compile-delete-errors} flag, which is +set to @code{t} for @code{(safety 3)} and to @code{nil} for all +lower settings. (The latter flag controls whether the compiler +is allowed to optimize out code whose only side-effect could +be to signal an error, e.g., rewriting @code{(progn foo bar)} to +@code{bar} when it is not known whether @code{foo} will be bound +at run-time.) + +Note that even compiling with @code{(safety 0)}, the Emacs +byte-code system provides sufficient checking to prevent real +harm from being done. For example, barring serious bugs in +Emacs itself, Emacs will not crash with a segmentation fault +just because of an error in a fully-optimized Lisp program. + +The @code{optimize} declaration is normally used in a top-level +@code{proclaim} or @code{declaim} in a file; Common Lisp allows +it to be used with @code{declare} to set the level of optimization +locally for a given form, but this will not work correctly with the +current version of the optimizing compiler. (The @code{declare} +will set the new optimization level, but that level will not +automatically be unset after the enclosing form is done.) + +@item warn +This declaration controls what sorts of warnings are generated +by the byte compiler. Again, only the optimizing compiler +generates warnings. The word @code{warn} is followed by any +number of ``warning qualities,'' similar in form to optimization +qualities. The currently supported warning types are +@code{redefine}, @code{callargs}, @code{unresolved}, and +@code{free-vars}; in the current system, a value of 0 will +disable these warnings and any higher value will enable them. +See the documentation for the optimizing byte compiler for details. +@end table + +@node Symbols, Numbers, Declarations, Top +@chapter Symbols + +@noindent +This package defines several symbol-related features that were +missing from Emacs Lisp. + +@menu +* Property Lists:: `get*', `remprop', `getf', `remf' +* Creating Symbols:: `gensym', `gentemp' +@end menu + +@node Property Lists, Creating Symbols, Symbols, Symbols +@section Property Lists + +@noindent +These functions augment the standard Emacs Lisp functions @code{get} +and @code{put} for operating on properties attached to symbols. +There are also functions for working with property lists as +first-class data structures not attached to particular symbols. + +@defun get* symbol property &optional default +This function is like @code{get}, except that if the property is +not found, the @var{default} argument provides the return value. +(The Emacs Lisp @code{get} function always uses @code{nil} as +the default; this package's @code{get*} is equivalent to Common +Lisp's @code{get}.) + +The @code{get*} function is @code{setf}-able; when used in this +fashion, the @var{default} argument is allowed but ignored. +@end defun + +@defun remprop symbol property +This function removes the entry for @var{property} from the property +list of @var{symbol}. It returns a true value if the property was +indeed found and removed, or @code{nil} if there was no such property. +(This function was probably omitted from Emacs originally because, +since @code{get} did not allow a @var{default}, it was very difficult +to distinguish between a missing property and a property whose value +was @code{nil}; thus, setting a property to @code{nil} was close +enough to @code{remprop} for most purposes.) +@end defun + +@defun getf place property &optional default +This function scans the list @var{place} as if it were a property +list, i.e., a list of alternating property names and values. If +an even-numbered element of @var{place} is found which is @code{eq} +to @var{property}, the following odd-numbered element is returned. +Otherwise, @var{default} is returned (or @code{nil} if no default +is given). + +In particular, + +@example +(get sym prop) @equiv{} (getf (symbol-plist sym) prop) +@end example + +It is legal to use @code{getf} as a @code{setf} place, in which case +its @var{place} argument must itself be a legal @code{setf} place. +The @var{default} argument, if any, is ignored in this context. +The effect is to change (via @code{setcar}) the value cell in the +list that corresponds to @var{property}, or to cons a new property-value +pair onto the list if the property is not yet present. + +@example +(put sym prop val) @equiv{} (setf (getf (symbol-plist sym) prop) val) +@end example + +The @code{get} and @code{get*} functions are also @code{setf}-able. +The fact that @code{default} is ignored can sometimes be useful: + +@example +(incf (get* 'foo 'usage-count 0)) +@end example + +Here, symbol @code{foo}'s @code{usage-count} property is incremented +if it exists, or set to 1 (an incremented 0) otherwise. + +When not used as a @code{setf} form, @code{getf} is just a regular +function and its @var{place} argument can actually be any Lisp +expression. +@end defun + +@defspec remf place property +This macro removes the property-value pair for @var{property} from +the property list stored at @var{place}, which is any @code{setf}-able +place expression. It returns true if the property was found. Note +that if @var{property} happens to be first on the list, this will +effectively do a @code{(setf @var{place} (cddr @var{place}))}, +whereas if it occurs later, this simply uses @code{setcdr} to splice +out the property and value cells. +@end defspec + +@iftex +@secno=2 +@end iftex + +@node Creating Symbols, , Property Lists, Symbols +@section Creating Symbols + +@noindent +These functions create unique symbols, typically for use as +temporary variables. + +@defun gensym &optional x +This function creates a new, uninterned symbol (using @code{make-symbol}) +with a unique name. (The name of an uninterned symbol is relevant +only if the symbol is printed.) By default, the name is generated +from an increasing sequence of numbers, @samp{G1000}, @samp{G1001}, +@samp{G1002}, etc. If the optional argument @var{x} is a string, that +string is used as a prefix instead of @samp{G}. Uninterned symbols +are used in macro expansions for temporary variables, to ensure that +their names will not conflict with ``real'' variables in the user's +code. +@end defun + +@defvar *gensym-counter* +This variable holds the counter used to generate @code{gensym} names. +It is incremented after each use by @code{gensym}. In Common Lisp +this is initialized with 0, but this package initializes it with a +random (time-dependent) value to avoid trouble when two files that +each used @code{gensym} in their compilation are loaded together. +(Uninterned symbols become interned when the compiler writes them +out to a file and the Emacs loader loads them, so their names have to +be treated a bit more carefully than in Common Lisp where uninterned +symbols remain uninterned after loading.) +@end defvar + +@defun gentemp &optional x +This function is like @code{gensym}, except that it produces a new +@emph{interned} symbol. If the symbol that is generated already +exists, the function keeps incrementing the counter and trying +again until a new symbol is generated. +@end defun + +The Quiroz @file{cl.el} package also defined a @code{defkeyword} +form for creating self-quoting keyword symbols. This package +automatically creates all keywords that are called for by +@code{&key} argument specifiers, and discourages the use of +keywords as data unrelated to keyword arguments, so the +@code{defkeyword} form has been discontinued. + +@iftex +@chapno=11 +@end iftex + +@node Numbers, Sequences, Symbols, Top +@chapter Numbers + +@noindent +This section defines a few simple Common Lisp operations on numbers +which were left out of Emacs Lisp. + +@menu +* Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc. +* Numerical Functions:: `abs', `expt', `floor*', etc. +* Random Numbers:: `random*', `make-random-state' +* Implementation Parameters:: `most-positive-fixnum', `most-positive-float' +@end menu + +@iftex +@secno=1 +@end iftex + +@node Predicates on Numbers, Numerical Functions, Numbers, Numbers +@section Predicates on Numbers + +@noindent +These functions return @code{t} if the specified condition is +true of the numerical argument, or @code{nil} otherwise. + +@defun plusp number +This predicate tests whether @var{number} is positive. It is an +error if the argument is not a number. +@end defun + +@defun minusp number +This predicate tests whether @var{number} is negative. It is an +error if the argument is not a number. +@end defun + +@defun oddp integer +This predicate tests whether @var{integer} is odd. It is an +error if the argument is not an integer. +@end defun + +@defun evenp integer +This predicate tests whether @var{integer} is even. It is an +error if the argument is not an integer. +@end defun + +@defun floatp-safe object +This predicate tests whether @var{object} is a floating-point +number. On systems that support floating-point, this is equivalent +to @code{floatp}. On other systems, this always returns @code{nil}. +@end defun + +@iftex +@secno=3 +@end iftex + +@node Numerical Functions, Random Numbers, Predicates on Numbers, Numbers +@section Numerical Functions + +@noindent +These functions perform various arithmetic operations on numbers. + +@defun abs number +This function returns the absolute value of @var{number}. (Newer +versions of Emacs provide this as a built-in function; this package +defines @code{abs} only for Emacs 18 versions which don't provide +it as a primitive.) +@end defun + +@defun expt base power +This function returns @var{base} raised to the power of @var{number}. +(Newer versions of Emacs provide this as a built-in function; this +package defines @code{expt} only for Emacs 18 versions which don't +provide it as a primitive.) +@end defun + +@defun gcd &rest integers +This function returns the Greatest Common Divisor of the arguments. +For one argument, it returns the absolute value of that argument. +For zero arguments, it returns zero. +@end defun + +@defun lcm &rest integers +This function returns the Least Common Multiple of the arguments. +For one argument, it returns the absolute value of that argument. +For zero arguments, it returns one. +@end defun + +@defun isqrt integer +This function computes the ``integer square root'' of its integer +argument, i.e., the greatest integer less than or equal to the true +square root of the argument. +@end defun + +@defun floor* number &optional divisor +This function implements the Common Lisp @code{floor} function. +It is called @code{floor*} to avoid name conflicts with the +simpler @code{floor} function built-in to Emacs 19. + +With one argument, @code{floor*} returns a list of two numbers: +The argument rounded down (toward minus infinity) to an integer, +and the ``remainder'' which would have to be added back to the +first return value to yield the argument again. If the argument +is an integer @var{x}, the result is always the list @code{(@var{x} 0)}. +If the argument is an Emacs 19 floating-point number, the first +result is a Lisp integer and the second is a Lisp float between +0 (inclusive) and 1 (exclusive). + +With two arguments, @code{floor*} divides @var{number} by +@var{divisor}, and returns the floor of the quotient and the +corresponding remainder as a list of two numbers. If +@code{(floor* @var{x} @var{y})} returns @code{(@var{q} @var{r})}, +then @code{@var{q}*@var{y} + @var{r} = @var{x}}, with @var{r} +between 0 (inclusive) and @var{r} (exclusive). Also, note +that @code{(floor* @var{x})} is exactly equivalent to +@code{(floor* @var{x} 1)}. + +This function is entirely compatible with Common Lisp's @code{floor} +function, except that it returns the two results in a list since +Emacs Lisp does not support multiple-valued functions. +@end defun + +@defun ceiling* number &optional divisor +This function implements the Common Lisp @code{ceiling} function, +which is analogous to @code{floor} except that it rounds the +argument or quotient of the arguments up toward plus infinity. +The remainder will be between 0 and minus @var{r}. +@end defun + +@defun truncate* number &optional divisor +This function implements the Common Lisp @code{truncate} function, +which is analogous to @code{floor} except that it rounds the +argument or quotient of the arguments toward zero. Thus it is +equivalent to @code{floor*} if the argument or quotient is +positive, or to @code{ceiling*} otherwise. The remainder has +the same sign as @var{number}. +@end defun + +@defun round* number &optional divisor +This function implements the Common Lisp @code{round} function, +which is analogous to @code{floor} except that it rounds the +argument or quotient of the arguments to the nearest integer. +In the case of a tie (the argument or quotient is exactly +halfway between two integers), it rounds to the even integer. +@end defun + +@defun mod* number divisor +This function returns the same value as the second return value +of @code{floor}. +@end defun + +@defun rem* number divisor +This function returns the same value as the second return value +of @code{truncate}. +@end defun + +These definitions are compatible with those in the Quiroz +@file{cl.el} package, except that this package appends @samp{*} +to certain function names to avoid conflicts with existing +Emacs 19 functions, and that the mechanism for returning +multiple values is different. + +@iftex +@secno=8 +@end iftex + +@node Random Numbers, Implementation Parameters, Numerical Functions, Numbers +@section Random Numbers + +@noindent +This package also provides an implementation of the Common Lisp +random number generator. It uses its own additive-congruential +algorithm, which is much more likely to give statistically clean +random numbers than the simple generators supplied by many +operating systems. + +@defun random* number &optional state +This function returns a random nonnegative number less than +@var{number}, and of the same type (either integer or floating-point). +The @var{state} argument should be a @code{random-state} object +which holds the state of the random number generator. The +function modifies this state object as a side effect. If +@var{state} is omitted, it defaults to the variable +@code{*random-state*}, which contains a pre-initialized +@code{random-state} object. +@end defun + +@defvar *random-state* +This variable contains the system ``default'' @code{random-state} +object, used for calls to @code{random*} that do not specify an +alternative state object. Since any number of programs in the +Emacs process may be accessing @code{*random-state*} in interleaved +fashion, the sequence generated from this variable will be +irreproducible for all intents and purposes. +@end defvar + +@defun make-random-state &optional state +This function creates or copies a @code{random-state} object. +If @var{state} is omitted or @code{nil}, it returns a new copy of +@code{*random-state*}. This is a copy in the sense that future +sequences of calls to @code{(random* @var{n})} and +@code{(random* @var{n} @var{s})} (where @var{s} is the new +random-state object) will return identical sequences of random +numbers. + +If @var{state} is a @code{random-state} object, this function +returns a copy of that object. If @var{state} is @code{t}, this +function returns a new @code{random-state} object seeded from the +date and time. As an extension to Common Lisp, @var{state} may also +be an integer in which case the new object is seeded from that +integer; each different integer seed will result in a completely +different sequence of random numbers. + +It is legal to print a @code{random-state} object to a buffer or +file and later read it back with @code{read}. If a program wishes +to use a sequence of pseudo-random numbers which can be reproduced +later for debugging, it can call @code{(make-random-state t)} to +get a new sequence, then print this sequence to a file. When the +program is later rerun, it can read the original run's random-state +from the file. +@end defun + +@defun random-state-p object +This predicate returns @code{t} if @var{object} is a +@code{random-state} object, or @code{nil} otherwise. +@end defun + +@node Implementation Parameters, , Random Numbers, Numbers +@section Implementation Parameters + +@noindent +This package defines several useful constants having to with numbers. + +@defvar most-positive-fixnum +This constant equals the largest value a Lisp integer can hold. +It is typically @code{2^23-1} or @code{2^25-1}. +@end defvar + +@defvar most-negative-fixnum +This constant equals the smallest (most negative) value a Lisp +integer can hold. +@end defvar + +The following parameters have to do with floating-point numbers. +This package determines their values by exercising the computer's +floating-point arithmetic in various ways. Because this operation +might be slow, the code for initializing them is kept in a separate +function that must be called before the parameters can be used. + +@defun cl-float-limits +This function makes sure that the Common Lisp floating-point +parameters like @code{most-positive-float} have been initialized. +Until it is called, these parameters will be @code{nil}. If this +version of Emacs does not support floats (e.g., most versions of +Emacs 18), the parameters will remain @code{nil}. If the parameters +have already been initialized, the function returns immediately. + +The algorithm makes assumptions that will be valid for most modern +machines, but will fail if the machine's arithmetic is extremely +unusual, e.g., decimal. +@end defun + +Since true Common Lisp supports up to four different floating-point +precisions, it has families of constants like +@code{most-positive-single-float}, @code{most-positive-double-float}, +@code{most-positive-long-float}, and so on. Emacs has only one +floating-point precision, so this package omits the precision word +from the constants' names. + +@defvar most-positive-float +This constant equals the largest value a Lisp float can hold. +For those systems whose arithmetic supports infinities, this is +the largest @emph{finite} value. For IEEE machines, the value +is approximately @code{1.79e+308}. +@end defvar + +@defvar most-negative-float +This constant equals the most-negative value a Lisp float can hold. +(It is assumed to be equal to @code{(- most-positive-float)}.) +@end defvar + +@defvar least-positive-float +This constant equals the smallest Lisp float value greater than zero. +For IEEE machines, it is about @code{4.94e-324} if denormals are +supported or @code{2.22e-308} if not. +@end defvar + +@defvar least-positive-normalized-float +This constant equals the smallest @emph{normalized} Lisp float greater +than zero, i.e., the smallest value for which IEEE denormalization +will not result in a loss of precision. For IEEE machines, this +value is about @code{2.22e-308}. For machines that do not support +the concept of denormalization and gradual underflow, this constant +will always equal @code{least-positive-float}. +@end defvar + +@defvar least-negative-float +This constant is the negative counterpart of @code{least-positive-float}. +@end defvar + +@defvar least-negative-normalized-float +This constant is the negative counterpart of +@code{least-positive-normalized-float}. +@end defvar + +@defvar float-epsilon +This constant is the smallest positive Lisp float that can be added +to 1.0 to produce a distinct value. Adding a smaller number to 1.0 +will yield 1.0 again due to roundoff. For IEEE machines, epsilon +is about @code{2.22e-16}. +@end defvar + +@defvar float-negative-epsilon +This is the smallest positive value that can be subtracted from +1.0 to produce a distinct value. For IEEE machines, it is about +@code{1.11e-16}. +@end defvar + +@iftex +@chapno=13 +@end iftex + +@node Sequences, Lists, Numbers, Top +@chapter Sequences + +@noindent +Common Lisp defines a number of functions that operate on +@dfn{sequences}, which are either lists, strings, or vectors. +Emacs Lisp includes a few of these, notably @code{elt} and +@code{length}; this package defines most of the rest. + +@menu +* Sequence Basics:: Arguments shared by all sequence functions +* Mapping over Sequences:: `mapcar*', `mapcan', `map', `every', etc. +* Sequence Functions:: `subseq', `remove*', `substitute', etc. +* Searching Sequences:: `find', `position', `count', `search', etc. +* Sorting Sequences:: `sort*', `stable-sort', `merge' +@end menu + +@node Sequence Basics, Mapping over Sequences, Sequences, Sequences +@section Sequence Basics + +@noindent +Many of the sequence functions take keyword arguments; @pxref{Argument +Lists}. All keyword arguments are optional and, if specified, +may appear in any order. + +The @code{:key} argument should be passed either @code{nil}, or a +function of one argument. This key function is used as a filter +through which the elements of the sequence are seen; for example, +@code{(find x y :key 'car)} is similar to @code{(assoc* x y)}: +It searches for an element of the list whose @code{car} equals +@code{x}, rather than for an element which equals @code{x} itself. +If @code{:key} is omitted or @code{nil}, the filter is effectively +the identity function. + +The @code{:test} and @code{:test-not} arguments should be either +@code{nil}, or functions of two arguments. The test function is +used to compare two sequence elements, or to compare a search value +with sequence elements. (The two values are passed to the test +function in the same order as the original sequence function +arguments from which they are derived, or, if they both come from +the same sequence, in the same order as they appear in that sequence.) +The @code{:test} argument specifies a function which must return +true (non-@code{nil}) to indicate a match; instead, you may use +@code{:test-not} to give a function which returns @emph{false} to +indicate a match. The default test function is @code{:test 'eql}. + +Many functions which take @var{item} and @code{:test} or @code{:test-not} +arguments also come in @code{-if} and @code{-if-not} varieties, +where a @var{predicate} function is passed instead of @var{item}, +and sequence elements match if the predicate returns true on them +(or false in the case of @code{-if-not}). For example: + +@example +(remove* 0 seq :test '=) @equiv{} (remove-if 'zerop seq) +@end example + +@noindent +to remove all zeros from sequence @code{seq}. + +Some operations can work on a subsequence of the argument sequence; +these function take @code{:start} and @code{:end} arguments which +default to zero and the length of the sequence, respectively. +Only elements between @var{start} (inclusive) and @var{end} +(exclusive) are affected by the operation. The @var{end} argument +may be passed @code{nil} to signify the length of the sequence; +otherwise, both @var{start} and @var{end} must be integers, with +@code{0 <= @var{start} <= @var{end} <= (length @var{seq})}. +If the function takes two sequence arguments, the limits are +defined by keywords @code{:start1} and @code{:end1} for the first, +and @code{:start2} and @code{:end2} for the second. + +A few functions accept a @code{:from-end} argument, which, if +non-@code{nil}, causes the operation to go from right-to-left +through the sequence instead of left-to-right, and a @code{:count} +argument, which specifies an integer maximum number of elements +to be removed or otherwise processed. + +The sequence functions make no guarantees about the order in +which the @code{:test}, @code{:test-not}, and @code{:key} functions +are called on various elements. Therefore, it is a bad idea to depend +on side effects of these functions. For example, @code{:from-end} +may cause the sequence to be scanned actually in reverse, or it may +be scanned forwards but computing a result ``as if'' it were scanned +backwards. (Some functions, like @code{mapcar*} and @code{every}, +@emph{do} specify exactly the order in which the function is called +so side effects are perfectly acceptable in those cases.) + +Strings in GNU Emacs 19 may contain ``text properties'' as well +as character data. Except as noted, it is undefined whether or +not text properties are preserved by sequence functions. For +example, @code{(remove* ?A @var{str})} may or may not preserve +the properties of the characters copied from @var{str} into the +result. + +@node Mapping over Sequences, Sequence Functions, Sequence Basics, Sequences +@section Mapping over Sequences + +@noindent +These functions ``map'' the function you specify over the elements +of lists or arrays. They are all variations on the theme of the +built-in function @code{mapcar}. + +@defun mapcar* function seq &rest more-seqs +This function calls @var{function} on successive parallel sets of +elements from its argument sequences. Given a single @var{seq} +argument it is equivalent to @code{mapcar}; given @var{n} sequences, +it calls the function with the first elements of each of the sequences +as the @var{n} arguments to yield the first element of the result +list, then with the second elements, and so on. The mapping stops as +soon as the shortest sequence runs out. The argument sequences may +be any mixture of lists, strings, and vectors; the return sequence +is always a list. + +Common Lisp's @code{mapcar} accepts multiple arguments but works +only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence +argument. This package's @code{mapcar*} works as a compatible +superset of both. +@end defun + +@defun map result-type function seq &rest more-seqs +This function maps @var{function} over the argument sequences, +just like @code{mapcar*}, but it returns a sequence of type +@var{result-type} rather than a list. @var{result-type} must +be one of the following symbols: @code{vector}, @code{string}, +@code{list} (in which case the effect is the same as for +@code{mapcar*}), or @code{nil} (in which case the results are +thrown away and @code{map} returns @code{nil}). +@end defun + +@defun maplist function list &rest more-lists +This function calls @var{function} on each of its argument lists, +then on the @code{cdr}s of those lists, and so on, until the +shortest list runs out. The results are returned in the form +of a list. Thus, @code{maplist} is like @code{mapcar*} except +that it passes in the list pointers themselves rather than the +@code{car}s of the advancing pointers. +@end defun + +@defun mapc function seq &rest more-seqs +This function is like @code{mapcar*}, except that the values +returned by @var{function} are ignored and thrown away rather +than being collected into a list. The return value of @code{mapc} +is @var{seq}, the first sequence. +@end defun + +@defun mapl function list &rest more-lists +This function is like @code{maplist}, except that it throws away +the values returned by @var{function}. +@end defun + +@defun mapcan function seq &rest more-seqs +This function is like @code{mapcar*}, except that it concatenates +the return values (which must be lists) using @code{nconc}, +rather than simply collecting them into a list. +@end defun + +@defun mapcon function list &rest more-lists +This function is like @code{maplist}, except that it concatenates +the return values using @code{nconc}. +@end defun + +@defun some predicate seq &rest more-seqs +This function calls @var{predicate} on each element of @var{seq} +in turn; if @var{predicate} returns a non-@code{nil} value, +@code{some} returns that value, otherwise it returns @code{nil}. +Given several sequence arguments, it steps through the sequences +in parallel until the shortest one runs out, just as in +@code{mapcar*}. You can rely on the left-to-right order in which +the elements are visited, and on the fact that mapping stops +immediately as soon as @var{predicate} returns non-@code{nil}. +@end defun + +@defun every predicate seq &rest more-seqs +This function calls @var{predicate} on each element of the sequence(s) +in turn; it returns @code{nil} as soon as @var{predicate} returns +@code{nil} for any element, or @code{t} if the predicate was true +for all elements. +@end defun + +@defun notany predicate seq &rest more-seqs +This function calls @var{predicate} on each element of the sequence(s) +in turn; it returns @code{nil} as soon as @var{predicate} returns +a non-@code{nil} value for any element, or @code{t} if the predicate +was @code{nil} for all elements. +@end defun + +@defun notevery predicate seq &rest more-seqs +This function calls @var{predicate} on each element of the sequence(s) +in turn; it returns a non-@code{nil} value as soon as @var{predicate} +returns @code{nil} for any element, or @code{t} if the predicate was +true for all elements. +@end defun + +@defun reduce function seq @t{&key :from-end :start :end :initial-value :key} +This function combines the elements of @var{seq} using an associative +binary operation. Suppose @var{function} is @code{*} and @var{seq} is +the list @code{(2 3 4 5)}. The first two elements of the list are +combined with @code{(* 2 3) = 6}; this is combined with the next +element, @code{(* 6 4) = 24}, and that is combined with the final +element: @code{(* 24 5) = 120}. Note that the @code{*} function happens +to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as +an explicit call to @code{reduce}. + +If @code{:from-end} is true, the reduction is right-associative instead +of left-associative: + +@example +(reduce '- '(1 2 3 4)) + @equiv{} (- (- (- 1 2) 3) 4) @result{} -8 +(reduce '- '(1 2 3 4) :from-end t) + @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2 +@end example + +If @code{:key} is specified, it is a function of one argument which +is called on each of the sequence elements in turn. + +If @code{:initial-value} is specified, it is effectively added to the +front (or rear in the case of @code{:from-end}) of the sequence. +The @code{:key} function is @emph{not} applied to the initial value. + +If the sequence, including the initial value, has exactly one element +then that element is returned without ever calling @var{function}. +If the sequence is empty (and there is no initial value), then +@var{function} is called with no arguments to obtain the return value. +@end defun + +All of these mapping operations can be expressed conveniently in +terms of the @code{loop} macro. In compiled code, @code{loop} will +be faster since it generates the loop as in-line code with no +function calls. + +@node Sequence Functions, Searching Sequences, Mapping over Sequences, Sequences +@section Sequence Functions + +@noindent +This section describes a number of Common Lisp functions for +operating on sequences. + +@defun subseq sequence start &optional end +This function returns a given subsequence of the argument +@var{sequence}, which may be a list, string, or vector. +The indices @var{start} and @var{end} must be in range, and +@var{start} must be no greater than @var{end}. If @var{end} +is omitted, it defaults to the length of the sequence. The +return value is always a copy; it does not share structure +with @var{sequence}. + +As an extension to Common Lisp, @var{start} and/or @var{end} +may be negative, in which case they represent a distance back +from the end of the sequence. This is for compatibility with +Emacs' @code{substring} function. Note that @code{subseq} is +the @emph{only} sequence function that allows negative +@var{start} and @var{end}. + +You can use @code{setf} on a @code{subseq} form to replace a +specified range of elements with elements from another sequence. +The replacement is done as if by @code{replace}, described below. +@end defun + +@defun concatenate result-type &rest seqs +This function concatenates the argument sequences together to +form a result sequence of type @var{result-type}, one of the +symbols @code{vector}, @code{string}, or @code{list}. The +arguments are always copied, even in cases such as +@code{(concatenate 'list '(1 2 3))} where the result is +identical to an argument. +@end defun + +@defun fill seq item @t{&key :start :end} +This function fills the elements of the sequence (or the specified +part of the sequence) with the value @var{item}. +@end defun + +@defun replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2} +This function copies part of @var{seq2} into part of @var{seq1}. +The sequence @var{seq1} is not stretched or resized; the amount +of data copied is simply the shorter of the source and destination +(sub)sequences. The function returns @var{seq1}. + +If @var{seq1} and @var{seq2} are @code{eq}, then the replacement +will work correctly even if the regions indicated by the start +and end arguments overlap. However, if @var{seq1} and @var{seq2} +are lists which share storage but are not @code{eq}, and the +start and end arguments specify overlapping regions, the effect +is undefined. +@end defun + +@defun remove* item seq @t{&key :test :test-not :key :count :start :end :from-end} +This returns a copy of @var{seq} with all elements matching +@var{item} removed. The result may share storage with or be +@code{eq} to @var{seq} in some circumstances, but the original +@var{seq} will not be modified. The @code{:test}, @code{:test-not}, +and @code{:key} arguments define the matching test that is used; +by default, elements @code{eql} to @var{item} are removed. The +@code{:count} argument specifies the maximum number of matching +elements that can be removed (only the leftmost @var{count} matches +are removed). The @code{:start} and @code{:end} arguments specify +a region in @var{seq} in which elements will be removed; elements +outside that region are not matched or removed. The @code{:from-end} +argument, if true, says that elements should be deleted from the +end of the sequence rather than the beginning (this matters only +if @var{count} was also specified). +@end defun + +@defun delete* item seq @t{&key :test :test-not :key :count :start :end :from-end} +This deletes all elements of @var{seq} which match @var{item}. +It is a destructive operation. Since Emacs Lisp does not support +stretchable strings or vectors, this is the same as @code{remove*} +for those sequence types. On lists, @code{remove*} will copy the +list if necessary to preserve the original list, whereas +@code{delete*} will splice out parts of the argument list. +Compare @code{append} and @code{nconc}, which are analogous +non-destructive and destructive list operations in Emacs Lisp. +@end defun + +@findex remove-if +@findex remove-if-not +@findex delete-if +@findex delete-if-not +The predicate-oriented functions @code{remove-if}, @code{remove-if-not}, +@code{delete-if}, and @code{delete-if-not} are defined similarly. + +@defun delete item list +This MacLisp-compatible function deletes from @var{list} all elements +which are @code{equal} to @var{item}. The @code{delete} function is +built-in to Emacs 19; this package defines it equivalently in Emacs 18. +@end defun + +@defun remove item list +This function removes from @var{list} all elements which are +@code{equal} to @var{item}. This package defines it for symmetry +with @code{delete}, even though @code{remove} is not built-in to +Emacs 19. +@end defun + +@defun remq item list +This function removes from @var{list} all elements which are +@code{eq} to @var{item}. This package defines it for symmetry +with @code{delq}, even though @code{remq} is not built-in to +Emacs 19. +@end defun + +@defun remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end} +This function returns a copy of @var{seq} with duplicate elements +removed. Specifically, if two elements from the sequence match +according to the @code{:test}, @code{:test-not}, and @code{:key} +arguments, only the rightmost one is retained. If @code{:from-end} +is true, the leftmost one is retained instead. If @code{:start} or +@code{:end} is specified, only elements within that subsequence are +examined or removed. +@end defun + +@defun delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end} +This function deletes duplicate elements from @var{seq}. It is +a destructive version of @code{remove-duplicates}. +@end defun + +@defun substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end} +This function returns a copy of @var{seq}, with all elements +matching @var{old} replaced with @var{new}. The @code{:count}, +@code{:start}, @code{:end}, and @code{:from-end} arguments may be +used to limit the number of substitutions made. +@end defun + +@defun nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end} +This is a destructive version of @code{substitute}; it performs +the substitution using @code{setcar} or @code{aset} rather than +by returning a changed copy of the sequence. +@end defun + +@findex substitute-if +@findex substitute-if-not +@findex nsubstitute-if +@findex nsubstitute-if-not +The @code{substitute-if}, @code{substitute-if-not}, @code{nsubstitute-if}, +and @code{nsubstitute-if-not} functions are defined similarly. For +these, a @var{predicate} is given in place of the @var{old} argument. + +@node Searching Sequences, Sorting Sequences, Sequence Functions, Sequences +@section Searching Sequences + +@noindent +These functions search for elements or subsequences in a sequence. +(See also @code{member*} and @code{assoc*}; @pxref{Lists}.) + +@defun find item seq @t{&key :test :test-not :key :start :end :from-end} +This function searches @var{seq} for an element matching @var{item}. +If it finds a match, it returns the matching element. Otherwise, +it returns @code{nil}. It returns the leftmost match, unless +@code{:from-end} is true, in which case it returns the rightmost +match. The @code{:start} and @code{:end} arguments may be used to +limit the range of elements that are searched. +@end defun + +@defun position item seq @t{&key :test :test-not :key :start :end :from-end} +This function is like @code{find}, except that it returns the +integer position in the sequence of the matching item rather than +the item itself. The position is relative to the start of the +sequence as a whole, even if @code{:start} is non-zero. The function +returns @code{nil} if no matching element was found. +@end defun + +@defun count item seq @t{&key :test :test-not :key :start :end} +This function returns the number of elements of @var{seq} which +match @var{item}. The result is always a nonnegative integer. +@end defun + +@findex find-if +@findex find-if-not +@findex position-if +@findex position-if-not +@findex count-if +@findex count-if-not +The @code{find-if}, @code{find-if-not}, @code{position-if}, +@code{position-if-not}, @code{count-if}, and @code{count-if-not} +functions are defined similarly. + +@defun mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end} +This function compares the specified parts of @var{seq1} and +@var{seq2}. If they are the same length and the corresponding +elements match (according to @code{:test}, @code{:test-not}, +and @code{:key}), the function returns @code{nil}. If there is +a mismatch, the function returns the index (relative to @var{seq1}) +of the first mismatching element. This will be the leftmost pair of +elements which do not match, or the position at which the shorter of +the two otherwise-matching sequences runs out. + +If @code{:from-end} is true, then the elements are compared from right +to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}. +If the sequences differ, then one plus the index of the rightmost +difference (relative to @var{seq1}) is returned. + +An interesting example is @code{(mismatch str1 str2 :key 'upcase)}, +which compares two strings case-insensitively. +@end defun + +@defun search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2} +This function searches @var{seq2} for a subsequence that matches +@var{seq1} (or part of it specified by @code{:start1} and +@code{:end1}.) Only matches which fall entirely within the region +defined by @code{:start2} and @code{:end2} will be considered. +The return value is the index of the leftmost element of the +leftmost match, relative to the start of @var{seq2}, or @code{nil} +if no matches were found. If @code{:from-end} is true, the +function finds the @emph{rightmost} matching subsequence. +@end defun + +@node Sorting Sequences, , Searching Sequences, Sequences +@section Sorting Sequences + +@defun sort* seq predicate @t{&key :key} +This function sorts @var{seq} into increasing order as determined +by using @var{predicate} to compare pairs of elements. @var{predicate} +should return true (non-@code{nil}) if and only if its first argument +is less than (not equal to) its second argument. For example, +@code{<} and @code{string-lessp} are suitable predicate functions +for sorting numbers and strings, respectively; @code{>} would sort +numbers into decreasing rather than increasing order. + +This function differs from Emacs' built-in @code{sort} in that it +can operate on any type of sequence, not just lists. Also, it +accepts a @code{:key} argument which is used to preprocess data +fed to the @var{predicate} function. For example, + +@example +(setq data (sort data 'string-lessp :key 'downcase)) +@end example + +@noindent +sorts @var{data}, a sequence of strings, into increasing alphabetical +order without regard to case. A @code{:key} function of @code{car} +would be useful for sorting association lists. + +The @code{sort*} function is destructive; it sorts lists by actually +rearranging the @code{cdr} pointers in suitable fashion. +@end defun + +@defun stable-sort seq predicate @t{&key :key} +This function sorts @var{seq} @dfn{stably}, meaning two elements +which are equal in terms of @var{predicate} are guaranteed not to +be rearranged out of their original order by the sort. + +In practice, @code{sort*} and @code{stable-sort} are equivalent +in Emacs Lisp because the underlying @code{sort} function is +stable by default. However, this package reserves the right to +use non-stable methods for @code{sort*} in the future. +@end defun + +@defun merge type seq1 seq2 predicate @t{&key :key} +This function merges two sequences @var{seq1} and @var{seq2} by +interleaving their elements. The result sequence, of type @var{type} +(in the sense of @code{concatenate}), has length equal to the sum +of the lengths of the two input sequences. The sequences may be +modified destructively. Order of elements within @var{seq1} and +@var{seq2} is preserved in the interleaving; elements of the two +sequences are compared by @var{predicate} (in the sense of +@code{sort}) and the lesser element goes first in the result. +When elements are equal, those from @var{seq1} precede those from +@var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are +both sorted according to @var{predicate}, then the result will be +a merged sequence which is (stably) sorted according to +@var{predicate}. +@end defun + +@node Lists, Hash Tables, Sequences, Top +@chapter Lists + +@noindent +The functions described here operate on lists. + +@menu +* List Functions:: `caddr', `first', `last*', `list*', etc. +* Substitution of Expressions:: `subst', `sublis', etc. +* Lists as Sets:: `member*', `adjoin', `union', etc. +* Association Lists:: `assoc*', `rassoc*', `acons', `pairlis' +@end menu + +@node List Functions, Substitution of Expressions, Lists, Lists +@section List Functions + +@noindent +This section describes a number of simple operations on lists, +i.e., chains of cons cells. + +@defun caddr x +This function is equivalent to @code{(car (cdr (cdr @var{x})))}. +Likewise, this package defines all 28 @code{c@var{xxx}r} functions +where @var{xxx} is up to four @samp{a}s and/or @samp{d}s. +All of these functions are @code{setf}-able, and calls to them +are expanded inline by the byte-compiler for maximum efficiency. +@end defun + +@defun first x +This function is a synonym for @code{(car @var{x})}. Likewise, +the functions @code{second}, @code{third}, @dots{}, through +@code{tenth} return the given element of the list @var{x}. +@end defun + +@defun rest x +This function is a synonym for @code{(cdr @var{x})}. +@end defun + +@defun endp x +Common Lisp defines this function to act like @code{null}, but +signaling an error if @code{x} is neither a @code{nil} nor a +cons cell. This package simply defines @code{endp} as a synonym +for @code{null}. +@end defun + +@defun list-length x +This function returns the length of list @var{x}, exactly like +@code{(length @var{x})}, except that if @var{x} is a circular +list (where the cdr-chain forms a loop rather than terminating +with @code{nil}), this function returns @code{nil}. (The regular +@code{length} function would get stuck if given a circular list.) +@end defun + +@defun last* x &optional n +This function returns the last cons, or the @var{n}th-to-last cons, +of the list @var{x}. If @var{n} is omitted it defaults to 1. +The ``last cons'' means the first cons cell of the list whose +@code{cdr} is not another cons cell. (For normal lists, the +@code{cdr} of the last cons will be @code{nil}.) This function +returns @code{nil} if @var{x} is @code{nil} or shorter than +@var{n}. Note that the last @emph{element} of the list is +@code{(car (last @var{x}))}. + +The Emacs function @code{last} does the same thing +except that it does not handle the optional argument @var{n}. +@end defun + +@defun butlast x &optional n +This function returns the list @var{x} with the last element, +or the last @var{n} elements, removed. If @var{n} is greater +than zero it makes a copy of the list so as not to damage the +original list. In general, @code{(append (butlast @var{x} @var{n}) +(last @var{x} @var{n}))} will return a list equal to @var{x}. +@end defun + +@defun nbutlast x &optional n +This is a version of @code{butlast} that works by destructively +modifying the @code{cdr} of the appropriate element, rather than +making a copy of the list. +@end defun + +@defun list* arg &rest others +This function constructs a list of its arguments. The final +argument becomes the @code{cdr} of the last cell constructed. +Thus, @code{(list* @var{a} @var{b} @var{c})} is equivalent to +@code{(cons @var{a} (cons @var{b} @var{c}))}, and +@code{(list* @var{a} @var{b} nil)} is equivalent to +@code{(list @var{a} @var{b})}. + +(Note that this function really is called @code{list*} in Common +Lisp; it is not a name invented for this package like @code{member*} +or @code{defun*}.) +@end defun + +@defun ldiff list sublist +If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to +one of the cons cells of @var{list}, then this function returns +a copy of the part of @var{list} up to but not including +@var{sublist}. For example, @code{(ldiff x (cddr x))} returns +the first two elements of the list @code{x}. The result is a +copy; the original @var{list} is not modified. If @var{sublist} +is not a sublist of @var{list}, a copy of the entire @var{list} +is returned. +@end defun + +@defun copy-list list +This function returns a copy of the list @var{list}. It copies +dotted lists like @code{(1 2 . 3)} correctly. +@end defun + +@defun copy-tree x &optional vecp +This function returns a copy of the tree of cons cells @var{x}. +Unlike @code{copy-sequence} (and its alias @code{copy-list}), +which copies only along the @code{cdr} direction, this function +copies (recursively) along both the @code{car} and the @code{cdr} +directions. If @var{x} is not a cons cell, the function simply +returns @var{x} unchanged. If the optional @var{vecp} argument +is true, this function copies vectors (recursively) as well as +cons cells. +@end defun + +@defun tree-equal x y @t{&key :test :test-not :key} +This function compares two trees of cons cells. If @var{x} and +@var{y} are both cons cells, their @code{car}s and @code{cdr}s are +compared recursively. If neither @var{x} nor @var{y} is a cons +cell, they are compared by @code{eql}, or according to the +specified test. The @code{:key} function, if specified, is +applied to the elements of both trees. @xref{Sequences}. +@end defun + +@iftex +@secno=3 +@end iftex + +@node Substitution of Expressions, Lists as Sets, List Functions, Lists +@section Substitution of Expressions + +@noindent +These functions substitute elements throughout a tree of cons +cells. (@xref{Sequence Functions}, for the @code{substitute} +function, which works on just the top-level elements of a list.) + +@defun subst new old tree @t{&key :test :test-not :key} +This function substitutes occurrences of @var{old} with @var{new} +in @var{tree}, a tree of cons cells. It returns a substituted +tree, which will be a copy except that it may share storage with +the argument @var{tree} in parts where no substitutions occurred. +The original @var{tree} is not modified. This function recurses +on, and compares against @var{old}, both @code{car}s and @code{cdr}s +of the component cons cells. If @var{old} is itself a cons cell, +then matching cells in the tree are substituted as usual without +recursively substituting in that cell. Comparisons with @var{old} +are done according to the specified test (@code{eql} by default). +The @code{:key} function is applied to the elements of the tree +but not to @var{old}. +@end defun + +@defun nsubst new old tree @t{&key :test :test-not :key} +This function is like @code{subst}, except that it works by +destructive modification (by @code{setcar} or @code{setcdr}) +rather than copying. +@end defun + +@findex subst-if +@findex subst-if-not +@findex nsubst-if +@findex nsubst-if-not +The @code{subst-if}, @code{subst-if-not}, @code{nsubst-if}, and +@code{nsubst-if-not} functions are defined similarly. + +@defun sublis alist tree @t{&key :test :test-not :key} +This function is like @code{subst}, except that it takes an +association list @var{alist} of @var{old}-@var{new} pairs. +Each element of the tree (after applying the @code{:key} +function, if any), is compared with the @code{car}s of +@var{alist}; if it matches, it is replaced by the corresponding +@code{cdr}. +@end defun + +@defun nsublis alist tree @t{&key :test :test-not :key} +This is a destructive version of @code{sublis}. +@end defun + +@node Lists as Sets, Association Lists, Substitution of Expressions, Lists +@section Lists as Sets + +@noindent +These functions perform operations on lists which represent sets +of elements. + +@defun member item list +This MacLisp-compatible function searches @var{list} for an element +which is @code{equal} to @var{item}. The @code{member} function is +built-in to Emacs 19; this package defines it equivalently in Emacs 18. +See the following function for a Common-Lisp compatible version. +@end defun + +@defun member* item list @t{&key :test :test-not :key} +This function searches @var{list} for an element matching @var{item}. +If a match is found, it returns the cons cell whose @code{car} was +the matching element. Otherwise, it returns @code{nil}. Elements +are compared by @code{eql} by default; you can use the @code{:test}, +@code{:test-not}, and @code{:key} arguments to modify this behavior. +@xref{Sequences}. + +Note that this function's name is suffixed by @samp{*} to avoid +the incompatible @code{member} function defined in Emacs 19. +(That function uses @code{equal} for comparisons; it is equivalent +to @code{(member* @var{item} @var{list} :test 'equal)}.) +@end defun + +@findex member-if +@findex member-if-not +The @code{member-if} and @code{member-if-not} functions +analogously search for elements which satisfy a given predicate. + +@defun tailp sublist list +This function returns @code{t} if @var{sublist} is a sublist of +@var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to +any of its @code{cdr}s. +@end defun + +@defun adjoin item list @t{&key :test :test-not :key} +This function conses @var{item} onto the front of @var{list}, +like @code{(cons @var{item} @var{list})}, but only if @var{item} +is not already present on the list (as determined by @code{member*}). +If a @code{:key} argument is specified, it is applied to +@var{item} as well as to the elements of @var{list} during +the search, on the reasoning that @var{item} is ``about'' to +become part of the list. +@end defun + +@defun union list1 list2 @t{&key :test :test-not :key} +This function combines two lists which represent sets of items, +returning a list that represents the union of those two sets. +The result list will contain all items which appear in @var{list1} +or @var{list2}, and no others. If an item appears in both +@var{list1} and @var{list2} it will be copied only once. If +an item is duplicated in @var{list1} or @var{list2}, it is +undefined whether or not that duplication will survive in the +result list. The order of elements in the result list is also +undefined. +@end defun + +@defun nunion list1 list2 @t{&key :test :test-not :key} +This is a destructive version of @code{union}; rather than copying, +it tries to reuse the storage of the argument lists if possible. +@end defun + +@defun intersection list1 list2 @t{&key :test :test-not :key} +This function computes the intersection of the sets represented +by @var{list1} and @var{list2}. It returns the list of items +which appear in both @var{list1} and @var{list2}. +@end defun + +@defun nintersection list1 list2 @t{&key :test :test-not :key} +This is a destructive version of @code{intersection}. It +tries to reuse storage of @var{list1} rather than copying. +It does @emph{not} reuse the storage of @var{list2}. +@end defun + +@defun set-difference list1 list2 @t{&key :test :test-not :key} +This function computes the ``set difference'' of @var{list1} +and @var{list2}, i.e., the set of elements that appear in +@var{list1} but @emph{not} in @var{list2}. +@end defun + +@defun nset-difference list1 list2 @t{&key :test :test-not :key} +This is a destructive @code{set-difference}, which will try +to reuse @var{list1} if possible. +@end defun + +@defun set-exclusive-or list1 list2 @t{&key :test :test-not :key} +This function computes the ``set exclusive or'' of @var{list1} +and @var{list2}, i.e., the set of elements that appear in +exactly one of @var{list1} and @var{list2}. +@end defun + +@defun nset-exclusive-or list1 list2 @t{&key :test :test-not :key} +This is a destructive @code{set-exclusive-or}, which will try +to reuse @var{list1} and @var{list2} if possible. +@end defun + +@defun subsetp list1 list2 @t{&key :test :test-not :key} +This function checks whether @var{list1} represents a subset +of @var{list2}, i.e., whether every element of @var{list1} +also appears in @var{list2}. +@end defun + +@node Association Lists, , Lists as Sets, Lists +@section Association Lists + +@noindent +An @dfn{association list} is a list representing a mapping from +one set of values to another; any list whose elements are cons +cells is an association list. + +@defun assoc* item a-list @t{&key :test :test-not :key} +This function searches the association list @var{a-list} for an +element whose @code{car} matches (in the sense of @code{:test}, +@code{:test-not}, and @code{:key}, or by comparison with @code{eql}) +a given @var{item}. It returns the matching element, if any, +otherwise @code{nil}. It ignores elements of @var{a-list} which +are not cons cells. (This corresponds to the behavior of +@code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's +@code{assoc} ignores @code{nil}s but considers any other non-cons +elements of @var{a-list} to be an error.) +@end defun + +@defun rassoc* item a-list @t{&key :test :test-not :key} +This function searches for an element whose @code{cdr} matches +@var{item}. If @var{a-list} represents a mapping, this applies +the inverse of the mapping to @var{item}. +@end defun + +@defun rassoc item a-list +This function searches like @code{rassoc*} with a @code{:test} +argument of @code{equal}. It is analogous to Emacs Lisp's +standard @code{assoc} function, which derives from the MacLisp +rather than the Common Lisp tradition. +@end defun + +@findex assoc-if +@findex assoc-if-not +@findex rassoc-if +@findex rassoc-if-not +The @code{assoc-if}, @code{assoc-if-not}, @code{rassoc-if}, +and @code{rassoc-if-not} functions are defined similarly. + +Two simple functions for constructing association lists are: + +@defun acons key value alist +This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}. +@end defun + +@defun pairlis keys values &optional alist +This is equivalent to @code{(nconc (mapcar* 'cons @var{keys} @var{values}) +@var{alist})}. +@end defun + +@node Hash Tables, Structures, Lists, Top +@chapter Hash Tables + +@noindent +A @dfn{hash table} is a data structure that maps ``keys'' onto +``values.'' Keys and values can be arbitrary Lisp data objects. +Hash tables have the property that the time to search for a given +key is roughly constant; simpler data structures like association +lists take time proportional to the number of entries in the list. + +@defun make-hash-table @t{&key :test :size} +This function creates and returns a hash-table object whose +function for comparing elements is @code{:test} (@code{eql} +by default), and which is allocated to fit about @code{:size} +elements. The @code{:size} argument is purely advisory; the +table will stretch automatically if you store more elements in +it. If @code{:size} is omitted, a reasonable default is used. + +Common Lisp allows only @code{eq}, @code{eql}, @code{equal}, +and @code{equalp} as legal values for the @code{:test} argument. +In this package, any reasonable predicate function will work, +though if you use something else you should check the details of +the hashing function described below to make sure it is suitable +for your predicate. + +Some versions of Emacs (like Lucid Emacs 19) include a built-in +hash table type; in these versions, @code{make-hash-table} with +a test of @code{eq} will use these built-in hash tables. In all +other cases, it will return a hash-table object which takes the +form of a list with an identifying ``tag'' symbol at the front. +All of the hash table functions in this package can operate on +both types of hash table; normally you will never know which +type is being used. + +This function accepts the additional Common Lisp keywords +@code{:rehash-size} and @code{:rehash-threshold}, but it ignores +their values. +@end defun + +@defun gethash key table &optional default +This function looks up @var{key} in @var{table}. If @var{key} +exists in the table, in the sense that it matches any of the existing +keys according to the table's test function, then the associated value +is returned. Otherwise, @var{default} (or @code{nil}) is returned. + +To store new data in the hash table, use @code{setf} on a call to +@code{gethash}. If @var{key} already exists in the table, the +corresponding value is changed to the stored value. If @var{key} +does not already exist, a new entry is added to the table and the +table is reallocated to a larger size if necessary. The @var{default} +argument is allowed but ignored in this case. The situation is +exactly analogous to that of @code{get*}; @pxref{Property Lists}. +@end defun + +@defun remhash key table +This function removes the entry for @var{key} from @var{table}. +If an entry was removed, it returns @code{t}. If @var{key} does +not appear in the table, it does nothing and returns @code{nil}. +@end defun + +@defun clrhash table +This function removes all the entries from @var{table}, leaving +an empty hash table. +@end defun + +@defun maphash function table +This function calls @var{function} for each entry in @var{table}. +It passes two arguments to @var{function}, the key and the value +of the given entry. The return value of @var{function} is ignored; +@var{maphash} itself returns @code{nil}. @xref{Loop Facility}, for +an alternate way of iterating over hash tables. +@end defun + +@defun hash-table-count table +This function returns the number of entries in @var{table}. +@strong{Warning:} The current implementation of Lucid Emacs 19 +hash-tables does not decrement the stored @code{count} when +@code{remhash} removes an entry. Therefore, the return value of +this function is not dependable if you have used @code{remhash} +on the table and the table's test is @code{eq}. A slower, but +reliable, way to count the entries is @code{(loop for x being the +hash-keys of @var{table} count t)}. +@end defun + +@defun hash-table-p object +This function returns @code{t} if @var{object} is a hash table, +@code{nil} otherwise. It recognizes both types of hash tables +(both Lucid Emacs built-in tables and tables implemented with +special lists.) +@end defun + +Sometimes when dealing with hash tables it is useful to know the +exact ``hash function'' that is used. This package implements +hash tables using Emacs Lisp ``obarrays,'' which are the same +data structure that Emacs Lisp uses to keep track of symbols. +Each hash table includes an embedded obarray. Key values given +to @code{gethash} are converted by various means into strings, +which are then looked up in the obarray using @code{intern} and +@code{intern-soft}. The symbol, or ``bucket,'' corresponding to +a given key string includes as its @code{symbol-value} an association +list of all key-value pairs which hash to that string. Depending +on the test function, it is possible for many entries to hash to +the same bucket. For example, if the test is @code{eql}, then the +symbol @code{foo} and two separately built strings @code{"foo"} will +create three entries in the same bucket. Search time is linear +within buckets, so hash tables will be most effective if you arrange +not to store too many things that hash the same. + +The following algorithm is used to convert Lisp objects to hash +strings: + +@itemize @bullet +@item +Strings are used directly as hash strings. (However, if the test +function is @code{equalp}, strings are @code{downcase}d first.) + +@item +Symbols are hashed according to their @code{symbol-name}. + +@item +Integers are hashed into one of 16 buckets depending on their value +modulo 16. Floating-point numbers are truncated to integers and +hashed modulo 16. + +@item +Cons cells are hashed according to their @code{car}s; nonempty vectors +are hashed according to their first element. + +@item +All other types of objects hash into a single bucket named @code{"*"}. +@end itemize + +@noindent +Thus, for example, searching among many buffer objects in a hash table +will devolve to a (still fairly fast) linear-time search through a +single bucket, whereas searching for different symbols will be very +fast since each symbol will, in general, hash into its own bucket. + +The size of the obarray in a hash table is automatically adjusted +as the number of elements increases. + +As a special case, @code{make-hash-table} with a @code{:size} argument +of 0 or 1 will create a hash-table object that uses a single association +list rather than an obarray of many lists. For very small tables this +structure will be more efficient since lookup does not require +converting the key to a string or looking it up in an obarray. +However, such tables are guaranteed to take time proportional to +their size to do a search. + +@iftex +@chapno=18 +@end iftex + +@node Structures, Assertions, Hash Tables, Top +@chapter Structures + +@noindent +The Common Lisp @dfn{structure} mechanism provides a general way +to define data types similar to C's @code{struct} types. A +structure is a Lisp object containing some number of @dfn{slots}, +each of which can hold any Lisp data object. Functions are +provided for accessing and setting the slots, creating or copying +structure objects, and recognizing objects of a particular structure +type. + +In true Common Lisp, each structure type is a new type distinct +from all existing Lisp types. Since the underlying Emacs Lisp +system provides no way to create new distinct types, this package +implements structures as vectors (or lists upon request) with a +special ``tag'' symbol to identify them. + +@defspec defstruct name slots@dots{} +The @code{defstruct} form defines a new structure type called +@var{name}, with the specified @var{slots}. (The @var{slots} +may begin with a string which documents the structure type.) +In the simplest case, @var{name} and each of the @var{slots} +are symbols. For example, + +@example +(defstruct person name age sex) +@end example + +@noindent +defines a struct type called @code{person} which contains three +slots. Given a @code{person} object @var{p}, you can access those +slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})}, +and @code{(person-sex @var{p})}. You can also change these slots by +using @code{setf} on any of these place forms: + +@example +(incf (person-age birthday-boy)) +@end example + +You can create a new @code{person} by calling @code{make-person}, +which takes keyword arguments @code{:name}, @code{:age}, and +@code{:sex} to specify the initial values of these slots in the +new object. (Omitting any of these arguments leaves the corresponding +slot ``undefined,'' according to the Common Lisp standard; in Emacs +Lisp, such uninitialized slots are filled with @code{nil}.) + +Given a @code{person}, @code{(copy-person @var{p})} makes a new +object of the same type whose slots are @code{eq} to those of @var{p}. + +Given any Lisp object @var{x}, @code{(person-p @var{x})} returns +true if @var{x} looks like a @code{person}, false otherwise. (Again, +in Common Lisp this predicate would be exact; in Emacs Lisp the +best it can do is verify that @var{x} is a vector of the correct +length which starts with the correct tag symbol.) + +Accessors like @code{person-name} normally check their arguments +(effectively using @code{person-p}) and signal an error if the +argument is the wrong type. This check is affected by +@code{(optimize (safety @dots{}))} declarations. Safety level 1, +the default, uses a somewhat optimized check that will detect all +incorrect arguments, but may use an uninformative error message +(e.g., ``expected a vector'' instead of ``expected a @code{person}''). +Safety level 0 omits all checks except as provided by the underlying +@code{aref} call; safety levels 2 and 3 do rigorous checking that will +always print a descriptive error message for incorrect inputs. +@xref{Declarations}. + +@example +(setq dave (make-person :name "Dave" :sex 'male)) + @result{} [cl-struct-person "Dave" nil male] +(setq other (copy-person dave)) + @result{} [cl-struct-person "Dave" nil male] +(eq dave other) + @result{} nil +(eq (person-name dave) (person-name other)) + @result{} t +(person-p dave) + @result{} t +(person-p [1 2 3 4]) + @result{} nil +(person-p "Bogus") + @result{} nil +(person-p '[cl-struct-person counterfeit person object]) + @result{} t +@end example + +In general, @var{name} is either a name symbol or a list of a name +symbol followed by any number of @dfn{struct options}; each @var{slot} +is either a slot symbol or a list of the form @samp{(@var{slot-name} +@var{default-value} @var{slot-options}@dots{})}. The @var{default-value} +is a Lisp form which is evaluated any time an instance of the +structure type is created without specifying that slot's value. + +Common Lisp defines several slot options, but the only one +implemented in this package is @code{:read-only}. A non-@code{nil} +value for this option means the slot should not be @code{setf}-able; +the slot's value is determined when the object is created and does +not change afterward. + +@example +(defstruct person + (name nil :read-only t) + age + (sex 'unknown)) +@end example + +Any slot options other than @code{:read-only} are ignored. + +For obscure historical reasons, structure options take a different +form than slot options. A structure option is either a keyword +symbol, or a list beginning with a keyword symbol possibly followed +by arguments. (By contrast, slot options are key-value pairs not +enclosed in lists.) + +@example +(defstruct (person (:constructor create-person) + (:type list) + :named) + name age sex) +@end example + +The following structure options are recognized. + +@table @code +@iftex +@itemmax=0 in +@advance@leftskip-.5@tableindent +@end iftex +@item :conc-name +The argument is a symbol whose print name is used as the prefix for +the names of slot accessor functions. The default is the name of +the struct type followed by a hyphen. The option @code{(:conc-name p-)} +would change this prefix to @code{p-}. Specifying @code{nil} as an +argument means no prefix, so that the slot names themselves are used +to name the accessor functions. + +@item :constructor +In the simple case, this option takes one argument which is an +alternate name to use for the constructor function. The default +is @code{make-@var{name}}, e.g., @code{make-person}. The above +example changes this to @code{create-person}. Specifying @code{nil} +as an argument means that no standard constructor should be +generated at all. + +In the full form of this option, the constructor name is followed +by an arbitrary argument list. @xref{Program Structure}, for a +description of the format of Common Lisp argument lists. All +options, such as @code{&rest} and @code{&key}, are supported. +The argument names should match the slot names; each slot is +initialized from the corresponding argument. Slots whose names +do not appear in the argument list are initialized based on the +@var{default-value} in their slot descriptor. Also, @code{&optional} +and @code{&key} arguments which don't specify defaults take their +defaults from the slot descriptor. It is legal to include arguments +which don't correspond to slot names; these are useful if they are +referred to in the defaults for optional, keyword, or @code{&aux} +arguments which @emph{do} correspond to slots. + +You can specify any number of full-format @code{:constructor} +options on a structure. The default constructor is still generated +as well unless you disable it with a simple-format @code{:constructor} +option. + +@example +(defstruct + (person + (:constructor nil) ; no default constructor + (:constructor new-person (name sex &optional (age 0))) + (:constructor new-hound (&key (name "Rover") + (dog-years 0) + &aux (age (* 7 dog-years)) + (sex 'canine)))) + name age sex) +@end example + +The first constructor here takes its arguments positionally rather +than by keyword. (In official Common Lisp terminology, constructors +that work By Order of Arguments instead of by keyword are called +``BOA constructors.'' No, I'm not making this up.) For example, +@code{(new-person "Jane" 'female)} generates a person whose slots +are @code{"Jane"}, 0, and @code{female}, respectively. + +The second constructor takes two keyword arguments, @code{:name}, +which initializes the @code{name} slot and defaults to @code{"Rover"}, +and @code{:dog-years}, which does not itself correspond to a slot +but which is used to initialize the @code{age} slot. The @code{sex} +slot is forced to the symbol @code{canine} with no syntax for +overriding it. + +@item :copier +The argument is an alternate name for the copier function for +this type. The default is @code{copy-@var{name}}. @code{nil} +means not to generate a copier function. (In this implementation, +all copier functions are simply synonyms for @code{copy-sequence}.) + +@item :predicate +The argument is an alternate name for the predicate which recognizes +objects of this type. The default is @code{@var{name}-p}. @code{nil} +means not to generate a predicate function. (If the @code{:type} +option is used without the @code{:named} option, no predicate is +ever generated.) + +In true Common Lisp, @code{typep} is always able to recognize a +structure object even if @code{:predicate} was used. In this +package, @code{typep} simply looks for a function called +@code{@var{typename}-p}, so it will work for structure types +only if they used the default predicate name. + +@item :include +This option implements a very limited form of C++-style inheritance. +The argument is the name of another structure type previously +created with @code{defstruct}. The effect is to cause the new +structure type to inherit all of the included structure's slots +(plus, of course, any new slots described by this struct's slot +descriptors). The new structure is considered a ``specialization'' +of the included one. In fact, the predicate and slot accessors +for the included type will also accept objects of the new type. + +If there are extra arguments to the @code{:include} option after +the included-structure name, these options are treated as replacement +slot descriptors for slots in the included structure, possibly with +modified default values. Borrowing an example from Steele: + +@example +(defstruct person name (age 0) sex) + @result{} person +(defstruct (astronaut (:include person (age 45))) + helmet-size + (favorite-beverage 'tang)) + @result{} astronaut + +(setq joe (make-person :name "Joe")) + @result{} [cl-struct-person "Joe" 0 nil] +(setq buzz (make-astronaut :name "Buzz")) + @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang] + +(list (person-p joe) (person-p buzz)) + @result{} (t t) +(list (astronaut-p joe) (astronaut-p buzz)) + @result{} (nil t) + +(person-name buzz) + @result{} "Buzz" +(astronaut-name joe) + @result{} error: "astronaut-name accessing a non-astronaut" +@end example + +Thus, if @code{astronaut} is a specialization of @code{person}, +then every @code{astronaut} is also a @code{person} (but not the +other way around). Every @code{astronaut} includes all the slots +of a @code{person}, plus extra slots that are specific to +astronauts. Operations that work on people (like @code{person-name}) +work on astronauts just like other people. + +@item :print-function +In full Common Lisp, this option allows you to specify a function +which is called to print an instance of the structure type. The +Emacs Lisp system offers no hooks into the Lisp printer which would +allow for such a feature, so this package simply ignores +@code{:print-function}. + +@item :type +The argument should be one of the symbols @code{vector} or @code{list}. +This tells which underlying Lisp data type should be used to implement +the new structure type. Vectors are used by default, but +@code{(:type list)} will cause structure objects to be stored as +lists instead. + +The vector representation for structure objects has the advantage +that all structure slots can be accessed quickly, although creating +vectors is a bit slower in Emacs Lisp. Lists are easier to create, +but take a relatively long time accessing the later slots. + +@item :named +This option, which takes no arguments, causes a characteristic ``tag'' +symbol to be stored at the front of the structure object. Using +@code{:type} without also using @code{:named} will result in a +structure type stored as plain vectors or lists with no identifying +features. + +The default, if you don't specify @code{:type} explicitly, is to +use named vectors. Therefore, @code{:named} is only useful in +conjunction with @code{:type}. + +@example +(defstruct (person1) name age sex) +(defstruct (person2 (:type list) :named) name age sex) +(defstruct (person3 (:type list)) name age sex) + +(setq p1 (make-person1)) + @result{} [cl-struct-person1 nil nil nil] +(setq p2 (make-person2)) + @result{} (person2 nil nil nil) +(setq p3 (make-person3)) + @result{} (nil nil nil) + +(person1-p p1) + @result{} t +(person2-p p2) + @result{} t +(person3-p p3) + @result{} error: function person3-p undefined +@end example + +Since unnamed structures don't have tags, @code{defstruct} is not +able to make a useful predicate for recognizing them. Also, +accessors like @code{person3-name} will be generated but they +will not be able to do any type checking. The @code{person3-name} +function, for example, will simply be a synonym for @code{car} in +this case. By contrast, @code{person2-name} is able to verify +that its argument is indeed a @code{person2} object before +proceeding. + +@item :initial-offset +The argument must be a nonnegative integer. It specifies a +number of slots to be left ``empty'' at the front of the +structure. If the structure is named, the tag appears at the +specified position in the list or vector; otherwise, the first +slot appears at that position. Earlier positions are filled +with @code{nil} by the constructors and ignored otherwise. If +the type @code{:include}s another type, then @code{:initial-offset} +specifies a number of slots to be skipped between the last slot +of the included type and the first new slot. +@end table +@end defspec + +Except as noted, the @code{defstruct} facility of this package is +entirely compatible with that of Common Lisp. + +@iftex +@chapno=23 +@end iftex + +@node Assertions, Efficiency Concerns, Structures, Top +@chapter Assertions and Errors + +@noindent +This section describes two macros that test @dfn{assertions}, i.e., +conditions which must be true if the program is operating correctly. +Assertions never add to the behavior of a Lisp program; they simply +make ``sanity checks'' to make sure everything is as it should be. + +If the optimization property @code{speed} has been set to 3, and +@code{safety} is less than 3, then the byte-compiler will optimize +away the following assertions. Because assertions might be optimized +away, it is a bad idea for them to include side-effects. + +@defspec assert test-form [show-args string args@dots{}] +This form verifies that @var{test-form} is true (i.e., evaluates to +a non-@code{nil} value). If so, it returns @code{nil}. If the test +is not satisfied, @code{assert} signals an error. + +A default error message will be supplied which includes @var{test-form}. +You can specify a different error message by including a @var{string} +argument plus optional extra arguments. Those arguments are simply +passed to @code{error} to signal the error. + +If the optional second argument @var{show-args} is @code{t} instead +of @code{nil}, then the error message (with or without @var{string}) +will also include all non-constant arguments of the top-level +@var{form}. For example: + +@example +(assert (> x 10) t "x is too small: %d") +@end example + +This usage of @var{show-args} is an extension to Common Lisp. In +true Common Lisp, the second argument gives a list of @var{places} +which can be @code{setf}'d by the user before continuing from the +error. Since Emacs Lisp does not support continuable errors, it +makes no sense to specify @var{places}. +@end defspec + +@defspec check-type form type [string] +This form verifies that @var{form} evaluates to a value of type +@var{type}. If so, it returns @code{nil}. If not, @code{check-type} +signals a @code{wrong-type-argument} error. The default error message +lists the erroneous value along with @var{type} and @var{form} +themselves. If @var{string} is specified, it is included in the +error message in place of @var{type}. For example: + +@example +(check-type x (integer 1 *) "a positive integer") +@end example + +@xref{Type Predicates}, for a description of the type specifiers +that may be used for @var{type}. + +Note that in Common Lisp, the first argument to @code{check-type} +must be a @var{place} suitable for use by @code{setf}, because +@code{check-type} signals a continuable error that allows the +user to modify @var{place}. +@end defspec + +The following error-related macro is also defined: + +@defspec ignore-errors forms@dots{} +This executes @var{forms} exactly like a @code{progn}, except that +errors are ignored during the @var{forms}. More precisely, if +an error is signaled then @code{ignore-errors} immediately +aborts execution of the @var{forms} and returns @code{nil}. +If the @var{forms} complete successfully, @code{ignore-errors} +returns the result of the last @var{form}. +@end defspec + +@node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top +@appendix Efficiency Concerns + +@appendixsec Macros + +@noindent +Many of the advanced features of this package, such as @code{defun*}, +@code{loop}, and @code{setf}, are implemented as Lisp macros. In +byte-compiled code, these complex notations will be expanded into +equivalent Lisp code which is simple and efficient. For example, +the forms + +@example +(incf i n) +(push x (car p)) +@end example + +@noindent +are expanded at compile-time to the Lisp forms + +@example +(setq i (+ i n)) +(setcar p (cons x (car p))) +@end example + +@noindent +which are the most efficient ways of doing these respective operations +in Lisp. Thus, there is no performance penalty for using the more +readable @code{incf} and @code{push} forms in your compiled code. + +@emph{Interpreted} code, on the other hand, must expand these macros +every time they are executed. For this reason it is strongly +recommended that code making heavy use of macros be compiled. +(The features labeled ``Special Form'' instead of ``Function'' in +this manual are macros.) A loop using @code{incf} a hundred times +will execute considerably faster if compiled, and will also +garbage-collect less because the macro expansion will not have +to be generated, used, and thrown away a hundred times. + +You can find out how a macro expands by using the +@code{cl-prettyexpand} function. + +@defun cl-prettyexpand form &optional full +This function takes a single Lisp form as an argument and inserts +a nicely formatted copy of it in the current buffer (which must be +in Lisp mode so that indentation works properly). It also expands +all Lisp macros which appear in the form. The easiest way to use +this function is to go to the @code{*scratch*} buffer and type, say, + +@example +(cl-prettyexpand '(loop for x below 10 collect x)) +@end example + +@noindent +and type @kbd{C-x C-e} immediately after the closing parenthesis; +the expansion + +@example +(block nil + (let* ((x 0) + (G1004 nil)) + (while (< x 10) + (setq G1004 (cons x G1004)) + (setq x (+ x 1))) + (nreverse G1004))) +@end example + +@noindent +will be inserted into the buffer. (The @code{block} macro is +expanded differently in the interpreter and compiler, so +@code{cl-prettyexpand} just leaves it alone. The temporary +variable @code{G1004} was created by @code{gensym}.) + +If the optional argument @var{full} is true, then @emph{all} +macros are expanded, including @code{block}, @code{eval-when}, +and compiler macros. Expansion is done as if @var{form} were +a top-level form in a file being compiled. For example, + +@example +(cl-prettyexpand '(pushnew 'x list)) + @print{} (setq list (adjoin 'x list)) +(cl-prettyexpand '(pushnew 'x list) t) + @print{} (setq list (if (memq 'x list) list (cons 'x list))) +(cl-prettyexpand '(caddr (member* 'a list)) t) + @print{} (car (cdr (cdr (memq 'a list)))) +@end example + +Note that @code{adjoin}, @code{caddr}, and @code{member*} all +have built-in compiler macros to optimize them in common cases. +@end defun + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec Error Checking + +@noindent +Common Lisp compliance has in general not been sacrificed for the +sake of efficiency. A few exceptions have been made for cases +where substantial gains were possible at the expense of marginal +incompatibility. One example is the use of @code{memq} (which is +treated very efficiently by the byte-compiler) to scan for keyword +arguments; this can become confused in rare cases when keyword +symbols are used as both keywords and data values at once. This +is extremely unlikely to occur in practical code, and the use of +@code{memq} allows functions with keyword arguments to be nearly +as fast as functions that use @code{&optional} arguments. + +The Common Lisp standard (as embodied in Steele's book) uses the +phrase ``it is an error if'' to indicate a situation which is not +supposed to arise in complying programs; implementations are strongly +encouraged but not required to signal an error in these situations. +This package sometimes omits such error checking in the interest of +compactness and efficiency. For example, @code{do} variable +specifiers are supposed to be lists of one, two, or three forms; +extra forms are ignored by this package rather than signaling a +syntax error. The @code{endp} function is simply a synonym for +@code{null} in this package. Functions taking keyword arguments +will accept an odd number of arguments, treating the trailing +keyword as if it were followed by the value @code{nil}. + +Argument lists (as processed by @code{defun*} and friends) +@emph{are} checked rigorously except for the minor point just +mentioned; in particular, keyword arguments are checked for +validity, and @code{&allow-other-keys} and @code{:allow-other-keys} +are fully implemented. Keyword validity checking is slightly +time consuming (though not too bad in byte-compiled code); +you can use @code{&allow-other-keys} to omit this check. Functions +defined in this package such as @code{find} and @code{member*} +do check their keyword arguments for validity. + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec Optimizing Compiler + +@noindent +The byte-compiler that comes with Emacs 18 normally fails to expand +macros that appear in top-level positions in the file (i.e., outside +of @code{defun}s or other enclosing forms). This would have +disastrous consequences to programs that used such top-level macros +as @code{defun*}, @code{eval-when}, and @code{defstruct}. To +work around this problem, the @dfn{CL} package patches the Emacs +18 compiler to expand top-level macros. This patch will apply to +your own macros, too, if they are used in a top-level context. +The patch will not harm versions of the Emacs 18 compiler which +have already had a similar patch applied, nor will it affect the +optimizing Emacs 19 byte-compiler written by Jamie Zawinski and +Hallvard Furuseth. The patch is applied to the byte compiler's +code in Emacs' memory, @emph{not} to the @file{bytecomp.elc} file +stored on disk. + +The Emacs 19 compiler (for Emacs 18) is available from various +Emacs Lisp archive sites such as @code{archive.cis.ohio-state.edu}. +Its use is highly recommended; many of the Common Lisp macros emit +code which can be improved by optimization. In particular, +@code{block}s (whether explicit or implicit in constructs like +@code{defun*} and @code{loop}) carry a fair run-time penalty; the +optimizing compiler removes @code{block}s which are not actually +referenced by @code{return} or @code{return-from} inside the block. + +@node Common Lisp Compatibility, Old CL Compatibility, Efficiency Concerns, Top +@appendix Common Lisp Compatibility + +@noindent +Following is a list of all known incompatibilities between this +package and Common Lisp as documented in Steele (2nd edition). + +Certain function names, such as @code{member}, @code{assoc}, and +@code{floor}, were already taken by (incompatible) Emacs Lisp +functions; this package appends @samp{*} to the names of its +Common Lisp versions of these functions. + +The word @code{defun*} is required instead of @code{defun} in order +to use extended Common Lisp argument lists in a function. Likewise, +@code{defmacro*} and @code{function*} are versions of those forms +which understand full-featured argument lists. The @code{&whole} +keyword does not work in @code{defmacro} argument lists (except +inside recursive argument lists). + +In order to allow an efficient implementation, keyword arguments use +a slightly cheesy parser which may be confused if a keyword symbol +is passed as the @emph{value} of another keyword argument. +(Specifically, @code{(memq :@var{keyword} @var{rest-of-arguments})} +is used to scan for @code{:@var{keyword}} among the supplied +keyword arguments.) + +The @code{eql} and @code{equal} predicates do not distinguish +between IEEE floating-point plus and minus zero. The @code{equalp} +predicate has several differences with Common Lisp; @pxref{Predicates}. + +The @code{setf} mechanism is entirely compatible, except that +setf-methods return a list of five values rather than five +values directly. Also, the new ``@code{setf} function'' concept +(typified by @code{(defun (setf foo) @dots{})}) is not implemented. + +The @code{do-all-symbols} form is the same as @code{do-symbols} +with no @var{obarray} argument. In Common Lisp, this form would +iterate over all symbols in all packages. Since Emacs obarrays +are not a first-class package mechanism, there is no way for +@code{do-all-symbols} to locate any but the default obarray. + +The @code{loop} macro is complete except that @code{loop-finish} +and type specifiers are unimplemented. + +The multiple-value return facility treats lists as multiple +values, since Emacs Lisp cannot support multiple return values +directly. The macros will be compatible with Common Lisp if +@code{values} or @code{values-list} is always used to return to +a @code{multiple-value-bind} or other multiple-value receiver; +if @code{values} is used without @code{multiple-value-@dots{}} +or vice-versa the effect will be different from Common Lisp. + +Many Common Lisp declarations are ignored, and others match +the Common Lisp standard in concept but not in detail. For +example, local @code{special} declarations, which are purely +advisory in Emacs Lisp, do not rigorously obey the scoping rules +set down in Steele's book. + +The variable @code{*gensym-counter*} starts out with a pseudo-random +value rather than with zero. This is to cope with the fact that +generated symbols become interned when they are written to and +loaded back from a file. + +The @code{defstruct} facility is compatible, except that structures +are of type @code{:type vector :named} by default rather than some +special, distinct type. Also, the @code{:type} slot option is ignored. + +The second argument of @code{check-type} is treated differently. + +@node Old CL Compatibility, Porting Common Lisp, Common Lisp Compatibility, Top +@appendix Old CL Compatibility + +@noindent +Following is a list of all known incompatibilities between this package +and the older Quiroz @file{cl.el} package. + +This package's emulation of multiple return values in functions is +incompatible with that of the older package. That package attempted +to come as close as possible to true Common Lisp multiple return +values; unfortunately, it could not be 100% reliable and so was prone +to occasional surprises if used freely. This package uses a simpler +method, namely replacing multiple values with lists of values, which +is more predictable though more noticeably different from Common Lisp. + +The @code{defkeyword} form and @code{keywordp} function are not +implemented in this package. + +The @code{member}, @code{floor}, @code{ceiling}, @code{truncate}, +@code{round}, @code{mod}, and @code{rem} functions are suffixed +by @samp{*} in this package to avoid collision with existing +functions in Emacs 18 or Emacs 19. The older package simply +redefined these functions, overwriting the built-in meanings and +causing serious portability problems with Emacs 19. (Some more +recent versions of the Quiroz package changed the names to +@code{cl-member}, etc.; this package defines the latter names as +aliases for @code{member*}, etc.) + +Certain functions in the old package which were buggy or inconsistent +with the Common Lisp standard are incompatible with the conforming +versions in this package. For example, @code{eql} and @code{member} +were synonyms for @code{eq} and @code{memq} in that package, @code{setf} +failed to preserve correct order of evaluation of its arguments, etc. + +Finally, unlike the older package, this package is careful to +prefix all of its internal names with @code{cl-}. Except for a +few functions which are explicitly defined as additional features +(such as @code{floatp-safe} and @code{letf}), this package does not +export any non-@samp{cl-} symbols which are not also part of Common +Lisp. + +@ifinfo +@example + +@end example +@end ifinfo +@appendixsec The @code{cl-compat} package + +@noindent +The @dfn{CL} package includes emulations of some features of the +old @file{cl.el}, in the form of a compatibility package +@code{cl-compat}. To use it, put @code{(require 'cl-compat)} in +your program. + +The old package defined a number of internal routines without +@code{cl-} prefixes or other annotations. Call to these routines +may have crept into existing Lisp code. @code{cl-compat} +provides emulations of the following internal routines: +@code{pair-with-newsyms}, @code{zip-lists}, @code{unzip-lists}, +@code{reassemble-arglists}, @code{duplicate-symbols-p}, +@code{safe-idiv}. + +Some @code{setf} forms translated into calls to internal +functions that user code might call directly. The functions +@code{setnth}, @code{setnthcdr}, and @code{setelt} fall in +this category; they are defined by @code{cl-compat}, but the +best fix is to change to use @code{setf} properly. + +The @code{cl-compat} file defines the keyword functions +@code{keywordp}, @code{keyword-of}, and @code{defkeyword}, +which are not defined by the new @dfn{CL} package because the +use of keywords as data is discouraged. + +The @code{build-klist} mechanism for parsing keyword arguments +is emulated by @code{cl-compat}; the @code{with-keyword-args} +macro is not, however, and in any case it's best to change to +use the more natural keyword argument processing offered by +@code{defun*}. + +Multiple return values are treated differently by the two +Common Lisp packages. The old package's method was more +compatible with true Common Lisp, though it used heuristics +that caused it to report spurious multiple return values in +certain cases. The @code{cl-compat} package defines a set +of multiple-value macros that are compatible with the old +CL package; again, they are heuristic in nature, but they +are guaranteed to work in any case where the old package's +macros worked. To avoid name collision with the ``official'' +multiple-value facilities, the ones in @code{cl-compat} have +capitalized names: @code{Values}, @code{Values-list}, +@code{Multiple-value-bind}, etc. + +The functions @code{cl-floor}, @code{cl-ceiling}, @code{cl-truncate}, +and @code{cl-round} are defined by @code{cl-compat} to use the +old-style multiple-value mechanism, just as they did in the old +package. The newer @code{floor*} and friends return their two +results in a list rather than as multiple values. Note that +older versions of the old package used the unadorned names +@code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use +these names because they conflict with Emacs 19 built-ins. + +@node Porting Common Lisp, Function Index, Old CL Compatibility, Top +@appendix Porting Common Lisp + +@noindent +This package is meant to be used as an extension to Emacs Lisp, +not as an Emacs implementation of true Common Lisp. Some of the +remaining differences between Emacs Lisp and Common Lisp make it +difficult to port large Common Lisp applications to Emacs. For +one, some of the features in this package are not fully compliant +with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there +are also quite a few features that this package does not provide +at all. Here are some major omissions that you will want watch out +for when bringing Common Lisp code into Emacs. + +@itemize @bullet +@item +Case-insensitivity. Symbols in Common Lisp are case-insensitive +by default. Some programs refer to a function or variable as +@code{foo} in one place and @code{Foo} or @code{FOO} in another. +Emacs Lisp will treat these as three distinct symbols. + +Some Common Lisp code is written entirely in upper case. While Emacs +is happy to let the program's own functions and variables use +this convention, calls to Lisp builtins like @code{if} and +@code{defun} will have to be changed to lower case. + +@item +Lexical scoping. In Common Lisp, function arguments and @code{let} +bindings apply only to references physically within their bodies +(or within macro expansions in their bodies). Emacs Lisp, by +contrast, uses @dfn{dynamic scoping} wherein a binding to a +variable is visible even inside functions called from the body. + +Variables in Common Lisp can be made dynamically scoped by +declaring them @code{special} or using @code{defvar}. In Emacs +Lisp it is as if all variables were declared @code{special}. + +Often you can use code that was written for lexical scoping +even in a dynamically scoped Lisp, but not always. Here is +an example of a Common Lisp code fragment that would fail in +Emacs Lisp: + +@example +(defun map-odd-elements (func list) + (loop for x in list + for flag = t then (not flag) + collect (if flag x (funcall func x)))) + +(defun add-odd-elements (list x) + (map-odd-elements (function (lambda (a) (+ a x))) list)) +@end example + +@noindent +In Common Lisp, the two functions' usages of @code{x} are completely +independent. In Emacs Lisp, the binding to @code{x} made by +@code{add-odd-elements} will have been hidden by the binding +in @code{map-odd-elements} by the time the @code{(+ a x)} function +is called. + +(This package avoids such problems in its own mapping functions +by using names like @code{cl-x} instead of @code{x} internally; +as long as you don't use the @code{cl-} prefix for your own +variables no collision can occur.) + +@xref{Lexical Bindings}, for a description of the @code{lexical-let} +form which establishes a Common Lisp-style lexical binding, and some +examples of how it differs from Emacs' regular @code{let}. + +@item +Reader macros. Common Lisp includes a second type of macro that +works at the level of individual characters. For example, Common +Lisp implements the quote notation by a reader macro called @code{'}, +whereas Emacs Lisp's parser just treats quote as a special case. +Some Lisp packages use reader macros to create special syntaxes +for themselves, which the Emacs parser is incapable of reading. + +The lack of reader macros, incidentally, is the reason behind +Emacs Lisp's unusual backquote syntax. Since backquotes are +implemented as a Lisp package and not built-in to the Emacs +parser, they are forced to use a regular macro named @code{`} +which is used with the standard function/macro call notation. + +@item +Other syntactic features. Common Lisp provides a number of +notations beginning with @code{#} that the Emacs Lisp parser +won't understand. For example, @samp{#| ... |#} is an +alternate comment notation, and @samp{#+lucid (foo)} tells +the parser to ignore the @code{(foo)} except in Lucid Common +Lisp. + +@item +Packages. In Common Lisp, symbols are divided into @dfn{packages}. +Symbols that are Lisp built-ins are typically stored in one package; +symbols that are vendor extensions are put in another, and each +application program would have a package for its own symbols. +Certain symbols are ``exported'' by a package and others are +internal; certain packages ``use'' or import the exported symbols +of other packages. To access symbols that would not normally be +visible due to this importing and exporting, Common Lisp provides +a syntax like @code{package:symbol} or @code{package::symbol}. + +Emacs Lisp has a single namespace for all interned symbols, and +then uses a naming convention of putting a prefix like @code{cl-} +in front of the name. Some Emacs packages adopt the Common Lisp-like +convention of using @code{cl:} or @code{cl::} as the prefix. +However, the Emacs parser does not understand colons and just +treats them as part of the symbol name. Thus, while @code{mapcar} +and @code{lisp:mapcar} may refer to the same symbol in Common +Lisp, they are totally distinct in Emacs Lisp. Common Lisp +programs which refer to a symbol by the full name sometimes +and the short name other times will not port cleanly to Emacs. + +Emacs Lisp does have a concept of ``obarrays,'' which are +package-like collections of symbols, but this feature is not +strong enough to be used as a true package mechanism. + +@item +The @code{format} function is quite different between Common +Lisp and Emacs Lisp. It takes an additional ``destination'' +argument before the format string. A destination of @code{nil} +means to format to a string as in Emacs Lisp; a destination +of @code{t} means to write to the terminal (similar to +@code{message} in Emacs). Also, format control strings are +utterly different; @code{~} is used instead of @code{%} to +introduce format codes, and the set of available codes is +much richer. There are no notations like @code{\n} for +string literals; instead, @code{format} is used with the +``newline'' format code, @code{~%}. More advanced formatting +codes provide such features as paragraph filling, case +conversion, and even loops and conditionals. + +While it would have been possible to implement most of Common +Lisp @code{format} in this package (under the name @code{format*}, +of course), it was not deemed worthwhile. It would have required +a huge amount of code to implement even a decent subset of +@code{format*}, yet the functionality it would provide over +Emacs Lisp's @code{format} would rarely be useful. + +@item +Vector constants use square brackets in Emacs Lisp, but +@code{#(a b c)} notation in Common Lisp. To further complicate +matters, Emacs 19 introduces its own @code{#(} notation for +something entirely different---strings with properties. + +@item +Characters are distinct from integers in Common Lisp. The +notation for character constants is also different: @code{#\A} +instead of @code{?A}. Also, @code{string=} and @code{string-equal} +are synonyms in Emacs Lisp whereas the latter is case-insensitive +in Common Lisp. + +@item +Data types. Some Common Lisp data types do not exist in Emacs +Lisp. Rational numbers and complex numbers are not present, +nor are large integers (all integers are ``fixnums''). All +arrays are one-dimensional. There are no readtables or pathnames; +streams are a set of existing data types rather than a new data +type of their own. Hash tables, random-states, structures, and +packages (obarrays) are built from Lisp vectors or lists rather +than being distinct types. + +@item +The Common Lisp Object System (CLOS) is not implemented, +nor is the Common Lisp Condition System. However, the EIEIO package +from @uref{ftp://ftp.ultranet.com/pub/zappo} does implement some +CLOS functionality. + +@item +Common Lisp features that are completely redundant with Emacs +Lisp features of a different name generally have not been +implemented. For example, Common Lisp writes @code{defconstant} +where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list} +takes its arguments in different ways in the two Lisps but does +exactly the same thing, so this package has not bothered to +implement a Common Lisp-style @code{make-list}. + +@item +A few more notable Common Lisp features not included in this +package: @code{compiler-let}, @code{tagbody}, @code{prog}, +@code{ldb/dpb}, @code{parse-integer}, @code{cerror}. + +@item +Recursion. While recursion works in Emacs Lisp just like it +does in Common Lisp, various details of the Emacs Lisp system +and compiler make recursion much less efficient than it is in +most Lisps. Some schools of thought prefer to use recursion +in Lisp over other techniques; they would sum a list of +numbers using something like + +@example +(defun sum-list (list) + (if list + (+ (car list) (sum-list (cdr list))) + 0)) +@end example + +@noindent +where a more iteratively-minded programmer might write one of +these forms: + +@example +(let ((total 0)) (dolist (x my-list) (incf total x)) total) +(loop for x in my-list sum x) +@end example + +While this would be mainly a stylistic choice in most Common Lisps, +in Emacs Lisp you should be aware that the iterative forms are +much faster than recursion. Also, Lisp programmers will want to +note that the current Emacs Lisp compiler does not optimize tail +recursion. +@end itemize + +@node Function Index, Variable Index, Porting Common Lisp, Top +@unnumbered Function Index + +@printindex fn + +@node Variable Index, , Function Index, Top +@unnumbered Variable Index + +@printindex vr + +@contents +@bye diff --git a/man/cmdargs.texi b/man/cmdargs.texi new file mode 100644 index 00000000000..97df157ddcb --- /dev/null +++ b/man/cmdargs.texi @@ -0,0 +1,1158 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Command Arguments, Antinews, Service, Top +@appendix Command Line Arguments +@cindex command line arguments +@cindex arguments (command line) +@cindex options (command line) +@cindex switches (command line) +@cindex startup (command line arguments) + + GNU Emacs supports command line arguments to request various actions +when invoking Emacs. These are for compatibility with other editors and +for sophisticated activities. We don't recommend using them for +ordinary editing. + + Arguments starting with @samp{-} are @dfn{options}. Other arguments +specify files to visit. Emacs visits the specified files while it +starts up. The last file name on your command line becomes the current +buffer; the other files are also present in other buffers. As usual, +the special argument @samp{--} says that all subsequent arguments +are file names, not options, even if they start with @samp{-}. + + Emacs command options can specify many things, such as the size and +position of the X window Emacs uses, its colors, and so on. A few +options support advanced usage, such as running Lisp functions on files +in batch mode. The sections of this chapter describe the available +options, arranged according to their purpose. + + There are two ways of writing options: the short forms that start with +a single @samp{-}, and the long forms that start with @samp{--}. For +example, @samp{-d} is a short form and @samp{--display} is the +corresponding long form. + + The long forms with @samp{--} are easier to remember, but longer to +type. However, you don't have to spell out the whole option name; any +unambiguous abbreviation is enough. When a long option takes an +argument, you can use either a space or an equal sign to separate the +option name and the argument. Thus, you can write either +@samp{--display sugar-bombs:0.0} or @samp{--display=sugar-bombs:0.0}. +We recommend an equal sign because it makes the relationship clearer, +and the tables below always show an equal sign. + +@cindex initial options (command line) +@cindex action options (command line) + Most options specify how to initialize Emacs, or set parameters for +the Emacs session. We call them @dfn{initial options}. A few options +specify things to do: for example, load libraries, call functions, or +exit Emacs. These are called @dfn{action options}. These and file +names together are called @dfn{action arguments}. Emacs processes all +the action arguments in the order they are written. + +@menu +* Action Arguments:: Arguments to visit files, load libraries, + and call functions. +* Initial Options:: Arguments that take effect while starting Emacs. +* Command Example:: Examples of using command line arguments. +* Resume Arguments:: Specifying arguments when you resume a running Emacs. +* Environment:: Environment variables that Emacs uses. + +* Display X:: Changing the default display and using remote login. +* Font X:: Choosing a font for text, under X. +* Colors X:: Choosing colors, under X. +* Window Size X:: Start-up window size, under X. +* Borders X:: Internal and external borders, under X. +* Title X:: Specifying the initial frame's title. +* Icons X:: Choosing what sort of icon to use, under X. +* Resources X:: Advanced use of classes and resources, under X. +* Lucid Resources:: X resources for Lucid menus. +* Motif Resources:: X resources for Motif menus. +@end menu + +@node Action Arguments +@appendixsec Action Arguments + + Here is a table of the action arguments and options: + +@table @samp +@item @var{file} +Visit @var{file} using @code{find-file}. @xref{Visiting}. + +@item +@var{linenum} @var{file} +Visit @var{file} using @code{find-file}, then go to line number +@var{linenum} in it. + +@need 3000 +@item -l @var{file} +@itemx --load=@var{file} +Load a Lisp library named @var{file} with the function @code{load}. +@xref{Lisp Libraries}. The library can be found either in the current +directory, or in the Emacs library search path as specified +with @code{EMACSLOADPATH} (@pxref{General Variables}). + +@item -f @var{function} +@itemx --funcall=@var{function} +Call Lisp function @var{function} with no arguments. + +@item --eval @var{expression} +Evaluate Lisp expression @var{expression}. + +@item --insert=@var{file} +Insert the contents of @var{file} into the current buffer. This is like +what @kbd{M-x insert-file} does. @xref{Misc File Ops}. + +@item --kill +Exit from Emacs without asking for confirmation. +@end table + +@vindex command-line-args + The init file can access the values of the action arguments as the +elements of a list in the variable @code{command-line-args}. The init +file can override the normal processing of the action arguments, or +define new ones, by reading and setting this variable. + +@node Initial Options +@appendixsec Initial Options + + The initial options specify parameters for the Emacs session. This +section describes the more general initial options; some other options +specifically related to X Windows appear in the following sections. + + Some initial options affect the loading of init files. The normal +actions of Emacs are to first load @file{site-start.el} if it exists, +then your own init file @file{~/.emacs} if it exists, and finally +@file{default.el} if it exists; certain options prevent loading of some +of these files or substitute other files for them. + +@table @samp +@item -t @var{device} +@itemx --terminal=@var{device} +Use @var{device} as the device for terminal input and output. + +@item -d @var{display} +@itemx --display=@var{display} +Use the X Window System and use the display named @var{display} to open +the initial Emacs frame. + +@item -nw +@itemx --no-windows +Don't communicate directly with X, disregarding the @code{DISPLAY} +environment variable even if it is set. + +@need 3000 +@cindex batch mode +@item -batch +@itemx --batch +Run Emacs in @dfn{batch mode}, which means that the text being edited is +not displayed and the standard terminal interrupt characters such as +@kbd{C-z} and @kbd{C-c} continue to have their normal effect. Emacs in +batch mode outputs to @code{stderr} only what would normally be printed +in the echo area under program control. + +Batch mode is used for running programs written in Emacs Lisp from +shell scripts, makefiles, and so on. Normally the @samp{-l} option +or @samp{-f} option will be used as well, to invoke a Lisp program +to do the batch processing. + +@samp{-batch} implies @samp{-q} (do not load an init file). It also causes +Emacs to kill itself after all command options have been processed. In +addition, auto-saving is not done except in buffers for which it has been +explicitly requested. + +@item -q +@itemx --no-init-file +Do not load your Emacs init file @file{~/.emacs}, or @file{default.el} +either. + +@item --no-site-file +Do not load @file{site-start.el}. The options @samp{-q}, @samp{-u} +and @samp{-batch} have no effect on the loading of this file---this is +the only option that blocks it. + +@item -u @var{user} +@itemx --user=@var{user} +Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of +your own. + +@item --debug-init +Enable the Emacs Lisp debugger for errors in the init file. + +@item --unibyte +@cindex unibyte operation +Set up to do almost everything with single-byte buffers and strings. +All buffers and strings are unibyte unless you (or a Lisp program) +explicitly ask for a multibyte buffer or string. Setting the +environment variable @code{EMACS_UNIBYTE} has the same effect. + +@item --multibyte +Inhibit the effect of @code{EMACS_UNIBYTE}, so that Emacs +uses multibyte characters by default, as usual. +@end table + +@node Command Example +@appendixsec Command Argument Example + + Here is an example of using Emacs with arguments and options. It +assumes you have a Lisp program file called @file{hack-c.el} which, when +loaded, performs some useful operation on the current buffer, expected +to be a C program. + +@example +emacs -batch foo.c -l hack-c -f save-buffer >& log +@end example + +@noindent +This says to visit @file{foo.c}, load @file{hack-c.el} (which makes +changes in the visited file), save @file{foo.c} (note that +@code{save-buffer} is the function that @kbd{C-x C-s} is bound to), and +then exit back to the shell (because of @samp{-batch}). @samp{-batch} +also guarantees there will be no problem redirecting output to +@file{log}, because Emacs will not assume that it has a display terminal +to work with. + +@node Resume Arguments +@appendixsec Resuming Emacs with Arguments + + You can specify action arguments for Emacs when you resume it after +a suspension. To prepare for this, put the following code in your +@file{.emacs} file (@pxref{Hooks}): + +@example +(add-hook 'suspend-hook 'resume-suspend-hook) +(add-hook 'suspend-resume-hook 'resume-process-args) +@end example + + As further preparation, you must execute the shell script +@file{emacs.csh} (if you use csh as your shell) or @file{emacs.bash} (if +you use bash as your shell). These scripts define an alias named +@code{edit}, which will resume Emacs giving it new command line +arguments such as files to visit. + + Only action arguments work properly when you resume Emacs. Initial +arguments are not recognized---it's too late to execute them anyway. + + Note that resuming Emacs (with or without arguments) must be done from +within the shell that is the parent of the Emacs job. This is why +@code{edit} is an alias rather than a program or a shell script. It is +not possible to implement a resumption command that could be run from +other subjobs of the shell; no way to define a command that could be +made the value of @code{EDITOR}, for example. Therefore, this feature +does not take the place of the Emacs Server feature (@pxref{Emacs +Server}). + + The aliases use the Emacs Server feature if you appear to have a +server Emacs running. However, they cannot determine this with complete +accuracy. They may think that a server is still running when in +actuality you have killed that Emacs, because the file +@file{/tmp/.esrv@dots{}} still exists. If this happens, find that +file and delete it. + +@node Environment +@appendixsec Environment Variables +@cindex environment variables + +This appendix describes how Emacs uses environment variables. An +environment variable is a string passed from the operating system to +Emacs, and the collection of environment variables is known as the +environment. Environment variable names are case sensitive and it is +conventional to use upper case letters only. + +Because environment variables come from the operating system there is no +general way to set them; it depends on the operating system and +especially the shell that you are using. For example, here's how to set +the environment variable @code{ORGANIZATION} to @samp{not very much} +using bash: + +@example +export ORGANIZATION="not very much" +@end example + +@noindent +and here's how to do it in csh or tcsh: + +@example +setenv ORGANIZATION "not very much" +@end example + +When Emacs is set-up to use the X windowing system, it inherits the +use of a large number of environment variables from the X library. See +the X documentation for more information. + +@menu +* General Variables:: Environment variables that all versions of Emacs use. +* Misc Variables:: Certain system-specific variables. +@end menu + +@node General Variables +@appendixsubsec General Variables + +@table @code +@item AUTHORCOPY +The name of a file used to archive news articles posted with the @sc{gnus} +package. +@item CDPATH +Used by the @code{cd} command to search for the directory you specify, +when you specify a relative directory name. +@item DOMAINNAME +The name of the Internet domain that the machine running Emacs is +located in. Used by the @sc{gnus} package. +@item EMACS_UNIBYTE +@cindex unibyte operation +Defining this environment variable directs Emacs to do almost everything +with single-byte buffers and strings. It is equivalent to using the +@samp{--unibyte} command-line option on each invocation. @xref{Initial +Options}. +@item EMACSDATA +Used to initialize the variable @code{data-directory} used to locate the +architecture-independent files that come with Emacs. Setting this +variable overrides the setting in @file{paths.h} when Emacs was built. +@item EMACSLOADPATH +A colon-separated list of directories from which to load Emacs Lisp +files. Setting this variable overrides the setting in @file{paths.h} +when Emacs was built. +@item EMACSLOCKDIR +The directory that Emacs places lock files---files used to protect +users from editing the same files simultaneously. Setting this variable +overrides the setting in @file{paths.h} when Emacs was built. +@item EMACSPATH +The location of Emacs-specific binaries. Setting this variable +overrides the setting in @file{paths.h} when Emacs was built. +@item ESHELL +Used for shell-mode to override the @code{SHELL} environment variable. +@item HISTFILE +The name of the file that shell commands are saved in between logins. +This variable defaults to @file{~/.history} if you use (t)csh as shell, +to @file{~/.bash_history} if you use bash, to @file{~/.sh_history} if +you use ksh, and to @file{~/.history} otherwise. +@item HOME +The location of the user's files in the directory tree; used for +expansion of file names starting with a tilde (@file{~}). On MS-DOS, it +defaults to the directory from which Emacs was started, with @samp{/bin} +removed from the end if it was present. +@item HOSTNAME +The name of the machine that Emacs is running on. +@item INCPATH +A colon-separated list of directories. Used by the @code{complete} package +to search for files. +@item INFOPATH +A colon-separated list of directories holding info files. Setting this +variable overrides the setting in @file{paths.el} when Emacs was built. +@item LANG +@itemx LC_ALL +@itemx LC_CTYPE +The user's preferred locale. A locale name which contains +@samp{8859-@var{n}}, @samp{8859_@var{n}} or @samp{8859@var{n}}, where +@var{n} is between 1 and 4, automatically specifies the +@samp{Latin-@var{n}} language environment when Emacs starts up. If +@var{n} is 9, that specifies @samp{Latin-5}. +@item LOGNAME +The user's login name. See also @code{USER}. +@item MAIL +The name of the user's system mail inbox. +@item MAILRC +Name of file containing mail aliases. This defaults to +@file{~/.mailrc}. +@item MH +Name of setup file for the mh system. This defaults to +@file{~/.mh_profile}. +@item NAME +The real-world name of the user. +@item NNTPSERVER +The name of the news server. Used by the mh and @sc{gnus} packages. +@item ORGANIZATION +The name of the organization to which you belong. Used for setting the +`Organization:' header in your posts from the @sc{gnus} package. +@item PATH +A colon-separated list of directories in which executables reside. (On +MS-DOS, it is semicolon-separated instead.) This variable is used to +set the Emacs Lisp variable @code{exec-path} which you should consider +to use instead. +@item PWD +If set, this should be the default directory when Emacs was started. +@item REPLYTO +If set, this specifies an initial value for the variable +@code{mail-default-reply-to}. @xref{Mail Headers}. +@item SAVEDIR +The name of a directory in which news articles are saved by default. +Used by the @sc{gnus} package. +@item SHELL +The name of an interpreter used to parse and execute programs run from +inside Emacs. +@item TERM +The name of the terminal that Emacs is running on. The variable must be +set unless Emacs is run in batch mode. On MS-DOS, it defaults to +@samp{internal}, which specifies a built-in terminal emulation that +handles the machine's own display. +@item TERMCAP +The name of the termcap library file describing how to program the +terminal specified by the @code{TERM} variable. This defaults to +@file{/etc/termcap}. +@item TMPDIR +Used by the Emerge package as a prefix for temporary files. +@item TZ +This specifies the current time zone and possibly also daylight savings +information. On MS-DOS, the default is based on country code; see the +file @file{msdos.c} for details. +@item USER +The user's login name. See also @code{LOGNAME}. On MS-DOS, this +defaults to @samp{root}. +@item VERSION_CONTROL +Used to initialize the @code{version-control} variable (@pxref{Backup +Names}). +@end table + +@node Misc Variables +@appendixsubsec Miscellaneous Variables + +These variables are used only on particular configurations: + +@table @code +@item COMSPEC +On MS-DOS, the name of the command interpreter to use. This is used to +make a default value for the @code{SHELL} environment variable. + +@item NAME +On MS-DOS, this variable defaults to the value of the @code{USER} +variable. + +@item TEMP +@itemx TMP +On MS-DOS, these specify the name of the directory for storing temporary +files in. + +@item EMACSTEST +On MS-DOS, this specifies a file to use to log the operation of the +internal terminal emulator. This feature is useful for submitting bug +reports. + +@item EMACSCOLORS +Used on MS-DOS systems to set screen colors early, so that the screen +won't momentarily flash the default colors when Emacs starts up. The +value of this variable should be two-character encoding of the +foreground (the first character) and the background (the second +character) colors of the default face. Each character should be the +hexadecimal code for the desired color on a standard PC text-mode +display. + +The PC display usually supports only eight background colors. However, +Emacs switches the DOS display to a mode where all 16 colors can be used +for the background, so all four bits of the background color are +actually used. + +@item WINDOW_GFX +Used when initializing the Sun windows system. +@end table + +@node Display X +@appendixsec Specifying the Display Name +@cindex display name (X Windows) +@cindex @code{DISPLAY} environment variable + + The environment variable @code{DISPLAY} tells all X clients, including +Emacs, where to display their windows. Its value is set up by default +in ordinary circumstances, when you start an X server and run jobs +locally. Occasionally you may need to specify the display yourself; for +example, if you do a remote login and want to run a client program +remotely, displaying on your local screen. + + With Emacs, the main reason people change the default display is to +let them log into another system, run Emacs on that system, but have the +window displayed at their local terminal. You might need to use login +to another system because the files you want to edit are there, or +because the Emacs executable file you want to run is there. + + The syntax of the @code{DISPLAY} environment variable is +@samp{@var{host}:@var{display}.@var{screen}}, where @var{host} is the +host name of the X Window System server machine, @var{display} is an +arbitrarily-assigned number that distinguishes your server (X terminal) +from other servers on the same machine, and @var{screen} is a +rarely-used field that allows an X server to control multiple terminal +screens. The period and the @var{screen} field are optional. If +included, @var{screen} is usually zero. + + For example, if your host is named @samp{glasperle} and your server is +the first (or perhaps the only) server listed in the configuration, your +@code{DISPLAY} is @samp{glasperle:0.0}. + + You can specify the display name explicitly when you run Emacs, either +by changing the @code{DISPLAY} variable, or with the option @samp{-d +@var{display}} or @samp{--display=@var{display}}. Here is an example: + +@smallexample +emacs --display=glasperle:0 & +@end smallexample + + You can inhibit the direct use of X with the @samp{-nw} option. This +is also an initial option. It tells Emacs to display using ordinary +ASCII on its controlling terminal. + + Sometimes, security arrangements prevent a program on a remote system +from displaying on your local system. In this case, trying to run Emacs +produces messages like this: + +@smallexample +Xlib: connection to "glasperle:0.0" refused by server +@end smallexample + +@noindent +You might be able to overcome this problem by using the @code{xhost} +command on the local system to give permission for access from your +remote machine. + +@node Font X +@appendixsec Font Specification Options +@cindex font name (X Windows) + + By default, Emacs displays text in the font named @samp{9x15}, which +makes each character nine pixels wide and fifteen pixels high. You can +specify a different font on your command line through the option +@samp{-fn @var{name}}. + +@table @samp +@item -fn @var{name} +Use font @var{name} as the default font. + +@item --font=@var{name} +@samp{--font} is an alias for @samp{-fn}. +@end table + + Under X, each font has a long name which consists of eleven words or +numbers, separated by dashes. Some fonts also have shorter +nicknames---@samp{9x15} is such a nickname. You can use either kind of +name. You can use wildcard patterns for the font name; then Emacs lets +X choose one of the fonts that match the pattern. Here is an example, +which happens to specify the font whose nickname is @samp{6x13}: + +@smallexample +emacs -fn "-misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1" & +@end smallexample + +@noindent +You can also specify the font in your @file{.Xdefaults} file: + +@smallexample +emacs.font: -misc-fixed-medium-r-semicondensed--13-*-*-*-c-60-iso8859-1 +@end smallexample + + A long font name has the following form: + +@smallexample +-@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{} +@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset} +@end smallexample + +@table @var +@item family +This is the name of the font family---for example, @samp{courier}. +@item weight +This is normally @samp{bold}, @samp{medium} or @samp{light}. Other +words may appear here in some font names. +@item slant +This is @samp{r} (roman), @samp{i} (italic), @samp{o} (oblique), +@samp{ri} (reverse italic), or @samp{ot} (other). +@item widthtype +This is normally @samp{condensed}, @samp{extended}, @samp{semicondensed} +or @samp{normal}. Other words may appear here in some font names. +@item style +This is an optional additional style name. Usually it is empty---most +long font names have two hyphens in a row at this point. +@item pixels +This is the font height, in pixels. +@item height +This is the font height on the screen, measured in tenths of a printer's +point---approximately 1/720 of an inch. In other words, it is the point +size of the font, times ten. For a given vertical resolution, +@var{height} and @var{pixels} are proportional; therefore, it is common +to specify just one of them and use @samp{*} for the other. +@item horiz +This is the horizontal resolution, in pixels per inch, of the screen for +which the font is intended. +@item vert +This is the vertical resolution, in dots per inch, of the screen for +which the font is intended. Normally the resolution of the fonts on +your system is the right value for your screen; therefore, you normally +specify @samp{*} for this and @var{horiz}. +@item spacing +This is @samp{m} (monospace), @samp{p} (proportional) or @samp{c} +(character cell). Emacs can use @samp{m} and @samp{c} fonts. +@item width +This is the average character width, in pixels, multiplied by ten. +@item charset +This is the character set that the font depicts. +Normally you should use @samp{iso8859-1}. +@end table + + Use only fixed-width fonts---that is, fonts in which all characters +have the same width; Emacs cannot yet handle display properly for +variable-width fonts. Any font with @samp{m} or @samp{c} in the +@var{spacing} field of the long name is a fixed-width font. Here's how +to use the @code{xlsfonts} program to list all the fixed-width fonts +available on your system: + +@example +xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+" +xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-m*' +xlsfonts -fn '*-*-*-*-*-*-*-*-*-*-*-c*' +@end example + +@noindent +To see what a particular font looks like, use the @code{xfd} command. +For example: + +@example +xfd -fn 6x13 +@end example + +@noindent +displays the entire font @samp{6x13}. + + While running Emacs, you can set the font of the current frame +(@pxref{Frame Parameters}) or for a specific kind of text +(@pxref{Faces}). + +@node Colors X +@appendixsec Window Color Options +@cindex color of window (X Windows) + + On a color display, you can specify which color to use for various +parts of the Emacs display. To find out what colors are available on +your system, look at the @file{/usr/lib/X11/rgb.txt} file. If you do +not specify colors, the default for the background is white and the +default for all other colors is black. On a monochrome display, the +foreground is black, the background is white, and the border is gray if +the display supports that. + + Here is a list of the options for specifying colors: + +@table @samp +@item -fg @var{color} +@itemx --foreground-color=@var{color} +Specify the foreground color. +@item -bg @var{color} +@itemx --background-color=@var{color} +Specify the background color. +@item -bd @var{color} +@itemx --border-color=@var{color} +Specify the color of the border of the X window. +@item -cr @var{color} +@itemx --cursor-color=@var{color} +Specify the color of the Emacs cursor which indicates where point is. +@item -ms @var{color} +@itemx --mouse-color=@var{color} +Specify the color for the mouse cursor when the mouse is in the Emacs window. +@item -r +@itemx --reverse-video +Reverse video---swap the foreground and background colors. +@end table + + For example, to use a coral mouse cursor and a slate blue text cursor, +enter: + +@example +emacs -ms coral -cr 'slate blue' & +@end example + + You can reverse the foreground and background colors through the +@samp{-r} option or with the X resource @samp{reverseVideo}. + +@node Window Size X +@appendixsec Options for Window Geometry +@cindex geometry (X Windows) + + The @samp{-geometry} option controls the size and position of the +initial Emacs frame. Here is the format for specifying the window +geometry: + +@table @samp +@item -g @var{width}x@var{height}@r{@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset} +Specify window size @var{width} and @var{height} (measured in character +columns and lines), and positions @var{xoffset} and @var{yoffset} +(measured in pixels). + +@item --geometry=@var{width}x@var{height}@r{@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset} +This is another way of writing the same thing. +@end table + +@noindent +@code{@r{@{}+-@r{@}}} means either a plus sign or a minus sign. A plus +sign before @var{xoffset} means it is the distance from the left side of +the screen; a minus sign means it counts from the right side. A plus +sign before @var{yoffset} means it is the distance from the top of the +screen, and a minus sign there indicates the distance from the bottom. +The values @var{xoffset} and @var{yoffset} may themselves be positive or +negative, but that doesn't change their meaning, only their direction. + + Emacs uses the same units as @code{xterm} does to interpret the geometry. +The @var{width} and @var{height} are measured in characters, so a large font +creates a larger frame than a small font. The @var{xoffset} and +@var{yoffset} are measured in pixels. + + Since the mode line and the echo area occupy the last 2 lines of the +frame, the height of the initial text window is 2 less than the height +specified in your geometry. In non-X-toolkit versions of Emacs, +the menu bar also takes one line of the specified number. + + You do not have to specify all of the fields in the geometry +specification. + + If you omit both @var{xoffset} and @var{yoffset}, the window manager +decides where to put the Emacs frame, possibly by letting you place +it with the mouse. For example, @samp{164x55} specifies a window 164 +columns wide, enough for two ordinary width windows side by side, and 55 +lines tall. + + The default width for Emacs is 80 characters and the default height is +40 lines. You can omit either the width or the height or both. If +you start the geometry with an integer, Emacs interprets it as the +width. If you start with an @samp{x} followed by an integer, Emacs +interprets it as the height. Thus, @samp{81} specifies just the width; +@samp{x45} specifies just the height. + + If you start with @samp{+} or @samp{-}, that introduces an offset, +which means both sizes are omitted. Thus, @samp{-3} specifies the +@var{xoffset} only. (If you give just one offset, it is always +@var{xoffset}.) @samp{+3-3} specifies both the @var{xoffset} and the +@var{yoffset}, placing the frame near the bottom left of the screen. + + You can specify a default for any or all of the fields in +@file{.Xdefaults} file, and then override selected fields with a +@samp{--geometry} option. + +@node Borders X +@appendixsec Internal and External Borders +@cindex borders (X Windows) + + An Emacs frame has an internal border and an external border. The +internal border is an extra strip of the background color around all +four edges of the frame. Emacs itself adds the internal border. The +external border is added by the window manager outside the internal +border; it may contain various boxes you can click on to move or iconify +the window. + +@table @samp +@item -ib @var{width} +@itemx --internal-border=@var{width} +Specify @var{width} as the width of the internal border. + +@item -bw @var{width} +@itemx --border-width=@var{width} +Specify @var{width} as the width of the main border. +@end table + + When you specify the size of the frame, that does not count the +borders. The frame's position is measured from the outside edge of the +external border. + + Use the @samp{-ib @var{n}} option to specify an internal border +@var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to +specify the width of the external border (though the window manager may +not pay attention to what you specify). The default width of the +external border is 2. + +@node Title X +@appendixsec Frame Titles + + An Emacs frame may or may not have a specified title. The frame +title, if specified, appears in window decorations and icons as the name +of the frame. If an Emacs frame has no specified title, the default +title is the name of the executable program (if there is only one frame) +or the selected window's buffer name (if there is more than one frame). + + You can specify a title for the initial Emacs frame with a command +line option: + +@table @samp +@item -title @var{title} +@itemx --title=@var{title} +@itemx -T @var{title} +Specify @var{title} as the title for the initial Emacs frame. +@end table + + The @samp{--name} option (@pxref{Resources X}) also specifies the title +for the initial Emacs frame. + +@node Icons X +@appendixsec Icons +@cindex icons (X Windows) + + Most window managers allow the user to ``iconify'' a frame, removing +it from sight, and leaving a small, distinctive ``icon'' window in its +place. Clicking on the icon window makes the frame itself appear again. +If you have many clients running at once, you can avoid cluttering up +the screen by iconifying most of the clients. + +@table @samp +@item -i +@itemx --icon-type +Use a picture of a gnu as the Emacs icon. + +@item -iconic +@itemx --iconic +Start Emacs in iconified state. +@end table + + The @samp{-i} or @samp{--icon-type} option tells Emacs to use an icon +window containing a picture of the GNU gnu. If omitted, Emacs lets the +window manager choose what sort of icon to use---usually just a small +rectangle containing the frame's title. + + The @samp{-iconic} option tells Emacs to begin running as an icon, +rather than opening a frame right away. In this situation, the icon +window provides only indication that Emacs has started; the usual text +frame doesn't appear until you deiconify it. + +@node Resources X +@appendixsec X Resources +@cindex resources + + Programs running under the X Window System organize their user options +under a hierarchy of classes and resources. You can specify default +values for these options in your X resources file, usually named +@file{~/.Xdefaults}. + + Each line in the file specifies a value for one option or for a +collection of related options, for one program or for several programs +(optionally even for all programs). + + Programs define named resources with particular meanings. They also +define how to group resources into named classes. For instance, in +Emacs, the @samp{internalBorder} resource controls the width of the +internal border, and the @samp{borderWidth} resource controls the width +of the external border. Both of these resources are part of the +@samp{BorderWidth} class. Case distinctions are significant in these +names. + + In @file{~/.Xdefaults}, you can specify a value for a single resource +on one line, like this: + +@example +emacs.borderWidth: 2 +@end example + +@noindent +Or you can use a class name to specify the same value for all resources +in that class. Here's an example: + +@example +emacs.BorderWidth: 2 +@end example + + If you specify a value for a class, it becomes the default for all +resources in that class. You can specify values for individual +resources as well; these override the class value, for those particular +resources. Thus, this example specifies 2 as the default width for all +borders, but overrides this value with 4 for the external border: + +@example +emacs.Borderwidth: 2 +emacs.borderwidth: 4 +@end example + + The order in which the lines appear in the file does not matter. +Also, command-line options always override the X resources file. + + The string @samp{emacs} in the examples above is also a resource +name. It actually represents the name of the executable file that you +invoke to run Emacs. If Emacs is installed under a different name, it +looks for resources under that name instead of @samp{emacs}. + +@table @samp +@item -name @var{name} +@itemx --name=@var{name} +Use @var{name} as the resource name (and the title) for the initial +Emacs frame. This option does not affect subsequent frames, but Lisp +programs can specify frame names when they create frames. + +If you don't specify this option, the default is to use the Emacs +executable's name as the resource name. + +@item -xrm @var{resource-values} +@itemx --xrm=@var{resource-values} +Specify X resource values for this Emacs job (see below). +@end table + + For consistency, @samp{-name} also specifies the name to use for +other resource values that do not belong to any particular frame. + + The resources that name Emacs invocations also belong to a class; its +name is @samp{Emacs}. If you write @samp{Emacs} instead of +@samp{emacs}, the resource applies to all frames in all Emacs jobs, +regardless of frame titles and regardless of the name of the executable +file. Here is an example: + +@example +Emacs.BorderWidth: 2 +Emacs.borderWidth: 4 +@end example + + You can specify a string of additional resource values for Emacs to +use with the command line option @samp{-xrm @var{resources}}. The text +@var{resources} should have the same format that you would use inside a file +of X resources. To include multiple resource specifications in +@var{data}, put a newline between them, just as you would in a file. +You can also use @samp{#include "@var{filename}"} to include a file full +of resource specifications. Resource values specified with @samp{-xrm} +take precedence over all other resource specifications. + + The following table lists the resource names that designate options +for Emacs, each with the class that it belongs to: + +@table @asis +@item @code{background} (class @code{Background}) +Background color name. + +@item @code{bitmapIcon} (class @code{BitmapIcon}) +Use a bitmap icon (a picture of a gnu) if @samp{on}, let the window +manager choose an icon if @samp{off}. + +@item @code{borderColor} (class @code{BorderColor}) +Color name for the external border. + +@item @code{borderWidth} (class @code{BorderWidth}) +Width in pixels of the external border. + +@item @code{cursorColor} (class @code{Foreground}) +Color name for text cursor (point). + +@item @code{font} (class @code{Font}) +Font name for text (or fontset name, @pxref{Fontsets}). + +@item @code{foreground} (class @code{Foreground}) +Color name for text. + +@item @code{geometry} (class @code{Geometry}) +Window size and position. Be careful not to specify this resource as +@samp{emacs*geometry}, because that may affect individual menus as well +as the Emacs frame itself. + +If this resource specifies a position, that position applies only to the +initial Emacs frame (or, in the case of a resource for a specific frame +name, only that frame). However, the size if specified here applies to +all frames. + +@item @code{iconName} (class @code{Title}) +Name to display in the icon. + +@item @code{internalBorder} (class @code{BorderWidth}) +Width in pixels of the internal border. + +@item @code{menuBar} (class @code{MenuBar}) +Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}. + +@item @code{minibuffer} (class @code{Minibuffer}) +If @samp{none}, don't make a minibuffer in this frame. +It will use a separate minibuffer frame instead. + +@item @code{paneFont} (class @code{Font}) +Font name for menu pane titles, in non-toolkit versions of Emacs. + +@item @code{pointerColor} (class @code{Foreground}) +Color of the mouse cursor. + +@item @code{reverseVideo} (class @code{ReverseVideo}) +Switch foreground and background default colors if @samp{on}, use colors as +specified if @samp{off}. + +@item @code{verticalScrollBars} (class @code{ScrollBars}) +Give frames scroll bars if @samp{on}; don't have scroll bars if +@samp{off}. + +@item @code{selectionFont} (class @code{Font}) +Font name for pop-up menu items, in non-toolkit versions of Emacs. (For +toolkit versions, see @ref{Lucid Resources}, also see @ref{Motif +Resources}.) + +@item @code{title} (class @code{Title}) +Name to display in the title bar of the initial Emacs frame. +@end table + + Here are resources for controlling the appearance of particular faces +(@pxref{Faces}): + +@table @code +@item @var{face}.attributeFont +Font for face @var{face}. +@item @var{face}.attributeForeground +Foreground color for face @var{face}. +@item @var{face}.attributeBackground +Background color for face @var{face}. +@item @var{face}.attributeUnderline +Underline flag for face @var{face}. Use @samp{on} or @samp{true} for +yes. +@end table + +@node Lucid Resources +@section Lucid Menu X Resources +@cindex Menu X Resources (Lucid widgets) +@cindex Lucid Widget X Resources + + If the Emacs installed at your site was built to use the X toolkit +with the Lucid menu widgets, then the menu bar is a separate widget and +has its own resources. The resource names contain @samp{pane.menubar} +(following, as always, the name of the Emacs invocation or @samp{Emacs} +which stands for all Emacs invocations). Specify them like this: + +@example +Emacs.pane.menubar.@var{resource}: @var{value} +@end example + +@noindent +For example, to specify the font @samp{8x16} for the menu-bar items, +write this: + +@example +Emacs.pane.menubar.font: 8x16 +@end example + +@noindent +Resources for @emph{non-menubar} toolkit pop-up menus have +@samp{menu*}, in like fashion. For example, to specify the font +@samp{8x16} for the pop-up menu items, write this: + +@example +Emacs.menu*.font: 8x16 +@end example + +@noindent +For dialog boxes, use @samp{dialog} instead of @samp{menu}: + +@example +Emacs.dialog*.font: 8x16 +@end example + +@noindent +Experience shows that on some systems you may need to add +@samp{shell.}@: before the @samp{pane.menubar} or @samp{menu*}. On +some other systems, you must not add @samp{shell.}. + + Here is a list of the specific resources for menu bars and pop-up menus: + +@table @code +@item font +Font for menu item text. +@item foreground +Color of the foreground. +@item background +Color of the background. +@item buttonForeground +In the menu bar, the color of the foreground for a selected item. +@item horizontalSpacing +Horizontal spacing in pixels between items. Default is 3. +@item verticalSpacing +Vertical spacing in pixels between items. Default is 1. +@item arrowSpacing +Horizontal spacing between the arrow (which indicates a submenu) and +the associated text. Default is 10. +@item shadowThickness +Thickness of shadow line around the widget. +@end table + +@node Motif Resources +@section Motif Menu X Resources +@cindex Menu X Resources (Motif widgets) +@cindex Motif Widget X Resources + + If the Emacs installed at your site was built to use the X toolkit +with the Motif widgets, then the menu bar is a separate widget and has +its own resources. The resource names contain @samp{pane.menubar} +(following, as always, the name of the Emacs invocation or @samp{Emacs} +which stands for all Emacs invocations). Specify them like this: + +@smallexample +Emacs.pane.menubar.@var{subwidget}.@var{resource}: @var{value} +@end smallexample + + Each individual string in the menu bar is a subwidget; the subwidget's +name is the same as the menu item string. For example, the word +@samp{Files} in the menu bar is part of a subwidget named +@samp{emacs.pane.menubar.Files}. Most likely, you want to specify the +same resources for the whole menu bar. To do this, use @samp{*} instead +of a specific subwidget name. For example, to specify the font +@samp{8x16} for the menu-bar items, write this: + +@smallexample +Emacs.pane.menubar.*.fontList: 8x16 +@end smallexample + +@noindent +This also specifies the resource value for submenus. + + Each item in a submenu in the menu bar also has its own name for X +resources; for example, the @samp{Files} submenu has an item named +@samp{Save Buffer}. A resource specification for a submenu item looks +like this: + +@smallexample +Emacs.pane.menubar.popup_*.@var{menu}.@var{item}.@var{resource}: @var{value} +@end smallexample + +@noindent +For example, here's how to specify the font for the @samp{Save Buffer} +item: + +@smallexample +Emacs.pane.menubar.popup_*.Files.Save Buffer.fontList: 8x16 +@end smallexample + +@noindent +For an item in a second-level submenu, such as @samp{Check Message} +under @samp{Spell} under @samp{Edit}, the resource fits this template: + +@smallexample +Emacs.pane.menubar.popup_*.popup_*.@var{menu}.@var{resource}: @var{value} +@end smallexample + +@noindent +For example, + +@smallexample +Emacs.pane.menubar.popup_*.popup_*.Spell.Check Message: @var{value} +@end smallexample + + It's impossible to specify a resource for all the menu-bar items +without also specifying it for the submenus as well. So if you want the +submenu items to look different from the menu bar itself, you must ask +for that in two steps. First, specify the resource for all of them; +then, override the value for submenus alone. Here is an example: + +@smallexample +Emacs.pane.menubar.*.fontList: 8x16 +Emacs.pane.menubar.popup_*.fontList: 8x16 +@end smallexample + +@noindent +For toolkit pop-up menus, use @samp{menu*} instead of +@samp{pane.menubar}. For example, to specify the font @samp{8x16} for +the pop-up menu items, write this: + +@smallexample +Emacs.menu*.fontList: 8x16 +@end smallexample + +@iftex +@medbreak +@end iftex + Here is a list of the specific resources for menu bars and pop-up menus: + +@table @code +@item armColor +The color to show in an armed button. +@item fontList +The font to use. +@item marginBottom +@itemx marginHeight +@itemx marginLeft +@itemx marginRight +@itemx marginTop +@itemx marginWidth +Amount of space to leave around the item, within the border. +@item borderWidth +The width of border around the menu item, on all sides. +@item shadowThickness +The width of the border shadow. +@item bottomShadowColor +The color for the border shadow, on the bottom and the right. +@item topShadowColor +The color for the border shadow, on the top and the left. +@end table diff --git a/man/commands.texi b/man/commands.texi new file mode 100644 index 00000000000..55696557514 --- /dev/null +++ b/man/commands.texi @@ -0,0 +1,251 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@iftex +@chapter Characters, Keys and Commands + + This chapter explains the character sets used by Emacs for input +commands and for the contents of files, and also explains the concepts +of @dfn{keys} and @dfn{commands}, which are fundamental for understanding +how Emacs interprets your keyboard and mouse input. +@end iftex + +@node User Input, Keys, Screen, Top +@section Kinds of User Input +@cindex input with the keyboard +@cindex keyboard input +@cindex character set (keyboard) +@cindex ASCII +@cindex C- +@cindex Control +@cindex control characters + + GNU Emacs uses an extension of the ASCII character set for keyboard +input; it also accepts non-character input events including function +keys and mouse button actions. + + ASCII consists of 128 character codes. Some of these codes are +assigned graphic symbols such as @samp{a} and @samp{=}; the rest are +control characters, such as @kbd{Control-a} (usually written @kbd{C-a} +for short). @kbd{C-a} gets its name from the fact that you type it by +holding down the @key{CTRL} key while pressing @kbd{a}. + + Some ASCII control characters have special names, and most terminals +have special keys you can type them with: for example, @key{RET}, +@key{TAB}, @key{DEL} and @key{ESC}. The space character is usually +referred to below as @key{SPC}, even though strictly speaking it is a +graphic character whose graphic happens to be blank. Some keyboards +have a key labeled ``linefeed'' which is an alias for @kbd{C-j}. + + Emacs extends the ASCII character set with thousands more printing +characters (@pxref{International}), additional control characters, and a +few more modifiers that can be combined with any character. + + On ASCII terminals, there are only 32 possible control characters. +These are the control variants of letters and @samp{@@[]\^_}. In +addition, the shift key is meaningless with control characters: +@kbd{C-a} and @kbd{C-A} are the same character, and Emacs cannot +distinguish them. + + But the Emacs character set has room for control variants of all +printing characters, and for distinguishing between @kbd{C-a} and +@kbd{C-A}. X Windows makes it possible to enter all these characters. +For example, @kbd{C--} (that's Control-Minus) and @kbd{C-5} are +meaningful Emacs commands under X. + + Another Emacs character-set extension is additional modifier bits. +Only one modifier bit is commonly used; it is called Meta. Every +character has a Meta variant; examples include @kbd{Meta-a} (normally +written @kbd{M-a}, for short), @kbd{M-A} (not the same character as +@kbd{M-a}, but those two characters normally have the same meaning in +Emacs), @kbd{M-@key{RET}}, and @kbd{M-C-a}. For reasons of tradition, +we usually write @kbd{C-M-a} rather than @kbd{M-C-a}; logically +speaking, the order in which the modifier keys @key{CTRL} and @key{META} +are mentioned does not matter. + +@cindex Meta +@cindex M- +@cindex @key{ESC} replacing @key{META} key + Some terminals have a @key{META} key, and allow you to type Meta +characters by holding this key down. Thus, @kbd{Meta-a} is typed by +holding down @key{META} and pressing @kbd{a}. The @key{META} key works +much like the @key{SHIFT} key. Such a key is not always labeled +@key{META}, however, as this function is often a special option for a key +with some other primary purpose.@refill + + If there is no @key{META} key, you can still type Meta characters +using two-character sequences starting with @key{ESC}. Thus, to enter +@kbd{M-a}, you could type @kbd{@key{ESC} a}. To enter @kbd{C-M-a}, you +would type @kbd{@key{ESC} C-a}. @key{ESC} is allowed on terminals with +@key{META} keys, too, in case you have formed a habit of using it. + + X Windows provides several other modifier keys that can be applied to +any input character. These are called @key{SUPER}, @key{HYPER} and +@key{ALT}. We write @samp{s-}, @samp{H-} and @samp{A-} to say that a +character uses these modifiers. Thus, @kbd{s-H-C-x} is short for +@kbd{Super-Hyper-Control-x}. Not all X terminals actually provide keys +for these modifier flags---in fact, many terminals have a key labeled +@key{ALT} which is really a @key{META} key. The standard key bindings +of Emacs do not include any characters with these modifiers. But you +can assign them meanings of your own by customizing Emacs. + + Keyboard input includes keyboard keys that are not characters at all: +for example function keys and arrow keys. Mouse buttons are also +outside the gamut of characters. You can modify these events with the +modifier keys @key{CTRL}, @key{META}, @key{SUPER}, @key{HYPER} and +@key{ALT}, just like keyboard characters. + +@cindex input event + Input characters and non-character inputs are collectively called +@dfn{input events}. @xref{Input Events,,, elisp, The Emacs Lisp +Reference Manual}, for more information. If you are not doing Lisp +programming, but simply want to redefine the meaning of some characters +or non-character events, see @ref{Customization}. + + ASCII terminals cannot really send anything to the computer except +ASCII characters. These terminals use a sequence of characters to +represent each function key. But that is invisible to the Emacs user, +because the keyboard input routines recognize these special sequences +and convert them to function key events before any other part of Emacs +gets to see them. + +@node Keys, Commands, User Input, Top +@section Keys + +@cindex key sequence +@cindex key + A @dfn{key sequence} (@dfn{key}, for short) is a sequence of input +events that are meaningful as a unit---as ``a single command.'' +Some Emacs command sequences are just one character or one event; for +example, just @kbd{C-f} is enough to move forward one character. But +Emacs also has commands that take two or more events to invoke. + +@cindex complete key +@cindex prefix key + If a sequence of events is enough to invoke a command, it is a +@dfn{complete key}. Examples of complete keys include @kbd{C-a}, +@kbd{X}, @key{RET}, @key{NEXT} (a function key), @key{DOWN} (an arrow +key), @kbd{C-x C-f}, and @kbd{C-x 4 C-f}. If it isn't long enough to be +complete, we call it a @dfn{prefix key}. The above examples show that +@kbd{C-x} and @kbd{C-x 4} are prefix keys. Every key sequence is either +a complete key or a prefix key. + + Most single characters constitute complete keys in the standard Emacs +command bindings. A few of them are prefix keys. A prefix key combines +with the following input event to make a longer key sequence, which may +itself be complete or a prefix. For example, @kbd{C-x} is a prefix key, +so @kbd{C-x} and the next input event combine to make a two-character +key sequence. Most of these key sequences are complete keys, including +@kbd{C-x C-f} and @kbd{C-x b}. A few, such as @kbd{C-x 4} and @kbd{C-x +r}, are themselves prefix keys that lead to three-character key +sequences. There's no limit to the length of a key sequence, but in +practice people rarely use sequences longer than four events. + + By contrast, you can't add more events onto a complete key. For +example, the two-character sequence @kbd{C-f C-k} is not a key, because +the @kbd{C-f} is a complete key in itself. It's impossible to give +@kbd{C-f C-k} an independent meaning as a command. @kbd{C-f C-k} is two +key sequences, not one.@refill + + All told, the prefix keys in Emacs are @kbd{C-c}, @kbd{C-h}, +@kbd{C-x}, @kbd{C-x @key{RET}}, @kbd{C-x @@}, @kbd{C-x a}, @kbd{C-x n}, @w{@kbd{C-x +r}}, @kbd{C-x v}, @kbd{C-x 4}, @kbd{C-x 5}, @kbd{C-x 6}, @key{ESC}, +@kbd{M-g} and @kbd{M-j}. But this list is not cast in concrete; it is +just a matter of Emacs's standard key bindings. If you customize Emacs, +you can make new prefix keys, or eliminate these. @xref{Key Bindings}. + + If you do make or eliminate prefix keys, that changes the set of +possible key sequences. For example, if you redefine @kbd{C-f} as a +prefix, @kbd{C-f C-k} automatically becomes a key (complete, unless you +define it too as a prefix). Conversely, if you remove the prefix +definition of @kbd{C-x 4}, then @kbd{C-x 4 f} (or @kbd{C-x 4 +@var{anything}}) is no longer a key. + + Typing the help character (@kbd{C-h} or @key{F1}) after a prefix +character displays a list of the commands starting with that prefix. +There are a few prefix characters for which @kbd{C-h} does not +work---for historical reasons, they have other meanings for @kbd{C-h} +which are not easy to change. But @key{F1} should work for all prefix +characters. + +@node Commands, Text Characters, Keys, Top +@section Keys and Commands + +@cindex binding +@cindex function +@cindex command +@cindex function definition + This manual is full of passages that tell you what particular keys +do. But Emacs does not assign meanings to keys directly. Instead, +Emacs assigns meanings to named @dfn{commands}, and then gives keys +their meanings by @dfn{binding} them to commands. + + Every command has a name chosen by a programmer. The name is usually +made of a few English words separated by dashes; for example, +@code{next-line} or @code{forward-word}. A command also has a +@dfn{function definition} which is a Lisp program; this is what makes +the command do what it does. In Emacs Lisp, a command is actually a +special kind of Lisp function; one which specifies how to read arguments +for it and call it interactively. For more information on commands and +functions, see @ref{What Is a Function,, What Is a Function, elisp, The +Emacs Lisp Reference Manual}. (The definition we use in this manual is +simplified slightly.) + + The bindings between keys and commands are recorded in various tables +called @dfn{keymaps}. @xref{Keymaps}. + + When we say that ``@kbd{C-n} moves down vertically one line'' we are +glossing over a distinction that is irrelevant in ordinary use but is vital +in understanding how to customize Emacs. It is the command +@code{next-line} that is programmed to move down vertically. @kbd{C-n} has +this effect @emph{because} it is bound to that command. If you rebind +@kbd{C-n} to the command @code{forward-word} then @kbd{C-n} will move +forward by words instead. Rebinding keys is a common method of +customization.@refill + + In the rest of this manual, we usually ignore this subtlety to keep +things simple. To give the information needed for customization, we +state the name of the command which really does the work in parentheses +after mentioning the key that runs it. For example, we will say that +``The command @kbd{C-n} (@code{next-line}) moves point vertically +down,'' meaning that @code{next-line} is a command that moves vertically +down and @kbd{C-n} is a key that is standardly bound to it. + + While we are on the subject of information for customization only, +it's a good time to tell you about @dfn{variables}. Often the +description of a command will say, ``To change this, set the variable +@code{mumble-foo}.'' A variable is a name used to remember a value. +Most of the variables documented in this manual exist just to facilitate +customization: some command or other part of Emacs examines the variable +and behaves differently according to the value that you set. Until you +are interested in customizing, you can ignore the information about +variables. When you are ready to be interested, read the basic +information on variables, and then the information on individual +variables will make sense. @xref{Variables}. + +@node Text Characters, Entering Emacs, Commands, Top +@section Character Set for Text +@cindex characters (in text) + + Text in Emacs buffers is a sequence of 8-bit bytes. Each byte can +hold a single ASCII character. Both ASCII control characters (octal +codes 000 through 037, and 0177) and ASCII printing characters (codes +040 through 0176) are allowed; however, non-ASCII control characters +cannot appear in a buffer. The other modifier flags used in keyboard +input, such as Meta, are not allowed in buffers either. + + Some ASCII control characters serve special purposes in text, and have +special names. For example, the newline character (octal code 012) is +used in the buffer to end a line, and the tab character (octal code 011) +is used for indenting to the next tab stop column (normally every 8 +columns). @xref{Text Display}. + + Non-ASCII printing characters can also appear in buffers. When +multibyte characters are enabled, you can use any of the non-ASCII +printing characters that Emacs supports. They have character codes +starting at 256, octal 0400, and each one is represented as a sequence +of two or more bytes. @xref{International}. + + If you disable multibyte characters, then you can use only one +alphabet of non-ASCII characters, but they all fit in one byte. They +use codes 0200 through 0377. @xref{Single-Byte European Support}. diff --git a/man/custom.texi b/man/custom.texi new file mode 100644 index 00000000000..3e4d627b0a9 --- /dev/null +++ b/man/custom.texi @@ -0,0 +1,2290 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Customization, Quitting, Amusements, Top +@chapter Customization +@cindex customization + + This chapter talks about various topics relevant to adapting the +behavior of Emacs in minor ways. See @cite{The Emacs Lisp Reference +Manual} for how to make more far-reaching changes. + + All kinds of customization affect only the particular Emacs session +that you do them in. They are completely lost when you kill the Emacs +session, and have no effect on other Emacs sessions you may run at the +same time or later. The only way an Emacs session can affect anything +outside of it is by writing a file; in particular, the only way to make +a customization ``permanent'' is to put something in your @file{.emacs} +file or other appropriate file to do the customization in each session. +@xref{Init File}. + +@menu +* Minor Modes:: Each minor mode is one feature you can turn on + independently of any others. +* Variables:: Many Emacs commands examine Emacs variables + to decide what to do; by setting variables, + you can control their functioning. +* Keyboard Macros:: A keyboard macro records a sequence of + keystrokes to be replayed with a single + command. +* Key Bindings:: The keymaps say what command each key runs. + By changing them, you can "redefine keys". +* Keyboard Translations:: + If your keyboard passes an undesired code + for a key, you can tell Emacs to + substitute another code. +* Syntax:: The syntax table controls how words and + expressions are parsed. +* Init File:: How to write common customizations in the + @file{.emacs} file. +@end menu + +@node Minor Modes +@section Minor Modes +@cindex minor modes +@cindex mode, minor + + Minor modes are optional features which you can turn on or off. For +example, Auto Fill mode is a minor mode in which @key{SPC} breaks lines +between words as you type. All the minor modes are independent of each +other and of the selected major mode. Most minor modes say in the mode +line when they are on; for example, @samp{Fill} in the mode line means +that Auto Fill mode is on. + + Append @code{-mode} to the name of a minor mode to get the name of a +command function that turns the mode on or off. Thus, the command to +enable or disable Auto Fill mode is called @kbd{M-x auto-fill-mode}. These +commands are usually invoked with @kbd{M-x}, but you can bind keys to them +if you wish. With no argument, the function turns the mode on if it was +off and off if it was on. This is known as @dfn{toggling}. A positive +argument always turns the mode on, and an explicit zero argument or a +negative argument always turns it off. + + Enabling or disabling some minor modes applies only to the current +buffer; each buffer is independent of the other buffers. Therefore, you +can enable the mode in particular buffers and disable it in others. The +per-buffer minor modes include Abbrev mode, Auto Fill mode, Auto Save +mode, Font-Lock mode, Hscroll mode, ISO Accents mode, Outline minor +mode, Overwrite mode, and Binary Overwrite mode. + + Abbrev mode allows you to define abbreviations that automatically expand +as you type them. For example, @samp{amd} might expand to @samp{abbrev +mode}. @xref{Abbrevs}, for full information. + + Auto Fill mode allows you to enter filled text without breaking lines +explicitly. Emacs inserts newlines as necessary to prevent lines from +becoming too long. @xref{Filling}. + + Auto Save mode causes the contents of a buffer to be saved +periodically to reduce the amount of work you can lose in case of a +system crash. @xref{Auto Save}. + + Enriched mode enables editing and saving of formatted text. +@xref{Formatted Text}. + + Flyspell mode automatically highlights misspelled words. +@xref{Spelling}. + + Font-Lock mode automatically highlights certain textual units found in +programs, such as comments, strings, and function names being defined. +This requires a window system that can display multiple fonts. +@xref{Faces}. + + Hscroll mode performs horizontal scrolling automatically +to keep point on the screen. @xref{Horizontal Scrolling}. + + ISO Accents mode makes the characters @samp{`}, @samp{'}, @samp{"}, +@samp{^}, @samp{/} and @samp{~} combine with the following letter, to +produce an accented letter in the ISO Latin-1 character set. +@xref{Single-Byte European Support}. + + Outline minor mode provides the same facilities as the major mode +called Outline mode; but since it is a minor mode instead, you can +combine it with any major mode. @xref{Outline Mode}. + +@cindex Overwrite mode +@cindex mode, Overwrite +@findex overwrite-mode +@findex binary-overwrite-mode + Overwrite mode causes ordinary printing characters to replace existing +text instead of shoving it to the right. For example, if point is in +front of the @samp{B} in @samp{FOOBAR}, then in Overwrite mode typing a +@kbd{G} changes it to @samp{FOOGAR}, instead of producing @samp{FOOGBAR} +as usual. In Overwrite mode, the command @kbd{C-q} inserts the next +character whatever it may be, even if it is a digit---this gives you a +way to insert a character instead of replacing an existing character. + + Binary Overwrite mode is a variant of Overwrite mode for editing +binary files; it treats newlines and tabs like other characters, so that +they overwrite other characters and can be overwritten by them. + + The following minor modes normally apply to all buffers at once. +Since each is enabled or disabled by the value of a variable, you +@emph{can} set them differently for particular buffers, by explicitly +making the corresponding variables local in those buffers. +@xref{Locals}. + + Icomplete mode displays an indication of available completions when +you are in the minibuffer and completion is active. @xref{Completion +Options}. + + Line Number mode enables continuous display in the mode line of the +line number of point. @xref{Mode Line}. + + Resize-Minibuffer mode makes the minibuffer expand as necessary to +hold the text that you put in it. @xref{Minibuffer Edit}. + + Scroll Bar mode gives each window a scroll bar (@pxref{Scroll Bars}). +Menu Bar mode gives each frame a menu bar (@pxref{Menu Bars}). Both of +these modes are enabled by default when you use the X Window System. + + In Transient Mark mode, every change in the buffer contents +``deactivates'' the mark, so that commands that operate on the region +will get an error. This means you must either set the mark, or +explicitly ``reactivate'' it, before each command that uses the region. +The advantage of Transient Mark mode is that Emacs can display the +region highlighted (currently only when using X). @xref{Setting Mark}. + + For most minor modes, the command name is also the name of a variable +which directly controls the mode. The mode is enabled whenever this +variable's value is non-@code{nil}, and the minor-mode command works by +setting the variable. For example, the command +@code{outline-minor-mode} works by setting the value of +@code{outline-minor-mode} as a variable; it is this variable that +directly turns Outline minor mode on and off. To check whether a given +minor mode works this way, use @kbd{C-h v} to ask for documentation on +the variable name. + + These minor-mode variables provide a good way for Lisp programs to turn +minor modes on and off; they are also useful in a file's local variables +list. But please think twice before setting minor modes with a local +variables list, because most minor modes are matter of user +preference---other users editing the same file might not want the same +minor modes you prefer. + +@node Variables +@section Variables +@cindex variable +@cindex option, user +@cindex user option + + A @dfn{variable} is a Lisp symbol which has a value. The symbol's +name is also called the name of the variable. A variable name can +contain any characters that can appear in a file, but conventionally +variable names consist of words separated by hyphens. A variable can +have a documentation string which describes what kind of value it should +have and how the value will be used. + + Lisp allows any variable to have any kind of value, but most variables +that Emacs uses require a value of a certain type. Often the value should +always be a string, or should always be a number. Sometimes we say that a +certain feature is turned on if a variable is ``non-@code{nil},'' meaning +that if the variable's value is @code{nil}, the feature is off, but the +feature is on for @emph{any} other value. The conventional value to use to +turn on the feature---since you have to pick one particular value when you +set the variable---is @code{t}. + + Emacs uses many Lisp variables for internal record keeping, as any +Lisp program must, but the most interesting variables for you are the +ones that exist for the sake of customization. Emacs does not (usually) +change the values of these variables; instead, you set the values, and +thereby alter and control the behavior of certain Emacs commands. These +variables are called @dfn{user options}. Most user options are +documented in this manual, and appear in the Variable Index +(@pxref{Variable Index}). + + One example of a variable which is a user option is @code{fill-column}, which +specifies the position of the right margin (as a number of characters from +the left margin) to be used by the fill commands (@pxref{Filling}). + +@menu +* Examining:: Examining or setting one variable's value. +* Easy Customization:: + Convenient and easy customization of variables. +* Hooks:: Hook variables let you specify programs for parts + of Emacs to run on particular occasions. +* Locals:: Per-buffer values of variables. +* File Variables:: How files can specify variable values. +@end menu + +@node Examining +@subsection Examining and Setting Variables +@cindex setting variables + +@table @kbd +@item C-h v @var{var} @key{RET} +Display the value and documentation of variable @var{var} +(@code{describe-variable}). +@item M-x set-variable @key{RET} @var{var} @key{RET} @var{value} @key{RET} +Change the value of variable @var{var} to @var{value}. +@end table + + To examine the value of a single variable, use @kbd{C-h v} +(@code{describe-variable}), which reads a variable name using the +minibuffer, with completion. It displays both the value and the +documentation of the variable. For example, + +@example +C-h v fill-column @key{RET} +@end example + +@noindent +displays something like this: + +@smallexample +fill-column's value is 75 + +Documentation: +*Column beyond which automatic line-wrapping should happen. +Automatically becomes buffer-local when set in any fashion. +@end smallexample + +@noindent +The star at the beginning of the documentation indicates that this +variable is a user option. @kbd{C-h v} is not restricted to user +options; it allows any variable name. + +@findex set-variable + The most convenient way to set a specific user option is with @kbd{M-x +set-variable}. This reads the variable name with the minibuffer (with +completion), and then reads a Lisp expression for the new value using +the minibuffer a second time. For example, + +@example +M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} +@end example + +@noindent +sets @code{fill-column} to 75. + + @kbd{M-x set-variable} is limited to user option variables, but you can +set any variable with a Lisp expression, using the function @code{setq}. +Here is a @code{setq} expression to set @code{fill-column}: + +@example +(setq fill-column 75) +@end example + + To execute an expression like this one, go to the @samp{*scratch*} +buffer, type in the expression, and then type @kbd{C-j}. @xref{Lisp +Interaction}. + + Setting variables, like all means of customizing Emacs except where +otherwise stated, affects only the current Emacs session. + +@node Easy Customization +@subsection Easy Customization Interface + +@findex customize +@cindex customization buffer + A convenient way to find the user option variables that you want to +change, and then change them, is with @kbd{M-x customize}. This command +creates a @dfn{customization buffer} with which you can browse through +the Emacs user options in a logically organized structure, then edit and +set their values. You can also use the customization buffer to save +settings permanently. (Not all Emacs user options are included in this +structure as of yet, but we are adding the rest.) + +@menu +* Groups: Customization Groups. + How options are classified in a structure. +* Changing an Option:: How to edit a value and set an option. +* Face Customization:: How to edit the attributes of a face. +* Specific Customization:: Making a customization buffer for specific + options, faces, or groups. +@end menu + +@node Customization Groups +@subsubsection Customization Groups +@cindex customization groups + + For customization purposes, user options are organized into +@dfn{groups} to help you find them. Groups are collected into bigger +groups, all the way up to a master group called @code{Emacs}. + + @kbd{M-x customize} creates a customization buffer that shows the +top-level @code{Emacs} group and the second-level groups immediately +under it. It looks like this, in part: + +@smallexample +/- Emacs group: ---------------------------------------------------\ + [State]: visible group members are all at standard settings. + Customization of the One True Editor. + See also [Manual]. + +Editing group: [Go to Group] +Basic text editing facilities. + +External group: [Go to Group] +Interfacing to external utilities. + +@var{more second-level groups} + +\- Emacs group end ------------------------------------------------/ + +@end smallexample + +@noindent +This says that the buffer displays the contents of the @code{Emacs} +group. The other groups are listed because they are its contents. But +they are listed differently, without indentation and dashes, because +@emph{their} contents are not included. Each group has a single-line +documentation string; the @code{Emacs} group also has a @samp{[State]} +line. + +@cindex editable fields (customization buffer) +@cindex active fields (customization buffer) + Most of the text in the customization buffer is read-only, but it +typically includes some @dfn{editable fields} that you can edit. There +are also @dfn{active fields}; this means a field that does something +when you @dfn{invoke} it. To invoke an active field, either click on it +with @kbd{Mouse-1}, or move point to it and type @key{RET}. + + For example, the phrase @samp{[Go to Group]} that appears in a +second-level group is an active field. Invoking the @samp{[Go to +Group]} field for a group creates a new customization buffer, which +shows that group and its contents. This field is a kind of hypertext +link to another group. + + The @code{Emacs} group does not include any user options itself, but +other groups do. By examining various groups, you will eventually find +the options and faces that belong to the feature you are interested in +customizing. Then you can use the customization buffer to set them. + +@findex customize-browse + You can view the structure of customization groups on a larger scale +with @kbd{M-x customize-browse}. This command creates a special kind of +customization buffer which shows only the names of the groups (and +options and faces), and their structure. + + In this buffer, you can show the contents of a group by invoking +@samp{[+]}. When the group contents are visible, this button changes to +@samp{[-]}; invoking that hides the group contents. + + Each group, option or face name in this buffer has an active field +which says @samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking +that active field creates an ordinary customization buffer showing just +that group and its contents, just that option, or just that face. +This is the way to set values in it. + +@node Changing an Option +@subsubsection Changing an Option + + Here is an example of what a user option looks like in the +customization buffer: + +@smallexample +Kill Ring Max: [Hide] 30 + [State]: this option is unchanged from its standard setting. +Maximum length of kill ring before oldest elements are thrown away. +@end smallexample + + The text following @samp{[Hide]}, @samp{30} in this case, indicates +the current value of the option. If you see @samp{[Show]} instead of +@samp{[Hide]}, it means that the value is hidden; the customization +buffer initially hides values that take up several lines. Invoke +@samp{[Show]} to show the value. + + The line after the option name indicates the @dfn{customization state} +of the option: in the example above, it says you have not changed the +option yet. The word @samp{[State]} at the beginning of this line is +active; you can get a menu of various operations by invoking it with +@kbd{Mouse-1} or @key{RET}. These operations are essential for +customizing the variable. + + The line after the @samp{[State]} line displays the beginning of the +option's documentation string. If there are more lines of +documentation, this line ends with @samp{[More]}; invoke this to show +the full documentation string. + + To enter a new value for @samp{Kill Ring Max}, move point to the value +and edit it textually. For example, you can type @kbd{M-d}, then insert +another number. + + When you begin to alter the text, you will see the @samp{[State]} line +change to say that you have edited the value: + +@smallexample +[State]: you have edited the value as text, but not set the option. +@end smallexample + +@cindex setting option value + Editing the value does not actually set the option variable. To do +that, you must @dfn{set} the option. To do this, invoke the word +@samp{[State]} and choose @samp{Set for Current Session}. + + The state of the option changes visibly when you set it: + +@smallexample +[State]: you have set this option, but not saved it for future sessions. +@end smallexample + + You don't have to worry about specifying a value that is not valid; +setting the option checks for validity and will not really install an +unacceptable value. + +@kindex M-TAB @r{(customization buffer)} +@findex widget-complete + While editing a value or field that is a file name, directory name, +command name, or anything else for which completion is defined, you can +type @kbd{M-@key{TAB}} (@code{widget-complete}) to do completion. + + Some options have a small fixed set of possible legitimate values. +These options don't let you edit the value textually. Instead, an +active field @samp{[Value Menu]} appears before the value; invoke this +field to edit the value. For a boolean ``on or off'' value, the active +field says @samp{[Toggle]}, and it changes to the other value. +@samp{[Value Menu]} and @samp{[Toggle]} edit the buffer; the changes +take effect when you use the @samp{Set for Current Session} operation. + + Some options have values with complex structure. For example, the +value of @code{load-path} is a list of directories. Here is how it +appears in the customization buffer: + +@smallexample +Load Path: +[INS] [DEL] [Current dir?]: /usr/local/share/emacs/20.3/site-lisp +[INS] [DEL] [Current dir?]: /usr/local/share/emacs/site-lisp +[INS] [DEL] [Current dir?]: /usr/local/share/emacs/20.3/leim +[INS] [DEL] [Current dir?]: /usr/local/share/emacs/20.3/lisp +[INS] [DEL] [Current dir?]: /build/emacs/e20/lisp +[INS] [DEL] [Current dir?]: /build/emacs/e20/lisp/gnus +[INS] + [State]: this item has been changed outside the customization buffer. +List of directories to search for files to load.... +@end smallexample + +@noindent +Each directory in the list appears on a separate line, and each line has +several editable or active fields. + + You can edit any of the directory names. To delete a directory from +the list, invoke @samp{[DEL]} on that line. To insert a new directory in +the list, invoke @samp{[INS]} at the point where you want to insert it. + + You can also invoke @samp{[Current dir?]} to switch between including +a specific named directory in the path, and including @code{nil} in the +path. (@code{nil} in a search path means ``try the current +directory.'') + +@kindex TAB @r{(customization buffer)} +@kindex S-TAB @r{(customization buffer)} +@findex widget-forward +@findex widget-backward + Two special commands, @key{TAB} and @kbd{S-@key{TAB}}, are useful for +moving through the customization buffer. @key{TAB} +(@code{widget-forward}) moves forward to the next active or editable +field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to the +previous active or editable field. + + Typing @key{RET} on an editable field also moves forward, just like +@key{TAB}. The reason for this is that people have a tendency to type +@key{RET} when they are finished editing a field. If you have occasion +to insert a newline in an editable field, use @kbd{C-o} or @kbd{C-q +C-j}. + +@cindex saving option value + Setting the option changes its value in the current Emacs session; +@dfn{saving} the value changes it for future sessions as well. This +works by writing code into your @file{~/.emacs} file so as to set the +option variable again each time you start Emacs. To save the option, +invoke @samp{[State]} and select the @samp{Save for Future Sessions} +operation. + + You can also restore the option to its standard value by invoking +@samp{[State]} and selecting the @samp{Reset to Standard Settings} +operation. There are actually three reset operations: + +@table @samp +@item Reset +If you have made some modifications and not yet set the option, +this restores the text in the customization buffer to match +the actual value. + +@item Reset to Saved +This restores the value of the option to the last saved value, +and updates the text accordingly. + +@item Reset to Standard Settings +This sets the option to its standard value, and updates the text +accordingly. This also eliminates any saved value for the option, +so that you will get the standard value in future Emacs sessions. +@end table + + The state of a group indicates whether anything in that group has been +edited, set or saved. You can select @samp{Set for Current Session}, +@samp{Save for Future Sessions} and the various kinds of @samp{Reset} +operation for the group; these operations on the group apply to all +options in the group and its subgroups. + + Near the top of the customization buffer there are two lines +containing several active fields: + +@smallexample + [Set for Current Session] [Save for Future Sessions] + [Reset] [Reset to Saved] [Reset to Standard] [Bury Buffer] +@end smallexample + +@noindent +Invoking @samp{[Bury Buffer]} buries this customization buffer. Each of +the other fields performs an operation---set, save or reset---on each of +the items in the buffer that could meaningfully be set, saved or reset. + +@node Face Customization +@subsubsection Customizing Faces +@cindex customizing faces +@cindex bold font +@cindex italic font +@cindex fonts and faces + + In addition to user options, some customization groups also include +faces. When you show the contents of a group, both the user options and +the faces in the group appear in the customization buffer. Here is an +example of how a face looks: + +@smallexample +Custom Changed Face: (sample) + [State]: this face is unchanged from its standard setting. +Face used when the customize item has been changed. +Attributes: [ ] Bold: [toggle] off + [X] Italic: [toggle] on + [ ] Underline: [toggle] off + [ ] Inverse-Video: [toggle] on + [ ] Foreground: black (sample) + [ ] Background: white (sample) + [ ] Stipple: +@end smallexample + + Each face attribute has its own line. The @samp{[@var{x}]} field +before the attribute name indicates whether the attribute is +@dfn{enabled}; @samp{X} means that it is. You can enable or disable the +attribute by invoking that field. When the attribute is enabled, you +can change the attribute value in the usual ways. + + On a black-and-white display, the colors you can use for the +background are @samp{black}, @samp{white}, @samp{gray}, @samp{gray1}, +and @samp{gray3}. Emacs supports these shades of gray by using +background stipple patterns instead of a color. + + Setting, saving and resetting a face work like the same operations for +options (@pxref{Changing an Option}). + + A face can specify different appearances for different types of +display. For example, a face can make text red on a color display, but +use a bold font on a monochrome display. To specify multiple +appearances for a face, select @samp{Show Display Types} in the menu you +get from invoking @samp{[State]}. + +@findex modify-face + Another more basic way to set the attributes of a specific face is +with @kbd{M-x modify-face}. This command reads the name of a face, then +reads the attributes one by one. For the color and stipple attributes, +the attribute's current value is the default---type just @key{RET} if +you don't want to change that attribute. Type @samp{none} if you want +to clear out the attribute. + +@node Specific Customization +@subsubsection Customizing Specific Items + + Instead of finding the options you want to change by moving down +through the structure of groups, you can specify the particular option, +face or group that you want to customize. + +@table @kbd +@item M-x customize-option @key{RET} @var{option} @key{RET} +Set up a customization buffer with just one option, @var{option}. +@item M-x customize-face @key{RET} @var{face} @key{RET} +Set up a customization buffer with just one face, @var{face}. +@item M-x customize-group @key{RET} @var{group} @key{RET} +Set up a customization buffer with just one group, @var{group}. +@item M-x customize-apropos @key{RET} @var{regexp} @key{RET} +Set up a customization buffer with all the options, faces and groups +that match @var{regexp}. +@item M-x customize-changed-options @key{RET} @var{version} @key{RET} +Set up a customization buffer with all the options, faces and groups +whose meaning has changed since Emacs version @var{version}. +@item M-x customize-saved +Set up a customization buffer containing all options and faces that you +have saved with customization buffers. +@item M-x customize-customized +Set up a customization buffer containing all options and faces that you +have customized but not saved. +@end table + +@findex customize-option + If you want to alter a particular user option variable with the +customization buffer, and you know its name, you can use the command +@kbd{M-x customize-option} and specify the option name. This sets up +the customization buffer with just one option---the one that you asked +for. Editing, setting and saving the value work as described above, but +only for the specified option. + +@findex customize-face + Likewise, you can modify a specific face, chosen by name, using +@kbd{M-x customize-face}. + +@findex customize-group + You can also set up the customization buffer with a specific group, +using @kbd{M-x customize-group}. The immediate contents of the chosen +group, including option variables, faces, and other groups, all appear +as well. However, these subgroups' own contents start out hidden. You +can show their contents in the usual way, by invoking @samp{[Show]}. + +@findex customize-apropos + To control more precisely what to customize, you can use @kbd{M-x +customize-apropos}. You specify a regular expression as argument; then +all options, faces and groups whose names match this regular expression +are set up in the customization buffer. If you specify an empty regular +expression, this includes @emph{all} groups, options and faces in the +customization buffer (but that takes a long time). + +@findex customize-changed-options + When you upgrade to a new Emacs version, you might want to customize +new options and options whose meanings or default values have changed. +To do this, use @kbd{M-x customize-changed-options} and specify a +previous Emacs version number using the minibuffer. It creates a +customization buffer which shows all the options (and groups) whose +definitions have been changed since the specified version. + +@findex customize-saved +@findex customize-customized + If you change option values and then decide the change was a mistake, +you can use two special commands to revisit your previous changes. Use +@kbd{customize-saved} to look at the options and faces that you have +saved. Use @kbd{M-x customize-customized} to look at the options and +faces that you have set but not saved. + +@node Hooks +@subsection Hooks +@cindex hook +@cindex hook function +@cindex running a hook + + @dfn{Hooks} are an important mechanism for customization of Emacs. A +hook is a Lisp variable which holds a list of functions, to be called on +some well-defined occasion. (This is called @dfn{running the hook}.) +The individual functions in the list are called the @dfn{hook functions} +of the hook. With rare exceptions, hooks in Emacs are empty when Emacs +starts up, so the only hook functions in any given hook are the ones you +explicitly put there as customization. + + Most major modes run one or more @dfn{mode hooks} as the last step of +initialization. This makes it easy for you to customize the behavior of +the mode, by setting up a hook function to override the local variable +assignments already made by the mode. But hooks are also used in other +contexts. For example, the hook @code{suspend-hook} runs just before +Emacs suspends itself (@pxref{Exiting}). + +@cindex normal hook + Most Emacs hooks are @dfn{normal hooks}. This means that running the +hook operates by calling all the hook functions, unconditionally, with +no arguments. We have made an effort to keep most hooks normal so that +you can use them in a uniform way. Every variable in Emacs whose name +ends in @samp{-hook} is a normal hook. + +@cindex abnormal hook + There are also a few @dfn{abnormal hooks}. These variables' names end +in @samp{-hooks} or @samp{-functions}, instead of @samp{-hook}. What +makes these hooks abnormal is that there is something peculiar about the +way its functions are called---perhaps they are given arguments, or +perhaps the values they return are used in some way. For example, +@code{find-file-not-found-hooks} (@pxref{Visiting}) is abnormal because +as soon as one hook function returns a non-@code{nil} value, the rest +are not called at all. The documentation of each abnormal hook variable +explains in detail what is peculiar about it. + + The recommended way to add a hook function to a hook (either normal or +abnormal) is by calling @code{add-hook}. You can use any valid Lisp +function as the hook function, provided it can handle the proper number +of arguments (zero arguments, in the case of a normal hook). Of course, +not every Lisp function is @emph{useful} in any particular hook. + + For example, here's how to set up a hook to turn on Auto Fill mode +when entering Text mode and other modes based on Text mode: + +@example +(add-hook 'text-mode-hook 'turn-on-auto-fill) +@end example + + The next example shows how to use a hook to customize the indentation +of C code. (People often have strong personal preferences for one +format compared to another.) Here the hook function is an anonymous +lambda expression. + +@example +@group +(setq my-c-style + '((c-comment-only-line-offset . 4) +@end group +@group + (c-cleanup-list . (scope-operator + empty-defun-braces + defun-close-semi)) +@end group +@group + (c-offsets-alist . ((arglist-close . c-lineup-arglist) + (substatement-open . 0))))) +@end group + +@group +(add-hook 'c-mode-common-hook + (function (lambda () + (c-add-style "my-style" my-c-style t)))) +@end group +@end example + + It is best to design your hook functions so that the order in which +they are executed does not matter. Any dependence on the order is +``asking for trouble.'' However, the order is predictable: the most +recently added hook functions are executed first. + +@node Locals +@subsection Local Variables + +@table @kbd +@item M-x make-local-variable @key{RET} @var{var} @key{RET} +Make variable @var{var} have a local value in the current buffer. +@item M-x kill-local-variable @key{RET} @var{var} @key{RET} +Make variable @var{var} use its global value in the current buffer. +@item M-x make-variable-buffer-local @key{RET} @var{var} @key{RET} +Mark variable @var{var} so that setting it will make it local to the +buffer that is current at that time. +@end table + +@cindex local variables + Almost any variable can be made @dfn{local} to a specific Emacs +buffer. This means that its value in that buffer is independent of its +value in other buffers. A few variables are always local in every +buffer. Every other Emacs variable has a @dfn{global} value which is in +effect in all buffers that have not made the variable local. + +@findex make-local-variable + @kbd{M-x make-local-variable} reads the name of a variable and makes it +local to the current buffer. Further changes in this buffer will not +affect others, and further changes in the global value will not affect this +buffer. + +@findex make-variable-buffer-local +@cindex per-buffer variables + @kbd{M-x make-variable-buffer-local} reads the name of a variable and +changes the future behavior of the variable so that it will become local +automatically when it is set. More precisely, once a variable has been +marked in this way, the usual ways of setting the variable automatically +do @code{make-local-variable} first. We call such variables +@dfn{per-buffer} variables. + + Major modes (@pxref{Major Modes}) always make variables local to the +buffer before setting the variables. This is why changing major modes +in one buffer has no effect on other buffers. Minor modes also work by +setting variables---normally, each minor mode has one controlling +variable which is non-@code{nil} when the mode is enabled (@pxref{Minor +Modes}). For most minor modes, the controlling variable is per buffer. + + Emacs contains a number of variables that are always per-buffer. +These include @code{abbrev-mode}, @code{auto-fill-function}, +@code{case-fold-search}, @code{comment-column}, @code{ctl-arrow}, +@code{fill-column}, @code{fill-prefix}, @code{indent-tabs-mode}, +@code{left-margin}, @code{mode-line-format}, @code{overwrite-mode}, +@code{selective-display-ellipses}, @code{selective-display}, +@code{tab-width}, and @code{truncate-lines}. Some other variables are +always local in every buffer, but they are used for internal +purposes.@refill + + A few variables cannot be local to a buffer because they are always +local to each display instead (@pxref{Multiple Displays}). If you try to +make one of these variables buffer-local, you'll get an error message. + +@findex kill-local-variable + @kbd{M-x kill-local-variable} reads the name of a variable and makes +it cease to be local to the current buffer. The global value of the +variable henceforth is in effect in this buffer. Setting the major mode +kills all the local variables of the buffer except for a few variables +specially marked as @dfn{permanent locals}. + +@findex setq-default + To set the global value of a variable, regardless of whether the +variable has a local value in the current buffer, you can use the Lisp +construct @code{setq-default}. This construct is used just like +@code{setq}, but it sets variables' global values instead of their local +values (if any). When the current buffer does have a local value, the +new global value may not be visible until you switch to another buffer. +Here is an example: + +@example +(setq-default fill-column 75) +@end example + +@noindent +@code{setq-default} is the only way to set the global value of a variable +that has been marked with @code{make-variable-buffer-local}. + +@findex default-value + Lisp programs can use @code{default-value} to look at a variable's +default value. This function takes a symbol as argument and returns its +default value. The argument is evaluated; usually you must quote it +explicitly. For example, here's how to obtain the default value of +@code{fill-column}: + +@example +(default-value 'fill-column) +@end example + +@node File Variables +@subsection Local Variables in Files +@cindex local variables in files +@cindex file local variables + + A file can specify local variable values for use when you edit the +file with Emacs. Visiting the file checks for local variable +specifications; it automatically makes these variables local to the +buffer, and sets them to the values specified in the file. + + There are two ways to specify local variable values: in the first +line, or with a local variables list. Here's how to specify them in the +first line: + +@example +-*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*- +@end example + +@noindent +You can specify any number of variables/value pairs in this way, each +pair with a colon and semicolon as shown above. @code{mode: +@var{modename};} specifies the major mode; this should come first in the +line. The @var{value}s are not evaluated; they are used literally. +Here is an example that specifies Lisp mode and sets two variables with +numeric values: + +@smallexample +;; -*-mode: Lisp; fill-column: 75; comment-column: 50; -*- +@end smallexample + + You can also specify the coding system for a file in this way: just +specify a value for the ``variable'' named @code{coding}. The ``value'' +must be a coding system name that Emacs recognizes. @xref{Coding +Systems}. + + A @dfn{local variables list} goes near the end of the file, in the +last page. (It is often best to put it on a page by itself.) The local +variables list starts with a line containing the string @samp{Local +Variables:}, and ends with a line containing the string @samp{End:}. In +between come the variable names and values, one set per line, as +@samp{@var{variable}:@: @var{value}}. The @var{value}s are not +evaluated; they are used literally. If a file has both a local +variables list and a @samp{-*-} line, Emacs processes @emph{everything} +in the @samp{-*-} line first, and @emph{everything} in the local +variables list afterward. + +Here is an example of a local variables list: + +@example +;;; Local Variables: *** +;;; mode:lisp *** +;;; comment-column:0 *** +;;; comment-start: ";;; " *** +;;; comment-end:"***" *** +;;; End: *** +@end example + + As you see, each line starts with the prefix @samp{;;; } and each line +ends with the suffix @samp{ ***}. Emacs recognizes these as the prefix +and suffix based on the first line of the list, by finding them +surrounding the magic string @samp{Local Variables:}; then it +automatically discards them from the other lines of the list. + + The usual reason for using a prefix and/or suffix is to embed the +local variables list in a comment, so it won't confuse other programs +that the file is intended as input for. The example above is for a +language where comment lines start with @samp{;;; } and end with +@samp{***}; the local values for @code{comment-start} and +@code{comment-end} customize the rest of Emacs for this unusual syntax. +Don't use a prefix (or a suffix) if you don't need one. + + Two ``variable names'' have special meanings in a local variables +list: a value for the variable @code{mode} really sets the major mode, +and a value for the variable @code{eval} is simply evaluated as an +expression and the value is ignored. @code{mode} and @code{eval} are +not real variables; setting variables named @code{mode} and @code{eval} +in any other context has no special meaning. If @code{mode} is used to +set a major mode, it should be the first ``variable'' in the list. + + You can use the @code{mode} ``variable'' to set minor modes as well as +major modes; in fact, you can use it more than once, first to set the +major mode and then to set minor modes which are specific to particular +buffers. But most minor modes should not be specified in the file in +any fashion, because they represent user preferences. + + For example, you may be tempted to try to turn on Auto Fill mode with +a local variable list. That is a mistake. The choice of Auto Fill mode +or not is a matter of individual taste, not a matter of the contents of +particular files. If you want to use Auto Fill, set up major mode hooks +with your @file{.emacs} file to turn it on (when appropriate) for you +alone (@pxref{Init File}). Don't use a local variable list to impose +your taste on everyone. + + The start of the local variables list must be no more than 3000 +characters from the end of the file, and must be in the last page if the +file is divided into pages. Otherwise, Emacs will not notice it is +there. The purpose of this rule is so that a stray @samp{Local +Variables:}@: not in the last page does not confuse Emacs, and so that +visiting a long file that is all one page and has no local variables +list need not take the time to search the whole file. + + Use the command @code{normal-mode} to reset the local variables and +major mode of a buffer according to the file name and contents, +including the local variables list if any. @xref{Choosing Modes}. + +@findex enable-local-variables + The variable @code{enable-local-variables} controls whether to process +local variables in files, and thus gives you a chance to override them. +Its default value is @code{t}, which means do process local variables in +files. If you set the value to @code{nil}, Emacs simply ignores local +variables in files. Any other value says to query you about each file +that has local variables, showing you the local variable specifications +so you can judge. + +@findex enable-local-eval + The @code{eval} ``variable,'' and certain actual variables, create a +special risk; when you visit someone else's file, local variable +specifications for these could affect your Emacs in arbitrary ways. +Therefore, the option @code{enable-local-eval} controls whether Emacs +processes @code{eval} variables, as well variables with names that end +in @samp{-hook}, @samp{-hooks}, @samp{-function} or @samp{-functions}, +and certain other variables. The three possibilities for the option's +value are @code{t}, @code{nil}, and anything else, just as for +@code{enable-local-variables}. The default is @code{maybe}, which is +neither @code{t} nor @code{nil}, so normally Emacs does ask for +confirmation about file settings for these variables. + +@node Keyboard Macros +@section Keyboard Macros + +@cindex defining keyboard macros +@cindex keyboard macro + A @dfn{keyboard macro} is a command defined by the user to stand for +another sequence of keys. For example, if you discover that you are +about to type @kbd{C-n C-d} forty times, you can speed your work by +defining a keyboard macro to do @kbd{C-n C-d} and calling it with a +repeat count of forty. + +@c widecommands +@table @kbd +@item C-x ( +Start defining a keyboard macro (@code{start-kbd-macro}). +@item C-x ) +End the definition of a keyboard macro (@code{end-kbd-macro}). +@item C-x e +Execute the most recent keyboard macro (@code{call-last-kbd-macro}). +@item C-u C-x ( +Re-execute last keyboard macro, then add more keys to its definition. +@item C-x q +When this point is reached during macro execution, ask for confirmation +(@code{kbd-macro-query}). +@item M-x name-last-kbd-macro +Give a command name (for the duration of the session) to the most +recently defined keyboard macro. +@item M-x insert-kbd-macro +Insert in the buffer a keyboard macro's definition, as Lisp code. +@item C-x C-k +Edit a previously defined keyboard macro (@code{edit-kbd-macro}). +@item M-x apply-macro-to-region-lines +Run the last keyboard macro on each complete line in the region. +@end table + + Keyboard macros differ from ordinary Emacs commands in that they are +written in the Emacs command language rather than in Lisp. This makes it +easier for the novice to write them, and makes them more convenient as +temporary hacks. However, the Emacs command language is not powerful +enough as a programming language to be useful for writing anything +intelligent or general. For such things, Lisp must be used. + + You define a keyboard macro while executing the commands which are the +definition. Put differently, as you define a keyboard macro, the +definition is being executed for the first time. This way, you can see +what the effects of your commands are, so that you don't have to figure +them out in your head. When you are finished, the keyboard macro is +defined and also has been, in effect, executed once. You can then do the +whole thing over again by invoking the macro. + +@menu +* Basic Kbd Macro:: Defining and running keyboard macros. +* Save Kbd Macro:: Giving keyboard macros names; saving them in files. +* Kbd Macro Query:: Making keyboard macros do different things each time. +@end menu + +@node Basic Kbd Macro +@subsection Basic Use + +@kindex C-x ( +@kindex C-x ) +@kindex C-x e +@findex start-kbd-macro +@findex end-kbd-macro +@findex call-last-kbd-macro + To start defining a keyboard macro, type the @kbd{C-x (} command +(@code{start-kbd-macro}). From then on, your keys continue to be +executed, but also become part of the definition of the macro. @samp{Def} +appears in the mode line to remind you of what is going on. When you are +finished, the @kbd{C-x )} command (@code{end-kbd-macro}) terminates the +definition (without becoming part of it!). For example, + +@example +C-x ( M-f foo C-x ) +@end example + +@noindent +defines a macro to move forward a word and then insert @samp{foo}. + + The macro thus defined can be invoked again with the @kbd{C-x e} +command (@code{call-last-kbd-macro}), which may be given a repeat count +as a numeric argument to execute the macro many times. @kbd{C-x )} can +also be given a repeat count as an argument, in which case it repeats +the macro that many times right after defining it, but defining the +macro counts as the first repetition (since it is executed as you define +it). Therefore, giving @kbd{C-x )} an argument of 4 executes the macro +immediately 3 additional times. An argument of zero to @kbd{C-x e} or +@kbd{C-x )} means repeat the macro indefinitely (until it gets an error +or you type @kbd{C-g} or, on MS-DOS, @kbd{C-@key{BREAK}}). + + If you wish to repeat an operation at regularly spaced places in the +text, define a macro and include as part of the macro the commands to move +to the next place you want to use it. For example, if you want to change +each line, you should position point at the start of a line, and define a +macro to change that line and leave point at the start of the next line. +Then repeating the macro will operate on successive lines. + + After you have terminated the definition of a keyboard macro, you can add +to the end of its definition by typing @kbd{C-u C-x (}. This is equivalent +to plain @kbd{C-x (} followed by retyping the whole definition so far. As +a consequence it re-executes the macro as previously defined. + + You can use function keys in a keyboard macro, just like keyboard +keys. You can even use mouse events, but be careful about that: when +the macro replays the mouse event, it uses the original mouse position +of that event, the position that the mouse had while you were defining +the macro. The effect of this may be hard to predict. (Using the +current mouse position would be even less predictable.) + + One thing that doesn't always work well in a keyboard macro is the +command @kbd{C-M-c} (@code{exit-recursive-edit}). When this command +exits a recursive edit that started within the macro, it works as you'd +expect. But if it exits a recursive edit that started before you +invoked the keyboard macro, it also necessarily exits the keyboard macro +as part of the process. + +@findex edit-kbd-macro +@kindex C-x C-k + You can edit a keyboard macro already defined by typing @kbd{C-x C-k} +(@code{edit-kbd-macro}). Follow that with the keyboard input that you +would use to invoke the macro---@kbd{C-x e} or @kbd{M-x @var{name}} or +some other key sequence. This formats the macro definition in a buffer +and enters a specialized major mode for editing it. Type @kbd{C-h m} +once in that buffer to display details of how to edit the macro. When +you are finished editing, type @kbd{C-c C-c}. + +@findex apply-macro-to-region-lines + The command @kbd{M-x apply-macro-to-region-lines} repeats the last +defined keyboard macro on each complete line within the current region. +It does this line by line, by moving point to the beginning of the line +and then executing the macro. + +@node Save Kbd Macro +@subsection Naming and Saving Keyboard Macros + +@cindex saving keyboard macros +@findex name-last-kbd-macro + If you wish to save a keyboard macro for longer than until you define the +next one, you must give it a name using @kbd{M-x name-last-kbd-macro}. +This reads a name as an argument using the minibuffer and defines that name +to execute the macro. The macro name is a Lisp symbol, and defining it in +this way makes it a valid command name for calling with @kbd{M-x} or for +binding a key to with @code{global-set-key} (@pxref{Keymaps}). If you +specify a name that has a prior definition other than another keyboard +macro, an error message is printed and nothing is changed. + +@findex insert-kbd-macro + Once a macro has a command name, you can save its definition in a file. +Then it can be used in another editing session. First, visit the file +you want to save the definition in. Then use this command: + +@example +M-x insert-kbd-macro @key{RET} @var{macroname} @key{RET} +@end example + +@noindent +This inserts some Lisp code that, when executed later, will define the +same macro with the same definition it has now. (You need not +understand Lisp code to do this, because @code{insert-kbd-macro} writes +the Lisp code for you.) Then save the file. You can load the file +later with @code{load-file} (@pxref{Lisp Libraries}). If the file you +save in is your init file @file{~/.emacs} (@pxref{Init File}) then the +macro will be defined each time you run Emacs. + + If you give @code{insert-kbd-macro} a numeric argument, it makes +additional Lisp code to record the keys (if any) that you have bound to the +keyboard macro, so that the macro will be reassigned the same keys when you +load the file. + +@node Kbd Macro Query +@subsection Executing Macros with Variations + +@kindex C-x q +@findex kbd-macro-query + Using @kbd{C-x q} (@code{kbd-macro-query}), you can get an effect +similar to that of @code{query-replace}, where the macro asks you each +time around whether to make a change. While defining the macro, +type @kbd{C-x q} at the point where you want the query to occur. During +macro definition, the @kbd{C-x q} does nothing, but when you run the +macro later, @kbd{C-x q} asks you interactively whether to continue. + + The valid responses when @kbd{C-x q} asks are @key{SPC} (or @kbd{y}), +@key{DEL} (or @kbd{n}), @key{RET} (or @kbd{q}), @kbd{C-l} and @kbd{C-r}. +The answers are the same as in @code{query-replace}, though not all of +the @code{query-replace} options are meaningful. + + These responses include @key{SPC} to continue, and @key{DEL} to skip +the remainder of this repetition of the macro and start right away with +the next repetition. @key{RET} means to skip the remainder of this +repetition and cancel further repetitions. @kbd{C-l} redraws the screen +and asks you again for a character to say what to do. + + @kbd{C-r} enters a recursive editing level, in which you can perform +editing which is not part of the macro. When you exit the recursive +edit using @kbd{C-M-c}, you are asked again how to continue with the +keyboard macro. If you type a @key{SPC} at this time, the rest of the +macro definition is executed. It is up to you to leave point and the +text in a state such that the rest of the macro will do what you +want.@refill + + @kbd{C-u C-x q}, which is @kbd{C-x q} with a numeric argument, +performs a completely different function. It enters a recursive edit +reading input from the keyboard, both when you type it during the +definition of the macro, and when it is executed from the macro. During +definition, the editing you do inside the recursive edit does not become +part of the macro. During macro execution, the recursive edit gives you +a chance to do some particularized editing on each repetition. +@xref{Recursive Edit}. + + Another way to vary the behavior of a keyboard macro is to use a +register as a counter, incrementing it on each repetition of the macro. +@xref{RegNumbers}. + +@node Key Bindings +@section Customizing Key Bindings +@cindex key bindings + + This section describes @dfn{key bindings}, which map keys to commands, +and @dfn{keymaps}, which record key bindings. It also explains how +to customize key bindings. + + Recall that a command is a Lisp function whose definition provides for +interactive use. Like every Lisp function, a command has a function +name which usually consists of lower-case letters and hyphens. + +@menu +* Keymaps:: Generalities. The global keymap. +* Prefix Keymaps:: Keymaps for prefix keys. +* Local Keymaps:: Major and minor modes have their own keymaps. +* Minibuffer Maps:: The minibuffer uses its own local keymaps. +* Rebinding:: How to redefine one key's meaning conveniently. +* Init Rebinding:: Rebinding keys with your init file, @file{.emacs}. +* Function Keys:: Rebinding terminal function keys. +* Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. +* Non-ASCII Rebinding:: Rebinding non-ASCII characters such as Latin-1. +* Mouse Buttons:: Rebinding mouse buttons in Emacs. +* Disabling:: Disabling a command means confirmation is required + before it can be executed. This is done to protect + beginners from surprises. +@end menu + +@node Keymaps +@subsection Keymaps +@cindex keymap + + The bindings between key sequences and command functions are recorded +in data structures called @dfn{keymaps}. Emacs has many of these, each +used on particular occasions. + + Recall that a @dfn{key sequence} (@dfn{key}, for short) is a sequence +of @dfn{input events} that have a meaning as a unit. Input events +include characters, function keys and mouse buttons---all the inputs +that you can send to the computer with your terminal. A key sequence +gets its meaning from its @dfn{binding}, which says what command it +runs. The function of keymaps is to record these bindings. + +@cindex global keymap + The @dfn{global} keymap is the most important keymap because it is +always in effect. The global keymap defines keys for Fundamental mode; +most of these definitions are common to most or all major modes. Each +major or minor mode can have its own keymap which overrides the global +definitions of some keys. + + For example, a self-inserting character such as @kbd{g} is +self-inserting because the global keymap binds it to the command +@code{self-insert-command}. The standard Emacs editing characters such +as @kbd{C-a} also get their standard meanings from the global keymap. +Commands to rebind keys, such as @kbd{M-x global-set-key}, actually work +by storing the new binding in the proper place in the global map. +@xref{Rebinding}. + + Meta characters work differently; Emacs translates each Meta +character into a pair of characters starting with @key{ESC}. When you +type the character @kbd{M-a} in a key sequence, Emacs replaces it with +@kbd{@key{ESC} a}. A meta key comes in as a single input event, but +becomes two events for purposes of key bindings. The reason for this is +historical, and we might change it someday. + +@cindex function key + Most modern keyboards have function keys as well as character keys. +Function keys send input events just as character keys do, and keymaps +can have bindings for them. + + On many terminals, typing a function key actually sends the computer a +sequence of characters; the precise details of the sequence depends on +which function key and on the model of terminal you are using. (Often +the sequence starts with @kbd{@key{ESC} [}.) If Emacs understands your +terminal type properly, it recognizes the character sequences forming +function keys wherever they occur in a key sequence (not just at the +beginning). Thus, for most purposes, you can pretend the function keys +reach Emacs directly and ignore their encoding as character sequences. + +@cindex mouse + Mouse buttons also produce input events. These events come with other +data---the window and position where you pressed or released the button, +and a time stamp. But only the choice of button matters for key +bindings; the other data matters only if a command looks at it. +(Commands designed for mouse invocation usually do look at the other +data.) + + A keymap records definitions for single events. Interpreting a key +sequence of multiple events involves a chain of keymaps. The first +keymap gives a definition for the first event; this definition is +another keymap, which is used to look up the second event in the +sequence, and so on. + + Key sequences can mix function keys and characters. For example, +@kbd{C-x @key{SELECT}} is meaningful. If you make @key{SELECT} a prefix +key, then @kbd{@key{SELECT} C-n} makes sense. You can even mix mouse +events with keyboard events, but we recommend against it, because such +sequences are inconvenient to type in. + + As a user, you can redefine any key; but it might be best to stick to +key sequences that consist of @kbd{C-c} followed by a letter. These +keys are ``reserved for users,'' so they won't conflict with any +properly designed Emacs extension. The function keys @key{F5} through +@key{F9} are also reserved for users. If you redefine some other key, +your definition may be overridden by certain extensions or major modes +which redefine the same key. + +@node Prefix Keymaps +@subsection Prefix Keymaps + + A prefix key such as @kbd{C-x} or @key{ESC} has its own keymap, +which holds the definition for the event that immediately follows +that prefix. + + The definition of a prefix key is usually the keymap to use for +looking up the following event. The definition can also be a Lisp +symbol whose function definition is the following keymap; the effect is +the same, but it provides a command name for the prefix key that can be +used as a description of what the prefix key is for. Thus, the binding +of @kbd{C-x} is the symbol @code{Ctl-X-Prefix}, whose function +definition is the keymap for @kbd{C-x} commands. The definitions of +@kbd{C-c}, @kbd{C-x}, @kbd{C-h} and @key{ESC} as prefix keys appear in +the global map, so these prefix keys are always available. + + Aside from ordinary prefix keys, there is a fictitious ``prefix key'' +which represents the menu bar; see @ref{Menu Bar,,,elisp, The Emacs Lisp +Reference Manual}, for special information about menu bar key bindings. +Mouse button events that invoke pop-up menus are also prefix keys; see +@ref{Menu Keymaps,,,elisp, The Emacs Lisp Reference Manual}, for more +details. + + Some prefix keymaps are stored in variables with names: + +@itemize @bullet +@item +@vindex ctl-x-map +@code{ctl-x-map} is the variable name for the map used for characters that +follow @kbd{C-x}. +@item +@vindex help-map +@code{help-map} is for characters that follow @kbd{C-h}. +@item +@vindex esc-map +@code{esc-map} is for characters that follow @key{ESC}. Thus, all Meta +characters are actually defined by this map. +@item +@vindex ctl-x-4-map +@code{ctl-x-4-map} is for characters that follow @kbd{C-x 4}. +@item +@vindex mode-specific-map +@code{mode-specific-map} is for characters that follow @kbd{C-c}. +@end itemize + +@node Local Keymaps +@subsection Local Keymaps + +@cindex local keymap + So far we have explained the ins and outs of the global map. Major +modes customize Emacs by providing their own key bindings in @dfn{local +keymaps}. For example, C mode overrides @key{TAB} to make it indent the +current line for C code. Portions of text in the buffer can specify +their own keymaps to substitute for the keymap of the buffer's major +mode. + +@cindex minor mode keymap + Minor modes can also have local keymaps. Whenever a minor mode is +in effect, the definitions in its keymap override both the major +mode's local keymap and the global keymap. + +@vindex c-mode-map +@vindex lisp-mode-map + The local keymaps for Lisp mode and several other major modes always +exist even when not in use. These are kept in variables named +@code{lisp-mode-map} and so on. For major modes less often used, the +local keymap is normally constructed only when the mode is used for the +first time in a session. This is to save space. If you wish to change +one of these keymaps, you must use the major mode's @dfn{mode +hook}---see below. + + All minor mode keymaps are created in advance. There is no way to +defer their creation until the first time the minor mode is enabled. + + A local keymap can locally redefine a key as a prefix key by defining +it as a prefix keymap. If the key is also defined globally as a prefix, +then its local and global definitions (both keymaps) effectively +combine: both of them are used to look up the event that follows the +prefix key. Thus, if the mode's local keymap defines @kbd{C-c} as +another keymap, and that keymap defines @kbd{C-z} as a command, this +provides a local meaning for @kbd{C-c C-z}. This does not affect other +sequences that start with @kbd{C-c}; if those sequences don't have their +own local bindings, their global bindings remain in effect. + + Another way to think of this is that Emacs handles a multi-event key +sequence by looking in several keymaps, one by one, for a binding of the +whole key sequence. First it checks the minor mode keymaps for minor +modes that are enabled, then it checks the major mode's keymap, and then +it checks the global keymap. This is not precisely how key lookup +works, but it's good enough for understanding ordinary circumstances. + +@cindex rebinding major mode keys + To change the local bindings of a major mode, you must change the +mode's local keymap. Normally you must wait until the first time the +mode is used, because most major modes don't create their keymaps until +then. If you want to specify something in your @file{~/.emacs} file to +change a major mode's bindings, you must use the mode's mode hook to +delay the change until the mode is first used. + + For example, the command @code{texinfo-mode} to select Texinfo mode +runs the hook @code{texinfo-mode-hook}. Here's how you can use the hook +to add local bindings (not very useful, we admit) for @kbd{C-c n} and +@kbd{C-c p} in Texinfo mode: + +@example +(add-hook 'texinfo-mode-hook + '(lambda () + (define-key texinfo-mode-map + "\C-cp" + 'backward-paragraph) + (define-key texinfo-mode-map + "\C-cn" + 'forward-paragraph) + )) +@end example + + @xref{Hooks}. + +@node Minibuffer Maps +@subsection Minibuffer Keymaps + +@cindex minibuffer keymaps +@vindex minibuffer-local-map +@vindex minibuffer-local-ns-map +@vindex minibuffer-local-completion-map +@vindex minibuffer-local-must-match-map + The minibuffer has its own set of local keymaps; they contain various +completion and exit commands. + +@itemize @bullet +@item +@code{minibuffer-local-map} is used for ordinary input (no completion). +@item +@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits +just like @key{RET}. This is used mainly for Mocklisp compatibility. +@item +@code{minibuffer-local-completion-map} is for permissive completion. +@item +@code{minibuffer-local-must-match-map} is for strict completion and +for cautious completion. +@end itemize + +@node Rebinding +@subsection Changing Key Bindings Interactively +@cindex key rebinding, this session +@cindex rebinding keys, this session + + The way to redefine an Emacs key is to change its entry in a keymap. +You can change the global keymap, in which case the change is effective in +all major modes (except those that have their own overriding local +definitions for the same key). Or you can change the current buffer's +local map, which affects all buffers using the same major mode. + +@findex global-set-key +@findex local-set-key +@findex global-unset-key +@findex local-unset-key +@table @kbd +@item M-x global-set-key @key{RET} @var{key} @var{cmd} @key{RET} +Define @var{key} globally to run @var{cmd}. +@item M-x local-set-key @key{RET} @var{key} @var{cmd} @key{RET} +Define @var{key} locally (in the major mode now in effect) to run +@var{cmd}. +@item M-x global-unset-key @key{RET} @var{key} +Make @var{key} undefined in the global map. +@item M-x local-unset-key @key{RET} @var{key} +Make @var{key} undefined locally (in the major mode now in effect). +@end table + + For example, suppose you like to execute commands in a subshell within +an Emacs buffer, instead of suspending Emacs and executing commands in +your login shell. Normally, @kbd{C-z} is bound to the function +@code{suspend-emacs} (when not using the X Window System), but you can +change @kbd{C-z} to invoke an interactive subshell within Emacs, by +binding it to @code{shell} as follows: + +@example +M-x global-set-key @key{RET} C-z shell @key{RET} +@end example + +@noindent +@code{global-set-key} reads the command name after the key. After you +press the key, a message like this appears so that you can confirm that +you are binding the key you want: + +@example +Set key C-z to command: +@end example + + You can redefine function keys and mouse events in the same way; just +type the function key or click the mouse when it's time to specify the +key to rebind. + + You can rebind a key that contains more than one event in the same +way. Emacs keeps reading the key to rebind until it is a complete key +(that is, not a prefix key). Thus, if you type @kbd{C-f} for +@var{key}, that's the end; the minibuffer is entered immediately to +read @var{cmd}. But if you type @kbd{C-x}, another character is read; +if that is @kbd{4}, another character is read, and so on. For +example, + +@example +M-x global-set-key @key{RET} C-x 4 $ spell-other-window @key{RET} +@end example + +@noindent +redefines @kbd{C-x 4 $} to run the (fictitious) command +@code{spell-other-window}. + + The two-character keys consisting of @kbd{C-c} followed by a letter +are reserved for user customizations. Lisp programs are not supposed to +define these keys, so the bindings you make for them will be available +in all major modes and will never get in the way of anything. + + You can remove the global definition of a key with +@code{global-unset-key}. This makes the key @dfn{undefined}; if you +type it, Emacs will just beep. Similarly, @code{local-unset-key} makes +a key undefined in the current major mode keymap, which makes the global +definition (or lack of one) come back into effect in that major mode. + + If you have redefined (or undefined) a key and you subsequently wish +to retract the change, undefining the key will not do the job---you need +to redefine the key with its standard definition. To find the name of +the standard definition of a key, go to a Fundamental mode buffer and +use @kbd{C-h c}. The documentation of keys in this manual also lists +their command names. + + If you want to prevent yourself from invoking a command by mistake, it +is better to disable the command than to undefine the key. A disabled +command is less work to invoke when you really want to. +@xref{Disabling}. + +@node Init Rebinding +@subsection Rebinding Keys in Your Init File + +@findex define-key +@findex substitute-key-definition + If you have a set of key bindings that you like to use all the time, +you can specify them in your @file{.emacs} file by using their Lisp +syntax. + + The simplest method for doing this works for ASCII characters and +Meta-modified ASCII characters only. This method uses a string to +represent the key sequence you want to rebind. For example, here's how +to bind @kbd{C-z} to @code{shell}: + +@example +(global-set-key "\C-z" 'shell) +@end example + +@noindent +This example uses a string constant containing one character, @kbd{C-z}. +The single-quote before the command name, @code{shell}, marks it as a +constant symbol rather than a variable. If you omit the quote, Emacs +would try to evaluate @code{shell} immediately as a variable. This +probably causes an error; it certainly isn't what you want. + + Here is another example that binds a key sequence two characters long: + +@example +(global-set-key "\C-xl" 'make-symbolic-link) +@end example + + When the key sequence includes function keys or mouse button events, +or non-ASCII characters such as @code{C-=} or @code{H-a}, you must use +the more general method of rebinding, which uses a vector to specify the +key sequence. + + The way to write a vector in Emacs Lisp is with square brackets around +the vector elements. Use spaces to separate the elements. If an +element is a symbol, simply write the symbol's name---no other +delimiters or punctuation are needed. If a vector element is a +character, write it as a Lisp character constant: @samp{?} followed by +the character as it would appear in a string. + + Here are examples of using vectors to rebind @kbd{C-=} (a control +character outside of ASCII), @kbd{H-a} (a Hyper character; ASCII doesn't +have Hyper at all), @key{F7} (a function key), and @kbd{C-Mouse-1} (a +keyboard-modified mouse button): + +@example +(global-set-key [?\C-=] 'make-symbolic-link) +(global-set-key [?\H-a] 'make-symbolic-link) +(global-set-key [f7] 'make-symbolic-link) +(global-set-key [C-mouse-1] 'make-symbolic-link) +@end example + + You can use a vector for the simple cases too. Here's how to rewrite +the first two examples, above, to use vectors: + +@example +(global-set-key [?\C-z] 'shell) + +(global-set-key [?\C-x ?l] 'make-symbolic-link) +@end example + +@node Function Keys +@subsection Rebinding Function Keys + + Key sequences can contain function keys as well as ordinary +characters. Just as Lisp characters (actually integers) represent +keyboard characters, Lisp symbols represent function keys. If the +function key has a word as its label, then that word is also the name of +the corresponding Lisp symbol. Here are the conventional Lisp names for +common function keys: + +@table @asis +@item @code{left}, @code{up}, @code{right}, @code{down} +Cursor arrow keys. + +@item @code{begin}, @code{end}, @code{home}, @code{next}, @code{prior} +Other cursor repositioning keys. + +@item @code{select}, @code{print}, @code{execute}, @code{backtab} +@itemx @code{insert}, @code{undo}, @code{redo}, @code{clearline} +@itemx @code{insertline}, @code{deleteline}, @code{insertchar}, @code{deletechar}, +Miscellaneous function keys. + +@item @code{f1}, @code{f2}, @dots{} @code{f35} +Numbered function keys (across the top of the keyboard). + +@item @code{kp-add}, @code{kp-subtract}, @code{kp-multiply}, @code{kp-divide} +@itemx @code{kp-backtab}, @code{kp-space}, @code{kp-tab}, @code{kp-enter} +@itemx @code{kp-separator}, @code{kp-decimal}, @code{kp-equal} +Keypad keys (to the right of the regular keyboard), with names or punctuation. + +@item @code{kp-0}, @code{kp-1}, @dots{} @code{kp-9} +Keypad keys with digits. + +@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4} +Keypad PF keys. +@end table + + These names are conventional, but some systems (especially when using +X windows) may use different names. To make certain what symbol is used +for a given function key on your terminal, type @kbd{C-h c} followed by +that key. + + A key sequence which contains function key symbols (or anything but +ASCII characters) must be a vector rather than a string. The vector +syntax uses spaces between the elements, and square brackets around the +whole vector. Thus, to bind function key @samp{f1} to the command +@code{rmail}, write the following: + +@example +(global-set-key [f1] 'rmail) +@end example + +@noindent +To bind the right-arrow key to the command @code{forward-char}, you can +use this expression: + +@example +(global-set-key [right] 'forward-char) +@end example + +@noindent +This uses the Lisp syntax for a vector containing the symbol +@code{right}. (This binding is present in Emacs by default.) + + @xref{Init Rebinding}, for more information about using vectors for +rebinding. + + You can mix function keys and characters in a key sequence. This +example binds @kbd{C-x @key{NEXT}} to the command @code{forward-page}. + +@example +(global-set-key [?\C-x next] 'forward-page) +@end example + +@noindent +where @code{?\C-x} is the Lisp character constant for the character +@kbd{C-x}. The vector element @code{next} is a symbol and therefore +does not take a question mark. + + You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER}, +@key{SUPER}, @key{ALT} and @key{SHIFT} with function keys. To represent +these modifiers, add the strings @samp{C-}, @samp{M-}, @samp{H-}, +@samp{s-}, @samp{A-} and @samp{S-} at the front of the symbol name. +Thus, here is how to make @kbd{Hyper-Meta-@key{RIGHT}} move forward a +word: + +@example +(global-set-key [H-M-right] 'forward-word) +@end example + +@node Named ASCII Chars +@subsection Named ASCII Control Characters + + @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL} +started out as names for certain ASCII control characters, used so often +that they have special keys of their own. Later, users found it +convenient to distinguish in Emacs between these keys and the ``same'' +control characters typed with the @key{CTRL} key. + + Emacs distinguishes these two kinds of input, when used with the X +Window System. It treats the ``special'' keys as function keys named +@code{tab}, @code{return}, @code{backspace}, @code{linefeed}, +@code{escape}, and @code{delete}. These function keys translate +automatically into the corresponding ASCII characters @emph{if} they +have no bindings of their own. As a result, neither users nor Lisp +programs need to pay attention to the distinction unless they care to. + + If you do not want to distinguish between (for example) @key{TAB} and +@kbd{C-i}, make just one binding, for the ASCII character @key{TAB} +(octal code 011). If you do want to distinguish, make one binding for +this ASCII character, and another for the ``function key'' @code{tab}. + + With an ordinary ASCII terminal, there is no way to distinguish +between @key{TAB} and @kbd{C-i} (and likewise for other such pairs), +because the terminal sends the same character in both cases. + +@node Non-ASCII Rebinding +@subsection Non-ASCII Characters on the Keyboard + +If your keyboard has keys that send non-ASCII characters, such as +accented letters, rebinding these keys is a bit tricky. There are +two solutions you can use. One is to specify a keyboard coding system, +using @code{set-keyboard-coding-system} (@pxref{Specify Coding}). +Then you can bind these keys in the usual way, but writing + +@example +(global-set-key [?@var{char}] 'some-function) +@end example + +@noindent +and typing the key you want to bind to insert @var{char}. + +If you don't specify the keyboard coding system, that approach won't +work. Instead, you need to find out the actual code that the terminal +sends. The easiest way to do this in Emacs is to create an empty buffer +with @kbd{C-x b temp @key{RET}}, make it unibyte with @kbd{M-x +toggle-enable-multibyte-characters @key{RET}}, then type the key to +insert the character into this buffer. + +Move point before the character, then type @kbd{C-x =}. This +displays a message in the minibuffer, showing the character code in +three ways, octal, decimal and hexadecimal, all within a set of +parentheses. Use the second of the three numbers, the decimal one, +inside the vector to bind: + +@example +(global-set-key [@var{decimal-code}] 'some-function) +@end example + +@node Mouse Buttons +@subsection Rebinding Mouse Buttons +@cindex mouse button events +@cindex rebinding mouse buttons +@cindex click events +@cindex drag events +@cindex down events +@cindex button down events + + Emacs uses Lisp symbols to designate mouse buttons, too. The ordinary +mouse events in Emacs are @dfn{click} events; these happen when you +press a button and release it without moving the mouse. You can also +get @dfn{drag} events, when you move the mouse while holding the button +down. Drag events happen when you finally let go of the button. + + The symbols for basic click events are @code{mouse-1} for the leftmost +button, @code{mouse-2} for the next, and so on. Here is how you can +redefine the second mouse button to split the current window: + +@example +(global-set-key [mouse-2] 'split-window-vertically) +@end example + + The symbols for drag events are similar, but have the prefix +@samp{drag-} before the word @samp{mouse}. For example, dragging the +first button generates a @code{drag-mouse-1} event. + + You can also define bindings for events that occur when a mouse button +is pressed down. These events start with @samp{down-} instead of +@samp{drag-}. Such events are generated only if they have key bindings. +When you get a button-down event, a corresponding click or drag event +will always follow. + +@cindex double clicks +@cindex triple clicks + If you wish, you can distinguish single, double, and triple clicks. A +double click means clicking a mouse button twice in approximately the +same place. The first click generates an ordinary click event. The +second click, if it comes soon enough, generates a double-click event +instead. The event type for a double-click event starts with +@samp{double-}: for example, @code{double-mouse-3}. + + This means that you can give a special meaning to the second click at +the same place, but it must act on the assumption that the ordinary +single click definition has run when the first click was received. + + This constrains what you can do with double clicks, but user interface +designers say that this constraint ought to be followed in any case. A +double click should do something similar to the single click, only +``more so.'' The command for the double-click event should perform the +extra work for the double click. + + If a double-click event has no binding, it changes to the +corresponding single-click event. Thus, if you don't define a +particular double click specially, it executes the single-click command +twice. + + Emacs also supports triple-click events whose names start with +@samp{triple-}. Emacs does not distinguish quadruple clicks as event +types; clicks beyond the third generate additional triple-click events. +However, the full number of clicks is recorded in the event list, so you +can distinguish if you really want to. We don't recommend distinct +meanings for more than three clicks, but sometimes it is useful for +subsequent clicks to cycle through the same set of three meanings, so +that four clicks are equivalent to one click, five are equivalent to +two, and six are equivalent to three. + + Emacs also records multiple presses in drag and button-down events. +For example, when you press a button twice, then move the mouse while +holding the button, Emacs gets a @samp{double-drag-} event. And at the +moment when you press it down for the second time, Emacs gets a +@samp{double-down-} event (which is ignored, like all button-down +events, if it has no binding). + +@vindex double-click-time + The variable @code{double-click-time} specifies how long may elapse +between clicks that are recognized as a pair. Its value is measured +in milliseconds. If the value is @code{nil}, double clicks are not +detected at all. If the value is @code{t}, then there is no time +limit. + + The symbols for mouse events also indicate the status of the modifier +keys, with the usual prefixes @samp{C-}, @samp{M-}, @samp{H-}, +@samp{s-}, @samp{A-} and @samp{S-}. These always precede @samp{double-} +or @samp{triple-}, which always precede @samp{drag-} or @samp{down-}. + + A frame includes areas that don't show text from the buffer, such as +the mode line and the scroll bar. You can tell whether a mouse button +comes from a special area of the screen by means of dummy ``prefix +keys.'' For example, if you click the mouse in the mode line, you get +the prefix key @code{mode-line} before the ordinary mouse-button symbol. +Thus, here is how to define the command for clicking the first button in +a mode line to run @code{scroll-up}: + +@example +(global-set-key [mode-line mouse-1] 'scroll-up) +@end example + + Here is the complete list of these dummy prefix keys and their +meanings: + +@table @code +@item mode-line +The mouse was in the mode line of a window. +@item vertical-line +The mouse was in the vertical line separating side-by-side windows. (If +you use scroll bars, they appear in place of these vertical lines.) +@item vertical-scroll-bar +The mouse was in a vertical scroll bar. (This is the only kind of +scroll bar Emacs currently supports.) +@ignore +@item horizontal-scroll-bar +The mouse was in a horizontal scroll bar. Horizontal scroll bars do +horizontal scrolling, and people don't use them often. +@end ignore +@end table + + You can put more than one mouse button in a key sequence, but it isn't +usual to do so. + +@node Disabling +@subsection Disabling Commands +@cindex disabled command + + Disabling a command marks the command as requiring confirmation before it +can be executed. The purpose of disabling a command is to prevent +beginning users from executing it by accident and being confused. + + An attempt to invoke a disabled command interactively in Emacs +displays a window containing the command's name, its documentation, and +some instructions on what to do immediately; then Emacs asks for input +saying whether to execute the command as requested, enable it and +execute it, or cancel. If you decide to enable the command, you are +asked whether to do this permanently or just for the current session. +Enabling permanently works by automatically editing your @file{.emacs} +file. + + The direct mechanism for disabling a command is to put a +non-@code{nil} @code{disabled} property on the Lisp symbol for the +command. Here is the Lisp program to do this: + +@example +(put 'delete-region 'disabled t) +@end example + + If the value of the @code{disabled} property is a string, that string +is included in the message printed when the command is used: + +@example +(put 'delete-region 'disabled + "It's better to use `kill-region' instead.\n") +@end example + +@findex disable-command +@findex enable-command + You can make a command disabled either by editing the @file{.emacs} +file directly or with the command @kbd{M-x disable-command}, which edits +the @file{.emacs} file for you. Likewise, @kbd{M-x enable-command} +edits @file{.emacs} to enable a command permanently. @xref{Init File}. + + Whether a command is disabled is independent of what key is used to +invoke it; disabling also applies if the command is invoked using +@kbd{M-x}. Disabling a command has no effect on calling it as a +function from Lisp programs. + +@node Keyboard Translations +@section Keyboard Translations + + Some keyboards do not make it convenient to send all the special +characters that Emacs uses. The most common problem case is the +@key{DEL} character. Some keyboards provide no convenient way to type +this very important character---usually because they were designed to +expect the character @kbd{C-h} to be used for deletion. On these +keyboards, if you press the key normally used for deletion, Emacs handles +the @kbd{C-h} as a prefix character and offers you a list of help +options, which is not what you want. + +@cindex keyboard translations +@findex keyboard-translate + You can work around this problem within Emacs by setting up keyboard +translations to turn @kbd{C-h} into @key{DEL} and @key{DEL} into +@kbd{C-h}, as follows: + +@example +;; @r{Translate @kbd{C-h} to @key{DEL}.} +(keyboard-translate ?\C-h ?\C-?) + +@need 3000 +;; @r{Translate @key{DEL} to @kbd{C-h}.} +(keyboard-translate ?\C-? ?\C-h) +@end example + + Keyboard translations are not the same as key bindings in keymaps +(@pxref{Keymaps}). Emacs contains numerous keymaps that apply in +different situations, but there is only one set of keyboard +translations, and it applies to every character that Emacs reads from +the terminal. Keyboard translations take place at the lowest level of +input processing; the keys that are looked up in keymaps contain the +characters that result from keyboard translation. + + Under X, the keyboard key named @key{DELETE} is a function key and is +distinct from the ASCII character named @key{DEL}. @xref{Named ASCII +Chars}. Keyboard translations affect only ASCII character input, not +function keys; thus, the above example used under X does not affect the +@key{DELETE} key. However, the translation above isn't necessary under +X, because Emacs can also distinguish between the @key{BACKSPACE} key +and @kbd{C-h}; and it normally treats @key{BACKSPACE} as @key{DEL}. + + For full information about how to use keyboard translations, see +@ref{Translating Input,,,elisp, The Emacs Lisp Reference Manual}. + +@node Syntax +@section The Syntax Table +@cindex syntax table + + All the Emacs commands which parse words or balance parentheses are +controlled by the @dfn{syntax table}. The syntax table says which +characters are opening delimiters, which are parts of words, which are +string quotes, and so on. Each major mode has its own syntax table +(though sometimes related major modes use the same one) which it +installs in each buffer that uses that major mode. The syntax table +installed in the current buffer is the one that all commands use, so we +call it ``the'' syntax table. A syntax table is a Lisp object, a +char-table, whose elements are numbers. + +@kindex C-h s +@findex describe-syntax + To display a description of the contents of the current syntax table, +type @kbd{C-h s} (@code{describe-syntax}). The description of each +character includes both the string you would have to give to +@code{modify-syntax-entry} to set up that character's current syntax, +and some English to explain that string if necessary. + + For full information on the syntax table, see @ref{Syntax Tables,, +Syntax Tables, elisp, The Emacs Lisp Reference Manual}. + +@node Init File +@section The Init File, @file{~/.emacs} +@cindex init file +@cindex Emacs initialization file +@cindex key rebinding, permanent +@cindex rebinding keys, permanently +@cindex startup (init file) + + When Emacs is started, it normally loads a Lisp program from the file +@file{.emacs} or @file{.emacs.el} in your home directory. We call this +file your @dfn{init file} because it specifies how to initialize Emacs +for you. You can use the command line switch @samp{-q} to prevent +loading your init file, and @samp{-u} (or @samp{--user}) to specify a +different user's init file (@pxref{Entering Emacs}). + + There can also be a @dfn{default init file}, which is the library +named @file{default.el}, found via the standard search path for +libraries. The Emacs distribution contains no such library; your site +may create one for local customizations. If this library exists, it is +loaded whenever you start Emacs (except when you specify @samp{-q}). +But your init file, if any, is loaded first; if it sets +@code{inhibit-default-init} non-@code{nil}, then @file{default} is not +loaded. + + Your site may also have a @dfn{site startup file}; this is named +@file{site-start.el}, if it exists. Emacs loads this library before it +loads your init file. To inhibit loading of this library, use the +option @samp{-no-site-file}. + + If you have a large amount of code in your @file{.emacs} file, you +should rename it to @file{~/.emacs.el}, and byte-compile it. @xref{Byte +Compilation,, Byte Compilation, elisp, the Emacs Lisp Reference Manual}, +for more information about compiling Emacs Lisp programs. + + If you are going to write actual Emacs Lisp programs that go beyond +minor customization, you should read the @cite{Emacs Lisp Reference Manual}. +@ifinfo +@xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference +Manual}. +@end ifinfo + +@menu +* Init Syntax:: Syntax of constants in Emacs Lisp. +* Init Examples:: How to do some things with an init file. +* Terminal Init:: Each terminal type can have an init file. +* Find Init:: How Emacs finds the init file. +@end menu + +@node Init Syntax +@subsection Init File Syntax + + The @file{.emacs} file contains one or more Lisp function call +expressions. Each of these consists of a function name followed by +arguments, all surrounded by parentheses. For example, @code{(setq +fill-column 60)} calls the function @code{setq} to set the variable +@code{fill-column} (@pxref{Filling}) to 60. + + The second argument to @code{setq} is an expression for the new value of +the variable. This can be a constant, a variable, or a function call +expression. In @file{.emacs}, constants are used most of the time. They can be: + +@table @asis +@item Numbers: +Numbers are written in decimal, with an optional initial minus sign. + +@item Strings: +@cindex Lisp string syntax +@cindex string syntax +Lisp string syntax is the same as C string syntax with a few extra +features. Use a double-quote character to begin and end a string constant. + +In a string, you can include newlines and special characters literally. +But often it is cleaner to use backslash sequences for them: @samp{\n} +for newline, @samp{\b} for backspace, @samp{\r} for carriage return, +@samp{\t} for tab, @samp{\f} for formfeed (control-L), @samp{\e} for +escape, @samp{\\} for a backslash, @samp{\"} for a double-quote, or +@samp{\@var{ooo}} for the character whose octal code is @var{ooo}. +Backslash and double-quote are the only characters for which backslash +sequences are mandatory. + +@samp{\C-} can be used as a prefix for a control character, as in +@samp{\C-s} for ASCII control-S, and @samp{\M-} can be used as a prefix for +a Meta character, as in @samp{\M-a} for @kbd{Meta-A} or @samp{\M-\C-a} for +@kbd{Control-Meta-A}.@refill + +@item Characters: +Lisp character constant syntax consists of a @samp{?} followed by +either a character or an escape sequence starting with @samp{\}. +Examples: @code{?x}, @code{?\n}, @code{?\"}, @code{?\)}. Note that +strings and characters are not interchangeable in Lisp; some contexts +require one and some contexts require the other. + +@item True: +@code{t} stands for `true'. + +@item False: +@code{nil} stands for `false'. + +@item Other Lisp objects: +Write a single-quote (') followed by the Lisp object you want. +@end table + +@node Init Examples +@subsection Init File Examples + + Here are some examples of doing certain commonly desired things with +Lisp expressions: + +@itemize @bullet +@item +Make @key{TAB} in C mode just insert a tab if point is in the middle of a +line. + +@example +(setq c-tab-always-indent nil) +@end example + +Here we have a variable whose value is normally @code{t} for `true' +and the alternative is @code{nil} for `false'. + +@item +Make searches case sensitive by default (in all buffers that do not +override this). + +@example +(setq-default case-fold-search nil) +@end example + +This sets the default value, which is effective in all buffers that do +not have local values for the variable. Setting @code{case-fold-search} +with @code{setq} affects only the current buffer's local value, which +is not what you probably want to do in an init file. + +@item +@vindex user-mail-address +Specify your own email address, if Emacs can't figure it out correctly. + +@example +(setq user-mail-address "coon@@yoyodyne.com") +@end example + +Various Emacs packages that need your own email address use the value of +@code{user-mail-address}. + +@item +Make Text mode the default mode for new buffers. + +@example +(setq default-major-mode 'text-mode) +@end example + +Note that @code{text-mode} is used because it is the command for +entering Text mode. The single-quote before it makes the symbol a +constant; otherwise, @code{text-mode} would be treated as a variable +name. + +@need 1500 +@item +Set up defaults for the Latin-1 character set +which supports most of the languages of Western Europe. + +@example +(set-language-environment "Latin-1") +@end example + +@need 1500 +@item +Turn on Auto Fill mode automatically in Text mode and related modes. + +@example +(add-hook 'text-mode-hook + '(lambda () (auto-fill-mode 1))) +@end example + +This shows how to add a hook function to a normal hook variable +(@pxref{Hooks}). The function we supply is a list starting with +@code{lambda}, with a single-quote in front of it to make it a list +constant rather than an expression. + +It's beyond the scope of this manual to explain Lisp functions, but for +this example it is enough to know that the effect is to execute +@code{(auto-fill-mode 1)} when Text mode is entered. You can replace +that with any other expression that you like, or with several +expressions in a row. + +Emacs comes with a function named @code{turn-on-auto-fill} whose +definition is @code{(lambda () (auto-fill-mode 1))}. Thus, a simpler +way to write the above example is as follows: + +@example +(add-hook 'text-mode-hook 'turn-on-auto-fill) +@end example + +@item +Load the installed Lisp library named @file{foo} (actually a file +@file{foo.elc} or @file{foo.el} in a standard Emacs directory). + +@example +(load "foo") +@end example + +When the argument to @code{load} is a relative file name, not starting +with @samp{/} or @samp{~}, @code{load} searches the directories in +@code{load-path} (@pxref{Lisp Libraries}). + +@item +Load the compiled Lisp file @file{foo.elc} from your home directory. + +@example +(load "~/foo.elc") +@end example + +Here an absolute file name is used, so no searching is done. + +@item +Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link}. + +@example +(global-set-key "\C-xl" 'make-symbolic-link) +@end example + +or + +@example +(define-key global-map "\C-xl" 'make-symbolic-link) +@end example + +Note once again the single-quote used to refer to the symbol +@code{make-symbolic-link} instead of its value as a variable. + +@item +Do the same thing for Lisp mode only. + +@example +(define-key lisp-mode-map "\C-xl" 'make-symbolic-link) +@end example + +@item +Redefine all keys which now run @code{next-line} in Fundamental mode +so that they run @code{forward-line} instead. + +@example +(substitute-key-definition 'next-line 'forward-line + global-map) +@end example + +@item +Make @kbd{C-x C-v} undefined. + +@example +(global-unset-key "\C-x\C-v") +@end example + +One reason to undefine a key is so that you can make it a prefix. +Simply defining @kbd{C-x C-v @var{anything}} will make @kbd{C-x C-v} a +prefix, but @kbd{C-x C-v} must first be freed of its usual non-prefix +definition. + +@item +Make @samp{$} have the syntax of punctuation in Text mode. +Note the use of a character constant for @samp{$}. + +@example +(modify-syntax-entry ?\$ "." text-mode-syntax-table) +@end example + +@item +Enable the use of the command @code{narrow-to-region} without confirmation. + +@example +(put 'narrow-to-region 'disabled nil) +@end example +@end itemize + +@node Terminal Init +@subsection Terminal-specific Initialization + + Each terminal type can have a Lisp library to be loaded into Emacs when +it is run on that type of terminal. For a terminal type named +@var{termtype}, the library is called @file{term/@var{termtype}} and it is +found by searching the directories @code{load-path} as usual and trying the +suffixes @samp{.elc} and @samp{.el}. Normally it appears in the +subdirectory @file{term} of the directory where most Emacs libraries are +kept.@refill + + The usual purpose of the terminal-specific library is to map the +escape sequences used by the terminal's function keys onto more +meaningful names, using @code{function-key-map}. See the file +@file{term/lk201.el} for an example of how this is done. Many function +keys are mapped automatically according to the information in the +Termcap data base; the terminal-specific library needs to map only the +function keys that Termcap does not specify. + + When the terminal type contains a hyphen, only the part of the name +before the first hyphen is significant in choosing the library name. +Thus, terminal types @samp{aaa-48} and @samp{aaa-30-rv} both use +the library @file{term/aaa}. The code in the library can use +@code{(getenv "TERM")} to find the full terminal type name.@refill + +@vindex term-file-prefix + The library's name is constructed by concatenating the value of the +variable @code{term-file-prefix} and the terminal type. Your @file{.emacs} +file can prevent the loading of the terminal-specific library by setting +@code{term-file-prefix} to @code{nil}. + +@vindex term-setup-hook + Emacs runs the hook @code{term-setup-hook} at the end of +initialization, after both your @file{.emacs} file and any +terminal-specific library have been read in. Add hook functions to this +hook if you wish to override part of any of the terminal-specific +libraries and to define initializations for terminals that do not have a +library. @xref{Hooks}. + +@node Find Init +@subsection How Emacs Finds Your Init File + + Normally Emacs uses the environment variable @code{HOME} to find +@file{.emacs}; that's what @samp{~} means in a file name. But if you +have done @code{su}, Emacs tries to find your own @file{.emacs}, not +that of the user you are currently pretending to be. The idea is +that you should get your own editor customizations even if you are +running as the super user. + + More precisely, Emacs first determines which user's init file to use. +It gets the user name from the environment variables @code{LOGNAME} and +@code{USER}; if neither of those exists, it uses effective user-ID. +If that user name matches the real user-ID, then Emacs uses @code{HOME}; +otherwise, it looks up the home directory corresponding to that user +name in the system's data base of users. +@c LocalWords: backtab diff --git a/man/dired-x.texi b/man/dired-x.texi new file mode 100644 index 00000000000..9402b12a6b5 --- /dev/null +++ b/man/dired-x.texi @@ -0,0 +1,1375 @@ +\input texinfo @comment -*-texinfo-*- + +@c dired-x.texi --- Sebastian Kremer's Extra DIRED hacked up for GNU Emacs19 +@c +@c Author: Sebastian Kremer <sk@thp.uni-koeln.de> +@c Lawrence R. Dodd <dodd@roebling.poly.edu> +@c Maintainer: Lawrence R. Dodd <dodd@roebling.poly.edu> +@c Version: 2.52 +@c Date: 1994/08/09 16:51:31 +@c Keywords: dired extensions +@c dired-x.el REVISION NUMBER: 2 + +@c State: Released +@c Ident: dired-x.texi,v 2.52 1994/08/09 16:51:31 dodd Released + +@comment %**start of header (This is for running Texinfo on a region.) +@c FOR GNU EMACS USE ../info/dired-x BELOW +@setfilename ../info/dired-x +@c dired-x.el REVISION NUMBER +@settitle Dired Extra Version 2 User's Manual + +@dircategory Editors +@direntry +* Dired-X: (dired-x). Dired Extra Features. +@end direntry + +@iftex +@finalout +@end iftex +@c @setchapternewpage odd % For book style double sided manual. +@comment %**end of header (This is for running Texinfo on a region.) +@c @smallbook +@tex +\overfullrule=0pt +%\global\baselineskip 30pt % For printing in double spaces +@end tex + +@ifinfo +@node Copyright, Top, (dir), (dir) +@comment node-name, next, previous, up +This documents the ``extra'' features for Dired Mode for GNU Emacs 19 found in +the file @file{dired-x.el}. + +Copyright @copyright{} 1993, 1994 Free Software Foundation, Inc. + +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. + +Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of +a permission notice identical to this one. + +Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for +modified versions, except that this permission notice may be stated +in a translation approved by the Free Software Foundation. + +The file used to create this is called @file{dired-x.texi}, but the +original work that was altered to make that file was called +@file{dired.texi} written by Sebastian Kremer. + +@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 +@c dired-x.el REVISION NUMBER +@center @titlefont{Dired Extra Version 2} +@sp 2 +@center @titlefont{For The GNU Emacs 19} +@sp 1 +@center @titlefont{Directory Editor} +@sp 4 +@center Manual Revision: 2.52 +@center 1994/08/09 16:51:31 +@sp 5 +@center Lawrence R@. Dodd +@center @t{dodd@@roebling.poly.edu} +@sp 5 +@center (Based on @file{dired.texi} by Sebastian Kremer <sk@@thp.uni-koeln.de>) +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1993, 1994 Free Software Foundation + +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. + +Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of +a permission notice identical to this one. + +Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for +modified versions, except that this permission notice may be stated +in a translation approved by the Free Software Foundation. + +The file used to create this is called @file{dired-x.texi}, but the +original work that was altered to make that file was called +@file{dired.texi} written by Sebastian Kremer. + +@end titlepage + +@page + +@ifinfo + +@node Top, Introduction, Copyright, (dir) +@comment node-name, next, previous, up + +@noindent +This documents the ``extra'' features for Dired Mode for GNU Emacs 19 that are +provided by the file @file{dired-x.el}. + +@itemize @bullet + +@item +Based on @file{dired.texi} by Sebastian Kremer <sk@@thp.uni-koeln.de> + +@c dired-x.el REVISION NUMBER +@item +For @file{dired-x.el} revision 2 + +@item +Revision of this manual: 2.52 (1994/08/09 16:51:31) + +@item +Bugs to Lawrence R. Dodd <dodd@@roebling.poly.edu>. @emph{Please} type +@kbd{M-x dired-x-submit-report} to submit a bug report (@xref{Bugs}). + +@item +You can obtain a copy of this package via anonymous ftp in +@t{/roebling.poly.edu:/pub/packages/dired-x.tar.gz} + +@end itemize + +@menu +* Introduction:: +* Installation:: +* Omitting Files in Dired:: +* Local Variables:: +* Shell Command Guessing:: +* Virtual Dired:: +* Advanced Mark Commands:: +* Multiple Dired Directories:: +* Find File At Point:: +* Miscellaneous Commands:: +* Bugs:: + +* Concept Index:: +* Command Index:: +* Key Index:: +* Variable Index:: + +@end menu + +@end ifinfo + +@node Introduction, Features, Top, Top +@comment node-name, next, previous, up +@chapter Introduction + +This documents the @emph{extra} features for Dired Mode for GNU Emacs 19. It +is derived from version 1.191 of Sebastian Kremer's @file{dired-x.el} and is +GNU Emacs v19 compatible. + +In adopting this @file{dired-x.el} to GNU Emacs v19 some material that has +been incorporated into @file{dired.el} and @file{dired-aux.el} of the GNU Emacs +19 distribution has been removed and some material was modified for agreement +with the functions in @file{dired.el} and @file{dired-aux.el}. For example, +the code using @code{gmhist} history functions was replaced with code using +the mini-buffer history now built into GNU Emacs 19. Finally, a few other +features have been added and a few more functions have been bound to keys. + +Please note that @file{dired-x.el} and this texinfo file @file{dired-x.texi} +are bundled with GNU Emacs versions 19.23 and later. + +@ifinfo +@menu +* Features:: +* Technical Details:: +@end menu +@end ifinfo + +@node Features, Technical Details, Introduction, Introduction +@comment node-name, next, previous, up +@section Features +@cindex Features + +Some features provided by Dired Extra + +@enumerate +@item +Omitting of uninteresting files from dired listing. +@itemize @bullet +@xref{Omitting Files in Dired} +@end itemize +@item +Local variables for dired directories. +@itemize @bullet +@xref{Local Variables} +@end itemize +@item +Guessing shell commands in dired buffers. +@itemize @bullet +@xref{Shell Command Guessing} +@end itemize +@item +Running dired command in non-dired buffers. +@itemize @bullet +@xref{Virtual Dired} +@end itemize +@item +Finding a file mentioned in a buffer +@itemize @bullet +@xref{Find File At Point} +@end itemize +@item +Commands using file marking. +@itemize @bullet +@xref{Advanced Mark Commands} +@end itemize +@end enumerate + +@noindent +@file{dired-x.el} binds some functions to keys in Dired Mode (@xref{Key +Index}) and also binds @kbd{C-x C-j} and @kbd{C-x 4 C-j} @emph{globally} to +@code{dired-jump} (@xref{Miscellaneous Commands}). It may also bind @kbd{C-x +C-f} and @kbd{C-x 4 C-f} to @code{dired-x-find-file} and +@code{dired-x-find-file-other-window}, respectively (@xref{Find File At +Point}). + +@node Technical Details, Installation, Features, Introduction +@comment node-name, next, previous, up +@section Technical Details +@cindex Redefined functions +@cindex @file{dired-aux.el} + +When loaded this code @emph{redefines} the following functions of GNU Emacs +from @file{dired.el} + +@itemize @bullet +@item +@code{dired-clean-up-after-deletion} +@item +@code{dired-find-buffer-nocreate} +@item +@code{dired-initial-position} +@item +@code{dired-up-directory} +@end itemize + +@noindent +and the following functions from @file{dired-aux.el} + +@itemize @bullet +@item +@code{dired-add-entry} +@item +@code{dired-read-shell-command} +@end itemize + +One drawback is that @file{dired-x.el} will load @file{dired-aux.el} as soon +as dired is loaded. Thus, the advantage of separating out non-essential dired +stuff into @file{dired-aux.el} and only loading when necessary will be lost +when @file{dired-x.el} is used. + +@node Installation, Optional Installation Dired Jump, Technical Details, Top +@comment node-name, next, previous, up +@chapter Installation + +@noindent +This manual describes the dired features provided by the file +@file{dired-x.el}. To take advantage of these features, you must load the +file and (optionally) set some variables. + +@noindent +In your @file{.emacs} file in your home directory, or in the system-wide +initialization file @file{default.el} in the @file{site-lisp} directory, put + +@example +(add-hook 'dired-load-hook + (function (lambda () + (load "dired-x") + ;; Set dired-x global variables here. For example: + ;; (setq dired-guess-shell-gnutar "gtar") + ;; (setq dired-x-hands-off-my-keys nil) + ))) +(add-hook 'dired-mode-hook + (function (lambda () + ;; Set dired-x buffer-local variables here. For example: + ;; (setq dired-omit-files-p t) + ))) +@end example + +@noindent +This will load @file{dired-x.el} when dired is first invoked (for example, +when you first do @kbd{C-x d}). + +@ifinfo +@menu +* Optional Installation Dired Jump:: +* Optional Installation File At Point:: +* Special Notes:: +@end menu +@end ifinfo + +@node Optional Installation Dired Jump, Optional Installation File At Point, Installation, Installation +@comment node-name, next, previous, up +@section Optional Installation Dired Jump + +@cindex Autoloading @code{dired-jump} and @code{dired-jump-other-window} + +In order to have @code{dired-jump} and @code{dired-jump-other-window} +(@xref{Miscellaneous Commands}) work @emph{before} @code{dired} and +@code{dired-x} have been properly loaded the user should set-up an autoload +for these functions. In your @file{.emacs} file put + +@example +;;; Autoload `dired-jump' and `dired-jump-other-window'. +;;; We autoload from FILE dired.el. This will then load dired-x.el +;;; and hence define `dired-jump' and `dired-jump-other-window'. +(define-key global-map "\C-x\C-j" 'dired-jump) +(define-key global-map "\C-x4\C-j" 'dired-jump-other-window) + +(autoload (quote dired-jump) "dired" "\ +Jump to dired buffer corresponding to current buffer. +If in a file, dired the current directory and move to file's line. +If in dired already, pop up a level and goto old directory's line. +In case the proper dired file line cannot be found, refresh the dired +buffer and try again." t nil) + +(autoload (quote dired-jump-other-window) "dired" "\ +Like \\[dired-jump] (dired-jump) but in other window." t nil) +@end example + +Note that in recent releases of GNU Emacs 19 (i.e., 19.25 or later) the file +@file{../lisp/loaddefs.el} of the Emacs distribution already contains the +proper auto-loading for @code{dired-jump} so you need only put + +@example +(define-key global-map "\C-x\C-j" 'dired-jump) +@end example + +@noindent in your @file{.emacs} file in order to have @kbd{C-x C-j} work +before @code{dired} is loaded. + +@node Optional Installation File At Point, Special Notes, Optional Installation Dired Jump, Installation +@comment node-name, next, previous, up +@section Optional Installation File At Point + +@cindex Binding @code{dired-x-find-file} +If you choose to have @file{dired-x.el} bind @code{dired-x-find-file} over +@code{find-file} (@xref{Find File At Point}), then you will need to set +@code{dired-x-hands-off-my-keys} and make a call to the function +@code{dired-x-bind-find-file} in the @code{dired-load-hook}: + +@example +(add-hook 'dired-load-hook + (function (lambda () + (load "dired-x") + ;; Bind dired-x-find-file. + (setq dired-x-hands-off-my-keys nil) + ;; Make sure our binding preference is invoked. + (dired-x-bind-find-file) + ))) +@end example + +Alternatively, you can set the variable @emph{before} @file{dired-x.el} is +loaded + +@example +(add-hook 'dired-load-hook + (function (lambda () + ;; Bind dired-x-find-file. + (setq dired-x-hands-off-my-keys nil) + (load "dired-x") + ))) +@end example + +@node Special Notes, Omitting Files in Dired, Optional Installation File At Point, Installation +@comment node-name, next, previous, up +@section Special Notes + +If @file{dired-x.el} was @emph{not} bundled with the version of GNU Emacs +installed at your site (i.e., not in the default @file{../lisp} directory) +then you must put the file @file{dired-x.el} in a directory known to GNU +Emacs. Examine the variable @code{load-path} for a list of these directories. +If you wish to add a new directory on this list of directories use something +like this in your @file{.emacs} file + +@example +;;; LOAD PATH +(setq load-path (append + load-path ; default at top + (list + "/the/directory/where/you/put/dired-x"))) +@end example + +@noindent If you wish to put the new directory at the head of the list (where +it will be found first) then you should use instead + +@example +;;; LOAD PATH +(setq load-path (append + (list + "/the/directory/where/you/put/dired-x") + load-path)) ; default at bottom +@end example + +You must also byte compile the file (for example, hitting @kbd{B} in +@code{dired-mode}). When byte-compiling @file{dired-x.el} you may get +messages about functions @code{vm-visit-folder}, @code{Man-notify-when-ready}, +and @code{reporter-submit-bug-report} not being defined. These are warnings +and should be ignored. + +@noindent CAUTION: If you are using a version of GNU Emacs earlier than 19.20 +than you may have to edit @file{dired.el}. The copy of @file{dired.el} in GNU +Emacs versions earlier than 19.20 incorrectly had the call to @code{run-hooks} +@emph{before} the call to @code{provide}. In such a case, it is possible that +byte-compiling and/or loading dired can cause an infinite loop. To prevent +this, make sure the line of code + +@example + (run-hooks 'dired-load-hook) +@end example + +@noindent is the @emph{last} executable line in the file @file{dired.el}. +That is, make sure it comes @emph{after} the line + +@example + (provide 'dired) +@end example + +@node Omitting Files in Dired, Omitting Variables, Special Notes, Top +@comment node-name, next, previous, up +@chapter Omitting Files in Dired + +@cindex Omitting Files in Dired +@dfn{Omitting} a file means removing it from the directory listing. Omitting +is useful for keeping Dired buffers free of ``uninteresting'' files (for +instance, auto-save, auxiliary, backup, and revision control files) so that +the user can concentrate on the interesting files. Like hidden files, omitted +files are never seen by Dired. Omitting differs from hiding in several +respects: + +@itemize @bullet + +@item +Omitting works on individual files, not on directories; an entire directory +cannot be omitted (though each of its files could be). + +@item +Omitting is wholesale; if omitting is turned on for a dired buffer, then all +uninteresting files listed in that buffer are omitted. The user does not omit +(or unomit) files one at a time. + +@item +Omitting can be automatic; uninteresting file lines in the buffer can be +removed before the user ever sees them. + +@item +Marked files are never omitted. +@end itemize + +@table @kbd +@item M-o +@kindex M-o +@findex dired-omit-toggle +(@code{dired-omit-toggle}) Toggle between displaying and omitting +``uninteresting'' files. With a prefix argument, don't toggle and just mark +the files, but don't actually omit them. +@end table + +@noindent +In order to make Dired Omit work you first need to load @file{dired-x.el} +inside @code{dired-load-hook} (@xref{Installation}) and then set +@code{dired-omit-files-p} in some way (@xref{Omitting Variables}). + +@ifinfo +@menu +* Omitting Variables:: +* Omitting Examples:: +* Omitting Technical:: +@end menu +@end ifinfo + +@node Omitting Variables, Omitting Examples, Omitting Files in Dired, Omitting Files in Dired +@comment node-name, next, previous, up + +@section Omitting Variables + +The following variables can be used to customize omitting. + +@table @code + +@vindex dired-omit-files-p +@item dired-omit-files-p + +Default: @code{nil} + +@cindex How to make omitting the default in Dired +If non-@code{nil}, ``uninteresting'' files are not listed. Uninteresting +files are those whose filenames match regexp @code{dired-omit-files}, plus +those ending with extensions in @code{dired-omit-extensions}. @kbd{M-o} +(@code{dired-omit-toggle}) toggles its value, which is buffer-local. Put + +@example +(setq dired-omit-files-p t) +@end example + +inside your @code{dired-mode-hook} to have omitting initially turned on in +@emph{every} Dired buffer (@xref{Installation}). You can then use @kbd{M-o} to +unomit in that buffer. + +To enable omitting automatically only in certain directories one can use Dired +Local Variables and put + +@example +Local Variables: +dired-omit-files-p: t +End: +@end example + +@noindent +into a file @file{.dired} (the default value of +@code{dired-local-variables-file}) in that directory (@xref{Local Variables}). + +@table @code +@findex dired-omit-here-always +@item dired-omit-here-always + +This is an interactive function that creates a local variables file exactly +like the example above (if it does not already exist) in the file +@code{dired-local-variables-file} in the current directory and then refreshes +the directory listing (@xref{Local Variables}). +@end table + +@vindex dired-omit-files +@item dired-omit-files + +Default: @code{"^#\\|\\.$"} + +Filenames matching this buffer-local regexp will not be displayed. +This only has effect when @code{dired-omit-files-p} is t. + +The default value omits the special directories @file{.} and @file{..} and +autosave files (plus other files ending in ``.'') (@xref{Omitting Examples}). + +@vindex dired-omit-extensions +@item dired-omit-extensions + +Default: The elements of @code{completion-ignored-extensions} (as defined in +the file @file{loaddefs.el} of the GNU Emacs distribution), +@code{dired-latex-unclean-extensions}, @code{dired-bibtex-unclean-extensions} +and @code{dired-texinfo-unclean-extensions}. + +If non-@code{nil}, a list of extensions (strings) to omit from Dired listings. +Its format is the same as that of @code{completion-ignored-extensions}. + +@vindex dired-omit-localp +@item dired-omit-localp + +Default: @code{'no-dir} + +The @var{localp} argument @code{dired-omit-expunge} passes to +@code{dired-get-filename}. If it is @code{'no-dir}, omitting is much faster, +but you can only match against the non-directory part of the filename. Set it +to @code{nil} if you need to match the whole pathname or @code{t} to match the +pathname relative to the buffer's top-level directory. + +@item dired-omit-marker-char +@vindex dired-omit-marker-char +@cindex Omitting additional files +Default: @kbd{C-o} + +Temporary marker used by by Dired to implement omitting. Should never be used +as marker by the user or other packages. There is one exception to this rule: +by doing + +@example +(setq dired-mark-keys "\C-o") +;; i.e., the value of dired-omit-marker-char +;; (which is not defined yet) +@end example + +anywhere in your @file{~/.emacs}, you will bind the @kbd{C-o} key to insert a +@kbd{C-o} marker, thus causing these files to be omitted in addition to the +usually omitted files. Unfortunately the files you omitted manually this way +will show up again after reverting the buffer, unlike the others. + +@end table + +@node Omitting Examples, Omitting Technical, Omitting Variables, Omitting Files in Dired +@comment node-name, next, previous, up +@section Examples of Omitting Various File Types + +@itemize @bullet + +@item +@cindex RCS files, how to omit them in Dired +@cindex Omitting RCS files in Dired +If you wish to avoid seeing RCS files and the RCS directory, then put + +@example +(setq dired-omit-files + (concat dired-omit-files "\\|^RCS$\\|,v$")) +@end example +@noindent +in the @code{dired-load-hook} (@xref{Installation}). This assumes +@code{dired-omit-localp} has its default value of @code{'no-dir} to make the +@code{^}-anchored matches work. As a slower alternative, with +@code{dired-omit-localp} set to @code{nil}, you can use @code{/} instead of +@code{^} in the regexp. + +@item +@cindex Tib files, how to omit them in Dired +@cindex Omitting tib files in Dired +If you use tib, the bibliography program for use with @TeX{} and La@TeX{}, you +might want to omit the @file{INDEX} and the @file{-t.tex} files, then put + +@example +(setq dired-omit-files + (concat dired-omit-files "\\|^INDEX$\\|-t\\.tex$")) +@end example + +@noindent +in the @code{dired-load-hook} (@xref{Installation}). + +@item +@cindex Dot files, how to omit them in Dired +@cindex Omitting dot files in Dired +If you do not wish to see @samp{dot} files (files starting with a @samp{.}), +then put + +@example +(setq dired-omit-files + (concat dired-omit-files "\\|^\\..+$")) +@end example + +@noindent +in the @code{dired-load-hook} (@xref{Installation}). + +@end itemize + +@node Omitting Technical, Local Variables, Omitting Examples, Omitting Files in Dired +@comment node-name, next, previous, up +@section Some Technical Details of Omitting + +Loading @file{dired-x.el} will install Dired Omit by putting +@code{dired-omit-expunge} on your @code{dired-after-readin-hook}, and will +call @code{dired-extra-startup}, which in turn calls @code{dired-omit-startup} +in your @code{dired-mode-hook}. + +@node Local Variables, Shell Command Guessing, Omitting Technical, Top +@comment node-name, next, previous, up +@chapter Local Variables for Dired Directories + +@cindex Local Variables for Dired Directories +@vindex dired-local-variables-file +@vindex dired-enable-local-variables +@noindent +When Dired visits a directory, it looks for a file whose name is the value of +variable @code{dired-local-variables-file} (default: @file{.dired}). If such +a file is found, Dired will temporarily insert it into the Dired buffer and +run @code{hack-local-variables}. + +@noindent +For example, if the user puts + +@example +Local Variables: +dired-actual-switches: "-lat" +dired-omit-files-p: t +End: +@end example + +@noindent +into a file called @file{.dired} in a directory then when that directory is +viewed it will be + +@enumerate +@item +sorted by date +@item +omitted automatically +@end enumerate + +@noindent +You can set @code{dired-local-variables-file} to @code{nil} to suppress this. +The value of @code{dired-enable-local-variables} controls if and how these +local variables are read. This variable exists so that if may override the +default value of @code{enable-local-variables}. + +@noindent +Please see the GNU Emacs Manual to learn more about local variables. +@xref{File Variables,Local Variables in Files,Local Variables in +Files,emacs,The GNU Emacs Manual}. + +@noindent +The following variables affect Dired Local Variables + +@table @code +@vindex dired-local-variables-file +@item dired-local-variables-file +Default: @code{".dired"} + +If non-@code{nil}, filename for local variables for Dired. If Dired finds a +file with that name in the current directory, it will temporarily insert it +into the dired buffer and run `hack-local-variables'. + +@vindex dired-enable-local-variables +@item dired-enable-local-variables +Default: @code{t} + +Controls use of local-variables lists in dired. The value can be @code{t}, +@code{nil}, or something else. A value of @code{t} means local-variables +lists are obeyed in the @code{dired-local-variables-file}; @code{nil} means +they are ignored; anything else means query. This variable temporarily +overrides the value of @code{enable-local-variables} when the Dired Local +Variables are hacked. +@end table + +@node Shell Command Guessing, Virtual Dired, Local Variables, Top +@comment node-name, next, previous, up +@chapter Shell Command Guessing +@cindex Guessing shell commands for files. + +Based upon the name of a filename, Dired tries to guess what shell +command you might want to apply to it. For example, if you have point +on a file named @file{foo.tar} and you press @kbd{!}, Dired will guess +you want to @samp{tar xvf} it and suggest that as the default shell +command. + +The default will be mentioned in brackets and you can type @kbd{M-p} to get +the default into the minibuffer so that you can edit it, e.g., changing +@samp{tar xvf} to @samp{tar tvf}. If there are several commands for a given +file, e.g., @samp{xtex} and @samp{dvips} for a @file{.dvi} file, you can type +@kbd{M-p} several times to see each of the matching commands. + +Dired only tries to guess a command for a single file, never for a list +of marked files. + +@table @code +@item dired-guess-shell-alist-default +@vindex dired-guess-shell-alist-default +Predefined rules for shell commands. Set this to @code{nil} to turn guessing off. +The elements of @code{dired-guess-shell-alist-user} (defined by the +user) will override these rules.@refill + +@item dired-guess-shell-alist-user +@vindex dired-guess-shell-alist-user +If non-@code{nil}, a user-defined alist of file regexps and their suggested +commands. These rules take precedence over the predefined rules in the +variable @code{dired-guess-shell-alist-default} (to which they are prepended) +when @code{dired-do-shell-command} is run). +@refill + +Each element of the alist looks like + +@example +(@var{regexp} @var{command}@dots{}) +@end example + +where each @var{command} can either be a string or a lisp expression +that evaluates to a string. If several @var{COMMAND}s are given, all +will temporarily be pushed on the history. + +You can set this variable in your @file{~/.emacs}. For example, +to add rules for @samp{.foo} and @samp{.bar} file extensions, write + +@example +(setq dired-guess-shell-alist-user + (list + (list "\\.foo$" "@var{foo-command}");; fixed rule + ;; possibly more rules... + (list "\\.bar$";; rule with condition test + '(if @var{condition} + "@var{bar-command-1}" + "@var{bar-command-2}")))) +@end example + +@noindent +This will override any predefined rules for the same extensions. + +@item dired-guess-shell-gnutar +@vindex dired-guess-shell-gnutar +@cindex Passing GNU tar its `z' switch. +Default: @code{nil} + +If non-@code{nil}, name of the GNU tar executable (e.g., @samp{"tar"} or +@samp{"gnutar"}). GNU tar's @samp{z} switch is used for compressed tar files. +If you don't have GNU tar, set this to @code{nil}: a pipe using @samp{zcat} is +then used. + +@item dired-guess-shell-gzip-quiet +@vindex dired-guess-shell-gzip-quiet +@cindex GNU zip. +Default: @code{t} + +A non-@code{nil} value means that @code{-q} is passed to gzip overriding a +verbose GNU zip's @samp{GZIP} environment variable. + +@item dired-guess-shell-znew-switches nil +@vindex dired-guess-shell-znew-switches nil +@cindex GNU zip. +Default: @code{nil} + +A string of switches passed to GNU zip's @file{znew}. An example is +@samp{"-K"} which will make @file{znew} keep a .Z file when it is smaller than +the .gz file. + +@item dired-shell-command-history nil +@vindex dired-shell-command-history nil + +History list for commands that read dired-shell commands. +@end table + +@node Virtual Dired, Advanced Mark Commands, Shell Command Guessing, Top +@comment node-name, next, previous, up +@chapter Virtual Dired + +@cindex Virtual Dired +@cindex Perusing ls listings +@cindex ls listings, how to peruse them in Dired +Using @dfn{Virtual Dired} means putting a buffer with Dired-like +contents in Dired mode. The files described by the buffer contents need +not actually exist. This is useful if you want to peruse an @samp{ls -lR} +output file, for example one you got from an FTP server. You can use +all motion commands usually available in Dired. You can also use +it to save a Dired buffer in a file and resume it in a later session. + +@findex dired-virtual +@kindex g +@findex dired-virtual-revert +Type @kbd{M-x dired-virtual} to put the current buffer into virtual +Dired mode. You will be prompted for the top level directory of this +buffer, with a default value guessed from the buffer contents. To +convert the virtual to a real Dired buffer again, type @kbd{g} (which +calls @code{dired-virtual-revert}) in the virtual Dired buffer and +answer @samp{y}. You don't have to do this, though: you can relist +single subdirectories using @kbd{l} (@code{dired-do-redisplay}) on the subdirectory +headerline, leaving the buffer in virtual Dired mode all the time. + +@findex dired-virtual-mode +@vindex auto-mode-alist +The function @samp{dired-virtual-mode} is specially designed to turn on +virtual Dired mode from the @code{auto-mode-alist}. To edit all +@file{*.dired} files automatically in virtual Dired mode, put this into your +@file{~/.emacs}: + +@example +(setq auto-mode-alist (cons '("[^/]\\.dired$" . dired-virtual-mode) + auto-mode-alist)) +@end example + +The regexp is a bit more complicated than usual to exclude ".dired" +local variable files. + +@node Advanced Mark Commands, Advanced Cleaning Functions, Virtual Dired, Top +@comment node-name, next, previous, up +@chapter Advanced Mark Commands + +@table @kbd +@item F +@kindex F +@cindex Visiting several files at once +@cindex Simultaneous visiting of several files +@findex dired-do-find-marked-files +(@code{dired-do-find-marked-files}) Find all marked files at once displaying +simultaneously. If optional NOSELECT is non-@code{nil} then just find the +files but do not select. If you want to keep the dired buffer displayed, type +@kbd{C-x 2} first. If you want just the marked files displayed and nothing +else, type @kbd{C-x 1} first. + +The current window is split across all files marked, as evenly as possible. +Remaining lines go to the bottom-most window. The number of files that can be +displayed this way is restricted by the height of the current window and the +variable @code{window-min-height}. +@end table + +@table @code +@item dired-mark-extension +@findex dired-mark-extension +Mark all files with a certain extension for use in later commands. A @samp{.} +is not automatically prepended to the string entered. + +When called from lisp, @var{extension} may also be a list of extensions +and an optional argument @var{marker-char} specifies the marker used. + +@item dired-flag-extension +@findex dired-flag-extension +Flag all files with a certain extension for deletion. A @samp{.} is +@emph{not} automatically prepended to the string entered. +@end table + +@ifinfo +@menu +* Advanced Cleaning Functions:: +* Advanced Cleaning Variables:: +* Special Marking Function:: +@end menu +@end ifinfo + +@node Advanced Cleaning Functions, Advanced Cleaning Variables, Advanced Mark Commands, Advanced Mark Commands +@comment node-name, next, previous, up + +@section Advanced Cleaning Functions + +@table @code +@item dired-clean-patch +@findex dired-clean-patch +Flag dispensable files created by the @samp{patch} program for deletion. See +variable @code{dired-patch-unclean-extensions}. + +@item dired-clean-tex +@findex dired-clean-tex +Flag dispensable files created by @TeX{}, La@TeX{}, and @samp{texinfo} for +deletion. See the following variables (@xref{Advanced Cleaning Variables}) + +@itemize @bullet +@item +@code{dired-tex-unclean-extensions} +@item +@code{dired-texinfo-unclean-extensions} +@item +@code{dired-latex-unclean-extensions} +@item +@code{dired-bibtex-unclean-extensions} +@end itemize + +@item dired-very-clean-tex +@findex dired-very-clean-tex +Flag dispensable files created by @TeX{}, La@TeX{}, @samp{texinfo}, and ".dvi" +files for deletion. +@end table + +@node Advanced Cleaning Variables, Special Marking Function, Advanced Cleaning Functions, Advanced Mark Commands +@comment node-name, next, previous, up + +@section Advanced Cleaning Variables + +@noindent Variables used by the above cleaning commands (and in the default value for +variable @code{dired-omit-extensions}, @xref{Omitting Variables}) + +@table @code +@item dired-patch-unclean-extensions +@vindex dired-patch-unclean-extensions +Default: @code{'(".rej" ".orig")} + +List of extensions of dispensable files created by the @samp{patch} program. + +@item dired-tex-unclean-extensions +@vindex dired-tex-unclean-extensions +Default: @code{'(".toc" ".log" ".aux")} + +List of extensions of dispensable files created by @TeX{}. + +@item dired-texinfo-unclean-extensions +@vindex dired-texinfo-unclean-extensions +Default: @code{'(".cp" ".cps" ".fn" ".fns" ".ky" ".kys"} +@code{".pg" ".pgs" ".tp" ".tps" ".vr" ".vrs")} + +List of extensions of dispensable files created by @samp{texinfo}. + +@item dired-latex-unclean-extensions +@vindex dired-latex-unclean-extensions +Default: @code{'(".idx" ".lof" ".lot" ".glo")} + +List of extensions of dispensable files created by La@TeX{}. + +@item dired-bibtex-unclean-extensions +@vindex dired-bibtex-unclean-extensions +Default: @code{'(".blg" ".bbl")} + +List of extensions of dispensable files created by Bib@TeX{}. +@end table + +@node Special Marking Function, Multiple Dired Directories, Advanced Cleaning Variables, Advanced Mark Commands +@comment node-name, next, previous, up + +@section Special Marking Function + +@table @kbd +@item M-( +@kindex M-( +@findex dired-mark-sexp +@cindex Lisp expression, marking files with in Dired +@cindex Mark file by lisp expression +(@code{dired-mark-sexp}) Mark files for which @var{predicate} returns +non-@code{nil}. With a prefix argument, unflag those files instead. + +The @var{predicate} is a lisp expression that can refer to the following +symbols: +@table @code +@item inode +[@i{integer}] the inode of the file (only for @samp{ls -i} output) +@item s +[@i{integer}] the size of the file for @samp{ls -s} output (usually in blocks or, +with @samp{-k}, in KBytes) +@item mode +[@i{string}] file permission bits, e.g., @samp{"-rw-r--r--"} +@item nlink +[@i{integer}] number of links to file +@item uid +[@i{string}] owner +@item gid +[@i{string}] group (If the gid is not displayed by @samp{ls}, this +will still be set (to the same as uid)) +@item size +[@i{integer}] file size in bytes +@item time +[@i{string}] the time that @samp{ls} displays, e.g., @samp{"Feb 12 14:17"} +@item name +[@i{string}] the name of the file +@item sym +[@i{string}] if file is a symbolic link, the linked-to name, else @samp{""} +@end table + +@noindent +For example, use +@example +(equal 0 size) +@end example +to mark all zero length files. + +To find out all not yet compiled Emacs lisp files in a directory, dired +all @file{.el} files in the lisp directory using the wildcard +@samp{*.el}. Then use @kbd{M-(} with +@example +(not (file-exists-p (concat name "c"))) +@end example +to mark all @file{.el} files without a corresponding @file{.elc} file. + +@end table + +@node Multiple Dired Directories, Find File At Point, Special Marking Function, Top +@comment node-name, next, previous, up +@chapter Multiple Dired Directories and Non-Dired Commands + +@cindex Multiple Dired directories +@cindex Working directory +An Emacs buffer can have but one working directory, stored in the +buffer-local variable @code{default-directory}. A Dired buffer may have +several subdirectories inserted, but still has but one working +directory: that of the top level Dired directory in that buffer. For +some commands it is appropriate that they use the current Dired +directory instead of @code{default-directory}, e.g., @code{find-file} and +@code{compile}. + +A general mechanism is provided for special handling of the working +directory in special major modes: + +@table @code +@item default-directory-alist +@vindex default-directory-alist +Default: @code{((dired-mode . (dired-current-directory)))} + +Alist of major modes and their opinion on @code{default-directory}, as a +lisp expression to evaluate. A resulting value of @code{nil} is ignored +in favor of @code{default-directory}. + +@item default-directory +@findex default-directory +Function with usage like variable @code{default-directory}, but knows about the +special cases in variable @code{default-directory-alist}. +@end table + +@node Find File At Point, Miscellaneous Commands, Multiple Dired Directories, Top +@comment node-name, next, previous, up + +@section Find File At Point +@cindex Visiting a file mentioned in a buffer +@cindex Finding a file at point + +@file{dired-x} provides a method of visiting or editing a file mentioned in +the buffer you are viewing (e.g., a mail buffer, a news article, a README +file, etc.) or to test if that file exists. You can then modify this in the +minibuffer after snatching the filename. + +When installed @file{dired-x} will substitute @code{dired-x-find-file} for +@code{find-file} (normally bound to @kbd{C-x C-f}) and +@code{dired-x-find-file-other-window} for @code{find-file-other-window} +(normally bound to @kbd{C-x 4 C-f}). + +In order to use this feature, you will need to set +@code{dired-x-hands-off-my-keys} to @code{nil} inside @code{dired-load-hook} +(@xref{Optional Installation File At Point}). + +@table @code +@item dired-x-find-file +@findex dired-x-find-file +@kindex C-x C-f + +@code{dired-x-find-file} behaves exactly like @code{find-file} (normally bound +to @kbd{C-x C-f}) unless a prefix argument is passed to the function in which +case it will use the filename at point as a guess for the file to visit. + +For example, if the buffer you were reading contained the words + +@example +Available via anonymous ftp in + + /roebling.poly.edu:/pub/lisp/crypt++.el.gz +@end example + +then you could move your cursor to the line containing the ftp address and +type @kbd{C-u C-x C-f} (the @kbd{C-u} is a universal argument). The +minibuffer would read + +@example +Find file: /roebling.poly.edu:/pub/lisp/crypt++.el.gz +@end example + +with the point after the last @code{/}. If you hit return emacs will visit +the file at that address. This also works with files on your own computer. + +@item dired-x-find-file-other-window +@findex dired-x-find-file-other-window +@kindex C-x 4 C-f + +@code{dired-x-find-file-other-window} behaves exactly like +@code{find-file-other-window} (normally bound to @kbd{C-x 4 C-f}) unless a +prefix argument is used. See @code{dired-x-find-file} for more information. + +@item dired-x-hands-off-my-keys +@vindex dired-x-hands-off-my-keys +If set to @code{t}, then it means that @file{dired-x} should @emph{not} bind +@code{dired-x-find-file} over @code{find-file} on keyboard. Similarly, it +should not bind @code{dired-x-find-file-other-window} over +@code{find-file-other-window}. If you change this variable after +@file{dired-x.el} is loaded then do @kbd{M-x dired-x-bind-find-file}. The +default value of this variable is @kbd{t}; by default, the binding is not +done. See @xref{Optional Installation File At Point}. + +@item dired-x-bind-find-file +@findex dired-x-bind-find-file +A function, which can be called interactively or in your @file{~/.emacs} file, +that uses the value of @code{dired-x-hands-off-my-keys} to determine if +@code{dired-x-find-file} should be bound over @code{find-file} and +@code{dired-x-find-file-other-window} bound over +@code{find-file-other-window}. See @xref{Optional Installation File At Point}. +@end table + +@node Miscellaneous Commands, Bugs, Find File At Point, Top +@comment node-name, next, previous, up +@chapter Miscellaneous Commands + +Miscellaneous features not fitting anywhere else: + +@table @code +@item dired-find-subdir +@vindex dired-find-subdir +Default: @code{nil} + +If non-@code{nil}, Dired does not make a new buffer for a directory if it can +be found (perhaps as subdirectory) in some existing Dired buffer. + +If there are several Dired buffers for a directory, the most recently +used is chosen. + +Dired avoids switching to the current buffer, so that if you have a +normal and a wildcard buffer for the same directory, @kbd{C-x d RET} +will toggle between those two. +@end table + +@table @kbd +@findex dired-goto-file +@kindex M-g +@item M-g +(@code{dired-goto-file}) Goto file line of a file (or directory). + +@findex dired-goto-subdir +@kindex M-G +@item M-G +(@code{dired-goto-subdir}) Goto headerline of an inserted directory. +This commands reads its argument with completion over the names of the +inserted subdirectories. +@end table + +@table @kbd +@item w +@cindex Adding to the kill ring in dired. +@kindex w +@findex dired-copy-filename-as-kill +(@code{dired-copy-filename-as-kill}) The @kbd{w} command puts the names +of the marked (or next @var{N}) files into the kill ring, as if you had +killed them with @kbd{C-w}. With a zero prefix argument @var{N}=0, use the +complete pathname of each file. With a raw (just @kbd{C-u}) prefix argument, +use the relative pathname of each marked file. As a special case, if no +prefix argument is given and point is on a directory headerline, it +gives you the name of that directory, without looking for marked files. + +@vindex dired-marked-files +The list of names is also stored onto the variable @code{dired-marked-files} +for use, e.g., in the @kbd{M-:} (@code{eval-expression}) command. + +As this command also displays what was pushed onto the kill ring you can +use it to display the list of currently marked files in the +echo area (unless you happen to be on a subdirectory headerline). + +You can then feed the file name to other Emacs commands with @kbd{C-y}. +For example, say you want to rename a long filename to a slightly +different name. First type @kbd{w} to push the old name onto the kill +ring. Then type @kbd{R} to rename it and use @kbd{C-y} inside @kbd{R}'s +minibuffer prompt to insert the old name at a convenient place. + +@item T +@kindex T +@cindex Toggling marks. +@findex dired-do-toggle +(@code{dired-do-toggle}) Toggle marks. That is, currently marked +files become unmarked and vice versa. Files marked with other flags +(such as `D') are not affected. The special directories `.' and `..' +are never toggled. +@end table + +@table @code +@item dired-smart-shell-command +@findex dired-smart-shell-command +@findex shell-command +@kindex M-! +Like function @code{shell-command}, but in the current Dired directory. +Bound to @kbd{M-!} in Dired buffers. + +@item dired-jump +@findex dired-jump +@kindex C-x C-j +@cindex Jumping to dired listing containing file. +Bound to @kbd{C-x C-j}. Jump back to dired: If in a file, dired the current +directory and move to file's line. If in Dired already, pop up a level and +goto old directory's line. In case the proper Dired file line cannot be +found, refresh the Dired buffer and try again. + +@item dired-jump-other-window +@findex dired-jump-other-window +@kindex C-x 4 C-j +Bound to @kbd{C-x 4 C-j}. Like @code{dired-jump}, but to other window. + +These functions can be autoloaded so they work even though @file{dired-x.el} +has not been loaded yet (@xref{Optional Installation Dired Jump}). + +@vindex dired-bind-jump +If the variable @code{dired-bind-jump} is @code{nil}, @code{dired-jump} will not be +bound to @kbd{C-x C-j} and @code{dired-jump-other-window} will not be bound to +@kbd{C-x 4 C-j}. + +@item dired-vm +@cindex Reading mail. +@kindex V +@findex dired-vm +Bound to @kbd{V} if @code{dired-bind-vm} is t. Run VM on this file (assumed +to be a UNIX mail folder). + +@vindex dired-vm-read-only-folders +If you give this command a prefix argument, it will visit the folder +read-only. This only works in VM~5, not VM~4. + +If the variable @code{dired-vm-read-only-folders} is t, @code{dired-vm} will +visit all folders read-only. If it is neither @code{nil} nor @code{t}, e.g., +the symbol @code{'if-file-read-only}, only files not writable by you are +visited read-only. This is the recommended value if you run VM 5. + +@vindex dired-bind-vm +If the variable @code{dired-bind-vm} is t, @code{dired-vm} will be bound to +@kbd{V}. Otherwise, @code{dired-bind-rmail} will be bound. + +@item dired-rmail +@cindex Reading mail. +@findex dired-rmail +Bound to @kbd{V} if @code{dired-bind-vm} is @code{nil}. Run Rmail on this +file (assumed to be mail folder in Rmail/BABYL format). + +@item dired-info +@kindex I +@cindex Running info. +@findex dired-info +Bound to @kbd{I}. Run Info on this file (assumed to be a file in Info +format). + +@vindex dired-bind-info +If the variable @code{dired-bind-info} is @code{nil}, @code{dired-info} will +not be bound to I. + +@item dired-man +@cindex Running man. +@kindex N +@findex dired-man +Bound to @kbd{N}. Run man on this file (assumed to be a file in nroff +format). + +@vindex dired-bind-man +If the variable @code{dired-bind-man} is @code{nil}, @code{dired-man} will not +be bound to N. + +@item dired-do-relative-symlink +@cindex Relative symbolic links. +@kindex Y +@findex dired-do-relative-symlink +Bound to @kbd{Y}. Relative symlink all marked (or next ARG) files into a +directory, or make a relative symbolic link to the current file. This creates +relative symbolic links like + + foo -> ../bar/foo + +not absolute ones like + + foo -> /ugly/path/that/may/change/any/day/bar/foo + +@item dired-do-relative-symlink-regexp +@kindex %Y +@findex dired-do-relative-symlink-regexp +Bound to @kbd{%Y}. Relative symlink all marked files containing REGEXP to +NEWNAME. See functions `dired-do-rename-regexp' and `dired-do-relsymlink' for +more info. +@end table + +@node Bugs, Concept Index, Miscellaneous Commands, Top +@comment node-name, next, previous, up +@chapter Bugs +@cindex Bugs +@findex dired-x-submit-report + +@noindent +If you encounter a bug in this package, wish to suggest an +enhancement, or want to make a smart remark, then type + +@example +@kbd{M-x dired-x-submit-report} +@end example + +@noindent +to set up an outgoing mail buffer, with the proper address to the +@file{dired-x.el} maintainer automatically inserted in the @samp{To:@:} field. +This command also inserts information that the Dired X maintainer can use to +recreate your exact setup, making it easier to verify your bug or social +maladjustment. + +Lawrence R. Dodd <dodd@@roebling.poly.edu> + +@node Concept Index, Command Index, Bugs, Top +@comment node-name, next, previous, up +@unnumbered Concept Index +@printindex cp + +@node Command Index, Key Index, Concept Index, Top +@comment node-name, next, previous, up +@unnumbered Function Index +@printindex fn + +@node Key Index, Variable Index, Command Index, Top +@comment node-name, next, previous, up +@unnumbered Key Index +@printindex ky + +@node Variable Index, , Key Index, Top +@comment node-name, next, previous, up +@unnumbered Variable Index +@printindex vr + +@c @summarycontents +@contents + +@bye +@c dired-x.texi ends here. diff --git a/man/dired.texi b/man/dired.texi new file mode 100644 index 00000000000..11114f785ae --- /dev/null +++ b/man/dired.texi @@ -0,0 +1,950 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Dired, Calendar/Diary, Rmail, Top +@chapter Dired, the Directory Editor +@cindex Dired + + Dired makes an Emacs buffer containing a listing of a directory, and +optionally some of its subdirectories as well. You can use the normal +Emacs commands to move around in this buffer, and special Dired commands +to operate on the files listed. + +@menu +* Enter: Dired Enter. How to invoke Dired. +* Commands: Dired Commands. Commands in the Dired buffer. +* Deletion: Dired Deletion. Deleting files with Dired. +* Flagging Many Files:: Flagging files based on their names. +* Visit: Dired Visiting. Other file operations through Dired. +* Marks vs Flags:: Flagging for deletion vs marking. +* Operating on Files:: How to copy, rename, print, compress, etc. + either one file or several files. +* Shell Commands in Dired:: Running a shell command on the marked files. +* Transforming File Names:: Using patterns to rename multiple files. +* Comparison in Dired:: Running `diff' by way of Dired. +* Subdirectories in Dired:: Adding subdirectories to the Dired buffer. +* Subdirectory Motion:: Moving across subdirectories, and up and down. +* Hiding Subdirectories:: Making subdirectories visible or invisible. +* Updating: Dired Updating. Discarding lines for files of no interest. +* Find: Dired and Find. Using `find' to choose the files for Dired. +@end menu + +@node Dired Enter +@section Entering Dired + +@findex dired +@kindex C-x d +@vindex dired-listing-switches + To invoke Dired, do @kbd{C-x d} or @kbd{M-x dired}. The command reads +a directory name or wildcard file name pattern as a minibuffer argument +to specify which files to list. Where @code{dired} differs from +@code{list-directory} is in putting the buffer into Dired mode so that +the special commands of Dired are available. + + The variable @code{dired-listing-switches} specifies the options to +give to @code{ls} for listing directory; this string @emph{must} contain +@samp{-l}. If you use a numeric prefix argument with the @code{dired} +command, you can specify the @code{ls} switches with the minibuffer +before you enter the directory specification. + +@findex dired-other-window +@kindex C-x 4 d +@findex dired-other-frame +@kindex C-x 5 d + To display the Dired buffer in another window rather than in the +selected window, use @kbd{C-x 4 d} (@code{dired-other-window}) instead +of @kbd{C-x d}. @kbd{C-x 5 d} (@code{dired-other-frame}) uses a +separate frame to display the Dired buffer. + +@node Dired Commands +@section Commands in the Dired Buffer + + The Dired buffer is ``read-only,'' and inserting text in it is not +useful, so ordinary printing characters such as @kbd{d} and @kbd{x} are +used for special Dired commands. Some Dired commands @dfn{mark} or +@dfn{flag} the @dfn{current file} (that is, the file on the current +line); other commands operate on the marked files or on the flagged +files. + +@kindex C-n @r{(Dired)} +@kindex C-p @r{(Dired)} + All the usual Emacs cursor motion commands are available in Dired +buffers. Some special-purpose cursor motion commands are also +provided. The keys @kbd{C-n} and @kbd{C-p} are redefined to put the +cursor at the beginning of the file name on the line, rather than at the +beginning of the line. + +@kindex SPC @r{(Dired)} + For extra convenience, @key{SPC} and @kbd{n} in Dired are equivalent +to @kbd{C-n}. @kbd{p} is equivalent to @kbd{C-p}. (Moving by lines is +so common in Dired that it deserves to be easy to type.) @key{DEL} +(move up and unflag) is often useful simply for moving up. + +@node Dired Deletion +@section Deleting Files with Dired +@cindex flagging files (in Dired) +@cindex deleting files (in Dired) + + The primary use of Dired is to @dfn{flag} files for deletion and then +delete the files previously flagged. + +@table @kbd +@item d +Flag this file for deletion. +@item u +Remove deletion flag on this line. +@item @key{DEL} +Move point to previous line and remove the deletion flag on that line. +@item x +Delete the files that are flagged for deletion. +@end table + +@kindex d @r{(Dired)} +@findex dired-flag-file-deletion + You can flag a file for deletion by moving to the line describing the +file and typing @kbd{d} (@code{dired-flag-file-deletion}). The deletion flag is visible as a @samp{D} at +the beginning of the line. This command moves point to the next line, +so that repeated @kbd{d} commands flag successive files. A numeric +argument serves as a repeat count. + +@kindex u @r{(Dired deletion)} +@kindex DEL @r{(Dired)} + The files are flagged for deletion rather than deleted immediately to +reduce the danger of deleting a file accidentally. Until you direct +Dired to expunge the flagged files, you can remove deletion flags using +the commands @kbd{u} and @key{DEL}. @kbd{u} (@code{dired-unmark}) works +just like @kbd{d}, but removes flags rather than making flags. +@key{DEL} (@code{dired-unmark-backward}) moves upward, removing flags; +it is like @kbd{u} with argument @minus{}1. + +@kindex x @r{(Dired)} +@findex dired-expunge +@cindex expunging (Dired) + To delete the flagged files, type @kbd{x} (@code{dired-expunge}). +This command first displays a list of all the file names flagged for +deletion, and requests confirmation with @kbd{yes}. If you confirm, +Dired deletes the flagged files, then deletes their lines from the text +of the Dired buffer. The shortened Dired buffer remains selected. + + If you answer @kbd{no} or quit with @kbd{C-g} when asked to confirm, you +return immediately to Dired, with the deletion flags still present in +the buffer, and no files actually deleted. + +@node Flagging Many Files +@section Flagging Many Files at Once + +@table @kbd +@item # +Flag all auto-save files (files whose names start and end with @samp{#}) +for deletion (@pxref{Auto Save}). + +@item ~ +Flag all backup files (files whose names end with @samp{~}) for deletion +(@pxref{Backup}). + +@item & +Flag for deletion all files with certain kinds of names, names that +suggest you could easily create the files again. + +@item .@: @r{(Period)} +Flag excess numeric backup files for deletion. The oldest and newest +few backup files of any one file are exempt; the middle ones are +flagged. + +@item % d @var{regexp} @key{RET} +Flag for deletion all files whose names match the regular expression +@var{regexp}. +@end table + + The @kbd{#}, @kbd{~}, @kbd{&}, and @kbd{.} commands flag many files for +deletion, based on their file names. These commands are useful +precisely because they do not themselves delete any files; you can +remove the deletion flags from any flagged files that you really wish to +keep.@refill + +@kindex & @r{(Dired)} +@findex dired-flag-garbage-files +@vindex dired-garbage-files-regexp + @kbd{&} (@code{dired-flag-garbage-files}) flags files whose names +match the regular expression specified by the variable +@code{dired-garbage-files-regexp}. By default, this matches certain +files produced by @TeX{}, and the @samp{.orig} and @samp{.rej} files +produced by @code{patch}. + +@kindex # @r{(Dired)} +@kindex ~ @r{(Dired)} +@findex dired-flag-auto-save-files +@findex dired-flag-backup-files + @kbd{#} (@code{dired-flag-auto-save-files}) flags for deletion all +files whose names look like auto-save files (@pxref{Auto Save})---that +is, files whose names begin and end with @samp{#}. @kbd{~} +(@code{dired-flag-backup-files}) flags for deletion all files whose +names say they are backup files (@pxref{Backup})---that is, whose names +end in @samp{~}. + +@kindex . @r{(Dired)} +@vindex dired-kept-versions +@findex dired-clean-directory + @kbd{.} (period, @code{dired-clean-directory}) flags just some of the +backup files for deletion: all but the oldest few and newest few backups +of any one file. Normally @code{dired-kept-versions} (@strong{not} +@code{kept-new-versions}; that applies only when saving) specifies the +number of newest versions of each file to keep, and +@code{kept-old-versions} specifies the number of oldest versions to +keep. + + Period with a positive numeric argument, as in @kbd{C-u 3 .}, +specifies the number of newest versions to keep, overriding +@code{dired-kept-versions}. A negative numeric argument overrides +@code{kept-old-versions}, using minus the value of the argument to +specify the number of oldest versions of each file to keep. + +@findex dired-flag-files-regexp +@kindex % d @r{(Dired)} + The @kbd{% d} command flags all files whose names match a specified +regular expression (@code{dired-flag-files-regexp}). Only the +non-directory part of the file name is used in matching. You can use +@samp{^} and @samp{$} to anchor matches. You can exclude subdirectories +by hiding them (@pxref{Hiding Subdirectories}). + +@node Dired Visiting +@section Visiting Files in Dired + + There are several Dired commands for visiting or examining the files +listed in the Dired buffer. All of them apply to the current line's +file; if that file is really a directory, these commands invoke Dired on +that subdirectory (making a separate Dired buffer). + +@table @kbd +@item f +@kindex f @r{(Dired)} +@findex dired-find-file +Visit the file described on the current line, like typing @kbd{C-x C-f} +and supplying that file name (@code{dired-find-file}). @xref{Visiting}. + +@item @key{RET} +@kindex RET @r{(Dired)} +Equivalent to @kbd{f}. + +@item o +@kindex o @r{(Dired)} +@findex dired-find-file-other-window +Like @kbd{f}, but uses another window to display the file's buffer +(@code{dired-find-file-other-window}). The Dired buffer remains visible +in the first window. This is like using @kbd{C-x 4 C-f} to visit the +file. @xref{Windows}. + +@item C-o +@kindex C-o @r{(Dired)} +@findex dired-display-file +Visit the file described on the current line, and display the buffer in +another window, but do not select that window (@code{dired-display-file}). + +@item Mouse-2 +@findex dired-mouse-find-file-other-window +Visit the file named by the line you click on +(@code{dired-mouse-find-file-other-window}). This uses another window +to display the file, like the @kbd{o} command. + +@item v +@kindex v @r{(Dired)} +@findex dired-view-file +View the file described on the current line, using @kbd{M-x view-file} +(@code{dired-view-file}). + +Viewing a file is like visiting it, but is slanted toward moving around +in the file conveniently and does not allow changing the file. +@xref{Misc File Ops,View File}. +@end table + +@node Marks vs Flags +@section Dired Marks vs. Flags + +@cindex marking in Dired + Instead of flagging a file with @samp{D}, you can @dfn{mark} the file +with some other character (usually @samp{*}). Most Dired commands to +operate on files, aside from ``expunge'' (@kbd{x}), look for files +marked with @samp{*}. + + Here are some commands for marking with @samp{*}, or for unmarking or +operating on marks. (@xref{Dired Deletion}, for commands to flag and +unflag files.) + +@table @kbd +@item m +@itemx * m +@kindex m @r{(Dired)} +@kindex * m @r{(Dired)} +@findex dired-mark +Mark the current file with @samp{*} (@code{dired-mark}). With a numeric +argument @var{n}, mark the next @var{n} files starting with the current +file. (If @var{n} is negative, mark the previous @minus{}@var{n} +files.) + +@item * * +@kindex * * @r{(Dired)} +@findex dired-mark-executables +Mark all executable files with @samp{*} +(@code{dired-mark-executables}). With a numeric argument, unmark all +those files. + +@item * @@ +@kindex * @@ @r{(Dired)} +@findex dired-mark-symlinks +Mark all symbolic links with @samp{*} (@code{dired-mark-symlinks}). +With a numeric argument, unmark all those files. + +@item * / +@kindex * / @r{(Dired)} +@findex dired-mark-directories +Mark with @samp{*} all files which are actually directories, except for +@file{.} and @file{..} (@code{dired-mark-directories}). With a numeric +argument, unmark all those files. + +@item * s +@kindex * s @r{(Dired)} +@findex dired-mark-subdir-files +Mark all the files in the current subdirectory, aside from @file{.} +and @file{..} (@code{dired-mark-subdir-files}). + +@item u +@itemx * u +@kindex u @r{(Dired)} +@kindex * u @r{(Dired)} +@findex dired-unmark +Remove any mark on this line (@code{dired-unmark}). + +@item @key{DEL} +@itemx * @key{DEL} +@kindex * DEL @r{(Dired)} +@findex dired-unmark-backward +Move point to previous line and remove any mark on that line +(@code{dired-unmark-backward}). + +@item * ! +@kindex * ! @r{(Dired)} +@findex dired-unmark-all-files-no-query +Remove all marks from all the files in this Dired buffer +(@code{dired-unmark-all-files-no-query}). + +@item * ? @var{markchar} +@kindex * ? @r{(Dired)} +@findex dired-unmark-all-files +Remove all marks that use the character @var{markchar} +(@code{dired-unmark-all-files}). The argument is a single +character---do not use @key{RET} to terminate it. + +With a numeric argument, this command queries about each marked file, +asking whether to remove its mark. You can answer @kbd{y} meaning yes, +@kbd{n} meaning no, or @kbd{!} to remove the marks from the remaining +files without asking about them. + +@item * C-n +@findex dired-next-marked-file +@kindex * C-n @r{(Dired)} +Move down to the next marked file (@code{dired-next-marked-file}) +A file is ``marked'' if it has any kind of mark. + +@item * C-p +@findex dired-prev-marked-file +@kindex * C-p @r{(Dired)} +Move up to the previous marked file (@code{dired-prev-marked-file}) + +@item * t +@kindex * t @r{(Dired)} +@findex dired-do-toggle +Toggle all marks (@code{dired-do-toggle}): files marked with @samp{*} +become unmarked, and unmarked files are marked with @samp{*}. Files +marked in any other way are not affected. + +@item * c @var{old} @var{new} +@kindex * c @r{(Dired)} +@findex dired-change-marks +Replace all marks that use the character @var{old} with marks that use +the character @var{new} (@code{dired-change-marks}). This command is +the primary way to create or use marks other than @samp{*} or @samp{D}. +The arguments are single characters---do not use @key{RET} to terminate +them. + +You can use almost any character as a mark character by means of this +command, to distinguish various classes of files. If @var{old} is a +space (@samp{ }), then the command operates on all unmarked files; if +@var{new} is a space, then the command unmarks the files it acts on. + +To illustrate the power of this command, here is how to put @samp{D} +flags on all the files that have no marks, while unflagging all those +that already have @samp{D} flags: + +@example +* c D t * c SPC D * c t SPC +@end example + +This assumes that no files are marked with @samp{t}. + +@item % m @var{regexp} @key{RET} +@itemx * % @var{regexp} @key{RET} +@findex dired-mark-files-regexp +@kindex % m @r{(Dired)} +@kindex * % @r{(Dired)} +Mark (with @samp{*}) all files whose names match the regular expression +@var{regexp} (@code{dired-mark-files-regexp}). This command is like +@kbd{% d}, except that it marks files with @samp{*} instead of flagging +with @samp{D}. @xref{Flagging Many Files}. + +Only the non-directory part of the file name is used in matching. Use +@samp{^} and @samp{$} to anchor matches. Exclude subdirectories by +hiding them (@pxref{Hiding Subdirectories}). + +@item % g @var{regexp} @key{RET} +@findex dired-mark-files-containing-regexp +@kindex % m @r{(Dired)} +Mark (with @samp{*}) all files whose @emph{contents} contain a match for +the regular expression @var{regexp} +(@code{dired-mark-files-containing-regexp}). This command is like +@kbd{% m}, except that it searches the file contents instead of the file +name. + +@item C-_ +@kindex C-_ @r{(Dired)} +@findex dired-undo +Undo changes in the Dired buffer, such as adding or removing +marks (@code{dired-undo}). +@end table + +@node Operating on Files +@section Operating on Files +@cindex operating on files in Dired + + This section describes the basic Dired commands to operate on one file +or several files. All of these commands are capital letters; all of +them use the minibuffer, either to read an argument or to ask for +confirmation, before they act. All of them give you several ways to +specify which files to manipulate: + +@itemize @bullet +@item +If you give the command a numeric prefix argument @var{n}, it operates +on the next @var{n} files, starting with the current file. (If @var{n} +is negative, the command operates on the @minus{}@var{n} files preceding +the current line.) + +@item +Otherwise, if some files are marked with @samp{*}, the command operates +on all those files. + +@item +Otherwise, the command operates on the current file only. +@end itemize + + Here are the file-manipulating commands that operate on files in this +way. (Some other Dired commands, such as @kbd{!} and the @samp{%} +commands, also use these conventions to decide which files to work on.) + +@table @kbd +@findex dired-do-copy +@kindex C @r{(Dired)} +@item C @var{new} @key{RET} +Copy the specified files (@code{dired-do-copy}). The argument @var{new} +is the directory to copy into, or (if copying a single file) the new +name. + +@vindex dired-copy-preserve-time +If @code{dired-copy-preserve-time} is non-@code{nil}, then copying with +this command sets the modification time of the new file to be the same +as that of the old file. + +@item D +@findex dired-do-delete +@kindex D @r{(Dired)} +Delete the specified files (@code{dired-do-delete}). Like the other +commands in this section, this command operates on the @emph{marked} +files, or the next @var{n} files. By contrast, @kbd{x} +(@code{dired-expunge}) deletes all @dfn{flagged} files. + +@findex dired-do-rename +@kindex R @r{(Dired)} +@item R @var{new} @key{RET} +Rename the specified files (@code{dired-do-rename}). The argument +@var{new} is the directory to rename into, or (if renaming a single +file) the new name. + +Dired automatically changes the visited file name of buffers associated +with renamed files so that they refer to the new names. + +@findex dired-do-hardlink +@kindex H @r{(Dired)} +@item H @var{new} @key{RET} +Make hard links to the specified files (@code{dired-do-hardlink}). The +argument @var{new} is the directory to make the links in, or (if making +just one link) the name to give the link. + +@findex dired-do-symlink +@kindex S @r{(Dired)} +@item S @var{new} @key{RET} +Make symbolic links to the specified files (@code{dired-do-symlink}). +The argument @var{new} is the directory to make the links in, or (if +making just one link) the name to give the link. + +@findex dired-do-chmod +@kindex M @r{(Dired)} +@item M @var{modespec} @key{RET} +Change the mode (also called ``permission bits'') of the specified files +(@code{dired-do-chmod}). This uses the @code{chmod} program, so +@var{modespec} can be any argument that @code{chmod} can handle. + +@findex dired-do-chgrp +@kindex G @r{(Dired)} +@item G @var{newgroup} @key{RET} +Change the group of the specified files to @var{newgroup} +(@code{dired-do-chgrp}). + +@findex dired-do-chown +@kindex O @r{(Dired)} +@item O @var{newowner} @key{RET} +Change the owner of the specified files to @var{newowner} +(@code{dired-do-chown}). (On most systems, only the superuser can do +this.) + +@vindex dired-chown-program +The variable @code{dired-chown-program} specifies the name of the +program to use to do the work (different systems put @code{chown} in +different places). + +@findex dired-do-print +@kindex P @r{(Dired)} +@item P @var{command} @key{RET} +Print the specified files (@code{dired-do-print}). You must specify the +command to print them with, but the minibuffer starts out with a +suitable guess made using the variables @code{lpr-command} and +@code{lpr-switches} (the same variables that @code{lpr-buffer} uses; +@pxref{Hardcopy}). + +@findex dired-do-compress +@kindex Z @r{(Dired)} +@item Z +Compress the specified files (@code{dired-do-compress}). If the file +appears to be a compressed file already, it is uncompressed instead. + +@findex dired-do-load +@kindex L @r{(Dired)} +@item L +Load the specified Emacs Lisp files (@code{dired-do-load}). +@xref{Lisp Libraries}. + +@findex dired-do-byte-compile +@kindex B @r{(Dired)} +@item B +Byte compile the specified Emacs Lisp files +(@code{dired-do-byte-compile}). @xref{Byte Compilation,, Byte +Compilation, elisp, The Emacs Lisp Reference Manual}. + +@kindex A @r{(Dired)} +@findex dired-do-search +@item A @var{regexp} @key{RET} +Search all the specified files for the regular expression @var{regexp} +(@code{dired-do-search}). + +This command is a variant of @code{tags-search}. The search stops at +the first match it finds; use @kbd{M-,} to resume the search and find +the next match. @xref{Tags Search}. + +@kindex Q @r{(Dired)} +@findex dired-do-query-replace +@item Q @var{from} @key{RET} @var{to} @key{RET} +Perform @code{query-replace-regexp} on each of the specified files, +replacing matches for @var{from} (a regular expression) with the string +@var{to} (@code{dired-do-query-replace}). + +This command is a variant of @code{tags-query-replace}. If you exit the +query replace loop, you can use @kbd{M-,} to resume the scan and replace +more matches. @xref{Tags Search}. +@end table + +@kindex + @r{(Dired)} +@findex dired-create-directory + One special file-operation command is @kbd{+} +(@code{dired-create-directory}). This command reads a directory name and +creates the directory if it does not already exist. + +@node Shell Commands in Dired +@section Shell Commands in Dired +@cindex shell commands, Dired + +@findex dired-do-shell-command +@kindex ! @r{(Dired)} +The dired command @kbd{!} (@code{dired-do-shell-command}) reads a shell +command string in the minibuffer and runs that shell command on all the +specified files. You can specify the files to operate on in the usual +ways for Dired commands (@pxref{Operating on Files}). There are two +ways of applying a shell command to multiple files: + +@itemize @bullet +@item +If you use @samp{*} in the shell command, then it runs just once, with +the list of file names substituted for the @samp{*}. The order of file +names is the order of appearance in the Dired buffer. + +Thus, @kbd{! tar cf foo.tar * @key{RET}} runs @code{tar} on the entire +list of file names, putting them into one tar file @file{foo.tar}. + +@item +If the command string doesn't contain @samp{*}, then it runs once +@emph{for each file}, with the file name added at the end. + +For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on each +file. +@end itemize + +What if you want to run the shell command once for each file but with +the file name inserted in the middle? Or if you want to use the file +names in a more complicated fashion? Use a shell loop. For example, +this shell command would run @code{uuencode} on each of the specified +files, writing the output into a corresponding @file{.uu} file: + +@example +for file in *; do uuencode $file $file >$file.uu; done +@end example + +The working directory for the shell command is the top-level directory +of the Dired buffer. + +The @kbd{!} command does not attempt to update the Dired buffer to show +new or modified files, because it doesn't really understand shell +commands, and does not know what files the shell command changed. Use +the @kbd{g} command to update the Dired buffer (@pxref{Dired +Updating}). + +@node Transforming File Names +@section Transforming File Names in Dired + + Here are commands that alter file names in a systematic way: + +@table @kbd +@findex dired-upcase +@kindex % u @r{(Dired)} +@item % u +Rename each of the selected files to an upper-case name +(@code{dired-upcase}). If the old file names are @file{Foo} +and @file{bar}, the new names are @file{FOO} and @file{BAR}. + +@item % l +@findex dired-downcase +@kindex % l @r{(Dired)} +Rename each of the selected files to a lower-case name +(@code{dired-downcase}). If the old file names are @file{Foo} and +@file{bar}, the new names are @file{foo} and @file{bar}. + +@item % R @var{from} @key{RET} @var{to} @key{RET} +@kindex % R @r{(Dired)} +@findex dired-do-rename-regexp +@itemx % C @var{from} @key{RET} @var{to} @key{RET} +@kindex % C @r{(Dired)} +@findex dired-do-copy-regexp +@itemx % H @var{from} @key{RET} @var{to} @key{RET} +@kindex % H @r{(Dired)} +@findex dired-do-hardlink-regexp +@itemx % S @var{from} @key{RET} @var{to} @key{RET} +@kindex % S @r{(Dired)} +@findex dired-do-symlink-regexp +These four commands rename, copy, make hard links and make soft links, +in each case computing the new name by regular-expression substitution +from the name of the old file. +@end table + + The four regular-expression substitution commands effectively perform +a search-and-replace on the selected file names in the Dired buffer. +They read two arguments: a regular expression @var{from}, and a +substitution pattern @var{to}. + + The commands match each ``old'' file name against the regular +expression @var{from}, and then replace the matching part with @var{to}. +You can use @samp{\&} and @samp{\@var{digit}} in @var{to} to refer to +all or part of what the pattern matched in the old file name, as in +@code{replace-regexp} (@pxref{Regexp Replace}). If the regular expression +matches more than once in a file name, only the first match is replaced. + + For example, @kbd{% R ^.*$ @key{RET} x-\& @key{RET}} renames each +selected file by prepending @samp{x-} to its name. The inverse of this, +removing @samp{x-} from the front of each file name, is also possible: +one method is @kbd{% R ^x-\(.*\)$ @key{RET} \1 @key{RET}}; another is +@kbd{% R ^x- @key{RET} @key{RET}}. (Use @samp{^} and @samp{$} to anchor +matches that should span the whole filename.) + + Normally, the replacement process does not consider the files' +directory names; it operates on the file name within the directory. If +you specify a numeric argument of zero, then replacement affects the +entire absolute file name including directory name. + + Often you will want to select the set of files to operate on using the +same @var{regexp} that you will use to operate on them. To do this, +mark those files with @kbd{% m @var{regexp} @key{RET}}, then use the +same regular expression in the command to operate on the files. To make +this easier, the @kbd{%} commands to operate on files use the last +regular expression specified in any @kbd{%} command as a default. + +@node Comparison in Dired +@section File Comparison with Dired + + Here are two Dired commands that compare specified files using +@code{diff}. + +@table @kbd +@item = +@findex dired-diff +@kindex = @r{(Dired)} +Compare the current file (the file at point) with another file (the file +at the mark) using the @code{diff} program (@code{dired-diff}). The +file at the mark is the first argument of @code{diff}, and the file at +point is the second argument. + +@findex dired-backup-diff +@kindex M-= @r{(Dired)} +@item M-= +Compare the current file with its latest backup file +(@code{dired-backup-diff}). If the current file is itself a backup, +compare it with the file it is a backup of; this way, you can compare +a file with any backup version of your choice. + +The backup file is the first file given to @code{diff}. +@end table + +@node Subdirectories in Dired +@section Subdirectories in Dired +@cindex subdirectories in Dired +@cindex expanding subdirectories in Dired + + A Dired buffer displays just one directory in the normal case; +but you can optionally include its subdirectories as well. + + The simplest way to include multiple directories in one Dired buffer is +to specify the options @samp{-lR} for running @code{ls}. (If you give a +numeric argument when you run Dired, then you can specify these options +in the minibuffer.) That produces a recursive directory listing showing +all subdirectories at all levels. + + But usually all the subdirectories are too many; usually you will +prefer to include specific subdirectories only. You can do this with +the @kbd{i} command: + +@table @kbd +@findex dired-maybe-insert-subdir +@kindex i @r{(Dired)} +@item i +@cindex inserted subdirectory (Dired) +@cindex in-situ subdirectory (Dired) +Insert the contents of a subdirectory later in the buffer. +@end table + +Use the @kbd{i} (@code{dired-maybe-insert-subdir}) command on a line +that describes a file which is a directory. It inserts the contents of +that directory into the same Dired buffer, and moves there. Inserted +subdirectory contents follow the top-level directory of the Dired +buffer, just as they do in @samp{ls -lR} output. + +If the subdirectory's contents are already present in the buffer, the +@kbd{i} command just moves to it. + +In either case, @kbd{i} sets the Emacs mark before moving, so @kbd{C-u +C-@key{SPC}} takes you back to the old position in the buffer (the line +describing that subdirectory). + +Use the @kbd{l} command (@code{dired-do-redisplay}) to update the +subdirectory's contents. Use @kbd{k} to delete the subdirectory. +@xref{Dired Updating}. + +@node Subdirectory Motion +@section Moving Over Subdirectories + + When a Dired buffer lists subdirectories, you can use the page motion +commands @kbd{C-x [} and @kbd{C-x ]} to move by entire directories. + +@cindex header line (Dired) +@cindex directory header lines + The following commands move across, up and down in the tree of +directories within one Dired buffer. They move to @dfn{directory header +lines}, which are the lines that give a directory's name, at the +beginning of the directory's contents. + +@table @kbd +@findex dired-next-subdir +@kindex C-M-n @r{(Dired)} +@item C-M-n +Go to next subdirectory header line, regardless of level +(@code{dired-next-subdir}). + +@findex dired-prev-subdir +@kindex C-M-p @r{(Dired)} +@item C-M-p +Go to previous subdirectory header line, regardless of level +(@code{dired-prev-subdir}). + +@findex dired-tree-up +@kindex C-M-u @r{(Dired)} +@item C-M-u +Go up to the parent directory's header line (@code{dired-tree-up}). + +@findex dired-tree-down +@kindex C-M-d @r{(Dired)} +@item C-M-d +Go down in the directory tree, to the first subdirectory's header line +(@code{dired-tree-down}). + +@findex dired-prev-dirline +@kindex < @r{(Dired)} +@item < +Move up to the previous directory-file line (@code{dired-prev-dirline}). +These lines are the ones that describe a directory as a file in its +parent directory. + +@findex dired-next-dirline +@kindex > @r{(Dired)} +@item > +Move down to the next directory-file line (@code{dired-prev-dirline}). +@end table + +@node Hiding Subdirectories +@section Hiding Subdirectories + +@cindex hiding in Dired (Dired) + @dfn{Hiding} a subdirectory means to make it invisible, except for its +header line, via selective display (@pxref{Selective Display}). + +@table @kbd +@item $ +@findex dired-hide-subdir +@kindex $ @r{(Dired)} +Hide or reveal the subdirectory that point is in, and move point to the +next subdirectory (@code{dired-hide-subdir}). A numeric argument serves +as a repeat count. + +@item M-$ +@findex dired-hide-all +@kindex M-$ @r{(Dired)} +Hide all subdirectories in this Dired buffer, leaving only their header +lines (@code{dired-hide-all}). Or, if any subdirectory is currently +hidden, make all subdirectories visible again. You can use this command +to get an overview in very deep directory trees or to move quickly to +subdirectories far away. +@end table + + Ordinary Dired commands never consider files inside a hidden +subdirectory. For example, the commands to operate on marked files +ignore files in hidden directories even if they are marked. Thus you +can use hiding to temporarily exclude subdirectories from operations +without having to remove the markers. + + The subdirectory hiding commands toggle; that is, they hide what was +visible, and show what was hidden. + +@node Dired Updating +@section Updating the Dired Buffer + + This section describes commands to update the Dired buffer to reflect +outside (non-Dired) changes in the directories and files, and to delete +part of the Dired buffer. + +@table @kbd +@item g +Update the entire contents of the Dired buffer (@code{revert-buffer}). + +@item l +Update the specified files (@code{dired-do-redisplay}). + +@item k +Delete the specified @emph{file lines}---not the files, just the lines +(@code{dired-do-kill-lines}). + +@item s +Toggle between alphabetical order and date/time order +(@code{dired-sort-toggle-or-edit}). + +@item C-u s @var{switches} @key{RET} +Refresh the Dired buffer using @var{switches} as +@code{dired-listing-switches}. +@end table + +@kindex g @r{(Dired)} +@findex revert-buffer @r{(Dired)} + Type @kbd{g} (@code{revert-buffer}) to update the contents of the +Dired buffer, based on changes in the files and directories listed. +This preserves all marks except for those on files that have vanished. +Hidden subdirectories are updated but remain hidden. + +@kindex l @r{(Dired)} +@findex dired-do-redisplay + To update only some of the files, type @kbd{l} +(@code{dired-do-redisplay}). This command applies to the next @var{n} +files, or to the marked files if any, or to the current file. Updating +them means reading their current status from the file system and +changing the buffer to reflect it properly. + + If you use @kbd{l} on a subdirectory header line, it updates the +contents of the corresponding subdirectory. + +@kindex k @r{(Dired)} +@findex dired-do-kill-lines + To delete the specified @emph{file lines}---not the files, just the +lines---type @kbd{k} (@code{dired-do-kill-lines}). With a numeric +argument @var{n}, this command applies to the next @var{n} files; +otherwise, it applies to the marked files. + + If you kill the line for a file that is a directory, the directory's +contents are also deleted from the buffer. Typing @kbd{C-u k} on the +header line for a subdirectory is another way to delete a subdirectory +from the Dired buffer. + + The @kbd{g} command brings back any individual lines that you have +killed in this way, but not subdirectories---you must use @kbd{i} to +reinsert each subdirectory. + +@cindex Dired sorting +@cindex sorting Dired buffer +@kindex s @r{(Dired)} +@findex dired-sort-toggle-or-edit + The files in a Dired buffers are normally listed in alphabetical order +by file names. Alternatively Dired can sort them by date/time. The +Dired command @kbd{s} (@code{dired-sort-toggle-or-edit}) switches +between these two sorting modes. The mode line in a Dired buffer +indicates which way it is currently sorted---by name, or by date. + + @kbd{C-u s @var{switches} @key{RET}} lets you specify a new value for +@code{dired-listing-switches}. + +@node Dired and Find +@section Dired and @code{find} +@cindex @code{find} and Dired + + You can select a set of files for display in a Dired buffer more +flexibly by using the @code{find} utility to choose the files. + +@findex find-name-dired + To search for files with names matching a wildcard pattern use +@kbd{M-x find-name-dired}. It reads arguments @var{directory} and +@var{pattern}, and chooses all the files in @var{directory} or its +subdirectories whose individual names match @var{pattern}. + + The files thus chosen are displayed in a Dired buffer in which the +ordinary Dired commands are available. + +@findex find-grep-dired + If you want to test the contents of files, rather than their names, +use @kbd{M-x find-grep-dired}. This command reads two minibuffer +arguments, @var{directory} and @var{regexp}; it chooses all the files in +@var{directory} or its subdirectories that contain a match for +@var{regexp}. It works by running the programs @code{find} and +@code{grep}. See also @kbd{M-x grep-find}, in @ref{Compilation}. +Remember to write the regular expression for @code{grep}, not for Emacs. + +@findex find-dired + The most general command in this series is @kbd{M-x find-dired}, which +lets you specify any condition that @code{find} can test. It takes two +minibuffer arguments, @var{directory} and @var{find-args}; it runs +@code{find} in @var{directory}, passing @var{find-args} to tell +@code{find} what condition to test. To use this command, you need to +know how to use @code{find}. + +@vindex find-ls-option + The format of listing produced by these commands is controlled by the +variable @code{find-ls-option}, whose default value specifies using +options @samp{-ld} for @code{ls}. If your listings are corrupted, you +may need to change the value of this variable. diff --git a/man/display.texi b/man/display.texi new file mode 100644 index 00000000000..9c732014a8c --- /dev/null +++ b/man/display.texi @@ -0,0 +1,397 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Display, Search, Registers, Top +@chapter Controlling the Display + + Since only part of a large buffer fits in the window, Emacs tries to +show a part that is likely to be interesting. Display-control commands +allow you to specify which part of the text you want to see, and how to +display it. + +@menu +* Scrolling:: Moving text up and down in a window. +* Horizontal Scrolling:: Moving text left and right in a window. +* Follow Mode:: Follow mode lets two windows scroll as one. +* Selective Display:: Hiding lines with lots of indentation. +* Optional Mode Line:: Optional mode line display features. +* Text Display:: How text characters are normally displayed. +* Display Vars:: Information on variables for customizing display. +@end menu + +@node Scrolling +@section Scrolling + + If a buffer contains text that is too large to fit entirely within a +window that is displaying the buffer, Emacs shows a contiguous portion of +the text. The portion shown always contains point. + +@cindex scrolling + @dfn{Scrolling} means moving text up or down in the window so that +different parts of the text are visible. Scrolling forward means that text +moves up, and new text appears at the bottom. Scrolling backward moves +text down and new text appears at the top. + + Scrolling happens automatically if you move point past the bottom or top +of the window. You can also explicitly request scrolling with the commands +in this section. + +@table @kbd +@item C-l +Clear screen and redisplay, scrolling the selected window to center +point vertically within it (@code{recenter}). +@item C-v +Scroll forward (a windowful or a specified number of lines) (@code{scroll-up}). +@item @key{NEXT} +Likewise, scroll forward. +@item M-v +Scroll backward (@code{scroll-down}). +@item @key{PRIOR} +Likewise, scroll backward. +@item @var{arg} C-l +Scroll so point is on line @var{arg} (@code{recenter}). +@item C-M-l +Scroll heuristically to bring useful information onto the screen +(@code{reposition-window}). +@end table + +@kindex C-l +@findex recenter + The most basic scrolling command is @kbd{C-l} (@code{recenter}) with +no argument. It clears the entire screen and redisplays all windows. +In addition, it scrolls the selected window so that point is halfway +down from the top of the window. + +@kindex C-v +@kindex M-v +@kindex NEXT +@kindex PRIOR +@findex scroll-up +@findex scroll-down + The scrolling commands @kbd{C-v} and @kbd{M-v} let you move all the text +in the window up or down a few lines. @kbd{C-v} (@code{scroll-up}) with an +argument shows you that many more lines at the bottom of the window, moving +the text and point up together as @kbd{C-l} might. @kbd{C-v} with a +negative argument shows you more lines at the top of the window. +@kbd{M-v} (@code{scroll-down}) is like @kbd{C-v}, but moves in the +opposite direction. The function keys @key{NEXT} and @key{PRIOR} are +equivalent to @kbd{C-v} and @kbd{M-v}. + + The names of scroll commands are based on the direction that the text +moves in the window. Thus, the command to scroll forward is called +@code{scroll-up} because it moves the text upward on the screen. + +@vindex next-screen-context-lines + To read the buffer a windowful at a time, use @kbd{C-v} with no argument. +It takes the last two lines at the bottom of the window and puts them at +the top, followed by nearly a whole windowful of lines not previously +visible. If point was in the text scrolled off the top, it moves to the +new top of the window. @kbd{M-v} with no argument moves backward with +overlap similarly. The number of lines of overlap across a @kbd{C-v} or +@kbd{M-v} is controlled by the variable @code{next-screen-context-lines}; by +default, it is 2. + +@vindex scroll-preserve-screen-position + Some users like the full-screen scroll commands to keep point at the +same screen line. To enable this behavior, set the variable +@code{scroll-preserve-screen-position} to a non-@code{nil} value. This +mode is convenient for browsing through a file by scrolling by +screenfuls; if you come back to the screen where you started, point goes +back to the line where it started. However, this mode is inconvenient +when you move to the next screen in order to move point to the text +there. + + Another way to do scrolling is with @kbd{C-l} with a numeric argument. +@kbd{C-l} does not clear the screen when given an argument; it only scrolls +the selected window. With a positive argument @var{n}, it repositions text +to put point @var{n} lines down from the top. An argument of zero puts +point on the very top line. Point does not move with respect to the text; +rather, the text and point move rigidly on the screen. @kbd{C-l} with a +negative argument puts point that many lines from the bottom of the window. +For example, @kbd{C-u - 1 C-l} puts point on the bottom line, and @kbd{C-u +- 5 C-l} puts it five lines from the bottom. Just @kbd{C-u} as argument, +as in @kbd{C-u C-l}, scrolls point to the center of the selected window. + +@kindex C-M-l +@findex reposition-window + The @kbd{C-M-l} command (@code{reposition-window}) scrolls the current +window heuristically in a way designed to get useful information onto +the screen. For example, in a Lisp file, this command tries to get the +entire current defun onto the screen if possible. + +@vindex scroll-conservatively + Scrolling happens automatically if point has moved out of the visible +portion of the text when it is time to display. Normally, automatic +scrolling centers point vertically within the window. However, if you +set @code{scroll-conservatively} to a small number @var{n}, then if you +move point just a little off the screen---less than @var{n} lines---then +Emacs scrolls the text just far enough to bring point back on screen. +By default, @code{scroll-conservatively} is 0. + +@vindex scroll-margin + The variable @code{scroll-margin} restricts how close point can come +to the top or bottom of a window. Its value is a number of screen +lines; if point comes within that many lines of the top or bottom of the +window, Emacs recenters the window. By default, @code{scroll-margin} is +0. + +@node Horizontal Scrolling +@section Horizontal Scrolling +@cindex horizontal scrolling + + @dfn{Horizontal scrolling} means shifting all the lines sideways +within a window---so that some of the text near the left margin +is not displayed at all. + +@table @kbd +@item C-x < +Scroll text in current window to the left (@code{scroll-left}). +@item C-x > +Scroll to the right (@code{scroll-right}). +@end table + + When a window has been scrolled horizontally, text lines are truncated +rather than continued (@pxref{Continuation Lines}), with a @samp{$} +appearing in the first column when there is text truncated to the left, +and in the last column when there is text truncated to the right. + +@kindex C-x < +@kindex C-x > +@findex scroll-left +@findex scroll-right + The command @kbd{C-x <} (@code{scroll-left}) scrolls the selected +window to the left by @var{n} columns with argument @var{n}. This moves +part of the beginning of each line off the left edge of the window. +With no argument, it scrolls by almost the full width of the window (two +columns less, to be precise). + + @kbd{C-x >} (@code{scroll-right}) scrolls similarly to the right. The +window cannot be scrolled any farther to the right once it is displayed +normally (with each line starting at the window's left margin); +attempting to do so has no effect. This means that you don't have to +calculate the argument precisely for @w{@kbd{C-x >}}; any sufficiently large +argument will restore the normal display. + +@cindex Hscroll mode +@cindex mode, Hscroll +@findex hscroll-mode + You can request automatic horizontal scrolling by enabling Hscroll +mode. When this mode is enabled, Emacs scrolls a window horizontally +whenever that is necessary to keep point visible and not too far from +the left or right edge. The command to enable or disable this mode is +@kbd{M-x hscroll-mode}. + +@node Follow Mode +@section Follow Mode +@cindex Follow mode +@cindex mode, Follow + + @dfn{Follow mode} is a minor mode that makes two windows showing the +same buffer scroll as one tall ``virtual window.'' To use Follow mode, +go to a frame with just one window, split it into two side-by-side +windows using @kbd{C-x 3}, and then type @kbd{M-x follow-mode}. From +then on, you can edit the buffer in either of the two windows, or scroll +either one; the other window follows it. + + To turn off Follow mode, type @kbd{M-x follow-mode} a second time. + +@node Selective Display +@section Selective Display +@findex set-selective-display +@kindex C-x $ + + Emacs has the ability to hide lines indented more than a certain number +of columns (you specify how many columns). You can use this to get an +overview of a part of a program. + + To hide lines, type @kbd{C-x $} (@code{set-selective-display}) with a +numeric argument @var{n}. Then lines with at least @var{n} columns of +indentation disappear from the screen. The only indication of their +presence is that three dots (@samp{@dots{}}) appear at the end of each +visible line that is followed by one or more hidden ones. + + The commands @kbd{C-n} and @kbd{C-p} move across the hidden lines as +if they were not there. + + The hidden lines are still present in the buffer, and most editing +commands see them as usual, so you may find point in the middle of the +hidden text. When this happens, the cursor appears at the end of the +previous line, after the three dots. If point is at the end of the +visible line, before the newline that ends it, the cursor appears before +the three dots. + + To make all lines visible again, type @kbd{C-x $} with no argument. + +@vindex selective-display-ellipses + If you set the variable @code{selective-display-ellipses} to +@code{nil}, the three dots do not appear at the end of a line that +precedes hidden lines. Then there is no visible indication of the +hidden lines. This variable becomes local automatically when set. + +@node Optional Mode Line +@section Optional Mode Line Features + +@cindex Line Number mode +@cindex mode, Line Number +@findex line-number-mode + The current line number of point appears in the mode line when Line +Number mode is enabled. Use the command @kbd{M-x line-number-mode} to +turn this mode on and off; normally it is on. The line number appears +before the buffer percentage @var{pos}, with the letter @samp{L} to +indicate what it is. @xref{Minor Modes}, for more information about +minor modes and about how to use this command. + +@vindex line-number-display-limit + If the buffer is very large (larger than the value of +@code{line-number-display-limit}), then the line number doesn't appear. +Emacs doesn't compute the line number when the buffer is large, because +that would be too slow. If you have narrowed the buffer +(@pxref{Narrowing}), the displayed line number is relative to the +accessible portion of the buffer. + +@cindex Column Number mode +@cindex mode, Column Number +@findex column-number-mode + You can also display the current column number by turning on Column +Number mode. It displays the current column number preceded by the +letter @samp{C}. Type @kbd{M-x column-number-mode} to toggle this mode. + +@findex display-time +@cindex time (on mode line) + Emacs can optionally display the time and system load in all mode +lines. To enable this feature, type @kbd{M-x display-time}. The +information added to the mode line usually appears after the buffer +name, before the mode names and their parentheses. It looks like this: + +@example +@var{hh}:@var{mm}pm @var{l.ll} +@end example + +@noindent +@vindex display-time-24hr-format +Here @var{hh} and @var{mm} are the hour and minute, followed always by +@samp{am} or @samp{pm}. @var{l.ll} is the average number of running +processes in the whole system recently. (Some fields may be missing if +your operating system cannot support them.) If you prefer time display +in 24-hour format, set the variable @code{display-time-24hr-format} +to @code{t}. + +@cindex mail (on mode line) + The word @samp{Mail} appears after the load level if there is mail +for you that you have not read yet. + +@node Text Display +@section How Text Is Displayed +@cindex characters (in text) + + ASCII printing characters (octal codes 040 through 0176) in Emacs +buffers are displayed with their graphics. So are non-ASCII multibyte +printing characters (octal codes above 0400). + + Some ASCII control characters are displayed in special ways. The +newline character (octal code 012) is displayed by starting a new line. +The tab character (octal code 011) is displayed by moving to the next +tab stop column (normally every 8 columns). + + Other ASCII control characters are normally displayed as a caret +(@samp{^}) followed by the non-control version of the character; thus, +control-A is displayed as @samp{^A}. + + Non-ASCII characters 0200 through 0377 are displayed with octal escape +sequences; thus, character code 0243 (octal) is displayed as +@samp{\243}. However, if you enable European display, most of these +characters become non-ASCII printing characters, and are displayed using +their graphics (assuming your terminal supports them). +@xref{Single-Byte European Support}. + +@node Display Vars +@section Variables Controlling Display + + This section contains information for customization only. Beginning +users should skip it. + +@vindex mode-line-inverse-video + The variable @code{mode-line-inverse-video} controls whether the mode +line is displayed in inverse video (assuming the terminal supports it); +@code{nil} means don't do so. @xref{Mode Line}. If you specify the +foreground color for the @code{modeline} face, and +@code{mode-line-inverse-video} is non-@code{nil}, then the default +background color for that face is the usual foreground color. +@xref{Faces}. + +@vindex inverse-video + If the variable @code{inverse-video} is non-@code{nil}, Emacs attempts +to invert all the lines of the display from what they normally are. + +@vindex visible-bell + If the variable @code{visible-bell} is non-@code{nil}, Emacs attempts +to make the whole screen blink when it would normally make an audible bell +sound. This variable has no effect if your terminal does not have a way +to make the screen blink.@refill + +@vindex no-redraw-on-reenter + When you reenter Emacs after suspending, Emacs normally clears the +screen and redraws the entire display. On some terminals with more than +one page of memory, it is possible to arrange the termcap entry so that +the @samp{ti} and @samp{te} strings (output to the terminal when Emacs +is entered and exited, respectively) switch between pages of memory so +as to use one page for Emacs and another page for other output. Then +you might want to set the variable @code{no-redraw-on-reenter} +non-@code{nil}; this tells Emacs to assume, when resumed, that the +screen page it is using still contains what Emacs last wrote there. + +@vindex echo-keystrokes + The variable @code{echo-keystrokes} controls the echoing of multi-character +keys; its value is the number of seconds of pause required to cause echoing +to start, or zero meaning don't echo at all. @xref{Echo Area}. + +@vindex ctl-arrow + If the variable @code{ctl-arrow} is @code{nil}, control characters in +the buffer are displayed with octal escape sequences, except for newline +and tab. Altering the value of @code{ctl-arrow} makes it local to the +current buffer; until that time, the default value is in effect. The +default is initially @code{t}. @xref{Display Tables,, Display Tables, +elisp, The Emacs Lisp Reference Manual}. + +@vindex tab-width + Normally, a tab character in the buffer is displayed as whitespace which +extends to the next display tab stop position, and display tab stops come +at intervals equal to eight spaces. The number of spaces per tab is +controlled by the variable @code{tab-width}, which is made local by +changing it, just like @code{ctl-arrow}. Note that how the tab character +in the buffer is displayed has nothing to do with the definition of +@key{TAB} as a command. The variable @code{tab-width} must have an +integer value between 1 and 1000, inclusive. + +@c @vindex truncate-lines @c No index entry here, because we have one +@c in the continuation section. + If the variable @code{truncate-lines} is non-@code{nil}, then each +line of text gets just one screen line for display; if the text line is +too long, display shows only the part that fits. If +@code{truncate-lines} is @code{nil}, then long text lines display as +more than one screen line, enough to show the whole text of the line. +@xref{Continuation Lines}. Altering the value of @code{truncate-lines} +makes it local to the current buffer; until that time, the default value +is in effect. The default is initially @code{nil}. + +@c @vindex truncate-partial-width-windows @c Idx entry is in Split Windows. + If the variable @code{truncate-partial-width-windows} is +non-@code{nil}, it forces truncation rather than continuation in any +window less than the full width of the screen or frame, regardless of +the value of @code{truncate-lines}. For information about side-by-side +windows, see @ref{Split Window}. See also @ref{Display,, Display, +elisp, The Emacs Lisp Reference Manual}. + +@vindex baud-rate + The variable @code{baud-rate} holds the output speed of the +terminal, as far as Emacs knows. Setting this variable does not change +the speed of actual data transmission, but the value is used for +calculations such as padding. It also affects decisions about whether +to scroll part of the screen or redraw it instead---even when using a +window system. (We designed it this way, despite the fact that a window +system has no true ``output speed,'' to give you a way to tune these +decisions.) + + You can customize the way any particular character code is displayed +by means of a display table. @xref{Display Tables,, Display Tables, +elisp, The Emacs Lisp Reference Manual}. diff --git a/man/ediff.texi b/man/ediff.texi new file mode 100644 index 00000000000..a2eefa9f16a --- /dev/null +++ b/man/ediff.texi @@ -0,0 +1,2275 @@ +\input texinfo @c -*-texinfo-*- +@c documentation for Ediff +@c Written by Michael Kifer + +@comment %**start of header (This is for running Texinfo on a region.) + +@comment Using ediff.info instead of ediff in setfilename breaks DOS. +@comment @setfilename ediff +@comment @setfilename ediff.info +@setfilename ../info/ediff + +@settitle Ediff User's Manual +@synindex vr cp +@synindex fn cp +@synindex pg cp + +@dircategory Editors +@direntry +* Ediff: (ediff). A visual interface for comparing and merging programs. +@end direntry + +@iftex +@finalout +@end iftex +@c @smallbook +@comment %**end of header (This is for running Texinfo on a region.) + +@ifinfo +This file documents Ediff, a comprehensive visual interface to Unix diff +and patch utilities. + +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 + +@iftex +@titlepage +@title Ediff User's Manual +@sp 4 +@subtitle Ediff version 2.70 +@sp 1 +@subtitle March 1998 +@sp 5 +@author Michael Kifer +@page + +@vskip 0pt plus 1filll +@noindent +Copyright @copyright{} 1995, 1996, 1997 Free Software Foundation, Inc. + +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 +@end iftex + +@node Top, Introduction, (dir), (dir) + + +@menu +* Introduction:: About Ediff. +* Major Entry Points:: How to use Ediff. +* Session Commands:: Ediff commands used within a session. +* Registry of Ediff Sessions:: Keeping track of multiple Ediff sessions. +* Session Groups:: Comparing and merging directories. +* Remote and Compressed Files:: You may want to know about this. +* Customization:: How to make Ediff work the way YOU want. +* Credits:: Thanks to those who helped. +* Index:: +@end menu + +@node Introduction, Major Entry Points, Top, Top +@chapter Introduction + +@cindex Comparing files and buffers +@cindex Merging files and buffers +@cindex Patching files and buffers +@cindex Finding differences + +Ediff provides a convenient way for simultaneous browsing through +the differences between a pair (or a triple) of files or buffers +(which are called @samp{variants} for our purposes). The +files being compared, file-A, file-B, and file-C (if applicable) are +shown in separate windows (side by side, one above the another, or in +separate frames), and the differences are highlighted as you step +through them. You can also copy difference regions from one buffer to +another (and recover old differences if you change your mind). + +Another powerful feature is the ability to merge a pair of files into a +third buffer. Merging with an ancestor file is also supported. +Furthermore, Ediff is equipped with directory-level capabilities that +allow the user to conveniently launch browsing or merging sessions on +groups of files in two (or three) different directories. + +In addition, Ediff can apply a patch to a file and then let you step though +both files, the patched and the original one, simultaneously, +difference-by-difference. You can even apply a patch right out of a mail +buffer, i.e., patches received by mail don't even have to be saved. Since +Ediff lets you copy differences between variants, you can, in effect, apply +patches selectively (i.e., you can copy a difference region from +@file{file.orig} to @file{file}, thereby undoing any particular patch that +you don't like). + +Ediff even understands multi-file patches and can apply them interactively! +(Ediff can recognize multi-file patches only if they are in the context +format or GNU unified format. All other patches are treated as 1-file +patches. Ediff is [hopefully] using the same algorithm as @file{patch} to +determine which files need to be patched.) + +Ediff is aware of version control, which lets you compare +files with their older versions. Ediff also works with remote and +compressed files, automatically ftp'ing them over and uncompressing them. +@xref{Remote and Compressed Files}, for details. + +This package builds upon ideas borrowed from Emerge, and several of Ediff's +functions are adaptations from Emerge. Although Ediff subsumes and greatly +extends Emerge, much of the functionality in Ediff is influenced by Emerge. +The architecture and the interface are, of course, drastically different. + +@node Major Entry Points, Session Commands, Introduction, Top +@chapter Major Entry Points + +Ediff can be invoked interactively using the following functions, which can +be run either from the minibuffer or from the menu bar. In the menu bar, +all Ediff's entry points belong to three submenus of the Tools menu: +Compare, Merge, and Apply Patch. + +@table @code +@item ediff-files +@itemx ediff +@findex ediff-files +@findex ediff +Compare two files. + +@item ediff-buffers +@findex ediff-buffers +Compare two buffers. + +@item ediff-files3 +@itemx ediff3 +@findex ediff-files3 +@findex ediff3 +Compare three files. + +@item ediff-buffers3 +@findex ediff-buffers3 +Compare three buffers. + +@item edirs +@itemx ediff-directories +@findex edirs +@findex ediff-directories + Compare files common to two directories. +@item edirs3 +@itemx ediff-directories3 +@findex edirs3 +@findex ediff-directories3 + Compare files common to three directories. +@item edir-revisions +@itemx ediff-directory-revisions +@findex ediff-directory-revisions +@findex edir-revisions + Compare versions of files in a given directory. Ediff selects only the +files that are under version control. +@item edir-merge-revisions +@itemx ediff-merge-directory-revisions +@findex edir-merge-revisions +@findex ediff-merge-directory-revisions + Merge versions of files in a given directory. Ediff selects only the +files that are under version control. +@item edir-merge-revisions-with-ancestor +@itemx ediff-merge-directory-revisions-with-ancestor +@findex edir-merge-revisions-with-ancestor +@findex ediff-merge-directory-revisions-with-ancestor + Merge versions of files in a given directory using other versions as +ancestors. Ediff selects only the files that are under version control. + +@item ediff-windows-wordwise +@findex ediff-windows-wordwise +Compare windows word-by-word. + +@item ediff-windows-linewise +@findex ediff-windows-linewise +Compare windows line-by-line. + +@item ediff-regions-wordwise +@findex ediff-regions-wordwise +Compare regions word-by-word. + +@item ediff-regions-linewise +@findex ediff-regions-linewise +Compare regions line-by-line. + +@item ediff-revision +@findex ediff-revision + Compare versions of the current buffer, if the buffer is visiting + a file under version control. + +@item ediff-patch-file +@itemx epatch +@findex ediff-patch-file +@findex epatch + +Patch a file or multiple files, then compare. If the patch applies to just +one file, Ediff will invoke a regular comparison session. If it is a +multi-file patch, then a session group interface will be used and the user +will be able to patch the files selectively. @xref{Session Groups}, for +more details. + +Note that @code{ediff-patch-file} will actually use the @file{patch} +utility to change the the original files on disk. This is not that +dangerous, since you will always have the original contents of the file +saved in another file that has the extension @file{.orig}. +Furthermore, if the file is under version control, then you can always back +out to one of the previous versions (see the section on Version Countrol in +Emacs manual). + +@code{ediff-patch-file} is careful about versions control: if the file +to be patched is checked in, then Ediff will offer to check it out, because +failing to do so may result in the loss of the changes when the file is +checked out the next time. + +If you don't intend to modify the file via the patch and just want to see +what the patch is all about (and decide later), then +@code{ediff-patch-buffer} might be a better choice. + +@item ediff-patch-buffer +@itemx epatch-buffer +@findex ediff-patch-buffer +@findex epatch-buffer +Patch a buffer, then compare. The buffer being patched and the file visited +by that buffer (if any) is @emph{not} modified. The result of the patch +appears in some other buffer that has the name ending with @emph{_patched}. + +This function would refuse to apply a multifile patch to a buffer. Use +@code{ediff-patch-file} for that (and when you want the original file to be +modified by the @file{patch} utility). + +@item ediff-merge-files +@itemx ediff-merge +@findex ediff-merge-files +@findex ediff-merge +Merge two files. + +@item ediff-merge-files-with-ancestor +@itemx ediff-merge-with-ancestor +@findex ediff-merge-files-with-ancestor +@findex ediff-merge-with-ancestor +Like @code{ediff-merge}, but with a third ancestor file. + +@item ediff-merge-buffers +@findex ediff-merge-buffers +Merge two buffers. + +@item ediff-merge-buffers-with-ancestor +@findex ediff-merge-buffers-with-ancestor +Same but with ancestor. + + +@item edirs-merge +@itemx ediff-merge-directories +@findex edirs-merge +@findex ediff-merge-directories + Merge files common to two directories. +@item edirs-merge-with-ancestor +@itemx ediff-merge-directories-with-ancestor +@findex edirs-merge-with-ancestor +@findex ediff-merge-directories-with-ancestor + Same but using files in a third directory as ancestors. + If a pair of files doesn't have an ancestor in the ancestor-directory, you + will still be able to merge them without the ancestor. + +@item ediff-merge-revisions +@findex ediff-merge-revisions +Merge two versions of the file visited by the current buffer. + +@item ediff-merge-revisions-with-ancestor +@findex ediff-merge-revisions-with-ancestor +Same but with ancestor. + +@item ediff-documentation +@findex ediff-documentation +Brings up this manual. + +@item ediff-show-registry +@itemx eregistry +Brings up Ediff session registry. This feature enables you to quickly find +and restart active Ediff sessions. +@end table + +@noindent +If you want Ediff to be loaded from the very beginning of your Emacs +session, you should put this line in your @file{~/.emacs} file: + +@example +(require 'ediff) +@end example + +@noindent +Otherwise, Ediff will be loaded automatically when you use one of the +above functions, either directly or through the menus. + +When the above functions are invoked, the user is prompted for all the +necessary information---typically the files or buffers to compare, merge, or +patch. Ediff tries to be smart about these prompts. For instance, in +comparing/merging files, it will offer the visible buffers as defaults. In +prompting for files, if the user enters a directory, the previously input +file name will be appended to that directory. In addition, if the variable +@code{ediff-use-last-dir} is not @code{nil}, Ediff will offer +previously entered directories as defaults (which will be maintained +separately for each type of file, A, B, or C). +@vindex @code{ediff-use-last-dir} + +All the above functions use the POSIX @code{diff} or @code{diff3} programs +to find differences between two files. They process the @code{diff} output +and display it in a convenient form. At present, Ediff understands only +the plain output from diff. Options such as @samp{-c} are not supported, +nor is the format produced by incompatible file comparison programs such as +the VMS version of @code{diff}. + +The functions @code{ediff-files}, @code{ediff-buffers}, +@code{ediff-files3}, @code{ediff-buffers3} first display the coarse, +line-based difference regions, as reported by the @file{diff} program. The +total number of difference regions and the current difference number are +always displayed in the mode line of the control window. + +Since @code{diff} may report fairly large chunks of text as being different, +even though the difference may be localized to just a few words or even +to the white space or line breaks, Ediff further @emph{refines} the +regions to indicate which exact words differ. If the only difference is +in the white space and line breaks, Ediff says so. + +On a color display, fine differences are highlighted with color; on a +monochrome display, they are underlined. @xref{Highlighting Difference +Regions}, for information on how to customize this. + +The functions @code{ediff-windows-wordwise}, +@code{ediff-windows-linewise}, @code{ediff-regions-wordwise} and +@code{ediff-regions-linewise} do comparison on parts of existing Emacs +buffers. Since @code{ediff-windows-wordwise} and +@code{ediff-regions-wordwise} are intended for relatively small segments +of buffers, comparison is done on the basis of words rather than lines. +No refinement is necessary in this case. These commands are recommended +only for relatively small regions (perhaps, up to 100 lines), because +these functions have a relatively slow startup. + +To compare large regions, use @code{ediff-regions-linewise}. This +command displays differences much like @code{ediff-files} and +@code{ediff-buffers}. + +The functions @code{ediff-patch-file} and @code{ediff-patch-buffer} apply a +patch to a file or a buffer and then run Ediff on the appropriate +files/buffers, displaying the difference regions. + +The entry points @code{ediff-directories}, @code{ediff-merge-directories}, +etc., provide a convenient interface for comparing and merging files in +different directories. The user is presented with Dired-like interface from +which one can run a group of related Ediff sessions. + +For files under version control, @code{ediff-revision} lets you compare +the file visited by the current buffer to one of its checked-in versions. +You can also compare two checked-in versions of the visited file. +Moreover, the functions @code{ediff-directory-revisions}, +@code{ediff-merge-directory-revisions}, etc., let you run a group of +related Ediff sessions by taking a directory and comparing (or merging) +versions of files in that directory. + +@node Session Commands, Registry of Ediff Sessions, Major Entry Points, Top +@chapter Session Commands + +All Ediff commands are displayed in a Quick Help window, unless you type +@kbd{?} to shrink the window to just one line. You can redisplay the help +window by typing @kbd{?} again. The Quick Help commands are detailed below. + +Many Ediff commands take numeric prefix arguments. For instance, if you +type a number, say 3, and then @kbd{j} (@code{ediff-jump-to-difference}), +Ediff moves to the third difference region. Typing 3 and then @kbd{a} +(@code{ediff-diff-to-diff}) copies the 3d difference region from variant A +to variant B. Likewise, 4 followed by @kbd{ra} restores the 4th difference +region in buffer A (if it was previously written over via the command +@kbd{a}). + +Some commands take negative prefix arguments as well. For instance, typing +@kbd{-} and then @kbd{j} will make the last difference region +current. Typing @kbd{-2} then @kbd{j} makes the penultimate difference +region current, etc. + +Without the prefix argument, all commands operate on the currently +selected difference region. You can make any difference region +current using the various commands explained below. + +For some commands, the actual value of the prefix argument is +immaterial. However, if supplied, the prefix argument may modify the +command (see @kbd{ga}, @kbd{gb}, and @kbd{gc}). + +@menu +* Quick Help Commands:: Frequently used commands. +* Other Session Commands:: Commands that are not bound to keys. +@end menu + +@node Quick Help Commands,Other Session Commands,,Session Commands +@section Quick Help Commands + +@table @kbd +@item ? +Toggles the Ediff Quick Help window ON and OFF. +@item G +Prepares a mail buffer for sending a praise or a curse to the Ediff maintainer. + +@item E +Brings up the top node of this manual, where you can find further +information on the various Ediff functions and advanced issues, such as +customization, session groups, etc. + +@item v +Scrolls up buffers A and B (and buffer C where appropriate) in a +coordinated fashion. +@item V +Scrolls the buffers down. + +@item < +Scrolls the buffers to the left simultaneously. +@item > +Scrolls buffers to the right. + +@item wd +Saves the output from the diff utility, for further reference. + +With prefix argument, saves the plain output from @file{diff} (see +@code{ediff-diff-program} and @code{ediff-diff-options}). Without the +argument, it saves customized @file{diff} output (see +@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options}), if +it is available. + +@item wa +Saves buffer A, if it was modified. +@item wb +Saves buffer B, if it was modified. +@item wc +Saves buffer C, if it was modified (if you are in a session that +compares three files simultaneously). + +@item a +@emph{In comparison sessions:} +Copies the current difference region (or the region specified as the prefix +to this command) from buffer A to buffer B. +Ediff saves the old contents of buffer B's region; it can +be restored via the command @kbd{rb}, which see. + +@emph{In merge sessions:} +Copies the current difference region (or the region specified as the prefix +to this command) from buffer A to the merge buffer. The old contents of +this region in buffer C can be restored via the command @kbd{r}. + +@item b +Works similarly, but copies the current difference region from buffer B to +buffer A (in @emph{comparison sessions}) or the merge buffer (in +@emph{merge sessions}). + +Ediff saves the old contents of the difference region copied over; it can +be reinstated via the command @kbd{ra} in comparison sessions and +@kbd{r} in merge sessions. + +@item ab +Copies the current difference region (or the region specified as the prefix +to this command) from buffer A to buffer B. This (and the next five) +command is enabled only in sessions that compare three files +simultaneously. The old region in buffer B is saved and can be restored +via the command @kbd{rb}. +@item ac +Copies the difference region from buffer A to buffer C. +The old region in buffer C is saved and can be restored via the command +@kbd{rc}. +@item ba +Copies the difference region from buffer B to buffer A. +The old region in buffer A is saved and can be restored via the command +@kbd{ra}. +@item bc +Copies the difference region from buffer B to buffer C. +The command @kbd{rc} undoes this. +@item ca +Copies the difference region from buffer C to buffer A. +The command @kbd{ra} undoes this. +@item cb +Copies the difference region from buffer C to buffer B. +The command @kbd{rb} undoes this. + +@item p +@itemx DEL +Makes the previous difference region current. +@item n +@itemx SPC +Makes the next difference region current. + +@item j +@itemx -j +@itemx Nj +Makes the very first difference region current. + +@kbd{-j} makes the last region current. Typing a number, N, and then `j' +makes the difference region N current. Typing -N (a negative number) then +`j' makes current the region Last - N. + +@item ga +Makes current the difference region closest to the position of the point in +buffer A. + +However, with a prefix argument, Ediff would position all variants +around the area indicated by the current point in buffer A: if +the point is inside a difference region, then the variants will be +positioned at this difference region. If the point is not in any difference +region, then it is in an area where all variants agree with each other. In +this case, the variants will be positioned so that each would display this +area (of agreement). +@item gb +Makes current the difference region closest to the position of the point in +buffer B. + +With a prefix argument, behaves like @kbd{ga}, but with respect to buffer B. +@item gc +@emph{In merge sessions:} +makes current the difference region closest to the point in the merge buffer. + +@emph{In 3-file comparison sessions:} +makes current the region closest to the point in buffer C. + +With a prefix argument, behaves like @kbd{ga}, but with respect to buffer C. + +@item ! +Recomputes the difference regions, bringing them up to date. This is often +needed because it is common to do all sorts of editing during Ediff +sessions, so after a while, the highlighted difference regions may no +longer reflect the actual differences among the buffers. + +@item * +Forces refinement of the current difference region, which highlights the exact +words of disagreement among the buffers. With a negative prefix argument, +unhighlights the current region. + +Forceful refinement may be needed if Ediff encounters a difference region +that is larger than @code{ediff-auto-refine-limit}. In this situation, +Ediff doesn't do automatic refinement in order to improve response time. +(Ediff doesn't auto-refine on dumb terminals as well, but @kbd{*} still +works there. However, the only useful piece of information it can tell you +is whether or not the difference regions disagree only in the amount of +white space.) + +This command is also useful when the highlighted fine differences are +no longer current, due to user editing. + +@item m +Displays the current Ediff session in a frame as wide as the physical +display. This is useful when comparing files side-by-side. Typing `m' again +restores the original size of the frame. + +@item | +Toggles the horizontal/vertical split of the Ediff display. Horizontal +split is convenient when it is possible to compare files +side-by-side. If the frame in which files are displayed is too narrow +and lines are cut off, typing @kbd{m} may help some. + +@item @@ +Toggles auto-refinement of difference regions (i.e., automatic highlighting +of the exact words that differ among the variants). Auto-refinement is +turned off on devices where Emacs doesn't support highlighting. + +On slow machines, it may be advantageous to turn auto-refinement off. The +user can always forcefully refine specific difference regions by typing +@kbd{*}. + +@item h +Cycles between full highlighting, the mode where fine differences are not +highlighted (but computed), and the mode where highlighting is done with +ASCII strings. The latter is not really recommended, unless on a dumb TTY. + +@item r +Restores the old contents of the region in the merge buffer. +(If you copied a difference region from buffer A or B into the merge buffer +using the commands @kbd{a} or @kbd{b}, Ediff saves the old contents of the +region in case you change your mind.) + +This command is enabled in merge sessions only. + +@item ra +Restores the old contents of the current difference region in buffer A, +which was previously saved when the user invoked one of these commands: +@kbd{b}, @kbd{ba}, @kbd{ca}, which see. This command is enabled in +comparison sessions only. +@item rb +Restores the old contents of the current difference region in buffer B, +which was previously saved when the user invoked one of these commands: +@kbd{a}, @kbd{ab}, @kbd{cb}, which see. This command is enabled in +comparison sessions only. +@item rc +Restores the old contents of the current difference region in buffer C, +which was previously saved when the user invoked one of these commands: +@kbd{ac}, @kbd{bc}, which see. This command is enabled in 3-file +comparison sessions only. + +@item ## +Tell Ediff to skip over regions that disagree among themselves only in the +amount of white space and line breaks. + +Even though such regions will be skipped over, you can still jump to any +one of them by typing the region number and then `j'. Typing @kbd{##} +again puts Ediff back in the original state. + +@item #h +@itemx #f +Ediff works hard to ameliorate the effects of boredom in the workplace... + +Quite often differences are due to identical replacements (e.g., the word +`foo' is replaced with the word `bar' everywhere). If the number of regions +with such boring differences exceeds your tolerance threshold, you may be +tempted to tell Ediff to skip these regions altogether (you will still be able +to jump to them via the command @kbd{j}). The above commands, @kbd{#h} +and @kbd{#f}, may well save your day! + +@kbd{#h} prompts you to specify regular expressions for each +variant. Difference regions where each variant's region matches the +corresponding regular expression will be skipped from then on. (You can +also tell Ediff to skip regions where at least one variant matches its +regular expression.) + +@kbd{#f} does dual job: it focuses on regions that match the corresponding +regular expressions. All other regions will be skipped +over. @xref{Selective Browsing}, for more. + +@item A +Toggles the read-only property in buffer A. +If file A is under version control and is checked in, it is checked out +(with your permission). +@item B +Toggles the read-only property in buffer B. +If file B is under version control and is checked in, it is checked out. +@item C +Toggles the read-only property in buffer C (in 3-file comparison sessions). +If file C is under version control and is checked in, it is checked out. + +@item ~ +Swaps the windows where buffers A and B are displayed. If you are comparing +three buffers at once, then this command would rotate the windows among +buffers A, B, and C. + +@item i +Displays all kinds of useful data about the current Ediff session. +@item D +Runs @code{ediff-custom-diff-program} on the variants and displays the +buffer containing the output. This is useful when you must send the output +to your Mom. + +With a prefix argument, displays the plain @file{diff} output. +@xref{Patch and Diff Programs}, for details. + +@item R +Displays a list of currently active Ediff sessions---the Ediff Registry. +You can then restart any of these sessions by either clicking on a session +record or by putting the cursor over it and then typing the return key. + +(Some poor souls leave so many active Ediff sessions around that they loose +track of them completely... The `R' command is designed to save these +people from the recently discovered Ediff Proficiency Syndrome.) + +Typing @kbd{R} brings up Ediff Registry only if it is typed into an Ediff +Control Panel. If you don't have a control panel handy, type this in the +minibuffer: @kbd{M-x eregistry}. @xref{Registry of Ediff Sessions}. + +@item M +Shows the session group buffer that invoked the current Ediff session. +@xref{Session Groups}, for more information on session groups. + +@item z +Suspends the current Ediff session. (If you develop a condition known as +Repetitive Ediff Injury---a serious but curable illness---you must change +your current activity. This command tries hard to hide all Ediff-related +buffers.) + +The easiest way to resume a suspended Ediff session is through the registry +of active sessions. @xref{Registry of Ediff Sessions}, for details. +@item q +Terminates this Ediff session. With a prefix argument (e.g.,@kbd{1q}), asks +if you also want to delete the buffers of the variants. +Modified files and the results of merges are never deleted. + +@item % +Toggles narrowing in Ediff buffers. Ediff buffers may be narrowed if you +are comparing only parts of these buffers via the commands +@code{ediff-windows-*} and @code{ediff-regions-*}, which see. + +@item C-l +Restores the usual Ediff window setup. This is the quickest way to resume +an Ediff session, but it works only if the control panel of that session is +visible. + +@item $ +While merging with an ancestor file, Ediff is determined to reduce user's +wear and tear by saving him and her much of unproductive, repetitive +typing. If it notices that, say, file A's difference region is identical to +the same difference region in the ancestor file, then the merge buffer will +automatically get the difference region taken from buffer B. The rationale +is that this difference region in buffer A is as old as that in the +ancestor buffer, so the contents of that region in buffer B represents real +change. + +You may want to ignore such `obvious' merges and concentrate on difference +regions where both files `clash' with the ancestor, since this means that +two different people have been changing this region independently and they +had different ideas on how to do this. + +The above command does this for you by skipping the regions where only one +of the variants clashes with the ancestor but the other variant agrees with +it. Typing @kbd{$} again undoes this setting. + +@item / +Displays the ancestor file during merges. +@item & +In some situations, such as when one of the files agrees with the ancestor file +on a difference region and the other doesn't, Ediff knows what to do: it copies +the current difference region from the second buffer into the merge buffer. + +In other cases, the right course of action is not that clearcut, and Ediff +would use a default action. The above command changes the default action. +The default action can be @samp{default-A} (choose the region from buffer +A), @samp{default-B} (choose the region from buffer B), or @samp{combined} +(combine the regions from the two buffers). +@xref{Merging and diff3}, for further details. + +The command @kbd{&} also affects the regions in the merge buffers that have +@samp{default-A}, @samp{default-B}, or @samp{combined} status, provided +they weren't changed with respect to the original. For instance, if such a +region has the status @samp{default-A} then changing the default action to +@samp{default-B} will also replace this merge-buffer's region with the +corresponding region from buffer B. + +@item s +Causes the merge window shrink to its minimum size, thereby exposing as much +of the variant buffers as possible. Typing `s' again restores +the original size of that window. + +With a positive prefix argument, this command enlarges the merge window. +E.g., @kbd{4s} increases the size of the window by about 4 lines, if +possible. With a negative numeric argument, the size of the merge window +shrinks by that many lines, if possible. Thus, @kbd{-s} shrinks the window +by about 1 line and @kbd{-3s} by about 3 lines. + +This command is intended only for temporary viewing; therefore, Ediff +restores window C to its original size whenever it makes any other change +in the window configuration. However, redisplaying (@kbd{C-l}) or jumping +to another difference does not affect window C's size. + +The split between the merge window and the variant windows is controlled by +the variable @code{ediff-merge-window-share}, which see. + +@item + +Combines the difference regions from buffers A and B and copies the +result into the merge buffer. @xref{Merging and diff3}, and the +variables @code{ediff-combine-diffs} and @code{ediff-combination-pattern}. + + +@item = +You may run into situations when a large chunk of text in one file has been +edited and then moved to a different place in another file. In such a case, +these two chunks of text are unlikely to belong to the same difference +region, so the refinement feature of Ediff will not be able to tell you +what exactly differs inside these chunks. Since eyeballing large pieces of +text is contrary to human nature, Ediff has a special command to help +reduce the risk of developing a cataract. + +The above command compares regions within Ediff buffers. This creates a +child Ediff session for comparing current Emacs regions in buffers A, B, or +C as follows: + +@emph{If you are comparing 2 files or buffers:} +Ediff would compare current Emacs regions in buffers A and B. + +@emph{If you are comparing 3 files or buffers simultaneously:} Ediff would +compare the current Emacs regions in the buffers of your choice (you will +be asked which two of the three buffers to use). + +@emph{If you are merging files or buffers (with or without ancestor):} +Ediff would take the current region in the merge buffer and compare +it to the current region in the buffer of your choice (A or B). + +Highlighting set by the parent Ediff session is removed, to avoid interference +with highlighting of the child session. When done with the child session, type +@kbd{C-l} in the parent's control panel to restore the original highlighting. + +If you temporarily switch to the parent session, parent highlighting will be +restored. If you then come back to the child session, you may want to remove +parent highlighting, so it won't interfere. Typing @kbd{h} may help here. + +@end table + +@node Other Session Commands,,Quick Help Commands,Session Commands +@section Other Session Commands + +The following commands can be invoked from within any Ediff session, +although some of them are not bound to a key. + +@table @code +@item eregistry +@itemx ediff-show-registry +@findex eregistry +@findex ediff-show-registry +This command brings up the registry of active Ediff sessions. Ediff +registry is a device that can be used to resume any active Ediff session +(which may have been postponed because the user switched to some other +activity). This command is also useful for switching between multiple +active Ediff sessions that are run at the same time. The function +@code{eregistry} is an alias for @code{ediff-show-registry}. +@xref{Registry of Ediff Sessions}, for more information on this registry. + +@item ediff-toggle-multiframe +@findex ediff-toggle-multiframe +Changes the display from the multi-frame mode (where the quick help window +is in a separate frame) to the single-frame mode (where all Ediff buffers +share the same frame), and vice versa. See +@code{ediff-window-setup-function} for details on how to make either of +these modes the default one. + +This function can also be invoked from the Menubar. However, in some +cases, the change will take place only after you execute one of the Ediff +commands, such as going to the next difference or redisplaying. + +@item ediff-revert-buffers-then-recompute-diffs +@findex ediff-revert-buffers-then-recompute-diffs +This command reverts the buffers you are comparing and recomputes their +differences. It is useful when, after making changes, you decided to +make a fresh start, or if at some point you changed the files being +compared but want to discard any changes to comparison buffers that were +done since then. + +This command normally asks for confirmation before reverting files. +With a prefix argument, it reverts files without asking. + + +@item ediff-profile +@findex ediff-profile +Ediff has an admittedly primitive (but useful) facility for profiling +Ediff's commands. It is meant for Ediff maintenance---specifically, for +making it run faster. The function @code{ediff-profile} toggles +profiling of ediff commands. +@end table + +@node Registry of Ediff Sessions, Session Groups, Session Commands, Top +@chapter Registry of Ediff Sessions + +Ediff maintains a registry of all its invocations that are +still @emph{active}. This feature is very convenient for switching among +active Ediff sessions or for quickly restarting a suspended Ediff session. + +The focal point of this activity is a buffer +called @emph{*Ediff Registry*}. You can display this buffer by typing +@kbd{R} in any Ediff Control Buffer or Session Group Buffer +(@pxref{Session Groups}), or by typing +@kbd{M-x eregistry} into the Minibuffer. +The latter would be the fastest way to bring up the registry +buffer if no control or group buffer is displayed in any of the visible +Emacs windows. +If you are in a habit of running multiple long Ediff sessions and often need to +suspend, resume, or switch between them, it may be a good idea to have the +registry buffer permanently displayed in a separate, dedicated window. + +The registry buffer has several convenient key bindings. +For instance, clicking mouse button 2 or typing +@kbd{RET} or @kbd{v} over any session record resumes that session. +Session records in the registry buffer provide a fairly complete +description of each session, so it is usually easy to identify the right +session to resume. + +Other useful commands are bound to @kbd{SPC} (next registry record) +and @kbd{DEL} (previous registry record). There are other commands as well, +but you don't need to memorize them, since they are listed at the top of +the registry buffer. + +@node Session Groups, Remote and Compressed Files, Registry of Ediff Sessions, Top +@chapter Session Groups + +Several major entries of Ediff perform comparison and merging on +directories. On entering @code{ediff-directories}, +@code{ediff-directories3}, +@code{ediff-merge-directories}, +@code{ediff-merge-directories-with-ancestor}, +@code{ediff-directory-revisions}, +@code{ediff-merge-directory-revisions}, or +@code{ediff-merge-directory-revisions-with-ancestor}, +the user is presented with a +Dired-like buffer that lists files common to the directories involved along +with their sizes. (The list of common files can be further filtered through +a regular expression, which the user is prompted for.) We call this buffer +@emph{Session Group Panel} because all Ediff sessions associated with the +listed files will have this buffer as a common focal point. + +Clicking button 2 or typing @kbd{RET} or @kbd{v} over a +record describing files invokes Ediff in the appropriate mode on these +files. You can come back to the session group buffer associated with a +particular invocation of Ediff by typing @kbd{M} in Ediff control buffer of +that invocation. + +Many commands are available in the session group buffer; some are +applicable only to certain types of work. The relevant commands are always +listed at the top of each session group buffer, so there is no need to +memorize them. + +In directory comparison or merging, a session group panel displays only the +files common to all directories involved. The differences are kept in a +separate buffer and are conveniently displayed by typing @kbd{D} to the +corresponding session group panel. Thus, as an added benefit, Ediff can be +used to compare the contents of up to three directories. + +Session records in session group panels are also marked with @kbd{+}, for +active sessions, and with @kbd{-}, for finished sessions. + +Sometimes, it is convenient to exclude certain sessions from a group. +Usually this happens when the user doesn't intend to run Ediff of certain +files in the group, and the corresponding session records just add clutter +to the session group buffer. To help alleviate this problem, the user can +type @kbd{h} to mark a session as a candidate for exclusion and @kbd{x} to +actually hide the marked sessions. There actions are reversible: with a +prefix argument, @kbd{h} unmarks the session under the cursor, and @kbd{x} +brings the hidden sessions into the view (@kbd{x} doesn't unmark them, +though, so the user has to explicitly unmark the sessions of interest). + +Group sessions also understand the command @kbd{m}, which marks sessions +for future operations (other than hiding) on a group of sessions. At present, +the only such group-level operation is the creation of a multi-file patch. + +@vindex ediff-autostore-merges +For group sessions created to merge files, Ediff can store all merges +automatically in a directory. The user is asked to specify such directory +if the value of @code{ediff-autostore-merges} is non-nil. If the value is +@code{nil}, nothing is done to the merge buffers---it will be the user's +responsibility to save them. If the value is @code{t}, the user will be +asked where to save the merge buffers in all merge jobs, even those that do +not originate from a session group. It the value is neither @code{nil} nor +@code{t}, the merge buffer is saved @emph{only} if this merge session was +invoked from a session group. This behavior is implemented in the function +@code{ediff-maybe-save-and-delete-merge}, which is a hook in +@code{ediff-quit-merge-hook}. The user can supply a different hook, if +necessary. + +The variable @code{ediff-autostore-merges} is buffer-local, so it can be +set in a per-buffer manner. Therefore, use @code{setq-default} to globally +change this variable. + +@cindex Multi-file patches +A multi-file patch is a concatenated output of several runs of the Unix +@file{diff} command (some versions of @file{diff} let you create a +multi-file patch in just one run). Ediff facilitates creation of +multi-file patches as follows. If you are in a session group buffer +created in response to @code{ediff-directories} or +@code{ediff-directory-revisions}, you can mark (by typing @kbd{m}) the +desired Ediff sessions and then type @kbd{P} to create a +multi-file patch of those marked sessions. +Ediff will then display a buffer containing the patch. +The patch is generated by invoking @file{diff} on all marked individual +sessions (represented by files) and session groups (represented by +directories). Ediff will also recursively descend into any @emph{unmarked} +session group and will search for marked sessions there. In this way, you +can create multi-file patches that span file subtrees that grow out of +any given directory. + +In an @code{ediff-directories} session, it is enough to just mark the +requisite sessions. In @code{ediff-directory-revisions} revisions, the +marked sessions must also be active, or else Ediff will refuse to produce a +multi-file patch. This is because, in the latter-style sessions, there are +many ways to create diff output, and it is easier to handle by running +Ediff on the inactive sessions. + +Last, but not least, by typing @kbd{=}, you can quickly find out which +sessions have identical files, so you won't have to run Ediff on those +sessions. This, however, works only on local, uncompressed files. +For compressed or remote files, this command won't report anything. + + +@node Remote and Compressed Files, Customization, Session Groups, Top +@chapter Remote and Compressed Files + +Ediff works with remote, compressed, and encrypted files. Ediff +supports @file{ange-ftp.el}, @file{jka-compr.el}, @file{uncompress.el} +and @file{crypt++.el}, but it may work with other similar packages as +well. This means that you can compare files residing on another +machine, or you can apply a patch to a file on another machine. Even +the patch itself can be a remote file! + +When patching compressed or remote files, Ediff does not rename the source +file (unlike what the @code{patch} utility would usually do). Instead, the +source file retains its name and the result of applying the patch is placed +in a temporary file that has the suffix @file{_patched} attached. +Generally, this applies to files that are handled using black magic, such +as special file handlers (ange-ftp and some compression and encryption +packages also use this method). + +Regular files are treated by the @code{patch} utility in the usual manner, +i.e., the original is renamed into @file{source-name.orig} and the result +of the patch is placed into the file source-name (@file{_orig} is used +on systems like VMS, DOS, etc.) + +@node Customization, Credits, Remote and Compressed Files, Top +@chapter Customization + +Ediff has a rather self-explanatory interface, and in most cases you +won't need to change anything. However, should the need arise, there are +extensive facilities for changing the default behavior. + +Most of the customization can be done by setting various variables in the +@file{.emacs} file. Some customization (mostly window-related +customization and faces) can be done by putting appropriate lines in +@file{.Xdefaults}, @file{.xrdb}, or whatever X resource file is in use. + +With respect to the latter, please note that the X resource +for Ediff customization is `Ediff', @emph{not} `emacs'. +@xref{Window and Frame Configuration}, +@xref{Highlighting Difference Regions}, for further details. Please also +refer to Emacs manual for the information on how to set Emacs X resources. + +@menu +* Hooks:: Customization via the hooks. +* Quick Help Customization:: How to customize Ediff's quick help feature. +* Window and Frame Configuration:: Controlling the way Ediff displays things. +* Selective Browsing:: Advanced browsing through difference regions. +* Highlighting Difference Regions:: Controlling highlighting. +* Narrowing:: Comparing regions, windows, etc. +* Refinement of Difference Regions:: How to control the refinement process. +* Patch and Diff Programs:: Changing the utilities that compute differences + and apply patches. +* Merging and diff3:: How to customize Ediff in its Merge Mode. +* Support for Version Control:: Changing the version control package. + You are not likely to do that. +* Customizing the Mode Line:: Changing the look of the mode line in Ediff. +* Miscellaneous:: Other customization. +* Notes on Heavy-duty Customization:: Customization for the gurus. +@end menu + +@node Hooks, Quick Help Customization, Customization, Customization +@section Hooks + +The bulk of customization can be done via the following hooks: + +@table @code +@item ediff-load-hook +@vindex ediff-load-hook +This hook can be used to change defaults after Ediff is loaded. + +@item ediff-keymap-setup-hook +@vindex ediff-keymap-setup-hook +@vindex ediff-mode-map +This hook can be used to alter bindings in Ediff's keymap, +@code{ediff-mode-map}. These hooks are +run right after the default bindings are set but before +@code{ediff-load-hook}. The regular user needs not be concerned with this +hook---it is provided for implementors of other Emacs packages built on top +of Ediff. + +@item ediff-before-setup-windows-hook +@itemx ediff-after-setup-windows-hook +@vindex ediff-before-setup-windows-hook +@vindex ediff-after-setup-windows-hook +These two hooks are called before and after Ediff sets up its window +configuration. Can be used to save the configuration that existed +before Ediff starts or for whatever other purposes. + +@item ediff-suspend-hook +@itemx ediff-quit-hook +@vindex ediff-suspend-hook +@vindex ediff-quit-hook +These two hooks are run when you suspend or quit Ediff. They can be +used to set desired window configurations, delete files Ediff didn't +want to clean up after exiting, etc. + +By default, @code{ediff-quit-hook} holds one hook function, +@code{ediff-cleanup-mess}, which cleans after Ediff, as appropriate in +most cases. You probably won't want to change it, but you might +want to add other hook functions. + +Keep in mind that hooks executing before @code{ediff-cleanup-mess} start +in @code{ediff-control-buffer;} they should also leave +@code{ediff-control-buffer} as the current buffer when they finish. +Hooks that are executed after @code{ediff-cleanup-mess} should expect +the current buffer be either buffer A or buffer B. +@code{ediff-cleanup-mess} doesn't kill the buffers being compared or +merged (see @code{ediff-cleanup-hook}, below). + +@item ediff-cleanup-hook +@vindex ediff-cleanup-hook +This hook is run just before @code{ediff-quit-hook}. This is a good +place to do various cleanups, such as deleting the variant buffers. +Ediff provides a function, @code{ediff-janitor}, as one such possible +hook, which you can add to @code{ediff-cleanup-hook} with +@code{add-hooks}. + +@findex ediff-janitor +This function kills buffers A, B, and, possibly, C, if these buffers aren't +modified. In merge jobs, buffer C is never deleted. However, the side +effect of using this function is that you may not be able to compare the +same buffer in two separate Ediff sessions: quitting one of them will +delete this buffer in another session as well. + +@item ediff-quit-merge-hook +@vindex ediff-quit-merge-hook +@vindex ediff-autostore-merges +@findex ediff-maybe-save-and-delete-merge +This hook is called when Ediff quits a merge job. By default, the value is +@code{ediff-maybe-save-and-delete-merge}, which is a function that attempts +to save the merge buffer according to the value of +@code{ediff-autostore-merges}, as described later. + +@item ediff-before-setup-control-frame-hook +@itemx ediff-after-setup-control-frame-hook +@vindex ediff-before-setup-control-frame-hook +@vindex ediff-after-setup-control-frame-hook +These two hooks run before and after Ediff sets up the control frame. +They can be used to relocate Ediff control frame when Ediff runs in a +multiframe mode (i.e., when the control buffer is in its own dedicated +frame). Be aware that many variables that drive Ediff are local to +Ediff Control Panel (@code{ediff-control-buffer}), which requires +special care in writing these hooks. Take a look at +@code{ediff-default-suspend-hook} and @code{ediff-default-quit-hook} to +see what's involved. + +@item ediff-startup-hook +@vindex ediff-startup-hook +This hook is run at the end of Ediff startup. + +@item ediff-select-hook +@vindex ediff-select-hook +This hook is run after Ediff selects the next difference region. + +@item ediff-unselect-hook +@vindex ediff-unselect-hook +This hook is run after Ediff unselects the current difference region. + +@item ediff-prepare-buffer-hook +@vindex ediff-prepare-buffer-hook +This hook is run for each Ediff buffer (A, B, C) right after the buffer +is arranged. + +@item ediff-display-help-hook +@vindex ediff-display-help-hook +Ediff runs this hook each time after setting up the help message. It +can be used to alter the help message for custom packages that run on +top of Ediff. + +@item ediff-mode-hook +@vindex ediff-mode-hook +This hook is run just after Ediff mode is set up in the control +buffer. This is done before any Ediff window is created. You can use it to +set local variables that alter the look of the display. + +@item ediff-registry-setup-hook +@vindex ediff-registry-setup-hook +Hooks run after setting up the registry for all active Ediff session. +@xref{Session Groups}, for details. +@item ediff-session-group-setup-hook +@vindex ediff-session-group-setup-hook +Hooks run after setting up a control panel for a group of related Ediff +sessions. @xref{Session Groups}, for details. +@item ediff-quit-session-group-hook +@vindex ediff-quit-session-group-hook +Hooks run just before exiting a session group. +@item ediff-meta-buffer-keymap-setup-hook +@vindex ediff-meta-buffer-keymap-setup-hook +@vindex ediff-meta-buffer-map +Hooks run just after setting up the @code{ediff-meta-buffer-map} --- the +map that controls key bindings in the meta buffer. Since +@code{ediff-meta-buffer-map} is a local variable, you can set different +bindings for different kinds of meta buffers. +@end table + +@node Quick Help Customization, Window and Frame Configuration, Hooks, Customization +@section Quick Help Customization +@vindex ediff-use-long-help-message +@vindex ediff-control-buffer +@vindex ediff-startup-hook +@vindex ediff-help-message + +Ediff provides quick help using its control panel window. Since this window +takes a fair share of the screen real estate, you can toggle it off by +typing @kbd{?}. The control window will then shrink to just one line and a +mode line, displaying a short help message. + +The variable @code{ediff-use-long-help-message} tells Ediff whether +you use the short message or the long one. By default, it +is set to @code{nil}, meaning that the short message is used. +Set this to @code{t}, if you want Ediff to use the long +message by default. This property can always be changed interactively, by +typing @kbd{?} into Ediff Control Buffer. + +If you want to change the appearance of the help message on a per-buffer +basis, you must use @code{ediff-startup-hook} to change the value of +the variable @code{ediff-help-message}, which is local to +@code{ediff-control-buffer}. + +@node Window and Frame Configuration, Selective Browsing, Quick Help Customization, Customization +@section Window and Frame Configuration + +On a non-windowing display, Ediff sets things up in one frame, splitting +it between a small control window and the windows for buffers A, B, and C. +The split between these windows can be horizontal or +vertical, which can be changed interactively by typing @kbd{|} while the +cursor is in the control window. + +On a window display, Ediff sets up a dedicated frame for Ediff Control +Panel and then it chooses windows as follows: If one of the buffers +is invisible, it is displayed in the currently selected frame. If +a buffer is visible, it is displayed in the frame where it is visible. +If, according to the above criteria, the two buffers fall into the same +frame, then so be it---the frame will be shared by the two. The same +algorithm works when you type @kbd{C-l} (@code{ediff-recenter}), @kbd{p} +(@code{ediff-previous-difference}), @kbd{n} +(@code{ediff-next-difference}), etc. + +The above behavior also depends on whether the current frame is splittable, +dedicated, etc. Unfortunately, the margin of this book is too narrow to +present the details of this remarkable algorithm. + +The upshot of all this is that you can compare buffers in one frame or +in different frames. The former is done by default, while the latter can +be achieved by arranging buffers A, B (and C, if applicable) to be seen in +different frames. Ediff respects these arrangements, automatically +adapting itself to the multi-frame mode. + +Ediff uses the following variables to set up its control panel +(a.k.a.@: control buffer, a.k.a.@: quick help window): + +@table @code +@item ediff-control-frame-parameters +@vindex ediff-control-frame-parameters +You can change or augment this variable including the font, color, +etc. The X resource name of Ediff Control Panel frames is @samp{Ediff}. Under +X-windows, you can use this name to set up preferences in your +@file{~/.Xdefaults}, @file{~/.xrdb}, or whatever X resource file is in +use. Usually this is preferable to changing +@code{ediff-control-frame-parameters} directly. For instance, you can +specify in @file{~/.Xdefaults} the color of the control frame +using the resource @samp{Ediff*background}. + +In general, any X resource pertaining the control frame can be reached +via the prefix @code{Ediff*}. + +@item ediff-control-frame-position-function +@vindex ediff-control-frame-position-function +The preferred way of specifying the position of the control frame is by +setting the variable @code{ediff-control-frame-position-function} to an +appropriate function. +The default value of this variable is +@code{ediff-make-frame-position}. This function places the control frame in +the vicinity of the North-East corner of the frame displaying buffer A. + +@findex ediff-make-frame-position +@end table + +The following variables can be used to adjust the location produced by +@code{ediff-make-frame-position} and for related customization. + +@table @code +@item ediff-narrow-control-frame-leftward-shift +@vindex ediff-narrow-control-frame-leftward-shift +Specifies the number of characters for shifting +the control frame from the rightmost edge of frame A when the control +frame is displayed as a small window. + +@item ediff-wide-control-frame-rightward-shift +@vindex ediff-wide-control-frame-rightward-shift +Specifies the rightward shift of the control frame +from the left edge of frame A when the control frame shows the full +menu of options. + +@item ediff-control-frame-upward-shift +@vindex ediff-control-frame-upward-shift +Specifies the number of pixels for the upward shift +of the control frame. + +@item ediff-prefer-iconified-control-frame +@vindex ediff-prefer-iconified-control-frame +If this variable is @code{t}, the control frame becomes iconified +automatically when you toggle the quick help message off. This saves +valuable real estate on the screen. Toggling help back will deiconify +the control frame. + +To start Ediff with an iconified Control Panel, you should set this +variable to @code{t} and @code{ediff-prefer-long-help-message} to +@code{nil} (@pxref{Quick Help Customization}). This behavior is useful +only if the window manager is TWM or a derivative. +@end table + +@findex ediff-setup-windows +To make more creative changes in the way Ediff sets up windows, you can +rewrite the function @code{ediff-setup-windows}. However, we believe +that detaching Ediff Control Panel from the rest and making it into a +separate frame offers an important opportunity by allowing you to +iconify that frame. The icon will usually accept all of the Ediff +commands, but will free up valuable real estate on your screen (this may +depend on your window manager, though). + +The following variable controls how windows are set up: + +@table @code +@item ediff-window-setup-function +@vindex ediff-window-setup-function +The multiframe setup is done by the +@code{ediff-setup-windows-multiframe} function, which is the default on +windowing displays. The plain setup, one where all windows are always +in one frame, is done by @code{ediff-setup-windows-plain}, which is the +default on a non-windowing display (or in an xterm window). In fact, +under Emacs, you can switch freely between these two setups by executing +the command @code{ediff-toggle-multiframe} using the Minibuffer of the +Menubar. +@findex ediff-setup-windows-multiframe +@findex ediff-setup-windows-plain +@findex ediff-toggle-multiframe + +If you don't like any of these setups, write your own function. See the +documentation for @code{ediff-window-setup-function} for the basic +guidelines. However, writing window setups is not easy, so you should +first take a close look at @code{ediff-setup-windows-plain} and +@code{ediff-setup-windows-multiframe}. +@end table + +You can run multiple Ediff sessions at once, by invoking Ediff several +times without exiting previous Ediff sessions. Different sessions +may even operate on the same pair of files. + +Each session has its own Ediff Control Panel and all the regarding a +particular session is local to the associated control panel buffer. You +can switch between sessions by suspending one session and then switching +to another control panel. (Different control panel buffers are +distinguished by a numerical suffix, e.g., @samp{Ediff Control Panel<3>}.) + +@node Selective Browsing, Highlighting Difference Regions, Window and Frame Configuration, Customization +@section Selective Browsing + +Sometimes it is convenient to be able to step through only some difference +regions, those that match certain regular expressions, and to ignore all +others. On other occasions, you may want to ignore difference regions that +match some regular expressions, and to look only at the rest. + +The commands @kbd{#f} and @kbd{#h} let you do precisely this. + +Typing @kbd{#f} lets you specify regular expressions that match difference +regions you want to focus on. +We shall call these regular expressions @var{regexp-A}, @var{regexp-B} and +@var{regexp-C}. +Ediff will then start stepping through only those difference regions +where the region in buffer A matches @var{regexp-A} and/or the region in +buffer B matches @var{regexp-B}, etc. Whether `and' or `or' will be used +depends on how you respond to a question. + +When scanning difference regions for the aforesaid regular expressions, +Ediff narrows the buffers to those regions. This means that you can use +the expressions @kbd{\`} and @kbd{\'} to tie search to the beginning or end +of the difference regions. + +On the other hand, typing @kbd{#h} lets you specify (hide) uninteresting +regions. That is, if a difference region in buffer A matches +@var{regexp-A}, the corresponding region in buffer B matches @var{regexp-B} +and (if applicable) buffer C's region matches @var{regexp-C}, then the +region will be ignored by the commands @kbd{n}/@key{SPC} +(@code{ediff-next-difference}) and @kbd{p}/@key{DEL} +(@code{ediff-previous-difference}) commands. + +Typing @kbd{#f} and @kbd{#h} toggles selective browsing on and off. + +Note that selective browsing affects only @code{ediff-next-difference} +and @code{ediff-previous-difference}, i.e., the commands +@kbd{n}/@key{SPC} and @kbd{p}/@key{DEL}. @kbd{#f} and @kbd{#h} do not +change the position of the point in the buffers. And you can still jump +directly (using @kbd{j}) to any numbered +difference. + +Users can supply their own functions to specify how Ediff should do +selective browsing. To change the default Ediff function, add a function to +@code{ediff-load-hook} which will do the following assignments: + +@example +(setq ediff-hide-regexp-matches-function 'your-hide-function) +(setq ediff-focus-on-regexp-matches-function 'your-focus-function) +@end example + +@strong{Useful hint}: To specify a regexp that matches everything, don't +simply type @key{RET} in response to a prompt. Typing @key{RET} tells Ediff +to accept the default value, which may not be what you want. Instead, you +should enter something like @key{^} or @key{$}. These match every +line. + +You can use the status command, @kbd{i}, to find out whether +selective browsing is currently in effect. + +The regular expressions you specified are kept in the local variables +@code{ediff-regexp-focus-A}, @code{ediff-regexp-focus-B}, +@code{ediff-regexp-focus-C}, @code{ediff-regexp-hide-A}, +@code{ediff-regexp-hide-B}, @code{ediff-regexp-hide-C}. Their default value +is the empty string (i.e., nothing is hidden or focused on). To change the +default, set these variables in @file{.emacs} using @code{setq-default}. + +In addition to the ability to ignore regions that match regular +expressions, Ediff can be ordered to start skipping over certain +``uninteresting'' difference regions. This is controlled by the following +variable: + +@table @code +@item ediff-ignore-similar-regions +@vindex ediff-ignore-similar-regions +If @code{t}, causes Ediff to skip over "uninteresting" difference regions, +which are the regions where the variants differ only in the amount of the +white space and newlines. This feature can be toggled on/off interactively, +via the command @kbd{##}. +@end table + +@strong{Note:} In order for this feature to work, auto-refining of +difference regions must be on, since otherwise Ediff won't know if there +are fine differences between regions. On devices where Emacs can display +faces, auto-refining is a default, but it is not turned on by default on +text-only terminals. In that case, you must explicitly turn auto-refining +on (such as, by typing @kbd{@@}). + +@strong{Reassurance:} If many such uninteresting regions appear in a row, +Ediff may take a long time to skip over them because it has to compute fine +differences of all intermediate regions. This delay does not indicate any +problem. + +@node Highlighting Difference Regions, Narrowing, Selective Browsing, Customization +@section Highlighting Difference Regions + +The following variables control the way Ediff highlights difference +regions: + +@table @code +@item ediff-before-flag-bol +@itemx ediff-after-flag-eol +@itemx ediff-before-flag-mol +@itemx ediff-after-flag-mol +@vindex ediff-before-flag-bol +@vindex ediff-after-flag-eol +@vindex ediff-before-flag-mol +@vindex ediff-after-flag-mol +These variables hold strings that Ediff uses to mark the beginning and the +end of the differences found in files A, B, and C on devices where Emacs +cannot display faces. Ediff uses different flags to highlight regions that +begin/end at the beginning/end of a line or in a middle of a line. + +@item ediff-current-diff-face-A +@itemx ediff-current-diff-face-B +@itemx ediff-current-diff-face-C +@vindex ediff-current-diff-face-A +@vindex ediff-current-diff-face-B +@vindex ediff-current-diff-face-C +Ediff uses these faces to highlight current differences on devices where +Emacs can display faces. These and subsequently described faces can be set +either in @file{.emacs} or in @file{.Xdefaults}. The X resource for Ediff +is @samp{Ediff}, @emph{not} @samp{emacs}. Please refer to Emacs manual for +the information on how to set X resources. +@item ediff-fine-diff-face-A +@itemx ediff-fine-diff-face-B +@itemx ediff-fine-diff-face-C +@vindex ediff-fine-diff-face-A +@vindex ediff-fine-diff-face-B +@vindex ediff-fine-diff-face-C +Ediff uses these faces to show the fine differences between the current +differences regions in buffers A, B, and C, respectively. + +@item ediff-even-diff-face-A +@itemx ediff-even-diff-face-B +@itemx ediff-even-diff-face-C +@itemx ediff-odd-diff-face-A +@itemx ediff-odd-diff-face-B +@itemx ediff-odd-diff-face-C +@vindex ediff-even-diff-face-A +@vindex ediff-even-diff-face-B +@vindex ediff-even-diff-face-C +@vindex ediff-odd-diff-face-A +@vindex ediff-odd-diff-face-B +@vindex ediff-odd-diff-face-C +Non-current difference regions are displayed using these alternating +faces. The odd and the even faces are actually identical on monochrome +displays, because without colors options are limited. +So, Ediff uses italics to highlight non-current differences. + +@item ediff-force-faces +@vindex ediff-force-faces +Ediff generally can detect when Emacs is running on a device where it can +use highlighting with faces. However, if it fails to determine that faces +can be used, the user can set this variable to @code{t} to make sure that +Ediff uses faces to highlight differences. + +@item ediff-highlight-all-diffs +@vindex ediff-highlight-all-diffs +Indicates whether---on a windowind display---Ediff should highlight +differences using inserted strings (as on text-only terminals) or using +colors and highlighting. Normally, Ediff highlights all differences, but +the selected difference is highlighted more visibly. One can cycle through +various modes of highlighting by typing @kbd{h}. By default, Ediff starts +in the mode where all difference regions are highlighted. If you prefer to +start in the mode where unselected differences are not highlighted, you +should set @code{ediff-highlight-all-diffs} to @code{nil}. Type @kbd{h} to +restore highlighting for all differences. + +Ediff lets you switch between the two modes of highlighting. That is, +you can switch interactively from highlighting using faces to +highlighting using string flags, and back. Of course, switching has +effect only under a windowing system. On a text-only terminal or in an +xterm window, the only available option is highlighting with strings. +@end table + +@noindent +If you want to change the default settings for @code{ediff-force-faces} and +@code{ediff-highlight-all-diffs}, you must do it @strong{before} Ediff is +loaded. + +You can also change the defaults for the faces used to highlight the +difference regions. There are two ways to do this. The simplest and the +preferred way is to use the customization widget accessible from the +menubar. Ediff's customization group is located under "Tools", which in +turn is under "Programming". The faces that are used to highlight +difference regions are located in the "Highlighting" subgroup of the Ediff +customization group. + +The second, much more arcane, method to change default faces is to include +some Lisp code in @file{~/.emacs}. For instance, + +@example +(setq ediff-current-diff-face-A + (copy-face 'bold-italic 'ediff-current-diff-face-A)) +@end example + +@noindent +would use the pre-defined fase @code{bold-italic} to highlight the current +difference region in buffer A (this face is not a good choice, by the way). + +If you are unhappy with just @emph{some} of the aspects of the default +faces, you can modify them when Ediff is being loaded using +@code{ediff-load-hook}. For instance: + +@smallexample +(add-hook 'ediff-load-hook + (function (lambda () + (set-face-foreground + ediff-current-diff-face-B "blue") + (set-face-background + ediff-current-diff-face-B "red") + (make-face-italic + ediff-current-diff-face-B)))) +@end smallexample + +@strong{Note:} it is not recommended to use @code{internal-get-face} +when defining Ediff's faces, since this may cause problems when there +are several frames with different font sizes. Instead, use +@code{copy-face} or @code{set/make-face-@dots{}} as shown above. + +@node Narrowing, Refinement of Difference Regions, Highlighting Difference Regions, Customization +@section Narrowing + +If buffers being compared are narrowed at the time of invocation of +Ediff, @code{ediff-buffers} will preserve the narrowing range. However, +if @code{ediff-files} is invoked on the files visited by these buffers, +that would widen the buffers, since this command is defined to compare the +entire files. + +Calling @code{ediff-regions-linewise} or @code{ediff-windows-linewise}, or +the corresponding @samp{-wordwise} commands, narrows the variants to the +particular regions being compared. The original accessible ranges are +restored when you quit Ediff. During the command, you can toggle this +narrowing on and off with the @kbd{%} command. + +These two variables control this narrowing behavior: + +@table @code +@item ediff-start-narrowed +@vindex ediff-start-narrowed +If @code{t}, Ediff narrows the display to the appropriate range when it +is invoked with an @samp{ediff-regions@dots{}} or +@samp{ediff-windows@dots{}} command. If @code{nil}, these commands do +not automatically narrow, but you can still toggle narrowing on and off +by typing @kbd{%}. + +@item ediff-quit-widened +@vindex ediff-quit-widened +Controls whether on quitting Ediff should restore the accessible range +that existed before the current invocation. +@end table + +@node Refinement of Difference Regions, Patch and Diff Programs, Narrowing, Customization +@section Refinement of Difference Regions + +Ediff has variables to control the way fine differences are +highlighted. This feature gives you control over the process of refinement. +Note that refinement ignores spaces, tabs, and newlines. + +@table @code +@item ediff-auto-refine +@vindex ediff-auto-refine +This variable controls whether fine differences within regions are +highlighted automatically (``auto-refining''). The default is yes +(@samp{on}). + +On a slow machine, automatic refinement may be painful. In that case, +you can turn auto-refining on or off interactively by typing +@kbd{@@}. You can also turn off display of refining that has +already been done. + +When auto-refining is off, fine differences are shown only for regions +for which these differences have been computed and saved before. If +auto-refining and display of refining are both turned off, fine +differences are not shown at all. + +Typing @kbd{*} computes and displays fine differences for the current +difference region, regardless of whether auto-refining is turned on. + +@item ediff-auto-refine-limit +@vindex ediff-auto-refine-limit +If auto-refining is on, this variable limits the size of the regions to +be auto-refined. This guards against the possible slowdown that may be +caused by extraordinary large difference regions. + +You can always refine the current region by typing @kbd{*}. + +@item ediff-forward-word-function +@vindex ediff-forward-word-function +This variable controls how fine differences are computed. The +value must be a Lisp function that determines how the current difference +region should be split into words. + +@vindex ediff-diff-program +@vindex ediff-forward-word-function +@findex ediff-forward-word +Fine differences are computed by first splitting the current difference +region into words and then passing the result to +@code{ediff-diff-program}. For the default forward word function (which is +@code{ediff-forward-word}), a word is a string consisting of letters, +@samp{-}, or @samp{_}; a string of punctuation symbols; a string of digits, +or a string consisting of symbols that are neither space, nor a letter. + +This default behavior is controlled by four variables: @code{ediff-word-1}, +..., @code{ediff-word-4}. See the on-line documentation for these variables +and for the function @code{ediff-forward-word} for an explanation of how to +modify these variables. +@vindex ediff-word-1 +@vindex ediff-word-2 +@vindex ediff-word-3 +@vindex ediff-word-4 +@end table + +Sometimes, when a region has too many differences between the variants, +highlighting of fine differences is inconvenient, especially on +color displays. If that is the case, type @kbd{*} with a negative +prefix argument. This unhighlights fine differences for the current +region. + +To unhighlight fine differences in all difference regions, use the +command @kbd{@@}. Repeated typing of this key cycles through three +different states: auto-refining, no-auto-refining, and no-highlighting +of fine differences. + +@node Patch and Diff Programs, Merging and diff3, Refinement of Difference Regions, Customization +@section Patch and Diff Programs + +This section describes variables that specify the programs to be used for +applying patches and for computing the main difference regions (not the +fine difference regions): + +@table @code +@item ediff-diff-program +@itemx ediff-diff3-program +@vindex ediff-patch-program +@vindex ediff-diff-program +@vindex ediff-diff3-program +These variables specify the programs to use to produce differences +and do patching. + +@item ediff-diff-options +@itemx ediff-diff3-options +@vindex ediff-patch-options +@vindex ediff-diff-options +@vindex ediff-diff3-options +These variables specify the options to pass to the above utilities. + +In @code{ediff-diff-options}, it may be useful to specify options +such as @samp{-w} that ignore certain kinds of changes. However, +Ediff does not let you use the option @samp{-c}, as it doesn't recognize this +format yet. + +@item ediff-patch-program +The program to use to apply patches. Since there are certain +incompatibilities between the different versions of the patch program, the +best way to stay out of trouble is to use a GNU-compatible version. +Otherwise, you may have to tune the values of the variables +@code{ediff-patch-options}, @code{ediff-backup-specs}, and +@code{ediff-backup-extension} as described below. +@item ediff-patch-options +Options to pass to @code{ediff-patch-program}. + +Note: the `-b' and `-z' options should be specified in +`ediff-backup-specs', not in @code{ediff-patch-options}. + +It is recommended to pass the `-f' option to the patch program, so it won't +ask questions. However, some implementations don't accept this option, in +which case the default value of this variable should be changed. + +@item ediff-backup-extension +Backup extension used by the patch program. Must be specified, even if +@code{ediff-backup-specs} is given. +@item ediff-backup-specs +Backup directives to pass to the patch program. +Ediff requires that the old version of the file (before applying the patch) +is saved in a file named @file{the-patch-file.extension}. Usually +`extension' is `.orig', but this can be changed by the user, and may also be +system-dependent. Therefore, Ediff needs to know the backup extension used +by the patch program. + +Some versions of the patch program let the user specify `-b backup-extension'. +Other versions only permit `-b', which (usually) assumes the extension `.orig'. +Yet others force you to use `-z<backup-extension>'. + +Note that both `ediff-backup-extension' and `ediff-backup-specs' must be +properly set. If your patch program takes the option `-b', but not +`-b extension', the variable `ediff-backup-extension' must still +be set so Ediff will know which extension to use. + +@item ediff-custom-diff-program +@itemx ediff-custom-diff-options +@vindex ediff-custom-diff-program +@vindex ediff-custom-diff-options +@findex ediff-save-buffer +Because Ediff limits the options you may want to pass to the @code{diff} +program, it partially makes up for this drawback by letting you save the +output from @code{diff} in your preferred format, which is specified via +the above two variables. + +The output generated by @code{ediff-custom-diff-program} (which doesn't +even have to be a standard-style @file{diff}!)@: is not used by Ediff. It is +provided exclusively so that you can +refer to +it later, send it over email, etc. For instance, after reviewing the +differences, you may want to send context differences to a colleague. +Since Ediff ignores the @samp{-c} option in +@code{ediff-diff-program}, you would have to run @code{diff -c} separately +just to produce the list of differences. Fortunately, +@code{ediff-custom-diff-program} and @code{ediff-custom-diff-options} +eliminate this nuisance by keeping a copy of a difference list in the +desired format in a buffer that can be displayed via the command @kbd{D}. + +@item ediff-patch-default-directory +@vindex ediff-patch-default-directory +Specifies the default directory to look for patches. + +@end table + +@noindent +@strong{Warning:} Ediff does not support the output format of VMS +@code{diff}. Instead, make sure you are using some implementation of POSIX +@code{diff}, such as @code{gnudiff}. + +@node Merging and diff3, Support for Version Control, Patch and Diff Programs, Customization +@section Merging and diff3 + +Ediff supports three-way comparison via the functions @code{ediff-files3} and +@code{ediff-buffers3}. The interface is the same as for two-way comparison. +In three-way comparison and merging, Ediff reports if any two difference +regions are identical. For instance, if the current region in buffer A +is the same as the region in buffer C, then the mode line of buffer A will +display @samp{[=diff(C)]} and the mode line of buffer C will display +@samp{[=diff(A)]}. + +Merging is done according to the following algorithm. + +If a difference region in one of the buffers, say B, differs from the ancestor +file while the region in the other buffer, A, doesn't, then the merge buffer, +C, gets B's region. Similarly when buffer A's region differs from +the ancestor and B's doesn't, A's region is used. + +@vindex ediff-default-variant +If both regions in buffers A and B differ from the ancestor file, Ediff +chooses the region according to the value of the variable +@code{ediff-default-variant}. If its value is @code{default-A} then A's +region is chosen. If it is @code{default-B} then B's region is chosen. +If it is @code{combined} then the region in buffer C will look like +this: + +@example +#ifdef NEW /* variant A */ +difference region from buffer A +#else /* variant B */ +difference region from buffer B +#endif /* NEW */ +@end example + +@vindex ediff-combination-pattern +The actual strings that separate the regions copied from buffer A and B +are controlled by the variable @code{ediff-combination-pattern}. Its +value should be a list of three strings. The first is inserted before +the difference region of buffer A; the second string goes between the +regions; the third goes after region B, as shown in the above example. + +In addition to the state of the difference, Ediff displays the state of the +merge for each region. If a difference came from buffer A by default +(because both regions A and B were different from the ancestor and +@code{ediff-default-variant} was set to @code{default-A}) then +@samp{[=diff(A) default-A]} is displayed in the mode line. If the +difference in buffer C came, say, from buffer B because the difference +region in that buffer differs from the ancestor, but the region in buffer A +does not (if merging with an ancestor) then @samp{[=diff(B) prefer-B]} is +displayed. The indicators default-A/B and prefer-A/B are inspired by +Emerge and have the same meaning. + +Another indicator of the state of merge is @samp{combined}. It appears +with any difference region in buffer C that was obtained by combining +the difference regions in buffers A and B as explained above. + +In addition to the state of merge and state of difference indicators, while +merging with an ancestor file or buffer, Ediff informs the user when the +current difference region in the (normally invisible) ancestor buffer is +empty via the @emph{AncestorEmpty} indicator. This helps determine if the +changes made to the original in variants A and B represent pure insertion +or deletion of text: if the mode line shows @emph{AncestorEmpty} and the +corresponding region in buffers A or B is not empty, this means that new +text was inserted. If this indicator is not present and the difference +regions in buffers A or B are non-empty, this means that text was +modified. Otherwise, the original text was deleted. + +Although the ancestor buffer is normally invisible, Ediff maintains +difference regions there and advances the current difference region +accordingly. All highlighting of difference regions is provided in the +ancestor buffer, except for the fine differences. Therefore, if desired, the +user can put the ancestor buffer in a separate frame and watch it +there. However, on a TTY, only one frame can be visible at any given time, +and Ediff doesn't support any single-frame window configuration where all +buffers, including the ancestor buffer, would be visible. However, the +ancestor buffer can be displayed by typing @kbd{/} to the control +window. (Type @kbd{C-l} to hide it again.) + +Note that the state-of-difference indicators @samp{=diff(A)} and +@samp{=diff(B)} above are not redundant, even in the presence of a +state-of-merge indicator. In fact, the two serve different purposes. + +For instance, if the mode line displays @samp{=diff(B) prefer(B)} and +you copy a difference region from buffer A to buffer C then +@samp{=diff(B)} will change to @samp{diff-A} and the mode line will +display @samp{=diff(A) prefer-B}. This indicates that the difference +region in buffer C is identical to that in buffer A, but originally +buffer C's region came from buffer B. This is useful to know because +you can recover the original difference region in buffer C by typing +@kbd{r}. + + +Ediff never changes the state-of-merge indicator, except in response to +the @kbd{!} command (see below), in which case the indicator is lost. +On the other hand, the state-of-difference indicator is changed +automatically by the copying/recovery commands, @kbd{a}, @kbd{b}, @kbd{r}, +@kbd{+}. + +The @kbd{!} command loses the information about origins of the regions +in the merge buffer (default-A, prefer-B, or combined). This is because +recomputing differences in this case means running @code{diff3} on +buffers A, B, and the merge buffer, not on the ancestor buffer. (It +makes no sense to recompute differences using the ancestor file, since +in the merging mode Ediff assumes that you have not edited buffers A and +B, but that you may have edited buffer C, and these changes are to be +preserved.) Since some difference regions may disappear as a result of +editing buffer C and others may arise, there is generally no simple way +to tell where the various regions in the merge buffer came from. + +In three-way comparison, Ediff tries to disregard regions that consist +entirely of white space. For instance, if, say, the current region in +buffer A consists of the white space only (or if it is empty), Ediff will +not take it into account for the purpose of computing fine differences. The +result is that Ediff can provide a better visual information regarding the +actual fine differences in the non-white regions in buffers B and +C. Moreover, if the regions in buffers B and C differ in the white space +only, then a message to this effect will be displayed. + +@vindex ediff-merge-window-share +In the merge mode, the share of the split between window C (the window +displaying the merge-buffer) and the windows displaying buffers A and B +is controlled by the variable @code{ediff-merge-window-share}. Its +default value is 0.5. To make the merge-buffer window smaller, reduce +this amount. + +We don't recommend increasing the size of the merge-window to more than +half the frame (i.e., to increase the value of +@code{ediff-merge-window-share}) to more than 0.5, since it would be +hard to see the contents of buffers A and B. + +You can temporarily shrink the merge window to just one line by +typing @kbd{s}. This change is temporary, until Ediff finds a reason to +redraw the screen. Typing @kbd{s} again restores the original window size. + +With a positive prefix argument, the @kbd{s} command will make the merge +window slightly taller. This change is persistent. With `@kbd{-}' or +with a negative prefix argument, the command @kbd{s} makes the merge +window slightly shorter. This change also persistent. + +@vindex ediff-show-clashes-only +Ediff lets you automatically ignore the regions where only one of the +buffers A and B disagrees with the ancestor. To do this, set the +variable @code{ediff-show-clashes-only} to non-@code{nil}. + +You can toggle this feature interactively by typing @kbd{$}. + +Note that this variable affects only the show next/previous difference +commands. You can still jump directly to any difference region directly +using the command @kbd{j} (with a prefix argument specifying the difference +number). + +@vindex ediff-autostore-merges +@vindex ediff-quit-merge-hook +@findex ediff-maybe-save-and-delete-merge +The variable @code{ediff-autostore-merges} controls what happens to the +merge buffer when Ediff quits. If the value is @code{nil}, nothing is done +to the merge buffer---it will be the user's responsibility to save it. +If the value is @code{t}, the user will be asked where to save the buffer +and whether to delete it afterwards. It the value is neither @code{nil} nor +@code{t}, the merge buffer is saved @emph{only} if this merge session was +invoked from a group of related Ediff session, such as those that result +from @code{ediff-merge-directories}, +@code{ediff-merge-directory-revisions}, etc. +@xref{Session Groups}. This behavior is implemented in the function +@code{ediff-maybe-save-and-delete-merge}, which is a hook in +@code{ediff-quit-merge-hook}. The user can supply a different hook, if +necessary. + +The variable @code{ediff-autostore-merges} is buffer-local, so it can be +set in a per-buffer manner. Therefore, use @code{setq-default} to globally +change this variable. + +@node Support for Version Control, Customizing the Mode Line, Merging and diff3, Customization +@section Support for Version Control + + +Ediff supports version control and lets you compare versions of files +visited by Emacs buffers via the function @code{ediff-revision}. This +feature is controlled by the following variables: + +@table @code +@item ediff-version-control-package +@vindex ediff-version-control-package +A symbol. The default is @samp{vc}. + +If you are like most Emacs users, Ediff will use VC as the version control +package. This is the standard Emacs interface to RCS, CVS, and SCCS. + +However, if your needs are better served by other interfaces, you will +have to tell Ediff which version control package you are using, e.g., +@example +(setq ediff-version-control-package 'rcs) +@end example + +Apart from the standard @file{vc.el}, Ediff supports three other interfaces +to version control: +@file{rcs.el}, @file{pcl-cvs.el}, and @file{generic-sc.el}. +The package @file{rcs.el} is written by Sebastian Kremer +<sk@@thp.Uni-Koeln.DE> and is available as +@example +@file{ftp.cs.buffalo.edu:pub/Emacs/rcs.tar.Z} +@file{ftp.uni-koeln.de:/pub/gnu/emacs/rcs.tar.Z} +@end example +@pindex @file{vc.el} +@pindex @file{rcs.el} +@pindex @file{pcl-cvs.el} +@pindex @file{generic-sc.el} +@end table + +Ediff's interface to the above packages allows the user to compare the +versions of the current buffer or to merge them (with or without an +ancestor-version). These operations can also be performed on directories +containing files under version control. + +In case of @file{pcl-cvs.el}, Ediff can also be invoked via the function +@code{run-ediff-from-cvs-buffer}---see the documentation string for this +function. + +@node Customizing the Mode Line, Miscellaneous, Support for Version Control, Customization +@section Customizing the Mode Line + +When Ediff is running, the mode line of @samp{Ediff Control Panel} +buffer shows the current difference number and the total number of +difference regions in the two files. + +The mode line of the buffers being compared displays the type of the +buffer (@samp{A:}, @samp{B:}, or @samp{C:}) and (usually) the file name. +Ediff tries to be intelligent in choosing the mode line buffer +identification. In particular, it works well with the +@file{uniquify.el} and @file{mode-line.el} packages (which improve on +the default way in which Emacs displays buffer identification). If you +don't like the way Ediff changes the mode line, you can use +@code{ediff-prepare-buffer-hook} to modify the mode line. +@vindex ediff-prepare-buffer-hook +@pindex @file{uniquify.el} +@pindex @file{mode-line.el} + +@node Miscellaneous, Notes on Heavy-duty Customization, Customizing the Mode Line, Customization +@section Miscellaneous + +Here are a few other variables for customizing Ediff: + +@table @code +@item ediff-split-window-function +@vindex ediff-split-window-function +Controls the way you want the window be split between file-A and file-B +(and file-C, if applicable). It defaults to the vertical split +(@code{split-window-vertically}, but you can set it to +@code{split-window-horizontally}, if you so wish. +Ediff also lets you switch from vertical to horizontal split and back +interactively. + +Note that if Ediff detects that all the buffers it compares are displayed in +separate frames, it assumes that the user wants them to be so displayed +and stops splitting windows. Instead, it arranges for each buffer to +be displayed in a separate frame. You can switch to the one-frame mode +by hiding one of the buffers A/B/C. + +You can also swap the windows where buffers are displayed by typing +@kbd{~}. + +@item ediff-merge-split-window-function +@vindex ediff-merge-split-window-function +Controls how windows are +split between buffers A and B in the merge mode. +This variable is like @code{ediff-split-window-function}, but it defaults +to @code{split-window-horizontally} instead of +@code{split-window-vertically}. + +@item ediff-make-wide-display-function +@vindex ediff-make-wide-display-function +The value is a function to be called to widen the frame for displaying +the Ediff buffers. See the on-line documentation for +@code{ediff-make-wide-display-function} for details. It is also +recommended to look into the source of the default function +@code{ediff-make-wide-display}. + +You can toggle wide/regular display by typing @kbd{m}. In the wide +display mode, buffers A, B (and C, when applicable) are displayed in a +single frame that is as wide as the entire workstation screen. This is +useful when files are compared side-by-side. By default, the display is +widened without changing its height. + +@item ediff-use-last-dir +@vindex ediff-use-last-dir +Controls the way Ediff presents the +default directory when it prompts the user for files to compare. If +@code{nil}, +Ediff uses the default directory of the current buffer when it +prompts the user for file names. Otherwise, it will use the +directories it had previously used for files A, B, or C, respectively. + +@item ediff-no-emacs-help-in-control-buffer +@vindex ediff-no-emacs-help-in-control-buffer +If @code{t}, makes @kbd{C-h} +behave like the @key{DEL} key, i.e., it will move you back to the previous +difference rather than invoking help. This is useful when, in an xterm +window or a text-only terminal, the Backspace key is bound to @kbd{C-h} and is +positioned more conveniently than the @key{DEL} key. + +@item ediff-toggle-read-only-function +@vindex ediff-toggle-read-only-function +This variable's value is a function that Ediff uses to toggle +the read-only property in its buffers. + +The default function that Ediff uses simply toggles the read-only property, +unless the file is under version control. For a checked-in file under +version control, Ediff first tries to check the file out. + +@item ediff-make-buffers-readonly-at-startup nil +@vindex ediff-make-buffers-readonly-at-startup +If t, all variant buffers are made read-only at Ediff startup. + +@item ediff-keep-variants +@vindex @code{ediff-keep-variants} +The default is @code{t}, meaning that the buffers being compared or merged will +be preserved when Ediff quits. Setting this to @code{nil} causes Ediff to +offer the user a chance to delete these buffers (if they are not modified). +Supplying a prefix argument to the quit command (@code{q}) temporarily +reverses the meaning of this variable. This is convenient when the user +prefers one of the behaviors most of the time, but occasionally needs the +other behavior. + +However, Ediff temporarily resets this variable to @code{t} if it is +invoked via one of the "buffer" jobs, such as @code{ediff-buffers}. +This is because it is all too easy to loose day's work otherwise. +Besides, in a "buffer" job, the variant buffers have already been loaded +prior to starting Ediff, so Ediff just preserves status quo here. + +Using @code{ediff-cleanup-hook}, one can make Ediff delete the variants +unconditionally (e.g., by making @code{ediff-janitor} into one of these hooks). +@item ediff-grab-mouse +@vindex @code{ediff-grab-mouse} +Default is @code{t}. Normally, Ediff grabs mouse and puts it in its +control frame. This is useful since the user can be sure that when he +needs to type an Ediff command the focus will be in an appropriate Ediff's +frame. However, some users prefer to move the mouse by themselves. The +above variable, if set to @code{maybe}, will prevent Ediff from grabbing +the mouse in many situations, usually after commands that may take more +time than usual. In other situation, Ediff will continue grabbing the mouse +and putting it where it believes is appropriate. If the value is +@code{nil}, then mouse is entirely user's responsibility. +Try different settings and see which one is for you. +@end table + + +@node Notes on Heavy-duty Customization, , Miscellaneous, Customization +@section Notes on Heavy-duty Customization + +Some users need to customize Ediff in rather sophisticated ways, which +requires different defaults for different kinds of files (e.g., SGML, +etc.). Ediff supports this kind of customization in several ways. First, +most customization variables are buffer-local. Those that aren't are +usually accessible from within Ediff Control Panel, so one can make them +local to the panel by calling make-local-variable from within +@code{ediff-startup-hook}. + +Second, the function @code{ediff-setup} accepts an optional sixth +argument which has the form @code{((@var{var-name-1} .@: @var{val-1}) +(@var{var-name-2} .@: @var{val-2}) @dots{})}. The function +@code{ediff-setup} sets the variables in the list to the respective +values, locally in the Ediff control buffer. This is an easy way to +throw in custom variables (which usually should be buffer-local) that +can then be tested in various hooks. + +Make sure the variable @code{ediff-job-name} and @code{ediff-word-mode} are set +properly in this case, as some things in Ediff depend on this. + +Finally, if you want custom-tailored help messages, you can set the +variables @code{ediff-brief-help-message-function} and +@code{ediff-long-help-message-function} +to functions that return help strings. +@vindex ediff-startup-hook +@findex ediff-setup +@vindex ediff-job-name +@vindex ediff-word-mode +@vindex ediff-brief-help-message-function +@vindex ediff-long-help-message-function + +When customizing Ediff, some other variables are useful, although they are +not user-definable. They are local to the Ediff control buffer, so this +buffer must be current when you access these variables. The control buffer +is accessible via the variable @code{ediff-control-buffer}, which is also +local to that buffer. It is usually used for checking if the current buffer +is also the control buffer. + +Other variables of interest are: +@table @code +@item ediff-buffer-A +The first of the data buffers being compared. + +@item ediff-buffer-B +The second of the data buffers being compared. + +@item ediff-buffer-C +In three-way comparisons, this is the third buffer being compared. +In merging, this is the merge buffer. +In two-way comparison, this variable is nil. + +@item ediff-window-A +The window displaying buffer A. If buffer A is not visible, this variable +is nil or it may be a dead window. + +@item ediff-window-B +The window displaying buffer B. + +@item ediff-window-C +The window displaying buffer C, if any. + +@item ediff-control-frame +A dedicated frame displaying the control buffer, if it exists. +It is non-nil only if Ediff uses the multiframe display, i.e., when the +control buffer is in its own frame. +@end table + +@node Credits, Index, Customization, Top +@chapter Credits + +Ediff was written by Michael Kifer <kifer@@cs.sunysb.edu>. It was inspired +by emerge.el written by Dale R.@: Worley <drw@@math.mit.edu>. An idea due to +Boris Goldowsky <boris@@cs.rochester.edu> made it possible to highlight +fine differences in Ediff buffers. Alastair Burt <burt@@dfki.uni-kl.de> +ported Ediff to XEmacs, Eric Freudenthal <freudent@@jan.ultra.nyu.edu> +made it work with VC, Marc Paquette <marcpa@@cam.org> wrote the +toolbar support package for Ediff, and Hrvoje Niksic <hniksic@@srce.hr> +adapted it to the Emacs customization package. + +Many people provided help with bug reports, patches, and advice. +Without them, Ediff would not be nearly as useful as it is today. +Here is a full list of contributors (I hope I didn't miss anyone): + +@example +Steve Baur (steve@@xemacs.org), +Neal Becker (neal@@ctd.comsat.com), +E.@: Jay Berkenbilt (ejb@@ql.org), +Alastair Burt (burt@@dfki.uni-kl.de), +Paul Bibilo (peb@@delcam.co.uk), +Kevin Broadey (KevinB@@bartley.demon.co.uk), +Harald Boegeholz (hwb@@machnix.mathematik.uni-stuttgart.de), +Bradley A.@: Bosch (brad@@lachman.com), +Michael D.@: Carney (carney@@ltx-tr.com), +Jin S.@: Choi (jin@@atype.com), +Scott Cummings (cummings@@adc.com), +Albert Dvornik (bert@@mit.edu), +Eric Eide (eeide@@asylum.cs.utah.edu), +Paul Eggert (eggert@@twinsun.com), +Kevin Esler (esler@@ch.hp.com), +Robert Estes (estes@@ece.ucdavis.edu), +Jay Finger (jayf@@microsoft.com), +Xavier Fornari (xavier@@europe.cma.fr), +Eric Freudenthal (freudent@@jan.ultra.nyu.edu), +Job Ganzevoort (Job.Ganzevoort@@cwi.nl), +Boris Goldowsky (boris@@cs.rochester.edu), +Allan Gottlieb (gottlieb@@allan.ultra.nyu.edu), +Thorbjoern Hansen (thorbjoern.hansen@@mchp.siemens.de), +Xiaoli Huang (hxl@@epic.com), +Lars Magne Ingebrigtsen (larsi@@ifi.uio.no), +Larry Gouge (larry@@itginc.com), +Karl Heuer (kwzh@@gnu.org), +(irvine@@lks.csi.com), +(jaffe@@chipmunk.cita.utoronto.ca), +David Karr (dkarr@@nmo.gtegsc.com), +Norbert Kiesel (norbert@@i3.informatik.rwth-aachen.de), +Leigh L Klotz (klotz@@adoc.xerox.com), +Fritz Knabe (Fritz.Knabe@@ecrc.de), +Heinz Knutzen (hk@@informatik.uni-kiel.d400.de), +Andrew Koenig (ark@@research.att.com), +Ken Laprade (laprade@@dw3f.ess.harris.com), +Will C Lauer (wcl@@cadre.com), +Richard Levitte (levitte@@e.kth.se), +Mike Long (mike.long@@analog.com), +Martin Maechler (maechler@@stat.math.ethz.ch), +Simon Marshall (simon@@gnu.org), +Richard Mlynarik (mly@@adoc.xerox.com), +Chris Murphy (murphycm@@sun.aston.ac.uk), +Erik Naggum (erik@@naggum.no), +Eyvind Ness (Eyvind.Ness@@hrp.no), +Ray Nickson (nickson@@cs.uq.oz.au), +David Petchey (petchey_david@@jpmorgan.com), +Benjamin Pierce (benjamin.pierce@@cl.cam.ac.uk), +Tibor Polgar (tlp00@@spg.amdahl.com), +David Prince (dave0d@@fegs.co.uk), +Paul Raines (raines@@slac.stanford.edu), +Bill Richter (richter@@math.nwu.edu), +C.S.@: Roberson (roberson@@aur.alcatel.com), +Kevin Rodgers (kevin.rodgers@@ihs.com), +Sandy Rutherford (sandy@@ibm550.sissa.it), +Heribert Schuetz (schuetz@@ecrc.de), +Andy Scott (ascott@@pcocd2.intel.com), +Axel Seibert (axel@@tumbolia.ppp.informatik.uni-muenchen.de), +Scott O.@: Sherman (Scott.Sherman@@mci.com), +Richard Stallman (rms@@gnu.org), +Richard Stanton (stanton@@haas.berkeley.edu), +Ake Stenhoff (etxaksf@@aom.ericsson.se), +Stig (stig@@hackvan.com), +Peter Stout (Peter_Stout@@cs.cmu.edu), +Chuck Thompson (cthomp@@cs.uiuc.edu), +Ray Tomlinson (tomlinso@@bbn.com), +Raymond Toy (toy@@rtp.ericsson.se), +Jan Vroonhof (vroonhof@@math.ethz.ch), +Philippe Waroquiers (philippe.waroquiers@@eurocontrol.be), +Klaus Weber (gizmo@@zork.north.de), +Ben Wing (wing@@666.com), +Ilya Zakharevich (ilya@@math.ohio-state.edu), +Eli Zaretskii (eliz@@is.elta.co.il) +@end example + +@node Index, , Credits, Top +@unnumbered Index +@printindex cp + +@contents +@bye diff --git a/man/entering.texi b/man/entering.texi new file mode 100644 index 00000000000..3835b47f376 --- /dev/null +++ b/man/entering.texi @@ -0,0 +1,136 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Entering Emacs, Exiting, Text Characters, Top +@chapter Entering and Exiting Emacs +@cindex entering Emacs +@cindex starting Emacs + + The usual way to invoke Emacs is with the shell command @samp{emacs}. +Emacs clears the screen and then displays an initial help message and +copyright notice. Some operating systems discard all type-ahead when +Emacs starts up; they give Emacs no way to prevent this. Therefore, it +is advisable to wait until Emacs clears the screen before typing your +first editing command. + + If you run Emacs from a shell window under the X Window System, run it +in the background with @samp{emacs&}. This way, Emacs does not tie up +the shell window, so you can use that to run other shell commands while +Emacs operates its own X windows. You can begin typing Emacs commands +as soon as you direct your keyboard input to the Emacs frame. + +@vindex initial-major-mode + When Emacs starts up, it makes a buffer named @samp{*scratch*}. +That's the buffer you start out in. The @samp{*scratch*} buffer uses Lisp +Interaction mode; you can use it to type Lisp expressions and evaluate +them, or you can ignore that capability and simply doodle. (You can +specify a different major mode for this buffer by setting the variable +@code{initial-major-mode} in your init file. @xref{Init File}.) + + It is possible to specify files to be visited, Lisp files to be +loaded, and functions to be called, by giving Emacs arguments in the +shell command line. @xref{Command Arguments}. But we don't recommend +doing this. The feature exists mainly for compatibility with other +editors. + + Many other editors are designed to be started afresh each time you +want to edit. You edit one file and then exit the editor. The next +time you want to edit either another file or the same one, you must run +the editor again. With these editors, it makes sense to use a +command-line argument to say which file to edit. + + But starting a new Emacs each time you want to edit a different file +does not make sense. For one thing, this would be annoyingly slow. For +another, this would fail to take advantage of Emacs's ability to visit +more than one file in a single editing session. And it would lose the +other accumulated context, such as registers, undo history, and the mark +ring. + + The recommended way to use GNU Emacs is to start it only once, just +after you log in, and do all your editing in the same Emacs session. +Each time you want to edit a different file, you visit it with the +existing Emacs, which eventually comes to have many files in it ready +for editing. Usually you do not kill the Emacs until you are about to +log out. @xref{Files}, for more information on visiting more than one +file. + +@node Exiting, Basic, Entering Emacs, Top +@section Exiting Emacs +@cindex exiting +@cindex killing Emacs +@cindex suspending +@cindex leaving Emacs +@cindex quitting Emacs + + There are two commands for exiting Emacs because there are two kinds +of exiting: @dfn{suspending} Emacs and @dfn{killing} Emacs. + + @dfn{Suspending} means stopping Emacs temporarily and returning +control to its parent process (usually a shell), allowing you to resume +editing later in the same Emacs job, with the same buffers, same kill +ring, same undo history, and so on. This is the usual way to exit. + + @dfn{Killing} Emacs means destroying the Emacs job. You can run Emacs +again later, but you will get a fresh Emacs; there is no way to resume +the same editing session after it has been killed. + +@table @kbd +@item C-z +Suspend Emacs (@code{suspend-emacs}) or iconify a frame +(@code{iconify-or-deiconify-frame}). +@item C-x C-c +Kill Emacs (@code{save-buffers-kill-emacs}). +@end table + +@kindex C-z +@findex suspend-emacs + To suspend Emacs, type @kbd{C-z} (@code{suspend-emacs}). This takes +you back to the shell from which you invoked Emacs. You can resume +Emacs with the shell command @samp{%emacs} in most common shells. + + On systems that do not support suspending programs, @kbd{C-z} starts +an inferior shell that communicates directly with the terminal. +Emacs waits until you exit the subshell. (The way to do that is +probably with @kbd{C-d} or @samp{exit}, but it depends on which shell +you use.) The only way on these systems to get back to the shell from +which Emacs was run (to log out, for example) is to kill Emacs. + + Suspending also fails if you run Emacs under a shell that doesn't +support suspending programs, even if the system itself does support it. +In such a case, you can set the variable @code{cannot-suspend} to a +non-@code{nil} value to force @kbd{C-z} to start an inferior shell. +(One might also describe Emacs's parent shell as ``inferior'' for +failing to support job control properly, but that is a matter of taste.) + + When Emacs communicates directly with an X server and creates its own +dedicated X windows, @kbd{C-z} has a different meaning. Suspending an +applications that uses its own X windows is not meaningful or useful. +Instead, @kbd{C-z} runs the command @code{iconify-or-deiconify-frame}, +which temporarily closes up the selected Emacs frame (@pxref{Frames}). +The way to get back to a shell window is with the window manager. + +@kindex C-x C-c +@findex save-buffers-kill-emacs + To kill Emacs, type @kbd{C-x C-c} (@code{save-buffers-kill-emacs}). A +two-character key is used for this to make it harder to type. This +command first offers to save any modified file-visiting buffers. If you +do not save them all, it asks for reconfirmation with @kbd{yes} before +killing Emacs, since any changes not saved will be lost forever. Also, +if any subprocesses are still running, @kbd{C-x C-c} asks for +confirmation about them, since killing Emacs will kill the subprocesses +immediately. + + There is no way to restart an Emacs session once you have killed it. +You can, however, arrange for Emacs to record certain session +information, such as which files are visited, when you kill it, so that +the next time you restart Emacs it will try to visit the same files and +so on. @xref{Saving Emacs Sessions}. + + The operating system usually listens for certain special characters +whose meaning is to kill or suspend the program you are running. +@b{This operating system feature is turned off while you are in Emacs.} +The meanings of @kbd{C-z} and @kbd{C-x C-c} as keys in Emacs were +inspired by the use of @kbd{C-z} and @kbd{C-c} on several operating +systems as the characters for stopping or killing a program, but that is +their only relationship with the operating system. You can customize +these keys to run any commands of your choice (@pxref{Keymaps}). diff --git a/man/files.texi b/man/files.texi new file mode 100644 index 00000000000..375615731d2 --- /dev/null +++ b/man/files.texi @@ -0,0 +1,2413 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Files, Buffers, Fixit, Top +@chapter File Handling +@cindex files + + The operating system stores data permanently in named @dfn{files}. So +most of the text you edit with Emacs comes from a file and is ultimately +stored in a file. + + To edit a file, you must tell Emacs to read the file and prepare a +buffer containing a copy of the file's text. This is called +@dfn{visiting} the file. Editing commands apply directly to text in the +buffer; that is, to the copy inside Emacs. Your changes appear in the +file itself only when you @dfn{save} the buffer back into the file. + + In addition to visiting and saving files, Emacs can delete, copy, +rename, and append to files, keep multiple versions of them, and operate +on file directories. + +@menu +* File Names:: How to type and edit file-name arguments. +* Visiting:: Visiting a file prepares Emacs to edit the file. +* Saving:: Saving makes your changes permanent. +* Reverting:: Reverting cancels all the changes not saved. +* Auto Save:: Auto Save periodically protects against loss of data. +* File Aliases:: Handling multiple names for one file. +* Version Control:: Version control systems (RCS, CVS and SCCS). +* Directories:: Creating, deleting, and listing file directories. +* Comparing Files:: Finding where two files differ. +* Misc File Ops:: Other things you can do on files. +* Compressed Files:: Accessing compressed files. +* Remote Files:: Accessing files on other sites. +* Quoted File Names:: Quoting special characters in file names. +@end menu + +@node File Names +@section File Names +@cindex file names + + Most Emacs commands that operate on a file require you to specify the +file name. (Saving and reverting are exceptions; the buffer knows which +file name to use for them.) You enter the file name using the +minibuffer (@pxref{Minibuffer}). @dfn{Completion} is available, to make +it easier to specify long file names. @xref{Completion}. + + For most operations, there is a @dfn{default file name} which is used +if you type just @key{RET} to enter an empty argument. Normally the +default file name is the name of the file visited in the current buffer; +this makes it easy to operate on that file with any of the Emacs file +commands. + +@vindex default-directory + Each buffer has a default directory, normally the same as the +directory of the file visited in that buffer. When you enter a file +name without a directory, the default directory is used. If you specify +a directory in a relative fashion, with a name that does not start with +a slash, it is interpreted with respect to the default directory. The +default directory is kept in the variable @code{default-directory}, +which has a separate value in every buffer. + + For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} then +the default directory is @file{/u/rms/gnu/}. If you type just @samp{foo}, +which does not specify a directory, it is short for @file{/u/rms/gnu/foo}. +@samp{../.login} would stand for @file{/u/rms/.login}. @samp{new/foo} +would stand for the file name @file{/u/rms/gnu/new/foo}. + +@findex cd +@findex pwd + The command @kbd{M-x pwd} prints the current buffer's default +directory, and the command @kbd{M-x cd} sets it (to a value read using +the minibuffer). A buffer's default directory changes only when the +@code{cd} command is used. A file-visiting buffer's default directory +is initialized to the directory of the file that is visited there. If +you create a buffer with @kbd{C-x b}, its default directory is copied +from that of the buffer that was current at the time. + +@vindex insert-default-directory + The default directory actually appears in the minibuffer when the +minibuffer becomes active to read a file name. This serves two +purposes: it @emph{shows} you what the default is, so that you can type +a relative file name and know with certainty what it will mean, and it +allows you to @emph{edit} the default to specify a different directory. +This insertion of the default directory is inhibited if the variable +@code{insert-default-directory} is set to @code{nil}. + + Note that it is legitimate to type an absolute file name after you +enter the minibuffer, ignoring the presence of the default directory +name as part of the text. The final minibuffer contents may look +invalid, but that is not so. For example, if the minibuffer starts out +with @samp{/usr/tmp/} and you add @samp{/x1/rms/foo}, you get +@samp{/usr/tmp//x1/rms/foo}; but Emacs ignores everything through the +first slash in the double slash; the result is @samp{/x1/rms/foo}. +@xref{Minibuffer File}. + + @samp{$} in a file name is used to substitute environment variables. +For example, if you have used the shell command @samp{export +FOO=rms/hacks} to set up an environment variable named @code{FOO}, then +you can use @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an +abbreviation for @file{/u/rms/hacks/test.c}. The environment variable +name consists of all the alphanumeric characters after the @samp{$}; +alternatively, it may be enclosed in braces after the @samp{$}. Note +that shell commands to set environment variables affect Emacs only if +done before Emacs is started. + + To access a file with @samp{$} in its name, type @samp{$$}. This pair +is converted to a single @samp{$} at the same time as variable +substitution is performed for single @samp{$}. Alternatively, quote the +whole file name with @samp{/:} (@pxref{Quoted File Names}). + +@findex substitute-in-file-name + The Lisp function that performs the substitution is called +@code{substitute-in-file-name}. The substitution is performed only on +file names read as such using the minibuffer. + + You can include non-ASCII characters in file names if you set the +variable @code{file-name-coding-system} to a non-@code{nil} value. +@xref{Specify Coding}. + +@node Visiting +@section Visiting Files +@cindex visiting files + +@c WideCommands +@table @kbd +@item C-x C-f +Visit a file (@code{find-file}). +@item C-x C-r +Visit a file for viewing, without allowing changes to it +(@code{find-file-read-only}). +@item C-x C-v +Visit a different file instead of the one visited last +(@code{find-alternate-file}). +@item C-x 4 f +Visit a file, in another window (@code{find-file-other-window}). Don't +alter what is displayed in the selected window. +@item C-x 5 f +Visit a file, in a new frame (@code{find-file-other-frame}). Don't +alter what is displayed in the selected frame. +@item M-x find-file-literally +Visit a file with no conversion of the contents. +@end table + +@cindex files, visiting and saving +@cindex visiting files +@cindex saving files + @dfn{Visiting} a file means copying its contents into an Emacs buffer +so you can edit them. Emacs makes a new buffer for each file that you +visit. We say that this buffer is visiting the file that it was created +to hold. Emacs constructs the buffer name from the file name by +throwing away the directory, keeping just the name proper. For example, +a file named @file{/usr/rms/emacs.tex} would get a buffer named +@samp{emacs.tex}. If there is already a buffer with that name, a unique +name is constructed by appending @samp{<2>}, @samp{<3>}, or so on, using +the lowest number that makes a name that is not already in use. + + Each window's mode line shows the name of the buffer that is being displayed +in that window, so you can always tell what buffer you are editing. + + The changes you make with editing commands are made in the Emacs +buffer. They do not take effect in the file that you visited, or any +place permanent, until you @dfn{save} the buffer. Saving the buffer +means that Emacs writes the current contents of the buffer into its +visited file. @xref{Saving}. + +@cindex modified (buffer) + If a buffer contains changes that have not been saved, we say the +buffer is @dfn{modified}. This is important because it implies that +some changes will be lost if the buffer is not saved. The mode line +displays two stars near the left margin to indicate that the buffer is +modified. + +@kindex C-x C-f +@findex find-file + To visit a file, use the command @kbd{C-x C-f} (@code{find-file}). Follow +the command with the name of the file you wish to visit, terminated by a +@key{RET}. + + The file name is read using the minibuffer (@pxref{Minibuffer}), with +defaulting and completion in the standard manner (@pxref{File Names}). +While in the minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}. + + Your confirmation that @kbd{C-x C-f} has completed successfully is the +appearance of new text on the screen and a new buffer name in the mode +line. If the specified file does not exist and could not be created, or +cannot be read, then you get an error, with an error message displayed +in the echo area. + + If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make +another copy. It selects the existing buffer containing that file. +However, before doing so, it checks that the file itself has not changed +since you visited or saved it last. If the file has changed, a warning +message is printed. @xref{Interlocking,,Simultaneous Editing}. + +@cindex creating files + What if you want to create a new file? Just visit it. Emacs prints +@samp{(New File)} in the echo area, but in other respects behaves as if +you had visited an existing empty file. If you make any changes and +save them, the file is created. + + Emacs recognizes from the contents of a file which convention it uses +to separate lines---newline (used on GNU/Linux and on Unix), +carriage-return linefeed (used on Microsoft systems), or just +carriage-return (used on the Macintosh)---and automatically converts the +contents to the normal Emacs convention, which is that the newline +character separates lines. This is a part of the general feature of +coding system conversion (@pxref{Coding Systems}), and makes it possible +to edit files imported from various different operating systems with +equal convenience. If you change the text and save the file, Emacs +performs the inverse conversion, changing newlines back into +carriage-return linefeed or just carriage-return if appropriate. + +@vindex find-file-run-dired + If the file you specify is actually a directory, @kbd{C-x C-f} invokes +Dired, the Emacs directory browser, so that you can ``edit'' the contents +of the directory (@pxref{Dired}). Dired is a convenient way to delete, +look at, or operate on the files in the directory. However, if the +variable @code{find-file-run-dired} is @code{nil}, then it is an error +to try to visit a directory. + + If the file name you specify contains wildcard characters, Emacs +visits all the files that match it. @xref{Quoted File Names}, if you +want to visit a file whose name actually contains wildcard characters. + + If you visit a file that the operating system won't let you modify, +Emacs makes the buffer read-only, so that you won't go ahead and make +changes that you'll have trouble saving afterward. You can make the +buffer writable with @kbd{C-x C-q} (@code{vc-toggle-read-only}). +@xref{Misc Buffer}. + +@kindex C-x C-r +@findex find-file-read-only + Occasionally you might want to visit a file as read-only in order to +protect yourself from entering changes accidentally; do so by visiting +the file with the command @kbd{C-x C-r} (@code{find-file-read-only}). + +@kindex C-x C-v +@findex find-alternate-file + If you visit a nonexistent file unintentionally (because you typed the +wrong file name), use the @kbd{C-x C-v} command +(@code{find-alternate-file}) to visit the file you really wanted. +@kbd{C-x C-v} is similar to @kbd{C-x C-f}, but it kills the current +buffer (after first offering to save it if it is modified). When it +reads the file name to visit, it inserts the entire default file name in +the buffer, with point just after the directory part; this is convenient +if you made a slight error in typing the name. + + If you find a file which exists but cannot be read, @kbd{C-x C-f} +signals an error. + +@kindex C-x 4 f +@findex find-file-other-window + @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f} +except that the buffer containing the specified file is selected in another +window. The window that was selected before @kbd{C-x 4 f} continues to +show the same buffer it was already showing. If this command is used when +only one window is being displayed, that window is split in two, with one +window showing the same buffer as before, and the other one showing the +newly requested file. @xref{Windows}. + +@kindex C-x 5 f +@findex find-file-other-frame + @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a +new frame, or makes visible any existing frame showing the file you +seek. This feature is available only when you are using a window +system. @xref{Frames}. + +@findex find-file-literally + If you wish to edit a file as a sequence of characters with no special +encoding or conversion, use the @kbd{M-x find-file-literally} command. +It visits a file, like @kbd{C-x C-f}, but does not do format conversion +(@pxref{Formatted Text}), character code conversion (@pxref{Coding +Systems}), or automatic uncompression (@pxref{Compressed Files}). +If you already have visited the same file in the usual (non-literal) +manner, this command asks you whether to visit it literally instead. + +@vindex find-file-hooks +@vindex find-file-not-found-hooks + Two special hook variables allow extensions to modify the operation of +visiting files. Visiting a file that does not exist runs the functions +in the list @code{find-file-not-found-hooks}; this variable holds a list +of functions, and the functions are called one by one (with no +arguments) until one of them returns non-@code{nil}. This is not a +normal hook, and the name ends in @samp{-hooks} rather than @samp{-hook} +to indicate that fact. + + Any visiting of a file, whether extant or not, expects +@code{find-file-hooks} to contain a list of functions, and calls them +all, one by one, with no arguments. This variable is really a normal +hook, but it has an abnormal name for historical compatibility. In the +case of a nonexistent file, the @code{find-file-not-found-hooks} are run +first. @xref{Hooks}. + + There are several ways to specify automatically the major mode for +editing the file (@pxref{Choosing Modes}), and to specify local +variables defined for that file (@pxref{File Variables}). + +@node Saving +@section Saving Files + + @dfn{Saving} a buffer in Emacs means writing its contents back into the file +that was visited in the buffer. + +@table @kbd +@item C-x C-s +Save the current buffer in its visited file (@code{save-buffer}). +@item C-x s +Save any or all buffers in their visited files (@code{save-some-buffers}). +@item M-~ +Forget that the current buffer has been changed (@code{not-modified}). +@item C-x C-w +Save the current buffer in a specified file (@code{write-file}). +@item M-x set-visited-file-name +Change file the name under which the current buffer will be saved. +@end table + +@kindex C-x C-s +@findex save-buffer + When you wish to save the file and make your changes permanent, type +@kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s} +displays a message like this: + +@example +Wrote /u/rms/gnu/gnu.tasks +@end example + +@noindent +If the selected buffer is not modified (no changes have been made in it +since the buffer was created or last saved), saving is not really done, +because it would have no effect. Instead, @kbd{C-x C-s} displays a message +like this in the echo area: + +@example +(No changes need to be saved) +@end example + +@kindex C-x s +@findex save-some-buffers + The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any +or all modified buffers. It asks you what to do with each buffer. The +possible responses are analogous to those of @code{query-replace}: + +@table @kbd +@item y +Save this buffer and ask about the rest of the buffers. +@item n +Don't save this buffer, but ask about the rest of the buffers. +@item ! +Save this buffer and all the rest with no more questions. +@c following generates acceptable underfull hbox +@item @key{RET} +Terminate @code{save-some-buffers} without any more saving. +@item . +Save this buffer, then exit @code{save-some-buffers} without even asking +about other buffers. +@item C-r +View the buffer that you are currently being asked about. When you exit +View mode, you get back to @code{save-some-buffers}, which asks the +question again. +@item C-h +Display a help message about these options. +@end table + + @kbd{C-x C-c}, the key sequence to exit Emacs, invokes +@code{save-some-buffers} and therefore asks the same questions. + +@kindex M-~ +@findex not-modified + If you have changed a buffer but you do not want to save the changes, +you should take some action to prevent it. Otherwise, each time you use +@kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer by +mistake. One thing you can do is type @kbd{M-~} (@code{not-modified}), +which clears out the indication that the buffer is modified. If you do +this, none of the save commands will believe that the buffer needs to be +saved. (@samp{~} is often used as a mathematical symbol for `not'; thus +@kbd{M-~} is `not', metafied.) You could also use +@code{set-visited-file-name} (see below) to mark the buffer as visiting +a different file name, one which is not in use for anything important. +Alternatively, you can cancel all the changes made since the file was +visited or saved, by reading the text from the file again. This is +called @dfn{reverting}. @xref{Reverting}. You could also undo all the +changes by repeating the undo command @kbd{C-x u} until you have undone +all the changes; but reverting is easier. + +@findex set-visited-file-name + @kbd{M-x set-visited-file-name} alters the name of the file that the +current buffer is visiting. It reads the new file name using the +minibuffer. Then it specifies the visited file name and changes the +buffer name correspondingly (as long as the new name is not in use). +@code{set-visited-file-name} does not save the buffer in the newly +visited file; it just alters the records inside Emacs in case you do +save later. It also marks the buffer as ``modified'' so that @kbd{C-x +C-s} in that buffer @emph{will} save. + +@kindex C-x C-w +@findex write-file + If you wish to mark the buffer as visiting a different file and save it +right away, use @kbd{C-x C-w} (@code{write-file}). It is precisely +equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}. +@kbd{C-x C-s} used on a buffer that is not visiting a file has the +same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the +buffer as visiting that file, and saves it there. The default file name in +a buffer that is not visiting a file is made by combining the buffer name +with the buffer's default directory. + + If the new file name implies a major mode, then @kbd{C-x C-w} switches +to that major mode, in most cases. The command +@code{set-visited-file-name} also does this. @xref{Choosing Modes}. + + If Emacs is about to save a file and sees that the date of the latest +version on disk does not match what Emacs last read or wrote, Emacs +notifies you of this fact, because it probably indicates a problem caused +by simultaneous editing and requires your immediate attention. +@xref{Interlocking,, Simultaneous Editing}. + +@vindex require-final-newline + If the variable @code{require-final-newline} is non-@code{nil}, Emacs +puts a newline at the end of any file that doesn't already end in one, +every time a file is saved or written. The default is @code{nil}. + +@menu +* Backup:: How Emacs saves the old version of your file. +* Interlocking:: How Emacs protects against simultaneous editing + of one file by two users. +@end menu + +@node Backup +@subsection Backup Files +@cindex backup file +@vindex make-backup-files +@vindex vc-make-backup-files +@vindex backup-enable-predicate + + On most operating systems, rewriting a file automatically destroys all +record of what the file used to contain. Thus, saving a file from Emacs +throws away the old contents of the file---or it would, except that +Emacs carefully copies the old contents to another file, called the +@dfn{backup} file, before actually saving. + + For most files, the variable @code{make-backup-files} determines +whether to make backup files. On most operating systems, its default +value is @code{t}, so that Emacs does write backup files. + + For files managed by a version control system (@pxref{Version +Control}), the variable @code{vc-make-backup-files} determines whether +to make backup files. By default, it is @code{nil}, since backup files +are redundant when you store all the previous versions in a version +control system. @xref{VC Workfile Handling}. + + The default value of the @code{backup-enable-predicate} variable +prevents backup files being written for files in @file{/tmp}. + + At your option, Emacs can keep either a single backup file or a series of +numbered backup files for each file that you edit. + + Emacs makes a backup for a file only the first time the file is saved +from one buffer. No matter how many times you save a file, its backup file +continues to contain the contents from before the file was visited. +Normally this means that the backup file contains the contents from before +the current editing session; however, if you kill the buffer and then visit +the file again, a new backup file will be made by the next save. + + You can also explicitly request making another backup file from a +buffer even though it has already been saved at least once. If you save +the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made +into a backup file if you save the buffer again. @kbd{C-u C-u C-x C-s} +saves the buffer, but first makes the previous file contents into a new +backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it makes a +backup from the previous contents, and arranges to make another from the +newly saved contents, if you save again. + +@menu +* Names: Backup Names. How backup files are named; + choosing single or numbered backup files. +* Deletion: Backup Deletion. Emacs deletes excess numbered backups. +* Copying: Backup Copying. Backups can be made by copying or renaming. +@end menu + +@node Backup Names +@subsubsection Single or Numbered Backups + + If you choose to have a single backup file (this is the default), +the backup file's name is constructed by appending @samp{~} to the +file name being edited; thus, the backup file for @file{eval.c} would +be @file{eval.c~}. + + If you choose to have a series of numbered backup files, backup file +names are made by appending @samp{.~}, the number, and another @samp{~} to +the original file name. Thus, the backup files of @file{eval.c} would be +called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, through names +like @file{eval.c.~259~} and beyond. + + If protection stops you from writing backup files under the usual names, +the backup file is written as @file{%backup%~} in your home directory. +Only one such file can exist, so only the most recently made such backup is +available. + +@vindex version-control + The choice of single backup or numbered backups is controlled by the +variable @code{version-control}. Its possible values are + +@table @code +@item t +Make numbered backups. +@item nil +Make numbered backups for files that have numbered backups already. +Otherwise, make single backups. +@item never +Do not in any case make numbered backups; always make single backups. +@end table + +@noindent +You can set @code{version-control} locally in an individual buffer to +control the making of backups for that buffer's file. For example, +Rmail mode locally sets @code{version-control} to @code{never} to make sure +that there is only one backup for an Rmail file. @xref{Locals}. + +@cindex @code{VERSION_CONTROL} environment variable + If you set the environment variable @code{VERSION_CONTROL}, to tell +various GNU utilities what to do with backup files, Emacs also obeys the +environment variable by setting the Lisp variable @code{version-control} +accordingly at startup. If the environment variable's value is @samp{t} +or @samp{numbered}, then @code{version-control} becomes @code{t}; if the +value is @samp{nil} or @samp{existing}, then @code{version-control} +becomes @code{nil}; if it is @samp{never} or @samp{simple}, then +@code{version-control} becomes @code{never}. + +@node Backup Deletion +@subsubsection Automatic Deletion of Backups + + To prevent unlimited consumption of disk space, Emacs can delete numbered +backup versions automatically. Generally Emacs keeps the first few backups +and the latest few backups, deleting any in between. This happens every +time a new backup is made. + +@vindex kept-old-versions +@vindex kept-new-versions + The two variables @code{kept-old-versions} and +@code{kept-new-versions} control this deletion. Their values are, +respectively the number of oldest (lowest-numbered) backups to keep and +the number of newest (highest-numbered) ones to keep, each time a new +backup is made. Recall that these values are used just after a new +backup version is made; that newly made backup is included in the count +in @code{kept-new-versions}. By default, both variables are 2. + +@vindex delete-old-versions + If @code{delete-old-versions} is non-@code{nil}, the excess +middle versions are deleted without a murmur. If it is @code{nil}, the +default, then you are asked whether the excess middle versions should +really be deleted. + + Dired's @kbd{.} (Period) command can also be used to delete old versions. +@xref{Dired Deletion}. + +@node Backup Copying +@subsubsection Copying vs.@: Renaming + + Backup files can be made by copying the old file or by renaming it. This +makes a difference when the old file has multiple names. If the old file +is renamed into the backup file, then the alternate names become names for +the backup file. If the old file is copied instead, then the alternate +names remain names for the file that you are editing, and the contents +accessed by those names will be the new contents. + + The method of making a backup file may also affect the file's owner +and group. If copying is used, these do not change. If renaming is used, +you become the file's owner, and the file's group becomes the default +(different operating systems have different defaults for the group). + + Having the owner change is usually a good idea, because then the owner +always shows who last edited the file. Also, the owners of the backups +show who produced those versions. Occasionally there is a file whose +owner should not change; it is a good idea for such files to contain +local variable lists to set @code{backup-by-copying-when-mismatch} +locally (@pxref{File Variables}). + +@vindex backup-by-copying +@vindex backup-by-copying-when-linked +@vindex backup-by-copying-when-mismatch + The choice of renaming or copying is controlled by three variables. +Renaming is the default choice. If the variable +@code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise, +if the variable @code{backup-by-copying-when-linked} is non-@code{nil}, +then copying is used for files that have multiple names, but renaming +may still be used when the file being edited has only one name. If the +variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then +copying is used if renaming would cause the file's owner or group to +change. @code{backup-by-copying-when-mismatch} is @code{t} by default +if you start Emacs as the superuser. + + When a file is managed with a version control system (@pxref{Version +Control}), Emacs does not normally make backups in the usual way for +that file. But check-in and check-out are similar in some ways to +making backups. One unfortunate similarity is that these operations +typically break hard links, disconnecting the file name you visited from +any alternate names for the same file. This has nothing to do with +Emacs---the version control system does it. + +@node Interlocking +@subsection Protection against Simultaneous Editing + +@cindex file dates +@cindex simultaneous editing + Simultaneous editing occurs when two users visit the same file, both +make changes, and then both save them. If nobody were informed that +this was happening, whichever user saved first would later find that his +changes were lost. + + On some systems, Emacs notices immediately when the second user starts +to change the file, and issues an immediate warning. On all systems, +Emacs checks when you save the file, and warns if you are about to +overwrite another user's changes. You can prevent loss of the other +user's work by taking the proper corrective action instead of saving the +file. + +@findex ask-user-about-lock +@cindex locking files + When you make the first modification in an Emacs buffer that is +visiting a file, Emacs records that the file is @dfn{locked} by you. +(It does this by creating a symbolic link in the same directory with a +different name.) Emacs removes the lock when you save the changes. The +idea is that the file is locked whenever an Emacs buffer visiting it has +unsaved changes. + +@cindex collision + If you begin to modify the buffer while the visited file is locked by +someone else, this constitutes a @dfn{collision}. When Emacs detects a +collision, it asks you what to do, by calling the Lisp function +@code{ask-user-about-lock}. You can redefine this function for the sake +of customization. The standard definition of this function asks you a +question and accepts three possible answers: + +@table @kbd +@item s +Steal the lock. Whoever was already changing the file loses the lock, +and you gain the lock. +@item p +Proceed. Go ahead and edit the file despite its being locked by someone else. +@item q +Quit. This causes an error (@code{file-locked}) and the modification you +were trying to make in the buffer does not actually take place. +@end table + + Note that locking works on the basis of a file name; if a file has +multiple names, Emacs does not realize that the two names are the same file +and cannot prevent two users from editing it simultaneously under different +names. However, basing locking on names means that Emacs can interlock the +editing of new files that will not really exist until they are saved. + + Some systems are not configured to allow Emacs to make locks, and +there are cases where lock files cannot be written. In these cases, +Emacs cannot detect trouble in advance, but it still can detect the +collision when you try to save a file and overwrite someone else's +changes. + + If Emacs or the operating system crashes, this may leave behind lock +files which are stale. So you may occasionally get warnings about +spurious collisions. When you determine that the collision is spurious, +just use @kbd{p} to tell Emacs to go ahead anyway. + + Every time Emacs saves a buffer, it first checks the last-modification +date of the existing file on disk to verify that it has not changed since the +file was last visited or saved. If the date does not match, it implies +that changes were made in the file in some other way, and these changes are +about to be lost if Emacs actually does save. To prevent this, Emacs +prints a warning message and asks for confirmation before saving. +Occasionally you will know why the file was changed and know that it does +not matter; then you can answer @kbd{yes} and proceed. Otherwise, you should +cancel the save with @kbd{C-g} and investigate the situation. + + The first thing you should do when notified that simultaneous editing +has already taken place is to list the directory with @kbd{C-u C-x C-d} +(@pxref{Directories}). This shows the file's current author. You +should attempt to contact him to warn him not to continue editing. +Often the next step is to save the contents of your Emacs buffer under a +different name, and use @code{diff} to compare the two files.@refill + +@node Reverting +@section Reverting a Buffer +@findex revert-buffer +@cindex drastic changes + + If you have made extensive changes to a file and then change your mind +about them, you can get rid of them by reading in the previous version +of the file. To do this, use @kbd{M-x revert-buffer}, which operates on +the current buffer. Since reverting a buffer unintentionally could lose +a lot of work, you must confirm this command with @kbd{yes}. + + @code{revert-buffer} keeps point at the same distance (measured in +characters) from the beginning of the file. If the file was edited only +slightly, you will be at approximately the same piece of text after +reverting as before. If you have made drastic changes, the same value of +point in the old file may address a totally different piece of text. + + Reverting marks the buffer as ``not modified'' until another change is +made. + + Some kinds of buffers whose contents reflect data bases other than files, +such as Dired buffers, can also be reverted. For them, reverting means +recalculating their contents from the appropriate data base. Buffers +created explicitly with @kbd{C-x b} cannot be reverted; @code{revert-buffer} +reports an error when asked to do so. + +@vindex revert-without-query + When you edit a file that changes automatically and frequently---for +example, a log of output from a process that continues to run---it may be +useful for Emacs to revert the file without querying you, whenever you +visit the file again with @kbd{C-x C-f}. + + To request this behavior, set the variable @code{revert-without-query} +to a list of regular expressions. When a file name matches one of these +regular expressions, @code{find-file} and @code{revert-buffer} will +revert it automatically if it has changed---provided the buffer itself +is not modified. (If you have edited the text, it would be wrong to +discard your changes.) + +@node Auto Save +@section Auto-Saving: Protection Against Disasters +@cindex Auto Save mode +@cindex mode, Auto Save +@cindex crashes + + Emacs saves all the visited files from time to time (based on counting +your keystrokes) without being asked. This is called @dfn{auto-saving}. +It prevents you from losing more than a limited amount of work if the +system crashes. + + When Emacs determines that it is time for auto-saving, each buffer is +considered, and is auto-saved if auto-saving is turned on for it and it +has been changed since the last time it was auto-saved. The message +@samp{Auto-saving...} is displayed in the echo area during auto-saving, +if any files are actually auto-saved. Errors occurring during +auto-saving are caught so that they do not interfere with the execution +of commands you have been typing. + +@menu +* Files: Auto Save Files. The file where auto-saved changes are + actually made until you save the file. +* Control: Auto Save Control. Controlling when and how often to auto-save. +* Recover:: Recovering text from auto-save files. +@end menu + +@node Auto Save Files +@subsection Auto-Save Files + + Auto-saving does not normally save in the files that you visited, because +it can be very undesirable to save a program that is in an inconsistent +state when you have made half of a planned change. Instead, auto-saving +is done in a different file called the @dfn{auto-save file}, and the +visited file is changed only when you request saving explicitly (such as +with @kbd{C-x C-s}). + + Normally, the auto-save file name is made by appending @samp{#} to the +front and rear of the visited file name. Thus, a buffer visiting file +@file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that +are not visiting files are auto-saved only if you request it explicitly; +when they are auto-saved, the auto-save file name is made by appending +@samp{#%} to the front and @samp{#} to the rear of buffer name. For +example, the @samp{*mail*} buffer in which you compose messages to be +sent is auto-saved in a file named @file{#%*mail*#}. Auto-save file +names are made this way unless you reprogram parts of Emacs to do +something different (the functions @code{make-auto-save-file-name} and +@code{auto-save-file-name-p}). The file name to be used for auto-saving +in a buffer is calculated when auto-saving is turned on in that buffer. + + When you delete a substantial part of the text in a large buffer, auto +save turns off temporarily in that buffer. This is because if you +deleted the text unintentionally, you might find the auto-save file more +useful if it contains the deleted text. To reenable auto-saving after +this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x +auto-save}. + +@vindex auto-save-visited-file-name + If you want auto-saving to be done in the visited file, set the variable +@code{auto-save-visited-file-name} to be non-@code{nil}. In this mode, +there is really no difference between auto-saving and explicit saving. + +@vindex delete-auto-save-files + A buffer's auto-save file is deleted when you save the buffer in its +visited file. To inhibit this, set the variable @code{delete-auto-save-files} +to @code{nil}. Changing the visited file name with @kbd{C-x C-w} or +@code{set-visited-file-name} renames any auto-save file to go with +the new visited name. + +@node Auto Save Control +@subsection Controlling Auto-Saving + +@vindex auto-save-default +@findex auto-save-mode + Each time you visit a file, auto-saving is turned on for that file's +buffer if the variable @code{auto-save-default} is non-@code{nil} (but not +in batch mode; @pxref{Entering Emacs}). The default for this variable is +@code{t}, so auto-saving is the usual practice for file-visiting buffers. +Auto-saving can be turned on or off for any existing buffer with the +command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x +auto-save-mode} turns auto-saving on with a positive argument, off with a +zero or negative argument; with no argument, it toggles. + +@vindex auto-save-interval + Emacs does auto-saving periodically based on counting how many characters +you have typed since the last time auto-saving was done. The variable +@code{auto-save-interval} specifies how many characters there are between +auto-saves. By default, it is 300. + +@vindex auto-save-timeout + Auto-saving also takes place when you stop typing for a while. The +variable @code{auto-save-timeout} says how many seconds Emacs should +wait before it does an auto save (and perhaps also a garbage +collection). (The actual time period is longer if the current buffer is +long; this is a heuristic which aims to keep out of your way when you +are editing long buffers, in which auto-save takes an appreciable amount +of time.) Auto-saving during idle periods accomplishes two things: +first, it makes sure all your work is saved if you go away from the +terminal for a while; second, it may avoid some auto-saving while you +are actually typing. + + Emacs also does auto-saving whenever it gets a fatal error. This +includes killing the Emacs job with a shell command such as @samp{kill +%emacs}, or disconnecting a phone line or network connection. + +@findex do-auto-save + You can request an auto-save explicitly with the command @kbd{M-x +do-auto-save}. + +@node Recover +@subsection Recovering Data from Auto-Saves + +@findex recover-file + You can use the contents of an auto-save file to recover from a loss +of data with the command @kbd{M-x recover-file @key{RET} @var{file} +@key{RET}}. This visits @var{file} and then (after your confirmation) +restores the contents from its auto-save file @file{#@var{file}#}. +You can then save with @kbd{C-x C-s} to put the recovered text into +@var{file} itself. For example, to recover file @file{foo.c} from its +auto-save file @file{#foo.c#}, do:@refill + +@example +M-x recover-file @key{RET} foo.c @key{RET} +yes @key{RET} +C-x C-s +@end example + + Before asking for confirmation, @kbd{M-x recover-file} displays a +directory listing describing the specified file and the auto-save file, +so you can compare their sizes and dates. If the auto-save file +is older, @kbd{M-x recover-file} does not offer to read it. + +@findex recover-session + If Emacs or the computer crashes, you can recover all the files you +were editing from their auto save files with the command @kbd{M-x +recover-session}. This first shows you a list of recorded interrupted +sessions. Move point to the one you choose, and type @kbd{C-c C-c}. + + Then @code{recover-session} asks about each of the files that were +being edited during that session, asking whether to recover that file. +If you answer @kbd{y}, it calls @code{recover-file}, which works in its +normal fashion. It shows the dates of the original file and its +auto-save file, and asks once again whether to recover that file. + + When @code{recover-session} is done, the files you've chosen to +recover are present in Emacs buffers. You should then save them. Only +this---saving them---updates the files themselves. + +@vindex auto-save-list-file-prefix + Interrupted sessions are recorded for later recovery in files named +@file{~/.saves-@var{pid}-@var{hostname}}. The @samp{~/.saves} portion of +these names comes from the value of @code{auto-save-list-file-prefix}. +You can arrange to record sessions in a different place by setting that +variable in your @file{.emacs} file, but you'll have to redefine +@code{recover-session} as well to make it look in the new place. If you +set @code{auto-save-list-file-prefix} to @code{nil} in your +@file{.emacs} file, sessions are not recorded for recovery. + +@node File Aliases +@section File Name Aliases + + Symbolic links and hard links both make it possible for several file +names to refer to the same file. Hard links are alternate names that +refer directly to the file; all the names are equally valid, and no one +of them is preferred. By contrast, a symbolic link is a kind of defined +alias: when @file{foo} is a symbolic link to @file{bar}, you can use +either name to refer to the file, but @file{bar} is the real name, while +@file{foo} is just an alias. More complex cases occur when symbolic +links point to directories. + + If you visit two names for the same file, normally Emacs makes +two different buffers, but it warns you about the situation. + +@vindex find-file-existing-other-name + If you wish to avoid visiting the same file in two buffers under +different names, set the variable @code{find-file-existing-other-name} +to a non-@code{nil} value. Then @code{find-file} uses the existing +buffer visiting the file, no matter which of the file's names you +specify. + +@vindex find-file-visit-truename +@cindex truenames of files +@cindex file truenames + If the variable @code{find-file-visit-truename} is non-@code{nil}, +then the file name recorded for a buffer is the file's @dfn{truename} +(made by replacing all symbolic links with their target names), rather +than the name you specify. Setting @code{find-file-visit-truename} also +implies the effect of @code{find-file-existing-other-name}. + +@node Version Control +@section Version Control +@cindex version control + + @dfn{Version control systems} are packages that can record multiple +versions of a source file, usually storing the unchanged parts of the +file just once. Version control systems also record history information +such as the creation time of each version, who created it, and a +description of what was changed in that version. + + The Emacs version control interface is called VC. Its commands work +with three version control systems---RCS, CVS and SCCS. The GNU project +recommends RCS and CVS, which are free software and available from the +Free Software Foundation. + +@menu +* Introduction to VC:: How version control works in general. +* VC Mode Line:: How the mode line shows version control status. +* Basic VC Editing:: How to edit a file under version control. +* Old Versions:: Examining and comparing old versions. +* Secondary VC Commands:: The commands used a little less frequently. +* Branches:: Multiple lines of development. +* Snapshots:: Sets of file versions treated as a unit. +* Miscellaneous VC:: Various other commands and features of VC. +* Customizing VC:: Variables that change VC's behavior. +@end menu + +@node Introduction to VC +@subsection Introduction to Version Control + + VC allows you to use a version control system from within Emacs, +integrating the version control operations smoothly with editing. VC +provides a uniform interface to version control, so that regardless of +which version control system is in use, you can use it the same way. + + This section provides a general overview of version control, and +describes the version control systems that VC supports. You can skip +this section if you are already familiar with the version control system +you want to use. + +@menu +* Version Systems:: Supported version control back-end systems. +* VC Concepts:: Words and concepts related to version control. +@end menu + +@node Version Systems +@subsubsection Supported Version Control Systems + +@cindex RCS +@cindex back end (version control) + VC currently works with three different version control systems or +``back ends'': RCS, CVS, and SCCS. + + RCS is a free version control system that is available from the Free +Software Foundation. It is perhaps the most mature of the supported +back ends, and the VC commands are conceptually closest to RCS. Almost +everything you can do with RCS can be done through VC. + +@cindex CVS + CVS is built on top of RCS, and extends the features of RCS, allowing +for more sophisticated release management, and concurrent multi-user +development. VC supports basic editing operations under CVS, but for +some less common tasks you still need to call CVS from the command line. +Note also that before using CVS you must set up a repository, which is a +subject too complex to treat here. + +@cindex SCCS + SCCS is a proprietary but widely used version control system. In +terms of capabilities, it is the weakest of the three that VC +supports. VC compensates for certain features missing in SCCS +(snapshots, for example) by implementing them itself, but some other VC +features, such as multiple branches, are not available with SCCS. You +should use SCCS only if for some reason you cannot use RCS. + +@node VC Concepts +@subsubsection Concepts of Version Control + +@cindex master file +@cindex registered file + When a file is under version control, we also say that it is +@dfn{registered} in the version control system. Each registered file +has a corresponding @dfn{master file} which represents the file's +present state plus its change history---enough to reconstruct the +current version or any earlier version. Usually the master file also +records a @dfn{log entry} for each version, describing in words what was +changed in that version. + +@cindex work file +@cindex checking out files + The file that is maintained under version control is sometimes called +the @dfn{work file} corresponding to its master file. You edit the work +file and make changes in it, as you would with an ordinary file. (With +SCCS and RCS, you must @dfn{lock} the file before you start to edit it.) +After you are done with a set of changes, you @dfn{check the file in}, +which records the changes in the master file, along with a log entry for +them. + + With CVS, there are usually multiple work files corresponding to a +single master file---often each user has his own copy. It is also +possible to use RCS in this way, but this is not the usual way to use +RCS. + +@cindex locking and version control + A version control system typically has some mechanism to coordinate +between users who want to change the same file. One method is +@dfn{locking} (analogous to the locking that Emacs uses to detect +simultaneous editing of a file, but distinct from it). The other method +is to merge your changes with other people's changes when you check them +in. + + With version control locking, work files are normally read-only so +that you cannot change them. You ask the version control system to make +a work file writable for you by locking it; only one user can do +this at any given time. When you check in your changes, that unlocks +the file, making the work file read-only again. This allows other users +to lock the file to make further changes. SCCS always uses locking, and +RCS normally does. + + The other alternative for RCS is to let each user modify the work file +at any time. In this mode, locking is not required, but it is +permitted; check-in is still the way to record a new version. + + CVS normally allows each user to modify his own copy of the work file +at any time, but requires merging with changes from other users at +check-in time. However, CVS can also be set up to require locking. +(@pxref{Backend Options}). + +@node VC Mode Line +@subsection Version Control and the Mode Line + + When you visit a file that is under version control, Emacs indicates +this on the mode line. For example, @samp{RCS-1.3} says that RCS is +used for that file, and the current version is 1.3. + + The character between the back-end name and the version number +indicates the version control status of the file. @samp{-} means that +the work file is not locked (if locking is in use), or not modified (if +locking is not in use). @samp{:} indicates that the file is locked, or +that it is modified. If the file is locked by some other user (for +instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}. + +@node Basic VC Editing +@subsection Basic Editing under Version Control + + The principal VC command is an all-purpose command that performs +either locking or check-in, depending on the situation. + +@table @kbd +@item C-x C-q +@itemx C-x v v +Perform the next logical version control operation on this file. +@end table + +@findex vc-next-action +@findex vc-toggle-read-only +@kindex C-x v v +@kindex C-x C-q @r{(Version Control)} + Strictly speaking, the command for this job is @code{vc-next-action}, +bound to @kbd{C-x v v}. However, the normal meaning of @kbd{C-x C-q} is +to make a read-only buffer writable, or vice versa; we have extended it +to do the same job properly for files managed by version control, by +performing the appropriate version control operations. When you type +@kbd{C-x C-q} on a registered file, it acts like @kbd{C-x v v}. + + The precise action of this command depends on the state of the file, +and whether the version control system uses locking or not. SCCS and +RCS normally use locking; CVS normally does not use locking. + +@menu +* VC with Locking:: RCS in its default mode, SCCS, and optionally CVS. +* Without Locking:: Without locking: default mode for CVS. +* Log Buffer:: Features available in log entry buffers. +@end menu + +@node VC with Locking +@subsubsection Basic Version Control with Locking + + If locking is used for the file (as with SCCS, and RCS in its default +mode), @kbd{C-x C-q} can either lock a file or check it in: + +@itemize @bullet +@item +If the file is not locked, @kbd{C-x C-q} locks it, and +makes it writable so that you can change it. + +@item +If the file is locked by you, and contains changes, @kbd{C-x C-q} checks +in the changes. In order to do this, it first reads the log entry +for the new version. @xref{Log Buffer}. + +@item +If the file is locked by you, but you have not changed it since you +locked it, @kbd{C-x C-q} releases the lock and makes the file read-only +again. + +@item +If the file is locked by some other user, @kbd{C-x C-q} asks you whether +you want to ``steal the lock'' from that user. If you say yes, the file +becomes locked by you, but a message is sent to the person who had +formerly locked the file, to inform him of what has happened. +@end itemize + + These rules also apply when you use CVS in locking mode, except +that there is no such thing as stealing a lock. + +@node Without Locking +@subsubsection Basic Version Control without Locking + + When there is no locking---the default for CVS---work files are always +writable; you do not need to do anything before you begin to edit a +file. The status indicator on the mode line is @samp{-} if the file is +unmodified; it flips to @samp{:} as soon as you save any changes in the +work file. + + Here is what @kbd{C-x C-q} does when using CVS: + +@itemize @bullet +@item +If some other user has checked in changes into the master file, +Emacs asks you whether you want to merge those changes into your own +work file (@pxref{Merging}). You must do this before you can check in +your own changes. + +@item +If there are no new changes in the master file, but you have made +modifications in your work file, @kbd{C-x C-q} checks in your changes. +In order to do this, it first reads the log entry for the new version. +@xref{Log Buffer}. + +@item +If the file is not modified, the @kbd{C-x C-q} does nothing. +@end itemize + + These rules also apply when you use RCS in the mode that does not +require locking, except that automatic merging of changes from the +master file is not implemented. Unfortunately, this means that nothing +informs you if another user has checked in changes in the same file +since you began editing it, and when this happens, his changes will be +effectively removed when you check in your version (though they will +remain in the master file, so they will not be entirely lost). You must +therefore verify the current version is unchanged, before you check in your +changes. We hope to eliminate this risk and provide automatic merging +with RCS in a future Emacs version. + + In addition, locking is possible with RCS even in this mode, although +it is not required; @kbd{C-x C-q} with an unmodified file locks the +file, just as it does with RCS in its normal (locking) mode. + +@node Log Buffer +@subsubsection Features of the Log Entry Buffer + + When you check in changes, @kbd{C-x C-q} first reads a log entry. It +pops up a buffer called @samp{*VC-Log*} for you to enter the log entry. +When you are finished, type @kbd{C-c C-c} in the @samp{*VC-Log*} buffer. +That is when check-in really happens. + + To abort check-in, just @strong{don't} type @kbd{C-c C-c} in that +buffer. You can switch buffers and do other editing. As long as you +don't try to check in another file, the entry you were editing remains +in the @samp{*VC-Log*} buffer, and you can go back to that buffer at any +time to complete the check-in. + + If you change several source files for the same reason, it is often +convenient to specify the same log entry for many of the files. To do +this, use the history of previous log entries. The commands @kbd{M-n}, +@kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this work just like the +minibuffer history commands (except that these versions are used outside +the minibuffer). + +@vindex vc-log-mode-hook + Each time you check in a file, the log entry buffer is put into VC Log +mode, which involves running two hooks: @code{text-mode-hook} and +@code{vc-log-mode-hook}. @xref{Hooks}. + +@node Old Versions +@subsection Examining And Comparing Old Versions + + One of the convenient features of version control is the ability +to examine any version of a file, or compare two versions. + +@table @kbd +@item C-x v ~ @var{version} @key{RET} +Examine version @var{version} of the visited file, in a buffer of its +own. + +@item C-x v = +Compare the current buffer contents with the latest checked-in version +of the file. + +@item C-u C-x v = @var{file} @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET} +Compare the specified two versions of @var{file}. + +@item C-x v g +Display the result of the CVS annotate command using colors. +@end table + +@findex vc-version-other-window +@kindex C-x v ~ + To examine an old version in toto, visit the file and then type +@kbd{C-x v ~ @var{version} @key{RET}} (@code{vc-version-other-window}). +This puts the text of version @var{version} in a file named +@file{@var{filename}.~@var{version}~}, and visits it in its own buffer +in a separate window. (In RCS, you can also select an old version +and create a branch from it. @xref{Branches}.) + +@findex vc-diff +@kindex C-x v = + But usually it is more convenient to compare two versions of the file, +with the command @kbd{C-x v =} (@code{vc-diff}). Plain @kbd{C-x v =} +compares the current buffer contents (saving them in the file if +necessary) with the last checked-in version of the file. @kbd{C-u C-x v +=}, with a numeric argument, reads a file name and two version numbers, +then compares those versions of the specified file. + + If you supply a directory name instead of the name of a registered +file, this command compares the two specified versions of all registered +files in that directory and its subdirectories. + + You can specify a checked-in version by its number; an empty input +specifies the current contents of the work file (which may be different +from all the checked-in versions). You can also specify a snapshot name +(@pxref{Snapshots}) instead of one or both version numbers. + + This command works by running the @code{diff} utility, getting the +options from the variable @code{diff-switches}. It displays the output +in a special buffer in another window. Unlike the @kbd{M-x diff} +command, @kbd{C-x v =} does not try to locate the changes in the old and +new versions. This is because normally one or both versions do not +exist as files when you compare them; they exist only in the records of +the master file. @xref{Comparing Files}, for more information about +@kbd{M-x diff}. + +@findex vc-annotate +@kindex C-x v g + For CVS-controlled files, you can display the result of the CVS +annotate command, using colors to enhance the visual appearance. Use +the command @kbd{M-x vc-annotate} to do this. Red means new, blue means +old, and intermediate colors indicate intermediate ages. A prefix +argument @var{n} specifies a stretch factor for the time scale; it makes +each color cover a period @var{n} times as long. + +@node Secondary VC Commands +@subsection The Secondary Commands of VC + + This section explains the secondary commands of VC; those that you might +use once a day. + +@menu +* Registering:: Putting a file under version control. +* VC Status:: Viewing the VC status of files. +* VC Undo:: Cancelling changes before or after check-in. +* VC Dired Mode:: Listing files managed by version control. +* VC Dired Commands:: Commands to use in a VC Dired buffer. +@end menu + +@node Registering +@subsubsection Registering a File for Version Control + +@kindex C-x v i +@findex vc-register + You can put any file under version control by simply visiting it, and +then typing @w{@kbd{C-x v i}} (@code{vc-register}). + +@table @kbd +@item C-x v i +Register the visited file for version control. +@end table + +@vindex vc-default-back-end + To register the file, Emacs must choose which version control system +to use for it. You can specify your choice explicitly by setting +@code{vc-default-back-end} to @code{RCS}, @code{CVS} or @code{SCCS}. +Otherwise, if there is a subdirectory named @file{RCS}, @file{SCCS}, or +@file{CVS}, Emacs uses the corresponding version control system. In the +absence of any specification, the default choice is RCS if RCS is +installed, otherwise SCCS. + + If locking is in use, @kbd{C-x v i} leaves the file unlocked and +read-only. Type @kbd{C-x C-q} if you wish to start editing it. After +registering a file with CVS, you must subsequently commit the initial +version by typing @kbd{C-x C-q}. + +@vindex vc-default-init-version + The initial version number for a newly registered file is 1.1, by +default. You can specify a different default by setting the variable +@code{vc-default-init-version}, or you can give @kbd{C-x v i} a numeric +argument; then it reads the initial version number for this particular +file using the minibuffer. + +@vindex vc-initial-comment + If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an +initial comment to describe the purpose of this source file. Reading +the initial comment works like reading a log entry (@pxref{Log Buffer}). + +@node VC Status +@subsubsection VC Status Commands + +@table @kbd +@item C-x v l +Display version control state and change history. +@end table + +@kindex C-x v l +@findex vc-print-log + To view the detailed version control status and history of a file, +type @kbd{C-x v l} (@code{vc-print-log}). It displays the history of +changes to the current file, including the text of the log entries. The +output appears in a separate window. + +@node VC Undo +@subsubsection Undoing Version Control Actions + +@table @kbd +@item C-x v u +Revert the buffer and the file to the last checked-in version. + +@item C-x v c +Remove the last-entered change from the master for the visited file. +This undoes your last check-in. +@end table + +@kindex C-x v u +@findex vc-revert-buffer + If you want to discard your current set of changes and revert to the +last version checked in, use @kbd{C-x v u} (@code{vc-revert-buffer}). +This leaves the file unlocked; if locking is in use, you must first lock +the file again before you change it again. @kbd{C-x v u} requires +confirmation, unless it sees that you haven't made any changes since the +last checked-in version. + + @kbd{C-x v u} is also the command to unlock a file if you lock it and +then decide not to change it. + +@kindex C-x v c +@findex vc-cancel-version + To cancel a change that you already checked in, use @kbd{C-x v c} +(@code{vc-cancel-version}). This command discards all record of the +most recent checked-in version. @kbd{C-x v c} also offers to revert +your work file and buffer to the previous version (the one that precedes +the version that is deleted). + + If you answer @kbd{no}, VC keeps your changes in the buffer, and locks +the file. The no-revert option is useful when you have checked in a +change and then discover a trivial error in it; you can cancel the +erroneous check-in, fix the error, and check the file in again. + + When @kbd{C-x v c} does not revert the buffer, it unexpands all +version control headers in the buffer instead (@pxref{Version Headers}). +This is because the buffer no longer corresponds to any existing +version. If you check it in again, the check-in process will expand the +headers properly for the new version number. + + However, it is impossible to unexpand the RCS @samp{@w{$}Log$} header +automatically. If you use that header feature, you have to unexpand it +by hand---by deleting the entry for the version that you just canceled. + + Be careful when invoking @kbd{C-x v c}, as it is easy to lose a lot of +work with it. To help you be careful, this command always requires +confirmation with @kbd{yes}. Note also that this command is disabled +under CVS, because canceling versions is very dangerous and discouraged +with CVS. + +@node VC Dired Mode +@subsubsection Dired under VC + +@kindex C-x v d +@findex vc-directory + When you are working on a large program, it is often useful to find +out which files have changed within an entire directory tree, or to view +the status of all files under version control at once, and to perform +version control operations on collections of files. You can use the +command @kbd{C-x v d} (@code{vc-directory}) to make a directory listing +that includes only files relevant for version control. + +@vindex vc-dired-terse-display + @kbd{C-x v d} creates a buffer which uses VC Dired Mode. This looks +much like an ordinary Dired buffer (@pxref{Dired}); however, normally it +shows only the noteworthy files (those locked or not up-to-date). This +is called @dfn{terse display}. If you set the variable +@code{vc-dired-terse-display} to @code{nil}, then VC Dired shows all +relevant files---those managed under version control, plus all +subdirectories (@dfn{full display}). The command @kbd{v t} in a VC +Dired buffer toggles between terse display and full display (@pxref{VC +Dired Commands}). + +@vindex vc-dired-recurse + By default, VC Dired produces a recursive listing of noteworthy or +relevant files at or below the given directory. You can change this by +setting the variable @code{vc-dired-recurse} to @code{nil}; then VC +Dired shows only the files in the given directory. + + The line for an individual file shows the version control state in the +place of the hard link count, owner, group, and size of the file. If +the file is unmodified, in sync with the master file, the version +control state shown is blank. Otherwise it consists of text in +parentheses. Under RCS and SCCS, the name of the user locking the file +is shown; under CVS, an abbreviated version of the @samp{cvs status} +output is used. Here is an example using RCS: + +@smallexample +@group + /home/jim/project: + + -rw-r--r-- (jim) Apr 2 23:39 file1 + -r--r--r-- Apr 5 20:21 file2 +@end group +@end smallexample + +@noindent +The files @samp{file1} and @samp{file2} are under version control, +@samp{file1} is locked by user jim, and @samp{file2} is unlocked. + + Here is an example using CVS: + +@smallexample +@group + /home/joe/develop: + + -rw-r--r-- (modified) Aug 2 1997 file1.c + -rw-r--r-- Apr 4 20:09 file2.c + -rw-r--r-- (merge) Sep 13 1996 file3.c +@end group +@end smallexample + + Here @samp{file1.c} is modified with respect to the repository, and +@samp{file2.c} is not. @samp{file3.c} is modified, but other changes +have also been checked in to the repository---you need to merge them +with the work file before you can check it in. + +@vindex vc-directory-exclusion-list + When VC Dired displays subdirectories (in the ``full'' display mode), +it omits some that should never contain any files under version control. +By default, this includes Version Control subdirectories such as +@samp{RCS} and @samp{CVS}; you can customize this by setting the +variable @code{vc-directory-exclusion-list}. + + You can fine-tune VC Dired's format by typing @kbd{C-u C-x v d}---as in +ordinary Dired, that allows you to specify additional switches for the +@samp{ls} command. + +@node VC Dired Commands +@subsubsection VC Dired Commands + + All the usual Dired commands work normally in VC Dired mode, except +for @kbd{v}, which is redefined as the version control prefix. You can +invoke VC commands such as @code{vc-diff} and @code{vc-print-log} by +typing @kbd{v =}, or @kbd{v l}, and so on. Most of these commands apply +to the file name on the current line. + + The command @kbd{v v} (@code{vc-next-action}) operates on all the +marked files, so that you can lock or check in several files at once. +If it operates on more than one file, it handles each file according to +its current state; thus, it might lock one file, but check in another +file. This could be confusing; it is up to you to avoid confusing +behavior by marking a set of files that are in a similar state. + + If any files call for check-in, @kbd{v v} reads a single log entry, +then uses it for all the files being checked in. This is convenient for +registering or checking in several files at once, as part of the same +change. + +@findex vc-dired-toggle-terse-mode +@findex vc-dired-mark-locked + You can toggle between terse display (only locked files, or files not +up-to-date) and full display at any time by typing @kbd{v t} +@code{vc-dired-toggle-terse-mode}. There is also a special command +@kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently +locked (or, with CVS, all files not up-to-date). Thus, typing @kbd{* l +t k} is another way to delete from the buffer all files except those +currently locked. + +@node Branches +@subsection Multiple Branches of a File +@cindex branch (version control) +@cindex trunk (version control) + + One use of version control is to maintain multiple ``current'' +versions of a file. For example, you might have different versions of a +program in which you are gradually adding various unfinished new +features. Each such independent line of development is called a +@dfn{branch}. VC allows you to create branches, switch between +different branches, and merge changes from one branch to another. +Please note, however, that branches are only supported for RCS at the +moment. + + A file's main line of development is usually called the @dfn{trunk}. +The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At +any such version, you can start an independent branch. A branch +starting at version 1.2 would have version number 1.2.1.1, and consecutive +versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4, +and so on. If there is a second branch also starting at version 1.2, it +would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. + +@cindex head version + If you omit the final component of a version number, that is called a +@dfn{branch number}. It refers to the highest existing version on that +branch---the @dfn{head version} of that branch. The branches in the +example above have branch numbers 1.2.1 and 1.2.2. + +@menu +* Switching Branches:: How to get to another existing branch. +* Creating Branches:: How to start a new branch. +* Merging:: Transferring changes between branches. +* Multi-User Branching:: Multiple users working at multiple branches + in parallel. +@end menu + +@node Switching Branches +@subsubsection Switching between Branches + + To switch between branches, type @kbd{C-u C-x C-q} and specify the +version number you want to select. This version is then visited +@emph{unlocked} (write-protected), so you can examine it before locking +it. Switching branches in this way is allowed only when the file is not +locked. + + You can omit the minor version number, thus giving only the branch +number; this takes you to the head version on the chosen branch. If you +only type @key{RET}, Emacs goes to the highest version on the trunk. + + After you have switched to any branch (including the main branch), you +stay on it for subsequent VC commands, until you explicitly select some +other branch. + +@node Creating Branches +@subsubsection Creating New Branches + + To create a new branch from a head version (one that is the latest in +the branch that contains it), first select that version if necessary, +lock it with @kbd{C-x C-q}, and make whatever changes you want. Then, +when you check in the changes, use @kbd{C-u C-x C-q}. This lets you +specify the version number for the new version. You should specify a +suitable branch number for a branch starting at the current version. +For example, if the current version is 2.5, the branch number should be +2.5.1, 2.5.2, and so on, depending on the number of existing branches at +that point. + + To create a new branch at an older version (one that is no longer the +head of a branch), first select that version (@pxref{Switching +Branches}), then lock it with @kbd{C-x C-q}. You'll be asked to +confirm, when you lock the old version, that you really mean to create a +new branch---if you say no, you'll be offered a chance to lock the +latest version instead. + + Then make your changes and type @kbd{C-x C-q} again to check in a new +version. This automatically creates a new branch starting from the +selected version. You need not specially request a new branch, because +that's the only way to add a new version at a point that is not the head +of a branch. + + After the branch is created, you ``stay'' on it. That means that +subsequent check-ins create new versions on that branch. To leave the +branch, you must explicitly select a different version with @kbd{C-u C-x +C-q}. To transfer changes from one branch to another, use the merge +command, described in the next section. + +@node Merging +@subsubsection Merging Branches + +@cindex merging changes + When you have finished the changes on a certain branch, you will +often want to incorporate them into the file's main line of development +(the trunk). This is not a trivial operation, because development might +also have proceeded on the trunk, so that you must @dfn{merge} the +changes into a file that has already been changed otherwise. VC allows +you to do this (and other things) with the @code{vc-merge} command. + +@table @kbd +@item C-x v m (vc-merge) +Merge changes into the work file. +@end table + +@kindex C-x v m +@findex vc-merge + @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it +into the current version of the work file. It first asks you for a +branch number or a pair of version numbers in the minibuffer. Then it +finds the changes from that branch, or between the two versions you +specified, and merges them into the current version of the current file. + + As an example, suppose that you have finished a certain feature on +branch 1.3.1. In the meantime, development on the trunk has proceeded +to version 1.5. To merge the changes from the branch to the trunk, +first go to the head version of the trunk, by typing @kbd{C-u C-x C-q +RET}. Version 1.5 is now current. If locking is used for the file, +type @kbd{C-x C-q} to lock version 1.5 so that you can change it. Next, +type @kbd{C-x v m 1.3.1 RET}. This takes the entire set of changes on +branch 1.3.1 (relative to version 1.3, where the branch started, up to +the last version on the branch) and merges it into the current version +of the work file. You can now check in the changed file, thus creating +version 1.6 containing the changes from the branch. + + It is possible to do further editing after merging the branch, before +the next check-in. But it is usually wiser to check in the merged +version, then lock it and make the further changes. This will keep +a better record of the history of changes. + +@cindex conflicts +@cindex resolving conflicts + When you merge changes into a file that has itself been modified, the +changes might overlap. We call this situation a @dfn{conflict}, and +reconciling the conflicting changes is called @dfn{resolving a +conflict}. + + Whenever conflicts occur during merging, VC detects them, tells you +about them in the echo area, and asks whether you want help in merging. +If you say yes, it starts an Ediff session (@pxref{Top, +Ediff, Ediff, ediff, The Ediff Manual}). + + If you say no, the conflicting changes are both inserted into the +file, surrounded by @dfn{conflict markers}. The example below shows how +a conflict region looks; the file is called @samp{name} and the current +master file version with user B's changes in it is 1.11. + +@c @w here is so CVS won't think this is a conflict. +@smallexample +@group +@w{<}<<<<<< name + @var{User A's version} +======= + @var{User B's version} +@w{>}>>>>>> 1.11 +@end group +@end smallexample + +@cindex vc-resolve-conflicts + Then you can resolve the conflicts by editing the file manually. Or +you can type @code{M-x vc-resolve-conflicts} after visiting the file. +This starts an Ediff session, as described above. + +@node Multi-User Branching +@subsubsection Multi-User Branching + + It is often useful for multiple developers to work simultaneously on +different branches of a file. CVS allows this by default; for RCS, it +is possible if you create multiple source directories. Each source +directory should have a link named @file{RCS} which points to a common +directory of RCS master files. Then each source directory can have its +own choice of selected versions, but all share the same common RCS +records. + + This technique works reliably and automatically, provided that the +source files contain RCS version headers (@pxref{Version Headers}). The +headers enable Emacs to be sure, at all times, which version number is +present in the work file. + + If the files do not have version headers, you must instead tell Emacs +explicitly in each session which branch you are working on. To do this, +first find the file, then type @kbd{C-u C-x C-q} and specify the correct +branch number. This ensures that Emacs knows which branch it is using +during this particular editing session. + +@node Snapshots +@subsection Snapshots +@cindex snapshots and version control + + A @dfn{snapshot} is a named set of file versions (one for each +registered file) that you can treat as a unit. One important kind of +snapshot is a @dfn{release}, a (theoretically) stable version of the +system that is ready for distribution to users. + +@menu +* Making Snapshots:: The snapshot facilities. +* Snapshot Caveats:: Things to be careful of when using snapshots. +@end menu + +@node Making Snapshots +@subsubsection Making and Using Snapshots + + There are two basic commands for snapshots; one makes a +snapshot with a given name, the other retrieves a named snapshot. + +@table @code +@kindex C-x v s +@findex vc-create-snapshot +@item C-x v s @var{name} @key{RET} +Define the last saved versions of every registered file in or under the +current directory as a snapshot named @var{name} +(@code{vc-create-snapshot}). + +@kindex C-x v r +@findex vc-retrieve-snapshot +@item C-x v r @var{name} @key{RET} +For all registered files at or below the current directory level, select +whatever versions correspond to the snapshot @var{name} +(@code{vc-retrieve-snapshot}). + +This command reports an error if any files are locked at or below the +current directory, without changing anything; this is to avoid +overwriting work in progress. +@end table + + A snapshot uses a very small amount of resources---just enough to record +the list of file names and which version belongs to the snapshot. Thus, +you need not hesitate to create snapshots whenever they are useful. + + You can give a snapshot name as an argument to @kbd{C-x v =} or +@kbd{C-x v ~} (@pxref{Old Versions}). Thus, you can use it to compare a +snapshot against the current files, or two snapshots against each other, +or a snapshot against a named version. + +@node Snapshot Caveats +@subsubsection Snapshot Caveats + +@cindex named configurations (RCS) + VC's snapshot facilities are modeled on RCS's named-configuration +support. They use RCS's native facilities for this, so under VC +snapshots made using RCS are visible even when you bypass VC. + +@c worded verbosely to avoid overfull hbox. + For SCCS, VC implements snapshots itself. The files it uses contain +name/file/version-number triples. These snapshots are visible only +through VC. + + A snapshot is a set of checked-in versions. So make sure that all the +files are checked in and not locked when you make a snapshot. + + File renaming and deletion can create some difficulties with snapshots. +This is not a VC-specific problem, but a general design issue in version +control systems that no one has solved very well yet. + + If you rename a registered file, you need to rename its master along +with it (the command @code{vc-rename-file} does this automatically). If +you are using SCCS, you must also update the records of the snapshot, to +mention the file by its new name (@code{vc-rename-file} does this, +too). An old snapshot that refers to a master file that no longer +exists under the recorded name is invalid; VC can no longer retrieve +it. It would be beyond the scope of this manual to explain enough about +RCS and SCCS to explain how to update the snapshots by hand. + + Using @code{vc-rename-file} makes the snapshot remain valid for +retrieval, but it does not solve all problems. For example, some of the +files in the program probably refer to others by name. At the very +least, the makefile probably mentions the file that you renamed. If you +retrieve an old snapshot, the renamed file is retrieved under its new +name, which is not the name that the makefile expects. So the program +won't really work as retrieved. + +@node Miscellaneous VC +@subsection Miscellaneous Commands and Features of VC + + This section explains the less-frequently-used features of VC. + +@menu +* Change Logs and VC:: Generating a change log file from log entries. +* Renaming and VC:: A command to rename both the source and master + file correctly. +* Version Headers:: Inserting version control headers into working files. +@end menu + +@node Change Logs and VC +@subsubsection Change Logs and VC + + If you use RCS or CVS for a program and also maintain a change log +file for it (@pxref{Change Log}), you can generate change log entries +automatically from the version control log entries: + +@table @kbd +@item C-x v a +@kindex C-x v a +@findex vc-update-change-log +Visit the current directory's change log file and, for registered files +in that directory, create new entries for versions checked in since the +most recent entry in the change log file. +(@code{vc-update-change-log}). + +This command works with RCS or CVS only, not with SCCS. + +@item C-u C-x v a +As above, but only find entries for the current buffer's file. + +@item M-1 C-x v a +As above, but find entries for all the currently visited files that are +maintained with version control. This works only with RCS, and it puts +all entries in the log for the default directory, which may not be +appropriate. +@end table + + For example, suppose the first line of @file{ChangeLog} is dated +1999-04-10, and that the only check-in since then was by Nathaniel +Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log +messages that start with `#'.}. Then @kbd{C-x v a} visits +@file{ChangeLog} and inserts text like this: + +@iftex +@medbreak +@end iftex +@smallexample +@group +1999-05-22 Nathaniel Bowditch <nat@@apn.org> + + * rcs2log: Ignore log messages that start with `#'. +@end group +@end smallexample +@iftex +@medbreak +@end iftex + +@noindent +You can then edit the new change log entry further as you wish. + + Unfortunately, timestamps in ChangeLog files are only dates, so some +of the new change log entry may duplicate what's already in ChangeLog. +You will have to remove these duplicates by hand. + + Normally, the log entry for file @file{foo} is displayed as @samp{* +foo: @var{text of log entry}}. The @samp{:} after @file{foo} is omitted +if the text of the log entry starts with @w{@samp{(@var{functionname}): +}}. For example, if the log entry for @file{vc.el} is +@samp{(vc-do-command): Check call-process status.}, then the text in +@file{ChangeLog} looks like this: + +@iftex +@medbreak +@end iftex +@smallexample +@group +1999-05-06 Nathaniel Bowditch <nat@@apn.org> + + * vc.el (vc-do-command): Check call-process status. +@end group +@end smallexample +@iftex +@medbreak +@end iftex + + When @kbd{C-x v a} adds several change log entries at once, it groups +related log entries together if they all are checked in by the same +author at nearly the same time. If the log entries for several such +files all have the same text, it coalesces them into a single entry. +For example, suppose the most recent check-ins have the following log +entries: + +@flushleft +@bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.} +@bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.} +@bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.} +@end flushleft + +@noindent +They appear like this in @file{ChangeLog}: + +@iftex +@medbreak +@end iftex +@smallexample +@group +1999-04-01 Nathaniel Bowditch <nat@@apn.org> + + * vc.texinfo: Fix expansion typos. + + * vc.el, vc-hooks.el: Don't call expand-file-name. +@end group +@end smallexample +@iftex +@medbreak +@end iftex + + Normally, @kbd{C-x v a} separates log entries by a blank line, but you +can mark several related log entries to be clumped together (without an +intervening blank line) by starting the text of each related log entry +with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label +itself is not copied to @file{ChangeLog}. For example, suppose the log +entries are: + +@flushleft +@bullet{} For @file{vc.texinfo}: @samp{@{expand@} Fix expansion typos.} +@bullet{} For @file{vc.el}: @samp{@{expand@} Don't call expand-file-name.} +@bullet{} For @file{vc-hooks.el}: @samp{@{expand@} Don't call expand-file-name.} +@end flushleft + +@noindent +Then the text in @file{ChangeLog} looks like this: + +@iftex +@medbreak +@end iftex +@smallexample +@group +1999-04-01 Nathaniel Bowditch <nat@@apn.org> + + * vc.texinfo: Fix expansion typos. + * vc.el, vc-hooks.el: Don't call expand-file-name. +@end group +@end smallexample +@iftex +@medbreak +@end iftex + + A log entry whose text begins with @samp{#} is not copied to +@file{ChangeLog}. For example, if you merely fix some misspellings in +comments, you can log the change with an entry beginning with @samp{#} +to avoid putting such trivia into @file{ChangeLog}. + +@node Renaming and VC +@subsubsection Renaming VC Work Files and Master Files + +@findex vc-rename-file + When you rename a registered file, you must also rename its master +file correspondingly to get proper results. Use @code{vc-rename-file} +to rename the source file as you specify, and rename its master file +accordingly. It also updates any snapshots (@pxref{Snapshots}) that +mention the file, so that they use the new name; despite this, the +snapshot thus modified may not completely work (@pxref{Snapshot +Caveats}). + + You cannot use @code{vc-rename-file} on a file that is locked by +someone else. + +@node Version Headers +@subsubsection Inserting Version Control Headers + + Sometimes it is convenient to put version identification strings +directly into working files. Certain special strings called +@dfn{version headers} are replaced in each successive version by the +number of that version. + + If you are using RCS, and version headers are present in your working +files, Emacs can use them to determine the current version and the +locking state of the files. This is more reliable than referring to the +master files, which is done when there are no version headers. Note +that in a multi-branch environment, version headers are necessary to +make VC behave correctly (@pxref{Multi-User Branching}). + + Searching for version headers is controlled by the variable +@code{vc-consult-headers}. If it is non-@code{nil}, Emacs searches for +headers to determine the version number you are editing. Setting it to +@code{nil} disables this feature. + +@kindex C-x v h +@findex vc-insert-headers + You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to +insert a suitable header string. + +@table @kbd +@item C-x v h +Insert headers in a file for use with your version-control system. +@end table + +@vindex vc-header-alist + The default header string is @samp{@w{$}Id$} for RCS and +@samp{@w{%}W%} for SCCS. You can specify other headers to insert by +setting the variable @code{vc-header-alist}. Its value is a list of +elements of the form @code{(@var{program} . @var{string})} where +@var{program} is @code{RCS} or @code{SCCS} and @var{string} is the +string to use. + + Instead of a single string, you can specify a list of strings; then +each string in the list is inserted as a separate header on a line of +its own. + + It is often necessary to use ``superfluous'' backslashes when writing +the strings that you put in this variable. This is to prevent the +string in the constant from being interpreted as a header itself if the +Emacs Lisp file containing it is maintained with version control. + +@vindex vc-comment-alist + Each header is inserted surrounded by tabs, inside comment delimiters, +on a new line at point. Normally the ordinary comment +start and comment end strings of the current mode are used, but for +certain modes, there are special comment delimiters for this purpose; +the variable @code{vc-comment-alist} specifies them. Each element of +this list has the form @code{(@var{mode} @var{starter} @var{ender})}. + +@vindex vc-static-header-alist + The variable @code{vc-static-header-alist} specifies further strings +to add based on the name of the buffer. Its value should be a list of +elements of the form @code{(@var{regexp} . @var{format})}. Whenever +@var{regexp} matches the buffer name, @var{format} is inserted as part +of the header. A header line is inserted for each element that matches +the buffer name, and for each string specified by +@code{vc-header-alist}. The header line is made by processing the +string from @code{vc-header-alist} with the format taken from the +element. The default value for @code{vc-static-header-alist} is as follows: + +@example +@group +(("\\.c$" . + "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\ +#endif /* lint */\n")) +@end group +@end example + +@noindent +It specifies insertion of text of this form: + +@example +@group + +#ifndef lint +static char vcid[] = "@var{string}"; +#endif /* lint */ +@end group +@end example + +@noindent +Note that the text above starts with a blank line. + + If you use more than one version header in a file, put them close +together in the file. The mechanism in @code{revert-buffer} that +preserves markers may not handle markers positioned between two version +headers. + +@node Customizing VC +@subsection Customizing VC + + There are many ways of customizing VC. The options you can set fall +into four categories, described in the following sections. + +@menu +* Backend Options:: Customizing the back-end to your needs. +* VC Workfile Handling:: Various options concerning working files. +* VC Status Retrieval:: How VC finds the version control status of a file, + and how to customize this. +* VC Command Execution:: Which commands VC should run, and how. +@end menu + +@node Backend Options +@subsubsection Options for VC Backends + +@cindex backend options (VC) +@cindex locking under version control + You can tell RCS and CVS whether to use locking for a file or not +(@pxref{VC Concepts}, for a description of locking). VC automatically +recognizes what you have chosen, and behaves accordingly. + +@cindex non-strict locking (RCS) +@cindex locking, non-strict (RCS) + For RCS, the default is to use locking, but there is a mode called +@dfn{non-strict locking} in which you can check-in changes without +locking the file first. Use @samp{rcs -U} to switch to non-strict +locking for a particular file, see the @samp{rcs} manpage for details. + +@cindex locking (CVS) + Under CVS, the default is not to use locking; anyone can change a work +file at any time. However, there are ways to restrict this, resulting +in behavior that resembles locking. + +@cindex CVSREAD environment variable (CVS) + For one thing, you can set the @code{CVSREAD} environment variable to +an arbitrary value. If this variable is defined, CVS makes your work +files read-only by default. In Emacs, you must type @kbd{C-x C-q} to +make the file writeable, so that editing works in fact similar as if +locking was used. Note however, that no actual locking is performed, so +several users can make their files writeable at the same time. When +setting @code{CVSREAD} for the first time, make sure to check out all +your modules anew, so that the file protections are set correctly. + +@cindex cvs watch feature +@cindex watching files (CVS) + Another way to achieve something similar to locking is to use the +@dfn{watch} feature of CVS. If a file is being watched, CVS makes it +read-only by default, and you must also use @kbd{C-x C-q} in Emacs to +make it writable. VC calls @code{cvs edit} to make the file writeable, +and CVS takes care to notify other developers of the fact that you +intend to change the file. See the CVS documentation for details on +using the watch feature. + +@vindex vc-handle-cvs + You can turn off use of VC for CVS-managed files by setting the +variable @code{vc-handle-cvs} to @code{nil}. If you do this, Emacs +treats these files as if they were not registered, and the VC commands +are not available for them. You must do all CVS operations manually. + +@node VC Workfile Handling +@subsubsection VC Workfile Handling + +@vindex vc-make-backup-files + Emacs normally does not save backup files for source files that are +maintained with version control. If you want to make backup files even +for files that use version control, set the variable +@code{vc-make-backup-files} to a non-@code{nil} value. + +@vindex vc-keep-workfiles + Normally the work file exists all the time, whether it is locked or +not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking +in a new version with @kbd{C-x C-q} deletes the work file; but any +attempt to visit the file with Emacs creates it again. (With CVS, work +files are always kept.) + +@vindex vc-follow-symlinks + Editing a version-controlled file through a symbolic link can be +dangerous. It bypasses the version control system---you can edit the +file without locking it, and fail to check your changes in. Also, +your changes might overwrite those of another user. To protect against +this, VC checks each symbolic link that you visit, to see if it points +to a file under version control. + + The variable @code{vc-follow-symlinks} controls what to do when a +symbolic link points to a version-controlled file. If it is @code{nil}, +VC only displays a warning message. If it is @code{t}, VC automatically +follows the link, and visits the real file instead, telling you about +this in the echo area. If the value is @code{ask} (the default), VC +asks you each time whether to follow the link. + +@node VC Status Retrieval +@subsubsection VC Status Retrieval +@c There is no need to tell users about vc-master-templates. + + When deducing the locked/unlocked state of a file, VC first looks for +an RCS version header string in the file (@pxref{Version Headers}). If +there is no header string, or if you are using SCCS, VC normally looks +at the file permissions of the work file; this is fast. But there might +be situations when the file permissions cannot be trusted. In this case +the master file has to be consulted, which is rather expensive. Also +the master file can only tell you @emph{if} there's any lock on the +file, but not whether your work file really contains that locked +version. + +@vindex vc-consult-headers + You can tell VC not to use version headers to determine lock status by +setting @code{vc-consult-headers} to @code{nil}. VC then always uses +the file permissions (if it can trust them), or else checks the master +file. + +@vindex vc-mistrust-permissions + You can specify the criterion for whether to trust the file +permissions by setting the variable @code{vc-mistrust-permissions}. Its +value can be @code{t} (always mistrust the file permissions and check +the master file), @code{nil} (always trust the file permissions), or a +function of one argument which makes the decision. The argument is the +directory name of the @file{RCS}, @file{CVS} or @file{SCCS} +subdirectory. A non-@code{nil} value from the function says to mistrust +the file permissions. If you find that the file permissions of work +files are changed erroneously, set @code{vc-mistrust-permissions} to +@code{t}. Then VC always checks the master file to determine the file's +status. + +@node VC Command Execution +@subsubsection VC Command Execution + +@vindex vc-suppress-confirm + If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x C-q} +and @kbd{C-x v i} can save the current buffer without asking, and +@kbd{C-x v u} also operates without asking for confirmation. (This +variable does not affect @kbd{C-x v c}; that operation is so drastic +that it should always ask for confirmation.) + +@vindex vc-command-messages + VC mode does much of its work by running the shell commands for RCS, +CVS and SCCS. If @code{vc-command-messages} is non-@code{nil}, VC +displays messages to indicate which shell commands it runs, and +additional messages when the commands finish. + +@vindex vc-path + You can specify additional directories to search for version control +programs by setting the variable @code{vc-path}. These directories are +searched before the usual search path. But the proper files are usually +found automatically. + +@node Directories +@section File Directories + +@cindex file directory +@cindex directory listing + The file system groups files into @dfn{directories}. A @dfn{directory +listing} is a list of all the files in a directory. Emacs provides +commands to create and delete directories, and to make directory +listings in brief format (file names only) and verbose format (sizes, +dates, and authors included). There is also a directory browser called +Dired; see @ref{Dired}. + +@table @kbd +@item C-x C-d @var{dir-or-pattern} @key{RET} +Display a brief directory listing (@code{list-directory}). +@item C-u C-x C-d @var{dir-or-pattern} @key{RET} +Display a verbose directory listing. +@item M-x make-directory @key{RET} @var{dirname} @key{RET} +Create a new directory named @var{dirname}. +@item M-x delete-directory @key{RET} @var{dirname} @key{RET} +Delete the directory named @var{dirname}. It must be empty, +or you get an error. +@end table + +@findex list-directory +@kindex C-x C-d + The command to display a directory listing is @kbd{C-x C-d} +(@code{list-directory}). It reads using the minibuffer a file name +which is either a directory to be listed or a wildcard-containing +pattern for the files to be listed. For example, + +@example +C-x C-d /u2/emacs/etc @key{RET} +@end example + +@noindent +lists all the files in directory @file{/u2/emacs/etc}. Here is an +example of specifying a file name pattern: + +@example +C-x C-d /u2/emacs/src/*.c @key{RET} +@end example + + Normally, @kbd{C-x C-d} prints a brief directory listing containing +just file names. A numeric argument (regardless of value) tells it to +make a verbose listing including sizes, dates, and authors (like +@samp{ls -l}). + +@vindex list-directory-brief-switches +@vindex list-directory-verbose-switches + The text of a directory listing is obtained by running @code{ls} in an +inferior process. Two Emacs variables control the switches passed to +@code{ls}: @code{list-directory-brief-switches} is a string giving the +switches to use in brief listings (@code{"-CF"} by default), and +@code{list-directory-verbose-switches} is a string giving the switches to +use in a verbose listing (@code{"-l"} by default). + +@node Comparing Files +@section Comparing Files +@cindex comparing files + +@findex diff +@vindex diff-switches + The command @kbd{M-x diff} compares two files, displaying the +differences in an Emacs buffer named @samp{*Diff*}. It works by running +the @code{diff} program, using options taken from the variable +@code{diff-switches}, whose value should be a string. + + The buffer @samp{*Diff*} has Compilation mode as its major mode, so +you can use @kbd{C-x `} to visit successive changed locations in the two +source files. You can also move to a particular hunk of changes and +type @key{RET} or @kbd{C-c C-c}, or click @kbd{Mouse-2} on it, to move +to the corresponding source location. You can also use the other +special commands of Compilation mode: @key{SPC} and @key{DEL} for +scrolling, and @kbd{M-p} and @kbd{M-n} for cursor motion. +@xref{Compilation}. + +@findex diff-backup + The command @kbd{M-x diff-backup} compares a specified file with its most +recent backup. If you specify the name of a backup file, +@code{diff-backup} compares it with the source file that it is a backup +of. + +@findex compare-windows + The command @kbd{M-x compare-windows} compares the text in the current +window with that in the next window. Comparison starts at point in each +window, and each starting position is pushed on the mark ring in its +respective buffer. Then point moves forward in each window, a character +at a time, until a mismatch between the two windows is reached. Then +the command is finished. For more information about windows in Emacs, +@ref{Windows}. + +@vindex compare-ignore-case + With a numeric argument, @code{compare-windows} ignores changes in +whitespace. If the variable @code{compare-ignore-case} is +non-@code{nil}, it ignores differences in case as well. + + See also @ref{Emerge}, for convenient facilities for merging two +similar files. + +@node Misc File Ops +@section Miscellaneous File Operations + + Emacs has commands for performing many other operations on files. +All operate on one file; they do not accept wildcard file names. + +@findex view-file +@cindex viewing +@cindex View mode +@cindex mode, View + @kbd{M-x view-file} allows you to scan or read a file by sequential +screenfuls. It reads a file name argument using the minibuffer. After +reading the file into an Emacs buffer, @code{view-file} displays the +beginning. You can then type @key{SPC} to scroll forward one windowful, +or @key{DEL} to scroll backward. Various other commands are provided +for moving around in the file, but none for changing it; type @kbd{?} +while viewing for a list of them. They are mostly the same as normal +Emacs cursor motion commands. To exit from viewing, type @kbd{q}. +The commands for viewing are defined by a special major mode called View +mode. + + A related command, @kbd{M-x view-buffer}, views a buffer already present +in Emacs. @xref{Misc Buffer}. + +@findex insert-file + @kbd{M-x insert-file} inserts a copy of the contents of the specified +file into the current buffer at point, leaving point unchanged before the +contents and the mark after them. + +@findex write-region + @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it +copies the contents of the region into the specified file. @kbd{M-x +append-to-file} adds the text of the region to the end of the specified +file. @xref{Accumulating Text}. + +@findex delete-file +@cindex deletion (of files) + @kbd{M-x delete-file} deletes the specified file, like the @code{rm} +command in the shell. If you are deleting many files in one directory, it +may be more convenient to use Dired (@pxref{Dired}). + +@findex rename-file + @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using +the minibuffer, then renames file @var{old} as @var{new}. If a file named +@var{new} already exists, you must confirm with @kbd{yes} or renaming is not +done; this is because renaming causes the old meaning of the name @var{new} +to be lost. If @var{old} and @var{new} are on different file systems, the +file @var{old} is copied and deleted. + +@findex add-name-to-file + The similar command @kbd{M-x add-name-to-file} is used to add an +additional name to an existing file without removing its old name. +The new name must belong on the same file system that the file is on. + +@findex copy-file +@cindex copying files + @kbd{M-x copy-file} reads the file @var{old} and writes a new file named +@var{new} with the same contents. Confirmation is required if a file named +@var{new} already exists, because copying has the consequence of overwriting +the old contents of the file @var{new}. + +@findex make-symbolic-link + @kbd{M-x make-symbolic-link} reads two file names @var{target} and +@var{linkname}, then creates a symbolic link named @var{linkname} and +pointing at @var{target}. The effect is that future attempts to open file +@var{linkname} will refer to whatever file is named @var{target} at the +time the opening is done, or will get an error if the name @var{target} is +not in use at that time. This command does not expand the argument +@var{target}, so that it allows you to specify a relative name +as the target of the link. + + Confirmation is required when creating the link if @var{linkname} is +in use. Note that not all systems support symbolic links. + +@node Compressed Files +@section Accessing Compressed Files +@cindex compression +@cindex uncompression +@cindex Auto Compression mode +@cindex mode, Auto Compression +@pindex gzip + +@findex auto-compression-mode + Emacs comes with a library that can automatically uncompress +compressed files when you visit them, and automatically recompress them +if you alter them and save them. To enable this feature, type the +command @kbd{M-x auto-compression-mode}. + + When automatic compression (which implies automatic uncompression as +well) is enabled, Emacs recognizes compressed files by their file names. +File names ending in @samp{.gz} indicate a file compressed with +@code{gzip}. Other endings indicate other compression programs. + + Automatic uncompression and compression apply to all the operations in +which Emacs uses the contents of a file. This includes visiting it, +saving it, inserting its contents into a buffer, loading it, and byte +compiling it. + +@node Remote Files +@section Remote Files + +@cindex FTP +@cindex remote file access + You can refer to files on other machines using a special file name syntax: + +@example +@group +/@var{host}:@var{filename} +/@var{user}@@@var{host}:@var{filename} +@end group +@end example + +@noindent +When you do this, Emacs uses the FTP program to read and write files on +the specified host. It logs in through FTP using your user name or the +name @var{user}. It may ask you for a password from time to time; this +is used for logging in on @var{host}. + +@cindex ange-ftp +@vindex ange-ftp-default-user + Normally, if you do not specify a user name in a remote file name, +that means to use your own user name. But if you set the variable +@code{ange-ftp-default-user} to a string, that string is used instead. +(The Emacs package that implements FTP file access is called +@code{ange-ftp}.) + +@vindex file-name-handler-alist + You can entirely turn off the FTP file name feature by setting the +variable @code{file-name-handler-alist} to @code{nil}. + +@node Quoted File Names +@section Quoted File Names + +@cindex quoting file names + You can @dfn{quote} an absolute file name to prevent special +characters and syntax in it from having their special effects. +The way to do this is to add @samp{/:} at the beginning. + + For example, you can quote a local file name which appears remote, to +prevent it from being treated as a remote file name. Thus, if you have +a directory named @file{/foo:} and a file named @file{bar} in it, you +can refer to that file in Emacs as @samp{/:/foo:/bar}. + + @samp{/:} can also prevent @samp{~} from being treated as a special +character for a user's home directory. For example, @file{/:/tmp/~hack} +refers to a file whose name is @file{~hack} in directory @file{/tmp}. + + Likewise, quoting with @samp{/:} is one way to enter in the minibuffer +a file name that contains @samp{$}. However, the @samp{/:} must be at +the beginning of the buffer in order to quote @samp{$}. + + You can also quote wildcard characters with @samp{/:}, for visiting. +For example, @file{/:/tmp/foo*bar} visits the file @file{/tmp/foo*bar}. +However, in most cases you can simply type the wildcard characters for +themselves. For example, if the only file name in @file{/tmp} that +starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, then +specifying @file{/tmp/foo*bar} will visit just @file{/tmp/foo*bar}. + diff --git a/man/fixit.texi b/man/fixit.texi new file mode 100644 index 00000000000..2adc975ed7c --- /dev/null +++ b/man/fixit.texi @@ -0,0 +1,317 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Fixit, Files, Search, Top +@chapter Commands for Fixing Typos +@cindex typos, fixing +@cindex mistakes, correcting + + In this chapter we describe the commands that are especially useful for +the times when you catch a mistake in your text just after you have made +it, or change your mind while composing text on the fly. + + The most fundamental command for correcting erroneous editing is the +undo command, @kbd{C-x u} or @kbd{C-_}. This command undoes a single +command (usually), a part of a command (in the case of +@code{query-replace}), or several consecutive self-inserting characters. +Consecutive repetitions of @kbd{C-_} or @kbd{C-x u} undo earlier and +earlier changes, back to the limit of the undo information available. +@xref{Undo}, for for more information. + +@menu +* Kill Errors:: Commands to kill a batch of recently entered text. +* Transpose:: Exchanging two characters, words, lines, lists... +* Fixing Case:: Correcting case of last word entered. +* Spelling:: Apply spelling checker to a word, or a whole file. +@end menu + +@node Kill Errors +@section Killing Your Mistakes + +@table @kbd +@item @key{DEL} +Delete last character (@code{delete-backward-char}). +@item M-@key{DEL} +Kill last word (@code{backward-kill-word}). +@item C-x @key{DEL} +Kill to beginning of sentence (@code{backward-kill-sentence}). +@end table + + The @key{DEL} character (@code{delete-backward-char}) is the most +important correction command. It deletes the character before point. +When @key{DEL} follows a self-inserting character command, you can think +of it as canceling that command. However, avoid the mistake of thinking +of @key{DEL} as a general way to cancel a command! + + When your mistake is longer than a couple of characters, it might be +more convenient to use @kbd{M-@key{DEL}} or @kbd{C-x @key{DEL}}. +@kbd{M-@key{DEL}} kills back to the start of the last word, and @kbd{C-x +@key{DEL}} kills back to the start of the last sentence. @kbd{C-x +@key{DEL}} is particularly useful when you change your mind about the +phrasing of the text you are writing. @kbd{M-@key{DEL}} and @kbd{C-x +@key{DEL}} save the killed text for @kbd{C-y} and @kbd{M-y} to +retrieve. @xref{Yanking}.@refill + + @kbd{M-@key{DEL}} is often useful even when you have typed only a few +characters wrong, if you know you are confused in your typing and aren't +sure exactly what you typed. At such a time, you cannot correct with +@key{DEL} except by looking at the screen to see what you did. Often it +requires less thought to kill the whole word and start again. + +@node Transpose +@section Transposing Text + +@table @kbd +@item C-t +Transpose two characters (@code{transpose-chars}). +@item M-t +Transpose two words (@code{transpose-words}). +@item C-M-t +Transpose two balanced expressions (@code{transpose-sexps}). +@item C-x C-t +Transpose two lines (@code{transpose-lines}). +@end table + +@kindex C-t +@findex transpose-chars + The common error of transposing two characters can be fixed, when they +are adjacent, with the @kbd{C-t} command (@code{transpose-chars}). Normally, +@kbd{C-t} transposes the two characters on either side of point. When +given at the end of a line, rather than transposing the last character of +the line with the newline, which would be useless, @kbd{C-t} transposes the +last two characters on the line. So, if you catch your transposition error +right away, you can fix it with just a @kbd{C-t}. If you don't catch it so +fast, you must move the cursor back to between the two transposed +characters. If you transposed a space with the last character of the word +before it, the word motion commands are a good way of getting there. +Otherwise, a reverse search (@kbd{C-r}) is often the best way. +@xref{Search}. + + +@kindex C-x C-t +@findex transpose-lines +@kindex M-t +@findex transpose-words +@kindex C-M-t +@findex transpose-sexps + @kbd{M-t} (@code{transpose-words}) transposes the word before point +with the word after point. It moves point forward over a word, dragging +the word preceding or containing point forward as well. The punctuation +characters between the words do not move. For example, @w{@samp{FOO, BAR}} +transposes into @w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. + + @kbd{C-M-t} (@code{transpose-sexps}) is a similar command for transposing +two expressions (@pxref{Lists}), and @kbd{C-x C-t} (@code{transpose-lines}) +exchanges lines. They work like @kbd{M-t} except in determining the +division of the text into syntactic units. + + A numeric argument to a transpose command serves as a repeat count: it +tells the transpose command to move the character (word, sexp, line) +before or containing point across several other characters (words, +sexps, lines). For example, @kbd{C-u 3 C-t} moves the character before +point forward across three other characters. It would change +@samp{f@point{}oobar} into @samp{oobf@point{}ar}. This is equivalent to +repeating @kbd{C-t} three times. @kbd{C-u - 4 M-t} moves the word +before point backward across four words. @kbd{C-u - C-M-t} would cancel +the effect of plain @kbd{C-M-t}.@refill + + A numeric argument of zero is assigned a special meaning (because +otherwise a command with a repeat count of zero would do nothing): to +transpose the character (word, sexp, line) ending after point with the +one ending after the mark. + +@node Fixing Case +@section Case Conversion + +@table @kbd +@item M-- M-l +Convert last word to lower case. Note @kbd{Meta--} is Meta-minus. +@item M-- M-u +Convert last word to all upper case. +@item M-- M-c +Convert last word to lower case with capital initial. +@end table + +@kindex M-@t{-} M-l +@kindex M-@t{-} M-u +@kindex M-@t{-} M-c + A very common error is to type words in the wrong case. Because of this, +the word case-conversion commands @kbd{M-l}, @kbd{M-u} and @kbd{M-c} have a +special feature when used with a negative argument: they do not move the +cursor. As soon as you see you have mistyped the last word, you can simply +case-convert it and go on typing. @xref{Case}.@refill + +@node Spelling +@section Checking and Correcting Spelling +@cindex spelling, checking and correcting +@cindex checking spelling +@cindex correcting spelling + + This section describes the commands to check the spelling of a single +word or of a portion of a buffer. These commands work with the spelling +checker program Ispell, which is not part of Emacs. +@ifinfo +@xref{Top, Ispell, Overview ispell, ispell.info, The Ispell Manual}. +@end ifinfo + +@table @kbd +@item M-x flyspell-mode +Enable Flyspell mode, which highlights all misspelled words. +@item M-$ +Check and correct spelling of the word at point (@code{ispell-word}). +@item M-@key{TAB} +Complete the word before point based on the spelling dictionary +(@code{ispell-complete-word}). +@item M-x ispell-buffer +Check and correct spelling of each word in the buffer. +@item M-x ispell-region +Check and correct spelling of each word in the region. +@item M-x ispell-message +Check and correct spelling of each word in a draft mail message, +excluding cited material. +@item M-x ispell-change-dictionary @key{RET} @var{dict} @key{RET} +Restart the Ispell process, using @var{dict} as the dictionary. +@item M-x ispell-kill-ispell +Kill the Ispell subprocess. +@end table + +@cindex Flyspell mode +@findex flyspell-mode + Flyspell mode is a fully-automatic way to check spelling as you edit +in Emacs. It operates by checking words as you change or insert them. +When it finds a word that it does not recognize, it highlights that +word. This does not interfere with your editing, but when you see the +highlighted word, you can move to it and fix it. Type @kbd{M-x +flyspell-mode} to enable or disable this mode in the current buffer. + + When Flyspell mode highlights a word as misspelled, you can click on +it with @kbd{Mouse-2} to display a menu of possible corrections and +actions. You can also correct the word by editing it manually in any +way you like. + + The other Emacs spell-checking features check or look up words when +you give an explicit command to do so. Checking all or part of the +buffer is useful when you have text that was written outside of this +Emacs session and might contain any number of misspellings. + +@kindex M-$ +@findex ispell-word + To check the spelling of the word around or next to point, and +optionally correct it as well, use the command @kbd{M-$} +(@code{ispell-word}). If the word is not correct, the command offers +you various alternatives for what to do about it. + +@findex ispell-buffer +@findex ispell-region + To check the entire current buffer, use @kbd{M-x ispell-buffer}. Use +@kbd{M-x ispell-region} to check just the current region. To check +spelling in an email message you are writing, use @kbd{M-x +ispell-message}; that checks the whole buffer, but does not check +material that is indented or appears to be cited from other messages. + + Each time these commands encounter an incorrect word, they ask you +what to do. They display a list of alternatives, usually including +several ``near-misses''---words that are close to the word being +checked. Then you must type a character. Here are the valid responses: + +@table @kbd +@item @key{SPC} +Skip this word---continue to consider it incorrect, but don't change it +here. + +@item r @var{new} @key{RET} +Replace the word (just this time) with @var{new}. + +@item R @var{new} @key{RET} +Replace the word with @var{new}, and do a @code{query-replace} so you +can replace it elsewhere in the buffer if you wish. + +@item @var{digit} +Replace the word (just this time) with one of the displayed +near-misses. Each near-miss is listed with a digit; type that digit to +select it. + +@item a +Accept the incorrect word---treat it as correct, but only in this +editing session. + +@item A +Accept the incorrect word---treat it as correct, but only in this +editing session and for this buffer. + +@item i +Insert this word in your private dictionary file so that Ispell will +consider it correct it from now on, even in future sessions. + +@item u +Insert the lower-case version of this word in your private dictionary +file. + +@item m +Like @kbd{i}, but you can also specify dictionary completion +information. + +@item l @var{word} @key{RET} +Look in the dictionary for words that match @var{word}. These words +become the new list of ``near-misses''; you can select one of them to +replace with by typing a digit. You can use @samp{*} in @var{word} as a +wildcard. + +@item C-g +Quit interactive spell checking. You can restart it again afterward +with @kbd{C-u M-$}. + +@item X +Same as @kbd{C-g}. + +@item x +Quit interactive spell checking and move point back to where it was +when you started spell checking. + +@item q +Quit interactive spell checking and kill the Ispell subprocess. + +@item C-l +Refresh the screen. + +@item C-z +This key has its normal command meaning (suspend Emacs or iconify this +frame). +@end table + +@findex ispell-complete-word + The command @code{ispell-complete-word}, which is bound to the key +@kbd{M-@key{TAB}} in Text mode and related modes, shows a list of +completions based on spelling correction. Insert the beginning of a +word, and then type @kbd{M-@key{TAB}}; the command displays a completion +list window. To choose one of the completions listed, click +@kbd{Mouse-2} on it, or move the cursor there in the completions window +and type @key{RET}. @xref{Text Mode}. + +@ignore +@findex reload-ispell + The first time you use any of the spell checking commands, it starts +an Ispell subprocess. The first thing the subprocess does is read your +private dictionary, which defaults to the file @file{~/ispell.words}. +Words that you ``insert'' with the @kbd{i} command are added to that +file, but not right away---only at the end of the interactive +replacement procedure. Use the @kbd{M-x reload-ispell} command to +reload your private dictionary if you edit the file outside of Ispell. +@end ignore + +@cindex @code{ispell} program +@findex ispell-kill-ispell + Once started, the Ispell subprocess continues to run (waiting for +something to do), so that subsequent spell checking commands complete +more quickly. If you want to get rid of the Ispell process, use +@kbd{M-x ispell-kill-ispell}. This is not usually necessary, since the +process uses no time except when you do spelling correction. + +@vindex ispell-dictionary + Ispell uses two dictionaries: the standard dictionary and your private +dictionary. The variable @code{ispell-dictionary} specifies the file +name of the standard dictionary to use. A value of @code{nil} says to +use the default dictionary. The command @kbd{M-x +ispell-change-dictionary} sets this variable and then restarts the +Ispell subprocess, so that it will use a different dictionary. + diff --git a/man/forms.texi b/man/forms.texi new file mode 100644 index 00000000000..0715ce9c56d --- /dev/null +++ b/man/forms.texi @@ -0,0 +1,974 @@ +\input texinfo @c -*-texinfo-*- +@c documentation for forms-mode +@c Written by Johan Vromans, and edited by Richard Stallman + +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename ../info/forms +@settitle Forms Mode User's Manual +@syncodeindex vr cp +@syncodeindex fn cp +@syncodeindex ky cp +@iftex +@finalout +@setchapternewpage odd +@end iftex +@c @smallbook +@comment %**end of header (This is for running Texinfo on a region.) + +@dircategory Editors +@direntry +* Forms: (forms). Emacs package for editing data bases + by filling in forms. +@end direntry + +@ifinfo +This file documents Forms mode, a form-editing major mode for GNU Emacs. + +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 + +@iftex +@titlepage +@sp 6 +@center @titlefont{Forms Mode User's Manual} +@sp 4 +@center Forms-Mode version 2 +@sp 1 +@center for GNU Emacs 20.1 +@sp 1 +@center June 1997 +@sp 5 +@center Johan Vromans +@center @i{jvromans@@squirrel.nl} +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1989, 1997 Free Software Foundation, Inc. + +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. +@page +@end titlepage +@end iftex + +@ifinfo +@node Top +@top Forms Mode + +Forms mode is an Emacs major mode for working with simple textual data +bases in a forms-oriented manner. In Forms mode, the information in +these files is presented in an Emacs window in a user-defined format, +one record at a time. The user can view records or modify their +contents. + +Forms mode is not a simple major mode, but requires two files to do its +job: a control file and a data file. The data file holds the +actual data to be presented. The control file describes +how to present it. + +@menu +* Forms Example:: An example: editing the password data base. +* Entering and Exiting Forms Mode:: + How to visit a file in Forms mode. +* Forms Commands:: Special commands to use while in Forms mode. +* Data File Format:: How to format the data file. +* Control File Format:: How to control forms mode. +* Format Description:: How to define the forms layout. +* Modifying Forms Contents:: How to modify. +* Miscellaneous:: Forms mode messages and other remarks. +* Error Messages:: List of error messages forms mode can produce. +* Long Example:: A more complex control file example. +* Credits:: Thanks everyone. +* Index:: Index to this manual. +@end menu +@end ifinfo + +@node Forms Example +@chapter Forms Example + +Let's illustrate Forms mode with an example. Suppose you are looking at +the @file{/etc/passwd} file, and the screen looks like this: + +@example +====== /etc/passwd ====== + +User : root Uid: 0 Gid: 1 + +Name : Super User + +Home : / + +Shell: /bin/sh +@end example + +As you can see, the familiar fields from the entry for the super user +are all there, but instead of being colon-separated on one single line, +they make up a forms. + +The contents of the forms consist of the contents of the fields of the +record (e.g. @samp{root}, @samp{0}, @samp{1}, @samp{Super User}) +interspersed with normal text (e.g @samp{User : }, @samp{Uid: }). + +If you modify the contents of the fields, Forms mode will analyze your +changes and update the file appropriately. You cannot modify the +interspersed explanatory text (unless you go to some trouble about it), +because that is marked read-only (@pxref{Text Properties,,, elisp, The +Emacs Lisp Reference Manual}). + +The Forms mode control file specifies the relationship between the +format of @file{/etc/passwd} and what appears on the screen in Forms +mode. @xref{Control File Format}. + +@node Entering and Exiting Forms Mode +@chapter Entering and Exiting Forms Mode + +@table @kbd +@findex forms-find-file +@item M-x forms-find-file @key{RET} @var{control-file} @key{RET} +Visit a database using Forms mode. Specify the name of the +@strong{control file}, not the data file! + +@findex forms-find-file-other-window +@item M-x forms-find-file-other-window @key{RET} @var{control-file} @key{RET} +Similar, but displays the file in another window. +@end table + +The command @code{forms-find-file} evaluates the file +@var{control-file}, and also visits it in Forms mode. What you see in +its buffer is not the contents of this file, but rather a single record +of the corresponding data file that is visited in its own buffer. So +there are two buffers involved in Forms mode: the @dfn{forms buffer} +that is initially used to visit the control file and that shows the +records being browsed, and the @dfn{data buffer} that holds the data +file being visited. The latter buffer is normally not visible. + +Initially, the first record is displayed in the forms buffer. +The mode line displays the major mode name @samp{Forms}, followed by the +minor mode @samp{View} if the data base is read-only. The number of the +current record (@var{n}) and the total number of records in the +file(@var{t}) are shown in the mode line as @samp{@var{n}/@var{t}}. For +example: + +@example +--%%-Emacs: passwd-demo (Forms View 1/54)----All------- +@end example + +If the buffer is not read-only, you may change the buffer to modify the +fields in the record. When you move to a different record, the contents +of the buffer are parsed using the specifications in +@code{forms-format-list}, and the data file is updated. If the record +has fields that aren't included in the display, they are not changed. + +@vindex forms-mode-hooks +Entering Forms mode runs the normal hook @code{forms-mode-hooks} to +perform user-defined customization. + +To save any modified data, you can use @kbd{C-x C-s} +(@code{forms-save-buffer}). This does not save the forms buffer (which would +be rather useless), but instead saves the buffer visiting the data file. + +To terminate Forms mode, you can use @kbd{C-x C-s} (@code{forms-save-buffer}) +and then kill the forms buffer. However, the data buffer will still +remain. If this is not desired, you have to kill this buffer too. + +@node Forms Commands +@chapter Forms Commands + +The commands of Forms mode belong to the @kbd{C-c} prefix, with one +exception: @key{TAB}, which moves to the next field. Forms mode uses +different key maps for normal mode and read-only mode. In read-only +Forms mode, you can access most of the commands without the @kbd{C-c} +prefix, but you must type ordinary letters instead of control +characters; for example, type @kbd{n} instead of @kbd{C-c C-n}. + +If your Emacs has been built with X-toolkit support, Forms mode will +provide its own menu with a number of Forms mode commands. + +@table @kbd +@findex forms-next-record +@kindex C-c C-n +@item C-c C-n +Show the next record (@code{forms-next-record}). With a numeric +argument @var{n}, show the @var{n}th next record. + +@findex forms-prev-record +@kindex C-c C-p +@item C-c C-p +Show the previous record (@code{forms-prev-record}). With a numeric +argument @var{n}, show the @var{n}th previous record. + +@findex forms-jump-record +@kindex C-c C-l +@item C-c C-l +Jump to a record by number (@code{forms-jump-record}). Specify +the record number with a numeric argument. + +@findex forms-first-record +@kindex C-c < +@item C-c < +Jump to the first record (@code{forms-first-record}). + +@findex forms-last-record +@kindex C-c > +@item C-c > +Jump to the last record (@code{forms-last-record}). This command also +recalculates the number of records in the data file. + +@findex forms-next-field +@kindex TAB +@item @key{TAB} +@kindex C-c TAB +@itemx C-c @key{TAB} +Jump to the next field in the current record (@code{forms-next-field}). +With a numeric argument @var{n}, jump forward @var{n} fields. If this command +would move past the last field, it wraps around to the first field. + +@findex forms-toggle-read-only +@kindex C-c C-q +@item C-c C-q +Toggles read-only mode (@code{forms-toggle-read-only}). In read-only +Forms mode, you cannot edit the fields; most Forms mode commands can be +accessed without the prefix @kbd{C-c} if you use the normal letter +instead (for example, type @kbd{n} instead of @kbd{C-c C-n}). In edit +mode, you can edit the fields and thus change the contents of the data +base; you must begin Forms mode commands with @code{C-c}. Switching +to edit mode is allowed only if you have write access to the data file. + +@findex forms-insert-record +@kindex C-c C-o +@item C-c C-o +Create a new record and insert it before the current record +(@code{forms-insert-record}). It starts out with empty (or default) +contents for its fields; you can then edit the fields. With a numeric +argument, the new record is created @emph{after} the current one. +See also @code{forms-modified-record-filter} in @ref{Modifying Forms +Contents}. + +@findex forms-delete-record +@kindex C-c C-k +@item C-c C-k +Delete the current record (@code{forms-delete-record}). You are +prompted for confirmation before the record is deleted unless a numeric +argument has been provided. + +@findex forms-search-forward +@kindex C-c C-s @var{regexp} @key{RET} +@item C-c C-s @var{regexp} @key{RET} +Search forward for @var{regexp} in all records following this one +(@code{forms-search-forward}). If found, this record is shown. +If you give an empty argument, the previous regexp is used again. + +@findex forms-search-backward +@kindex C-c C-r @var{regexp} @key{RET} +@item C-c C-r @var{regexp} @key{RET} +Search backward for @var{regexp} in all records following this one +(@code{forms-search-backward}). If found, this record is shown. +If you give an empty argument, the previous regexp is used again. + +@ignore +@findex forms-exit +@kindex C-c C-x +@item C-c C-x +Terminate Forms mode processing (@code{forms-exit}). The data file is +saved if it has been modified. + +@findex forms-exit-no-save +@item M-x forms-exit-no-save +Terminates forms mode processing without saving modified data first. +@end ignore + +@findex forms-prev-field +@item M-x forms-prev-field +Similar to @code{forms-next-field} but moves backwards. + +@findex forms-save-buffer +@item M-x forms-save-buffer +@kindex C-x C-s +@itemx C-x C-s +Forms mode replacement for @code{save-buffer}. When executed in the +forms buffer it will save the contents of the (modified) data buffer +instead. In Forms mode this function will be bound to @kbd{C-x C-s}. + +@findex forms-print +@item M-x forms-print +This command can be used to make a formatted print +of the contents of the data file. + +@end table + +In addition the command @kbd{M-x revert-buffer} is useful in Forms mode +just as in other modes. + +@ignore +@vindex forms-forms-scroll +@findex scroll-up +@findex scroll-down +If the variable @code{forms-forms-scrolls} is set to a value other +than @code{nil} (which it is, by default), the Emacs functions +@code{scroll-up} and @code{scroll-down} will perform a +@code{forms-next-record} and @code{forms-prev-record} when in forms +mode. So you can use your favourite page commands to page through the +data file. + +@vindex forms-forms-jump +@findex beginning-of-buffer +@findex end-of-buffer +Likewise, if the variable @code{forms-forms-jump} is not @code{nil} +(which it is, by default), Emacs functions @code{beginning-of-buffer} +and @code{end-of-buffer} will perform @code{forms-first-record} and +@code{forms-last-record} when in forms mode. +@end ignore + +The following function key definitions are set up in Forms mode +(whether read-only or not): + +@table @kbd +@kindex next +@item next +forms-next-record + +@kindex prior +@item prior +forms-prev-record + +@kindex begin +@item begin +forms-first-record + +@kindex end +@item end +forms-last-record + +@kindex S-Tab +@findex forms-prev-field +@item S-Tab +forms-prev-field +@end table + +@node Data File Format +@chapter Data File Format + +@cindex record +@cindex field +@vindex forms-field-sep +Files for use with Forms mode are very simple---each @dfn{record} +(usually one line) forms the contents of one form. Each record consists +of a number of @dfn{fields}, which are separated by the value of the +string @code{forms-field-sep}, which is @code{"\t"} (a Tab) by default. + +@vindex forms-read-file-filter +@vindex forms-write-file-filter +If the format of the data file is not suitable enough you can define the +filter functions @code{forms-read-file-filter} and +@code{forms-write-file-filter}. @code{forms-read-file-filter} is called +when the data file is read from disk into the data buffer. It operates +on the data buffer, ignoring read-only protections. When the data file +is saved to disk @code{forms-write-file-filter} is called to cancel the +effects of @code{forms-read-file-filter}. After being saved, +@code{forms-read-file-filter} is called again to prepare the data buffer +for further processing. + +@cindex pseudo-newline +@vindex forms-multi-line +Fields may contain text which shows up in the forms in multiple lines. +These lines are separated in the field using a ``pseudo-newline'' +character which is defined by the value of the string +@code{forms-multi-line}. Its default value is @code{"\^k"} (a Control-K +character). If it is +set to @code{nil}, multiple line fields are prohibited. + +If the data file does not exist, it is automatically created. + +@node Control File Format +@chapter Control File Format + +@cindex control file +The Forms mode @dfn{control file} serves two purposes. First, it names +the data file to use, and defines its format and properties. Second, +the Emacs buffer it occupies is used by Forms mode to display the forms. + +The contents of the control file are evaluated as a Lisp program. It +should set the following Lisp variables to suitable values: + +@table @code +@vindex forms-file +@item forms-file +This variable specifies the name of the data file. Example: + +@example +(setq forms-file "my/data-file") +@end example + +If the control file doesn't set @code{forms-file}, Forms mode +reports an error. + +@vindex forms-format-list +@item forms-format-list +This variable describes the way the fields of the record are formatted on +the screen. For details, see @ref{Format Description}. + +@vindex forms-number-of-fields +@item forms-number-of-fields +This variable holds the number of fields in each record of the data +file. Example: + +@example +(setq forms-number-of-fields 10) +@end example +@end table + +If the control file does not set @code{forms-format-list} a default +format is used. In this situation, Forms mode will deduce the number of +fields from the data file providing this file exists and +@code{forms-number-of-records} has not been set in the control file. + +The control file can optionally set the following additional Forms mode +variables. Most of them have default values that are good for most +applications. + +@table @code +@vindex forms-field-sep +@item forms-field-sep +This variable may be used to designate the string which separates the +fields in the records of the data file. If not set, it defaults to the +string @code{"\t"} (a Tab character). Example: + +@example +(setq forms-field-sep "\t") +@end example + +@vindex forms-read-only +@item forms-read-only +If the value is non-@code{nil}, the data file is treated read-only. (Forms +mode also treats the data file as read-only if you don't have access to +write it.) Example: + +@example +(set forms-read-only t) +@end example + +@vindex forms-multi-line +@item forms-multi-line +This variable specifies the @dfn{pseudo newline} separator that allows +multi-line fields. This separator goes between the ``lines'' within a +field---thus, the field doesn't really contain multiple lines, but it +appears that way when displayed in Forms mode. If the value is +@code{nil}, multi-line text fields are prohibited. The pseudo newline +must not be a character contained in @code{forms-field-sep}. + +The default value is @code{"\^k"}, the character Control-K. Example: + +@example +(setq forms-multi-line "\^k") +@end example + +@ignore +@vindex forms-forms-scroll +@item forms-forms-scroll +@xref{Forms Mode Commands}, for details. + +@vindex forms-forms-jump +@item forms-forms-jump +@xref{Forms Mode Commands}, for details. +@end ignore + +@findex forms-read-file-filter +@item forms-read-file-filter +This variable holds the name of a function to be called after the data +file has been read in. This can be used to transform the contents of the +data file into a format more suitable for forms processing. +If it is @code{nil}, no function is called. For example, to maintain a +gzipped database: + +@example +(defun gzip-read-file-filter () + (shell-command-on-region (point-min) (point-max) + "gzip -d" t t)) +(setq forms-read-file-filter 'gzip-read-file-filter) +@end example + +@findex forms-write-file-filter +@item forms-write-file-filter +This variable holds the name of a function to be called before writing +out the contents of the data file. +This can be used to undo the effects of @code{forms-read-file-filter}. +If it is @code{nil}, no function is called. Example: + +@example +(defun gzip-write-file-filter () + (make-variable-buffer-local 'require-final-newline) + (setq require-final-newline nil) + (shell-command-on-region (point-min) (point-max) + "gzip" t t)) +(setq forms-write-file-filter 'gzip-write-file-filter) +@end example + +@findex forms-new-record-filter +@item forms-new-record-filter +This variable holds a function to be called whenever a new record is created +to supply default values for fields. If it is @code{nil}, no function is +called. +@xref{Modifying Forms Contents}, for details. + +@findex forms-modified-record-filter +@item forms-modified-record-filter +This variable holds a function to be called whenever a record is +modified, just before updating the Forms data file. If it is +@code{nil}, no function is called. +@xref{Modifying Forms Contents}, for details. + +@findex forms-insert-after +@item forms-insert-after +If this variable is not @code{nil}, new records are created @emph{after} the +current record. Also, upon visiting a file, the initial position will be +at the last record instead of the first one. + +@findex forms-check-number-of-fields +@item forms-check-number-of-fields +Normally each record is checked to contain the correct number of fields. +Under certain circumstances, this can be undesirable. +If this variable is set to @code{nil}, these checks will be bypassed. +@end table + +@node Format Description +@chapter The Format Description + +@vindex forms-format-list + The variable @code{forms-format-list} specifies the format of the data +in the data file, and how to convert the data for display in Forms mode. +Its value must be a list of Forms mode @dfn{formatting elements}, each +of which can be a string, a number, a Lisp list, or a Lisp symbol that +evaluates to one of those. The formatting elements are processed in the +order they appear in the list. + +@table @var +@item string +A string formatting element is inserted in the forms ``as is,'' as text +that the user cannot alter. + +@item number +A number element selects a field of the record. The contents of this +field are inserted in the display at this point. Field numbers count +starting from 1 (one). + +@item list +A formatting element that is a list specifies a function call. This +function is called every time a record is displayed, and its result, +which must be a string, is inserted in the display text. The function +should do nothing but returning a string. + +@vindex forms-fields +The function you call can access the fields of the record as a list in +the variable +@code{forms-fields}. + +@item symbol +A symbol used as a formatting element should evaluate to a string, number, +or list; the value is interpreted as a formatting element, as described +above. +@end table + +If a record does not contain the number of fields as specified in +@code{forms-number-of-fields}, a warning message will be printed. Excess +fields are ignored, missing fields are set to empty. + +The control file which displays @file{/etc/passwd} file as demonstrated +in the beginning of this manual might look as follows: + +@example +;; @r{This demo visits @file{/etc/passwd}.} + +(setq forms-file "/etc/passwd") +(setq forms-number-of-fields 7) +(setq forms-read-only t) ; @r{to make sure} +(setq forms-field-sep ":") +;; @r{Don't allow multi-line fields.} +(setq forms-multi-line nil) + +(setq forms-format-list + (list + "====== /etc/passwd ======\n\n" + "User : " 1 + " Uid: " 3 + " Gid: " 4 + "\n\n" + "Name : " 5 + "\n\n" + "Home : " 6 + "\n\n" + "Shell: " 7 + "\n")) +@end example + +When you construct the value of @code{forms-format-list}, you should +usually either quote the whole value, like this, + +@example +(setq forms-format-list + '( + "====== " forms-file " ======\n\n" + "User : " 1 + (make-string 20 ?-) + @dots{} + )) +@end example + +@noindent +or quote the elements which are lists, like this: + +@example +(setq forms-format-list + (list + "====== " forms-file " ======\n\n" + "User : " 1 + '(make-string 20 ?-) + @dots{} + )) +@end example + +Forms mode validates the contents of @code{forms-format-list} when you +visit a database. If there are errors, processing is aborted with an +error message which includes a descriptive text. @xref{Error Messages}, +for a detailed list of error messages. + +If no @code{forms-format-list} is specified, Forms mode will supply a +default format list. This list contains the name of the file being +visited, and a simple label for each field indicating the field number. + +@node Modifying Forms Contents +@chapter Modifying The Forms Contents + +If @code{forms-read-only} is @code{nil}, the user can modify the fields +and records of the database. + +All normal editing commands are available for editing the contents of the +displayed record. You cannot delete or modify the fixed, explanatory +text that comes from string formatting elements, but you can modify the +actual field contents. + +@ignore +@c This is for the Emacs 18 version only. +If the contents of the forms cannot be recognized properly, this is +signaled using a descriptive text. @xref{Error Messages}, for more info. +The cursor will indicate the last part of the forms which was +successfully parsed. It's important to avoid entering field contents +that would cause confusion with the field-separating fixed text. +@end ignore + +If the variable @code{forms-modified-record-filter} is non-@code{nil}, +it is called as a function before the new data is written to the data +file. The function receives one argument, a vector that contains the +contents of the fields of the record. + +The function can refer to fields with @code{aref} and modify them with +@code{aset}. The first field has number 1 (one); thus, element 0 of the +vector is not used. The function should return the same vector it was +passed; the (possibly modified) contents of the vector determine what is +actually written in the file. Here is an example: + +@example +(defun my-modified-record-filter (record) + ;; @r{Modify second field.} + (aset record 2 (current-time-string)) + ;; @r{Return the field vector.} + record) + +(setq forms-modified-record-filter 'my-modified-record-filter) +@end example + +If the variable @code{forms-new-record-filter} is non-@code{nil}, its +value is a function to be called to fill in default values for the +fields of a new record. The function is passed a vector of empty +strings, one for each field; it should return the same vector, with +the desired field values stored in it. Fields are numbered starting +from 1 (one). Example: + +@example +(defun my-new-record-filter (fields) + (aset fields 5 (login-name)) + (aset fields 1 (current-time-string)) + fields) + +(setq forms-new-record-filter 'my-new-record-filter) +@end example + +@node Miscellaneous +@chapter Miscellaneous + +@vindex forms-version +The global variable @code{forms-version} holds the version information +of the Forms mode software. + +@findex forms-enumerate +It is very convenient to use symbolic names for the fields in a record. +The function @code{forms-enumerate} provides an elegant means to define +a series of variables whose values are consecutive integers. The +function returns the highest number used, so it can be used to set +@code{forms-number-of-fields} also. For example: + +@example +(setq forms-number-of-fields + (forms-enumerate + '(field1 field2 field3 @dots{}))) +@end example + +This sets @code{field1} to 1, @code{field2} to 2, and so on. + +Care has been taken to keep the Forms mode variables buffer-local, so it +is possible to visit multiple files in Forms mode simultaneously, even +if they have different properties. + +@findex forms-mode +If you have visited the control file in normal fashion with +@code{find-file} or a like command, you can switch to Forms mode with +the command @code{M-x forms-mode}. If you put @samp{-*- forms -*-} in +the first line of the control file, then visiting it enables Forms mode +automatically. But this makes it hard to edit the control file itself, +so you'd better think twice before using this. + +The default format for the data file, using @code{"\t"} to separate +fields and @code{"\^k"} to separate lines within a field, matches the +file format of some popular database programs, e.g. FileMaker. So +@code{forms-mode} can decrease the need to use proprietary software. + +@node Error Messages +@chapter Error Messages + +This section describes all error messages which can be generated by +forms mode. Error messages that result from parsing the control file +all start with the text @samp{Forms control file error}. Messages +generated while analyzing the definition of @code{forms-format-list} +start with @samp{Forms format error}. + +@table @code +@item Forms control file error: `forms-file' has not been set +The variable @code{forms-file} was not set by the control file. + +@item Forms control file error: `forms-number-of-fields' has not been set +The variable @code{forms-number-of-fields} was not set by the control +file. + +@item Forms control file error: `forms-number-of-fields' must be a number > 0 +The variable @code{forms-number-of-fields} did not contain a positive +number. + +@item Forms control file error: `forms-field-sep' is not a string +@itemx Forms control file error: `forms-multi-line' must be nil or a one-character string +The variable @code{forms-multi-line} was set to something other than +@code{nil} or a single-character string. + +@item Forms control file error: `forms-multi-line' is equal to 'forms-field-sep' +The variable @code{forms-multi-line} may not be equal to +@code{forms-field-sep} for this would make it impossible to distinguish +fields and the lines in the fields. + +@item Forms control file error: `forms-new-record-filter' is not a function +@itemx Forms control file error: `forms-modified-record-filter' is not a function +The variable has been set to something else than a function. + +@item Forms control file error: `forms-format-list' is not a list +The variable @code{forms-format-list} was not set to a Lisp list +by the control file. + +@item Forms format error: field number @var{xx} out of range 1..@var{nn} +A field number was supplied in @code{forms-format-list} with a value of +@var{xx}, which was not greater than zero and smaller than or equal to +the number of fields in the forms, @var{nn}. + +@item Forms format error: @var{fun} is not a function +The first element of a list which is an element of +@code{forms-format-list} was not a valid Lisp function. + +@item Forms format error: invalid element @var{xx} +A list element was supplied in @code{forms-format-list} which was not a +string, number or list. + +@ignore +@c This applies to Emacs 18 only. +@c Error messages generated while a modified form is being analyzed. + +@item Parse error: not looking at `...' +When re-parsing the contents of a forms, the text shown could not +be found. + +@item Parse error: cannot find `...' +When re-parsing the contents of a forms, the text shown, which +separates two fields, could not be found. + +@item Parse error: cannot parse adjacent fields @var{xx} and @var{yy} +Fields @var{xx} and @var{yy} were not separated by text, so could not be +parsed again. +@end ignore + +@item Warning: this record has @var{xx} fields instead of @var{yy} +The number of fields in this record in the data file did not match +@code{forms-number-of-fields}. Missing fields will be made empty. + +@item Multi-line fields in this record - update refused! +The current record contains newline characters, hence can not be written +back to the data file, for it would corrupt it. Probably you inserted a +newline in a field, while @code{forms-multi-line} was @code{nil}. + +@item Field separator occurs in record - update refused! +The current record contains the field separator string inside one of the +fields. It can not be written back to the data file, for it would +corrupt it. Probably you inserted the field separator string in a field. + +@item Record number @var{xx} out of range 1..@var{yy} +A jump was made to non-existing record @var{xx}. @var{yy} denotes the +number of records in the file. + +@item Stuck at record @var{xx} +An internal error prevented a specific record from being retrieved. + +@item No write access to @code{"}@var{file}@code{"} +An attempt was made to enable edit mode on a file that has been write +protected. + +@item Search failed: @var{regexp} +The @var{regexp} could not be found in the data file. Forward searching +is done from the current location until the end of the file, then +retrying from the beginning of the file until the current location. +Backward searching is done from the current location until the beginning +of the file, then retrying from the end of the file until the current +location. + +@item Wrapped +A search completed successfully after wrapping around. + +@item Warning: number of records changed to @var{nn} +Forms mode's idea of the number of records has been adjusted to the +number of records actually present in the data file. + +@item Problem saving buffers? +An error occurred while saving the data file buffer. Most likely, Emacs +did ask to confirm deleting the buffer because it had been modified, and +you said `no'. +@end table + +@node Long Example +@chapter Long Example + +The following example exploits most of the features of Forms mode. +This example is included in the distribution as file @file{forms-d2.el}. + +@example +;; demo2 -- demo forms-mode -*- emacs-lisp -*- + +;; @r{This sample forms exploit most of the features of forms mode.} + +;; @r{Set the name of the data file.} +(setq forms-file "forms-d2.dat") + +;; @r{Use @code{forms-enumerate} to set field names and number thereof.} +(setq forms-number-of-fields + (forms-enumerate + '(arch-newsgroup ; 1 + arch-volume ; 2 + arch-issue ; and ... + arch-article ; ... so + arch-shortname ; ... ... on + arch-parts + arch-from + arch-longname + arch-keywords + arch-date + arch-remarks))) + +;; @r{The following functions are used by this form for layout purposes.} +;; +(defun arch-tocol (target &optional fill) + "Produces a string to skip to column TARGET. +Prepends newline if needed. +The optional FILL should be a character, used to fill to the column." + (if (null fill) + (setq fill ? )) + (if (< target (current-column)) + (concat "\n" (make-string target fill)) + (make-string (- target (current-column)) fill))) +;; +(defun arch-rj (target field &optional fill) + "Produces a string to skip to column TARGET\ + minus the width of field FIELD. +Prepends newline if needed. +The optional FILL should be a character, +used to fill to the column." + (arch-tocol (- target (length (nth field forms-fields))) fill)) + +;; @r{Record filters.} +;; +(defun new-record-filter (the-record) + "Form a new record with some defaults." + (aset the-record arch-from (user-full-name)) + (aset the-record arch-date (current-time-string)) + the-record) ; return it +(setq forms-new-record-filter 'new-record-filter) + +;; @r{The format list.} +(setq forms-format-list + (list + "====== Public Domain Software Archive ======\n\n" + arch-shortname + " - " arch-longname + "\n\n" + "Article: " arch-newsgroup + "/" arch-article + " " + '(arch-tocol 40) + "Issue: " arch-issue + " " + '(arch-rj 73 10) + "Date: " arch-date + "\n\n" + "Submitted by: " arch-from + "\n" + '(arch-tocol 79 ?-) + "\n" + "Keywords: " arch-keywords + "\n\n" + "Parts: " arch-parts + "\n\n====== Remarks ======\n\n" + arch-remarks + )) + +;; @r{That's all, folks!} +@end example + +@node Credits +@chapter Credits + +Bug fixes and other useful suggestions were supplied by +Harald Hanche-Olsen (@code{hanche@@imf.unit.no}), +@code{cwitty@@portia.stanford.edu}, +Jonathan I. Kamens, +Per Cederqvist (@code{ceder@@signum.se}), +Michael Lipka (@code{lipka@@lip.hanse.de}), +Andy Piper (@code{ajp@@eng.cam.ac.uk}), +Frederic Pierresteguy (@code{F.Pierresteguy@@frcl.bull.fr}), +Ignatios Souvatzis +and Richard Stallman (@code{rms@@gnu.org}). + +This documentation was slightly inspired by the documentation of ``rolo +mode'' by Paul Davis at Schlumberger Cambridge Research +(@code{davis%scrsu1%sdr.slb.com@@relay.cs.net}). + +None of this would have been possible without GNU Emacs of the Free +Software Foundation. Thanks, Richard! + +@node Index +@unnumbered Index +@printindex cp + +@contents +@bye diff --git a/man/frames.texi b/man/frames.texi new file mode 100644 index 00000000000..392e890c50c --- /dev/null +++ b/man/frames.texi @@ -0,0 +1,1076 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Frames, International, Windows, Top +@chapter Frames and X Windows +@cindex frames + + When using the X Window System, you can create multiple windows at the +X level in a single Emacs session. Each X window that belongs to Emacs +displays a @dfn{frame} which can contain one or several Emacs windows. +A frame initially contains a single general-purpose Emacs window which +you can subdivide vertically or horizontally into smaller windows. A +frame normally contains its own echo area and minibuffer, but you can +make frames that don't have these---they use the echo area and +minibuffer of another frame. + + Editing you do in one frame also affects the other frames. For +instance, if you put text in the kill ring in one frame, you can yank it +in another frame. If you exit Emacs through @kbd{C-x C-c} in one frame, +it terminates all the frames. To delete just one frame, use @kbd{C-x 5 +0}. + + To avoid confusion, we reserve the word ``window'' for the +subdivisions that Emacs implements, and never use it to refer to a +frame. + + Emacs compiled for MS-DOS emulates some aspects of the window system +so that you can use many of the features described in this chapter. +@xref{MS-DOS Input}, for more information. + +@menu +* Mouse Commands:: Moving, cutting, and pasting, with the mouse. +* Secondary Selection:: Cutting without altering point and mark. +* Mouse References:: Using the mouse to select an item from a list. +* Menu Mouse Clicks:: Mouse clicks that bring up menus. +* Mode Line Mouse:: Mouse clicks on the mode line. +* Speedbar:: How to make and use a speedbar frame. +* Creating Frames:: Creating additional Emacs frames with various contents. +* Multiple Displays:: How one Emacs job can talk to several displays. +* Special Buffer Frames:: You can make certain buffers have their own frames. +* Frame Parameters:: Changing the colors and other modes of frames. +* Scroll Bars:: How to enable and disable scroll bars; how to use them. +* Menu Bars:: Enabling and disabling the menu bar. +* Faces:: How to change the display style using faces. +* Font Lock:: Minor mode for syntactic highlighting using faces. +* Support Modes:: Font Lock support modes make Font Lock faster. +* Highlight Changes:: Using colors to show where you changed the buffer. +* Misc X:: Iconifying and deleting frames. Region highlighting. +* Non-Window Terminals:: Multiple frames on terminals that show only one. +@end menu + +@node Mouse Commands +@section Mouse Commands for Editing +@cindex mouse buttons (what they do) + + The mouse commands for selecting and copying a region are mostly +compatible with the @code{xterm} program. You can use the same mouse +commands for copying between Emacs and other X client programs. + +@kindex DELETE + If you select a region with any of these mouse commands, and then +immediately afterward type the @key{DELETE} function key, it deletes the +region that you selected. The @key{BACKSPACE} function key and the +ASCII character @key{DEL} do not do this; if you type any other key +in between the mouse command and @key{DELETE}, it does not do this. + +@findex mouse-set-region +@findex mouse-set-point +@findex mouse-yank-at-click +@findex mouse-save-then-click +@kindex Mouse-1 +@kindex Mouse-2 +@kindex Mouse-3 +@table @kbd +@item Mouse-1 +Move point to where you click (@code{mouse-set-point}). +This is normally the left button. + +@item Drag-Mouse-1 +Set the region to the text you select by dragging, and copy it to the +kill ring (@code{mouse-set-region}). You can specify both ends of the +region with this single command. + +@vindex mouse-scroll-min-lines +If you move the mouse off the top or bottom of the window while +dragging, the window scrolls at a steady rate until you move the mouse +back into the window. This way, you can select regions that don't fit +entirely on the screen. The number of lines scrolled per step depends +on how far away from the window edge the mouse has gone; the variable +@code{mouse-scroll-min-lines} specifies a minimum step size. + +@item Mouse-2 +Yank the last killed text, where you click (@code{mouse-yank-at-click}). +This is normally the middle button. + +@item Mouse-3 +This command, @code{mouse-save-then-kill}, has several functions +depending on where you click and the status of the region. + +The most basic case is when you click @kbd{Mouse-1} in one place and +then @kbd{Mouse-3} in another. This selects the text between those two +positions as the region. It also copies the new region to the kill +ring, so that you can copy it to someplace else. + +If you click @kbd{Mouse-1} in the text, scroll with the scroll bar, and +then click @kbd{Mouse-3}, it remembers where point was before scrolling +(where you put it with @kbd{Mouse-1}), and uses that position as the +other end of the region. This is so that you can select a region that +doesn't fit entirely on the screen. + +More generally, if you do not have a highlighted region, @kbd{Mouse-3} +selects the text between point and the click position as the region. It +does this by setting the mark where point was, and moving point to where +you click. + +If you have a highlighted region, or if the region was set just before +by dragging button 1, @kbd{Mouse-3} adjusts the nearer end of the region +by moving it to where you click. The adjusted region's text also +replaces the old region's text in the kill ring. + +If you originally specified the region using a double or triple +@kbd{Mouse-1}, so that the region is defined to consist of entire words +or lines, then adjusting the region with @kbd{Mouse-3} also proceeds by +entire words or lines. + +If you use @kbd{Mouse-3} a second time consecutively, at the same place, +that kills the region already selected. + +@item Double-Mouse-1 +This key sets the region around the word which you click on. If you +click on a character with ``symbol'' syntax (such as underscore, in C +mode), it sets the region around the symbol surrounding that character. + +If you click on a character with open-parenthesis or close-parenthesis +syntax, it sets the region around the parenthetical grouping (sexp) +which that character starts or ends. If you click on a character with +string-delimiter syntax (such as a singlequote or doublequote in C), it +sets the region around the string constant (using heuristics to figure +out whether that character is the beginning or the end of it). + +@item Double-Drag-Mouse-1 +This key selects a region made up of the words you drag across. + +@item Triple-Mouse-1 +This key sets the region around the line you click on. + +@item Triple-Drag-Mouse-1 +This key selects a region made up of the lines you drag across. +@end table + + The simplest way to kill text with the mouse is to press @kbd{Mouse-1} +at one end, then press @kbd{Mouse-3} twice at the other end. +@xref{Killing}. To copy the text into the kill ring without deleting it +from the buffer, press @kbd{Mouse-3} just once---or just drag across the +text with @kbd{Mouse-1}. Then you can copy it elsewhere by yanking it. + +@vindex mouse-yank-at-point + To yank the killed or copied text somewhere else, move the mouse there +and press @kbd{Mouse-2}. @xref{Yanking}. However, if +@code{mouse-yank-at-point} is non-@code{nil}, @kbd{Mouse-2} yanks at +point. Then it does not matter where you click, or even which of the +frame's windows you click on. The default value is @code{nil}. This +variable also affects yanking the secondary selection. + +@cindex cutting and X +@cindex pasting and X +@cindex X cutting and pasting + To copy text to another X window, kill it or save it in the kill ring. +Under X, this also sets the @dfn{primary selection}. Then use the +``paste'' or ``yank'' command of the program operating the other window +to insert the text from the selection. + + To copy text from another X window, use the ``cut'' or ``copy'' command +of the program operating the other window, to select the text you want. +Then yank it in Emacs with @kbd{C-y} or @kbd{Mouse-2}. + + These cutting and pasting commands also work on MS-Windows. + +@cindex primary selection +@cindex cut buffer +@cindex selection, primary +@vindex x-cut-buffer-max + When Emacs puts text into the kill ring, or rotates text to the front +of the kill ring, it sets the @dfn{primary selection} in the X server. +This is how other X clients can access the text. Emacs also stores the +text in the cut buffer, but only if the text is short enough +(@code{x-cut-buffer-max} specifies the maximum number of characters); +putting long strings in the cut buffer can be slow. + + The commands to yank the first entry in the kill ring actually check +first for a primary selection in another program; after that, they check +for text in the cut buffer. If neither of those sources provides text +to yank, the kill ring contents are used. + +@node Secondary Selection +@section Secondary Selection +@cindex secondary selection + + The @dfn{secondary selection} is another way of selecting text using +X. It does not use point or the mark, so you can use it to kill text +without setting point or the mark. + +@table @kbd +@findex mouse-set-secondary +@kindex M-Drag-Mouse-1 +@item M-Drag-Mouse-1 +Set the secondary selection, with one end at the place where you press +down the button, and the other end at the place where you release it +(@code{mouse-set-secondary}). The highlighting appears and changes as +you drag. + +If you move the mouse off the top or bottom of the window while +dragging, the window scrolls at a steady rate until you move the mouse +back into the window. This way, you can mark regions that don't fit +entirely on the screen. + +@findex mouse-start-secondary +@kindex M-Mouse-1 +@item M-Mouse-1 +Set one endpoint for the @dfn{secondary selection} +(@code{mouse-start-secondary}). + +@findex mouse-secondary-save-then-kill +@kindex M-Mouse-3 +@item M-Mouse-3 +Make a secondary selection, using the place specified with @kbd{M-Mouse-1} +as the other end (@code{mouse-secondary-save-then-kill}). A second click +at the same place kills the secondary selection just made. + +@findex mouse-yank-secondary +@kindex M-Mouse-2 +@item M-Mouse-2 +Insert the secondary selection where you click +(@code{mouse-yank-secondary}). This places point at the end of the +yanked text. +@end table + +Double or triple clicking of @kbd{M-Mouse-1} operates on words and +lines, much like @kbd{Mouse-1}. + +If @code{mouse-yank-at-point} is non-@code{nil}, @kbd{M-Mouse-2} +yanks at point. Then it does not matter precisely where you click; all +that matters is which window you click on. @xref{Mouse Commands}. + +@node Mouse References +@section Following References with the Mouse +@kindex Mouse-2 @r{(selection)} + + Some Emacs buffers display lists of various sorts. These include +lists of files, of buffers, of possible completions, of matches for +a pattern, and so on. + + Since yanking text into these buffers is not very useful, most of them +define @kbd{Mouse-2} specially, as a command to use or view the item you +click on. + + For example, if you click @kbd{Mouse-2} on a file name in a Dired +buffer, you visit that file. If you click @kbd{Mouse-2} on an error +message in the @samp{*Compilation*} buffer, you go to the source code +for that error message. If you click @kbd{Mouse-2} on a completion in +the @samp{*Completions*} buffer, you choose that completion. + + You can usually tell when @kbd{Mouse-2} has this special sort of +meaning because the sensitive text highlights when you move the mouse +over it. + +@node Menu Mouse Clicks +@section Mouse Clicks for Menus + + Mouse clicks modified with the @key{CTRL} and @key{SHIFT} keys +bring up menus. + +@kindex C-Mouse-3 +@table @kbd +@item C-Mouse-1 +This menu is for selecting a buffer. + +@item C-Mouse-2 +This menu is for specifying faces and other text properties +for editing formatted text. @xref{Formatted Text}. + +@item C-Mouse-3 +This menu is mode-specific. For most modes, this menu has the same +items as all the mode-specific menu-bar menus put together. Some modes +may specify a different menu for this button.@footnote{Some systems use +@kbd{Mouse-3} for a mode-specific menu. We took a survey of users, and +found they preferred to keep @kbd{Mouse-3} for selecting and killing +regions. Hence the decision to use @kbd{C-Mouse-3} for this menu.} + +@item S-mouse-1 +This menu is for specifying the frame's principal font. +@end table + +@node Mode Line Mouse +@section Mode Line Mouse Commands + + You can use mouse clicks on window mode lines to select and manipulate +windows. + +@table @kbd +@item Mouse-1 +@kbd{Mouse-1} on a mode line selects the window above. By dragging +@kbd{Mouse-1} on the mode line, you can move it, thus changing the +height of the windows above and below. + +@item Mouse-2 +@kbd{Mouse-2} on a mode line expands that window to fill its frame. + +@item Mouse-3 +@kbd{Mouse-3} on a mode line deletes the window above. + +@item C-Mouse-2 +@kbd{C-Mouse-2} on a mode line splits the window above +horizontally, above the place in the mode line where you click. +@end table + + @kbd{C-Mouse-2} on a scroll bar splits the corresponding window +vertically. @xref{Split Window}. + +@node Creating Frames +@section Creating Frames +@cindex creating frames + +@kindex C-x 5 + The prefix key @kbd{C-x 5} is analogous to @kbd{C-x 4}, with parallel +subcommands. The difference is that @kbd{C-x 5} commands create a new +frame rather than just a new window in the selected frame (@pxref{Pop +Up Window}). If an existing visible or iconified frame already displays +the requested material, these commands use the existing frame, after +raising or deiconifying as necessary. + + The various @kbd{C-x 5} commands differ in how they find or create the +buffer to select: + +@table @kbd +@item C-x 5 2 +@kindex C-x 5 2 +@findex make-frame-command +Create a new frame (@code{make-frame-command}). +@item C-x 5 b @var{bufname} @key{RET} +Select buffer @var{bufname} in another frame. This runs +@code{switch-to-buffer-other-frame}. +@item C-x 5 f @var{filename} @key{RET} +Visit file @var{filename} and select its buffer in another frame. This +runs @code{find-file-other-frame}. @xref{Visiting}. +@item C-x 5 d @var{directory} @key{RET} +Select a Dired buffer for directory @var{directory} in another frame. +This runs @code{dired-other-frame}. @xref{Dired}. +@item C-x 5 m +Start composing a mail message in another frame. This runs +@code{mail-other-frame}. It is the other-frame variant of @kbd{C-x m}. +@xref{Sending Mail}. +@item C-x 5 . +Find a tag in the current tag table in another frame. This runs +@code{find-tag-other-frame}, the multiple-frame variant of @kbd{M-.}. +@xref{Tags}. +@item C-x 5 r @var{filename} @key{RET} +@kindex C-x 5 r +@findex find-file-read-only-other-frame +Visit file @var{filename} read-only, and select its buffer in another +frame. This runs @code{find-file-read-only-other-frame}. +@xref{Visiting}. +@end table + +@cindex default-frame-alist +@cindex initial-frame-alist + You can control the appearance of new frames you create by setting the +frame parameters in @code{default-frame-alist}. You can use the +variable @code{initial-frame-alist} to specify parameters that affect +only the initial frame. @xref{Initial Parameters,,, elisp, The Emacs +Lisp Reference Manual}, for more information. + +@cindex font (default) + The easiest way to specify the principal font for all your Emacs +frames is with an X resource (@pxref{Font X}), but you can also do it by +modifying @code{default-frame-alist} to specify the @code{font} +parameter, as shown here: + +@example +(add-to-list 'default-frame-alist '(font . "10x20")) +@end example + +@node Speedbar +@section Making and Using a Speedbar Frame +@cindex speedbar + + An Emacs frame can have a @dfn{speedbar}, which is a vertical window +that serves as a scrollable menu of files you could visit and tags +within those files. To create a speedbar, type @kbd{M-x speedbar}; this +creates a speedbar window for the selected frame. From then on, you can +click on a file name in the speedbar to visit that file in the +corresponding Emacs frame, or click on a tag name to jump to that tag in +the Emacs frame. + + Initially the speedbar lists the immediate contents of the current +directory, one file per line. Each line also has a box, @samp{[+]} or +@samp{<+>}, that you can click on with @kbd{Mouse-2} to ``open up'' the +contents of that item. If the line names a directory, opening it adds +the contents of that directory to the speedbar display, underneath the +directory's own line. If the line lists an ordinary file, opening it up +adds a list of the tags in that file to the speedbar display. When a +file is opened up, the @samp{[+]} changes to @samp{[-]}; you can click +on that box to ``close up'' that file (hide its contents). + + Some major modes, including Rmail mode, Info, and GUD, have +specialized ways of putting useful items into the speedbar for you to +select. For example, in Rmail mode, the speedbar shows a list of Rmail +files, and lets you move the current message to another Rmail file by +clicking on its @samp{<M>} box. + + A speedbar belongs to one Emacs frame, and always operates on that +frame. If you use multiple frames, you can make a speedbar for some or +all of the frames; type @kbd{M-x speedbar} in any given frame to make a +speedbar for it. + +@node Multiple Displays +@section Multiple Displays +@cindex multiple displays + + A single Emacs can talk to more than one X Windows display. +Initially, Emacs uses just one display---the one specified with the +@code{DISPLAY} environment variable or with the @samp{--display} option +(@pxref{Initial Options}). To connect to another display, use the +command @code{make-frame-on-display}: + +@findex make-frame-on-display +@table @kbd +@item M-x make-frame-on-display @key{RET} @var{display} @key{RET} +Create a new frame on display @var{display}. +@end table + + A single X server can handle more than one screen. When you open +frames on two screens belonging to one server, Emacs knows they share a +single keyboard, and it treats all the commands arriving from these +screens as a single stream of input. + + When you open frames on different X servers, Emacs makes a separate +input stream for each server. This way, two users can type +simultaneously on the two displays, and Emacs will not garble their +input. Each server also has its own selected frame. The commands you +enter with a particular X server apply to that server's selected frame. + + Despite these features, people using the same Emacs job from different +displays can still interfere with each other if they are not careful. +For example, if any one types @kbd{C-x C-c}, that exits the Emacs job +for all of them! + +@node Special Buffer Frames +@section Special Buffer Frames + +@vindex special-display-buffer-names + You can make certain chosen buffers, for which Emacs normally creates +a second window when you have just one window, appear in special frames +of their own. To do this, set the variable +@code{special-display-buffer-names} to a list of buffer names; any +buffer whose name is in that list automatically gets a special frame, +when an Emacs command wants to display it ``in another window.'' + + For example, if you set the variable this way, + +@example +(setq special-display-buffer-names + '("*Completions*" "*grep*" "*tex-shell*")) +@end example + +@noindent +then completion lists, @code{grep} output and the @TeX{} mode shell +buffer get individual frames of their own. These frames, and the +windows in them, are never automatically split or reused for any other +buffers. They continue to show the buffers they were created for, +unless you alter them by hand. Killing the special buffer deletes its +frame automatically. + +@vindex special-display-regexps + More generally, you can set @code{special-display-regexps} to a list +of regular expressions; then a buffer gets its own frame if its name +matches any of those regular expressions. (Once again, this applies only +to buffers that normally get displayed for you in a separate window.) + +@vindex special-display-frame-alist + The variable @code{special-display-frame-alist} specifies the frame +parameters for these frames. It has a default value, so you don't need +to set it. + + For those who know Lisp, an element of +@code{special-display-buffer-names} or @code{special-display-regexps} +can also be a list. Then the first element is the buffer name or +regular expression; the rest of the list specifies how to create the +frame. It can be an association list specifying frame parameter values; +these values take precedence over parameter values specified in +@code{special-display-frame-alist}. Alternatively, it can have this +form: + +@example +(@var{function} @var{args}...) +@end example + +@noindent +where @var{function} is a symbol. Then the frame is constructed by +calling @var{function}; its first argument is the buffer, and its +remaining arguments are @var{args}. + + An analogous feature lets you specify buffers which should be +displayed in the selected window. @xref{Force Same Window}. The +same-window feature takes precedence over the special-frame feature; +therefore, if you add a buffer name to +@code{special-display-buffer-names} and it has no effect, check to see +whether that feature is also in use for the same buffer name. + +@node Frame Parameters +@section Setting Frame Parameters +@cindex colors +@cindex Auto-Raise mode +@cindex Auto-Lower mode + + This section describes commands for altering the display style and +window management behavior of the selected frame. + +@findex set-foreground-color +@findex set-background-color +@findex set-cursor-color +@findex set-mouse-color +@findex set-border-color +@findex auto-raise-mode +@findex auto-lower-mode +@table @kbd +@item M-x set-foreground-color @key{RET} @var{color} @key{RET} +Specify color @var{color} for the foreground of the selected frame. +(This also changes the foreground color of the default face.) + +@item M-x set-background-color @key{RET} @var{color} @key{RET} +Specify color @var{color} for the background of the selected frame. +(This also changes the background color of the default face.) + +@item M-x set-cursor-color @key{RET} @var{color} @key{RET} +Specify color @var{color} for the cursor of the selected frame. + +@item M-x set-mouse-color @key{RET} @var{color} @key{RET} +Specify color @var{color} for the mouse cursor when it is over the +selected frame. + +@item M-x set-border-color @key{RET} @var{color} @key{RET} +Specify color @var{color} for the border of the selected frame. + +@item M-x list-colors-display +Display the defined color names and show what the colors look like. +This command is somewhat slow. + +@item M-x auto-raise-mode +Toggle whether or not the selected frame should auto-raise. Auto-raise +means that every time you move the mouse onto the frame, it raises the +frame. + +Note that this auto-raise feature is implemented by Emacs itself. Some +window managers also implement auto-raise. If you enable auto-raise for +Emacs frames in your X window manager, it should work, but it is beyond +Emacs's control and therefore @code{auto-raise-mode} has no effect on +it. + +@item M-x auto-lower-mode +Toggle whether or not the selected frame should auto-lower. +Auto-lower means that every time you move the mouse off the frame, +the frame moves to the bottom of the stack of X windows. + +The command @code{auto-lower-mode} has no effect on auto-lower +implemented by the X window manager. To control that, you must use +the appropriate window manager features. + +@findex set-frame-font +@item M-x set-frame-font @key{RET} @var{font} @key{RET} +@cindex font (principal) +Specify font @var{font} as the principal font for the selected frame. +The principal font controls several face attributes of the +@code{default} face (@pxref{Faces}). For example, if the principal font +has a height of 12 pt, all text will be drawn in 12 pt fonts, unless you +use another face that specifies a different height. @xref{Font X}, for +ways to list the available fonts on your system. + +@kindex S-Mouse-1 +You can also set a frame's principal font through a pop-up menu. +Press @kbd{S-Mouse-1} to activate this menu. +@end table + + In Emacs versions that use an X toolkit, the color-setting and +font-setting functions don't affect menus and the menu bar, since they +are displayed by their own widget classes. To change the appearance of +the menus and menu bar, you must use X resources (@pxref{Resources X}). +@xref{Colors X}, regarding colors. @xref{Font X}, regarding choice of +font. + + For information on frame parameters and customization, see @ref{Frame +Parameters,,, elisp, The Emacs Lisp Reference Manual}. + +@node Scroll Bars +@section Scroll Bars +@cindex Scroll Bar mode +@cindex mode, Scroll Bar + + When using X, Emacs normally makes a @dfn{scroll bar} at the left of +each Emacs window. The scroll bar runs the height of the window, and +shows a moving rectangular inner box which represents the portion of the +buffer currently displayed. The entire height of the scroll bar +represents the entire length of the buffer. + + You can use @kbd{Mouse-2} (normally, the middle button) in the scroll +bar to move or drag the inner box up and down. If you move it to the +top of the scroll bar, you see the top of the buffer. If you move it to +the bottom of the scroll bar, you see the bottom of the buffer. + + The left and right buttons in the scroll bar scroll by controlled +increments. @kbd{Mouse-1} (normally, the left button) moves the line at +the level where you click up to the top of the window. @kbd{Mouse-3} +(normally, the right button) moves the line at the top of the window +down to the level where you click. By clicking repeatedly in the same +place, you can scroll by the same distance over and over. + + Aside from scrolling, you can also click @kbd{C-Mouse-2} in the scroll +bar to split a window vertically. The split occurs on the line where +you click. + +@findex scroll-bar-mode + You can enable or disable Scroll Bar mode with the command @kbd{M-x +scroll-bar-mode}. With no argument, it toggles the use of scroll bars. +With an argument, it turns use of scroll bars on if and only if the +argument is positive. This command applies to all frames, including +frames yet to be created. You can use the X resource +@samp{verticalScrollBars} to control the initial setting of Scroll Bar +mode. @xref{Resources X}. + +@findex toggle-scroll-bar + To enable or disable scroll bars for just the selected frame, use the +@kbd{M-x toggle-scroll-bar} command. + +@node Menu Bars +@section Menu Bars +@cindex Menu Bar mode +@cindex mode, Menu Bar + + You can turn display of menu bars on or off with @kbd{M-x +menu-bar-mode}. With no argument, this command toggles Menu Bar mode, a +minor mode. With an argument, the command turns Menu Bar mode on if the +argument is positive, off if the argument is not positive. You can use +the X resource @samp{menuBarLines} to control the initial setting of +Menu Bar mode. @xref{Resources X}. Expert users often turn off the +menu bar, especially on text-only terminals, where this makes one +additional line available for text. + + @xref{Menu Bar}, for information on how to invoke commands with the +menu bar. + +@node Faces +@section Using Multiple Typefaces +@cindex faces + + When using Emacs with X, you can set up multiple styles of displaying +characters. The aspects of style that you can control are the type +font, the foreground color, the background color, and whether to +underline. Emacs on MS-DOS supports faces partially by letting you +control the foreground and background colors of each face +(@pxref{MS-DOS}). + + The way you control display style is by defining named @dfn{faces}. +Each face can specify a type font, a foreground color, a background +color, and an underline flag; but it does not have to specify all of +them. Then by specifying the face or faces to use for a given part +of the text in the buffer, you control how that text appears. + + The style of display used for a given character in the text is +determined by combining several faces. Any aspect of the display style +that isn't specified by overlays or text properties comes from the frame +itself. + + Enriched mode, the mode for editing formatted text, includes several +commands and menus for specifying faces. @xref{Format Faces}, for how +to specify the font for text in the buffer. @xref{Format Colors}, for +how to specify the foreground and background color. + + To alter the appearance of a face, use the customization buffer. +@xref{Face Customization}. You can also use X resources to specify +attributes of particular faces (@pxref{Resources X}). + +@findex list-faces-display + To see what faces are currently defined, and what they look like, type +@kbd{M-x list-faces-display}. It's possible for a given face to look +different in different frames; this command shows the appearance in the +frame in which you type it. Here's a list of the standardly defined +faces: + +@table @code +@item default +This face is used for ordinary text that doesn't specify any other face. +@item modeline +This face is used for mode lines. By default, it's set up as the +inverse of the default face. @xref{Display Vars}. +@item highlight +This face is used for highlighting portions of text, in various modes. +@item region +This face is used for displaying a selected region (when Transient Mark +mode is enabled---see below). +@item secondary-selection +This face is used for displaying a secondary selection (@pxref{Secondary +Selection}). +@item bold +This face uses a bold variant of the default font, if it has one. +@item italic +This face uses an italic variant of the default font, if it has one. +@item bold-italic +This face uses a bold italic variant of the default font, if it has one. +@item underline +This face underlines text. +@end table + +@cindex @code{region} face + When Transient Mark mode is enabled, the text of the region is +highlighted when the mark is active. This uses the face named +@code{region}; you can control the style of highlighting by changing the +style of this face (@pxref{Face Customization}). @xref{Transient Mark}, +for more information about Transient Mark mode and activation and +deactivation of the mark. + + One easy way to use faces is to turn on Font Lock mode. This minor +mode, which is always local to a particular buffer, arranges to +choose faces according to the syntax of the text you are editing. It +can recognize comments and strings in most languages; in several +languages, it can also recognize and properly highlight various other +important constructs. @xref{Font Lock}, for more information about +Font Lock mode and syntactic highlighting. + + You can print out the buffer with the highlighting that appears +on your screen using the command @code{ps-print-buffer-with-faces}. +@xref{Postscript}. + +@node Font Lock +@section Font Lock mode +@cindex Font Lock mode +@cindex mode, Font Lock +@cindex syntax highlighting + + Font Lock mode is a minor mode, always local to a particular +buffer, which highlights (or ``fontifies'') using various faces +according to the syntax of the text you are editing. It can +recognize comments and strings in most languages; in several +languages, it can also recognize and properly highlight various other +important constructs---for example, names of functions being defined +or reserved keywords. + +@findex font-lock-mode +@findex turn-on-font-lock + The command @kbd{M-x font-lock-mode} turns Font Lock mode on or off +according to the argument, and toggles the mode when it has no argument. +The function @code{turn-on-font-lock} unconditionally enables Font Lock +mode. This is useful in mode-hook functions. For example, to enable +Font Lock mode whenever you edit a C file, you can do this: + +@example +(add-hook 'c-mode-hook 'turn-on-font-lock) +@end example + +@findex global-font-lock-mode + To turn on Font Lock mode automatically in all modes which support it, +use the function @code{global-font-lock-mode}, like this: + +@example +(global-font-lock-mode 1) +@end example + +@kindex M-g M-g +@findex font-lock-fontify-block + In Font Lock mode, when you edit the text, the highlighting updates +automatically in the line that you changed. Most changes don't affect +the highlighting of subsequent lines, but occasionally they do. To +rehighlight a range of lines, use the command @kbd{M-g M-g} +(@code{font-lock-fontify-block}). + +@vindex font-lock-mark-block-function + In certain major modes, @kbd{M-g M-g} refontifies the entire current +function. (The variable @code{font-lock-mark-block-function} controls +how to find the current function.) In other major modes, @kbd{M-g M-g} +refontifies 16 lines above and below point. + + With a prefix argument @var{n}, @kbd{M-g M-g} refontifies @var{n} +lines above and below point, regardless of the mode. + + To get the full benefit of Font Lock mode, you need to choose a +default font which has bold, italic, and bold-italic variants; or else +you need to have a color or gray-scale screen. + +@vindex font-lock-maximum-decoration + The variable @code{font-lock-maximum-decoration} specifies the +preferred level of fontification, for modes that provide multiple +levels. Level 1 is the least amount of fontification; some modes +support levels as high as 3. The normal default is ``as high as +possible.'' You can specify an integer, which applies to all modes, or +you can specify different numbers for particular major modes; for +example, to use level 1 for C/C++ modes, and the default level +otherwise, use this: + +@example +(setq font-lock-maximum-decoration + '((c-mode . 1) (c++-mode . 1))) +@end example + +@vindex font-lock-maximum-size + Fontification can be too slow for large buffers, so you can suppress +it. The variable @code{font-lock-maximum-size} specifies a buffer size, +beyond which buffer fontification is suppressed. + +@c @w is used below to prevent a bad page-break. +@vindex font-lock-beginning-of-syntax-function + Comment and string fontification (or ``syntactic'' fontification) +relies on analysis of the syntactic structure of the buffer text. For +the purposes of speed, some modes including C mode and Lisp mode rely on +a special convention: an open-parenthesis in the leftmost column always +defines the @w{beginning} of a defun, and is thus always outside any string +or comment. (@xref{Defuns}.) If you don't follow this convention, +then Font Lock mode can misfontify the text after an open-parenthesis in +the leftmost column that is inside a string or comment. + + The variable @code{font-lock-beginning-of-syntax-function} (always +buffer-local) specifies how Font Lock mode can find a position +guaranteed to be outside any comment or string. In modes which use the +leftmost column parenthesis convention, the default value of the variable +is @code{beginning-of-defun}---that tells Font Lock mode to use the +convention. If you set this variable to @code{nil}, Font Lock no longer +relies on the convention. This avoids incorrect results, but the price +is that, in some cases, fontification for a changed text must rescan +buffer text from the beginning of the buffer. + +@findex font-lock-add-keywords + Font Lock highlighting patterns already exist for many modes, but you +may want to fontify additional patterns. You can use the function +@code{font-lock-add-keywords}, to add your own highlighting patterns for +a particular mode. For example, to highlight @samp{FIXME:} words in C +comments, use this: + +@example +(font-lock-add-keywords + 'c-mode + '(("\\<\\(FIXME\\):" 1 font-lock-warning-face t))) +@end example + +@node Support Modes +@section Font Lock Support Modes + + Font Lock support modes make Font Lock mode faster for large buffers. +There are two support modes: Fast Lock mode and Lazy Lock mode. They +use two different methods of speeding up Font Lock mode. + +@menu +* Fast Lock Mode:: Saving font information in files. +* Lazy Lock Mode:: Fontifying only text that is actually displayed. +* Fast or Lazy:: Which support mode is best for you? +@end menu + +@node Fast Lock Mode +@subsection Fast Lock Mode + +@cindex Fast Lock mode +@cindex mode, Fast Lock + To make Font Lock mode faster for buffers visiting large files, you +can use Fast Lock mode. Fast Lock mode saves the font information for +each file in a separate cache file; each time you visit the file, it +rereads the font information from the cache file instead of refontifying +the text from scratch. + +@findex fast-lock-mode + The command @kbd{M-x fast-lock-mode} turns Fast Lock mode on or off, +according to the argument (with no argument, it toggles). You can also +arrange to enable Fast Lock mode whenever you use Font Lock mode, like +this: + +@example +(setq font-lock-support-mode 'fast-lock-mode) +@end example + +@vindex fast-lock-minimum-size + It is not worth writing a cache file for small buffers. Therefore, +the variable @code{fast-lock-minimum-size} specifies a minimum file size +for caching font information. + +@vindex fast-lock-cache-directories + The variable @code{fast-lock-cache-directories} specifies where to put +the cache files. Its value is a list of directories to try; @code{"."} +means the same directory as the file being edited. The default value is +@w{@code{("." "~/.emacs-flc")}}, which means to use the same directory if +possible, and otherwise the directory @file{~/.emacs-flc}. + +@vindex fast-lock-save-others + The variable @code{fast-lock-save-others} specifies whether Fast Lock +mode should save cache files for files that you do not own. A +non-@code{nil} value means yes (and that is the default). + +@node Lazy Lock Mode +@subsection Lazy Lock Mode +@cindex Lazy Lock mode +@cindex mode, Lazy Lock + + To make Font Lock mode faster for large buffers, you can use Lazy Lock +mode to reduce the amount of text that is fontified. In Lazy Lock mode, +buffer fontification is demand-driven; it happens to portions of the +buffer that are about to be displayed. And fontification of your +changes is deferred; it happens only when Emacs has been idle for a +certain short period of time. + +@findex lazy-lock-mode + The command @kbd{M-x lazy-lock-mode} turns Lazy Lock mode on or off, +according to the argument (with no argument, it toggles). You can also +arrange to enable Lazy Lock mode whenever you use Font Lock mode, like +this: + +@example +(setq font-lock-support-mode 'lazy-lock-mode) +@end example + +@vindex lazy-lock-minimum-size + It is not worth avoiding buffer fontification for small buffers. +Therefore, the variable @code{lazy-lock-minimum-size} specifies a +minimum buffer size for demand-driven buffer fontification. Buffers +smaller than that are fontified all at once, as in plain Font Lock mode. + +@vindex lazy-lock-defer-time + When you alter the buffer, Lazy Lock mode defers fontification of the +text you changed. The variable @code{lazy-lock-defer-time} specifies +how many seconds Emacs must be idle before it starts fontifying your +changes. If the value is 0, then changes are fontified immediately, as +in plain Font Lock mode. + +@vindex lazy-lock-defer-on-scrolling + Lazy Lock mode normally fontifies newly visible portions of the buffer +before they are first displayed. However, if the value of +@code{lazy-lock-defer-on-scrolling} is non-@code{nil}, newly visible +text is fontified only when Emacs is idle for +@code{lazy-lock-defer-time} seconds. + +@vindex lazy-lock-defer-contextually + In some modes, including C mode and Emacs Lisp mode, changes in one +line's contents can alter the context for subsequent lines, and thus +change how they ought to be fontified. Ordinarily, you must type +@kbd{M-g M-g} to refontify the subsequent lines. However, if you set +the variable @code{lazy-lock-defer-contextually} to non-@code{nil}, Lazy +Lock mode does this automatically, after @code{lazy-lock-defer-time} +seconds. + +@cindex stealth fontification + When Emacs is idle for a long time, Lazy Lock fontifies additional +portions of the buffer, not yet displayed, in case you will display them +later. This is called @dfn{stealth fontification}. + +@vindex lazy-lock-stealth-time +@vindex lazy-lock-stealth-lines +@vindex lazy-lock-stealth-verbose + The variable @code{lazy-lock-stealth-time} specifies how many seconds +Emacs has to be idle before stealth fontification starts. A value of +@code{nil} means no stealth fontification. The variables +@code{lazy-lock-stealth-lines} and @code{lazy-lock-stealth-verbose} +specify the granularity and verbosity of stealth fontification. + +@node Fast or Lazy +@subsection Fast Lock or Lazy Lock? + + Here is a simple guide to help you choose one of the Font Lock support +modes. + +@itemize @bullet +@item +Fast Lock mode intervenes only during file visiting and buffer +killing (and related events); therefore buffer editing and window +scrolling are no faster or slower than in plain Font Lock mode. + +@item +Fast Lock mode is slower at reading a cache file than Lazy Lock +mode is at fontifying a window; therefore Fast Lock mode is slower at +visiting a file than Lazy Lock mode. + +@item +Lazy Lock mode intervenes during window scrolling to fontify text that +scrolls onto the screen; therefore, scrolling is slower than in plain +Font Lock mode. + +@item +Lazy Lock mode doesn't fontify during buffer editing (it defers +fontification of changes); therefore, editing is faster than in plain +Font Lock mode. + +@item +Fast Lock mode can be fooled by a file that is kept under version +control software; therefore buffer fontification may occur even when +a cache file exists for the file. + +@item +Fast Lock mode only works with a buffer visiting a file; Lazy Lock +mode works with any buffer. + +@item +Fast Lock mode generates cache files; Lazy Lock mode does not. +@end itemize + +@vindex font-lock-support-mode + The variable @code{font-lock-support-mode} specifies which of these +support modes to use; for example, to specify that Fast Lock mode is +used for C/C++ modes, and Lazy Lock mode otherwise, set the variable +like this: + +@example +(setq font-lock-support-mode + '((c-mode . fast-lock-mode) (c++-mode . fast-lock-mode) + (t . lazy-lock-mode))) +@end example + +@node Highlight Changes +@section Highlight Changes Mode + +@findex highlight-changes-mode + Use @kbd{M-x highlight-changes-mode} to enable a minor mode +that uses faces (colors, typically) to indicate which parts of +the buffer were changed most recently. + +@node Misc X +@section Miscellaneous X Window Features + + The following commands let you create, delete and operate on frames: + +@table @kbd +@item C-z +@kindex C-z @r{(X windows)} +@findex iconify-or-deiconify-frame +Iconify the selected Emacs frame (@code{iconify-or-deiconify-frame}). +The normal meaning of @kbd{C-z}, to suspend Emacs, is not useful under a +window system, so it has a different binding in that case. + +If you type this command on an Emacs frame's icon, it deiconifies the frame. + +@item C-x 5 0 +@kindex C-x 5 0 +@findex delete-frame +Delete the selected frame (@code{delete-frame}). This is not allowed if +there is only one frame. + +@item C-x 5 o +@kindex C-x 5 o +@findex other-frame +Select another frame, raise it, and warp the mouse to it so that it +stays selected. If you repeat this command, it cycles through all the +frames on your terminal. +@end table + +@node Non-Window Terminals +@section Non-Window Terminals +@cindex non-window terminals +@cindex single-frame terminals + + If your terminal does not have a window system that Emacs supports, +then it can display only one Emacs frame at a time. However, you can +still create multiple Emacs frames, and switch between them. Switching +frames on these terminals is much like switching between different +window configurations. + + Use @kbd{C-x 5 2} to create a new frame and switch to it; use @kbd{C-x +5 o} to cycle through the existing frames; use @kbd{C-x 5 0} to delete +the current frame. + + Each frame has a number to distinguish it. If your terminal can +display only one frame at a time, the selected frame's number @var{n} +appears near the beginning of the mode line, in the form +@samp{F@var{n}}. + +@findex set-frame-name +@findex select-frame-by-name + @samp{F@var{n}} is actually the frame's name. You can also specify a +different name if you wish, and you can select a frame by its name. Use +the command @kbd{M-x set-frame-name @key{RET} @var{name} @key{RET}} to +specify a new name for the selected frame, and use @kbd{M-x +select-frame-by-name @key{RET} @var{name} @key{RET}} to select a frame +according to its name. The name you specify appears in the mode line +when the frame is selected. + diff --git a/man/glossary.texi b/man/glossary.texi new file mode 100644 index 00000000000..c484b1662a0 --- /dev/null +++ b/man/glossary.texi @@ -0,0 +1,1009 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Glossary, Key Index, Intro, Top +@unnumbered Glossary + +@table @asis +@item Abbrev +An abbrev is a text string which expands into a different text string +when present in the buffer. For example, you might define a few letters +as an abbrev for a long phrase that you want to insert frequently. +@xref{Abbrevs}. + +@item Aborting +Aborting means getting out of a recursive edit (q.v.@:). The +commands @kbd{C-]} and @kbd{M-x top-level} are used for this. +@xref{Quitting}. + +@item Alt +Alt is the name of a modifier bit which a keyboard input character may +have. To make a character Alt, type it while holding down the @key{ALT} +key. Such characters are given names that start with @kbd{Alt-} +(usually written @kbd{A-} for short). (Note that many terminals have a +key labeled @key{ALT} which is really a @key{META} key.) @xref{User +Input, Alt}. + +@item ASCII character +An ASCII character is either an ASCII control character or an ASCII +printing character. @xref{User Input}. + +@item ASCII control character +An ASCII control character is the Control version of an upper-case +letter, or the Control version of one of the characters @samp{@@[\]^_?}. + +@item ASCII printing character +ASCII printing characters include letters, digits, space, and these +punctuation characters: @samp{!@@#$%^& *()_-+=|\~` @{@}[]:;"' <>,.?/}. + +@item Auto Fill Mode +Auto Fill mode is a minor mode in which text that you insert is +automatically broken into lines of fixed width. @xref{Filling}. + +@item Auto Saving +Auto saving is the practice of saving the contents of an Emacs buffer in +a specially-named file, so that the information will not be lost if the +buffer is lost due to a system error or user error. @xref{Auto Save}. + +@item Backup File +A backup file records the contents that a file had before the current +editing session. Emacs makes backup files automatically to help you +track down or cancel changes you later regret making. @xref{Backup}. + +@item Balance Parentheses +Emacs can balance parentheses manually or automatically. Manual +balancing is done by the commands to move over balanced expressions +(@pxref{Lists}). Automatic balancing is done by blinking or +highlighting the parenthesis that matches one just inserted +(@pxref{Matching,,Matching Parens}). + +@item Bind +To bind a key sequence means to give it a binding (q.v.@:). +@xref{Rebinding}. + +@item Binding +A key sequence gets its meaning in Emacs by having a binding, which is a +command (q.v.@:), a Lisp function that is run when the user types that +sequence. @xref{Commands,Binding}. Customization often involves +rebinding a character to a different command function. The bindings of +all key sequences are recorded in the keymaps (q.v.@:). @xref{Keymaps}. + +@item Blank Lines +Blank lines are lines that contain only whitespace. Emacs has several +commands for operating on the blank lines in the buffer. + +@item Buffer +The buffer is the basic editing unit; one buffer corresponds to one text +being edited. You can have several buffers, but at any time you are +editing only one, the `selected' buffer, though several can be visible +when you are using multiple windows (q.v.). Most buffers are visiting +(q.v.@:) some file. @xref{Buffers}. + +@item Buffer Selection History +Emacs keeps a buffer selection history which records how recently each +Emacs buffer has been selected. This is used for choosing a buffer to +select. @xref{Buffers}. + +@item Button Down Event +A button down event is the kind of input event generated right away when +you press a mouse button. @xref{Mouse Buttons}. + +@item @kbd{C-} +@kbd{C-} in the name of a character is an abbreviation for Control. +@xref{User Input,C-}. + +@item @kbd{C-M-} +@kbd{C-M-} in the name of a character is an abbreviation for +Control-Meta. @xref{User Input,C-M-}. + +@item Case Conversion +Case conversion means changing text from upper case to lower case or +vice versa. @xref{Case}, for the commands for case conversion. + +@item Character +Characters form the contents of an Emacs buffer; see @ref{Text +Characters}. Also, key sequences (q.v.@:) are usually made up of +characters (though they may include other input events as well). +@xref{User Input}. + +@item Character Set +Emacs supports a number of character sets, each of which represents a +particular alphabet or script. @xref{International}. + +@item Click Event +A click event is the kind of input event generated when you press a +mouse button and release it without moving the mouse. @xref{Mouse Buttons}. + +@item Coding System +A coding system is an encoding for representing text characters in a +file or in a stream of information. Emacs has the ability to convert +text to or from a variety of coding systems when reading or writing it. +@xref{Coding Systems}. + +@item Command +A command is a Lisp function specially defined to be able to serve as a +key binding in Emacs. When you type a key sequence (q.v.@:), its +binding (q.v.@:) is looked up in the relevant keymaps (q.v.@:) to find +the command to run. @xref{Commands}. + +@item Command Name +A command name is the name of a Lisp symbol which is a command +(@pxref{Commands}). You can invoke any command by its name using +@kbd{M-x} (@pxref{M-x}). + +@item Comment +A comment is text in a program which is intended only for humans reading +the program, and which is marked specially so that it will be ignored +when the program is loaded or compiled. Emacs offers special commands +for creating, aligning and killing comments. @xref{Comments}. + +@item Compilation +Compilation is the process of creating an executable program from source +code. Emacs has commands for compiling files of Emacs Lisp code +(@pxref{Byte Compilation,, Byte Compilation, elisp, the Emacs Lisp +Reference Manual}) and programs in C and other languages +(@pxref{Compilation}). + +@item Complete Key +A complete key is a key sequence which fully specifies one action to be +performed by Emacs. For example, @kbd{X} and @kbd{C-f} and @kbd{C-x m} +are complete keys. Complete keys derive their meanings from being bound +(q.v.@:) to commands (q.v.@:). Thus, @kbd{X} is conventionally bound to +a command to insert @samp{X} in the buffer; @kbd{C-x m} is +conventionally bound to a command to begin composing a mail message. +@xref{Keys}. + +@item Completion +Completion is what Emacs does when it automatically fills out an +abbreviation for a name into the entire name. Completion is done for +minibuffer (q.v.@:) arguments when the set of possible valid inputs +is known; for example, on command names, buffer names, and +file names. Completion occurs when @key{TAB}, @key{SPC} or @key{RET} +is typed. @xref{Completion}.@refill + +@item Continuation Line +When a line of text is longer than the width of the window, it +takes up more than one screen line when displayed. We say that the +text line is continued, and all screen lines used for it after the +first are called continuation lines. @xref{Basic,Continuation,Basic +Editing}. + +@item Control Character +A control character is a character that you type by holding down the +@key{CTRL} key. Some control characters also have their own keys, so +that you can type them without using @key{CTRL}. For example, +@key{RET}, @key{TAB}, @key{ESC} and @key{DEL} are all control +characters. @xref{User Input}. + +@item Copyleft +A copyleft is a notice giving the public legal permission to +redistribute a program or other work of art. Copylefts are used by +left-wing programmers to promote freedom and cooperation, just as +copyrights are used by right-wing programmers to gain power over other +people. + +The particular form of copyleft used by the GNU project is called the +GNU General Public License. @xref{Copying}. + +@item Current Buffer +The current buffer in Emacs is the Emacs buffer on which most editing +commands operate. You can select any Emacs buffer as the current one. +@xref{Buffers}. + +@item Current Line +The line point is on (@pxref{Point}). + +@item Current Paragraph +The paragraph that point is in. If point is between paragraphs, the +current paragraph is the one that follows point. @xref{Paragraphs}. + +@item Current Defun +The defun (q.v.@:) that point is in. If point is between defuns, the +current defun is the one that follows point. @xref{Defuns}. + +@item Cursor +The cursor is the rectangle on the screen which indicates the position +called point (q.v.@:) at which insertion and deletion takes place. +The cursor is on or under the character that follows point. Often +people speak of `the cursor' when, strictly speaking, they mean +`point'. @xref{Basic,Cursor,Basic Editing}. + +@item Customization +Customization is making minor changes in the way Emacs works. It is +often done by setting variables (@pxref{Variables}) or by rebinding +key sequences (@pxref{Keymaps}). + +@item Default Argument +The default for an argument is the value that will be assumed if you +do not specify one. When the minibuffer is used to read an argument, +the default argument is used if you just type @key{RET}. +@xref{Minibuffer}. + +@item Default Directory +When you specify a file name that does not start with @samp{/} or @samp{~}, +it is interpreted relative to the current buffer's default directory. +@xref{Minibuffer File,Default Directory}. + +@item Defun +A defun is a list at the top level of parenthesis or bracket structure +in a program. It is so named because most such lists in Lisp programs +are calls to the Lisp function @code{defun}. @xref{Defuns}. + +@item @key{DEL} +@key{DEL} is a character that runs the command to delete one character of +text. @xref{Basic,DEL,Basic Editing}. + +@item Deletion +Deletion means erasing text without copying it into the kill ring +(q.v.@:). The alternative is killing (q.v.@:). @xref{Killing,Deletion}. + +@item Deletion of Files +Deleting a file means erasing it from the file system. +@xref{Misc File Ops}. + +@item Deletion of Messages +Deleting a message means flagging it to be eliminated from your mail +file. Until you expunge (q.v.@:) the Rmail file, you can still undelete +the messages you have deleted. @xref{Rmail Deletion}. + +@item Deletion of Windows +Deleting a window means eliminating it from the screen. Other windows +expand to use up the space. The deleted window can never come back, +but no actual text is thereby lost. @xref{Windows}. + +@item Directory +File directories are named collections in the file system, within which +you can place individual files or subdirectories. @xref{Directories}. + +@item Dired +Dired is the Emacs facility that displays the contents of a file +directory and allows you to ``edit the directory,'' performing +operations on the files in the directory. @xref{Dired}. + +@item Disabled Command +A disabled command is one that you may not run without special +confirmation. The usual reason for disabling a command is that it is +confusing for beginning users. @xref{Disabling}. + +@item Down Event +Short for `button down event'. + +@item Drag Event +A drag event is the kind of input event generated when you press a mouse +button, move the mouse, and then release the button. @xref{Mouse +Buttons}. + +@item Dribble File +A file into which Emacs writes all the characters that the user types +on the keyboard. Dribble files are used to make a record for +debugging Emacs bugs. Emacs does not make a dribble file unless you +tell it to. @xref{Bugs}. + +@item Echo Area +The echo area is the bottom line of the screen, used for echoing the +arguments to commands, for asking questions, and printing brief messages +(including error messages). The messages are stored in the buffer +@samp{*Messages*} so you can review them later. @xref{Echo Area}. + +@item Echoing +Echoing is acknowledging the receipt of commands by displaying them (in +the echo area). Emacs never echoes single-character key sequences; +longer key sequences echo only if you pause while typing them. + +@item Electric +We say that a character is electric if it is normally self-inserting +(q.v.), but the current major mode (q.v.) redefines it to do something +else as well. For example, some programming language major modes define +particular delimiter characters to reindent the line or insert one or +more newlines in addition to self-insertion. + +@item Error +An error occurs when an Emacs command cannot execute in the current +circumstances. When an error occurs, execution of the command stops +(unless the command has been programmed to do otherwise) and Emacs +reports the error by printing an error message (q.v.@:). Type-ahead +is discarded. Then Emacs is ready to read another editing command. + +@item Error Message +An error message is a single line of output displayed by Emacs when the +user asks for something impossible to do (such as, killing text +forward when point is at the end of the buffer). They appear in the +echo area, accompanied by a beep. + +@item @key{ESC} +@key{ESC} is a character used as a prefix for typing Meta characters on +keyboards lacking a @key{META} key. Unlike the @key{META} key (which, +like the @key{SHIFT} key, is held down while another character is +typed), you press the @key{ESC} key as you would press a letter key, and +it applies to the next character you type. + +@item Expunging +Expunging an Rmail file or Dired buffer is an operation that truly +discards the messages or files you have previously flagged for deletion. + +@item File Locking +Emacs used file locking to notice when two different users +start to edit one file at the same time. @xref{Interlocking}. + +@item File Name +A file name is a name that refers to a file. File names may be relative +or absolute; the meaning of a relative file name depends on the current +directory, but an absolute file name refers to the same file regardless +of which directory is current. On GNU and Unix systems, an absolute +file name starts with a slash (the root directory) or with @samp{~/} or +@samp{~@var{user}/} (a home directory). + +Some people use the term ``pathname'' for file names, but we do not; +we use the word ``path'' only in the term ``search path'' (q.v.). + +@item File-Name Component +A file-name component names a file directly within a particular +directory. On GNU and Unix systems, a file name is a sequence of +file-name components, separated by slashes. For example, @file{foo/bar} +is a file name containing two components, @samp{foo} and @samp{bar}; it +refers to the file named @samp{bar} in the directory named @samp{foo} in +the current directory. + +@item Fill Prefix +The fill prefix is a string that should be expected at the beginning +of each line when filling is done. It is not regarded as part of the +text to be filled. @xref{Filling}. + +@item Filling +Filling text means shifting text between consecutive lines so that all +the lines are approximately the same length. @xref{Filling}. + +@item Formatted Text +Formatted text is text that displays with formatting information while +you edit. Formatting information includes fonts, colors, and specified +margins. @xref{Formatted Text}. + +@item Frame +A frame is a rectangular cluster of Emacs windows. Emacs starts out +with one frame, but you can create more. You can subdivide each frame +into Emacs windows (q.v.). When you are using X windows, all the frames +can be visible at the same time. @xref{Frames}. + +@item Function Key +A function key is a key on the keyboard that sends input but does not +correspond to any character. @xref{Function Keys}. + +@item Global +Global means `independent of the current environment; in effect +throughout Emacs'. It is the opposite of local (q.v.@:). Particular +examples of the use of `global' appear below. + +@item Global Abbrev +A global definition of an abbrev (q.v.@:) is effective in all major +modes that do not have local (q.v.@:) definitions for the same abbrev. +@xref{Abbrevs}. + +@item Global Keymap +The global keymap (q.v.@:) contains key bindings that are in effect +except when overridden by local key bindings in a major mode's local +keymap (q.v.@:). @xref{Keymaps}. + +@item Global Mark Ring +The global mark ring records the series of buffers you have recently set +a mark in. In many cases you can use this to backtrack through buffers +you have been editing in, or in which you have found tags. @xref{Global +Mark Ring}. + +@item Global Substitution +Global substitution means replacing each occurrence of one string by +another string through a large amount of text. @xref{Replace}. + +@item Global Variable +The global value of a variable (q.v.@:) takes effect in all buffers +that do not have their own local (q.v.@:) values for the variable. +@xref{Variables}. + +@item Graphic Character +Graphic characters are those assigned pictorial images rather than +just names. All the non-Meta (q.v.@:) characters except for the +Control (q.v.@:) characters are graphic characters. These include +letters, digits, punctuation, and spaces; they do not include +@key{RET} or @key{ESC}. In Emacs, typing a graphic character inserts +that character (in ordinary editing modes). @xref{Basic,,Basic Editing}. + +@item Highlighting +Highlighting text means displaying it with a different foreground and/or +background color to make it stand out from the rest of the text in the +buffer. + +@item Hardcopy +Hardcopy means printed output. Emacs has commands for making printed +listings of text in Emacs buffers. @xref{Hardcopy}. + +@item @key{HELP} +@key{HELP} is the Emacs name for @kbd{C-h} or @key{F1}. You can type +@key{HELP} at any time to ask what options you have, or to ask what any +command does. @xref{Help}. + +@item Hyper +Hyper is the name of a modifier bit which a keyboard input character may +have. To make a character Hyper, type it while holding down the +@key{HYPER} key. Such characters are given names that start with +@kbd{Hyper-} (usually written @kbd{H-} for short). @xref{User Input, +Hyper}. + +@item Inbox +An inbox is a file in which mail is delivered by the operating system. +Rmail transfers mail from inboxes to Rmail files (q.v.@:) in which the +mail is then stored permanently or until explicitly deleted. +@xref{Rmail Inbox}. + +@item Indentation +Indentation means blank space at the beginning of a line. Most +programming languages have conventions for using indentation to +illuminate the structure of the program, and Emacs has special +commands to adjust indentation. +@xref{Indentation}. + +@item Indirect Buffer +An indirect buffer is a buffer that shares the text of another buffer, +called its base buffer. @xref{Indirect Buffers}. + +@item Input Event +An input event represents, within Emacs, one action taken by the user on +the terminal. Input events include typing characters, typing function +keys, pressing or releasing mouse buttons, and switching between Emacs +frames. @xref{User Input}. + +@item Input Method +An input method is a system for entering non-ASCII text characters by +typing sequences of ASCII characters (q.v.@:). @xref{Input Methods}. + +@item Insertion +Insertion means copying text into the buffer, either from the keyboard +or from some other place in Emacs. + +@item Interlocking +Interlocking is a feature for warning when you start to alter a file +that someone else is already editing. @xref{Interlocking,,Simultaneous +Editing}. + +@item Justification +Justification means adding extra spaces to lines of text to make them +come exactly to a specified width. @xref{Filling,Justification}. + +@item Keyboard Macro +Keyboard macros are a way of defining new Emacs commands from +sequences of existing ones, with no need to write a Lisp program. +@xref{Keyboard Macros}. + +@item Key Sequence +A key sequence (key, for short) is a sequence of input events (q.v.@:) +that are meaningful as a single unit. If the key sequence is enough to +specify one action, it is a complete key (q.v.@:); if it is not enough, +it is a prefix key (q.v.@:). @xref{Keys}. + +@item Keymap +The keymap is the data structure that records the bindings (q.v.@:) of +key sequences to the commands that they run. For example, the global +keymap binds the character @kbd{C-n} to the command function +@code{next-line}. @xref{Keymaps}. + +@item Keyboard Translation Table +The keyboard translation table is an array that translates the character +codes that come from the terminal into the character codes that make up +key sequences. @xref{Keyboard Translations}. + +@item Kill Ring +The kill ring is where all text you have killed recently is saved. +You can reinsert any of the killed text still in the ring; this is +called yanking (q.v.@:). @xref{Yanking}. + +@item Killing +Killing means erasing text and saving it on the kill ring so it can be +yanked (q.v.@:) later. Some other systems call this ``cutting.'' +Most Emacs commands to erase text do killing, as opposed to deletion +(q.v.@:). @xref{Killing}. + +@item Killing Jobs +Killing a job (such as, an invocation of Emacs) means making it cease +to exist. Any data within it, if not saved in a file, is lost. +@xref{Exiting}. + +@item Language Environment +Your choice of language environment specifies defaults for the input +method (q.v.@:) and coding system (q.v.@:). @xref{Language +Environments}. These defaults are relevant if you edit non-ASCII text +(@pxref{International}). + +@item List +A list is, approximately, a text string beginning with an open +parenthesis and ending with the matching close parenthesis. In C mode +and other non-Lisp modes, groupings surrounded by other kinds of matched +delimiters appropriate to the language, such as braces, are also +considered lists. Emacs has special commands for many operations on +lists. @xref{Lists}. + +@item Local +Local means `in effect only in a particular context'; the relevant +kind of context is a particular function execution, a particular +buffer, or a particular major mode. It is the opposite of `global' +(q.v.@:). Specific uses of `local' in Emacs terminology appear below. + +@item Local Abbrev +A local abbrev definition is effective only if a particular major mode +is selected. In that major mode, it overrides any global definition +for the same abbrev. @xref{Abbrevs}. + +@item Local Keymap +A local keymap is used in a particular major mode; the key bindings +(q.v.@:) in the current local keymap override global bindings of the +same key sequences. @xref{Keymaps}. + +@item Local Variable +A local value of a variable (q.v.@:) applies to only one buffer. +@xref{Locals}. + +@item @kbd{M-} +@kbd{M-} in the name of a character is an abbreviation for @key{META}, +one of the modifier keys that can accompany any character. +@xref{User Input}. + +@item @kbd{M-C-} +@kbd{M-C-} in the name of a character is an abbreviation for +Control-Meta; it means the same thing as @kbd{C-M-}. If your +terminal lacks a real @key{META} key, you type a Control-Meta character by +typing @key{ESC} and then typing the corresponding Control character. +@xref{User Input,C-M-}. + +@item @kbd{M-x} +@kbd{M-x} is the key sequence which is used to call an Emacs command by +name. This is how you run commands that are not bound to key sequences. +@xref{M-x}. + +@item Mail +Mail means messages sent from one user to another through the computer +system, to be read at the recipient's convenience. Emacs has commands for +composing and sending mail, and for reading and editing the mail you have +received. @xref{Sending Mail}. @xref{Rmail}, for how to read mail. + +@item Mail Composition Method +A mail composition method is a program runnable within Emacs for editing +and sending a mail message. Emacs lets you select from several +alternative mail composition methods. @xref{Mail Methods}. + +@item Major Mode +The Emacs major modes are a mutually exclusive set of options, each of +which configures Emacs for editing a certain sort of text. Ideally, +each programming language has its own major mode. @xref{Major Modes}. + +@item Mark +The mark points to a position in the text. It specifies one end of the +region (q.v.@:), point being the other end. Many commands operate on +all the text from point to the mark. Each buffer has its own mark. +@xref{Mark}. + +@item Mark Ring +The mark ring is used to hold several recent previous locations of the +mark, just in case you want to move back to them. Each buffer has its +own mark ring; in addition, there is a single global mark ring (q.v.). +@xref{Mark Ring}. + +@item Menu Bar +The menu bar is the line at the top of an Emacs frame. It contains +words you can click on with the mouse to bring up menus. The menu bar +feature is supported only with X. @xref{Menu Bars}. + +@item Message +See `mail'. + +@item Meta +Meta is the name of a modifier bit which a command character may have. +It is present in a character if the character is typed with the +@key{META} key held down. Such characters are given names that start +with @kbd{Meta-} (usually written @kbd{M-} for short). For example, +@kbd{M-<} is typed by holding down @key{META} and at the same time +typing @kbd{<} (which itself is done, on most terminals, by holding +down @key{SHIFT} and typing @kbd{,}). @xref{User Input,Meta}. + +@item Meta Character +A Meta character is one whose character code includes the Meta bit. + +@item Minibuffer +The minibuffer is the window that appears when necessary inside the +echo area (q.v.@:), used for reading arguments to commands. +@xref{Minibuffer}. + +@item Minibuffer History +The minibuffer history records the text you have specified in the past +for minibuffer arguments, so you can conveniently use the same text +again. @xref{Minibuffer History}. + +@item Minor Mode +A minor mode is an optional feature of Emacs which can be switched on +or off independently of all other features. Each minor mode has a +command to turn it on or off. @xref{Minor Modes}. + +@item Minor Mode Keymap +A keymap that belongs to a minor mode and is active when that mode is +enabled. Minor mode keymaps take precedence over the buffer's local +keymap, just as the local keymap takes precedence over the global +keymap. @xref{Keymaps}. + +@item Mode Line +The mode line is the line at the bottom of each window (q.v.@:), giving +status information on the buffer displayed in that window. @xref{Mode +Line}. + +@item Modified Buffer +A buffer (q.v.@:) is modified if its text has been changed since the +last time the buffer was saved (or since when it was created, if it +has never been saved). @xref{Saving}. + +@item Moving Text +Moving text means erasing it from one place and inserting it in +another. The usual way to move text by killing (q.v.@:) and then +yanking (q.v.@:). @xref{Killing}. + +@item MULE +MULE refers to the Emacs features for editing non-ASCII text +using multibyte characters (q.v.@:). @xref{International}. + +@item Multibyte Character +A multibyte character is a character that takes up several buffer +positions. Emacs uses multibyte characters to represent non-ASCII text, +since the number of non-ASCII characters is much more than 256. +@xref{International Intro}. + +@item Named Mark +A named mark is a register (q.v.@:) in its role of recording a +location in text so that you can move point to that location. +@xref{Registers}. + +@item Narrowing +Narrowing means creating a restriction (q.v.@:) that limits editing in +the current buffer to only a part of the text in the buffer. Text +outside that part is inaccessible to the user until the boundaries are +widened again, but it is still there, and saving the file saves it +all. @xref{Narrowing}. + +@item Newline +Control-J characters in the buffer terminate lines of text and are +therefore also called newlines. @xref{Text Characters,Newline}. + +@item Numeric Argument +A numeric argument is a number, specified before a command, to change +the effect of the command. Often the numeric argument serves as a +repeat count. @xref{Arguments}. + +@item Overwrite Mode +Overwrite mode is a minor mode. When it is enabled, ordinary text +characters replace the existing text after point rather than pushing +it to the right. @xref{Minor Modes}. + +@item Page +A page is a unit of text, delimited by formfeed characters (ASCII +control-L, code 014) coming at the beginning of a line. Some Emacs +commands are provided for moving over and operating on pages. +@xref{Pages}. + +@item Paragraph +Paragraphs are the medium-size unit of English text. There are +special Emacs commands for moving over and operating on paragraphs. +@xref{Paragraphs}. + +@item Parsing +We say that certain Emacs commands parse words or expressions in the +text being edited. Really, all they know how to do is find the other +end of a word or expression. @xref{Syntax}. + +@item Point +Point is the place in the buffer at which insertion and deletion +occur. Point is considered to be between two characters, not at one +character. The terminal's cursor (q.v.@:) indicates the location of +point. @xref{Basic,Point}. + +@item Prefix Argument +See `numeric argument'. + +@item Prefix Key +A prefix key is a key sequence (q.v.@:) whose sole function is to +introduce a set of longer key sequences. @kbd{C-x} is an example of +prefix key; any two-character sequence starting with @kbd{C-x} is +therefore a legitimate key sequence. @xref{Keys}. + +@item Primary Rmail File +Your primary Rmail file is the file named @samp{RMAIL} in your home +directory. That's where Rmail stores your incoming mail, unless you +specify a different file name. @xref{Rmail}. + +@item Primary Selection +The primary selection is one particular X selection (q.v.@:); it is the +selection that most X applications use for transferring text to and from +other applications. + +The Emacs kill commands set the primary selection and the yank command +uses the primary selection when appropriate. @xref{Killing}. + +@item Prompt +A prompt is text printed to ask the user for input. Displaying a prompt +is called prompting. Emacs prompts always appear in the echo area +(q.v.@:). One kind of prompting happens when the minibuffer is used to +read an argument (@pxref{Minibuffer}); the echoing which happens when +you pause in the middle of typing a multi-character key sequence is also +a kind of prompting (@pxref{Echo Area}). + +@item Quitting +Quitting means canceling a partially typed command or a running +command, using @kbd{C-g} (or @kbd{C-@key{BREAK}} on MS-DOS). @xref{Quitting}. + +@item Quoting +Quoting means depriving a character of its usual special significance. +The most common kind of quoting in Emacs is with @kbd{C-q}. What +constitutes special significance depends on the context and on +convention. For example, an ``ordinary'' character as an Emacs command +inserts itself; so in this context, a special character is any character +that does not normally insert itself (such as @key{DEL}, for example), +and quoting it makes it insert itself as if it were not special. Not +all contexts allow quoting. @xref{Basic,Quoting,Basic Editing}. + +@item Quoting File Names +Quoting a file name turns off the special significance of constructs +such as @samp{$}, @samp{~} and @samp{:}. @xref{Quoted File Names}. + +@item Read-Only Buffer +A read-only buffer is one whose text you are not allowed to change. +Normally Emacs makes buffers read-only when they contain text which +has a special significance to Emacs; for example, Dired buffers. +Visiting a file that is write-protected also makes a read-only buffer. +@xref{Buffers}. + +@item Rectangle +A rectangle consists of the text in a given range of columns on a given +range of lines. Normally you specify a rectangle by putting point at +one corner and putting the mark at the opposite corner. +@xref{Rectangles}. + +@item Recursive Editing Level +A recursive editing level is a state in which part of the execution of +a command involves asking the user to edit some text. This text may +or may not be the same as the text to which the command was applied. +The mode line indicates recursive editing levels with square brackets +(@samp{[} and @samp{]}). @xref{Recursive Edit}. + +@item Redisplay +Redisplay is the process of correcting the image on the screen to +correspond to changes that have been made in the text being edited. +@xref{Screen,Redisplay}. + +@item Regexp +See `regular expression'. + +@item Region +The region is the text between point (q.v.@:) and the mark (q.v.@:). +Many commands operate on the text of the region. @xref{Mark,Region}. + +@item Registers +Registers are named slots in which text or buffer positions or +rectangles can be saved for later use. @xref{Registers}. + +@item Regular Expression +A regular expression is a pattern that can match various text strings; +for example, @samp{l[0-9]+} matches @samp{l} followed by one or more +digits. @xref{Regexps}. + +@item Repeat Count +See `numeric argument'. + +@item Replacement +See `global substitution'. + +@item Restriction +A buffer's restriction is the amount of text, at the beginning or the +end of the buffer, that is temporarily inaccessible. Giving a buffer a +nonzero amount of restriction is called narrowing (q.v.@:). +@xref{Narrowing}. + +@item @key{RET} +@key{RET} is a character that in Emacs runs the command to insert a +newline into the text. It is also used to terminate most arguments +read in the minibuffer (q.v.@:). @xref{User Input,Return}. + +@item Rmail File +An Rmail file is a file containing text in a special format used by +Rmail for storing mail. @xref{Rmail}. + +@item Saving +Saving a buffer means copying its text into the file that was visited +(q.v.@:) in that buffer. This is the way text in files actually gets +changed by your Emacs editing. @xref{Saving}. + +@item Scroll Bar +A scroll bar is a tall thin hollow box that appears at the side of a +window. You can use mouse commands in the scroll bar to scroll the +window. The scroll bar feature is supported only with X. @xref{Scroll +Bars}. + +@item Scrolling +Scrolling means shifting the text in the Emacs window so as to see a +different part of the buffer. @xref{Display,Scrolling}. + +@item Searching +Searching means moving point to the next occurrence of a specified +string or the next match for a specified regular expression. +@xref{Search}. + +@item Search Path +A search path is a list of directory names, to be used for searching for +files for certain purposes. For example, the variable @code{load-path} +holds a search path for finding Lisp library files. @xref{Lisp Libraries}. + +@item Secondary Selection +The secondary selection is one particular X selection; some X +applications can use it for transferring text to and from other +applications. Emacs has special mouse commands for transferring text +using the secondary selection. @xref{Secondary Selection}. + +@item Selecting +Selecting a buffer means making it the current (q.v.@:) buffer. +@xref{Buffers,Selecting}. + +@item Selection +The X window system allows an application program to specify named +selections whose values are text. A program can also read the +selections that other programs have set up. This is the principal way +of transferring text between window applications. Emacs has commands to +work with the primary (q.v.@:) selection and the secondary (q.v.@:) +selection. + +@item Self-Documentation +Self-documentation is the feature of Emacs which can tell you what any +command does, or give you a list of all commands related to a topic +you specify. You ask for self-documentation with the help character, +@kbd{C-h}. @xref{Help}. + +@item Self-Inserting Character +A character is self-inserting if typing that character inserts that +character in the buffer. Ordinary printing and whitespace characters +are self-inserting in Emacs, except in certain special major modes. + +@item Sentences +Emacs has commands for moving by or killing by sentences. +@xref{Sentences}. + +@item Sexp +A sexp (short for `s-expression') is the basic syntactic unit of Lisp +in its textual form: either a list, or Lisp atom. Many Emacs commands +operate on sexps. The term `sexp' is generalized to languages other +than Lisp, to mean a syntactically recognizable expression. +@xref{Lists,Sexps}. + +@item Simultaneous Editing +Simultaneous editing means two users modifying the same file at once. +Simultaneous editing if not detected can cause one user to lose his +work. Emacs detects all cases of simultaneous editing and warns one of +the users to investigate. @xref{Interlocking,,Simultaneous Editing}. + +@item String +A string is a kind of Lisp data object which contains a sequence of +characters. Many Emacs variables are intended to have strings as +values. The Lisp syntax for a string consists of the characters in the +string with a @samp{"} before and another @samp{"} after. A @samp{"} +that is part of the string must be written as @samp{\"} and a @samp{\} +that is part of the string must be written as @samp{\\}. All other +characters, including newline, can be included just by writing them +inside the string; however, backslash sequences as in C, such as +@samp{\n} for newline or @samp{\241} using an octal character code, are +allowed as well. + +@item String Substitution +See `global substitution'. + +@item Syntax Table +The syntax table tells Emacs which characters are part of a word, +which characters balance each other like parentheses, etc. +@xref{Syntax}. + +@item Super +Super is the name of a modifier bit which a keyboard input character may +have. To make a character Super, type it while holding down the +@key{SUPER} key. Such characters are given names that start with +@kbd{Super-} (usually written @kbd{s-} for short). @xref{User Input, +Super}. + +@item Tags Table +A tags table is a file that serves as an index to the function +definitions in one or more other files. @xref{Tags}. + +@item Termscript File +A termscript file contains a record of all characters sent by Emacs to +the terminal. It is used for tracking down bugs in Emacs redisplay. +Emacs does not make a termscript file unless you tell it to. +@xref{Bugs}. + +@item Text +Two meanings (@pxref{Text}): + +@itemize @bullet +@item +Data consisting of a sequence of characters, as opposed to binary +numbers, images, graphics commands, executable programs, and the like. +The contents of an Emacs buffer are always text in this sense. +@item +Data consisting of written human language, as opposed to programs, +or following the stylistic conventions of human language. +@end itemize + +@item Top Level +Top level is the normal state of Emacs, in which you are editing the +text of the file you have visited. You are at top level whenever you +are not in a recursive editing level (q.v.@:) or the minibuffer +(q.v.@:), and not in the middle of a command. You can get back to top +level by aborting (q.v.@:) and quitting (q.v.@:). @xref{Quitting}. + +@item Transposition +Transposing two units of text means putting each one into the place +formerly occupied by the other. There are Emacs commands to transpose +two adjacent characters, words, sexps (q.v.@:) or lines +(@pxref{Transpose}). + +@item Truncation +Truncating text lines in the display means leaving out any text on a +line that does not fit within the right margin of the window +displaying it. See also `continuation line'. +@xref{Basic,Truncation,Basic Editing}. + +@item Undoing +Undoing means making your previous editing go in reverse, bringing +back the text that existed earlier in the editing session. +@xref{Undo}. + +@item User Option +A user option is a variable (q.v.@:) that exists so that you can customize +Emacs by setting it to a new value. @xref{Variables}. + +@item Variable +A variable is an object in Lisp that can store an arbitrary value. +Emacs uses some variables for internal purposes, and has others (known +as `user options' (q.v.@:)) just so that you can set their values to +control the behavior of Emacs. The variables used in Emacs that you +are likely to be interested in are listed in the Variables Index in +this manual. @xref{Variables}, for information on variables. + +@item Version Control +Version control systems keep track of multiple versions of a source file. +They provide a more powerful alternative to keeping backup files (q.v.@:). +@xref{Version Control}. + +@item Visiting +Visiting a file means loading its contents into a buffer (q.v.@:) +where they can be edited. @xref{Visiting}. + +@item Whitespace +Whitespace is any run of consecutive formatting characters (space, +tab, newline, and backspace). + +@item Widening +Widening is removing any restriction (q.v.@:) on the current buffer; +it is the opposite of narrowing (q.v.@:). @xref{Narrowing}. + +@item Window +Emacs divides a frame (q.v.@:) into one or more windows, each of which +can display the contents of one buffer (q.v.@:) at any time. +@xref{Screen}, for basic information on how Emacs uses the screen. +@xref{Windows}, for commands to control the use of windows. + +@item Word Abbrev +Synonymous with `abbrev'. + +@item Word Search +Word search is searching for a sequence of words, considering the +punctuation between them as insignificant. @xref{Word Search}. + +@item WYSIWYG +WYSIWYG stands for `What you see is what you get.' Emacs generally +provides WYSIWYG editing for files of characters; in Enriched mode +(@pxref{Formatted Text}), it provides WYSIWYG editing for files that +include text formatting information. + +@item Yanking +Yanking means reinserting text previously killed. It can be used to +undo a mistaken kill, or for copying or moving text. Some other +systems call this ``pasting.'' @xref{Yanking}. +@end table + diff --git a/man/gnu.texi b/man/gnu.texi new file mode 100644 index 00000000000..c4633a000f6 --- /dev/null +++ b/man/gnu.texi @@ -0,0 +1,535 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1995 Free Software Foundation, Inc. +@ifclear justgnu +@node Manifesto,, MS-DOS, Top +@unnumbered The GNU Manifesto +@end ifclear +@ifset justgnu +Copyright (C) 1985, 1993 Free Software Foundation, Inc. + +Permission is granted to anyone to make or distribute verbatim copies +of this document, in any medium, provided that the +copyright notice and permission notice are preserved, +and that the distributor grants the recipient permission +for further redistribution as permitted by this notice. + +Modified versions may not be made. + +@node Top +@top The GNU Manifesto +@end ifset + +@quotation +The GNU Manifesto which appears below was written by Richard Stallman at +the beginning of the GNU project, to ask for participation and support. +For the first few years, it was updated in minor ways to account for +developments, but now it seems best to leave it unchanged as most people +have seen it. + +Since that time, we have learned about certain common misunderstandings +that different wording could help avoid. Footnotes added in 1993 help +clarify these points. + +For up-to-date information about the available GNU software, please see +the latest issue of the GNU's Bulletin. The list is much too long to +include here. +@end quotation + +@unnumberedsec What's GNU? Gnu's Not Unix! + +GNU, which stands for Gnu's Not Unix, is the name for the complete +Unix-compatible software system which I am writing so that I can give it +away free to everyone who can use it.@footnote{The wording here was +careless. The intention was that nobody would have to pay for +@emph{permission} to use the GNU system. But the words don't make this +clear, and people often interpret them as saying that copies of GNU +should always be distributed at little or no charge. That was never the +intent; later on, the manifesto mentions the possibility of companies +providing the service of distribution for a profit. Subsequently I have +learned to distinguish carefully between ``free'' in the sense of +freedom and ``free'' in the sense of price. Free software is software +that users have the freedom to distribute and change. Some users may +obtain copies at no charge, while others pay to obtain copies---and if +the funds help support improving the software, so much the better. The +important thing is that everyone who has a copy has the freedom to +cooperate with others in using it.} Several other volunteers are helping +me. Contributions of time, money, programs and equipment are greatly +needed. + +So far we have an Emacs text editor with Lisp for writing editor commands, +a source level debugger, a yacc-compatible parser generator, a linker, and +around 35 utilities. A shell (command interpreter) is nearly completed. A +new portable optimizing C compiler has compiled itself and may be released +this year. An initial kernel exists but many more features are needed to +emulate Unix. When the kernel and compiler are finished, it will be +possible to distribute a GNU system suitable for program development. We +will use @TeX{} as our text formatter, but an nroff is being worked on. We +will use the free, portable X window system as well. After this we will +add a portable Common Lisp, an Empire game, a spreadsheet, and hundreds of +other things, plus on-line documentation. We hope to supply, eventually, +everything useful that normally comes with a Unix system, and more. + +GNU will be able to run Unix programs, but will not be identical to Unix. +We will make all improvements that are convenient, based on our experience +with other operating systems. In particular, we plan to have longer +file names, file version numbers, a crashproof file system, file name +completion perhaps, terminal-independent display support, and perhaps +eventually a Lisp-based window system through which several Lisp programs +and ordinary Unix programs can share a screen. Both C and Lisp will be +available as system programming languages. We will try to support UUCP, +MIT Chaosnet, and Internet protocols for communication. + +GNU is aimed initially at machines in the 68000/16000 class with virtual +memory, because they are the easiest machines to make it run on. The extra +effort to make it run on smaller machines will be left to someone who wants +to use it on them. + +To avoid horrible confusion, please pronounce the `G' in the word `GNU' +when it is the name of this project. + +@unnumberedsec Why I Must Write GNU + +I consider that the golden rule requires that if I like a program I must +share it with other people who like it. Software sellers want to divide +the users and conquer them, making each user agree not to share with +others. I refuse to break solidarity with other users in this way. I +cannot in good conscience sign a nondisclosure agreement or a software +license agreement. For years I worked within the Artificial Intelligence +Lab to resist such tendencies and other inhospitalities, but eventually +they had gone too far: I could not remain in an institution where such +things are done for me against my will. + +So that I can continue to use computers without dishonor, I have decided to +put together a sufficient body of free software so that I will be able to +get along without any software that is not free. I have resigned from the +AI lab to deny MIT any legal excuse to prevent me from giving GNU away. + +@unnumberedsec Why GNU Will Be Compatible with Unix + +Unix is not my ideal system, but it is not too bad. The essential features +of Unix seem to be good ones, and I think I can fill in what Unix lacks +without spoiling them. And a system compatible with Unix would be +convenient for many other people to adopt. + +@unnumberedsec How GNU Will Be Available + +GNU is not in the public domain. Everyone will be permitted to modify and +redistribute GNU, but no distributor will be allowed to restrict its +further redistribution. That is to say, proprietary modifications will not +be allowed. I want to make sure that all versions of GNU remain free. + +@unnumberedsec Why Many Other Programmers Want to Help + +I have found many other programmers who are excited about GNU and want to +help. + +Many programmers are unhappy about the commercialization of system +software. It may enable them to make more money, but it requires them to +feel in conflict with other programmers in general rather than feel as +comrades. The fundamental act of friendship among programmers is the +sharing of programs; marketing arrangements now typically used essentially +forbid programmers to treat others as friends. The purchaser of software +must choose between friendship and obeying the law. Naturally, many decide +that friendship is more important. But those who believe in law often do +not feel at ease with either choice. They become cynical and think that +programming is just a way of making money. + +By working on and using GNU rather than proprietary programs, we can be +hospitable to everyone and obey the law. In addition, GNU serves as an +example to inspire and a banner to rally others to join us in sharing. +This can give us a feeling of harmony which is impossible if we use +software that is not free. For about half the programmers I talk to, this +is an important happiness that money cannot replace. + +@unnumberedsec How You Can Contribute + +I am asking computer manufacturers for donations of machines and money. +I'm asking individuals for donations of programs and work. + +One consequence you can expect if you donate machines is that GNU will run +on them at an early date. The machines should be complete, ready to use +systems, approved for use in a residential area, and not in need of +sophisticated cooling or power. + +I have found very many programmers eager to contribute part-time work for +GNU. For most projects, such part-time distributed work would be very hard +to coordinate; the independently-written parts would not work together. +But for the particular task of replacing Unix, this problem is absent. A +complete Unix system contains hundreds of utility programs, each of which +is documented separately. Most interface specifications are fixed by Unix +compatibility. If each contributor can write a compatible replacement for +a single Unix utility, and make it work properly in place of the original +on a Unix system, then these utilities will work right when put together. +Even allowing for Murphy to create a few unexpected problems, assembling +these components will be a feasible task. (The kernel will require closer +communication and will be worked on by a small, tight group.) + +If I get donations of money, I may be able to hire a few people full or +part time. The salary won't be high by programmers' standards, but I'm +looking for people for whom building community spirit is as important as +making money. I view this as a way of enabling dedicated people to devote +their full energies to working on GNU by sparing them the need to make a +living in another way. + +@unnumberedsec Why All Computer Users Will Benefit + +Once GNU is written, everyone will be able to obtain good system +software free, just like air.@footnote{This is another place I failed to +distinguish carefully between the two different meanings of ``free''. +The statement as it stands is not false---you can get copies of GNU +software at no charge, from your friends or over the net. But it does +suggest the wrong idea.} + +This means much more than just saving everyone the price of a Unix license. +It means that much wasteful duplication of system programming effort will +be avoided. This effort can go instead into advancing the state of the +art. + +Complete system sources will be available to everyone. As a result, a user +who needs changes in the system will always be free to make them himself, +or hire any available programmer or company to make them for him. Users +will no longer be at the mercy of one programmer or company which owns the +sources and is in sole position to make changes. + +Schools will be able to provide a much more educational environment by +encouraging all students to study and improve the system code. Harvard's +computer lab used to have the policy that no program could be installed on +the system if its sources were not on public display, and upheld it by +actually refusing to install certain programs. I was very much inspired by +this. + +Finally, the overhead of considering who owns the system software and what +one is or is not entitled to do with it will be lifted. + +Arrangements to make people pay for using a program, including licensing of +copies, always incur a tremendous cost to society through the cumbersome +mechanisms necessary to figure out how much (that is, which programs) a +person must pay for. And only a police state can force everyone to obey +them. Consider a space station where air must be manufactured at great +cost: charging each breather per liter of air may be fair, but wearing the +metered gas mask all day and all night is intolerable even if everyone can +afford to pay the air bill. And the TV cameras everywhere to see if you +ever take the mask off are outrageous. It's better to support the air +plant with a head tax and chuck the masks. + +Copying all or parts of a program is as natural to a programmer as +breathing, and as productive. It ought to be as free. + +@unnumberedsec Some Easily Rebutted Objections to GNU's Goals + +@quotation +``Nobody will use it if it is free, because that means they can't rely +on any support.'' + +``You have to charge for the program to pay for providing the +support.'' +@end quotation + +If people would rather pay for GNU plus service than get GNU free without +service, a company to provide just service to people who have obtained GNU +free ought to be profitable.@footnote{Several such companies now exist.} + +We must distinguish between support in the form of real programming work +and mere handholding. The former is something one cannot rely on from a +software vendor. If your problem is not shared by enough people, the +vendor will tell you to get lost. + +If your business needs to be able to rely on support, the only way is to +have all the necessary sources and tools. Then you can hire any available +person to fix your problem; you are not at the mercy of any individual. +With Unix, the price of sources puts this out of consideration for most +businesses. With GNU this will be easy. It is still possible for there to +be no available competent person, but this problem cannot be blamed on +distribution arrangements. GNU does not eliminate all the world's problems, +only some of them. + +Meanwhile, the users who know nothing about computers need handholding: +doing things for them which they could easily do themselves but don't know +how. + +Such services could be provided by companies that sell just hand-holding +and repair service. If it is true that users would rather spend money and +get a product with service, they will also be willing to buy the service +having got the product free. The service companies will compete in quality +and price; users will not be tied to any particular one. Meanwhile, those +of us who don't need the service should be able to use the program without +paying for the service. + +@quotation +``You cannot reach many people without advertising, +and you must charge for the program to support that.'' + +``It's no use advertising a program people can get free.'' +@end quotation + +There are various forms of free or very cheap publicity that can be used to +inform numbers of computer users about something like GNU. But it may be +true that one can reach more microcomputer users with advertising. If this +is really so, a business which advertises the service of copying and +mailing GNU for a fee ought to be successful enough to pay for its +advertising and more. This way, only the users who benefit from the +advertising pay for it. + +On the other hand, if many people get GNU from their friends, and such +companies don't succeed, this will show that advertising was not really +necessary to spread GNU. Why is it that free market advocates don't +want to let the free market decide this?@footnote{The Free Software +Foundation raises most of its funds from a distribution service, +although it is a charity rather than a company. If @emph{no one} +chooses to obtain copies by ordering from the FSF, it will be unable +to do its work. But this does not mean that proprietary restrictions +are justified to force every user to pay. If a small fraction of all +the users order copies from the FSF, that is sufficient to keep the FSF +afloat. So we ask users to choose to support us in this way. Have you +done your part?} + +@quotation +``My company needs a proprietary operating system +to get a competitive edge.'' +@end quotation + +GNU will remove operating system software from the realm of competition. +You will not be able to get an edge in this area, but neither will your +competitors be able to get an edge over you. You and they will compete in +other areas, while benefiting mutually in this one. If your business is +selling an operating system, you will not like GNU, but that's tough on +you. If your business is something else, GNU can save you from being +pushed into the expensive business of selling operating systems. + +I would like to see GNU development supported by gifts from many +manufacturers and users, reducing the cost to each.@footnote{A group of +computer companies recently pooled funds to support maintenance of the +GNU C Compiler.} + +@quotation +``Don't programmers deserve a reward for their creativity?'' +@end quotation + +If anything deserves a reward, it is social contribution. Creativity can +be a social contribution, but only in so far as society is free to use the +results. If programmers deserve to be rewarded for creating innovative +programs, by the same token they deserve to be punished if they restrict +the use of these programs. + +@quotation +``Shouldn't a programmer be able to ask for a reward for his creativity?'' +@end quotation + +There is nothing wrong with wanting pay for work, or seeking to maximize +one's income, as long as one does not use means that are destructive. But +the means customary in the field of software today are based on +destruction. + +Extracting money from users of a program by restricting their use of it is +destructive because the restrictions reduce the amount and the ways that +the program can be used. This reduces the amount of wealth that humanity +derives from the program. When there is a deliberate choice to restrict, +the harmful consequences are deliberate destruction. + +The reason a good citizen does not use such destructive means to become +wealthier is that, if everyone did so, we would all become poorer from the +mutual destructiveness. This is Kantian ethics; or, the Golden Rule. +Since I do not like the consequences that result if everyone hoards +information, I am required to consider it wrong for one to do so. +Specifically, the desire to be rewarded for one's creativity does not +justify depriving the world in general of all or part of that creativity. + +@quotation +``Won't programmers starve?'' +@end quotation + +I could answer that nobody is forced to be a programmer. Most of us cannot +manage to get any money for standing on the street and making faces. But +we are not, as a result, condemned to spend our lives standing on the +street making faces, and starving. We do something else. + +But that is the wrong answer because it accepts the questioner's implicit +assumption: that without ownership of software, programmers cannot possibly +be paid a cent. Supposedly it is all or nothing. + +The real reason programmers will not starve is that it will still be +possible for them to get paid for programming; just not paid as much as +now. + +Restricting copying is not the only basis for business in software. It is +the most common basis because it brings in the most money. If it were +prohibited, or rejected by the customer, software business would move to +other bases of organization which are now used less often. There are +always numerous ways to organize any kind of business. + +Probably programming will not be as lucrative on the new basis as it is +now. But that is not an argument against the change. It is not considered +an injustice that sales clerks make the salaries that they now do. If +programmers made the same, that would not be an injustice either. (In +practice they would still make considerably more than that.) + +@quotation +``Don't people have a right to control how their creativity is used?'' +@end quotation + +``Control over the use of one's ideas'' really constitutes control over +other people's lives; and it is usually used to make their lives more +difficult. + +People who have studied the issue of intellectual property rights carefully +(such as lawyers) say that there is no intrinsic right to intellectual +property. The kinds of supposed intellectual property rights that the +government recognizes were created by specific acts of legislation for +specific purposes. + +For example, the patent system was established to encourage inventors to +disclose the details of their inventions. Its purpose was to help society +rather than to help inventors. At the time, the life span of 17 years for +a patent was short compared with the rate of advance of the state of the +art. Since patents are an issue only among manufacturers, for whom the +cost and effort of a license agreement are small compared with setting up +production, the patents often do not do much harm. They do not obstruct +most individuals who use patented products. + +The idea of copyright did not exist in ancient times, when authors +frequently copied other authors at length in works of non-fiction. This +practice was useful, and is the only way many authors' works have survived +even in part. The copyright system was created expressly for the purpose +of encouraging authorship. In the domain for which it was +invented---books, which could be copied economically only on a printing +press---it did little harm, and did not obstruct most of the individuals +who read the books. + +All intellectual property rights are just licenses granted by society +because it was thought, rightly or wrongly, that society as a whole would +benefit by granting them. But in any particular situation, we have to ask: +are we really better off granting such license? What kind of act are we +licensing a person to do? + +The case of programs today is very different from that of books a hundred +years ago. The fact that the easiest way to copy a program is from one +neighbor to another, the fact that a program has both source code and +object code which are distinct, and the fact that a program is used rather +than read and enjoyed, combine to create a situation in which a person who +enforces a copyright is harming society as a whole both materially and +spiritually; in which a person should not do so regardless of whether the +law enables him to. + +@quotation +``Competition makes things get done better.'' +@end quotation + +The paradigm of competition is a race: by rewarding the winner, we +encourage everyone to run faster. When capitalism really works this way, +it does a good job; but its defenders are wrong in assuming it always works +this way. If the runners forget why the reward is offered and become +intent on winning, no matter how, they may find other strategies---such as, +attacking other runners. If the runners get into a fist fight, they will +all finish late. + +Proprietary and secret software is the moral equivalent of runners in a +fist fight. Sad to say, the only referee we've got does not seem to +object to fights; he just regulates them (``For every ten yards you run, +you can fire one shot''). He really ought to break them up, and penalize +runners for even trying to fight. + +@quotation +``Won't everyone stop programming without a monetary incentive?'' +@end quotation + +Actually, many people will program with absolutely no monetary incentive. +Programming has an irresistible fascination for some people, usually the +people who are best at it. There is no shortage of professional musicians +who keep at it even though they have no hope of making a living that way. + +But really this question, though commonly asked, is not appropriate to the +situation. Pay for programmers will not disappear, only become less. So +the right question is, will anyone program with a reduced monetary +incentive? My experience shows that they will. + +For more than ten years, many of the world's best programmers worked at the +Artificial Intelligence Lab for far less money than they could have had +anywhere else. They got many kinds of non-monetary rewards: fame and +appreciation, for example. And creativity is also fun, a reward in itself. + +Then most of them left when offered a chance to do the same interesting +work for a lot of money. + +What the facts show is that people will program for reasons other than +riches; but if given a chance to make a lot of money as well, they will +come to expect and demand it. Low-paying organizations do poorly in +competition with high-paying ones, but they do not have to do badly if the +high-paying ones are banned. + +@quotation +``We need the programmers desperately. If they demand that we +stop helping our neighbors, we have to obey.'' +@end quotation + +You're never so desperate that you have to obey this sort of demand. +Remember: millions for defense, but not a cent for tribute! + +@quotation +``Programmers need to make a living somehow.'' +@end quotation + +In the short run, this is true. However, there are plenty of ways that +programmers could make a living without selling the right to use a program. +This way is customary now because it brings programmers and businessmen the +most money, not because it is the only way to make a living. It is easy to +find other ways if you want to find them. Here are a number of examples. + +A manufacturer introducing a new computer will pay for the porting of +operating systems onto the new hardware. + +The sale of teaching, hand-holding and maintenance services could also +employ programmers. + +People with new ideas could distribute programs as freeware, asking for +donations from satisfied users, or selling hand-holding services. I have +met people who are already working this way successfully. + +Users with related needs can form users' groups, and pay dues. A group +would contract with programming companies to write programs that the +group's members would like to use. + +All sorts of development can be funded with a Software Tax: + +@quotation +Suppose everyone who buys a computer has to pay x percent of +the price as a software tax. The government gives this to +an agency like the NSF to spend on software development. + +But if the computer buyer makes a donation to software development +himself, he can take a credit against the tax. He can donate to +the project of his own choosing---often, chosen because he hopes to +use the results when it is done. He can take a credit for any amount +of donation up to the total tax he had to pay. + +The total tax rate could be decided by a vote of the payers of +the tax, weighted according to the amount they will be taxed on. + +The consequences: + +@itemize @bullet +@item +The computer-using community supports software development. +@item +This community decides what level of support is needed. +@item +Users who care which projects their share is spent on +can choose this for themselves. +@end itemize +@end quotation + +In the long run, making programs free is a step toward the post-scarcity +world, where nobody will have to work very hard just to make a living. +People will be free to devote themselves to activities that are fun, such +as programming, after spending the necessary ten hours a week on required +tasks such as legislation, family counseling, robot repair and asteroid +prospecting. There will be no need to be able to make a living from +programming. + +We have already greatly reduced the amount of work that the whole society +must do for its actual productivity, but only a little of this has +translated itself into leisure for workers because much nonproductive +activity is required to accompany productive activity. The main causes of +this are bureaucracy and isometric struggles against competition. Free +software will greatly reduce these drains in the area of software +production. We must do this, in order for technical gains in productivity +to translate into less work for us. diff --git a/man/gnus-faq.texi b/man/gnus-faq.texi new file mode 100644 index 00000000000..a899e7def45 --- /dev/null +++ b/man/gnus-faq.texi @@ -0,0 +1,659 @@ +\input texinfo +@c -*-texinfo-*- +@c Copyright (C) 1995 Free Software Foundation, Inc. +@setfilename gnus-faq.info + +@node Frequently Asked Questions +@section Frequently Asked Questions + +This is the Gnus Frequently Asked Questions list. +If you have a Web browser, the official hypertext version is at +@file{http://www.miranova.com/~steve/gnus-faq.html>}, and has +probably been updated since you got this manual. + +@menu +* Installation FAQ:: Installation of Gnus. +* Customization FAQ:: Customizing Gnus. +* Reading News FAQ:: News Reading Questions. +* Reading Mail FAQ:: Mail Reading Questions. +@end menu + + +@node Installation FAQ +@subsection Installation + +@itemize @bullet +@item +Q1.1 What is the latest version of Gnus? + +The latest (and greatest) version is 5.0.10. You might also run +across something called @emph{September Gnus}. September Gnus +is the alpha version of the next major release of Gnus. It is currently +not stable enough to run unless you are prepared to debug lisp. + +@item +Q1.2 Where do I get Gnus? + +Any of the following locations: + +@itemize @minus +@item +@file{ftp://ftp.ifi.uio.no/pub/emacs/gnus/gnus.tar.gz} + +@item +@file{ftp://ftp.pilgrim.umass.edu/pub/misc/ding/} + +@item +@file{gopher://gopher.pilgrim.umass.edu/11/pub/misc/ding/} + +@item +@file{ftp://aphrodite.nectar.cs.cmu.edu/pub/ding-gnus/} + +@item +@file{ftp://ftp.solace.mh.se:/pub/gnu/elisp/} + +@end itemize + +@item +Q1.3 Which version of Emacs do I need? + +At least GNU Emacs 19.28, or XEmacs 19.12 is recommended. GNU Emacs +19.25 has been reported to work under certain circumstances, but it +doesn't @emph{officially} work on it. 19.27 has also been reported to +work. Gnus has been reported to work under OS/2 as well as Unix. + + +@item +Q1.4 Where is timezone.el? + +Upgrade to XEmacs 19.13. In earlier versions of XEmacs this file was +placed with Gnus 4.1.3, but that has been corrected. + + +@item +Q1.5 When I run Gnus on XEmacs 19.13 I get weird error messages. + +You're running an old version of Gnus. Upgrade to at least version +5.0.4. + + +@item +Q1.6 How do I unsubscribe from the Mailing List? + +Send an e-mail message to @file{ding-request@@ifi.uio.no} with the magic word +@emph{unsubscribe} somewhere in it, and you will be removed. + +If you are reading the digest version of the list, send an e-mail message +to @* +@file{ding-rn-digests-d-request@@moe.shore.net} +with @emph{unsubscribe} as the subject and you will be removed. + + +@item +Q1.7 How do I run Gnus on both Emacs and XEmacs? + +The basic answer is to byte-compile under XEmacs, and then you can +run under either Emacsen. There is, however, a potential version +problem with easymenu.el with Gnu Emacs prior to 19.29. + +Per Abrahamsen <abraham@@dina.kvl.dk> writes :@* +The internal easymenu.el interface changed between 19.28 and 19.29 in +order to make it possible to create byte compiled files that can be +shared between Gnu Emacs and XEmacs. The change is upward +compatible, but not downward compatible. +This gives the following compatibility table: + +@example +Compiled with: | Can be used with: +----------------+-------------------------------------- +19.28 | 19.28 19.29 +19.29 | 19.29 XEmacs +XEmacs | 19.29 XEmacs +@end example + +If you have Gnu Emacs 19.28 or earlier, or XEmacs 19.12 or earlier, get +a recent version of auc-menu.el from +@file{ftp://ftp.iesd.auc.dk/pub/emacs-lisp/auc-menu.el}, and install it +under the name easymenu.el somewhere early in your load path. + + +@item +Q1.8 What resources are available? + +There is the newsgroup Gnu.emacs.gnus. Discussion of Gnus 5.x is now +taking place there. There is also a mailing list, send mail to +@file{ding-request@@ifi.uio.no} with the magic word @emph{subscribe} +somewhere in it. + +@emph{NOTE:} the traffic on this list is heavy so you may not want to be +on it (unless you use Gnus as your mailer reader, that is). The mailing +list is mainly for developers and testers. + +Gnus has a home World Wide Web page at@* +@file{http://www.ifi.uio.no/~larsi/ding.html}. + +Gnus has a write up in the X Windows Applications FAQ at@* +@file{http://www.ee.ryerson.ca:8080/~elf/xapps/Q-III.html}. + +The Gnus manual is also available on the World Wide Web. The canonical +source is in Norway at@* +@file{http://www.ifi.uio.no/~larsi/ding-manual/gnus_toc.html}. + +There are three mirrors in the United States: +@enumerate +@item +@file{http://www.miranova.com/gnus-man/} + +@item +@file{http://www.pilgrim.umass.edu/pub/misc/ding/manual/gnus_toc.html} + +@item +@file{http://www.rtd.com/~woo/gnus/} + +@end enumerate + +PostScript copies of the Gnus Reference card are available from@* +@file{ftp://ftp.cs.ualberta.ca/pub/oolog/gnus/}. They are mirrored at@* +@file{ftp://ftp.pilgrim.umass.edu/pub/misc/ding/refcard/} in the +United States. And@* +@file{ftp://marvin.fkphy.uni-duesseldorf.de/pub/gnus/} +in Germany. + +An online version of the Gnus FAQ is available at@* +@file{http://www.miranova.com/~steve/gnus-faq.html}. Off-line formats +are also available:@* +ASCII: @file{ftp://ftp.miranova.com/pub/gnus/gnus-faq}@* +PostScript: @file{ftp://ftp.miranova.com/pub/gnus/gnus-faq.ps}. + + +@item +Q1.9 Gnus hangs on connecting to NNTP server + +I am running XEmacs on SunOS and Gnus prints a message about Connecting +to NNTP server and then just hangs. + +Ben Wing <wing@@netcom.com> writes :@* +I wonder if you're hitting the infamous @emph{libresolv} problem. +The basic problem is that under SunOS you can compile either +with DNS or NIS name lookup libraries but not both. Try +substituting the IP address and see if that works; if so, you +need to download the sources and recompile. + + +@item +Q1.10 Mailcrypt 3.4 doesn't work + +This problem is verified to still exist in Gnus 5.0.9 and MailCrypt 3.4. +The answer comes from Peter Arius +<arius@@immd2.informatik.uni-erlangen.de>. + +I found out that mailcrypt uses +@code{gnus-eval-in-buffer-window}, which is a macro. +It seems as if you have +compiled mailcrypt with plain old GNUS in load path, and the XEmacs byte +compiler has inserted that macro definition into +@file{mc-toplev.elc}. +The solution is to recompile @file{mc-toplev.el} with Gnus 5 in +load-path, and it works fine. + +Steve Baur <steve@@miranova.com> adds :@* +The problem also manifests itself if neither GNUS 4 nor Gnus 5 is in the +load-path. + + +@item +Q1.11 What other packages work with Gnus? + +@itemize @minus +@item +Mailcrypt. + +Mailcrypt is an Emacs interface to PGP. It works, it installs +without hassle, and integrates very easily. Mailcrypt can be +obtained from@* +@file{ftp://cag.lcs.mit.edu/pub/patl/mailcrypt-3.4.tar.gz}. + +@item +Tiny Mime. + +Tiny Mime is an Emacs MUA interface to MIME. Installation is +a two-step process unlike most other packages, so you should +be prepared to move the byte-compiled code somewhere. There +are currently two versions of this package available. It can +be obtained from@* +@file{ftp://ftp.jaist.ac.jp/pub/GNU/elisp/}. +Be sure to apply the supplied patch. It works with Gnus through +version 5.0.9. In order for all dependencies to work correctly +the load sequence is as follows: +@lisp + (load "tm-setup") + (load "gnus") + (load "mime-compose") +@end lisp + +@emph{NOTE:} Loading the package disables citation highlighting by +default. To get the old behavior back, use the @kbd{M-t} command. + +@end itemize + +@end itemize + + +@node Customization FAQ +@subsection Customization + +@itemize @bullet +@item +Q2.1 Custom Edit does not work under XEmacs + +The custom package has not been ported to XEmacs. + + +@item +Q2.2 How do I quote messages? + +I see lots of messages with quoted material in them. I am wondering +how to have Gnus do it for me. + +This is Gnus, so there are a number of ways of doing this. You can use +the built-in commands to do this. There are the @kbd{F} and @kbd{R} +keys from the summary buffer which automatically include the article +being responded to. These commands are also selectable as @i{Followup +and Yank} and @i{Reply and Yank} in the Post menu. + +@kbd{C-c C-y} grabs the previous message and prefixes each line with +@code{ail-indentation-spaces} spaces or @code{mail-yank-prefix} if that is +non-nil, unless you have set your own @code{mail-citation-hook}, which will +be called to to do the job. + +You might also consider the Supercite package, which allows for pretty +arbitrarily complex quoting styles. Some people love it, some people +hate it. + + +@item +Q2.3 How can I keep my nnvirtual:* groups sorted? + +How can I most efficiently arrange matters so as to keep my nnvirtual:* +(etc) groups at the top of my group selection buffer, whilst keeping +everything sorted in alphabetical order. + +If you don't subscribe often to new groups then the easiest way is to +first sort the groups and then manually kill and yank the virtuals +wherever you want them. + + +@item +Q2.4 Any good suggestions on stuff for an all.SCORE file? + +Here is a collection of suggestions from the Gnus mailing list. + +@enumerate +@item +From ``Dave Disser'' <disser@@sdd.hp.com>@* +I like blasting anything without lowercase letters. Weeds out most of +the make $$ fast, as well as the lame titles like ``IBM'' and ``HP-UX'' +with no further description. +@lisp + (("Subject" + ("^\\(Re: \\)?[^a-z]*$" -200 nil R))) +@end lisp + +@item +From ``Peter Arius'' <arius@@immd2.informatik.uni-erlangen.de>@* +The most vital entries in my (still young) all.SCORE: +@lisp +(("xref" + ("alt.fan.oj-simpson" -1000 nil s)) + ("subject" + ("\\<\\(make\\|fast\\|big\\)\\s-*\\(money\\|cash\\|bucks?\\)\\>" -1000 nil r) + ("$$$$" -1000 nil s))) +@end lisp + +@item +From ``Per Abrahamsen'' <abraham@@dina.kvl.dk>@* +@lisp +(("subject" + ;; CAPS OF THE WORLD, UNITE + ("^..[^a-z]+$" -1 nil R) + ;; $$$ Make Money $$$ (Try work) + ("$" -1 nil s) + ;; I'm important! And I have exclamation marks to prove it! + ("!" -1 nil s))) +@end lisp + +@item +From ``heddy boubaker'' <boubaker@@cenatls.cena.dgac.fr>@* +I would like to contribute with mine. +@lisp +( + (read-only t) + ("subject" + ;; ALL CAPS SUBJECTS + ("^\\([Rr][Ee]: +\\)?[^a-z]+$" -1 nil R) + ;; $$$ Make Money $$$ + ("$$" -10 nil s) + ;; Empty subjects are worthless! + ("^ *\\([(<]none[>)]\\|(no subject\\( given\\)?)\\)? *$" -10 nil r) + ;; Sometimes interesting announces occur! + ("ANN?OU?NC\\(E\\|ING\\)" +10 nil r) + ;; Some people think they're on mailing lists + ("\\(un\\)?sub?scribe" -100 nil r) + ;; Stop Micro$oft NOW!! + ("\\(m\\(icro\\)?[s$]\\(oft\\|lot\\)?-?\\)?wind?\\(ows\\|aube\\|oze\\)?[- ]*\\('?95\\|NT\\|3[.]1\\|32\\)" -1001 nil r) + ;; I've nothing to buy + ("\\(for\\|4\\)[- ]*sale" -100 nil r) + ;; SELF-DISCIPLINED people + ("\\[[^a-z0-9 \t\n][^a-z0-9 \t\n]\\]" +100 nil r) + ) + ("from" + ;; To keep track of posters from my site + (".dgac.fr" +1000 nil s)) + ("followup" + ;; Keep track of answers to my posts + ("boubaker" +1000 nil s)) + ("lines" + ;; Some people have really nothing to say!! + (1 -10 nil <=)) + (mark -100) + (expunge -1000) + ) +@end lisp + +@item +From ``Christopher Jones'' <cjones@@au.oracle.com>@* +The sample @file{all.SCORE} files from Per and boubaker could be +augmented with: +@lisp + (("subject" + ;; No junk mail please! + ("please ignore" -500 nil s) + ("test" -500 nil e)) + ) +@end lisp + +@item +From ``Brian Edmonds'' <edmonds@@cs.ubc.ca>@* +Augment any of the above with a fast method of scoring down +excessively cross posted articles. +@lisp + ("xref" + ;; the more cross posting, the exponentially worse the article + ("^xref: \\S-+ \\S-+ \\S-+ \\S-+" -1 nil r) + ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -2 nil r) + ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -4 nil r) + ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -8 nil r) + ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -16 nil r) + ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -32 nil r) + ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -64 nil r) + ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -128 nil r) + ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -256 nil r) + ("^xref: \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+ \\S-+" -512 nil r)) +@end lisp + +@end enumerate + + +@item +Q2.5 What do I use to yank-through when replying? + +You should probably reply and followup with @kbd{R} and @kbd{F}, instead +of @kbd{r} and @kbd{f}, which solves your problem. But you could try +something like: + +@example +(defconst mail-yank-ignored-headers + "^.*:" + "Delete these headers from old message when it's inserted in a reply.") +@end example + + +@item +Q2.6 I don't like the default WWW browser + +Now when choosing an URL Gnus starts up a W3 buffer, I would like it +to always use Netscape (I don't browse in text-mode ;-). + +@enumerate +@item +Activate `Customize...' from the `Help' menu. + +@item +Scroll down to the `WWW Browser' field. + +@item +Click `mouse-2' on `WWW Browser'. + +@item +Select `Netscape' from the pop up menu. + +@item +Press `C-c C-c' + +@end enumerate + +If you are using XEmacs then to specify Netscape do +@lisp + (setq gnus-button-url 'gnus-netscape-open-url) +@end lisp + + +@item +Q2.7 What, if any, relation is between ``ask-server'' and ``(setq +gnus-read-active-file 'some)''? + +In order for Gnus to show you the complete list of newsgroups, it will +either have to either store the list locally, or ask the server to +transmit the list. You enable the first with + +@lisp + (setq gnus-save-killed-list t) +@end lisp + +and the second with + +@lisp + (setq gnus-read-active-file t) +@end lisp + +If both are disabled, Gnus will not know what newsgroups exists. There +is no option to get the list by casting a spell. + + +@item +Q2.8 Moving between groups is slow. + +Per Abrahamsen <abraham@@dina.kvl.dk> writes:@* + +Do you call @code{define-key} or something like that in one of the +summary mode hooks? This would force Emacs to recalculate the keyboard +shortcuts. Removing the call should speed up @kbd{M-x gnus-summary-mode +RET} by a couple of orders of magnitude. You can use + +@lisp +(define-key gnus-summary-mode-map KEY COMMAND) +@end lisp + +in your @file{.gnus} instead. + +@end itemize + + +@node Reading News FAQ +@subsection Reading News + +@itemize @bullet +@item +Q3.1 How do I convert my kill files to score files? + +A kill-to-score translator was written by Ethan Bradford +<ethanb@@ptolemy.astro.washington.edu>. It is available from@* +@file{http://baugi.ifi.uio.no/~larsi/ding-various/gnus-kill-to-score.el}. + + +@item +Q3.2 My news server has a lot of groups, and killing groups is painfully +slow. + +Don't do that then. The best way to get rid of groups that should be +dead is to edit your newsrc directly. This problem will be addressed +in the near future. + + +@item +Q3.3 How do I use an NNTP server with authentication? + +Put the following into your .gnus: +@lisp + (add-hook 'nntp-server-opened-hook 'nntp-send-authinfo) +@end lisp + + +@item +Q3.4 Not reading the first article. + +How do I avoid reading the first article when a group is selected? + +@enumerate +@item +Use @kbd{RET} to select the group instead of @kbd{SPC}. + +@item +@code{(setq gnus-auto-select first nil)} + +@item +Luis Fernandes <elf@@mailhost.ee.ryerson.ca>writes:@* +This is what I use...customize as necessary... + +@lisp +;;; Don't auto-select first article if reading sources, or archives or +;;; jobs postings, etc. and just display the summary buffer +(add-hook 'gnus-select-group-hook + (function + (lambda () + (cond ((string-match "sources" gnus-newsgroup-name) + (setq gnus-auto-select-first nil)) + ((string-match "jobs" gnus-newsgroup-name) + (setq gnus-auto-select-first nil)) + ((string-match "comp\\.archives" gnus-newsgroup-name) + (setq gnus-auto-select-first nil)) + ((string-match "reviews" gnus-newsgroup-name) + (setq gnus-auto-select-first nil)) + ((string-match "announce" gnus-newsgroup-name) + (setq gnus-auto-select-first nil)) + ((string-match "binaries" gnus-newsgroup-name) + (setq gnus-auto-select-first nil)) + (t + (setq gnus-auto-select-first t)))))) +@end lisp + +@item +Per Abrahamsen <abraham@@dina.kvl.dk> writes:@* +Another possibility is to create an @file{all.binaries.all.SCORE} file +like this: + +@lisp +((local + (gnus-auto-select-first nil))) +@end lisp + +and insert +@lisp + (setq gnus-auto-select-first t) +@end lisp + +in your @file{.gnus}. + +@end enumerate + +@item +Q3.5 Why aren't BBDB known posters marked in the summary buffer? + +Brian Edmonds <edmonds@@cs.ubc.ca> writes:@* +Due to changes in Gnus 5.0, @file{bbdb-gnus.el} no longer marks known +posters in the summary buffer. An updated version, @file{gnus-bbdb.el} +is available at the locations listed below. This package also supports +autofiling of incoming mail to folders specified in the BBDB. Extensive +instructions are included as comments in the file. + +Send mail to @file{majordomo@@edmonds.home.cs.ubc.ca} with the following +line in the body of the message: @emph{get misc gnus-bbdb.el}. + +Or get it from the World Wide Web:@* +@file{http://www.cs.ubc.ca/spider/edmonds/gnus-bbdb.el}. + +@end itemize + + +@node Reading Mail FAQ +@subsection Reading Mail + +@itemize @bullet +@item +Q4.1 What does the message ``Buffer has changed on disk'' mean in a mail +group? + +Your filter program should not deliver mail directly to your folders, +instead it should put the mail into spool files. Gnus will then move +the mail safely from the spool files into the folders. This will +eliminate the problem. Look it up in the manual, in the section +entitled ``Mail & Procmail''. + + +@item +Q4.2 How do you make articles un-expirable? + +I am using nnml to read news and have used +@code{gnus-auto-expirable-newsgroups} to automagically expire articles +in some groups (Gnus being one of them). Sometimes there are +interesting articles in these groups that I want to keep. Is there any +way of explicitly marking an article as un-expirable - that is mark it +as read but not expirable? + +Use @kbd{u}, @kbd{!}, @kbd{d} or @kbd{M-u} in the summary buffer. You +just remove the @kbd{E} mark by setting some other mark. It's not +necessary to tick the articles. + + +@item +Q4.3 How do I delete bogus nnml: groups? + +My problem is that I have various mail (nnml) groups generated while +experimenting with Gnus. How do I remove them now? Setting the level to +9 does not help. Also @code{gnus-group-check-bogus-groups} does not +recognize them. + +Removing mail groups is tricky at the moment. (It's on the to-do list, +though.) You basically have to kill the groups in Gnus, shut down Gnus, +edit the active file to exclude these groups, and probably remove the +nnml directories that contained these groups as well. Then start Gnus +back up again. + + +@item +Q4.4 What happened to my new mail groups? + +I got new mail, but I have +never seen the groups they should have been placed in. + +They are probably there, but as zombies. Press @kbd{A z} to list +zombie groups, and then subscribe to the groups you want with @kbd{u}. +This is all documented quite nicely in the user's manual. + + +@item +Q4.5 Not scoring mail groups + +How do you @emph{totally} turn off scoring in mail groups? + +Use an nnbabyl:all.SCORE (or nnmh, or nnml, or whatever) file containing: + +@example +((adapt ignore) + (local (gnus-use-scoring nil)) + (exclude-files "all.SCORE")) +@end example + +@end itemize + + diff --git a/man/gnus.texi b/man/gnus.texi new file mode 100644 index 00000000000..fa585a065e1 --- /dev/null +++ b/man/gnus.texi @@ -0,0 +1,19430 @@ +\input texinfo @c -*-texinfo-*- + +@setfilename ../info/gnus +@settitle Gnus Manual +@synindex fn cp +@synindex vr cp +@synindex pg cp +@direntry +* Gnus: (gnus). The newsreader Gnus. +@end direntry +@iftex +@finalout +@end iftex +@setchapternewpage odd + +@iftex +@end iftex + + +@ifinfo + +This file documents Gnus, the GNU Emacs newsreader. + +Copyright (C) 1995,96 Free Software Foundation, Inc. + +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 +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + +@tex + +@titlepage +@title Gnus 5.7 Manual + +@author by Lars Magne Ingebrigtsen +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1995,96,97 Free Software Foundation, Inc. + +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. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. + +@end titlepage +@page + +@end tex + + +@node Top +@top The Gnus Newsreader + +@ifinfo + +You can read news (and mail) from within Emacs by using Gnus. The news +can be gotten by any nefarious means you can think of---@sc{nntp}, local +spool or your mbox file. All at the same time, if you want to push your +luck. + +This manual corresponds to Gnus 5.7. + +@end ifinfo + +@iftex + +Gnus is the advanced, self-documenting, customizable, extensible +unreal-time newsreader for GNU Emacs. + +Oops. That sounds oddly familiar, so let's start over again to avoid +being accused of plagiarism: + +Gnus is a message-reading laboratory. It will let you look at just +about anything as if it were a newsgroup. You can read mail with it, +you can browse directories with it, you can @code{ftp} with it---you can +even read news with it! + +Gnus tries to empower people who read news the same way Emacs empowers +people who edit text. Gnus sets no limits to what the user should be +allowed to do. Users are encouraged to extend Gnus to make it behave +like they want it to behave. A program should not control people; +people should be empowered to do what they want by using (or abusing) +the program. + +@end iftex + + +@menu +* Starting Up:: Finding news can be a pain. +* The Group Buffer:: Selecting, subscribing and killing groups. +* The Summary Buffer:: Reading, saving and posting articles. +* The Article Buffer:: Displaying and handling articles. +* Composing Messages:: Information on sending mail and news. +* Select Methods:: Gnus reads all messages from various select methods. +* Scoring:: Assigning values to articles. +* Various:: General purpose settings. +* The End:: Farewell and goodbye. +* Appendices:: Terminology, Emacs intro, FAQ, History, Internals. +* Index:: Variable, function and concept index. +* Key Index:: Key Index. +@end menu + +@node Starting Up +@chapter Starting Gnus +@cindex starting up + +@kindex M-x gnus +@findex gnus +If your system administrator has set things up properly, starting Gnus +and reading news is extremely easy---you just type @kbd{M-x gnus} in +your Emacs. + +@findex gnus-other-frame +@kindex M-x gnus-other-frame +If you want to start Gnus in a different frame, you can use the command +@kbd{M-x gnus-other-frame} instead. + +If things do not go smoothly at startup, you have to twiddle some +variables in your @file{~/.gnus} file. This file is similar to +@file{~/.emacs}, but is read when gnus starts. + +If you puzzle at any terms used in this manual, please refer to the +terminology section (@pxref{Terminology}). + +@menu +* Finding the News:: Choosing a method for getting news. +* The First Time:: What does Gnus do the first time you start it? +* The Server is Down:: How can I read my mail then? +* Slave Gnusae:: You can have more than one Gnus active at a time. +* Fetching a Group:: Starting Gnus just to read a group. +* New Groups:: What is Gnus supposed to do with new groups? +* Startup Files:: Those pesky startup files---@file{.newsrc}. +* Auto Save:: Recovering from a crash. +* The Active File:: Reading the active file over a slow line Takes Time. +* Changing Servers:: You may want to move from one server to another. +* Startup Variables:: Other variables you might change. +@end menu + + +@node Finding the News +@section Finding the News +@cindex finding news + +@vindex gnus-select-method +@c @head +The @code{gnus-select-method} variable says where Gnus should look for +news. This variable should be a list where the first element says +@dfn{how} and the second element says @dfn{where}. This method is your +native method. All groups not fetched with this method are +foreign groups. + +For instance, if the @samp{news.somewhere.edu} @sc{nntp} server is where +you want to get your daily dosage of news from, you'd say: + +@lisp +(setq gnus-select-method '(nntp "news.somewhere.edu")) +@end lisp + +If you want to read directly from the local spool, say: + +@lisp +(setq gnus-select-method '(nnspool "")) +@end lisp + +If you can use a local spool, you probably should, as it will almost +certainly be much faster. + +@vindex gnus-nntpserver-file +@cindex NNTPSERVER +@cindex @sc{nntp} server +If this variable is not set, Gnus will take a look at the +@code{NNTPSERVER} environment variable. If that variable isn't set, +Gnus will see whether @code{gnus-nntpserver-file} +(@file{/etc/nntpserver} by default) has any opinions on the matter. If +that fails as well, Gnus will try to use the machine running Emacs as an @sc{nntp} server. That's a long shot, though. + +@vindex gnus-nntp-server +If @code{gnus-nntp-server} is set, this variable will override +@code{gnus-select-method}. You should therefore set +@code{gnus-nntp-server} to @code{nil}, which is what it is by default. + +@vindex gnus-secondary-servers +You can also make Gnus prompt you interactively for the name of an +@sc{nntp} server. If you give a non-numerical prefix to @code{gnus} +(i.e., @kbd{C-u M-x gnus}), Gnus will let you choose between the servers +in the @code{gnus-secondary-servers} list (if any). You can also just +type in the name of any server you feel like visiting. + +@findex gnus-group-browse-foreign-server +@kindex B (Group) +However, if you use one @sc{nntp} server regularly and are just +interested in a couple of groups from a different server, you would be +better served by using the @kbd{B} command in the group buffer. It will +let you have a look at what groups are available, and you can subscribe +to any of the groups you want to. This also makes @file{.newsrc} +maintenance much tidier. @xref{Foreign Groups}. + +@vindex gnus-secondary-select-methods +@c @head +A slightly different approach to foreign groups is to set the +@code{gnus-secondary-select-methods} variable. The select methods +listed in this variable are in many ways just as native as the +@code{gnus-select-method} server. They will also be queried for active +files during startup (if that's required), and new newsgroups that +appear on these servers will be subscribed (or not) just as native +groups are. + +For instance, if you use the @code{nnmbox} backend to read your mail, you +would typically set this variable to + +@lisp +(setq gnus-secondary-select-methods '((nnmbox ""))) +@end lisp + + +@node The First Time +@section The First Time +@cindex first time usage + +If no startup files exist, Gnus will try to determine what groups should +be subscribed by default. + +@vindex gnus-default-subscribed-newsgroups +If the variable @code{gnus-default-subscribed-newsgroups} is set, Gnus +will subscribe you to just those groups in that list, leaving the rest +killed. Your system administrator should have set this variable to +something useful. + +Since she hasn't, Gnus will just subscribe you to a few arbitrarily +picked groups (i.e., @samp{*.newusers}). (@dfn{Arbitrary} is defined +here as @dfn{whatever Lars thinks you should read}.) + +You'll also be subscribed to the Gnus documentation group, which should +help you with most common problems. + +If @code{gnus-default-subscribed-newsgroups} is @code{t}, Gnus will just +use the normal functions for handling new groups, and not do anything +special. + + +@node The Server is Down +@section The Server is Down +@cindex server errors + +If the default server is down, Gnus will understandably have some +problems starting. However, if you have some mail groups in addition to +the news groups, you may want to start Gnus anyway. + +Gnus, being the trusting sort of program, will ask whether to proceed +without a native select method if that server can't be contacted. This +will happen whether the server doesn't actually exist (i.e., you have +given the wrong address) or the server has just momentarily taken ill +for some reason or other. If you decide to continue and have no foreign +groups, you'll find it difficult to actually do anything in the group +buffer. But, hey, that's your problem. Blllrph! + +@findex gnus-no-server +@kindex M-x gnus-no-server +@c @head +If you know that the server is definitely down, or you just want to read +your mail without bothering with the server at all, you can use the +@code{gnus-no-server} command to start Gnus. That might come in handy +if you're in a hurry as well. This command will not attempt to contact +your primary server---instead, it will just activate all groups on level +1 and 2. (You should preferably keep no native groups on those two +levels.) + + +@node Slave Gnusae +@section Slave Gnusae +@cindex slave + +You might want to run more than one Emacs with more than one Gnus at the +same time. If you are using different @file{.newsrc} files (e.g., if you +are using the two different Gnusae to read from two different servers), +that is no problem whatsoever. You just do it. + +The problem appears when you want to run two Gnusae that use the same +@code{.newsrc} file. + +To work around that problem some, we here at the Think-Tank at the Gnus +Towers have come up with a new concept: @dfn{Masters} and +@dfn{slaves}. (We have applied for a patent on this concept, and have +taken out a copyright on those words. If you wish to use those words in +conjunction with each other, you have to send $1 per usage instance to +me. Usage of the patent (@dfn{Master/Slave Relationships In Computer +Applications}) will be much more expensive, of course.) + +Anyways, you start one Gnus up the normal way with @kbd{M-x gnus} (or +however you do it). Each subsequent slave Gnusae should be started with +@kbd{M-x gnus-slave}. These slaves won't save normal @file{.newsrc} +files, but instead save @dfn{slave files} that contain information only +on what groups have been read in the slave session. When a master Gnus +starts, it will read (and delete) these slave files, incorporating all +information from them. (The slave files will be read in the sequence +they were created, so the latest changes will have precedence.) + +Information from the slave files has, of course, precedence over the +information in the normal (i.e., master) @code{.newsrc} file. + + +@node Fetching a Group +@section Fetching a Group +@cindex fetching a group + +@findex gnus-fetch-group +It is sometimes convenient to be able to just say ``I want to read this +group and I don't care whether Gnus has been started or not''. This is +perhaps more useful for people who write code than for users, but the +command @code{gnus-fetch-group} provides this functionality in any case. +It takes the group name as a parameter. + + +@node New Groups +@section New Groups +@cindex new groups +@cindex subscription + +@vindex gnus-check-new-newsgroups +If you are satisfied that you really never want to see any new groups, +you can set @code{gnus-check-new-newsgroups} to @code{nil}. This will +also save you some time at startup. Even if this variable is +@code{nil}, you can always subscribe to the new groups just by pressing +@kbd{U} in the group buffer (@pxref{Group Maintenance}). This variable +is @code{ask-server} by default. If you set this variable to +@code{always}, then Gnus will query the backends for new groups even +when you do the @kbd{g} command (@pxref{Scanning New Messages}). + +@menu +* Checking New Groups:: Determining what groups are new. +* Subscription Methods:: What Gnus should do with new groups. +* Filtering New Groups:: Making Gnus ignore certain new groups. +@end menu + + +@node Checking New Groups +@subsection Checking New Groups + +Gnus normally determines whether a group is new or not by comparing the +list of groups from the active file(s) with the lists of subscribed and +dead groups. This isn't a particularly fast method. If +@code{gnus-check-new-newsgroups} is @code{ask-server}, Gnus will ask the +server for new groups since the last time. This is both faster and +cheaper. This also means that you can get rid of the list of killed +groups altogether, so you may set @code{gnus-save-killed-list} to +@code{nil}, which will save time both at startup, at exit, and all over. +Saves disk space, too. Why isn't this the default, then? +Unfortunately, not all servers support this command. + +I bet I know what you're thinking now: How do I find out whether my +server supports @code{ask-server}? No? Good, because I don't have a +fail-safe answer. I would suggest just setting this variable to +@code{ask-server} and see whether any new groups appear within the next +few days. If any do, then it works. If none do, then it doesn't +work. I could write a function to make Gnus guess whether the server +supports @code{ask-server}, but it would just be a guess. So I won't. +You could @code{telnet} to the server and say @code{HELP} and see +whether it lists @samp{NEWGROUPS} among the commands it understands. If +it does, then it might work. (But there are servers that lists +@samp{NEWGROUPS} without supporting the function properly.) + +This variable can also be a list of select methods. If so, Gnus will +issue an @code{ask-server} command to each of the select methods, and +subscribe them (or not) using the normal methods. This might be handy +if you are monitoring a few servers for new groups. A side effect is +that startup will take much longer, so you can meditate while waiting. +Use the mantra ``dingnusdingnusdingnus'' to achieve permanent bliss. + + +@node Subscription Methods +@subsection Subscription Methods + +@vindex gnus-subscribe-newsgroup-method +What Gnus does when it encounters a new group is determined by the +@code{gnus-subscribe-newsgroup-method} variable. + +This variable should contain a function. This function will be called +with the name of the new group as the only parameter. + +Some handy pre-fab functions are: + +@table @code + +@item gnus-subscribe-zombies +@vindex gnus-subscribe-zombies +Make all new groups zombies. This is the default. You can browse the +zombies later (with @kbd{A z}) and either kill them all off properly +(with @kbd{S z}), or subscribe to them (with @kbd{u}). + +@item gnus-subscribe-randomly +@vindex gnus-subscribe-randomly +Subscribe all new groups in arbitrary order. This really means that all +new groups will be added at ``the top'' of the group buffer. + +@item gnus-subscribe-alphabetically +@vindex gnus-subscribe-alphabetically +Subscribe all new groups in alphabetical order. + +@item gnus-subscribe-hierarchically +@vindex gnus-subscribe-hierarchically +Subscribe all new groups hierarchically. The difference between this +function and @code{gnus-subscribe-alphabetically} is slight. +@code{gnus-subscribe-alphabetically} will subscribe new groups in a strictly +alphabetical fashion, while this function will enter groups into it's +hierarchy. So if you want to have the @samp{rec} hierarchy before the +@samp{comp} hierarchy, this function will not mess that configuration +up. Or something like that. + +@item gnus-subscribe-interactively +@vindex gnus-subscribe-interactively +Subscribe new groups interactively. This means that Gnus will ask +you about @strong{all} new groups. The groups you choose to subscribe +to will be subscribed hierarchically. + +@item gnus-subscribe-killed +@vindex gnus-subscribe-killed +Kill all new groups. + +@end table + +@vindex gnus-subscribe-hierarchical-interactive +A closely related variable is +@code{gnus-subscribe-hierarchical-interactive}. (That's quite a +mouthful.) If this variable is non-@code{nil}, Gnus will ask you in a +hierarchical fashion whether to subscribe to new groups or not. Gnus +will ask you for each sub-hierarchy whether you want to descend the +hierarchy or not. + +One common mistake is to set the variable a few paragraphs above +(@code{gnus-subscribe-newsgroup-method}) to +@code{gnus-subscribe-hierarchical-interactive}. This is an error. This +will not work. This is ga-ga. So don't do it. + + +@node Filtering New Groups +@subsection Filtering New Groups + +A nice and portable way to control which new newsgroups should be +subscribed (or ignored) is to put an @dfn{options} line at the start of +the @file{.newsrc} file. Here's an example: + +@example +options -n !alt.all !rec.all sci.all +@end example + +@vindex gnus-subscribe-options-newsgroup-method +This line obviously belongs to a serious-minded intellectual scientific +person (or she may just be plain old boring), because it says that all +groups that have names beginning with @samp{alt} and @samp{rec} should +be ignored, and all groups with names beginning with @samp{sci} should +be subscribed. Gnus will not use the normal subscription method for +subscribing these groups. +@code{gnus-subscribe-options-newsgroup-method} is used instead. This +variable defaults to @code{gnus-subscribe-alphabetically}. + +@vindex gnus-options-not-subscribe +@vindex gnus-options-subscribe +If you don't want to mess with your @file{.newsrc} file, you can just +set the two variables @code{gnus-options-subscribe} and +@code{gnus-options-not-subscribe}. These two variables do exactly the +same as the @file{.newsrc} @samp{options -n} trick. Both are regexps, +and if the new group matches the former, it will be unconditionally +subscribed, and if it matches the latter, it will be ignored. + +@vindex gnus-auto-subscribed-groups +Yet another variable that meddles here is +@code{gnus-auto-subscribed-groups}. It works exactly like +@code{gnus-options-subscribe}, and is therefore really superfluous, but I +thought it would be nice to have two of these. This variable is more +meant for setting some ground rules, while the other variable is used +more for user fiddling. By default this variable makes all new groups +that come from mail backends (@code{nnml}, @code{nnbabyl}, +@code{nnfolder}, @code{nnmbox}, and @code{nnmh}) subscribed. If you +don't like that, just set this variable to @code{nil}. + +New groups that match this regexp are subscribed using +@code{gnus-subscribe-options-newsgroup-method}. + + +@node Changing Servers +@section Changing Servers +@cindex changing servers + +Sometimes it is necessary to move from one @sc{nntp} server to another. +This happens very rarely, but perhaps you change jobs, or one server is +very flaky and you want to use another. + +Changing the server is pretty easy, right? You just change +@code{gnus-select-method} to point to the new server? + +@emph{Wrong!} + +Article numbers are not (in any way) kept synchronized between different +@sc{nntp} servers, and the only way Gnus keeps track of what articles +you have read is by keeping track of article numbers. So when you +change @code{gnus-select-method}, your @file{.newsrc} file becomes +worthless. + +Gnus provides a few functions to attempt to translate a @file{.newsrc} +file from one server to another. They all have one thing in +common---they take a looong time to run. You don't want to use these +functions more than absolutely necessary. + +@kindex M-x gnus-change-server +@findex gnus-change-server +If you have access to both servers, Gnus can request the headers for all +the articles you have read and compare @code{Message-ID}s and map the +article numbers of the read articles and article marks. The @kbd{M-x +gnus-change-server} command will do this for all your native groups. It +will prompt for the method you want to move to. + +@kindex M-x gnus-group-move-group-to-server +@findex gnus-group-move-group-to-server +You can also move individual groups with the @kbd{M-x +gnus-group-move-group-to-server} command. This is useful if you want to +move a (foreign) group from one server to another. + +@kindex M-x gnus-group-clear-data-on-native-groups +@findex gnus-group-clear-data-on-native-groups +If you don't have access to both the old and new server, all your marks +and read ranges have become worthless. You can use the @kbd{M-x +gnus-group-clear-data-on-native-groups} command to clear out all data +that you have on your native groups. Use with caution. + + +@node Startup Files +@section Startup Files +@cindex startup files +@cindex .newsrc +@cindex .newsrc.el +@cindex .newsrc.eld + +Now, you all know about the @file{.newsrc} file. All subscription +information is traditionally stored in this file. + +Things got a bit more complicated with @sc{gnus}. In addition to +keeping the @file{.newsrc} file updated, it also used a file called +@file{.newsrc.el} for storing all the information that didn't fit into +the @file{.newsrc} file. (Actually, it also duplicated everything in +the @file{.newsrc} file.) @sc{gnus} would read whichever one of these +files was the most recently saved, which enabled people to swap between +@sc{gnus} and other newsreaders. + +That was kinda silly, so Gnus went one better: In addition to the +@file{.newsrc} and @file{.newsrc.el} files, Gnus also has a file called +@file{.newsrc.eld}. It will read whichever of these files that are most +recent, but it will never write a @file{.newsrc.el} file. You should +never delete the @file{.newsrc.eld} file---it contains much information +not stored in the @file{.newsrc} file. + +@vindex gnus-save-newsrc-file +You can turn off writing the @file{.newsrc} file by setting +@code{gnus-save-newsrc-file} to @code{nil}, which means you can delete +the file and save some space, as well as exiting from Gnus faster. +However, this will make it impossible to use other newsreaders than +Gnus. But hey, who would want to, right? + +@vindex gnus-save-killed-list +If @code{gnus-save-killed-list} (default @code{t}) is @code{nil}, Gnus +will not save the list of killed groups to the startup file. This will +save both time (when starting and quitting) and space (on disk). It +will also mean that Gnus has no record of what groups are new or old, +so the automatic new groups subscription methods become meaningless. +You should always set @code{gnus-check-new-newsgroups} to @code{nil} or +@code{ask-server} if you set this variable to @code{nil} (@pxref{New +Groups}). This variable can also be a regular expression. If that's +the case, remove all groups that do not match this regexp before +saving. This can be useful in certain obscure situations that involve +several servers where not all servers support @code{ask-server}. + +@vindex gnus-startup-file +The @code{gnus-startup-file} variable says where the startup files are. +The default value is @file{~/.newsrc}, with the Gnus (El Dingo) startup +file being whatever that one is, with a @samp{.eld} appended. + +@vindex gnus-save-newsrc-hook +@vindex gnus-save-quick-newsrc-hook +@vindex gnus-save-standard-newsrc-hook +@code{gnus-save-newsrc-hook} is called before saving any of the newsrc +files, while @code{gnus-save-quick-newsrc-hook} is called just before +saving the @file{.newsrc.eld} file, and +@code{gnus-save-standard-newsrc-hook} is called just before saving the +@file{.newsrc} file. The latter two are commonly used to turn version +control on or off. Version control is on by default when saving the +startup files. If you want to turn backup creation off, say something like: + +@lisp +(defun turn-off-backup () + (set (make-local-variable 'backup-inhibited) t)) + +(add-hook 'gnus-save-quick-newsrc-hook 'turn-off-backup) +(add-hook 'gnus-save-standard-newsrc-hook 'turn-off-backup) +@end lisp + +@vindex gnus-init-file +When Gnus starts, it will read the @code{gnus-site-init-file} +(@file{.../site-lisp/gnus} by default) and @code{gnus-init-file} +(@file{~/.gnus} by default) files. These are normal Emacs Lisp files +and can be used to avoid cluttering your @file{~/.emacs} and +@file{site-init} files with Gnus stuff. Gnus will also check for files +with the same names as these, but with @file{.elc} and @file{.el} +suffixes. In other words, if you have set @code{gnus-init-file} to +@file{~/.gnus}, it will look for @file{~/.gnus.elc}, @file{~/.gnus.el}, +and finally @file{~/.gnus} (in this order). + + + +@node Auto Save +@section Auto Save +@cindex dribble file +@cindex auto-save + +Whenever you do something that changes the Gnus data (reading articles, +catching up, killing/subscribing groups), the change is added to a +special @dfn{dribble buffer}. This buffer is auto-saved the normal +Emacs way. If your Emacs should crash before you have saved the +@file{.newsrc} files, all changes you have made can be recovered from +this file. + +If Gnus detects this file at startup, it will ask the user whether to +read it. The auto save file is deleted whenever the real startup file is +saved. + +@vindex gnus-use-dribble-file +If @code{gnus-use-dribble-file} is @code{nil}, Gnus won't create and +maintain a dribble buffer. The default is @code{t}. + +@vindex gnus-dribble-directory +Gnus will put the dribble file(s) in @code{gnus-dribble-directory}. If +this variable is @code{nil}, which it is by default, Gnus will dribble +into the directory where the @file{.newsrc} file is located. (This is +normally the user's home directory.) The dribble file will get the same +file permissions as the @code{.newsrc} file. + +@vindex gnus-always-read-dribble-file +If @code{gnus-always-read-dribble-file} is non-@code{nil}, Gnus will +read the dribble file on startup without querying the user. + + +@node The Active File +@section The Active File +@cindex active file +@cindex ignored groups + +When Gnus starts, or indeed whenever it tries to determine whether new +articles have arrived, it reads the active file. This is a very large +file that lists all the active groups and articles on the server. + +@vindex gnus-ignored-newsgroups +Before examining the active file, Gnus deletes all lines that match the +regexp @code{gnus-ignored-newsgroups}. This is done primarily to reject +any groups with bogus names, but you can use this variable to make Gnus +ignore hierarchies you aren't ever interested in. However, this is not +recommended. In fact, it's highly discouraged. Instead, @pxref{New +Groups} for an overview of other variables that can be used instead. + +@c This variable is +@c @code{nil} by default, and will slow down active file handling somewhat +@c if you set it to anything else. + +@vindex gnus-read-active-file +@c @head +The active file can be rather Huge, so if you have a slow network, you +can set @code{gnus-read-active-file} to @code{nil} to prevent Gnus from +reading the active file. This variable is @code{some} by default. + +Gnus will try to make do by getting information just on the groups that +you actually subscribe to. + +Note that if you subscribe to lots and lots of groups, setting this +variable to @code{nil} will probably make Gnus slower, not faster. At +present, having this variable @code{nil} will slow Gnus down +considerably, unless you read news over a 2400 baud modem. + +This variable can also have the value @code{some}. Gnus will then +attempt to read active info only on the subscribed groups. On some +servers this is quite fast (on sparkling, brand new INN servers that +support the @code{LIST ACTIVE group} command), on others this isn't fast +at all. In any case, @code{some} should be faster than @code{nil}, and +is certainly faster than @code{t} over slow lines. + +If this variable is @code{nil}, Gnus will ask for group info in total +lock-step, which isn't very fast. If it is @code{some} and you use an +@sc{nntp} server, Gnus will pump out commands as fast as it can, and +read all the replies in one swoop. This will normally result in better +performance, but if the server does not support the aforementioned +@code{LIST ACTIVE group} command, this isn't very nice to the server. + +In any case, if you use @code{some} or @code{nil}, you should definitely +kill all groups that you aren't interested in to speed things up. + +Note that this variable also affects active file retrieval from +secondary select methods. + + +@node Startup Variables +@section Startup Variables + +@table @code + +@item gnus-load-hook +@vindex gnus-load-hook +A hook run while Gnus is being loaded. Note that this hook will +normally be run just once in each Emacs session, no matter how many +times you start Gnus. + +@item gnus-before-startup-hook +@vindex gnus-before-startup-hook +A hook run after starting up Gnus successfully. + +@item gnus-startup-hook +@vindex gnus-startup-hook +A hook run as the very last thing after starting up Gnus + +@item gnus-started-hook +@vindex gnus-started-hook +A hook that is run as the very last thing after starting up Gnus +successfully. + +@item gnus-started-hook +@vindex gnus-started-hook +A hook that is run after reading the @file{.newsrc} file(s), but before +generating the group buffer. + +@item gnus-check-bogus-newsgroups +@vindex gnus-check-bogus-newsgroups +If non-@code{nil}, Gnus will check for and delete all bogus groups at +startup. A @dfn{bogus group} is a group that you have in your +@file{.newsrc} file, but doesn't exist on the news server. Checking for +bogus groups can take quite a while, so to save time and resources it's +best to leave this option off, and do the checking for bogus groups once +in a while from the group buffer instead (@pxref{Group Maintenance}). + +@item gnus-inhibit-startup-message +@vindex gnus-inhibit-startup-message +If non-@code{nil}, the startup message won't be displayed. That way, +your boss might not notice as easily that you are reading news instead +of doing your job. Note that this variable is used before +@file{.gnus.el} is loaded, so it should be set in @code{.emacs} instead. + +@item gnus-no-groups-message +@vindex gnus-no-groups-message +Message displayed by Gnus when no groups are available. + +@item gnus-play-startup-jingle +@vindex gnus-play-startup-jingle +If non-@code{nil}, play the Gnus jingle at startup. + +@item gnus-startup-jingle +@vindex gnus-startup-jingle +Jingle to be played if the above variable is non-@code{nil}. The +default is @samp{Tuxedomoon.Jingle4.au}. + +@end table + + +@node The Group Buffer +@chapter The Group Buffer +@cindex group buffer + +The @dfn{group buffer} lists all (or parts) of the available groups. It +is the first buffer shown when Gnus starts, and will never be killed as +long as Gnus is active. + + +@menu +* Group Buffer Format:: Information listed and how you can change it. +* Group Maneuvering:: Commands for moving in the group buffer. +* Selecting a Group:: Actually reading news. +* Group Data:: Changing the info for a group. +* Subscription Commands:: Unsubscribing, killing, subscribing. +* Group Levels:: Levels? What are those, then? +* Group Score:: A mechanism for finding out what groups you like. +* Marking Groups:: You can mark groups for later processing. +* Foreign Groups:: Creating and editing groups. +* Group Parameters:: Each group may have different parameters set. +* Listing Groups:: Gnus can list various subsets of the groups. +* Sorting Groups:: Re-arrange the group order. +* Group Maintenance:: Maintaining a tidy @file{.newsrc} file. +* Browse Foreign Server:: You can browse a server. See what it has to offer. +* Exiting Gnus:: Stop reading news and get some work done. +* Group Topics:: A folding group mode divided into topics. +* Misc Group Stuff:: Other stuff that you can to do. +@end menu + + +@node Group Buffer Format +@section Group Buffer Format + +@menu +* Group Line Specification:: Deciding how the group buffer is to look. +* Group Modeline Specification:: The group buffer modeline. +* Group Highlighting:: Having nice colors in the group buffer. +@end menu + + +@node Group Line Specification +@subsection Group Line Specification +@cindex group buffer format + +The default format of the group buffer is nice and dull, but you can +make it as exciting and ugly as you feel like. + +Here's a couple of example group lines: + +@example + 25: news.announce.newusers + * 0: alt.fan.andrea-dworkin +@end example + +Quite simple, huh? + +You can see that there are 25 unread articles in +@samp{news.announce.newusers}. There are no unread articles, but some +ticked articles, in @samp{alt.fan.andrea-dworkin} (see that little +asterisk at the beginning of the line?). + +@vindex gnus-group-line-format +You can change that format to whatever you want by fiddling with the +@code{gnus-group-line-format} variable. This variable works along the +lines of a @code{format} specification, which is pretty much the same as +a @code{printf} specifications, for those of you who use (feh!) C. +@xref{Formatting Variables}. + +@samp{%M%S%5y: %(%g%)\n} is the value that produced those lines above. + +There should always be a colon on the line; the cursor always moves to +the colon after performing an operation. Nothing else is required---not +even the group name. All displayed text is just window dressing, and is +never examined by Gnus. Gnus stores all real information it needs using +text properties. + +(Note that if you make a really strange, wonderful, spreadsheet-like +layout, everybody will believe you are hard at work with the accounting +instead of wasting time reading news.) + +Here's a list of all available format characters: + +@table @samp + +@item M +An asterisk if the group only has marked articles. + +@item S +Whether the group is subscribed. + +@item L +Level of subscribedness. + +@item N +Number of unread articles. + +@item I +Number of dormant articles. + +@item T +Number of ticked articles. + +@item R +Number of read articles. + +@item t +Estimated total number of articles. (This is really @var{max-number} +minus @var{min-number} plus 1.) + +@item y +Number of unread, unticked, non-dormant articles. + +@item i +Number of ticked and dormant articles. + +@item g +Full group name. + +@item G +Group name. + +@item D +Newsgroup description. + +@item o +@samp{m} if moderated. + +@item O +@samp{(m)} if moderated. + +@item s +Select method. + +@item n +Select from where. + +@item z +A string that looks like @samp{<%s:%n>} if a foreign select method is +used. + +@item P +Indentation based on the level of the topic (@pxref{Group Topics}). + +@item c +@vindex gnus-group-uncollapsed-levels +Short (collapsed) group name. The @code{gnus-group-uncollapsed-levels} +variable says how many levels to leave at the end of the group name. +The default is 1---this will mean that group names like +@samp{gnu.emacs.gnus} will be shortened to @samp{g.emacs.gnus}. + +@item m +@vindex gnus-new-mail-mark +@cindex % +@samp{%} (@code{gnus-new-mail-mark}) if there has arrived new mail to +the group lately. + +@item d +A string that says when you last read the group (@pxref{Group +Timestamp}). + +@item u +User defined specifier. The next character in the format string should +be a letter. Gnus will call the function +@code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter +following @samp{%u}. The function will be passed a single dummy +parameter as argument. The function should return a string, which will +be inserted into the buffer just like information from any other +specifier. +@end table + +@cindex * +All the ``number-of'' specs will be filled with an asterisk (@samp{*}) +if no info is available---for instance, if it is a non-activated foreign +group, or a bogus native group. + + +@node Group Modeline Specification +@subsection Group Modeline Specification +@cindex group modeline + +@vindex gnus-group-mode-line-format +The mode line can be changed by setting +@code{gnus-group-mode-line-format} (@pxref{Mode Line Formatting}). It +doesn't understand that many format specifiers: + +@table @samp +@item S +The native news server. +@item M +The native select method. +@end table + + +@node Group Highlighting +@subsection Group Highlighting +@cindex highlighting +@cindex group highlighting + +@vindex gnus-group-highlight +Highlighting in the group buffer is controlled by the +@code{gnus-group-highlight} variable. This is an alist with elements +that look like @var{(form . face)}. If @var{form} evaluates to +something non-@code{nil}, the @var{face} will be used on the line. + +Here's an example value for this variable that might look nice if the +background is dark: + +@lisp +(face-spec-set 'my-group-face-1 + '((t (:foreground "Red" :bold t)))) +(face-spec-set 'my-group-face-2 + '((t (:foreground "SeaGreen" :bold t)))) +(face-spec-set 'my-group-face-3 + '((t (:foreground "SpringGreen" :bold t)))) +(face-spec-set 'my-group-face-4 + '((t (:foreground "SteelBlue" :bold t)))) +(face-spec-set 'my-group-face-5 + '((t (:foreground "SkyBlue" :bold t)))) + +(setq gnus-group-highlight + '(((> unread 200) . my-group-face-1) + ((and (< level 3) (zerop unread)) . my-group-face-2) + ((< level 3) . my-group-face-3) + ((zerop unread) . my-group-face-4) + (t . my-group-face-5))) +@end lisp + +Also @pxref{Faces and Fonts}. + +Variables that are dynamically bound when the forms are evaluated +include: + +@table @code +@item group +The group name. +@item unread +The number of unread articles in the group. +@item method +The select method. +@item mailp +Whether the group is a mail group. +@item level +The level of the group. +@item score +The score of the group. +@item ticked +The number of ticked articles in the group. +@item total +The total number of articles in the group. Or rather, MAX-NUMBER minus +MIN-NUMBER plus one. +@item topic +When using the topic minor mode, this variable is bound to the current +topic being inserted. +@end table + +When the forms are @code{eval}ed, point is at the beginning of the line +of the group in question, so you can use many of the normal Gnus +functions for snarfing info on the group. + +@vindex gnus-group-update-hook +@findex gnus-group-highlight-line +@code{gnus-group-update-hook} is called when a group line is changed. +It will not be called when @code{gnus-visual} is @code{nil}. This hook +calls @code{gnus-group-highlight-line} by default. + + +@node Group Maneuvering +@section Group Maneuvering +@cindex group movement + +All movement commands understand the numeric prefix and will behave as +expected, hopefully. + +@table @kbd + +@item n +@kindex n (Group) +@findex gnus-group-next-unread-group +Go to the next group that has unread articles +(@code{gnus-group-next-unread-group}). + +@item p +@itemx DEL +@kindex DEL (Group) +@kindex p (Group) +@findex gnus-group-prev-unread-group +Go to the previous group that has unread articles +(@code{gnus-group-prev-unread-group}). + +@item N +@kindex N (Group) +@findex gnus-group-next-group +Go to the next group (@code{gnus-group-next-group}). + +@item P +@kindex P (Group) +@findex gnus-group-prev-group +Go to the previous group (@code{gnus-group-prev-group}). + +@item M-n +@kindex M-n (Group) +@findex gnus-group-next-unread-group-same-level +Go to the next unread group on the same (or lower) level +(@code{gnus-group-next-unread-group-same-level}). + +@item M-p +@kindex M-p (Group) +@findex gnus-group-prev-unread-group-same-level +Go to the previous unread group on the same (or lower) level +(@code{gnus-group-prev-unread-group-same-level}). +@end table + +Three commands for jumping to groups: + +@table @kbd + +@item j +@kindex j (Group) +@findex gnus-group-jump-to-group +Jump to a group (and make it visible if it isn't already) +(@code{gnus-group-jump-to-group}). Killed groups can be jumped to, just +like living groups. + +@item , +@kindex , (Group) +@findex gnus-group-best-unread-group +Jump to the unread group with the lowest level +(@code{gnus-group-best-unread-group}). + +@item . +@kindex . (Group) +@findex gnus-group-first-unread-group +Jump to the first group with unread articles +(@code{gnus-group-first-unread-group}). +@end table + +@vindex gnus-group-goto-unread +If @code{gnus-group-goto-unread} is @code{nil}, all the movement +commands will move to the next group, not the next unread group. Even +the commands that say they move to the next unread group. The default +is @code{t}. + + +@node Selecting a Group +@section Selecting a Group +@cindex group selection + +@table @kbd + +@item SPACE +@kindex SPACE (Group) +@findex gnus-group-read-group +Select the current group, switch to the summary buffer and display the +first unread article (@code{gnus-group-read-group}). If there are no +unread articles in the group, or if you give a non-numerical prefix to +this command, Gnus will offer to fetch all the old articles in this +group from the server. If you give a numerical prefix @var{N}, @var{N} +determines the number of articles Gnus will fetch. If @var{N} is +positive, Gnus fetches the @var{N} newest articles, if @var{N} is +negative, Gnus fetches the @var{abs(N)} oldest articles. + +@item RET +@kindex RET (Group) +@findex gnus-group-select-group +Select the current group and switch to the summary buffer +(@code{gnus-group-select-group}). Takes the same arguments as +@code{gnus-group-read-group}---the only difference is that this command +does not display the first unread article automatically upon group +entry. + +@item M-RET +@kindex M-RET (Group) +@findex gnus-group-quick-select-group +This does the same as the command above, but tries to do it with the +minimum amount of fuzz (@code{gnus-group-quick-select-group}). No +scoring/killing will be performed, there will be no highlights and no +expunging. This might be useful if you're in a real hurry and have to +enter some humongous group. If you give a 0 prefix to this command +(i.e., @kbd{0 M-RET}), Gnus won't even generate the summary buffer, +which is useful if you want to toggle threading before generating the +summary buffer (@pxref{Summary Generation Commands}). + +@item M-SPACE +@kindex M-SPACE (Group) +@findex gnus-group-visible-select-group +This is yet one more command that does the same as the @kbd{RET} +command, but this one does it without expunging and hiding dormants +(@code{gnus-group-visible-select-group}). + +@item M-C-RET +@kindex M-C-RET (Group) +@findex gnus-group-select-group-ephemerally +Finally, this command selects the current group ephemerally without +doing any processing of its contents +(@code{gnus-group-select-group-ephemerally}). Even threading has been +turned off. Everything you do in the group after selecting it in this +manner will have no permanent effects. + +@end table + +@vindex gnus-large-newsgroup +The @code{gnus-large-newsgroup} variable says what Gnus should consider +to be a big group. This is 200 by default. If the group has more +(unread and/or ticked) articles than this, Gnus will query the user +before entering the group. The user can then specify how many articles +should be fetched from the server. If the user specifies a negative +number (@code{-n}), the @code{n} oldest articles will be fetched. If it +is positive, the @code{n} articles that have arrived most recently will +be fetched. + +@vindex gnus-select-group-hook +@vindex gnus-auto-select-first +@code{gnus-auto-select-first} control whether any articles are selected +automatically when entering a group with the @kbd{SPACE} command. + +@table @code + +@item nil +Don't select any articles when entering the group. Just display the +full summary buffer. + +@item t +Select the first unread article when entering the group. + +@item best +Select the highest scored article in the group when entering the +group. +@end table + +If you want to prevent automatic selection in some group (say, in a +binary group with Huge articles) you can set this variable to @code{nil} +in @code{gnus-select-group-hook}, which is called when a group is +selected. + + +@node Subscription Commands +@section Subscription Commands +@cindex subscription + +@table @kbd + +@item S t +@itemx u +@kindex S t (Group) +@kindex u (Group) +@findex gnus-group-unsubscribe-current-group +@c @icon{gnus-group-unsubscribe} +Toggle subscription to the current group +(@code{gnus-group-unsubscribe-current-group}). + +@item S s +@itemx U +@kindex S s (Group) +@kindex U (Group) +@findex gnus-group-unsubscribe-group +Prompt for a group to subscribe, and then subscribe it. If it was +subscribed already, unsubscribe it instead +(@code{gnus-group-unsubscribe-group}). + +@item S k +@itemx C-k +@kindex S k (Group) +@kindex C-k (Group) +@findex gnus-group-kill-group +@c @icon{gnus-group-kill-group} +Kill the current group (@code{gnus-group-kill-group}). + +@item S y +@itemx C-y +@kindex S y (Group) +@kindex C-y (Group) +@findex gnus-group-yank-group +Yank the last killed group (@code{gnus-group-yank-group}). + +@item C-x C-t +@kindex C-x C-t (Group) +@findex gnus-group-transpose-groups +Transpose two groups (@code{gnus-group-transpose-groups}). This isn't +really a subscription command, but you can use it instead of a +kill-and-yank sequence sometimes. + +@item S w +@itemx C-w +@kindex S w (Group) +@kindex C-w (Group) +@findex gnus-group-kill-region +Kill all groups in the region (@code{gnus-group-kill-region}). + +@item S z +@kindex S z (Group) +@findex gnus-group-kill-all-zombies +Kill all zombie groups (@code{gnus-group-kill-all-zombies}). + +@item S C-k +@kindex S C-k (Group) +@findex gnus-group-kill-level +Kill all groups on a certain level (@code{gnus-group-kill-level}). +These groups can't be yanked back after killing, so this command should +be used with some caution. The only time where this command comes in +really handy is when you have a @file{.newsrc} with lots of unsubscribed +groups that you want to get rid off. @kbd{S C-k} on level 7 will +kill off all unsubscribed groups that do not have message numbers in the +@file{.newsrc} file. + +@end table + +Also @pxref{Group Levels}. + + +@node Group Data +@section Group Data + +@table @kbd + +@item c +@kindex c (Group) +@findex gnus-group-catchup-current +@vindex gnus-group-catchup-group-hook +@c @icon{gnus-group-catchup-current} +Mark all unticked articles in this group as read +(@code{gnus-group-catchup-current}). +@code{gnus-group-catchup-group-hook} is called when catching up a group from +the group buffer. + +@item C +@kindex C (Group) +@findex gnus-group-catchup-current-all +Mark all articles in this group, even the ticked ones, as read +(@code{gnus-group-catchup-current-all}). + +@item M-c +@kindex M-c (Group) +@findex gnus-group-clear-data +Clear the data from the current group---nix out marks and the list of +read articles (@code{gnus-group-clear-data}). + +@item M-x gnus-group-clear-data-on-native-groups +@kindex M-x gnus-group-clear-data-on-native-groups +@findex gnus-group-clear-data-on-native-groups +If you have switched from one @sc{nntp} server to another, all your marks +and read ranges have become worthless. You can use this command to +clear out all data that you have on your native groups. Use with +caution. + +@end table + + +@node Group Levels +@section Group Levels +@cindex group level +@cindex level + +All groups have a level of @dfn{subscribedness}. For instance, if a +group is on level 2, it is more subscribed than a group on level 5. You +can ask Gnus to just list groups on a given level or lower +(@pxref{Listing Groups}), or to just check for new articles in groups on +a given level or lower (@pxref{Scanning New Messages}). + +Remember: The higher the level of the group, the less important it is. + +@table @kbd + +@item S l +@kindex S l (Group) +@findex gnus-group-set-current-level +Set the level of the current group. If a numeric prefix is given, the +next @var{n} groups will have their levels set. The user will be +prompted for a level. +@end table + +@vindex gnus-level-killed +@vindex gnus-level-zombie +@vindex gnus-level-unsubscribed +@vindex gnus-level-subscribed +Gnus considers groups from levels 1 to +@code{gnus-level-subscribed} (inclusive) (default 5) to be subscribed, +@code{gnus-level-subscribed} (exclusive) and +@code{gnus-level-unsubscribed} (inclusive) (default 7) to be +unsubscribed, @code{gnus-level-zombie} to be zombies (walking dead) +(default 8) and @code{gnus-level-killed} to be killed (completely dead) +(default 9). Gnus treats subscribed and unsubscribed groups exactly the +same, but zombie and killed groups have no information on what articles +you have read, etc, stored. This distinction between dead and living +groups isn't done because it is nice or clever, it is done purely for +reasons of efficiency. + +It is recommended that you keep all your mail groups (if any) on quite +low levels (e.g. 1 or 2). + +If you want to play with the level variables, you should show some care. +Set them once, and don't touch them ever again. Better yet, don't touch +them at all unless you know exactly what you're doing. + +@vindex gnus-level-default-unsubscribed +@vindex gnus-level-default-subscribed +Two closely related variables are @code{gnus-level-default-subscribed} +(default 3) and @code{gnus-level-default-unsubscribed} (default 6), +which are the levels that new groups will be put on if they are +(un)subscribed. These two variables should, of course, be inside the +relevant valid ranges. + +@vindex gnus-keep-same-level +If @code{gnus-keep-same-level} is non-@code{nil}, some movement commands +will only move to groups of the same level (or lower). In +particular, going from the last article in one group to the next group +will go to the next group of the same level (or lower). This might be +handy if you want to read the most important groups before you read the +rest. + +@vindex gnus-group-default-list-level +All groups with a level less than or equal to +@code{gnus-group-default-list-level} will be listed in the group buffer +by default. + +@vindex gnus-group-list-inactive-groups +If @code{gnus-group-list-inactive-groups} is non-@code{nil}, non-active +groups will be listed along with the unread groups. This variable is +@code{t} by default. If it is @code{nil}, inactive groups won't be +listed. + +@vindex gnus-group-use-permanent-levels +If @code{gnus-group-use-permanent-levels} is non-@code{nil}, once you +give a level prefix to @kbd{g} or @kbd{l}, all subsequent commands will +use this level as the ``work'' level. + +@vindex gnus-activate-level +Gnus will normally just activate (i. e., query the server about) groups +on level @code{gnus-activate-level} or less. If you don't want to +activate unsubscribed groups, for instance, you might set this variable +to 5. The default is 6. + + +@node Group Score +@section Group Score +@cindex group score +@cindex group rank +@cindex rank + +You would normally keep important groups on high levels, but that scheme +is somewhat restrictive. Don't you wish you could have Gnus sort the +group buffer according to how often you read groups, perhaps? Within +reason? + +This is what @dfn{group score} is for. You can assign a score to each +group. You can then sort the group buffer based on this score. +Alternatively, you can sort on score and then level. (Taken together, +the level and the score is called the @dfn{rank} of the group. A group +that is on level 4 and has a score of 1 has a higher rank than a group +on level 5 that has a score of 300. (The level is the most significant +part and the score is the least significant part.)) + +@findex gnus-summary-bubble-group +If you want groups you read often to get higher scores than groups you +read seldom you can add the @code{gnus-summary-bubble-group} function to +the @code{gnus-summary-exit-hook} hook. This will result (after +sorting) in a bubbling sort of action. If you want to see that in +action after each summary exit, you can add +@code{gnus-group-sort-groups-by-rank} or +@code{gnus-group-sort-groups-by-score} to the same hook, but that will +slow things down somewhat. + + +@node Marking Groups +@section Marking Groups +@cindex marking groups + +If you want to perform some command on several groups, and they appear +subsequently in the group buffer, you would normally just give a +numerical prefix to the command. Most group commands will then do your +bidding on those groups. + +However, if the groups are not in sequential order, you can still +perform a command on several groups. You simply mark the groups first +with the process mark and then execute the command. + +@table @kbd + +@item # +@kindex # (Group) +@itemx M m +@kindex M m (Group) +@findex gnus-group-mark-group +Set the mark on the current group (@code{gnus-group-mark-group}). + +@item M-# +@kindex M-# (Group) +@itemx M u +@kindex M u (Group) +@findex gnus-group-unmark-group +Remove the mark from the current group +(@code{gnus-group-unmark-group}). + +@item M U +@kindex M U (Group) +@findex gnus-group-unmark-all-groups +Remove the mark from all groups (@code{gnus-group-unmark-all-groups}). + +@item M w +@kindex M w (Group) +@findex gnus-group-mark-region +Mark all groups between point and mark (@code{gnus-group-mark-region}). + +@item M b +@kindex M b (Group) +@findex gnus-group-mark-buffer +Mark all groups in the buffer (@code{gnus-group-mark-buffer}). + +@item M r +@kindex M r (Group) +@findex gnus-group-mark-regexp +Mark all groups that match some regular expression +(@code{gnus-group-mark-regexp}). +@end table + +Also @pxref{Process/Prefix}. + +@findex gnus-group-universal-argument +If you want to execute some command on all groups that have been marked +with the process mark, you can use the @kbd{M-&} +(@code{gnus-group-universal-argument}) command. It will prompt you for +the command to be executed. + + +@node Foreign Groups +@section Foreign Groups +@cindex foreign groups + +Below are some group mode commands for making and editing general foreign +groups, as well as commands to ease the creation of a few +special-purpose groups. All these commands insert the newly created +groups under point---@code{gnus-subscribe-newsgroup-method} is not +consulted. + +@table @kbd + +@item G m +@kindex G m (Group) +@findex gnus-group-make-group +@cindex making groups +Make a new group (@code{gnus-group-make-group}). Gnus will prompt you +for a name, a method and possibly an @dfn{address}. For an easier way +to subscribe to @sc{nntp} groups, @pxref{Browse Foreign Server}. + +@item G r +@kindex G r (Group) +@findex gnus-group-rename-group +@cindex renaming groups +Rename the current group to something else +(@code{gnus-group-rename-group}). This is valid only on some +groups---mail groups mostly. This command might very well be quite slow +on some backends. + +@item G c +@kindex G c (Group) +@cindex customizing +@findex gnus-group-customize +Customize the group parameters (@code{gnus-group-customize}). + +@item G e +@kindex G e (Group) +@findex gnus-group-edit-group-method +@cindex renaming groups +Enter a buffer where you can edit the select method of the current +group (@code{gnus-group-edit-group-method}). + +@item G p +@kindex G p (Group) +@findex gnus-group-edit-group-parameters +Enter a buffer where you can edit the group parameters +(@code{gnus-group-edit-group-parameters}). + +@item G E +@kindex G E (Group) +@findex gnus-group-edit-group +Enter a buffer where you can edit the group info +(@code{gnus-group-edit-group}). + +@item G d +@kindex G d (Group) +@findex gnus-group-make-directory-group +@cindex nndir +Make a directory group (@pxref{Directory Groups}). You will be prompted +for a directory name (@code{gnus-group-make-directory-group}). + +@item G h +@kindex G h (Group) +@cindex help group +@findex gnus-group-make-help-group +Make the Gnus help group (@code{gnus-group-make-help-group}). + +@item G a +@kindex G a (Group) +@cindex (ding) archive +@cindex archive group +@findex gnus-group-make-archive-group +@vindex gnus-group-archive-directory +@vindex gnus-group-recent-archive-directory +Make a Gnus archive group (@code{gnus-group-make-archive-group}). By +default a group pointing to the most recent articles will be created +(@code{gnus-group-recent-archive-directory}), but given a prefix, a full +group will be created from @code{gnus-group-archive-directory}. + +@item G k +@kindex G k (Group) +@findex gnus-group-make-kiboze-group +@cindex nnkiboze +Make a kiboze group. You will be prompted for a name, for a regexp to +match groups to be ``included'' in the kiboze group, and a series of +strings to match on headers (@code{gnus-group-make-kiboze-group}). +@xref{Kibozed Groups}. + +@item G D +@kindex G D (Group) +@findex gnus-group-enter-directory +@cindex nneething +Read an arbitrary directory as if it were a newsgroup with the +@code{nneething} backend (@code{gnus-group-enter-directory}). +@xref{Anything Groups}. + +@item G f +@kindex G f (Group) +@findex gnus-group-make-doc-group +@cindex ClariNet Briefs +@cindex nndoc +Make a group based on some file or other +(@code{gnus-group-make-doc-group}). If you give a prefix to this +command, you will be prompted for a file name and a file type. +Currently supported types are @code{babyl}, @code{mbox}, @code{digest}, +@code{mmdf}, @code{news}, @code{rnews}, @code{clari-briefs}, +@code{rfc934}, @code{rfc822-forward}, and @code{forward}. If you run +this command without a prefix, Gnus will guess at the file type. +@xref{Document Groups}. + +@item G u +@kindex G u (Group) +@vindex gnus-useful-groups +@findex gnus-group-make-useful-group +Create one of the groups mentioned in @code{gnus-useful-groups} +(@code{gnus-group-make-useful-group}). + +@item G w +@kindex G w (Group) +@findex gnus-group-make-web-group +@cindex DejaNews +@cindex Alta Vista +@cindex InReference +@cindex nnweb +Make an ephemeral group based on a web search +(@code{gnus-group-make-web-group}). If you give a prefix to this +command, make a solid group instead. You will be prompted for the +search engine type and the search string. Valid search engine types +include @code{dejanews}, @code{altavista} and @code{reference}. +@xref{Web Searches}. + +If you use the @code{dejanews} search engine, you can limit the search +to a particular group by using a match string like +@samp{~g alt.sysadmin.recovery shaving}. + +@item G DEL +@kindex G DEL (Group) +@findex gnus-group-delete-group +This function will delete the current group +(@code{gnus-group-delete-group}). If given a prefix, this function will +actually delete all the articles in the group, and forcibly remove the +group itself from the face of the Earth. Use a prefix only if you are +absolutely sure of what you are doing. This command can't be used on +read-only groups (like @code{nntp} group), though. + +@item G V +@kindex G V (Group) +@findex gnus-group-make-empty-virtual +Make a new, fresh, empty @code{nnvirtual} group +(@code{gnus-group-make-empty-virtual}). @xref{Virtual Groups}. + +@item G v +@kindex G v (Group) +@findex gnus-group-add-to-virtual +Add the current group to an @code{nnvirtual} group +(@code{gnus-group-add-to-virtual}). Uses the process/prefix convention. +@end table + +@xref{Select Methods}, for more information on the various select +methods. + +@vindex gnus-activate-foreign-newsgroups +If @code{gnus-activate-foreign-newsgroups} is a positive number, +Gnus will check all foreign groups with this level or lower at startup. +This might take quite a while, especially if you subscribe to lots of +groups from different @sc{nntp} servers. Also @pxref{Group Levels}; +@code{gnus-activate-level} also affects activation of foreign +newsgroups. + + +@node Group Parameters +@section Group Parameters +@cindex group parameters + +The group parameters store information local to a particular group. +Here's an example group parameter list: + +@example +((to-address . "ding@@gnus.org") + (auto-expire . t)) +@end example + +We see that each element consists of a "dotted pair"---the thing before +the dot is the key, while the thing after the dot is the value. All the +parameters have this form @emph{except} local variable specs, which are +not dotted pairs, but proper lists. + +The following group parameters can be used: + +@table @code +@item to-address +@cindex to-address +Address used by when doing followups and new posts. + +@example +(to-address . "some@@where.com") +@end example + +This is primarily useful in mail groups that represent closed mailing +lists---mailing lists where it's expected that everybody that writes to +the mailing list is subscribed to it. Since using this parameter +ensures that the mail only goes to the mailing list itself, it means +that members won't receive two copies of your followups. + +Using @code{to-address} will actually work whether the group is foreign +or not. Let's say there's a group on the server that is called +@samp{fa.4ad-l}. This is a real newsgroup, but the server has gotten +the articles from a mail-to-news gateway. Posting directly to this +group is therefore impossible---you have to send mail to the mailing +list address instead. + +@item to-list +@cindex to-list +Address used when doing a @kbd{a} in that group. + +@example +(to-list . "some@@where.com") +@end example + +It is totally ignored +when doing a followup---except that if it is present in a news group, +you'll get mail group semantics when doing @kbd{f}. + +If you do an @kbd{a} command in a mail group and you have neither a +@code{to-list} group parameter nor a @code{to-address} group parameter, +then a @code{to-list} group parameter will be added automatically upon +sending the message if @code{gnus-add-to-list} is set to @code{t}. +@vindex gnus-add-to-list + +If you do an @kbd{a} command in a mail group and you don't have a +@code{to-list} group parameter, one will be added automatically upon +sending the message. + +@item visible +@cindex visible +If the group parameter list has the element @code{(visible . t)}, +that group will always be visible in the Group buffer, regardless +of whether it has any unread articles. + +@item broken-reply-to +@cindex broken-reply-to +Elements like @code{(broken-reply-to . t)} signals that @code{Reply-To} +headers in this group are to be ignored. This can be useful if you're +reading a mailing list group where the listserv has inserted +@code{Reply-To} headers that point back to the listserv itself. This is +broken behavior. So there! + +@item to-group +@cindex to-group +Elements like @code{(to-group . "some.group.name")} means that all +posts in that group will be sent to @code{some.group.name}. + +@item newsgroup +@cindex newsgroup +If you have @code{(newsgroup . t)} in the group parameter list, Gnus +will treat all responses as if they were responses to news articles. +This can be useful if you have a mail group that's really a mirror of a +news group. + +@item gcc-self +@cindex gcc-self +If @code{(gcc-self . t)} is present in the group parameter list, newly +composed messages will be @code{Gcc}'d to the current group. If +@code{(gcc-self . none)} is present, no @code{Gcc:} header will be +generated, if @code{(gcc-self . "string")} is present, this string will +be inserted literally as a @code{gcc} header. This parameter takes +precedence over any default @code{Gcc} rules as described later +(@pxref{Archived Messages}). + +@item auto-expire +@cindex auto-expire +If the group parameter has an element that looks like @code{(auto-expire +. t)}, all articles read will be marked as expirable. For an +alternative approach, @pxref{Expiring Mail}. + +@item total-expire +@cindex total-expire +If the group parameter has an element that looks like +@code{(total-expire . t)}, all read articles will be put through the +expiry process, even if they are not marked as expirable. Use with +caution. Unread, ticked and dormant articles are not eligible for +expiry. + +@item expiry-wait +@cindex expiry-wait +@vindex nnmail-expiry-wait-function +If the group parameter has an element that looks like @code{(expiry-wait +. 10)}, this value will override any @code{nnmail-expiry-wait} and +@code{nnmail-expiry-wait-function} when expiring expirable messages. +The value can either be a number of days (not necessarily an integer) or +the symbols @code{never} or @code{immediate}. + +@item score-file +@cindex score file group parameter +Elements that look like @code{(score-file . "file")} will make +@file{file} into the current score file for the group in question. All +interactive score entries will be put into this file. + +@item adapt-file +@cindex adapt file group parameter +Elements that look like @code{(adapt-file . "file")} will make +@file{file} into the current adaptive file for the group in question. +All adaptive score entries will be put into this file. + +@item admin-address +When unsubscribing from a mailing list you should never send the +unsubscription notice to the mailing list itself. Instead, you'd send +messages to the administrative address. This parameter allows you to +put the admin address somewhere convenient. + +@item display +Elements that look like @code{(display . MODE)} say which articles to +display on entering the group. Valid values are: + +@table @code +@item all +Display all articles, both read and unread. + +@item default +Display the default visible articles, which normally includes unread and +ticked articles. +@end table + +@item comment +Elements that look like @code{(comment . "This is a comment")} +are arbitrary comments on the group. They are currently ignored by +Gnus, but provide a place for you to store information on particular +groups. + +@item @var{(variable form)} +You can use the group parameters to set variables local to the group you +are entering. If you want to turn threading off in @samp{news.answers}, +you could put @code{(gnus-show-threads nil)} in the group parameters of +that group. @code{gnus-show-threads} will be made into a local variable +in the summary buffer you enter, and the form @code{nil} will be +@code{eval}ed there. + +This can also be used as a group-specific hook function, if you'd like. +If you want to hear a beep when you enter a group, you could put +something like @code{(dummy-variable (ding))} in the parameters of that +group. @code{dummy-variable} will be set to the result of the +@code{(ding)} form, but who cares? + +@end table + +Use the @kbd{G p} command to edit group parameters of a group. You +might also be interested in reading about topic parameters (@pxref{Topic +Parameters}). + + +@node Listing Groups +@section Listing Groups +@cindex group listing + +These commands all list various slices of the groups available. + +@table @kbd + +@item l +@itemx A s +@kindex A s (Group) +@kindex l (Group) +@findex gnus-group-list-groups +List all groups that have unread articles +(@code{gnus-group-list-groups}). If the numeric prefix is used, this +command will list only groups of level ARG and lower. By default, it +only lists groups of level five (i. e., +@code{gnus-group-default-list-level}) or lower (i.e., just subscribed +groups). + +@item L +@itemx A u +@kindex A u (Group) +@kindex L (Group) +@findex gnus-group-list-all-groups +List all groups, whether they have unread articles or not +(@code{gnus-group-list-all-groups}). If the numeric prefix is used, +this command will list only groups of level ARG and lower. By default, +it lists groups of level seven or lower (i.e., just subscribed and +unsubscribed groups). + +@item A l +@kindex A l (Group) +@findex gnus-group-list-level +List all unread groups on a specific level +(@code{gnus-group-list-level}). If given a prefix, also list the groups +with no unread articles. + +@item A k +@kindex A k (Group) +@findex gnus-group-list-killed +List all killed groups (@code{gnus-group-list-killed}). If given a +prefix argument, really list all groups that are available, but aren't +currently (un)subscribed. This could entail reading the active file +from the server. + +@item A z +@kindex A z (Group) +@findex gnus-group-list-zombies +List all zombie groups (@code{gnus-group-list-zombies}). + +@item A m +@kindex A m (Group) +@findex gnus-group-list-matching +List all unread, subscribed groups with names that match a regexp +(@code{gnus-group-list-matching}). + +@item A M +@kindex A M (Group) +@findex gnus-group-list-all-matching +List groups that match a regexp (@code{gnus-group-list-all-matching}). + +@item A A +@kindex A A (Group) +@findex gnus-group-list-active +List absolutely all groups in the active file(s) of the +server(s) you are connected to (@code{gnus-group-list-active}). This +might very well take quite a while. It might actually be a better idea +to do a @kbd{A M} to list all matching, and just give @samp{.} as the +thing to match on. Also note that this command may list groups that +don't exist (yet)---these will be listed as if they were killed groups. +Take the output with some grains of salt. + +@item A a +@kindex A a (Group) +@findex gnus-group-apropos +List all groups that have names that match a regexp +(@code{gnus-group-apropos}). + +@item A d +@kindex A d (Group) +@findex gnus-group-description-apropos +List all groups that have names or descriptions that match a regexp +(@code{gnus-group-description-apropos}). + +@end table + +@vindex gnus-permanently-visible-groups +@cindex visible group parameter +Groups that match the @code{gnus-permanently-visible-groups} regexp will +always be shown, whether they have unread articles or not. You can also +add the @code{visible} element to the group parameters in question to +get the same effect. + +@vindex gnus-list-groups-with-ticked-articles +Groups that have just ticked articles in it are normally listed in the +group buffer. If @code{gnus-list-groups-with-ticked-articles} is +@code{nil}, these groups will be treated just like totally empty +groups. It is @code{t} by default. + + +@node Sorting Groups +@section Sorting Groups +@cindex sorting groups + +@kindex C-c C-s (Group) +@findex gnus-group-sort-groups +@vindex gnus-group-sort-function +The @kbd{C-c C-s} (@code{gnus-group-sort-groups}) command sorts the +group buffer according to the function(s) given by the +@code{gnus-group-sort-function} variable. Available sorting functions +include: + +@table @code + +@item gnus-group-sort-by-alphabet +@findex gnus-group-sort-by-alphabet +Sort the group names alphabetically. This is the default. + +@item gnus-group-sort-by-real-name +@findex gnus-group-sort-by-real-name +Sort the group alphabetically on the real (unprefixed) group names. + +@item gnus-group-sort-by-level +@findex gnus-group-sort-by-level +Sort by group level. + +@item gnus-group-sort-by-score +@findex gnus-group-sort-by-score +Sort by group score. @xref{Group Score}. + +@item gnus-group-sort-by-rank +@findex gnus-group-sort-by-rank +Sort by group score and then the group level. The level and the score +are, when taken together, the group's @dfn{rank}. @xref{Group Score}. + +@item gnus-group-sort-by-unread +@findex gnus-group-sort-by-unread +Sort by number of unread articles. + +@item gnus-group-sort-by-method +@findex gnus-group-sort-by-method +Sort alphabetically on the select method. + + +@end table + +@code{gnus-group-sort-function} can also be a list of sorting +functions. In that case, the most significant sort key function must be +the last one. + + +There are also a number of commands for sorting directly according to +some sorting criteria: + +@table @kbd +@item G S a +@kindex G S a (Group) +@findex gnus-group-sort-groups-by-alphabet +Sort the group buffer alphabetically by group name +(@code{gnus-group-sort-groups-by-alphabet}). + +@item G S u +@kindex G S u (Group) +@findex gnus-group-sort-groups-by-unread +Sort the group buffer by the number of unread articles +(@code{gnus-group-sort-groups-by-unread}). + +@item G S l +@kindex G S l (Group) +@findex gnus-group-sort-groups-by-level +Sort the group buffer by group level +(@code{gnus-group-sort-groups-by-level}). + +@item G S v +@kindex G S v (Group) +@findex gnus-group-sort-groups-by-score +Sort the group buffer by group score +(@code{gnus-group-sort-groups-by-score}). @xref{Group Score}. + +@item G S r +@kindex G S r (Group) +@findex gnus-group-sort-groups-by-rank +Sort the group buffer by group rank +(@code{gnus-group-sort-groups-by-rank}). @xref{Group Score}. + +@item G S m +@kindex G S m (Group) +@findex gnus-group-sort-groups-by-method +Sort the group buffer alphabetically by backend name +(@code{gnus-group-sort-groups-by-method}). + +@end table + +When given a prefix, all these commands will sort in reverse order. + +You can also sort a subset of the groups: + +@table @kbd +@item G P a +@kindex G P a (Group) +@findex gnus-group-sort-selected-groups-by-alphabet +Sort the process/prefixed groups in the group buffer alphabetically by +group name (@code{gnus-group-sort-selected-groups-by-alphabet}). + +@item G P u +@kindex G P u (Group) +@findex gnus-group-sort-selected-groups-by-unread +Sort the process/prefixed groups in the group buffer by the number of +unread articles (@code{gnus-group-sort-selected-groups-by-unread}). + +@item G P l +@kindex G P l (Group) +@findex gnus-group-sort-selected-groups-by-level +Sort the process/prefixed groups in the group buffer by group level +(@code{gnus-group-sort-selected-groups-by-level}). + +@item G P v +@kindex G P v (Group) +@findex gnus-group-sort-selected-groups-by-score +Sort the process/prefixed groups in the group buffer by group score +(@code{gnus-group-sort-selected-groups-by-score}). @xref{Group Score}. + +@item G P r +@kindex G P r (Group) +@findex gnus-group-sort-selected-groups-by-rank +Sort the process/prefixed groups in the group buffer by group rank +(@code{gnus-group-sort-selected-groups-by-rank}). @xref{Group Score}. + +@item G P m +@kindex G P m (Group) +@findex gnus-group-sort-selected-groups-by-method +Sort the process/prefixed groups in the group buffer alphabetically by +backend name (@code{gnus-group-sort-selected-groups-by-method}). + +@end table + + + +@node Group Maintenance +@section Group Maintenance +@cindex bogus groups + +@table @kbd +@item b +@kindex b (Group) +@findex gnus-group-check-bogus-groups +Find bogus groups and delete them +(@code{gnus-group-check-bogus-groups}). + +@item F +@kindex F (Group) +@findex gnus-group-find-new-groups +Find new groups and process them (@code{gnus-group-find-new-groups}). +With 1 @kbd{C-u}, use the @code{ask-server} method to query the server +for new groups. With 2 @kbd{C-u}'s, use most complete method possible +to query the server for new groups, and subscribe the new groups as +zombies. + +@item C-c C-x +@kindex C-c C-x (Group) +@findex gnus-group-expire-articles +Run all expirable articles in the current group through the expiry +process (if any) (@code{gnus-group-expire-articles}). + +@item C-c M-C-x +@kindex C-c M-C-x (Group) +@findex gnus-group-expire-all-groups +Run all articles in all groups through the expiry process +(@code{gnus-group-expire-all-groups}). + +@end table + + +@node Browse Foreign Server +@section Browse Foreign Server +@cindex foreign servers +@cindex browsing servers + +@table @kbd +@item B +@kindex B (Group) +@findex gnus-group-browse-foreign-server +You will be queried for a select method and a server name. Gnus will +then attempt to contact this server and let you browse the groups there +(@code{gnus-group-browse-foreign-server}). +@end table + +@findex gnus-browse-mode +A new buffer with a list of available groups will appear. This buffer +will use the @code{gnus-browse-mode}. This buffer looks a bit (well, +a lot) like a normal group buffer. + +Here's a list of keystrokes available in the browse mode: + +@table @kbd +@item n +@kindex n (Browse) +@findex gnus-group-next-group +Go to the next group (@code{gnus-group-next-group}). + +@item p +@kindex p (Browse) +@findex gnus-group-prev-group +Go to the previous group (@code{gnus-group-prev-group}). + +@item SPACE +@kindex SPACE (Browse) +@findex gnus-browse-read-group +Enter the current group and display the first article +(@code{gnus-browse-read-group}). + +@item RET +@kindex RET (Browse) +@findex gnus-browse-select-group +Enter the current group (@code{gnus-browse-select-group}). + +@item u +@kindex u (Browse) +@findex gnus-browse-unsubscribe-current-group +Unsubscribe to the current group, or, as will be the case here, +subscribe to it (@code{gnus-browse-unsubscribe-current-group}). + +@item l +@itemx q +@kindex q (Browse) +@kindex l (Browse) +@findex gnus-browse-exit +Exit browse mode (@code{gnus-browse-exit}). + +@item ? +@kindex ? (Browse) +@findex gnus-browse-describe-briefly +Describe browse mode briefly (well, there's not much to describe, is +there) (@code{gnus-browse-describe-briefly}). +@end table + + +@node Exiting Gnus +@section Exiting Gnus +@cindex exiting Gnus + +Yes, Gnus is ex(c)iting. + +@table @kbd +@item z +@kindex z (Group) +@findex gnus-group-suspend +Suspend Gnus (@code{gnus-group-suspend}). This doesn't really exit Gnus, +but it kills all buffers except the Group buffer. I'm not sure why this +is a gain, but then who am I to judge? + +@item q +@kindex q (Group) +@findex gnus-group-exit +@c @icon{gnus-group-exit} +Quit Gnus (@code{gnus-group-exit}). + +@item Q +@kindex Q (Group) +@findex gnus-group-quit +Quit Gnus without saving the @file{.newsrc} files (@code{gnus-group-quit}). +The dribble file will be saved, though (@pxref{Auto Save}). +@end table + +@vindex gnus-exit-gnus-hook +@vindex gnus-suspend-gnus-hook +@code{gnus-suspend-gnus-hook} is called when you suspend Gnus and +@code{gnus-exit-gnus-hook} is called when you quit Gnus, while +@code{gnus-after-exiting-gnus-hook} is called as the final item when +exiting Gnus. + +@findex gnus-unload +@cindex unloading +If you wish to completely unload Gnus and all its adherents, you can use +the @code{gnus-unload} command. This command is also very handy when +trying to customize meta-variables. + +Note: + +@quotation +Miss Lisa Cannifax, while sitting in English class, felt her feet go +numbly heavy and herself fall into a hazy trance as the boy sitting +behind her drew repeated lines with his pencil across the back of her +plastic chair. +@end quotation + + +@node Group Topics +@section Group Topics +@cindex topics + +If you read lots and lots of groups, it might be convenient to group +them hierarchically according to topics. You put your Emacs groups over +here, your sex groups over there, and the rest (what, two groups or so?) +you put in some misc section that you never bother with anyway. You can +even group the Emacs sex groups as a sub-topic to either the Emacs +groups or the sex groups---or both! Go wild! + +Here's an example: + +@example +Gnus + Emacs -- I wuw it! + 3: comp.emacs + 2: alt.religion.emacs + Naughty Emacs + 452: alt.sex.emacs + 0: comp.talk.emacs.recovery + Misc + 8: comp.binaries.fractals + 13: comp.sources.unix +@end example + +@findex gnus-topic-mode +@kindex t (Group) +To get this @emph{fab} functionality you simply turn on (ooh!) the +@code{gnus-topic} minor mode---type @kbd{t} in the group buffer. (This +is a toggling command.) + +Go ahead, just try it. I'll still be here when you get back. La de +dum... Nice tune, that... la la la... What, you're back? Yes, and now +press @kbd{l}. There. All your groups are now listed under +@samp{misc}. Doesn't that make you feel all warm and fuzzy? Hot and +bothered? + +If you want this permanently enabled, you should add that minor mode to +the hook for the group mode: + +@lisp +(add-hook 'gnus-group-mode-hook 'gnus-topic-mode) +@end lisp + +@menu +* Topic Variables:: How to customize the topics the Lisp Way. +* Topic Commands:: Interactive E-Z commands. +* Topic Sorting:: Sorting each topic individually. +* Topic Topology:: A map of the world. +* Topic Parameters:: Parameters that apply to all groups in a topic. +@end menu + + +@node Topic Variables +@subsection Topic Variables +@cindex topic variables + +Now, if you select a topic, it will fold/unfold that topic, which is +really neat, I think. + +@vindex gnus-topic-line-format +The topic lines themselves are created according to the +@code{gnus-topic-line-format} variable (@pxref{Formatting Variables}). +Valid elements are: + +@table @samp +@item i +Indentation. +@item n +Topic name. +@item v +Visibility. +@item l +Level. +@item g +Number of groups in the topic. +@item a +Number of unread articles in the topic. +@item A +Number of unread articles in the topic and all its subtopics. +@end table + +@vindex gnus-topic-indent-level +Each sub-topic (and the groups in the sub-topics) will be indented with +@code{gnus-topic-indent-level} times the topic level number of spaces. +The default is 2. + +@vindex gnus-topic-mode-hook +@code{gnus-topic-mode-hook} is called in topic minor mode buffers. + +@vindex gnus-topic-display-empty-topics +The @code{gnus-topic-display-empty-topics} says whether to display even +topics that have no unread articles in them. The default is @code{t}. + + +@node Topic Commands +@subsection Topic Commands +@cindex topic commands + +When the topic minor mode is turned on, a new @kbd{T} submap will be +available. In addition, a few of the standard keys change their +definitions slightly. + +@table @kbd + +@item T n +@kindex T n (Topic) +@findex gnus-topic-create-topic +Prompt for a new topic name and create it +(@code{gnus-topic-create-topic}). + +@item T m +@kindex T m (Topic) +@findex gnus-topic-move-group +Move the current group to some other topic +(@code{gnus-topic-move-group}). This command uses the process/prefix +convention (@pxref{Process/Prefix}). + +@item T c +@kindex T c (Topic) +@findex gnus-topic-copy-group +Copy the current group to some other topic +(@code{gnus-topic-copy-group}). This command uses the process/prefix +convention (@pxref{Process/Prefix}). + +@item T D +@kindex T D (Topic) +@findex gnus-topic-remove-group +Remove a group from the current topic (@code{gnus-topic-remove-group}). +This command is mainly useful if you have the same group in several +topics and wish to remove it from one of the topics. You may also +remove a group from all topics, but in that case, Gnus will add it to +the root topic the next time you start Gnus. In fact, all new groups +(which, naturally, don't belong to any topic) will show up in the root +topic. + +This command uses the process/prefix convention +(@pxref{Process/Prefix}). + +@item T M +@kindex T M (Topic) +@findex gnus-topic-move-matching +Move all groups that match some regular expression to a topic +(@code{gnus-topic-move-matching}). + +@item T C +@kindex T C (Topic) +@findex gnus-topic-copy-matching +Copy all groups that match some regular expression to a topic +(@code{gnus-topic-copy-matching}). + +@item T H +@kindex T H (Topic) +@findex gnus-topic-toggle-display-empty-topics +Toggle hiding empty topics +(@code{gnus-topic-toggle-display-empty-topics}). + +@item T # +@kindex T # (Topic) +@findex gnus-topic-mark-topic +Mark all groups in the current topic with the process mark +(@code{gnus-topic-mark-topic}). + +@item T M-# +@kindex T M-# (Topic) +@findex gnus-topic-unmark-topic +Remove the process mark from all groups in the current topic +(@code{gnus-topic-unmark-topic}). + +@item RET +@kindex RET (Topic) +@findex gnus-topic-select-group +@itemx SPACE +Either select a group or fold a topic (@code{gnus-topic-select-group}). +When you perform this command on a group, you'll enter the group, as +usual. When done on a topic line, the topic will be folded (if it was +visible) or unfolded (if it was folded already). So it's basically a +toggling command on topics. In addition, if you give a numerical +prefix, group on that level (and lower) will be displayed. + +@item T TAB +@itemx TAB +@kindex T TAB (Topic) +@kindex TAB (Topic) +@findex gnus-topic-indent +``Indent'' the current topic so that it becomes a sub-topic of the +previous topic (@code{gnus-topic-indent}). If given a prefix, +``un-indent'' the topic instead. + +@item M-TAB +@kindex M-TAB (Topic) +@findex gnus-topic-unindent +``Un-indent'' the current topic so that it becomes a sub-topic of the +parent of its current parent (@code{gnus-topic-unindent}). + +@item C-k +@kindex C-k (Topic) +@findex gnus-topic-kill-group +Kill a group or topic (@code{gnus-topic-kill-group}). All groups in the +topic will be removed along with the topic. + +@item C-y +@kindex C-y (Topic) +@findex gnus-topic-yank-group +Yank the previously killed group or topic +(@code{gnus-topic-yank-group}). Note that all topics will be yanked +before all groups. + +@item T r +@kindex T r (Topic) +@findex gnus-topic-rename +Rename a topic (@code{gnus-topic-rename}). + +@item T DEL +@kindex T DEL (Topic) +@findex gnus-topic-delete +Delete an empty topic (@code{gnus-topic-delete}). + +@item A T +@kindex A T (Topic) +@findex gnus-topic-list-active +List all groups that Gnus knows about in a topics-ified way +(@code{gnus-topic-list-active}). + +@item G p +@kindex G p (Topic) +@findex gnus-topic-edit-parameters +@cindex group parameters +@cindex topic parameters +@cindex parameters +Edit the topic parameters (@code{gnus-topic-edit-parameters}). +@xref{Topic Parameters}. + +@end table + + +@node Topic Sorting +@subsection Topic Sorting +@cindex topic sorting + +You can sort the groups in each topic individually with the following +commands: + + +@table @kbd +@item T S a +@kindex T S a (Topic) +@findex gnus-topic-sort-groups-by-alphabet +Sort the current topic alphabetically by group name +(@code{gnus-topic-sort-groups-by-alphabet}). + +@item T S u +@kindex T S u (Topic) +@findex gnus-topic-sort-groups-by-unread +Sort the current topic by the number of unread articles +(@code{gnus-topic-sort-groups-by-unread}). + +@item T S l +@kindex T S l (Topic) +@findex gnus-topic-sort-groups-by-level +Sort the current topic by group level +(@code{gnus-topic-sort-groups-by-level}). + +@item T S v +@kindex T S v (Topic) +@findex gnus-topic-sort-groups-by-score +Sort the current topic by group score +(@code{gnus-topic-sort-groups-by-score}). @xref{Group Score}. + +@item T S r +@kindex T S r (Topic) +@findex gnus-topic-sort-groups-by-rank +Sort the current topic by group rank +(@code{gnus-topic-sort-groups-by-rank}). @xref{Group Score}. + +@item T S m +@kindex T S m (Topic) +@findex gnus-topic-sort-groups-by-method +Sort the current topic alphabetically by backend name +(@code{gnus-topic-sort-groups-by-method}). + +@end table + +@xref{Sorting Groups}, for more information about group sorting. + + +@node Topic Topology +@subsection Topic Topology +@cindex topic topology +@cindex topology + +So, let's have a look at an example group buffer: + +@example +Gnus + Emacs -- I wuw it! + 3: comp.emacs + 2: alt.religion.emacs + Naughty Emacs + 452: alt.sex.emacs + 0: comp.talk.emacs.recovery + Misc + 8: comp.binaries.fractals + 13: comp.sources.unix +@end example + +So, here we have one top-level topic (@samp{Gnus}), two topics under +that, and one sub-topic under one of the sub-topics. (There is always +just one (1) top-level topic). This topology can be expressed as +follows: + +@lisp +(("Gnus" visible) + (("Emacs -- I wuw it!" visible) + (("Naughty Emacs" visible))) + (("Misc" visible))) +@end lisp + +@vindex gnus-topic-topology +This is in fact how the variable @code{gnus-topic-topology} would look +for the display above. That variable is saved in the @file{.newsrc.eld} +file, and shouldn't be messed with manually---unless you really want +to. Since this variable is read from the @file{.newsrc.eld} file, +setting it in any other startup files will have no effect. + +This topology shows what topics are sub-topics of what topics (right), +and which topics are visible. Two settings are currently +allowed---@code{visible} and @code{invisible}. + + +@node Topic Parameters +@subsection Topic Parameters +@cindex topic parameters + +All groups in a topic will inherit group parameters from the parent (and +ancestor) topic parameters. All valid group parameters are valid topic +parameters (@pxref{Group Parameters}). + +Group parameters (of course) override topic parameters, and topic +parameters in sub-topics override topic parameters in super-topics. You +know. Normal inheritance rules. (@dfn{Rules} is here a noun, not a +verb, although you may feel free to disagree with me here.) + +@example +Gnus + Emacs + 3: comp.emacs + 2: alt.religion.emacs + 452: alt.sex.emacs + Relief + 452: alt.sex.emacs + 0: comp.talk.emacs.recovery + Misc + 8: comp.binaries.fractals + 13: comp.sources.unix + 452: alt.sex.emacs +@end example + +The @samp{Emacs} topic has the topic parameter @code{(score-file +. "emacs.SCORE")}; the @samp{Relief} topic has the topic parameter +@code{(score-file . "relief.SCORE")}; and the @samp{Misc} topic has the +topic parameter @code{(score-file . "emacs.SCORE")}. In addition, +@* @samp{alt.religion.emacs} has the group parameter @code{(score-file +. "religion.SCORE")}. + +Now, when you enter @samp{alt.sex.emacs} in the @samp{Relief} topic, you +will get the @file{relief.SCORE} home score file. If you enter the same +group in the @samp{Emacs} topic, you'll get the @file{emacs.SCORE} home +score file. If you enter the group @samp{alt.religion.emacs}, you'll +get the @file{religion.SCORE} home score file. + +This seems rather simple and self-evident, doesn't it? Well, yes. But +there are some problems, especially with the @code{total-expiry} +parameter. Say you have a mail group in two topics; one with +@code{total-expiry} and one without. What happens when you do @kbd{M-x +gnus-expire-all-expirable-groups}? Gnus has no way of telling which one +of these topics you mean to expire articles from, so anything may +happen. In fact, I hereby declare that it is @dfn{undefined} what +happens. You just have to be careful if you do stuff like that. + + +@node Misc Group Stuff +@section Misc Group Stuff + +@menu +* Scanning New Messages:: Asking Gnus to see whether new messages have arrived. +* Group Information:: Information and help on groups and Gnus. +* Group Timestamp:: Making Gnus keep track of when you last read a group. +* File Commands:: Reading and writing the Gnus files. +@end menu + +@table @kbd + +@item ^ +@kindex ^ (Group) +@findex gnus-group-enter-server-mode +Enter the server buffer (@code{gnus-group-enter-server-mode}). +@xref{The Server Buffer}. + +@item a +@kindex a (Group) +@findex gnus-group-post-news +Post an article to a group (@code{gnus-group-post-news}). If given a +prefix, the current group name will be used as the default. + +@item m +@kindex m (Group) +@findex gnus-group-mail +Mail a message somewhere (@code{gnus-group-mail}). + +@end table + +Variables for the group buffer: + +@table @code + +@item gnus-group-mode-hook +@vindex gnus-group-mode-hook +is called after the group buffer has been +created. + +@item gnus-group-prepare-hook +@vindex gnus-group-prepare-hook +is called after the group buffer is +generated. It may be used to modify the buffer in some strange, +unnatural way. + +@item gnus-group-prepared-hook +@vindex gnus-group-prepare-hook +is called as the very last thing after the group buffer has been +generated. It may be used to move point around, for instance. + +@item gnus-permanently-visible-groups +@vindex gnus-permanently-visible-groups +Groups matching this regexp will always be listed in the group buffer, +whether they are empty or not. + +@end table + + +@node Scanning New Messages +@subsection Scanning New Messages +@cindex new messages +@cindex scanning new news + +@table @kbd + +@item g +@kindex g (Group) +@findex gnus-group-get-new-news +@c @icon{gnus-group-get-new-news} +Check the server(s) for new articles. If the numerical prefix is used, +this command will check only groups of level @var{arg} and lower +(@code{gnus-group-get-new-news}). If given a non-numerical prefix, this +command will force a total re-reading of the active file(s) from the +backend(s). + +@item M-g +@kindex M-g (Group) +@findex gnus-group-get-new-news-this-group +@vindex gnus-goto-next-group-when-activating +@c @icon{gnus-group-get-new-news-this-group} +Check whether new articles have arrived in the current group +(@code{gnus-group-get-new-news-this-group}). +@code{gnus-goto-next-group-when-activating} says whether this command is +to move point to the next group or not. It is @code{t} by default. + +@findex gnus-activate-all-groups +@cindex activating groups +@item C-c M-g +@kindex C-c M-g (Group) +Activate absolutely all groups (@code{gnus-activate-all-groups}). + +@item R +@kindex R (Group) +@cindex restarting +@findex gnus-group-restart +Restart Gnus (@code{gnus-group-restart}). This saves the @file{.newsrc} +file(s), closes the connection to all servers, clears up all run-time +Gnus variables, and then starts Gnus all over again. + +@end table + +@vindex gnus-get-new-news-hook +@code{gnus-get-new-news-hook} is run just before checking for new news. + +@vindex gnus-after-getting-new-news-hook +@code{gnus-after-getting-new-news-hook} is run after checking for new +news. + + +@node Group Information +@subsection Group Information +@cindex group information +@cindex information on groups + +@table @kbd + + +@item H f +@kindex H f (Group) +@findex gnus-group-fetch-faq +@vindex gnus-group-faq-directory +@cindex FAQ +@cindex ange-ftp +Try to fetch the FAQ for the current group +(@code{gnus-group-fetch-faq}). Gnus will try to get the FAQ from +@code{gnus-group-faq-directory}, which is usually a directory on a +remote machine. This variable can also be a list of directories. In +that case, giving a prefix to this command will allow you to choose +between the various sites. @code{ange-ftp} (or @code{efs}) will be used +for fetching the file. + +If fetching from the first site is unsuccessful, Gnus will attempt to go +through @code{gnus-group-faq-directory} and try to open them one by one. + +@item H d +@itemx C-c C-d +@c @icon{gnus-group-describe-group} +@kindex H d (Group) +@kindex C-c C-d (Group) +@cindex describing groups +@cindex group description +@findex gnus-group-describe-group +Describe the current group (@code{gnus-group-describe-group}). If given +a prefix, force Gnus to re-read the description from the server. + +@item M-d +@kindex M-d (Group) +@findex gnus-group-describe-all-groups +Describe all groups (@code{gnus-group-describe-all-groups}). If given a +prefix, force Gnus to re-read the description file from the server. + +@item H v +@itemx V +@kindex V (Group) +@kindex H v (Group) +@cindex version +@findex gnus-version +Display current Gnus version numbers (@code{gnus-version}). + +@item ? +@kindex ? (Group) +@findex gnus-group-describe-briefly +Give a very short help message (@code{gnus-group-describe-briefly}). + +@item C-c C-i +@kindex C-c C-i (Group) +@cindex info +@cindex manual +@findex gnus-info-find-node +Go to the Gnus info node (@code{gnus-info-find-node}). +@end table + + +@node Group Timestamp +@subsection Group Timestamp +@cindex timestamps +@cindex group timestamps + +It can be convenient to let Gnus keep track of when you last read a +group. To set the ball rolling, you should add +@code{gnus-group-set-timestamp} to @code{gnus-select-group-hook}: + +@lisp +(add-hook 'gnus-select-group-hook 'gnus-group-set-timestamp) +@end lisp + +After doing this, each time you enter a group, it'll be recorded. + +This information can be displayed in various ways---the easiest is to +use the @samp{%d} spec in the group line format: + +@lisp +(setq gnus-group-line-format + "%M\%S\%p\%P\%5y: %(%-40,40g%) %d\n") +@end lisp + +This will result in lines looking like: + +@example +* 0: mail.ding 19961002T012943 + 0: custom 19961002T012713 +@end example + +As you can see, the date is displayed in compact ISO 8601 format. This +may be a bit too much, so to just display the date, you could say +something like: + +@lisp +(setq gnus-group-line-format + "%M\%S\%p\%P\%5y: %(%-40,40g%) %6,6~(cut 2)d\n") +@end lisp + + +@node File Commands +@subsection File Commands +@cindex file commands + +@table @kbd + +@item r +@kindex r (Group) +@findex gnus-group-read-init-file +@vindex gnus-init-file +@cindex reading init file +Re-read the init file (@code{gnus-init-file}, which defaults to +@file{~/.gnus}) (@code{gnus-group-read-init-file}). + +@item s +@kindex s (Group) +@findex gnus-group-save-newsrc +@cindex saving .newsrc +Save the @file{.newsrc.eld} file (and @file{.newsrc} if wanted) +(@code{gnus-group-save-newsrc}). If given a prefix, force saving the +file(s) whether Gnus thinks it is necessary or not. + +@c @item Z +@c @kindex Z (Group) +@c @findex gnus-group-clear-dribble +@c Clear the dribble buffer (@code{gnus-group-clear-dribble}). + +@end table + + +@node The Summary Buffer +@chapter The Summary Buffer +@cindex summary buffer + +A line for each article is displayed in the summary buffer. You can +move around, read articles, post articles and reply to articles. + +The most common way to a summary buffer is to select a group from the +group buffer (@pxref{Selecting a Group}). + +You can have as many summary buffers open as you wish. + +@menu +* Summary Buffer Format:: Deciding how the summary buffer is to look. +* Summary Maneuvering:: Moving around the summary buffer. +* Choosing Articles:: Reading articles. +* Paging the Article:: Scrolling the current article. +* Reply Followup and Post:: Posting articles. +* Canceling and Superseding:: ``Whoops, I shouldn't have called him that.'' +* Marking Articles:: Marking articles as read, expirable, etc. +* Limiting:: You can limit the summary buffer. +* Threading:: How threads are made. +* Sorting:: How articles and threads are sorted. +* Asynchronous Fetching:: Gnus might be able to pre-fetch articles. +* Article Caching:: You may store articles in a cache. +* Persistent Articles:: Making articles expiry-resistant. +* Article Backlog:: Having already read articles hang around. +* Saving Articles:: Ways of customizing article saving. +* Decoding Articles:: Gnus can treat series of (uu)encoded articles. +* Article Treatment:: The article buffer can be mangled at will. +* Article Commands:: Doing various things with the article buffer. +* Summary Sorting:: Sorting the summary buffer in various ways. +* Finding the Parent:: No child support? Get the parent. +* Alternative Approaches:: Reading using non-default summaries. +* Tree Display:: A more visual display of threads. +* Mail Group Commands:: Some commands can only be used in mail groups. +* Various Summary Stuff:: What didn't fit anywhere else. +* Exiting the Summary Buffer:: Returning to the Group buffer. +* Crosspost Handling:: How crossposted articles are dealt with. +* Duplicate Suppression:: An alternative when crosspost handling fails. +@end menu + + +@node Summary Buffer Format +@section Summary Buffer Format +@cindex summary buffer format + +@menu +* Summary Buffer Lines:: You can specify how summary lines should look. +* Summary Buffer Mode Line:: You can say how the mode line should look. +* Summary Highlighting:: Making the summary buffer all pretty and nice. +@end menu + +@findex mail-extract-address-components +@findex gnus-extract-address-components +@vindex gnus-extract-address-components +Gnus will use the value of the @code{gnus-extract-address-components} +variable as a function for getting the name and address parts of a +@code{From} header. Two pre-defined functions exist: +@code{gnus-extract-address-components}, which is the default, quite +fast, and too simplistic solution; and +@code{mail-extract-address-components}, which works very nicely, but is +slower. The default function will return the wrong answer in 5% of the +cases. If this is unacceptable to you, use the other function instead. + +@vindex gnus-summary-same-subject +@code{gnus-summary-same-subject} is a string indicating that the current +article has the same subject as the previous. This string will be used +with those specs that require it. The default is @code{""}. + + +@node Summary Buffer Lines +@subsection Summary Buffer Lines + +@vindex gnus-summary-line-format +You can change the format of the lines in the summary buffer by changing +the @code{gnus-summary-line-format} variable. It works along the same +lines as a normal @code{format} string, with some extensions +(@pxref{Formatting Variables}). + +The default string is @samp{%U%R%z%I%(%[%4L: %-20,20n%]%) %s\n}. + +The following format specification characters are understood: + +@table @samp +@item N +Article number. +@item S +Subject string. +@item s +Subject if the article is the root of the thread or the previous article +had a different subject, @code{gnus-summary-same-subject} otherwise. +(@code{gnus-summary-same-subject} defaults to @code{""}.) +@item F +Full @code{From} header. +@item n +The name (from the @code{From} header). +@item a +The name (from the @code{From} header). This differs from the @code{n} +spec in that it uses the function designated by the +@code{gnus-extract-address-components} variable, which is slower, but +may be more thorough. +@item A +The address (from the @code{From} header). This works the same way as +the @code{a} spec. +@item L +Number of lines in the article. +@item c +Number of characters in the article. +@item I +Indentation based on thread level (@pxref{Customizing Threading}). +@item T +Nothing if the article is a root and lots of spaces if it isn't (it +pushes everything after it off the screen). +@item [ +Opening bracket, which is normally @samp{[}, but can also be @samp{<} +for adopted articles (@pxref{Customizing Threading}). +@item ] +Closing bracket, which is normally @samp{]}, but can also be @samp{>} +for adopted articles. +@item > +One space for each thread level. +@item < +Twenty minus thread level spaces. +@item U +Unread. + +@item R +This misleadingly named specifier is the @dfn{secondary mark}. This +mark will say whether the article has been replied to, has been cached, +or has been saved. + +@item i +Score as a number (@pxref{Scoring}). +@item z +@vindex gnus-summary-zcore-fuzz +Zcore, @samp{+} if above the default level and @samp{-} if below the +default level. If the difference between +@code{gnus-summary-default-score} and the score is less than +@code{gnus-summary-zcore-fuzz}, this spec will not be used. +@item V +Total thread score. +@item x +@code{Xref}. +@item D +@code{Date}. +@item d +The @code{Date} in @code{DD-MMM} format. +@item o +The @code{Date} in @var{YYYYMMDD}@code{T}@var{HHMMSS} format. +@item M +@code{Message-ID}. +@item r +@code{References}. +@item t +Number of articles in the current sub-thread. Using this spec will slow +down summary buffer generation somewhat. +@item e +An @samp{=} (@code{gnus-not-empty-thread-mark}) will be displayed if the +article has any children. +@item P +The line number. +@item O +Download mark. +@item u +User defined specifier. The next character in the format string should +be a letter. Gnus will call the function +@code{gnus-user-format-function-}@samp{X}, where @samp{X} is the letter +following @samp{%u}. The function will be passed the current header as +argument. The function should return a string, which will be inserted +into the summary just like information from any other summary specifier. +@end table + +The @samp{%U} (status), @samp{%R} (replied) and @samp{%z} (zcore) specs +have to be handled with care. For reasons of efficiency, Gnus will +compute what column these characters will end up in, and ``hard-code'' +that. This means that it is invalid to have these specs after a +variable-length spec. Well, you might not be arrested, but your summary +buffer will look strange, which is bad enough. + +The smart choice is to have these specs as far to the left as possible. +(Isn't that the case with everything, though? But I digress.) + +This restriction may disappear in later versions of Gnus. + + +@node Summary Buffer Mode Line +@subsection Summary Buffer Mode Line + +@vindex gnus-summary-mode-line-format +You can also change the format of the summary mode bar (@pxref{Mode Line +Formatting}). Set @code{gnus-summary-mode-line-format} to whatever you +like. The default is @samp{Gnus: %%b [%A] %Z}. + +Here are the elements you can play with: + +@table @samp +@item G +Group name. +@item p +Unprefixed group name. +@item A +Current article number. +@item z +Current article score. +@item V +Gnus version. +@item U +Number of unread articles in this group. +@item e +Number of unread articles in this group that aren't displayed in the +summary buffer. +@item Z +A string with the number of unread and unselected articles represented +either as @samp{<%U(+%e) more>} if there are both unread and unselected +articles, and just as @samp{<%U more>} if there are just unread articles +and no unselected ones. +@item g +Shortish group name. For instance, @samp{rec.arts.anime} will be +shortened to @samp{r.a.anime}. +@item S +Subject of the current article. +@item u +User-defined spec (@pxref{User-Defined Specs}). +@item s +Name of the current score file (@pxref{Scoring}). +@item d +Number of dormant articles (@pxref{Unread Articles}). +@item t +Number of ticked articles (@pxref{Unread Articles}). +@item r +Number of articles that have been marked as read in this session. +@item E +Number of articles expunged by the score files. +@end table + + +@node Summary Highlighting +@subsection Summary Highlighting + +@table @code + +@item gnus-visual-mark-article-hook +@vindex gnus-visual-mark-article-hook +This hook is run after selecting an article. It is meant to be used for +highlighting the article in some way. It is not run if +@code{gnus-visual} is @code{nil}. + +@item gnus-summary-update-hook +@vindex gnus-summary-update-hook +This hook is called when a summary line is changed. It is not run if +@code{gnus-visual} is @code{nil}. + +@item gnus-summary-selected-face +@vindex gnus-summary-selected-face +This is the face (or @dfn{font} as some people call it) used to +highlight the current article in the summary buffer. + +@item gnus-summary-highlight +@vindex gnus-summary-highlight +Summary lines are highlighted according to this variable, which is a +list where the elements are of the format @var{(FORM . FACE)}. If you +would, for instance, like ticked articles to be italic and high-scored +articles to be bold, you could set this variable to something like +@lisp +(((eq mark gnus-ticked-mark) . italic) + ((> score default) . bold)) +@end lisp +As you may have guessed, if @var{FORM} returns a non-@code{nil} value, +@var{FACE} will be applied to the line. +@end table + + +@node Summary Maneuvering +@section Summary Maneuvering +@cindex summary movement + +All the straight movement commands understand the numeric prefix and +behave pretty much as you'd expect. + +None of these commands select articles. + +@table @kbd +@item G M-n +@itemx M-n +@kindex M-n (Summary) +@kindex G M-n (Summary) +@findex gnus-summary-next-unread-subject +Go to the next summary line of an unread article +(@code{gnus-summary-next-unread-subject}). + +@item G M-p +@itemx M-p +@kindex M-p (Summary) +@kindex G M-p (Summary) +@findex gnus-summary-prev-unread-subject +Go to the previous summary line of an unread article +(@code{gnus-summary-prev-unread-subject}). + +@item G j +@itemx j +@kindex j (Summary) +@kindex G j (Summary) +@findex gnus-summary-goto-article +Ask for an article number or @code{Message-ID}, and then go to that +article (@code{gnus-summary-goto-article}). + +@item G g +@kindex G g (Summary) +@findex gnus-summary-goto-subject +Ask for an article number and then go to the summary line of that article +without displaying the article (@code{gnus-summary-goto-subject}). +@end table + +If Gnus asks you to press a key to confirm going to the next group, you +can use the @kbd{C-n} and @kbd{C-p} keys to move around the group +buffer, searching for the next group to read without actually returning +to the group buffer. + +Variables related to summary movement: + +@table @code + +@vindex gnus-auto-select-next +@item gnus-auto-select-next +If you issue one of the movement commands (like @kbd{n}) and there are +no more unread articles after the current one, Gnus will offer to go to +the next group. If this variable is @code{t} and the next group is +empty, Gnus will exit summary mode and return to the group buffer. If +this variable is neither @code{t} nor @code{nil}, Gnus will select the +next group, no matter whether it has any unread articles or not. As a +special case, if this variable is @code{quietly}, Gnus will select the +next group without asking for confirmation. If this variable is +@code{almost-quietly}, the same will happen only if you are located on +the last article in the group. Finally, if this variable is +@code{slightly-quietly}, the @kbd{Z n} command will go to the next group +without confirmation. Also @pxref{Group Levels}. + +@item gnus-auto-select-same +@vindex gnus-auto-select-same +If non-@code{nil}, all the movement commands will try to go to the next +article with the same subject as the current. (@dfn{Same} here might +mean @dfn{roughly equal}. See @code{gnus-summary-gather-subject-limit} +for details (@pxref{Customizing Threading}).) If there are no more +articles with the same subject, go to the first unread article. + +This variable is not particularly useful if you use a threaded display. + +@item gnus-summary-check-current +@vindex gnus-summary-check-current +If non-@code{nil}, all the ``unread'' movement commands will not proceed +to the next (or previous) article if the current article is unread. +Instead, they will choose the current article. + +@item gnus-auto-center-summary +@vindex gnus-auto-center-summary +If non-@code{nil}, Gnus will keep the point in the summary buffer +centered at all times. This makes things quite tidy, but if you have a +slow network connection, or simply do not like this un-Emacsism, you can +set this variable to @code{nil} to get the normal Emacs scrolling +action. This will also inhibit horizontal re-centering of the summary +buffer, which might make it more inconvenient to read extremely long +threads. + +@end table + + +@node Choosing Articles +@section Choosing Articles +@cindex selecting articles + +@menu +* Choosing Commands:: Commands for choosing articles. +* Choosing Variables:: Variables that influence these commands. +@end menu + + +@node Choosing Commands +@subsection Choosing Commands + +None of the following movement commands understand the numeric prefix, +and they all select and display an article. + +@table @kbd +@item SPACE +@kindex SPACE (Summary) +@findex gnus-summary-next-page +Select the current article, or, if that one's read already, the next +unread article (@code{gnus-summary-next-page}). + +@item G n +@itemx n +@kindex n (Summary) +@kindex G n (Summary) +@findex gnus-summary-next-unread-article +@c @icon{gnus-summary-next-unread} +Go to next unread article (@code{gnus-summary-next-unread-article}). + +@item G p +@itemx p +@kindex p (Summary) +@findex gnus-summary-prev-unread-article +@c @icon{gnus-summary-prev-unread} +Go to previous unread article (@code{gnus-summary-prev-unread-article}). + +@item G N +@itemx N +@kindex N (Summary) +@kindex G N (Summary) +@findex gnus-summary-next-article +Go to the next article (@code{gnus-summary-next-article}). + +@item G P +@itemx P +@kindex P (Summary) +@kindex G P (Summary) +@findex gnus-summary-prev-article +Go to the previous article (@code{gnus-summary-prev-article}). + +@item G C-n +@kindex G C-n (Summary) +@findex gnus-summary-next-same-subject +Go to the next article with the same subject +(@code{gnus-summary-next-same-subject}). + +@item G C-p +@kindex G C-p (Summary) +@findex gnus-summary-prev-same-subject +Go to the previous article with the same subject +(@code{gnus-summary-prev-same-subject}). + +@item G f +@itemx . +@kindex G f (Summary) +@kindex . (Summary) +@findex gnus-summary-first-unread-article +Go to the first unread article +(@code{gnus-summary-first-unread-article}). + +@item G b +@itemx , +@kindex G b (Summary) +@kindex , (Summary) +@findex gnus-summary-best-unread-article +Go to the article with the highest score +(@code{gnus-summary-best-unread-article}). + +@item G l +@itemx l +@kindex l (Summary) +@kindex G l (Summary) +@findex gnus-summary-goto-last-article +Go to the previous article read (@code{gnus-summary-goto-last-article}). + +@item G o +@kindex G o (Summary) +@findex gnus-summary-pop-article +@cindex history +@cindex article history +Pop an article off the summary history and go to this article +(@code{gnus-summary-pop-article}). This command differs from the +command above in that you can pop as many previous articles off the +history as you like, while @kbd{l} toggles the two last read articles. +For a somewhat related issue (if you use these commands a lot), +@pxref{Article Backlog}. +@end table + + +@node Choosing Variables +@subsection Choosing Variables + +Some variables relevant for moving and selecting articles: + +@table @code +@item gnus-auto-extend-newsgroup +@vindex gnus-auto-extend-newsgroup +All the movement commands will try to go to the previous (or next) +article, even if that article isn't displayed in the Summary buffer if +this variable is non-@code{nil}. Gnus will then fetch the article from +the server and display it in the article buffer. + +@item gnus-select-article-hook +@vindex gnus-select-article-hook +This hook is called whenever an article is selected. By default it +exposes any threads hidden under the selected article. + +@item gnus-mark-article-hook +@vindex gnus-mark-article-hook +@findex gnus-summary-mark-unread-as-read +@findex gnus-summary-mark-read-and-unread-as-read +@findex gnus-unread-mark +This hook is called whenever an article is selected. It is intended to +be used for marking articles as read. The default value is +@code{gnus-summary-mark-read-and-unread-as-read}, and will change the +mark of almost any article you read to @code{gnus-unread-mark}. The +only articles not affected by this function are ticked, dormant, and +expirable articles. If you'd instead like to just have unread articles +marked as read, you can use @code{gnus-summary-mark-unread-as-read} +instead. It will leave marks like @code{gnus-low-score-mark}, +@code{gnus-del-mark} (and so on) alone. + +@end table + + +@node Paging the Article +@section Scrolling the Article +@cindex article scrolling + +@table @kbd + +@item SPACE +@kindex SPACE (Summary) +@findex gnus-summary-next-page +Pressing @kbd{SPACE} will scroll the current article forward one page, +or, if you have come to the end of the current article, will choose the +next article (@code{gnus-summary-next-page}). + +@item DEL +@kindex DEL (Summary) +@findex gnus-summary-prev-page +Scroll the current article back one page (@code{gnus-summary-prev-page}). + +@item RET +@kindex RET (Summary) +@findex gnus-summary-scroll-up +Scroll the current article one line forward +(@code{gnus-summary-scroll-up}). + +@item M-RET +@kindex M-RET (Summary) +@findex gnus-summary-scroll-down +Scroll the current article one line backward +(@code{gnus-summary-scroll-down}). + +@item A g +@itemx g +@kindex A g (Summary) +@kindex g (Summary) +@findex gnus-summary-show-article +(Re)fetch the current article (@code{gnus-summary-show-article}). If +given a prefix, fetch the current article, but don't run any of the +article treatment functions. This will give you a ``raw'' article, just +the way it came from the server. + +@item A < +@itemx < +@kindex < (Summary) +@kindex A < (Summary) +@findex gnus-summary-beginning-of-article +Scroll to the beginning of the article +(@code{gnus-summary-beginning-of-article}). + +@item A > +@itemx > +@kindex > (Summary) +@kindex A > (Summary) +@findex gnus-summary-end-of-article +Scroll to the end of the article (@code{gnus-summary-end-of-article}). + +@item A s +@itemx s +@kindex A s (Summary) +@kindex s (Summary) +@findex gnus-summary-isearch-article +Perform an isearch in the article buffer +(@code{gnus-summary-isearch-article}). + +@item h +@kindex h (Summary) +@findex gnus-summary-select-article-buffer +Select the article buffer (@code{gnus-summary-select-article-buffer}). + +@end table + + +@node Reply Followup and Post +@section Reply, Followup and Post + +@menu +* Summary Mail Commands:: Sending mail. +* Summary Post Commands:: Sending news. +@end menu + + +@node Summary Mail Commands +@subsection Summary Mail Commands +@cindex mail +@cindex composing mail + +Commands for composing a mail message: + +@table @kbd + +@item S r +@itemx r +@kindex S r (Summary) +@kindex r (Summary) +@findex gnus-summary-reply +@c @icon{gnus-summary-mail-reply} +@c @icon{gnus-summary-reply} +Mail a reply to the author of the current article +(@code{gnus-summary-reply}). + +@item S R +@itemx R +@kindex R (Summary) +@kindex S R (Summary) +@findex gnus-summary-reply-with-original +@c @icon{gnus-summary-reply-with-original} +Mail a reply to the author of the current article and include the +original message (@code{gnus-summary-reply-with-original}). This +command uses the process/prefix convention. + +@item S w +@kindex S w (Summary) +@findex gnus-summary-wide-reply +Mail a wide reply to the author of the current article +(@code{gnus-summary-wide-reply}). A @dfn{wide reply} is a reply that +goes out to all people listed in the @code{To}, @code{From} (or +@code{Reply-to}) and @code{Cc} headers. + +@item S W +@kindex S W (Summary) +@findex gnus-summary-wide-reply-with-original +Mail a wide reply to the current article and include the original +message (@code{gnus-summary-reply-with-original}). This command uses +the process/prefix convention. + +@item S o m +@kindex S o m (Summary) +@findex gnus-summary-mail-forward +@c @icon{gnus-summary-mail-forward} +Forward the current article to some other person +(@code{gnus-summary-mail-forward}). If given a prefix, include the full +headers of the forwarded article. + +@item S m +@itemx m +@kindex m (Summary) +@kindex S m (Summary) +@findex gnus-summary-mail-other-window +@c @icon{gnus-summary-mail-originate} +Send a mail to some other person +(@code{gnus-summary-mail-other-window}). + +@item S D b +@kindex S D b (Summary) +@findex gnus-summary-resend-bounced-mail +@cindex bouncing mail +If you have sent a mail, but the mail was bounced back to you for some +reason (wrong address, transient failure), you can use this command to +resend that bounced mail (@code{gnus-summary-resend-bounced-mail}). You +will be popped into a mail buffer where you can edit the headers before +sending the mail off again. If you give a prefix to this command, and +the bounced mail is a reply to some other mail, Gnus will try to fetch +that mail and display it for easy perusal of its headers. This might +very well fail, though. + +@item S D r +@kindex S D r (Summary) +@findex gnus-summary-resend-message +Not to be confused with the previous command, +@code{gnus-summary-resend-message} will prompt you for an address to +send the current message off to, and then send it to that place. The +headers of the message won't be altered---but lots of headers that say +@code{Resent-To}, @code{Resent-From} and so on will be added. This +means that you actually send a mail to someone that has a @code{To} +header that (probably) points to yourself. This will confuse people. +So, natcherly you'll only do that if you're really eVIl. + +This command is mainly used if you have several accounts and want to +ship a mail to a different account of yours. (If you're both +@code{root} and @code{postmaster} and get a mail for @code{postmaster} +to the @code{root} account, you may want to resend it to +@code{postmaster}. Ordnung muß sein! + +This command understands the process/prefix convention +(@pxref{Process/Prefix}). + +@item S O m +@kindex S O m (Summary) +@findex gnus-uu-digest-mail-forward +Digest the current series (@pxref{Decoding Articles}) and forward the +result using mail (@code{gnus-uu-digest-mail-forward}). This command +uses the process/prefix convention (@pxref{Process/Prefix}). + +@item S M-c +@kindex S M-c (Summary) +@findex gnus-summary-mail-crosspost-complaint +@cindex crossposting +@cindex excessive crossposting +Send a complaint about excessive crossposting to the author of the +current article (@code{gnus-summary-mail-crosspost-complaint}). + +@findex gnus-crosspost-complaint +This command is provided as a way to fight back against the current +crossposting pandemic that's sweeping Usenet. It will compose a reply +using the @code{gnus-crosspost-complaint} variable as a preamble. This +command understands the process/prefix convention +(@pxref{Process/Prefix}) and will prompt you before sending each mail. + +@end table + +Also @pxref{(message)Header Commands} for more information. + + +@node Summary Post Commands +@subsection Summary Post Commands +@cindex post +@cindex composing news + +Commands for posting a news article: + +@table @kbd +@item S p +@itemx a +@kindex a (Summary) +@kindex S p (Summary) +@findex gnus-summary-post-news +@c @icon{gnus-summary-post-news} +Post an article to the current group +(@code{gnus-summary-post-news}). + +@item S f +@itemx f +@kindex f (Summary) +@kindex S f (Summary) +@findex gnus-summary-followup +@c @icon{gnus-summary-followup} +Post a followup to the current article (@code{gnus-summary-followup}). + +@item S F +@itemx F +@kindex S F (Summary) +@kindex F (Summary) +@c @icon{gnus-summary-followup-with-original} +@findex gnus-summary-followup-with-original +Post a followup to the current article and include the original message +(@code{gnus-summary-followup-with-original}). This command uses the +process/prefix convention. + +@item S n +@kindex S n (Summary) +@findex gnus-summary-followup-to-mail +Post a followup to the current article via news, even if you got the +message through mail (@code{gnus-summary-followup-to-mail}). + +@item S N +@kindex S N (Summary) +@findex gnus-summary-followup-to-mail-with-original +Post a followup to the current article via news, even if you got the +message through mail and include the original message +(@code{gnus-summary-followup-to-mail-with-original}). This command uses +the process/prefix convention. + +@item S o p +@kindex S o p (Summary) +@findex gnus-summary-post-forward +Forward the current article to a newsgroup +(@code{gnus-summary-post-forward}). If given a prefix, include the full +headers of the forwarded article. + +@item S O p +@kindex S O p (Summary) +@findex gnus-uu-digest-post-forward +@cindex digests +@cindex making digests +Digest the current series and forward the result to a newsgroup +(@code{gnus-uu-digest-mail-forward}). This command uses the +process/prefix convention. + +@item S u +@kindex S u (Summary) +@findex gnus-uu-post-news +@c @icon{gnus-uu-post-news} +Uuencode a file, split it into parts, and post it as a series +(@code{gnus-uu-post-news}). (@pxref{Uuencoding and Posting}). +@end table + +Also @pxref{(message)Header Commands} for more information. + + +@node Canceling and Superseding +@section Canceling Articles +@cindex canceling articles +@cindex superseding articles + +Have you ever written something, and then decided that you really, +really, really wish you hadn't posted that? + +Well, you can't cancel mail, but you can cancel posts. + +@findex gnus-summary-cancel-article +@kindex C (Summary) +@c @icon{gnus-summary-cancel-article} +Find the article you wish to cancel (you can only cancel your own +articles, so don't try any funny stuff). Then press @kbd{C} or @kbd{S +c} (@code{gnus-summary-cancel-article}). Your article will be +canceled---machines all over the world will be deleting your article. +This command uses the process/prefix convention (@pxref{Process/Prefix}). + +Be aware, however, that not all sites honor cancels, so your article may +live on here and there, while most sites will delete the article in +question. + +Gnus will use the ``current'' select method when canceling. If you +want to use the standard posting method, use the @samp{a} symbolic +prefix (@pxref{Symbolic Prefixes}). + +If you discover that you have made some mistakes and want to do some +corrections, you can post a @dfn{superseding} article that will replace +your original article. + +@findex gnus-summary-supersede-article +@kindex S (Summary) +Go to the original article and press @kbd{S s} +(@code{gnus-summary-supersede-article}). You will be put in a buffer +where you can edit the article all you want before sending it off the +usual way. + +The same goes for superseding as for canceling, only more so: Some +sites do not honor superseding. On those sites, it will appear that you +have posted almost the same article twice. + +If you have just posted the article, and change your mind right away, +there is a trick you can use to cancel/supersede the article without +waiting for the article to appear on your site first. You simply return +to the post buffer (which is called @code{*sent ...*}). There you will +find the article you just posted, with all the headers intact. Change +the @code{Message-ID} header to a @code{Cancel} or @code{Supersedes} +header by substituting one of those words for the word +@code{Message-ID}. Then just press @kbd{C-c C-c} to send the article as +you would do normally. The previous article will be +canceled/superseded. + +Just remember, kids: There is no 'c' in 'supersede'. + + +@node Marking Articles +@section Marking Articles +@cindex article marking +@cindex article ticking +@cindex marks + +There are several marks you can set on an article. + +You have marks that decide the @dfn{readedness} (whoo, neato-keano +neologism ohoy!) of the article. Alphabetic marks generally mean +@dfn{read}, while non-alphabetic characters generally mean @dfn{unread}. + +In addition, you also have marks that do not affect readedness. + +@menu +* Unread Articles:: Marks for unread articles. +* Read Articles:: Marks for read articles. +* Other Marks:: Marks that do not affect readedness. +@end menu + +@ifinfo +There's a plethora of commands for manipulating these marks: +@end ifinfo + +@menu +* Setting Marks:: How to set and remove marks. +* Setting Process Marks:: How to mark articles for later processing. +@end menu + + +@node Unread Articles +@subsection Unread Articles + +The following marks mark articles as (kinda) unread, in one form or +other. + +@table @samp +@item ! +@vindex gnus-ticked-mark +Marked as ticked (@code{gnus-ticked-mark}). + +@dfn{Ticked articles} are articles that will remain visible always. If +you see an article that you find interesting, or you want to put off +reading it, or replying to it, until sometime later, you'd typically +tick it. However, articles can be expired, so if you want to keep an +article forever, you'll have to make it persistent (@pxref{Persistent +Articles}). + +@item ? +@vindex gnus-dormant-mark +Marked as dormant (@code{gnus-dormant-mark}). + +@dfn{Dormant articles} will only appear in the summary buffer if there +are followups to it. If you want to see them even if they don't have +followups, you can use the @kbd{/ D} command (@pxref{Limiting}). + +@item SPACE +@vindex gnus-unread-mark +Marked as unread (@code{gnus-unread-mark}). + +@dfn{Unread articles} are articles that haven't been read at all yet. +@end table + + +@node Read Articles +@subsection Read Articles +@cindex expirable mark + +All the following marks mark articles as read. + +@table @samp + +@item r +@vindex gnus-del-mark +These are articles that the user has marked as read with the @kbd{d} +command manually, more or less (@code{gnus-del-mark}). + +@item R +@vindex gnus-read-mark +Articles that have actually been read (@code{gnus-read-mark}). + +@item O +@vindex gnus-ancient-mark +Articles that were marked as read in previous sessions and are now +@dfn{old} (@code{gnus-ancient-mark}). + +@item K +@vindex gnus-killed-mark +Marked as killed (@code{gnus-killed-mark}). + +@item X +@vindex gnus-kill-file-mark +Marked as killed by kill files (@code{gnus-kill-file-mark}). + +@item Y +@vindex gnus-low-score-mark +Marked as read by having too low a score (@code{gnus-low-score-mark}). + +@item C +@vindex gnus-catchup-mark +Marked as read by a catchup (@code{gnus-catchup-mark}). + +@item G +@vindex gnus-canceled-mark +Canceled article (@code{gnus-canceled-mark}) + +@item F +@vindex gnus-souped-mark +@sc{SOUP}ed article (@code{gnus-souped-mark}). @xref{SOUP}. + +@item Q +@vindex gnus-sparse-mark +Sparsely reffed article (@code{gnus-sparse-mark}). @xref{Customizing +Threading}. + +@item M +@vindex gnus-duplicate-mark +Article marked as read by duplicate suppression +(@code{gnus-duplicated-mark}). @xref{Duplicate Suppression}. + +@end table + +All these marks just mean that the article is marked as read, really. +They are interpreted differently when doing adaptive scoring, though. + +One more special mark, though: + +@table @samp +@item E +@vindex gnus-expirable-mark +Marked as expirable (@code{gnus-expirable-mark}). + +Marking articles as @dfn{expirable} (or have them marked as such +automatically) doesn't make much sense in normal groups---a user doesn't +control expiring of news articles, but in mail groups, for instance, +articles marked as @dfn{expirable} can be deleted by Gnus at +any time. +@end table + + +@node Other Marks +@subsection Other Marks +@cindex process mark +@cindex bookmarks + +There are some marks that have nothing to do with whether the article is +read or not. + +@itemize @bullet + +@item +You can set a bookmark in the current article. Say you are reading a +long thesis on cats' urinary tracts, and have to go home for dinner +before you've finished reading the thesis. You can then set a bookmark +in the article, and Gnus will jump to this bookmark the next time it +encounters the article. @xref{Setting Marks}. + +@item +@vindex gnus-replied-mark +All articles that you have replied to or made a followup to (i.e., have +answered) will be marked with an @samp{A} in the second column +(@code{gnus-replied-mark}). + +@item +@vindex gnus-cached-mark +Articles stored in the article cache will be marked with an @samp{*} in +the second column (@code{gnus-cached-mark}). @xref{Article Caching}. + +@item +@vindex gnus-saved-mark +Articles ``saved'' (in some manner or other; not necessarily +religiously) are marked with an @samp{S} in the second column +(@code{gnus-saved-mark}). + +@item +@vindex gnus-not-empty-thread-mark +@vindex gnus-empty-thread-mark +If the @samp{%e} spec is used, the presence of threads or not will be +marked with @code{gnus-not-empty-thread-mark} and +@code{gnus-empty-thread-mark} in the third column, respectively. + +@item +@vindex gnus-process-mark +Finally we have the @dfn{process mark} (@code{gnus-process-mark}). A +variety of commands react to the presence of the process mark. For +instance, @kbd{X u} (@code{gnus-uu-decode-uu}) will uudecode and view +all articles that have been marked with the process mark. Articles +marked with the process mark have a @samp{#} in the second column. + +@end itemize + +You might have noticed that most of these ``non-readedness'' marks +appear in the second column by default. So if you have a cached, saved, +replied article that you have process-marked, what will that look like? + +Nothing much. The precedence rules go as follows: process -> cache -> +replied -> saved. So if the article is in the cache and is replied, +you'll only see the cache mark and not the replied mark. + + +@node Setting Marks +@subsection Setting Marks +@cindex setting marks + +All the marking commands understand the numeric prefix. + +@table @kbd +@item M c +@itemx M-u +@kindex M c (Summary) +@kindex M-u (Summary) +@findex gnus-summary-clear-mark-forward +@cindex mark as unread +Clear all readedness-marks from the current article +(@code{gnus-summary-clear-mark-forward}). In other words, mark the +article as unread. + +@item M t +@itemx ! +@kindex ! (Summary) +@kindex M t (Summary) +@findex gnus-summary-tick-article-forward +Tick the current article (@code{gnus-summary-tick-article-forward}). +@xref{Article Caching}. + +@item M ? +@itemx ? +@kindex ? (Summary) +@kindex M ? (Summary) +@findex gnus-summary-mark-as-dormant +Mark the current article as dormant +(@code{gnus-summary-mark-as-dormant}). @xref{Article Caching}. + +@item M d +@itemx d +@kindex M d (Summary) +@kindex d (Summary) +@findex gnus-summary-mark-as-read-forward +Mark the current article as read +(@code{gnus-summary-mark-as-read-forward}). + +@item D +@kindex D (Summary) +@findex gnus-summary-mark-as-read-backward +Mark the current article as read and move point to the previous line +(@code{gnus-summary-mark-as-read-backward}). + +@item M k +@itemx k +@kindex k (Summary) +@kindex M k (Summary) +@findex gnus-summary-kill-same-subject-and-select +Mark all articles that have the same subject as the current one as read, +and then select the next unread article +(@code{gnus-summary-kill-same-subject-and-select}). + +@item M K +@itemx C-k +@kindex M K (Summary) +@kindex C-k (Summary) +@findex gnus-summary-kill-same-subject +Mark all articles that have the same subject as the current one as read +(@code{gnus-summary-kill-same-subject}). + +@item M C +@kindex M C (Summary) +@findex gnus-summary-catchup +@c @icon{gnus-summary-catchup} +Mark all unread articles as read (@code{gnus-summary-catchup}). + +@item M C-c +@kindex M C-c (Summary) +@findex gnus-summary-catchup-all +Mark all articles in the group as read---even the ticked and dormant +articles (@code{gnus-summary-catchup-all}). + +@item M H +@kindex M H (Summary) +@findex gnus-summary-catchup-to-here +Catchup the current group to point +(@code{gnus-summary-catchup-to-here}). + +@item C-w +@kindex C-w (Summary) +@findex gnus-summary-mark-region-as-read +Mark all articles between point and mark as read +(@code{gnus-summary-mark-region-as-read}). + +@item M V k +@kindex M V k (Summary) +@findex gnus-summary-kill-below +Kill all articles with scores below the default score (or below the +numeric prefix) (@code{gnus-summary-kill-below}). + +@item M e +@itemx E +@kindex M e (Summary) +@kindex E (Summary) +@findex gnus-summary-mark-as-expirable +Mark the current article as expirable +(@code{gnus-summary-mark-as-expirable}). + +@item M b +@kindex M b (Summary) +@findex gnus-summary-set-bookmark +Set a bookmark in the current article +(@code{gnus-summary-set-bookmark}). + +@item M B +@kindex M B (Summary) +@findex gnus-summary-remove-bookmark +Remove the bookmark from the current article +(@code{gnus-summary-remove-bookmark}). + +@item M V c +@kindex M V c (Summary) +@findex gnus-summary-clear-above +Clear all marks from articles with scores over the default score (or +over the numeric prefix) (@code{gnus-summary-clear-above}). + +@item M V u +@kindex M V u (Summary) +@findex gnus-summary-tick-above +Tick all articles with scores over the default score (or over the +numeric prefix) (@code{gnus-summary-tick-above}). + +@item M V m +@kindex M V m (Summary) +@findex gnus-summary-mark-above +Prompt for a mark, and mark all articles with scores over the default +score (or over the numeric prefix) with this mark +(@code{gnus-summary-clear-above}). +@end table + +@vindex gnus-summary-goto-unread +The @code{gnus-summary-goto-unread} variable controls what action should +be taken after setting a mark. If non-@code{nil}, point will move to +the next/previous unread article. If @code{nil}, point will just move +one line up or down. As a special case, if this variable is +@code{never}, all the marking commands as well as other commands (like +@kbd{SPACE}) will move to the next article, whether it is unread or not. +The default is @code{t}. + + +@node Setting Process Marks +@subsection Setting Process Marks +@cindex setting process marks + +@table @kbd + +@item M P p +@itemx # +@kindex # (Summary) +@kindex M P p (Summary) +@findex gnus-summary-mark-as-processable +Mark the current article with the process mark +(@code{gnus-summary-mark-as-processable}). +@findex gnus-summary-unmark-as-processable + +@item M P u +@itemx M-# +@kindex M P u (Summary) +@kindex M-# (Summary) +Remove the process mark, if any, from the current article +(@code{gnus-summary-unmark-as-processable}). + +@item M P U +@kindex M P U (Summary) +@findex gnus-summary-unmark-all-processable +Remove the process mark from all articles +(@code{gnus-summary-unmark-all-processable}). + +@item M P i +@kindex M P i (Summary) +@findex gnus-uu-invert-processable +Invert the list of process marked articles +(@code{gnus-uu-invert-processable}). + +@item M P R +@kindex M P R (Summary) +@findex gnus-uu-mark-by-regexp +Mark articles that have a @code{Subject} header that matches a regular +expression (@code{gnus-uu-mark-by-regexp}). + +@item M P r +@kindex M P r (Summary) +@findex gnus-uu-mark-region +Mark articles in region (@code{gnus-uu-mark-region}). + +@item M P t +@kindex M P t (Summary) +@findex gnus-uu-mark-thread +Mark all articles in the current (sub)thread +(@code{gnus-uu-mark-thread}). + +@item M P T +@kindex M P T (Summary) +@findex gnus-uu-unmark-thread +Unmark all articles in the current (sub)thread +(@code{gnus-uu-unmark-thread}). + +@item M P v +@kindex M P v (Summary) +@findex gnus-uu-mark-over +Mark all articles that have a score above the prefix argument +(@code{gnus-uu-mark-over}). + +@item M P s +@kindex M P s (Summary) +@findex gnus-uu-mark-series +Mark all articles in the current series (@code{gnus-uu-mark-series}). + +@item M P S +@kindex M P S (Summary) +@findex gnus-uu-mark-sparse +Mark all series that have already had some articles marked +(@code{gnus-uu-mark-sparse}). + +@item M P a +@kindex M P a (Summary) +@findex gnus-uu-mark-all +Mark all articles in series order (@code{gnus-uu-mark-series}). + +@item M P b +@kindex M P b (Summary) +@findex gnus-uu-mark-buffer +Mark all articles in the buffer in the order they appear +(@code{gnus-uu-mark-buffer}). + +@item M P k +@kindex M P k (Summary) +@findex gnus-summary-kill-process-mark +Push the current process mark set onto the stack and unmark all articles +(@code{gnus-summary-kill-process-mark}). + +@item M P y +@kindex M P y (Summary) +@findex gnus-summary-yank-process-mark +Pop the previous process mark set from the stack and restore it +(@code{gnus-summary-yank-process-mark}). + +@item M P w +@kindex M P w (Summary) +@findex gnus-summary-save-process-mark +Push the current process mark set onto the stack +(@code{gnus-summary-save-process-mark}). + +@end table + + +@node Limiting +@section Limiting +@cindex limiting + +It can be convenient to limit the summary buffer to just show some +subset of the articles currently in the group. The effect most limit +commands have is to remove a few (or many) articles from the summary +buffer. + +All limiting commands work on subsets of the articles already fetched +from the servers. None of these commands query the server for +additional articles. + +@table @kbd + +@item / / +@itemx / s +@kindex / / (Summary) +@findex gnus-summary-limit-to-subject +Limit the summary buffer to articles that match some subject +(@code{gnus-summary-limit-to-subject}). + +@item / a +@kindex / a (Summary) +@findex gnus-summary-limit-to-author +Limit the summary buffer to articles that match some author +(@code{gnus-summary-limit-to-author}). + +@item / u +@itemx x +@kindex / u (Summary) +@kindex x (Summary) +@findex gnus-summary-limit-to-unread +Limit the summary buffer to articles not marked as read +(@code{gnus-summary-limit-to-unread}). If given a prefix, limit the +buffer to articles strictly unread. This means that ticked and +dormant articles will also be excluded. + +@item / m +@kindex / m (Summary) +@findex gnus-summary-limit-to-marks +Ask for a mark and then limit to all articles that have been marked +with that mark (@code{gnus-summary-limit-to-marks}). + +@item / t +@kindex / t (Summary) +@findex gnus-summary-limit-to-age +Ask for a number and then limit the summary buffer to articles older than (or equal to) that number of days +(@code{gnus-summary-limit-to-marks}). If given a prefix, limit to +articles younger than that number of days. + +@item / n +@kindex / n (Summary) +@findex gnus-summary-limit-to-articles +Limit the summary buffer to the current article +(@code{gnus-summary-limit-to-articles}). Uses the process/prefix +convention (@pxref{Process/Prefix}). + +@item / w +@kindex / w (Summary) +@findex gnus-summary-pop-limit +Pop the previous limit off the stack and restore it +(@code{gnus-summary-pop-limit}). If given a prefix, pop all limits off +the stack. + +@item / v +@kindex / v (Summary) +@findex gnus-summary-limit-to-score +Limit the summary buffer to articles that have a score at or above some +score (@code{gnus-summary-limit-to-score}). + +@item / E +@itemx M S +@kindex M S (Summary) +@kindex / E (Summary) +@findex gnus-summary-limit-include-expunged +Include all expunged articles in the limit +(@code{gnus-summary-limit-include-expunged}). + +@item / D +@kindex / D (Summary) +@findex gnus-summary-limit-include-dormant +Include all dormant articles in the limit +(@code{gnus-summary-limit-include-dormant}). + +@item / * +@kindex / * (Summary) +@findex gnus-summary-limit-include-cached +Include all cached articles in the limit +(@code{gnus-summary-limit-include-cached}). + +@item / d +@kindex / d (Summary) +@findex gnus-summary-limit-exclude-dormant +Exclude all dormant articles from the limit +(@code{gnus-summary-limit-exclude-dormant}). + +@item / T +@kindex / T (Summary) +@findex gnus-summary-limit-include-thread +Include all the articles in the current thread in the limit. + +@item / c +@kindex / c (Summary) +@findex gnus-summary-limit-exclude-childless-dormant +Exclude all dormant articles that have no children from the limit +(@code{gnus-summary-limit-exclude-childless-dormant}). + +@item / C +@kindex / C (Summary) +@findex gnus-summary-limit-mark-excluded-as-read +Mark all excluded unread articles as read +(@code{gnus-summary-limit-mark-excluded-as-read}). If given a prefix, +also mark excluded ticked and dormant articles as read. + +@end table + + +@node Threading +@section Threading +@cindex threading +@cindex article threading + +Gnus threads articles by default. @dfn{To thread} is to put responses +to articles directly after the articles they respond to---in a +hierarchical fashion. + +Threading is done by looking at the @code{References} headers of the +articles. In a perfect world, this would be enough to build pretty +trees, but unfortunately, the @code{References} header is often broken +or simply missing. Weird news propagation excarcerbates the problem, +so one has to employ other heuristics to get pleasing results. A +plethora of approaches exists, as detailed in horrible detail in +@pxref{Customizing Threading}. + +First, a quick overview of the concepts: + +@table @dfn +@item root +The top-most article in a thread; the first article in the thread. + +@item thread +A tree-like article structure. + +@item sub-thread +A small(er) section of this tree-like structure. + +@item loose threads +Threads often lose their roots due to article expiry, or due to the root +already having been read in a previous session, and not displayed in the +summary buffer. We then typically have many sub-threads that really +belong to one thread, but are without connecting roots. These are +called loose threads. + +@item thread gathering +An attempt to gather loose threads into bigger threads. + +@item sparse threads +A thread where the missing articles have been ``guessed'' at, and are +displayed as empty lines in the summary buffer. + +@end table + + +@menu +* Customizing Threading:: Variables you can change to affect the threading. +* Thread Commands:: Thread based commands in the summary buffer. +@end menu + + +@node Customizing Threading +@subsection Customizing Threading +@cindex customizing threading + +@menu +* Loose Threads:: How Gnus gathers loose threads into bigger threads. +* Filling In Threads:: Making the threads displayed look fuller. +* More Threading:: Even more variables for fiddling with threads. +* Low-Level Threading:: You thought it was over... but you were wrong! +@end menu + + +@node Loose Threads +@subsubsection Loose Threads +@cindex < +@cindex > +@cindex loose threads + +@table @code +@item gnus-summary-make-false-root +@vindex gnus-summary-make-false-root +If non-@code{nil}, Gnus will gather all loose subtrees into one big tree +and create a dummy root at the top. (Wait a minute. Root at the top? +Yup.) Loose subtrees occur when the real root has expired, or you've +read or killed the root in a previous session. + +When there is no real root of a thread, Gnus will have to fudge +something. This variable says what fudging method Gnus should use. +There are four possible values: + +@cindex adopting articles + +@table @code + +@item adopt +Gnus will make the first of the orphaned articles the parent. This +parent will adopt all the other articles. The adopted articles will be +marked as such by pointy brackets (@samp{<>}) instead of the standard +square brackets (@samp{[]}). This is the default method. + +@item dummy +@vindex gnus-summary-dummy-line-format +Gnus will create a dummy summary line that will pretend to be the +parent. This dummy line does not correspond to any real article, so +selecting it will just select the first real article after the dummy +article. @code{gnus-summary-dummy-line-format} is used to specify the +format of the dummy roots. It accepts only one format spec: @samp{S}, +which is the subject of the article. @xref{Formatting Variables}. + +@item empty +Gnus won't actually make any article the parent, but simply leave the +subject field of all orphans except the first empty. (Actually, it will +use @code{gnus-summary-same-subject} as the subject (@pxref{Summary +Buffer Format}).) + +@item none +Don't make any article parent at all. Just gather the threads and +display them after one another. + +@item nil +Don't gather loose threads. +@end table + +@item gnus-summary-gather-subject-limit +@vindex gnus-summary-gather-subject-limit +Loose threads are gathered by comparing subjects of articles. If this +variable is @code{nil}, Gnus requires an exact match between the +subjects of the loose threads before gathering them into one big +super-thread. This might be too strict a requirement, what with the +presence of stupid newsreaders that chop off long subject lines. If +you think so, set this variable to, say, 20 to require that only the +first 20 characters of the subjects have to match. If you set this +variable to a really low number, you'll find that Gnus will gather +everything in sight into one thread, which isn't very helpful. + +@cindex fuzzy article gathering +If you set this variable to the special value @code{fuzzy}, Gnus will +use a fuzzy string comparison algorithm on the subjects (@pxref{Fuzzy +Matching}). + +@item gnus-simplify-subject-fuzzy-regexp +@vindex gnus-simplify-subject-fuzzy-regexp +This can either be a regular expression or list of regular expressions +that match strings that will be removed from subjects if fuzzy subject +simplification is used. + +@item gnus-simplify-ignored-prefixes +@vindex gnus-simplify-ignored-prefixes +If you set @code{gnus-summary-gather-subject-limit} to something as low +as 10, you might consider setting this variable to something sensible: + +@c Written by Michael Ernst <mernst@cs.rice.edu> +@lisp +(setq gnus-simplify-ignored-prefixes + (concat + "\\`\\[?\\(" + (mapconcat + 'identity + '("looking" + "wanted" "followup" "summary\\( of\\)?" + "help" "query" "problem" "question" + "answer" "reference" "announce" + "How can I" "How to" "Comparison of" + ;; ... + ) + "\\|") + "\\)\\s *\\(" + (mapconcat 'identity + '("for" "for reference" "with" "about") + "\\|") + "\\)?\\]?:?[ \t]*")) +@end lisp + +All words that match this regexp will be removed before comparing two +subjects. + +@item gnus-simplify-subject-functions +@vindex gnus-simplify-subject-functions +If non-@code{nil}, this variable overrides +@code{gnus-summary-gather-subject-limit}. This variable should be a +list of functions to apply to the @code{Subject} string iteratively to +arrive at the simplified version of the string. + +Useful functions to put in this list include: + +@table @code +@item gnus-simplify-subject-re +@findex gnus-simplify-subject-re +Strip the leading @samp{Re:}. + +@item gnus-simplify-subject-fuzzy +@findex gnus-simplify-subject-fuzzy +Simplify fuzzily. + +@item gnus-simplify-whitespace +@findex gnus-simplify-whitespace +Remove excessive whitespace. +@end table + +You may also write your own functions, of course. + + +@item gnus-summary-gather-exclude-subject +@vindex gnus-summary-gather-exclude-subject +Since loose thread gathering is done on subjects only, that might lead +to many false hits, especially with certain common subjects like +@samp{} and @samp{(none)}. To make the situation slightly better, +you can use the regexp @code{gnus-summary-gather-exclude-subject} to say +what subjects should be excluded from the gathering process.@* +The default is @samp{^ *$\\|^(none)$}. + +@item gnus-summary-thread-gathering-function +@vindex gnus-summary-thread-gathering-function +Gnus gathers threads by looking at @code{Subject} headers. This means +that totally unrelated articles may end up in the same ``thread'', which +is confusing. An alternate approach is to look at all the +@code{Message-ID}s in all the @code{References} headers to find matches. +This will ensure that no gathered threads ever include unrelated +articles, but it also means that people who have posted with broken +newsreaders won't be gathered properly. The choice is yours---plague or +cholera: + +@table @code +@item gnus-gather-threads-by-subject +@findex gnus-gather-threads-by-subject +This function is the default gathering function and looks at +@code{Subject}s exclusively. + +@item gnus-gather-threads-by-references +@findex gnus-gather-threads-by-references +This function looks at @code{References} headers exclusively. +@end table + +If you want to test gathering by @code{References}, you could say +something like: + +@lisp +(setq gnus-summary-thread-gathering-function + 'gnus-gather-threads-by-references) +@end lisp + +@end table + + +@node Filling In Threads +@subsubsection Filling In Threads + +@table @code +@item gnus-fetch-old-headers +@vindex gnus-fetch-old-headers +If non-@code{nil}, Gnus will attempt to build old threads by fetching +more old headers---headers to articles marked as read. If you +would like to display as few summary lines as possible, but still +connect as many loose threads as possible, you should set this variable +to @code{some} or a number. If you set it to a number, no more than +that number of extra old headers will be fetched. In either case, +fetching old headers only works if the backend you are using carries +overview files---this would normally be @code{nntp}, @code{nnspool} and +@code{nnml}. Also remember that if the root of the thread has been +expired by the server, there's not much Gnus can do about that. + +This variable can also be set to @code{invisible}. This won't have any +visible effects, but is useful if you use the @kbd{A T} command a lot +(@pxref{Finding the Parent}). + +@item gnus-build-sparse-threads +@vindex gnus-build-sparse-threads +Fetching old headers can be slow. A low-rent similar effect can be +gotten by setting this variable to @code{some}. Gnus will then look at +the complete @code{References} headers of all articles and try to string +together articles that belong in the same thread. This will leave +@dfn{gaps} in the threading display where Gnus guesses that an article +is missing from the thread. (These gaps appear like normal summary +lines. If you select a gap, Gnus will try to fetch the article in +question.) If this variable is @code{t}, Gnus will display all these +``gaps'' without regard for whether they are useful for completing the +thread or not. Finally, if this variable is @code{more}, Gnus won't cut +off sparse leaf nodes that don't lead anywhere. This variable is +@code{nil} by default. + +@end table + + +@node More Threading +@subsubsection More Threading + +@table @code +@item gnus-show-threads +@vindex gnus-show-threads +If this variable is @code{nil}, no threading will be done, and all of +the rest of the variables here will have no effect. Turning threading +off will speed group selection up a bit, but it is sure to make reading +slower and more awkward. + +@item gnus-thread-hide-subtree +@vindex gnus-thread-hide-subtree +If non-@code{nil}, all threads will be hidden when the summary buffer is +generated. + +@item gnus-thread-expunge-below +@vindex gnus-thread-expunge-below +All threads that have a total score (as defined by +@code{gnus-thread-score-function}) less than this number will be +expunged. This variable is @code{nil} by default, which means that no +threads are expunged. + +@item gnus-thread-hide-killed +@vindex gnus-thread-hide-killed +if you kill a thread and this variable is non-@code{nil}, the subtree +will be hidden. + +@item gnus-thread-ignore-subject +@vindex gnus-thread-ignore-subject +Sometimes somebody changes the subject in the middle of a thread. If +this variable is non-@code{nil}, the subject change is ignored. If it +is @code{nil}, which is the default, a change in the subject will result +in a new thread. + +@item gnus-thread-indent-level +@vindex gnus-thread-indent-level +This is a number that says how much each sub-thread should be indented. +The default is 4. + +@end table + + +@node Low-Level Threading +@subsubsection Low-Level Threading + +@table @code + +@item gnus-parse-headers-hook +@vindex gnus-parse-headers-hook +Hook run before parsing any headers. The default value is +@code{(gnus-decode-rfc1522)}, which means that QPized headers will be +slightly decoded in a hackish way. This is likely to change in the +future when Gnus becomes @sc{MIME}ified. + +@item gnus-alter-header-function +@vindex gnus-alter-header-function +If non-@code{nil}, this function will be called to allow alteration of +article header structures. The function is called with one parameter, +the article header vector, which it may alter in any way. For instance, +if you have a mail-to-news gateway which alters the @code{Message-ID}s +in systematic ways (by adding prefixes and such), you can use this +variable to un-scramble the @code{Message-ID}s so that they are more +meaningful. Here's one example: + +@lisp +(setq gnus-alter-header-function 'my-alter-message-id) + +(defun my-alter-message-id (header) + (let ((id (mail-header-id header))) + (when (string-match + "\\(<[^<>@@]*\\)\\.?cygnus\\..*@@\\([^<>@@]*>\\)" id) + (mail-header-set-id + (concat (match-string 1 id) "@@" (match-string 2 id)) + header)))) +@end lisp + +@end table + + +@node Thread Commands +@subsection Thread Commands +@cindex thread commands + +@table @kbd + +@item T k +@itemx M-C-k +@kindex T k (Summary) +@kindex M-C-k (Summary) +@findex gnus-summary-kill-thread +Mark all articles in the current (sub-)thread as read +(@code{gnus-summary-kill-thread}). If the prefix argument is positive, +remove all marks instead. If the prefix argument is negative, tick +articles instead. + +@item T l +@itemx M-C-l +@kindex T l (Summary) +@kindex M-C-l (Summary) +@findex gnus-summary-lower-thread +Lower the score of the current (sub-)thread +(@code{gnus-summary-lower-thread}). + +@item T i +@kindex T i (Summary) +@findex gnus-summary-raise-thread +Increase the score of the current (sub-)thread +(@code{gnus-summary-raise-thread}). + +@item T # +@kindex T # (Summary) +@findex gnus-uu-mark-thread +Set the process mark on the current (sub-)thread +(@code{gnus-uu-mark-thread}). + +@item T M-# +@kindex T M-# (Summary) +@findex gnus-uu-unmark-thread +Remove the process mark from the current (sub-)thread +(@code{gnus-uu-unmark-thread}). + +@item T T +@kindex T T (Summary) +@findex gnus-summary-toggle-threads +Toggle threading (@code{gnus-summary-toggle-threads}). + +@item T s +@kindex T s (Summary) +@findex gnus-summary-show-thread +Expose the (sub-)thread hidden under the current article, if any +(@code{gnus-summary-show-thread}). + +@item T h +@kindex T h (Summary) +@findex gnus-summary-hide-thread +Hide the current (sub-)thread (@code{gnus-summary-hide-thread}). + +@item T S +@kindex T S (Summary) +@findex gnus-summary-show-all-threads +Expose all hidden threads (@code{gnus-summary-show-all-threads}). + +@item T H +@kindex T H (Summary) +@findex gnus-summary-hide-all-threads +Hide all threads (@code{gnus-summary-hide-all-threads}). + +@item T t +@kindex T t (Summary) +@findex gnus-summary-rethread-current +Re-thread the current article's thread +(@code{gnus-summary-rethread-current}). This works even when the +summary buffer is otherwise unthreaded. + +@item T ^ +@kindex T ^ (Summary) +@findex gnus-summary-reparent-thread +Make the current article the child of the marked (or previous) article +(@code{gnus-summary-reparent-thread}). + +@end table + +The following commands are thread movement commands. They all +understand the numeric prefix. + +@table @kbd + +@item T n +@kindex T n (Summary) +@findex gnus-summary-next-thread +Go to the next thread (@code{gnus-summary-next-thread}). + +@item T p +@kindex T p (Summary) +@findex gnus-summary-prev-thread +Go to the previous thread (@code{gnus-summary-prev-thread}). + +@item T d +@kindex T d (Summary) +@findex gnus-summary-down-thread +Descend the thread (@code{gnus-summary-down-thread}). + +@item T u +@kindex T u (Summary) +@findex gnus-summary-up-thread +Ascend the thread (@code{gnus-summary-up-thread}). + +@item T o +@kindex T o (Summary) +@findex gnus-summary-top-thread +Go to the top of the thread (@code{gnus-summary-top-thread}). +@end table + +@vindex gnus-thread-operation-ignore-subject +If you ignore subject while threading, you'll naturally end up with +threads that have several different subjects in them. If you then issue +a command like `T k' (@code{gnus-summary-kill-thread}) you might not +wish to kill the entire thread, but just those parts of the thread that +have the same subject as the current article. If you like this idea, +you can fiddle with @code{gnus-thread-operation-ignore-subject}. If it +is non-@code{nil} (which it is by default), subjects will be ignored +when doing thread commands. If this variable is @code{nil}, articles in +the same thread with different subjects will not be included in the +operation in question. If this variable is @code{fuzzy}, only articles +that have subjects fuzzily equal will be included (@pxref{Fuzzy +Matching}). + + +@node Sorting +@section Sorting + +@findex gnus-thread-sort-by-total-score +@findex gnus-thread-sort-by-date +@findex gnus-thread-sort-by-score +@findex gnus-thread-sort-by-subject +@findex gnus-thread-sort-by-author +@findex gnus-thread-sort-by-number +@vindex gnus-thread-sort-functions +If you are using a threaded summary display, you can sort the threads by +setting @code{gnus-thread-sort-functions}, which is a list of functions. +By default, sorting is done on article numbers. Ready-made sorting +predicate functions include @code{gnus-thread-sort-by-number}, +@code{gnus-thread-sort-by-author}, @code{gnus-thread-sort-by-subject}, +@code{gnus-thread-sort-by-date}, @code{gnus-thread-sort-by-score}, and +@code{gnus-thread-sort-by-total-score}. + +Each function takes two threads and returns non-@code{nil} if the first +thread should be sorted before the other. Note that sorting really is +normally done by looking only at the roots of each thread. If you use +more than one function, the primary sort key should be the last function +in the list. You should probably always include +@code{gnus-thread-sort-by-number} in the list of sorting +functions---preferably first. This will ensure that threads that are +equal with respect to the other sort criteria will be displayed in +ascending article order. + +If you would like to sort by score, then by subject, and finally by +number, you could do something like: + +@lisp +(setq gnus-thread-sort-functions + '(gnus-thread-sort-by-number + gnus-thread-sort-by-subject + gnus-thread-sort-by-total-score)) +@end lisp + +The threads that have highest score will be displayed first in the +summary buffer. When threads have the same score, they will be sorted +alphabetically. The threads that have the same score and the same +subject will be sorted by number, which is (normally) the sequence in +which the articles arrived. + +If you want to sort by score and then reverse arrival order, you could +say something like: + +@lisp +(setq gnus-thread-sort-functions + '((lambda (t1 t2) + (not (gnus-thread-sort-by-number t1 t2))) + gnus-thread-sort-by-score)) +@end lisp + +@vindex gnus-thread-score-function +The function in the @code{gnus-thread-score-function} variable (default +@code{+}) is used for calculating the total score of a thread. Useful +functions might be @code{max}, @code{min}, or squared means, or whatever +tickles your fancy. + +@findex gnus-article-sort-functions +@findex gnus-article-sort-by-date +@findex gnus-article-sort-by-score +@findex gnus-article-sort-by-subject +@findex gnus-article-sort-by-author +@findex gnus-article-sort-by-number +If you are using an unthreaded display for some strange reason or other, +you have to fiddle with the @code{gnus-article-sort-functions} variable. +It is very similar to the @code{gnus-thread-sort-functions}, except that +it uses slightly different functions for article comparison. Available +sorting predicate functions are @code{gnus-article-sort-by-number}, +@code{gnus-article-sort-by-author}, @code{gnus-article-sort-by-subject}, +@code{gnus-article-sort-by-date}, and @code{gnus-article-sort-by-score}. + +If you want to sort an unthreaded summary display by subject, you could +say something like: + +@lisp +(setq gnus-article-sort-functions + '(gnus-article-sort-by-number + gnus-article-sort-by-subject)) +@end lisp + + + +@node Asynchronous Fetching +@section Asynchronous Article Fetching +@cindex asynchronous article fetching +@cindex article pre-fetch +@cindex pre-fetch + +If you read your news from an @sc{nntp} server that's far away, the +network latencies may make reading articles a chore. You have to wait +for a while after pressing @kbd{n} to go to the next article before the +article appears. Why can't Gnus just go ahead and fetch the article +while you are reading the previous one? Why not, indeed. + +First, some caveats. There are some pitfalls to using asynchronous +article fetching, especially the way Gnus does it. + +Let's say you are reading article 1, which is short, and article 2 is +quite long, and you are not interested in reading that. Gnus does not +know this, so it goes ahead and fetches article 2. You decide to read +article 3, but since Gnus is in the process of fetching article 2, the +connection is blocked. + +To avoid these situations, Gnus will open two (count 'em two) +connections to the server. Some people may think this isn't a very nice +thing to do, but I don't see any real alternatives. Setting up that +extra connection takes some time, so Gnus startup will be slower. + +Gnus will fetch more articles than you will read. This will mean that +the link between your machine and the @sc{nntp} server will become more +loaded than if you didn't use article pre-fetch. The server itself will +also become more loaded---both with the extra article requests, and the +extra connection. + +Ok, so now you know that you shouldn't really use this thing... unless +you really want to. + +@vindex gnus-asynchronous +Here's how: Set @code{gnus-asynchronous} to @code{t}. The rest should +happen automatically. + +@vindex gnus-use-article-prefetch +You can control how many articles are to be pre-fetched by setting +@code{gnus-use-article-prefetch}. This is 30 by default, which means +that when you read an article in the group, the backend will pre-fetch +the next 30 articles. If this variable is @code{t}, the backend will +pre-fetch all the articles it can without bound. If it is +@code{nil}, no pre-fetching will be done. + +@vindex gnus-async-prefetch-article-p +@findex gnus-async-read-p +There are probably some articles that you don't want to pre-fetch---read +articles, for instance. The @code{gnus-async-prefetch-article-p} variable controls whether an article is to be pre-fetched. This function should +return non-@code{nil} when the article in question is to be +pre-fetched. The default is @code{gnus-async-read-p}, which returns +@code{nil} on read articles. The function is called with an article +data structure as the only parameter. + +If, for instance, you wish to pre-fetch only unread articles shorter than 100 lines, you could say something like: + +@lisp +(defun my-async-short-unread-p (data) + "Return non-nil for short, unread articles." + (and (gnus-data-unread-p data) + (< (mail-header-lines (gnus-data-header data)) + 100))) + +(setq gnus-async-prefetch-article-p 'my-async-short-unread-p) +@end lisp + +These functions will be called many, many times, so they should +preferably be short and sweet to avoid slowing down Gnus too much. +It's probably a good idea to byte-compile things like this. + +@vindex gnus-prefetched-article-deletion-strategy +Articles have to be removed from the asynch buffer sooner or later. The +@code{gnus-prefetched-article-deletion-strategy} says when to remove +articles. This is a list that may contain the following elements: + +@table @code +@item read +Remove articles when they are read. + +@item exit +Remove articles when exiting the group. +@end table + +The default value is @code{(read exit)}. + +@c @vindex gnus-use-header-prefetch +@c If @code{gnus-use-header-prefetch} is non-@code{nil}, prefetch articles +@c from the next group. + + +@node Article Caching +@section Article Caching +@cindex article caching +@cindex caching + +If you have an @emph{extremely} slow @sc{nntp} connection, you may +consider turning article caching on. Each article will then be stored +locally under your home directory. As you may surmise, this could +potentially use @emph{huge} amounts of disk space, as well as eat up all +your inodes so fast it will make your head swim. In vodka. + +Used carefully, though, it could be just an easier way to save articles. + +@vindex gnus-use-long-file-name +@vindex gnus-cache-directory +@vindex gnus-use-cache +To turn caching on, set @code{gnus-use-cache} to @code{t}. By default, +all articles ticked or marked as dormant will then be copied +over to your local cache (@code{gnus-cache-directory}). Whether this +cache is flat or hierarchal is controlled by the +@code{gnus-use-long-file-name} variable, as usual. + +When re-selecting a ticked or dormant article, it will be fetched from the +cache instead of from the server. As articles in your cache will never +expire, this might serve as a method of saving articles while still +keeping them where they belong. Just mark all articles you want to save +as dormant, and don't worry. + +When an article is marked as read, is it removed from the cache. + +@vindex gnus-cache-remove-articles +@vindex gnus-cache-enter-articles +The entering/removal of articles from the cache is controlled by the +@code{gnus-cache-enter-articles} and @code{gnus-cache-remove-articles} +variables. Both are lists of symbols. The first is @code{(ticked +dormant)} by default, meaning that ticked and dormant articles will be +put in the cache. The latter is @code{(read)} by default, meaning that +articles marked as read are removed from the cache. Possibly +symbols in these two lists are @code{ticked}, @code{dormant}, +@code{unread} and @code{read}. + +@findex gnus-jog-cache +So where does the massive article-fetching and storing come into the +picture? The @code{gnus-jog-cache} command will go through all +subscribed newsgroups, request all unread articles, score them, and +store them in the cache. You should only ever, ever ever ever, use this +command if 1) your connection to the @sc{nntp} server is really, really, +really slow and 2) you have a really, really, really huge disk. +Seriously. One way to cut down on the number of articles downloaded is +to score unwanted articles down and have them marked as read. They will +not then be downloaded by this command. + +@vindex gnus-uncacheable-groups +@vindex gnus-cacheable-groups +It is likely that you do not want caching on all groups. For instance, +if your @code{nnml} mail is located under your home directory, it makes no +sense to cache it somewhere else under your home directory. Unless you +feel that it's neat to use twice as much space. + +To limit the caching, you could set @code{gnus-cacheable-groups} to a +regexp of groups to cache, @samp{^nntp} for instance, or set the +@code{gnus-uncacheable-groups} regexp to @samp{^nnml}, for instance. +Both variables are @code{nil} by default. If a group matches both +variables, the group is not cached. + +@findex gnus-cache-generate-nov-databases +@findex gnus-cache-generate-active +@vindex gnus-cache-active-file +The cache stores information on what articles it contains in its active +file (@code{gnus-cache-active-file}). If this file (or any other parts +of the cache) becomes all messed up for some reason or other, Gnus +offers two functions that will try to set things right. @kbd{M-x +gnus-cache-generate-nov-databases} will (re)build all the @sc{nov} +files, and @kbd{gnus-cache-generate-active} will (re)generate the active +file. + + +@node Persistent Articles +@section Persistent Articles +@cindex persistent articles + +Closely related to article caching, we have @dfn{persistent articles}. +In fact, it's just a different way of looking at caching, and much more +useful in my opinion. + +Say you're reading a newsgroup, and you happen on to some valuable gem +that you want to keep and treasure forever. You'd normally just save it +(using one of the many saving commands) in some file. The problem with +that is that it's just, well, yucky. Ideally you'd prefer just having +the article remain in the group where you found it forever; untouched by +the expiry going on at the news server. + +This is what a @dfn{persistent article} is---an article that just won't +be deleted. It's implemented using the normal cache functions, but +you use two explicit commands for managing persistent articles: + +@table @kbd + +@item * +@kindex * (Summary) +@findex gnus-cache-enter-article +Make the current article persistent (@code{gnus-cache-enter-article}). + +@item M-* +@kindex M-* (Summary) +@findex gnus-cache-remove-article +Remove the current article from the persistent articles +(@code{gnus-cache-remove-article}). This will normally delete the +article. +@end table + +Both these commands understand the process/prefix convention. + +To avoid having all ticked articles (and stuff) entered into the cache, +you should set @code{gnus-use-cache} to @code{passive} if you're just +interested in persistent articles: + +@lisp +(setq gnus-use-cache 'passive) +@end lisp + + +@node Article Backlog +@section Article Backlog +@cindex backlog +@cindex article backlog + +If you have a slow connection, but the idea of using caching seems +unappealing to you (and it is, really), you can help the situation some +by switching on the @dfn{backlog}. This is where Gnus will buffer +already read articles so that it doesn't have to re-fetch articles +you've already read. This only helps if you are in the habit of +re-selecting articles you've recently read, of course. If you never do +that, turning the backlog on will slow Gnus down a little bit, and +increase memory usage some. + +@vindex gnus-keep-backlog +If you set @code{gnus-keep-backlog} to a number @var{n}, Gnus will store +at most @var{n} old articles in a buffer for later re-fetching. If this +variable is non-@code{nil} and is not a number, Gnus will store +@emph{all} read articles, which means that your Emacs will grow without +bound before exploding and taking your machine down with you. I put +that in there just to keep y'all on your toes. + +This variable is @code{nil} by default. + + +@node Saving Articles +@section Saving Articles +@cindex saving articles + +Gnus can save articles in a number of ways. Below is the documentation +for saving articles in a fairly straight-forward fashion (i.e., little +processing of the article is done before it is saved). For a different +approach (uudecoding, unsharing) you should use @code{gnus-uu} +(@pxref{Decoding Articles}). + +@vindex gnus-save-all-headers +If @code{gnus-save-all-headers} is non-@code{nil}, Gnus will not delete +unwanted headers before saving the article. + +@vindex gnus-saved-headers +If the preceding variable is @code{nil}, all headers that match the +@code{gnus-saved-headers} regexp will be kept, while the rest will be +deleted before saving. + +@table @kbd + +@item O o +@itemx o +@kindex O o (Summary) +@kindex o (Summary) +@findex gnus-summary-save-article +@c @icon{gnus-summary-save-article} +Save the current article using the default article saver +(@code{gnus-summary-save-article}). + +@item O m +@kindex O m (Summary) +@findex gnus-summary-save-article-mail +Save the current article in mail format +(@code{gnus-summary-save-article-mail}). + +@item O r +@kindex O r (Summary) +@findex gnus-summary-save-article-rmail +Save the current article in rmail format +(@code{gnus-summary-save-article-rmail}). + +@item O f +@kindex O f (Summary) +@findex gnus-summary-save-article-file +@c @icon{gnus-summary-save-article-file} +Save the current article in plain file format +(@code{gnus-summary-save-article-file}). + +@item O F +@kindex O F (Summary) +@findex gnus-summary-write-article-file +Write the current article in plain file format, overwriting any previous +file contents (@code{gnus-summary-write-article-file}). + +@item O b +@kindex O b (Summary) +@findex gnus-summary-save-article-body-file +Save the current article body in plain file format +(@code{gnus-summary-save-article-body-file}). + +@item O h +@kindex O h (Summary) +@findex gnus-summary-save-article-folder +Save the current article in mh folder format +(@code{gnus-summary-save-article-folder}). + +@item O v +@kindex O v (Summary) +@findex gnus-summary-save-article-vm +Save the current article in a VM folder +(@code{gnus-summary-save-article-vm}). + +@item O p +@kindex O p (Summary) +@findex gnus-summary-pipe-output +Save the current article in a pipe. Uhm, like, what I mean is---Pipe +the current article to a process (@code{gnus-summary-pipe-output}). +@end table + +@vindex gnus-prompt-before-saving +All these commands use the process/prefix convention +(@pxref{Process/Prefix}). If you save bunches of articles using these +functions, you might get tired of being prompted for files to save each +and every article in. The prompting action is controlled by +the @code{gnus-prompt-before-saving} variable, which is @code{always} by +default, giving you that excessive prompting action you know and +loathe. If you set this variable to @code{t} instead, you'll be prompted +just once for each series of articles you save. If you like to really +have Gnus do all your thinking for you, you can even set this variable +to @code{nil}, which means that you will never be prompted for files to +save articles in. Gnus will simply save all the articles in the default +files. + + +@vindex gnus-default-article-saver +You can customize the @code{gnus-default-article-saver} variable to make +Gnus do what you want it to. You can use any of the four ready-made +functions below, or you can create your own. + +@table @code + +@item gnus-summary-save-in-rmail +@findex gnus-summary-save-in-rmail +@vindex gnus-rmail-save-name +@findex gnus-plain-save-name +This is the default format, @dfn{babyl}. Uses the function in the +@code{gnus-rmail-save-name} variable to get a file name to save the +article in. The default is @code{gnus-plain-save-name}. + +@item gnus-summary-save-in-mail +@findex gnus-summary-save-in-mail +@vindex gnus-mail-save-name +Save in a Unix mail (mbox) file. Uses the function in the +@code{gnus-mail-save-name} variable to get a file name to save the +article in. The default is @code{gnus-plain-save-name}. + +@item gnus-summary-save-in-file +@findex gnus-summary-save-in-file +@vindex gnus-file-save-name +@findex gnus-numeric-save-name +Append the article straight to an ordinary file. Uses the function in +the @code{gnus-file-save-name} variable to get a file name to save the +article in. The default is @code{gnus-numeric-save-name}. + +@item gnus-summary-save-body-in-file +@findex gnus-summary-save-body-in-file +Append the article body to an ordinary file. Uses the function in the +@code{gnus-file-save-name} variable to get a file name to save the +article in. The default is @code{gnus-numeric-save-name}. + +@item gnus-summary-save-in-folder +@findex gnus-summary-save-in-folder +@findex gnus-folder-save-name +@findex gnus-Folder-save-name +@vindex gnus-folder-save-name +@cindex rcvstore +@cindex MH folders +Save the article to an MH folder using @code{rcvstore} from the MH +library. Uses the function in the @code{gnus-folder-save-name} variable +to get a file name to save the article in. The default is +@code{gnus-folder-save-name}, but you can also use +@code{gnus-Folder-save-name}, which creates capitalized names. + +@item gnus-summary-save-in-vm +@findex gnus-summary-save-in-vm +Save the article in a VM folder. You have to have the VM mail +reader to use this setting. +@end table + +@vindex gnus-article-save-directory +All of these functions, except for the last one, will save the article +in the @code{gnus-article-save-directory}, which is initialized from the +@code{SAVEDIR} environment variable. This is @file{~/News/} by +default. + +As you can see above, the functions use different functions to find a +suitable name of a file to save the article in. Below is a list of +available functions that generate names: + +@table @code + +@item gnus-Numeric-save-name +@findex gnus-Numeric-save-name +File names like @file{~/News/Alt.andrea-dworkin/45}. + +@item gnus-numeric-save-name +@findex gnus-numeric-save-name +File names like @file{~/News/alt.andrea-dworkin/45}. + +@item gnus-Plain-save-name +@findex gnus-Plain-save-name +File names like @file{~/News/Alt.andrea-dworkin}. + +@item gnus-plain-save-name +@findex gnus-plain-save-name +File names like @file{~/News/alt.andrea-dworkin}. +@end table + +@vindex gnus-split-methods +You can have Gnus suggest where to save articles by plonking a regexp into +the @code{gnus-split-methods} alist. For instance, if you would like to +save articles related to Gnus in the file @file{gnus-stuff}, and articles +related to VM in @code{vm-stuff}, you could set this variable to something +like: + +@lisp +(("^Subject:.*gnus\\|^Newsgroups:.*gnus" "gnus-stuff") + ("^Subject:.*vm\\|^Xref:.*vm" "vm-stuff") + (my-choosing-function "../other-dir/my-stuff") + ((equal gnus-newsgroup-name "mail.misc") "mail-stuff")) +@end lisp + +We see that this is a list where each element is a list that has two +elements---the @dfn{match} and the @dfn{file}. The match can either be +a string (in which case it is used as a regexp to match on the article +head); it can be a symbol (which will be called as a function with the +group name as a parameter); or it can be a list (which will be +@code{eval}ed). If any of these actions have a non-@code{nil} result, +the @dfn{file} will be used as a default prompt. In addition, the +result of the operation itself will be used if the function or form +called returns a string or a list of strings. + +You basically end up with a list of file names that might be used when +saving the current article. (All ``matches'' will be used.) You will +then be prompted for what you really want to use as a name, with file +name completion over the results from applying this variable. + +This variable is @code{((gnus-article-archive-name))} by default, which +means that Gnus will look at the articles it saves for an +@code{Archive-name} line and use that as a suggestion for the file +name. + +Here's an example function to clean up file names somewhat. If you have +lots of mail groups called things like +@samp{nnml:mail.whatever}, you may want to chop off the beginning of +these group names before creating the file name to save to. The +following will do just that: + +@lisp +(defun my-save-name (group) + (when (string-match "^nnml:mail." group) + (substring group (match-end 0)))) + +(setq gnus-split-methods + '((gnus-article-archive-name) + (my-save-name))) +@end lisp + + +@vindex gnus-use-long-file-name +Finally, you have the @code{gnus-use-long-file-name} variable. If it is +@code{nil}, all the preceding functions will replace all periods +(@samp{.}) in the group names with slashes (@samp{/})---which means that +the functions will generate hierarchies of directories instead of having +all the files in the top level directory +(@file{~/News/alt/andrea-dworkin} instead of +@file{~/News/alt.andrea-dworkin}.) This variable is @code{t} by default +on most systems. However, for historical reasons, this is @code{nil} on +Xenix and usg-unix-v machines by default. + +This function also affects kill and score file names. If this variable +is a list, and the list contains the element @code{not-score}, long file +names will not be used for score files, if it contains the element +@code{not-save}, long file names will not be used for saving, and if it +contains the element @code{not-kill}, long file names will not be used +for kill files. + +If you'd like to save articles in a hierarchy that looks something like +a spool, you could + +@lisp +(setq gnus-use-long-file-name '(not-save)) ; to get a hierarchy +(setq gnus-default-article-saver 'gnus-summary-save-in-file) ; no encoding +@end lisp + +Then just save with @kbd{o}. You'd then read this hierarchy with +ephemeral @code{nneething} groups---@kbd{G D} in the group buffer, and +the top level directory as the argument (@file{~/News/}). Then just walk +around to the groups/directories with @code{nneething}. + + +@node Decoding Articles +@section Decoding Articles +@cindex decoding articles + +Sometime users post articles (or series of articles) that have been +encoded in some way or other. Gnus can decode them for you. + +@menu +* Uuencoded Articles:: Uudecode articles. +* Shell Archives:: Unshar articles. +* PostScript Files:: Split PostScript. +* Other Files:: Plain save and binhex. +* Decoding Variables:: Variables for a happy decoding. +* Viewing Files:: You want to look at the result of the decoding? +@end menu + +@cindex series +@cindex article series +All these functions use the process/prefix convention +(@pxref{Process/Prefix}) for finding out what articles to work on, with +the extension that a ``single article'' means ``a single series''. Gnus +can find out by itself what articles belong to a series, decode all the +articles and unpack/view/save the resulting file(s). + +Gnus guesses what articles are in the series according to the following +simplish rule: The subjects must be (nearly) identical, except for the +last two numbers of the line. (Spaces are largely ignored, however.) + +For example: If you choose a subject called @samp{cat.gif (2/3)}, Gnus +will find all the articles that match the regexp @samp{^cat.gif +([0-9]+/[0-9]+).*$}. + +Subjects that are non-standard, like @samp{cat.gif (2/3) Part 6 of a +series}, will not be properly recognized by any of the automatic viewing +commands, and you have to mark the articles manually with @kbd{#}. + + +@node Uuencoded Articles +@subsection Uuencoded Articles +@cindex uudecode +@cindex uuencoded articles + +@table @kbd + +@item X u +@kindex X u (Summary) +@findex gnus-uu-decode-uu +@c @icon{gnus-uu-decode-uu} +Uudecodes the current series (@code{gnus-uu-decode-uu}). + +@item X U +@kindex X U (Summary) +@findex gnus-uu-decode-uu-and-save +Uudecodes and saves the current series +(@code{gnus-uu-decode-uu-and-save}). + +@item X v u +@kindex X v u (Summary) +@findex gnus-uu-decode-uu-view +Uudecodes and views the current series (@code{gnus-uu-decode-uu-view}). + +@item X v U +@kindex X v U (Summary) +@findex gnus-uu-decode-uu-and-save-view +Uudecodes, views and saves the current series +(@code{gnus-uu-decode-uu-and-save-view}). + +@end table + +Remember that these all react to the presence of articles marked with +the process mark. If, for instance, you'd like to decode and save an +entire newsgroup, you'd typically do @kbd{M P a} +(@code{gnus-uu-mark-all}) and then @kbd{X U} +(@code{gnus-uu-decode-uu-and-save}). + +All this is very much different from how @code{gnus-uu} worked with +@sc{gnus 4.1}, where you had explicit keystrokes for everything under +the sun. This version of @code{gnus-uu} generally assumes that you mark +articles in some way (@pxref{Setting Process Marks}) and then press +@kbd{X u}. + +@vindex gnus-uu-notify-files +Note: When trying to decode articles that have names matching +@code{gnus-uu-notify-files}, which is hard-coded to +@samp{[Cc][Ii][Nn][Dd][Yy][0-9]+.\\(gif\\|jpg\\)}, @code{gnus-uu} will +automatically post an article on @samp{comp.unix.wizards} saying that +you have just viewed the file in question. This feature can't be turned +off. + + +@node Shell Archives +@subsection Shell Archives +@cindex unshar +@cindex shell archives +@cindex shared articles + +Shell archives (``shar files'') used to be a popular way to distribute +sources, but it isn't used all that much today. In any case, we have +some commands to deal with these: + +@table @kbd + +@item X s +@kindex X s (Summary) +@findex gnus-uu-decode-unshar +Unshars the current series (@code{gnus-uu-decode-unshar}). + +@item X S +@kindex X S (Summary) +@findex gnus-uu-decode-unshar-and-save +Unshars and saves the current series (@code{gnus-uu-decode-unshar-and-save}). + +@item X v s +@kindex X v s (Summary) +@findex gnus-uu-decode-unshar-view +Unshars and views the current series (@code{gnus-uu-decode-unshar-view}). + +@item X v S +@kindex X v S (Summary) +@findex gnus-uu-decode-unshar-and-save-view +Unshars, views and saves the current series +(@code{gnus-uu-decode-unshar-and-save-view}). +@end table + + +@node PostScript Files +@subsection PostScript Files +@cindex PostScript + +@table @kbd + +@item X p +@kindex X p (Summary) +@findex gnus-uu-decode-postscript +Unpack the current PostScript series (@code{gnus-uu-decode-postscript}). + +@item X P +@kindex X P (Summary) +@findex gnus-uu-decode-postscript-and-save +Unpack and save the current PostScript series +(@code{gnus-uu-decode-postscript-and-save}). + +@item X v p +@kindex X v p (Summary) +@findex gnus-uu-decode-postscript-view +View the current PostScript series +(@code{gnus-uu-decode-postscript-view}). + +@item X v P +@kindex X v P (Summary) +@findex gnus-uu-decode-postscript-and-save-view +View and save the current PostScript series +(@code{gnus-uu-decode-postscript-and-save-view}). +@end table + + +@node Other Files +@subsection Other Files + +@table @kbd +@item X o +@kindex X o (Summary) +@findex gnus-uu-decode-save +Save the current series +(@code{gnus-uu-decode-save}). + +@item X b +@kindex X b (Summary) +@findex gnus-uu-decode-binhex +Unbinhex the current series (@code{gnus-uu-decode-binhex}). This +doesn't really work yet. +@end table + + +@node Decoding Variables +@subsection Decoding Variables + +Adjective, not verb. + +@menu +* Rule Variables:: Variables that say how a file is to be viewed. +* Other Decode Variables:: Other decode variables. +* Uuencoding and Posting:: Variables for customizing uuencoding. +@end menu + + +@node Rule Variables +@subsubsection Rule Variables +@cindex rule variables + +Gnus uses @dfn{rule variables} to decide how to view a file. All these +variables are of the form + +@lisp + (list '(regexp1 command2) + '(regexp2 command2) + ...) +@end lisp + +@table @code + +@item gnus-uu-user-view-rules +@vindex gnus-uu-user-view-rules +@cindex sox +This variable is consulted first when viewing files. If you wish to use, +for instance, @code{sox} to convert an @samp{.au} sound file, you could +say something like: +@lisp +(setq gnus-uu-user-view-rules + (list '(\"\\\\.au$\" \"sox %s -t .aiff > /dev/audio\"))) +@end lisp + +@item gnus-uu-user-view-rules-end +@vindex gnus-uu-user-view-rules-end +This variable is consulted if Gnus couldn't make any matches from the +user and default view rules. + +@item gnus-uu-user-archive-rules +@vindex gnus-uu-user-archive-rules +This variable can be used to say what commands should be used to unpack +archives. +@end table + + +@node Other Decode Variables +@subsubsection Other Decode Variables + +@table @code +@vindex gnus-uu-grabbed-file-functions + +@item gnus-uu-grabbed-file-functions +All functions in this list will be called right after each file has been +successfully decoded---so that you can move or view files right away, +and don't have to wait for all files to be decoded before you can do +anything. Ready-made functions you can put in this list are: + +@table @code + +@item gnus-uu-grab-view +@findex gnus-uu-grab-view +View the file. + +@item gnus-uu-grab-move +@findex gnus-uu-grab-move +Move the file (if you're using a saving function.) +@end table + +@item gnus-uu-be-dangerous +@vindex gnus-uu-be-dangerous +Specifies what to do if unusual situations arise during decoding. If +@code{nil}, be as conservative as possible. If @code{t}, ignore things +that didn't work, and overwrite existing files. Otherwise, ask each +time. + +@item gnus-uu-ignore-files-by-name +@vindex gnus-uu-ignore-files-by-name +Files with name matching this regular expression won't be viewed. + +@item gnus-uu-ignore-files-by-type +@vindex gnus-uu-ignore-files-by-type +Files with a @sc{mime} type matching this variable won't be viewed. +Note that Gnus tries to guess what type the file is based on the name. +@code{gnus-uu} is not a @sc{mime} package (yet), so this is slightly +kludgey. + +@item gnus-uu-tmp-dir +@vindex gnus-uu-tmp-dir +Where @code{gnus-uu} does its work. + +@item gnus-uu-do-not-unpack-archives +@vindex gnus-uu-do-not-unpack-archives +Non-@code{nil} means that @code{gnus-uu} won't peek inside archives +looking for files to display. + +@item gnus-uu-view-and-save +@vindex gnus-uu-view-and-save +Non-@code{nil} means that the user will always be asked to save a file +after viewing it. + +@item gnus-uu-ignore-default-view-rules +@vindex gnus-uu-ignore-default-view-rules +Non-@code{nil} means that @code{gnus-uu} will ignore the default viewing +rules. + +@item gnus-uu-ignore-default-archive-rules +@vindex gnus-uu-ignore-default-archive-rules +Non-@code{nil} means that @code{gnus-uu} will ignore the default archive +unpacking commands. + +@item gnus-uu-kill-carriage-return +@vindex gnus-uu-kill-carriage-return +Non-@code{nil} means that @code{gnus-uu} will strip all carriage returns +from articles. + +@item gnus-uu-unmark-articles-not-decoded +@vindex gnus-uu-unmark-articles-not-decoded +Non-@code{nil} means that @code{gnus-uu} will mark unsuccessfully +decoded articles as unread. + +@item gnus-uu-correct-stripped-uucode +@vindex gnus-uu-correct-stripped-uucode +Non-@code{nil} means that @code{gnus-uu} will @emph{try} to fix +uuencoded files that have had trailing spaces deleted. + +@item gnus-uu-pre-uudecode-hook +@vindex gnus-uu-pre-uudecode-hook +Hook run before sending a message to @code{uudecode}. + +@item gnus-uu-view-with-metamail +@vindex gnus-uu-view-with-metamail +@cindex metamail +Non-@code{nil} means that @code{gnus-uu} will ignore the viewing +commands defined by the rule variables and just fudge a @sc{mime} +content type based on the file name. The result will be fed to +@code{metamail} for viewing. + +@item gnus-uu-save-in-digest +@vindex gnus-uu-save-in-digest +Non-@code{nil} means that @code{gnus-uu}, when asked to save without +decoding, will save in digests. If this variable is @code{nil}, +@code{gnus-uu} will just save everything in a file without any +embellishments. The digesting almost conforms to RFC1153---no easy way +to specify any meaningful volume and issue numbers were found, so I +simply dropped them. + +@end table + + +@node Uuencoding and Posting +@subsubsection Uuencoding and Posting + +@table @code + +@item gnus-uu-post-include-before-composing +@vindex gnus-uu-post-include-before-composing +Non-@code{nil} means that @code{gnus-uu} will ask for a file to encode +before you compose the article. If this variable is @code{t}, you can +either include an encoded file with @kbd{C-c C-i} or have one included +for you when you post the article. + +@item gnus-uu-post-length +@vindex gnus-uu-post-length +Maximum length of an article. The encoded file will be split into how +many articles it takes to post the entire file. + +@item gnus-uu-post-threaded +@vindex gnus-uu-post-threaded +Non-@code{nil} means that @code{gnus-uu} will post the encoded file in a +thread. This may not be smart, as no other decoder I have seen is able +to follow threads when collecting uuencoded articles. (Well, I have +seen one package that does that---@code{gnus-uu}, but somehow, I don't +think that counts...) Default is @code{nil}. + +@item gnus-uu-post-separate-description +@vindex gnus-uu-post-separate-description +Non-@code{nil} means that the description will be posted in a separate +article. The first article will typically be numbered (0/x). If this +variable is @code{nil}, the description the user enters will be included +at the beginning of the first article, which will be numbered (1/x). +Default is @code{t}. + +@end table + + +@node Viewing Files +@subsection Viewing Files +@cindex viewing files +@cindex pseudo-articles + +After decoding, if the file is some sort of archive, Gnus will attempt +to unpack the archive and see if any of the files in the archive can be +viewed. For instance, if you have a gzipped tar file @file{pics.tar.gz} +containing the files @file{pic1.jpg} and @file{pic2.gif}, Gnus will +uncompress and de-tar the main file, and then view the two pictures. +This unpacking process is recursive, so if the archive contains archives +of archives, it'll all be unpacked. + +Finally, Gnus will normally insert a @dfn{pseudo-article} for each +extracted file into the summary buffer. If you go to these +``articles'', you will be prompted for a command to run (usually Gnus +will make a suggestion), and then the command will be run. + +@vindex gnus-view-pseudo-asynchronously +If @code{gnus-view-pseudo-asynchronously} is @code{nil}, Emacs will wait +until the viewing is done before proceeding. + +@vindex gnus-view-pseudos +If @code{gnus-view-pseudos} is @code{automatic}, Gnus will not insert +the pseudo-articles into the summary buffer, but view them +immediately. If this variable is @code{not-confirm}, the user won't even +be asked for a confirmation before viewing is done. + +@vindex gnus-view-pseudos-separately +If @code{gnus-view-pseudos-separately} is non-@code{nil}, one +pseudo-article will be created for each file to be viewed. If +@code{nil}, all files that use the same viewing command will be given as +a list of parameters to that command. + +@vindex gnus-insert-pseudo-articles +If @code{gnus-insert-pseudo-articles} is non-@code{nil}, insert +pseudo-articles when decoding. It is @code{t} by default. + +So; there you are, reading your @emph{pseudo-articles} in your +@emph{virtual newsgroup} from the @emph{virtual server}; and you think: +Why isn't anything real anymore? How did we get here? + + +@node Article Treatment +@section Article Treatment + +Reading through this huge manual, you may have quite forgotten that the +object of newsreaders is to actually, like, read what people have +written. Reading articles. Unfortunately, people are quite bad at +writing, so there are tons of functions and variables to make reading +these articles easier. + +@menu +* Article Highlighting:: You want to make the article look like fruit salad. +* Article Fontisizing:: Making emphasized text look nice. +* Article Hiding:: You also want to make certain info go away. +* Article Washing:: Lots of way-neat functions to make life better. +* Article Buttons:: Click on URLs, Message-IDs, addresses and the like. +* Article Date:: Grumble, UT! +* Article Signature:: What is a signature? +@end menu + + +@node Article Highlighting +@subsection Article Highlighting +@cindex highlighting + +Not only do you want your article buffer to look like fruit salad, but +you want it to look like technicolor fruit salad. + +@table @kbd + +@item W H a +@kindex W H a (Summary) +@findex gnus-article-highlight +@findex gnus-article-maybe-highlight +Do much highlighting of the current article +(@code{gnus-article-highlight}). This function highlights header, cited +text, the signature, and adds buttons to the body and the head. + +Most users would prefer using @code{gnus-article-maybe-highlight} in +@code{gnus-article-display-hook} (@pxref{Customizing Articles}) instead. +This is a bit less agressive---it highlights only the headers, the +signature and adds buttons. + +@item W H h +@kindex W H h (Summary) +@findex gnus-article-highlight-headers +@vindex gnus-header-face-alist +Highlight the headers (@code{gnus-article-highlight-headers}). The +highlighting will be done according to the @code{gnus-header-face-alist} +variable, which is a list where each element has the form @var{(regexp +name content)}. @var{regexp} is a regular expression for matching the +header, @var{name} is the face used for highlighting the header name +(@pxref{Faces and Fonts}) and @var{content} is the face for highlighting +the header value. The first match made will be used. Note that +@var{regexp} shouldn't have @samp{^} prepended---Gnus will add one. + +@item W H c +@kindex W H c (Summary) +@findex gnus-article-highlight-citation +Highlight cited text (@code{gnus-article-highlight-citation}). + +Some variables to customize the citation highlights: + +@table @code +@vindex gnus-cite-parse-max-size + +@item gnus-cite-parse-max-size +If the article size if bigger than this variable (which is 25000 by +default), no citation highlighting will be performed. + +@item gnus-cite-prefix-regexp +@vindex gnus-cite-prefix-regexp +Regexp matching the longest possible citation prefix on a line. + +@item gnus-cite-max-prefix +@vindex gnus-cite-max-prefix +Maximum possible length for a citation prefix (default 20). + +@item gnus-cite-face-list +@vindex gnus-cite-face-list +List of faces used for highlighting citations (@pxref{Faces and Fonts}). +When there are citations from multiple articles in the same message, +Gnus will try to give each citation from each article its own face. +This should make it easier to see who wrote what. + +@item gnus-supercite-regexp +@vindex gnus-supercite-regexp +Regexp matching normal Supercite attribution lines. + +@item gnus-supercite-secondary-regexp +@vindex gnus-supercite-secondary-regexp +Regexp matching mangled Supercite attribution lines. + +@item gnus-cite-minimum-match-count +@vindex gnus-cite-minimum-match-count +Minimum number of identical prefixes we have to see before we believe +that it's a citation. + +@item gnus-cite-attribution-prefix +@vindex gnus-cite-attribution-prefix +Regexp matching the beginning of an attribution line. + +@item gnus-cite-attribution-suffix +@vindex gnus-cite-attribution-suffix +Regexp matching the end of an attribution line. + +@item gnus-cite-attribution-face +@vindex gnus-cite-attribution-face +Face used for attribution lines. It is merged with the face for the +cited text belonging to the attribution. + +@end table + + +@item W H s +@kindex W H s (Summary) +@vindex gnus-signature-separator +@vindex gnus-signature-face +@findex gnus-article-highlight-signature +Highlight the signature (@code{gnus-article-highlight-signature}). +Everything after @code{gnus-signature-separator} (@pxref{Article +Signature}) in an article will be considered a signature and will be +highlighted with @code{gnus-signature-face}, which is @code{italic} by +default. + +@end table + +@xref{Customizing Articles}, for how to highlight articles automatically. + + +@node Article Fontisizing +@subsection Article Fontisizing +@cindex emphasis +@cindex article emphasis + +@findex gnus-article-emphasize +@kindex W e (Summary) +People commonly add emphasis to words in news articles by writing things +like @samp{_this_} or @samp{*this*}. Gnus can make this look nicer by +running the article through the @kbd{W e} +(@code{gnus-article-emphasize}) command. + +@vindex gnus-emphasis-alist +How the emphasis is computed is controlled by the +@code{gnus-emphasis-alist} variable. This is an alist where the first +element is a regular expression to be matched. The second is a number +that says what regular expression grouping is used to find the entire +emphasized word. The third is a number that says what regexp grouping +should be displayed and highlighted. (The text between these two +groupings will be hidden.) The fourth is the face used for +highlighting. + +@lisp +(setq gnus-article-emphasis + '(("_\\(\\w+\\)_" 0 1 gnus-emphasis-underline) + ("\\*\\(\\w+\\)\\*" 0 1 gnus-emphasis-bold))) +@end lisp + +@vindex gnus-emphasis-underline +@vindex gnus-emphasis-bold +@vindex gnus-emphasis-italic +@vindex gnus-emphasis-underline-bold +@vindex gnus-emphasis-underline-italic +@vindex gnus-emphasis-bold-italic +@vindex gnus-emphasis-underline-bold-italic +By default, there are seven rules, and they use the following faces: +@code{gnus-emphasis-bold}, @code{gnus-emphasis-italic}, +@code{gnus-emphasis-underline}, @code{gnus-emphasis-bold-italic}, +@code{gnus-emphasis-underline-italic}, +@code{gnus-emphasis-underline-bold}, and +@code{gnus-emphasis-underline-bold-italic}. + +If you want to change these faces, you can either use @kbd{M-x +customize}, or you can use @code{copy-face}. For instance, if you want +to make @code{gnus-emphasis-italic} use a red face instead, you could +say something like: + +@lisp +(copy-face 'red 'gnus-emphasis-italic) +@end lisp + +@xref{Customizing Articles}, for how to fontize articles automatically. + + +@node Article Hiding +@subsection Article Hiding +@cindex article hiding + +Or rather, hiding certain things in each article. There usually is much +too much cruft in most articles. + +@table @kbd + +@item W W a +@kindex W W a (Summary) +@findex gnus-article-hide +Do quite a lot of hiding on the article buffer +(@kbd{gnus-article-hide}). In particular, this function will hide +headers, PGP, cited text and the signature. + +@item W W h +@kindex W W h (Summary) +@findex gnus-article-hide-headers +Hide headers (@code{gnus-article-hide-headers}). @xref{Hiding +Headers}. + +@item W W b +@kindex W W b (Summary) +@findex gnus-article-hide-boring-headers +Hide headers that aren't particularly interesting +(@code{gnus-article-hide-boring-headers}). @xref{Hiding Headers}. + +@item W W s +@kindex W W s (Summary) +@findex gnus-article-hide-signature +Hide signature (@code{gnus-article-hide-signature}). @xref{Article +Signature}. + +@item W W p +@kindex W W p (Summary) +@findex gnus-article-hide-pgp +@vindex gnus-article-hide-pgp-hook +Hide @sc{pgp} signatures (@code{gnus-article-hide-pgp}). The +@code{gnus-article-hide-pgp-hook} hook will be run after a @sc{pgp} +signature has been hidden. + +@item W W P +@kindex W W P (Summary) +@findex gnus-article-hide-pem +Hide @sc{pem} (privacy enhanced messages) cruft +(@code{gnus-article-hide-pem}). + +@item W W c +@kindex W W c (Summary) +@findex gnus-article-hide-citation +Hide citation (@code{gnus-article-hide-citation}). Some variables for +customizing the hiding: + +@table @code + +@item gnus-cited-opened-text-button-line-format +@itemx gnus-cited-closed-text-button-line-format +@vindex gnus-cited-closed-text-button-line-format +@vindex gnus-cited-opened-text-button-line-format +Gnus adds buttons to show where the cited text has been hidden, and to +allow toggle hiding the text. The format of the variable is specified +by these format-like variable (@pxref{Formatting Variables}). These +specs are valid: + +@table @samp +@item b +Starting point of the hidden text. +@item e +Ending point of the hidden text. +@item l +Number of characters in the hidden region. +@item n +Number of lines of hidden text. +@end table + +@item gnus-cited-lines-visible +@vindex gnus-cited-lines-visible +The number of lines at the beginning of the cited text to leave shown. + +@end table + +@item W W C-c +@kindex W W C-c (Summary) +@findex gnus-article-hide-citation-maybe + +Hide citation (@code{gnus-article-hide-citation-maybe}) depending on the +following two variables: + +@table @code +@item gnus-cite-hide-percentage +@vindex gnus-cite-hide-percentage +If the cited text is of a bigger percentage than this variable (default +50), hide the cited text. + +@item gnus-cite-hide-absolute +@vindex gnus-cite-hide-absolute +The cited text must have at least this length (default 10) before it +is hidden. +@end table + +@item W W C +@kindex W W C (Summary) +@findex gnus-article-hide-citation-in-followups +Hide cited text in articles that aren't roots +(@code{gnus-article-hide-citation-in-followups}). This isn't very +useful as an interactive command, but might be a handy function to stick +in @code{gnus-article-display-hook} (@pxref{Customizing Articles}). + +@end table + +All these ``hiding'' commands are toggles, but if you give a negative +prefix to these commands, they will show what they have previously +hidden. If you give a positive prefix, they will always hide. + +Also @pxref{Article Highlighting} for further variables for +citation customization. + +@xref{Customizing Articles}, for how to hide article elements +automatically. + + +@node Article Washing +@subsection Article Washing +@cindex washing +@cindex article washing + +We call this ``article washing'' for a really good reason. Namely, the +@kbd{A} key was taken, so we had to use the @kbd{W} key instead. + +@dfn{Washing} is defined by us as ``changing something from something to +something else'', but normally results in something looking better. +Cleaner, perhaps. + +@table @kbd + +@item W l +@kindex W l (Summary) +@findex gnus-summary-stop-page-breaking +Remove page breaks from the current article +(@code{gnus-summary-stop-page-breaking}). @xref{Misc Article}, for page +delimiters. + +@item W r +@kindex W r (Summary) +@findex gnus-summary-caesar-message +@c @icon{gnus-summary-caesar-message} +Do a Caesar rotate (rot13) on the article buffer +(@code{gnus-summary-caesar-message}). +Unreadable articles that tell you to read them with Caesar rotate or rot13. +(Typically offensive jokes and such.) + +It's commonly called ``rot13'' because each letter is rotated 13 +positions in the alphabet, e. g. @samp{B} (letter #2) -> @samp{O} (letter +#15). It is sometimes referred to as ``Caesar rotate'' because Caesar +is rumored to have employed this form of, uh, somewhat weak encryption. + +@item W t +@kindex W t (Summary) +@findex gnus-summary-toggle-header +Toggle whether to display all headers in the article buffer +(@code{gnus-summary-toggle-header}). + +@item W v +@kindex W v (Summary) +@findex gnus-summary-verbose-header +Toggle whether to display all headers in the article buffer permanently +(@code{gnus-summary-verbose-header}). + +@item W m +@kindex W m (Summary) +@findex gnus-summary-toggle-mime +Toggle whether to run the article through @sc{mime} before displaying +(@code{gnus-summary-toggle-mime}). + +@item W o +@kindex W o (Summary) +@findex gnus-article-treat-overstrike +Treat overstrike (@code{gnus-article-treat-overstrike}). + +@item W d +@kindex W d (Summary) +@findex gnus-article-treat-dumbquotes +Treat M******** sm*rtq**t*s (@code{gnus-article-treat-dumbquotes}). + +@item W w +@kindex W w (Summary) +@findex gnus-article-fill-cited-article +Do word wrap (@code{gnus-article-fill-cited-article}). If you use this +function in @code{gnus-article-display-hook}, it should be run fairly +late and certainly after any highlighting. + +You can give the command a numerical prefix to specify the width to use +when filling. + +@item W c +@kindex W c (Summary) +@findex gnus-article-remove-cr +Remove CR (i. e., @samp{^M}s on the end of the lines) +(@code{gnus-article-remove-cr}). + +@item W q +@kindex W q (Summary) +@findex gnus-article-de-quoted-unreadable +Treat quoted-printable (@code{gnus-article-de-quoted-unreadable}). +Quoted-Printable is one common @sc{mime} encoding employed when sending +non-ASCII (i. e., 8-bit) articles. It typically makes strings like +@samp{déjà vu} look like @samp{d=E9j=E0 vu}, which doesn't look very +readable to me. + +@item W f +@kindex W f (Summary) +@cindex x-face +@findex gnus-article-display-x-face +@findex gnus-article-x-face-command +@vindex gnus-article-x-face-command +@vindex gnus-article-x-face-too-ugly +Look for and display any X-Face headers +(@code{gnus-article-display-x-face}). The command executed by this +function is given by the @code{gnus-article-x-face-command} variable. +If this variable is a string, this string will be executed in a +sub-shell. If it is a function, this function will be called with the +face as the argument. If the @code{gnus-article-x-face-too-ugly} (which +is a regexp) matches the @code{From} header, the face will not be shown. +The default action under Emacs is to fork off an @code{xv} to view the +face; under XEmacs the default action is to display the face before the +@code{From} header. (It's nicer if XEmacs has been compiled with X-Face +support---that will make display somewhat faster. If there's no native +X-Face support, Gnus will try to convert the @code{X-Face} header using +external programs from the @code{pbmplus} package and friends.) If you +want to have this function in the display hook, it should probably come +last. + +@item W b +@kindex W b (Summary) +@findex gnus-article-add-buttons +Add clickable buttons to the article (@code{gnus-article-add-buttons}). +@xref{Article Buttons}. + +@item W B +@kindex W B (Summary) +@findex gnus-article-add-buttons-to-head +Add clickable buttons to the article headers +(@code{gnus-article-add-buttons-to-head}). + +@item W E l +@kindex W E l (Summary) +@findex gnus-article-strip-leading-blank-lines +Remove all blank lines from the beginning of the article +(@code{gnus-article-strip-leading-blank-lines}). + +@item W E m +@kindex W E m (Summary) +@findex gnus-article-strip-multiple-blank-lines +Replace all blank lines with empty lines and then all multiple empty +lines with a single empty line. +(@code{gnus-article-strip-multiple-blank-lines}). + +@item W E t +@kindex W E t (Summary) +@findex gnus-article-remove-trailing-blank-lines +Remove all blank lines at the end of the article +(@code{gnus-article-remove-trailing-blank-lines}). + +@item W E a +@kindex W E a (Summary) +@findex gnus-article-strip-blank-lines +Do all the three commands above +(@code{gnus-article-strip-blank-lines}). + +@item W E A +@kindex W E A (Summary) +@findex gnus-article-strip-all-blank-lines +Remove all blank lines +(@code{gnus-article-strip-all-blank-lines}). + +@item W E s +@kindex W E s (Summary) +@findex gnus-article-strip-leading-space +Remove all white space from the beginning of all lines of the article +body (@code{gnus-article-strip-leading-space}). + +@end table + +@xref{Customizing Articles}, for how to wash articles automatically. + + +@node Article Buttons +@subsection Article Buttons +@cindex buttons + +People often include references to other stuff in articles, and it would +be nice if Gnus could just fetch whatever it is that people talk about +with the minimum of fuzz when you hit @kbd{RET} or use the middle mouse +button on these references. + +Gnus adds @dfn{buttons} to certain standard references by default: +Well-formed URLs, mail addresses and Message-IDs. This is controlled by +two variables, one that handles article bodies and one that handles +article heads: + +@table @code + +@item gnus-button-alist +@vindex gnus-button-alist +This is an alist where each entry has this form: + +@lisp +(REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR) +@end lisp + +@table @var + +@item regexp +All text that match this regular expression will be considered an +external reference. Here's a typical regexp that matches embedded URLs: +@samp{<URL:\\([^\n\r>]*\\)>}. + +@item button-par +Gnus has to know which parts of the matches is to be highlighted. This +is a number that says what sub-expression of the regexp is to be +highlighted. If you want it all highlighted, you use 0 here. + +@item use-p +This form will be @code{eval}ed, and if the result is non-@code{nil}, +this is considered a match. This is useful if you want extra sifting to +avoid false matches. + +@item function +This function will be called when you click on this button. + +@item data-par +As with @var{button-par}, this is a sub-expression number, but this one +says which part of the match is to be sent as data to @var{function}. + +@end table + +So the full entry for buttonizing URLs is then + +@lisp +("<URL:\\([^\n\r>]*\\)>" 0 t gnus-button-url 1) +@end lisp + +@item gnus-header-button-alist +@vindex gnus-header-button-alist +This is just like the other alist, except that it is applied to the +article head only, and that each entry has an additional element that is +used to say what headers to apply the buttonize coding to: + +@lisp +(HEADER REGEXP BUTTON-PAR USE-P FUNCTION DATA-PAR) +@end lisp + +@var{HEADER} is a regular expression. + +@item gnus-button-url-regexp +@vindex gnus-button-url-regexp +A regular expression that matches embedded URLs. It is used in the +default values of the variables above. + +@item gnus-article-button-face +@vindex gnus-article-button-face +Face used on buttons. + +@item gnus-article-mouse-face +@vindex gnus-article-mouse-face +Face used when the mouse cursor is over a button. + +@end table + +@xref{Customizing Articles}, for how to buttonize articles automatically. + + +@node Article Date +@subsection Article Date + +The date is most likely generated in some obscure timezone you've never +heard of, so it's quite nice to be able to find out what the time was +when the article was sent. + +@table @kbd + +@item W T u +@kindex W T u (Summary) +@findex gnus-article-date-ut +Display the date in UT (aka. GMT, aka ZULU) +(@code{gnus-article-date-ut}). + +@item W T i +@kindex W T i (Summary) +@findex gnus-article-date-iso8601 +@cindex ISO 8601 +Display the date in international format, aka. ISO 8601 +(@code{gnus-article-date-iso8601}). + +@item W T l +@kindex W T l (Summary) +@findex gnus-article-date-local +Display the date in the local timezone (@code{gnus-article-date-local}). + +@item W T s +@kindex W T s (Summary) +@vindex gnus-article-time-format +@findex gnus-article-date-user +@findex format-time-string +Display the date using a user-defined format +(@code{gnus-article-date-user}). The format is specified by the +@code{gnus-article-time-format} variable, and is a string that's passed +to @code{format-time-string}. See the documentation of that variable +for a list of possible format specs. + +@item W T e +@kindex W T e (Summary) +@findex gnus-article-date-lapsed +@findex gnus-start-date-timer +@findex gnus-stop-date-timer +Say how much time has elapsed between the article was posted and now +(@code{gnus-article-date-lapsed}). If you want to have this line +updated continually, you can put + +@lisp +(gnus-start-date-timer) +@end lisp + +in your @file{.gnus.el} file, or you can run it off of some hook. If +you want to stop the timer, you can use the @code{gnus-stop-date-timer} +command. + +@item W T o +@kindex W T o (Summary) +@findex gnus-article-date-original +Display the original date (@code{gnus-article-date-original}). This can +be useful if you normally use some other conversion function and are +worried that it might be doing something totally wrong. Say, claiming +that the article was posted in 1854. Although something like that is +@emph{totally} impossible. Don't you trust me? *titter* + +@end table + +@xref{Customizing Articles}, for how to display the date in your +preferred format automatically. + + +@node Article Signature +@subsection Article Signature +@cindex signatures +@cindex article signature + +@vindex gnus-signature-separator +Each article is divided into two parts---the head and the body. The +body can be divided into a signature part and a text part. The variable +that says what is to be considered a signature is +@code{gnus-signature-separator}. This is normally the standard +@samp{^-- $} as mandated by son-of-RFC 1036. However, many people use +non-standard signature separators, so this variable can also be a list +of regular expressions to be tested, one by one. (Searches are done +from the end of the body towards the beginning.) One likely value is: + +@lisp +(setq gnus-signature-separator + '("^-- $" ; The standard + "^-- *$" ; A common mangling + "^-------*$" ; Many people just use a looong + ; line of dashes. Shame! + "^ *--------*$" ; Double-shame! + "^________*$" ; Underscores are also popular + "^========*$")) ; Pervert! +@end lisp + +The more permissive you are, the more likely it is that you'll get false +positives. + +@vindex gnus-signature-limit +@code{gnus-signature-limit} provides a limit to what is considered a +signature. + +@enumerate +@item +If it is an integer, no signature may be longer (in characters) than +that integer. +@item +If it is a floating point number, no signature may be longer (in lines) +than that number. +@item +If it is a function, the function will be called without any parameters, +and if it returns @code{nil}, there is no signature in the buffer. +@item +If it is a string, it will be used as a regexp. If it matches, the text +in question is not a signature. +@end enumerate + +This variable can also be a list where the elements may be of the types +listed above. Here's an example: + +@lisp +(setq gnus-signature-limit + '(200.0 "^---*Forwarded article")) +@end lisp + +This means that if there are more than 200 lines after the signature +separator, or the text after the signature separator is matched by +the regular expression @samp{^---*Forwarded article}, then it isn't a +signature after all. + + +@node Article Commands +@section Article Commands + +@table @kbd + +@item A P +@cindex PostScript +@cindex printing +@kindex A P (Summary) +@vindex gnus-ps-print-hook +@findex gnus-summary-print-article +Generate and print a PostScript image of the article buffer +(@code{gnus-summary-print-article}). @code{gnus-ps-print-hook} will be +run just before printing the buffer. + +@end table + + +@node Summary Sorting +@section Summary Sorting +@cindex summary sorting + +You can have the summary buffer sorted in various ways, even though I +can't really see why you'd want that. + +@table @kbd + +@item C-c C-s C-n +@kindex C-c C-s C-n (Summary) +@findex gnus-summary-sort-by-number +Sort by article number (@code{gnus-summary-sort-by-number}). + +@item C-c C-s C-a +@kindex C-c C-s C-a (Summary) +@findex gnus-summary-sort-by-author +Sort by author (@code{gnus-summary-sort-by-author}). + +@item C-c C-s C-s +@kindex C-c C-s C-s (Summary) +@findex gnus-summary-sort-by-subject +Sort by subject (@code{gnus-summary-sort-by-subject}). + +@item C-c C-s C-d +@kindex C-c C-s C-d (Summary) +@findex gnus-summary-sort-by-date +Sort by date (@code{gnus-summary-sort-by-date}). + +@item C-c C-s C-l +@kindex C-c C-s C-l (Summary) +@findex gnus-summary-sort-by-lines +Sort by lines (@code{gnus-summary-sort-by-lines}). + +@item C-c C-s C-i +@kindex C-c C-s C-i (Summary) +@findex gnus-summary-sort-by-score +Sort by score (@code{gnus-summary-sort-by-score}). +@end table + +These functions will work both when you use threading and when you don't +use threading. In the latter case, all summary lines will be sorted, +line by line. In the former case, sorting will be done on a +root-by-root basis, which might not be what you were looking for. To +toggle whether to use threading, type @kbd{T T} (@pxref{Thread +Commands}). + + +@node Finding the Parent +@section Finding the Parent +@cindex parent articles +@cindex referring articles + +@table @kbd +@item ^ +@kindex ^ (Summary) +@findex gnus-summary-refer-parent-article +If you'd like to read the parent of the current article, and it is not +displayed in the summary buffer, you might still be able to. That is, +if the current group is fetched by @sc{nntp}, the parent hasn't expired +and the @code{References} in the current article are not mangled, you +can just press @kbd{^} or @kbd{A r} +(@code{gnus-summary-refer-parent-article}). If everything goes well, +you'll get the parent. If the parent is already displayed in the +summary buffer, point will just move to this article. + +If given a positive numerical prefix, fetch that many articles back into +the ancestry. If given a negative numerical prefix, fetch just that +ancestor. So if you say @kbd{3 ^}, Gnus will fetch the parent, the +grandparent and the grandgrandparent of the current article. If you say +@kbd{-3 ^}, Gnus will only fetch the grandgrandparent of the current +article. + +@item A R (Summary) +@findex gnus-summary-refer-references +@kindex A R (Summary) +Fetch all articles mentioned in the @code{References} header of the +article (@code{gnus-summary-refer-references}). + +@item A T (Summary) +@findex gnus-summary-refer-thread +@kindex A T (Summary) +Display the full thread where the current article appears +(@code{gnus-summary-refer-thread}). This command has to fetch all the +headers in the current group to work, so it usually takes a while. If +you do it often, you may consider setting @code{gnus-fetch-old-headers} +to @code{invisible} (@pxref{Filling In Threads}). This won't have any +visible effects normally, but it'll make this command work a whole lot +faster. Of course, it'll make group entry somewhat slow. + +@vindex gnus-refer-thread-limit +The @code{gnus-refer-thread-limit} variable says how many old (i. e., +articles before the first displayed in the current group) headers to +fetch when doing this command. The default is 200. If @code{t}, all +the available headers will be fetched. This variable can be overridden +by giving the @kbd{A T} command a numerical prefix. + +@item M-^ (Summary) +@findex gnus-summary-refer-article +@kindex M-^ (Summary) +@cindex Message-ID +@cindex fetching by Message-ID +You can also ask the @sc{nntp} server for an arbitrary article, no +matter what group it belongs to. @kbd{M-^} +(@code{gnus-summary-refer-article}) will ask you for a +@code{Message-ID}, which is one of those long, hard-to-read thingies +that look something like @samp{<38o6up$6f2@@hymir.ifi.uio.no>}. You +have to get it all exactly right. No fuzzy searches, I'm afraid. +@end table + +The current select method will be used when fetching by +@code{Message-ID} from non-news select method, but you can override this +by giving this command a prefix. + +@vindex gnus-refer-article-method +If the group you are reading is located on a backend that does not +support fetching by @code{Message-ID} very well (like @code{nnspool}), +you can set @code{gnus-refer-article-method} to an @sc{nntp} method. It +would, perhaps, be best if the @sc{nntp} server you consult is the one +updating the spool you are reading from, but that's not really +necessary. + +Most of the mail backends support fetching by @code{Message-ID}, but do +not do a particularly excellent job at it. That is, @code{nnmbox} and +@code{nnbabyl} are able to locate articles from any groups, while +@code{nnml} and @code{nnfolder} are only able to locate articles that +have been posted to the current group. (Anything else would be too time +consuming.) @code{nnmh} does not support this at all. + + +@node Alternative Approaches +@section Alternative Approaches + +Different people like to read news using different methods. This being +Gnus, we offer a small selection of minor modes for the summary buffers. + +@menu +* Pick and Read:: First mark articles and then read them. +* Binary Groups:: Auto-decode all articles. +@end menu + + +@node Pick and Read +@subsection Pick and Read +@cindex pick and read + +Some newsreaders (like @code{nn} and, uhm, @code{Netnews} on VM/CMS) use +a two-phased reading interface. The user first marks in a summary +buffer the articles she wants to read. Then she starts reading the +articles with just an article buffer displayed. + +@findex gnus-pick-mode +@kindex M-x gnus-pick-mode +Gnus provides a summary buffer minor mode that allows +this---@code{gnus-pick-mode}. This basically means that a few process +mark commands become one-keystroke commands to allow easy marking, and +it provides one additional command for switching to the summary buffer. + +Here are the available keystrokes when using pick mode: + +@table @kbd +@item . +@kindex . (Pick) +@findex gnus-pick-article-or-thread +Pick the article or thread on the current line +(@code{gnus-pick-article-or-thread}). If the variable +@code{gnus-thread-hide-subtree} is true, then this key selects the +entire thread when used at the first article of the thread. Otherwise, +it selects just the article. If given a numerical prefix, go to that +thread or article and pick it. (The line number is normally displayed +at the beginning of the summary pick lines.) + +@item SPACE +@kindex SPACE (Pick) +@findex gnus-pick-next-page +Scroll the summary buffer up one page (@code{gnus-pick-next-page}). If +at the end of the buffer, start reading the picked articles. + +@item u +@kindex u (Pick) +@findex gnus-pick-unmark-article-or-thread. +Unpick the thread or article +(@code{gnus-pick-unmark-article-or-thread}). If the variable +@code{gnus-thread-hide-subtree} is true, then this key unpicks the +thread if used at the first article of the thread. Otherwise it unpicks +just the article. You can give this key a numerical prefix to unpick +the thread or article at that line. + +@item RET +@kindex RET (Pick) +@findex gnus-pick-start-reading +@vindex gnus-pick-display-summary +Start reading the picked articles (@code{gnus-pick-start-reading}). If +given a prefix, mark all unpicked articles as read first. If +@code{gnus-pick-display-summary} is non-@code{nil}, the summary buffer +will still be visible when you are reading. + +@end table + +All the normal summary mode commands are still available in the +pick-mode, with the exception of @kbd{u}. However @kbd{!} is available +which is mapped to the same function +@code{gnus-summary-tick-article-forward}. + +If this sounds like a good idea to you, you could say: + +@lisp +(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode) +@end lisp + +@vindex gnus-pick-mode-hook +@code{gnus-pick-mode-hook} is run in pick minor mode buffers. + +@vindex gnus-mark-unpicked-articles-as-read +If @code{gnus-mark-unpicked-articles-as-read} is non-@code{nil}, mark +all unpicked articles as read. The default is @code{nil}. + +@vindex gnus-summary-pick-line-format +The summary line format in pick mode is slightly different from the +standard format. At the beginning of each line the line number is +displayed. The pick mode line format is controlled by the +@code{gnus-summary-pick-line-format} variable (@pxref{Formatting +Variables}). It accepts the same format specs that +@code{gnus-summary-line-format} does (@pxref{Summary Buffer Lines}). + + +@node Binary Groups +@subsection Binary Groups +@cindex binary groups + +@findex gnus-binary-mode +@kindex M-x gnus-binary-mode +If you spend much time in binary groups, you may grow tired of hitting +@kbd{X u}, @kbd{n}, @kbd{RET} all the time. @kbd{M-x gnus-binary-mode} +is a minor mode for summary buffers that makes all ordinary Gnus article +selection functions uudecode series of articles and display the result +instead of just displaying the articles the normal way. + +@kindex g (Binary) +@findex gnus-binary-show-article +The only way, in fact, to see the actual articles is the @kbd{g} +command, when you have turned on this mode +(@code{gnus-binary-show-article}). + +@vindex gnus-binary-mode-hook +@code{gnus-binary-mode-hook} is called in binary minor mode buffers. + + +@node Tree Display +@section Tree Display +@cindex trees + +@vindex gnus-use-trees +If you don't like the normal Gnus summary display, you might try setting +@code{gnus-use-trees} to @code{t}. This will create (by default) an +additional @dfn{tree buffer}. You can execute all summary mode commands +in the tree buffer. + +There are a few variables to customize the tree display, of course: + +@table @code +@item gnus-tree-mode-hook +@vindex gnus-tree-mode-hook +A hook called in all tree mode buffers. + +@item gnus-tree-mode-line-format +@vindex gnus-tree-mode-line-format +A format string for the mode bar in the tree mode buffers (@pxref{Mode +Line Formatting}). The default is @samp{Gnus: %%b %S %Z}. For a list +of valid specs, @pxref{Summary Buffer Mode Line}. + +@item gnus-selected-tree-face +@vindex gnus-selected-tree-face +Face used for highlighting the selected article in the tree buffer. The +default is @code{modeline}. + +@item gnus-tree-line-format +@vindex gnus-tree-line-format +A format string for the tree nodes. The name is a bit of a misnomer, +though---it doesn't define a line, but just the node. The default value +is @samp{%(%[%3,3n%]%)}, which displays the first three characters of +the name of the poster. It is vital that all nodes are of the same +length, so you @emph{must} use @samp{%4,4n}-like specifiers. + +Valid specs are: + +@table @samp +@item n +The name of the poster. +@item f +The @code{From} header. +@item N +The number of the article. +@item [ +The opening bracket. +@item ] +The closing bracket. +@item s +The subject. +@end table + +@xref{Formatting Variables}. + +Variables related to the display are: + +@table @code +@item gnus-tree-brackets +@vindex gnus-tree-brackets +This is used for differentiating between ``real'' articles and +``sparse'' articles. The format is @var{((real-open . real-close) +(sparse-open . sparse-close) (dummy-open . dummy-close))}, and the +default is @code{((?[ . ?]) (?( . ?)) (?@{ . ?@}) (?< . ?>))}. + +@item gnus-tree-parent-child-edges +@vindex gnus-tree-parent-child-edges +This is a list that contains the characters used for connecting parent +nodes to their children. The default is @code{(?- ?\\ ?|)}. + +@end table + +@item gnus-tree-minimize-window +@vindex gnus-tree-minimize-window +If this variable is non-@code{nil}, Gnus will try to keep the tree +buffer as small as possible to allow more room for the other Gnus +windows. If this variable is a number, the tree buffer will never be +higher than that number. The default is @code{t}. Note that if you +have several windows displayed side-by-side in a frame and the tree +buffer is one of these, minimizing the tree window will also resize all +other windows displayed next to it. + +@item gnus-generate-tree-function +@vindex gnus-generate-tree-function +@findex gnus-generate-horizontal-tree +@findex gnus-generate-vertical-tree +The function that actually generates the thread tree. Two predefined +functions are available: @code{gnus-generate-horizontal-tree} and +@code{gnus-generate-vertical-tree} (which is the default). + +@end table + +Here's an example from a horizontal tree buffer: + +@example +@{***@}-(***)-[odd]-[Gun] + | \[Jan] + | \[odd]-[Eri] + | \(***)-[Eri] + | \[odd]-[Paa] + \[Bjo] + \[Gun] + \[Gun]-[Jor] +@end example + +Here's the same thread displayed in a vertical tree buffer: + +@example +@{***@} + |--------------------------\-----\-----\ +(***) [Bjo] [Gun] [Gun] + |--\-----\-----\ | +[odd] [Jan] [odd] (***) [Jor] + | | |--\ +[Gun] [Eri] [Eri] [odd] + | + [Paa] +@end example + +If you're using horizontal trees, it might be nice to display the trees +side-by-side with the summary buffer. You could add something like the +following to your @file{.gnus.el} file: + +@lisp +(setq gnus-use-trees t + gnus-generate-tree-function 'gnus-generate-horizontal-tree + gnus-tree-minimize-window nil) +(gnus-add-configuration + '(article + (vertical 1.0 + (horizontal 0.25 + (summary 0.75 point) + (tree 1.0)) + (article 1.0)))) +@end lisp + +@xref{Windows Configuration}. + + +@node Mail Group Commands +@section Mail Group Commands +@cindex mail group commands + +Some commands only make sense in mail groups. If these commands are +invalid in the current group, they will raise a hell and let you know. + +All these commands (except the expiry and edit commands) use the +process/prefix convention (@pxref{Process/Prefix}). + +@table @kbd + +@item B e +@kindex B e (Summary) +@findex gnus-summary-expire-articles +Expire all expirable articles in the group +(@code{gnus-summary-expire-articles}). + +@item B M-C-e +@kindex B M-C-e (Summary) +@findex gnus-summary-expire-articles-now +Delete all the expirable articles in the group +(@code{gnus-summary-expire-articles-now}). This means that @strong{all} +articles eligible for expiry in the current group will +disappear forever into that big @file{/dev/null} in the sky. + +@item B DEL +@kindex B DEL (Summary) +@findex gnus-summary-delete-article +@c @icon{gnus-summary-mail-delete} +Delete the mail article. This is ``delete'' as in ``delete it from your +disk forever and ever, never to return again.'' Use with caution. +(@code{gnus-summary-delete-article}). + +@item B m +@kindex B m (Summary) +@cindex move mail +@findex gnus-summary-move-article +Move the article from one mail group to another +(@code{gnus-summary-move-article}). + +@item B c +@kindex B c (Summary) +@cindex copy mail +@findex gnus-summary-copy-article +@c @icon{gnus-summary-mail-copy} +Copy the article from one group (mail group or not) to a mail group +(@code{gnus-summary-copy-article}). + +@item B B +@kindex B B (Summary) +@cindex crosspost mail +@findex gnus-summary-crosspost-article +Crosspost the current article to some other group +(@code{gnus-summary-crosspost-article}). This will create a new copy of +the article in the other group, and the Xref headers of the article will +be properly updated. + +@item B i +@kindex B i (Summary) +@findex gnus-summary-import-article +Import an arbitrary file into the current mail newsgroup +(@code{gnus-summary-import-article}). You will be prompted for a file +name, a @code{From} header and a @code{Subject} header. + +@item B r +@kindex B r (Summary) +@findex gnus-summary-respool-article +Respool the mail article (@code{gnus-summary-respool-article}). +@code{gnus-summary-respool-default-method} will be used as the default +select method when respooling. This variable is @code{nil} by default, +which means that the current group select method will be used instead. + +@item B w +@itemx e +@kindex B w (Summary) +@kindex e (Summary) +@findex gnus-summary-edit-article +@kindex C-c C-c (Article) +Edit the current article (@code{gnus-summary-edit-article}). To finish +editing and make the changes permanent, type @kbd{C-c C-c} +(@kbd{gnus-summary-edit-article-done}). If you give a prefix to the +@kbd{C-c C-c} command, Gnus won't re-highlight the article. + +@item B q +@kindex B q (Summary) +@findex gnus-summary-respool-query +If you want to re-spool an article, you might be curious as to what group +the article will end up in before you do the re-spooling. This command +will tell you (@code{gnus-summary-respool-query}). + +@item B t +@kindex B t (Summary) +@findex gnus-summary-respool-trace +Similarly, this command will display all fancy splitting patterns used +when repooling, if any (@code{gnus-summary-respool-trace}). + +@item B p +@kindex B p (Summary) +@findex gnus-summary-article-posted-p +Some people have a tendency to send you "courtesy" copies when they +follow up to articles you have posted. These usually have a +@code{Newsgroups} header in them, but not always. This command +(@code{gnus-summary-article-posted-p}) will try to fetch the current +article from your news server (or rather, from +@code{gnus-refer-article-method} or @code{gnus-select-method}) and will +report back whether it found the article or not. Even if it says that +it didn't find the article, it may have been posted anyway---mail +propagation is much faster than news propagation, and the news copy may +just not have arrived yet. + +@end table + +@vindex gnus-move-split-methods +@cindex moving articles +If you move (or copy) articles regularly, you might wish to have Gnus +suggest where to put the articles. @code{gnus-move-split-methods} is a +variable that uses the same syntax as @code{gnus-split-methods} +(@pxref{Saving Articles}). You may customize that variable to create +suggestions you find reasonable. + +@lisp +(setq gnus-move-split-methods + '(("^From:.*Lars Magne" "nnml:junk") + ("^Subject:.*gnus" "nnfolder:important") + (".*" "nnml:misc"))) +@end lisp + + +@node Various Summary Stuff +@section Various Summary Stuff + +@menu +* Summary Group Information:: Information oriented commands. +* Searching for Articles:: Multiple article commands. +* Summary Generation Commands:: (Re)generating the summary buffer. +* Really Various Summary Commands:: Those pesky non-conformant commands. +@end menu + +@table @code +@vindex gnus-summary-mode-hook +@item gnus-summary-mode-hook +This hook is called when creating a summary mode buffer. + +@vindex gnus-summary-generate-hook +@item gnus-summary-generate-hook +This is called as the last thing before doing the threading and the +generation of the summary buffer. It's quite convenient for customizing +the threading variables based on what data the newsgroup has. This hook +is called from the summary buffer after most summary buffer variables +have been set. + +@vindex gnus-summary-prepare-hook +@item gnus-summary-prepare-hook +It is called after the summary buffer has been generated. You might use +it to, for instance, highlight lines or modify the look of the buffer in +some other ungodly manner. I don't care. + +@vindex gnus-summary-ignore-duplicates +@item gnus-summary-ignore-duplicates +When Gnus discovers two articles that have the same @code{Message-ID}, +it has to do something drastic. No articles are allowed to have the +same @code{Message-ID}, but this may happen when reading mail from some +sources. Gnus allows you to customize what happens with this variable. +If it is @code{nil} (which is the default), Gnus will rename the +@code{Message-ID} (for display purposes only) and display the article as +any other article. If this variable is @code{t}, it won't display the +article---it'll be as if it never existed. + +@end table + + +@node Summary Group Information +@subsection Summary Group Information + +@table @kbd + +@item H f +@kindex H f (Summary) +@findex gnus-summary-fetch-faq +@vindex gnus-group-faq-directory +Try to fetch the FAQ (list of frequently asked questions) for the +current group (@code{gnus-summary-fetch-faq}). Gnus will try to get the +FAQ from @code{gnus-group-faq-directory}, which is usually a directory +on a remote machine. This variable can also be a list of directories. +In that case, giving a prefix to this command will allow you to choose +between the various sites. @code{ange-ftp} or @code{efs} will probably +be used for fetching the file. + +@item H d +@kindex H d (Summary) +@findex gnus-summary-describe-group +Give a brief description of the current group +(@code{gnus-summary-describe-group}). If given a prefix, force +rereading the description from the server. + +@item H h +@kindex H h (Summary) +@findex gnus-summary-describe-briefly +Give an extremely brief description of the most important summary +keystrokes (@code{gnus-summary-describe-briefly}). + +@item H i +@kindex H i (Summary) +@findex gnus-info-find-node +Go to the Gnus info node (@code{gnus-info-find-node}). +@end table + + +@node Searching for Articles +@subsection Searching for Articles + +@table @kbd + +@item M-s +@kindex M-s (Summary) +@findex gnus-summary-search-article-forward +Search through all subsequent articles for a regexp +(@code{gnus-summary-search-article-forward}). + +@item M-r +@kindex M-r (Summary) +@findex gnus-summary-search-article-backward +Search through all previous articles for a regexp +(@code{gnus-summary-search-article-backward}). + +@item & +@kindex & (Summary) +@findex gnus-summary-execute-command +This command will prompt you for a header field, a regular expression to +match on this field, and a command to be executed if the match is made +(@code{gnus-summary-execute-command}). If given a prefix, search +backward instead. + +@item M-& +@kindex M-& (Summary) +@findex gnus-summary-universal-argument +Perform any operation on all articles that have been marked with +the process mark (@code{gnus-summary-universal-argument}). +@end table + +@node Summary Generation Commands +@subsection Summary Generation Commands + +@table @kbd + +@item Y g +@kindex Y g (Summary) +@findex gnus-summary-prepare +Regenerate the current summary buffer (@code{gnus-summary-prepare}). + +@item Y c +@kindex Y c (Summary) +@findex gnus-summary-insert-cached-articles +Pull all cached articles (for the current group) into the summary buffer +(@code{gnus-summary-insert-cached-articles}). + +@end table + + +@node Really Various Summary Commands +@subsection Really Various Summary Commands + +@table @kbd + +@item C-d +@kindex C-d (Summary) +@findex gnus-summary-enter-digest-group +If the current article is a collection of other articles (for instance, +a digest), you might use this command to enter a group based on the that +article (@code{gnus-summary-enter-digest-group}). Gnus will try to +guess what article type is currently displayed unless you give a prefix +to this command, which forces a ``digest'' interpretation. Basically, +whenever you see a message that is a collection of other messages of +some format, you @kbd{C-d} and read these messages in a more convenient +fashion. + +@item M-C-d +@kindex M-C-d (Summary) +@findex gnus-summary-read-document +This command is very similar to the one above, but lets you gather +several documents into one biiig group +(@code{gnus-summary-read-document}). It does this by opening several +@code{nndoc} groups for each document, and then opening an +@code{nnvirtual} group on top of these @code{nndoc} groups. This +command understands the process/prefix convention +(@pxref{Process/Prefix}). + +@item C-t +@kindex C-t (Summary) +@findex gnus-summary-toggle-truncation +Toggle truncation of summary lines +(@code{gnus-summary-toggle-truncation}). This will probably confuse the +line centering function in the summary buffer, so it's not a good idea +to have truncation switched off while reading articles. + +@item = +@kindex = (Summary) +@findex gnus-summary-expand-window +Expand the summary buffer window (@code{gnus-summary-expand-window}). +If given a prefix, force an @code{article} window configuration. + +@item M-C-e +@kindex M-C-e (Summary) +@findex gnus-summary-edit-parameters +Edit the group parameters (@pxref{Group Parameters}) of the current +group (@code{gnus-summary-edit-parameters}). + +@end table + + +@node Exiting the Summary Buffer +@section Exiting the Summary Buffer +@cindex summary exit +@cindex exiting groups + +Exiting from the summary buffer will normally update all info on the +group and return you to the group buffer. + +@table @kbd + +@item Z Z +@itemx q +@kindex Z Z (Summary) +@kindex q (Summary) +@findex gnus-summary-exit +@vindex gnus-summary-exit-hook +@vindex gnus-summary-prepare-exit-hook +@c @icon{gnus-summary-exit} +Exit the current group and update all information on the group +(@code{gnus-summary-exit}). @code{gnus-summary-prepare-exit-hook} is +called before doing much of the exiting, which calls +@code{gnus-summary-expire-articles} by default. +@code{gnus-summary-exit-hook} is called after finishing the exit +process. @code{gnus-group-no-more-groups-hook} is run when returning to +group mode having no more (unread) groups. + +@item Z E +@itemx Q +@kindex Z E (Summary) +@kindex Q (Summary) +@findex gnus-summary-exit-no-update +Exit the current group without updating any information on the group +(@code{gnus-summary-exit-no-update}). + +@item Z c +@itemx c +@kindex Z c (Summary) +@kindex c (Summary) +@findex gnus-summary-catchup-and-exit +@c @icon{gnus-summary-catchup-and-exit} +Mark all unticked articles in the group as read and then exit +(@code{gnus-summary-catchup-and-exit}). + +@item Z C +@kindex Z C (Summary) +@findex gnus-summary-catchup-all-and-exit +Mark all articles, even the ticked ones, as read and then exit +(@code{gnus-summary-catchup-all-and-exit}). + +@item Z n +@kindex Z n (Summary) +@findex gnus-summary-catchup-and-goto-next-group +Mark all articles as read and go to the next group +(@code{gnus-summary-catchup-and-goto-next-group}). + +@item Z R +@kindex Z R (Summary) +@findex gnus-summary-reselect-current-group +Exit this group, and then enter it again +(@code{gnus-summary-reselect-current-group}). If given a prefix, select +all articles, both read and unread. + +@item Z G +@itemx M-g +@kindex Z G (Summary) +@kindex M-g (Summary) +@findex gnus-summary-rescan-group +@c @icon{gnus-summary-mail-get} +Exit the group, check for new articles in the group, and select the +group (@code{gnus-summary-rescan-group}). If given a prefix, select all +articles, both read and unread. + +@item Z N +@kindex Z N (Summary) +@findex gnus-summary-next-group +Exit the group and go to the next group +(@code{gnus-summary-next-group}). + +@item Z P +@kindex Z P (Summary) +@findex gnus-summary-prev-group +Exit the group and go to the previous group +(@code{gnus-summary-prev-group}). + +@item Z s +@kindex Z s (Summary) +@findex gnus-summary-save-newsrc +Save the current number of read/marked articles in the dribble buffer +and then save the dribble buffer (@code{gnus-summary-save-newsrc}). If +given a prefix, also save the @file{.newsrc} file(s). Using this +command will make exit without updating (the @kbd{Q} command) worthless. +@end table + +@vindex gnus-exit-group-hook +@code{gnus-exit-group-hook} is called when you exit the current +group. + +@findex gnus-summary-wake-up-the-dead +@findex gnus-dead-summary-mode +@vindex gnus-kill-summary-on-exit +If you're in the habit of exiting groups, and then changing your mind +about it, you might set @code{gnus-kill-summary-on-exit} to @code{nil}. +If you do that, Gnus won't kill the summary buffer when you exit it. +(Quelle surprise!) Instead it will change the name of the buffer to +something like @samp{*Dead Summary ... *} and install a minor mode +called @code{gnus-dead-summary-mode}. Now, if you switch back to this +buffer, you'll find that all keys are mapped to a function called +@code{gnus-summary-wake-up-the-dead}. So tapping any keys in a dead +summary buffer will result in a live, normal summary buffer. + +There will never be more than one dead summary buffer at any one time. + +@vindex gnus-use-cross-reference +The data on the current group will be updated (which articles you have +read, which articles you have replied to, etc.) when you exit the +summary buffer. If the @code{gnus-use-cross-reference} variable is +@code{t} (which is the default), articles that are cross-referenced to +this group and are marked as read, will also be marked as read in the +other subscribed groups they were cross-posted to. If this variable is +neither @code{nil} nor @code{t}, the article will be marked as read in +both subscribed and unsubscribed groups (@pxref{Crosspost Handling}). + + +@node Crosspost Handling +@section Crosspost Handling + +@cindex velveeta +@cindex spamming +Marking cross-posted articles as read ensures that you'll never have to +read the same article more than once. Unless, of course, somebody has +posted it to several groups separately. Posting the same article to +several groups (not cross-posting) is called @dfn{spamming}, and you are +by law required to send nasty-grams to anyone who perpetrates such a +heinous crime. You may want to try NoCeM handling to filter out spam +(@pxref{NoCeM}). + +Remember: Cross-posting is kinda ok, but posting the same article +separately to several groups is not. Massive cross-posting (aka. +@dfn{velveeta}) is to be avoided at all costs, and you can even use the +@code{gnus-summary-mail-crosspost-complaint} command to complain about +excessive crossposting (@pxref{Summary Mail Commands}). + +@cindex cross-posting +@cindex Xref +@cindex @sc{nov} +One thing that may cause Gnus to not do the cross-posting thing +correctly is if you use an @sc{nntp} server that supports @sc{xover} +(which is very nice, because it speeds things up considerably) which +does not include the @code{Xref} header in its @sc{nov} lines. This is +Evil, but all too common, alas, alack. Gnus tries to Do The Right Thing +even with @sc{xover} by registering the @code{Xref} lines of all +articles you actually read, but if you kill the articles, or just mark +them as read without reading them, Gnus will not get a chance to snoop +the @code{Xref} lines out of these articles, and will be unable to use +the cross reference mechanism. + +@cindex LIST overview.fmt +@cindex overview.fmt +To check whether your @sc{nntp} server includes the @code{Xref} header +in its overview files, try @samp{telnet your.nntp.server nntp}, +@samp{MODE READER} on @code{inn} servers, and then say @samp{LIST +overview.fmt}. This may not work, but if it does, and the last line you +get does not read @samp{Xref:full}, then you should shout and whine at +your news admin until she includes the @code{Xref} header in the +overview files. + +@vindex gnus-nov-is-evil +If you want Gnus to get the @code{Xref}s right all the time, you have to +set @code{gnus-nov-is-evil} to @code{t}, which slows things down +considerably. + +C'est la vie. + +For an alternative approach, @pxref{Duplicate Suppression}. + + +@node Duplicate Suppression +@section Duplicate Suppression + +By default, Gnus tries to make sure that you don't have to read the same +article more than once by utilizing the crossposting mechanism +(@pxref{Crosspost Handling}). However, that simple and efficient +approach may not work satisfactory for some users for various +reasons. + +@enumerate +@item +The @sc{nntp} server may fail to generate the @code{Xref} header. This +is evil and not very common. + +@item +The @sc{nntp} server may fail to include the @code{Xref} header in the +@file{.overview} data bases. This is evil and all too common, alas. + +@item +You may be reading the same group (or several related groups) from +different @sc{nntp} servers. + +@item +You may be getting mail that duplicates articles posted to groups. +@end enumerate + +I'm sure there are other situations where @code{Xref} handling fails as +well, but these four are the most common situations. + +If, and only if, @code{Xref} handling fails for you, then you may +consider switching on @dfn{duplicate suppression}. If you do so, Gnus +will remember the @code{Message-ID}s of all articles you have read or +otherwise marked as read, and then, as if by magic, mark them as read +all subsequent times you see them---in @emph{all} groups. Using this +mechanism is quite likely to be somewhat inefficient, but not overly +so. It's certainly preferable to reading the same articles more than +once. + +Duplicate suppression is not a very subtle instrument. It's more like a +sledge hammer than anything else. It works in a very simple +fashion---if you have marked an article as read, it adds this Message-ID +to a cache. The next time it sees this Message-ID, it will mark the +article as read with the @samp{M} mark. It doesn't care what group it +saw the article in. + +@table @code +@item gnus-suppress-duplicates +@vindex gnus-suppress-duplicates +If non-@code{nil}, suppress duplicates. + +@item gnus-save-duplicate-list +@vindex gnus-save-duplicate-list +If non-@code{nil}, save the list of duplicates to a file. This will +make startup and shutdown take longer, so the default is @code{nil}. +However, this means that only duplicate articles read in a single Gnus +session are suppressed. + +@item gnus-duplicate-list-length +@vindex gnus-duplicate-list-length +This variable says how many @code{Message-ID}s to keep in the duplicate +suppression list. The default is 10000. + +@item gnus-duplicate-file +@vindex gnus-duplicate-file +The name of the file to store the duplicate suppression list in. The +default is @file{~/News/suppression}. +@end table + +If you have a tendency to stop and start Gnus often, setting +@code{gnus-save-duplicate-list} to @code{t} is probably a good idea. If +you leave Gnus running for weeks on end, you may have it @code{nil}. On +the other hand, saving the list makes startup and shutdown much slower, +so that means that if you stop and start Gnus often, you should set +@code{gnus-save-duplicate-list} to @code{nil}. Uhm. I'll leave this up +to you to figure out, I think. + + +@node The Article Buffer +@chapter The Article Buffer +@cindex article buffer + +The articles are displayed in the article buffer, of which there is only +one. All the summary buffers share the same article buffer unless you +tell Gnus otherwise. + +@menu +* Hiding Headers:: Deciding what headers should be displayed. +* Using MIME:: Pushing articles through @sc{mime} before reading them. +* Customizing Articles:: Tailoring the look of the articles. +* Article Keymap:: Keystrokes available in the article buffer. +* Misc Article:: Other stuff. +@end menu + + +@node Hiding Headers +@section Hiding Headers +@cindex hiding headers +@cindex deleting headers + +The top section of each article is the @dfn{head}. (The rest is the +@dfn{body}, but you may have guessed that already.) + +@vindex gnus-show-all-headers +There is a lot of useful information in the head: the name of the person +who wrote the article, the date it was written and the subject of the +article. That's well and nice, but there's also lots of information +most people do not want to see---what systems the article has passed +through before reaching you, the @code{Message-ID}, the +@code{References}, etc. ad nauseum---and you'll probably want to get rid +of some of those lines. If you want to keep all those lines in the +article buffer, you can set @code{gnus-show-all-headers} to @code{t}. + +Gnus provides you with two variables for sifting headers: + +@table @code + +@item gnus-visible-headers +@vindex gnus-visible-headers +If this variable is non-@code{nil}, it should be a regular expression +that says what headers you wish to keep in the article buffer. All +headers that do not match this variable will be hidden. + +For instance, if you only want to see the name of the person who wrote +the article and the subject, you'd say: + +@lisp +(setq gnus-visible-headers "^From:\\|^Subject:") +@end lisp + +This variable can also be a list of regexps to match headers to +remain visible. + +@item gnus-ignored-headers +@vindex gnus-ignored-headers +This variable is the reverse of @code{gnus-visible-headers}. If this +variable is set (and @code{gnus-visible-headers} is @code{nil}), it +should be a regular expression that matches all lines that you want to +hide. All lines that do not match this variable will remain visible. + +For instance, if you just want to get rid of the @code{References} line +and the @code{Xref} line, you might say: + +@lisp +(setq gnus-ignored-headers "^References:\\|^Xref:") +@end lisp + +This variable can also be a list of regexps to match headers to +be removed. + +Note that if @code{gnus-visible-headers} is non-@code{nil}, this +variable will have no effect. + +@end table + +@vindex gnus-sorted-header-list +Gnus can also sort the headers for you. (It does this by default.) You +can control the sorting by setting the @code{gnus-sorted-header-list} +variable. It is a list of regular expressions that says in what order +the headers are to be displayed. + +For instance, if you want the name of the author of the article first, +and then the subject, you might say something like: + +@lisp +(setq gnus-sorted-header-list '("^From:" "^Subject:")) +@end lisp + +Any headers that are to remain visible, but are not listed in this +variable, will be displayed in random order after all the headers listed in this variable. + +@findex gnus-article-hide-boring-headers +@vindex gnus-article-display-hook +@vindex gnus-boring-article-headers +You can hide further boring headers by entering +@code{gnus-article-hide-boring-headers} into +@code{gnus-article-display-hook}. What this function does depends on +the @code{gnus-boring-article-headers} variable. It's a list, but this +list doesn't actually contain header names. Instead is lists various +@dfn{boring conditions} that Gnus can check and remove from sight. + +These conditions are: +@table @code +@item empty +Remove all empty headers. +@item followup-to +Remove the @code{Followup-To} header if it is identical to the +@code{Newsgroups} header. +@item reply-to +Remove the @code{Reply-To} header if it lists the same address as the +@code{From} header. +@item newsgroups +Remove the @code{Newsgroups} header if it only contains the current group +name. +@item date +Remove the @code{Date} header if the article is less than three days +old. +@item long-to +Remove the @code{To} header if it is very long. +@item many-to +Remove all @code{To} headers if there are more than one. +@end table + +To include the four three elements, you could say something like; + +@lisp +(setq gnus-boring-article-headers + '(empty followup-to reply-to)) +@end lisp + +This is also the default value for this variable. + + +@node Using MIME +@section Using @sc{mime} +@cindex @sc{mime} + +Mime is a standard for waving your hands through the air, aimlessly, +while people stand around yawning. + +@sc{mime}, however, is a standard for encoding your articles, aimlessly, +while all newsreaders die of fear. + +@sc{mime} may specify what character set the article uses, the encoding +of the characters, and it also makes it possible to embed pictures and +other naughty stuff in innocent-looking articles. + +@vindex gnus-show-mime +@vindex gnus-show-mime-method +@vindex gnus-strict-mime +@findex metamail-buffer +Gnus handles @sc{mime} by pushing the articles through +@code{gnus-show-mime-method}, which is @code{metamail-buffer} by +default. This function calls the external @code{metamail} program to +actually do the work. One common problem with this program is that is +thinks that it can't display 8-bit things in the Emacs buffer. To tell +it the truth, put something like the following in your +@file{.bash_profile} file. (You do use @code{bash}, don't you?) + +@example +export MM_CHARSET="iso-8859-1" +@end example + +For more information on @code{metamail}, see its manual page. + +Set @code{gnus-show-mime} to @code{t} if you want to use +@sc{mime} all the time. However, if @code{gnus-strict-mime} is +non-@code{nil}, the @sc{mime} method will only be used if there are +@sc{mime} headers in the article. If you have @code{gnus-show-mime} +set, then you'll see some unfortunate display glitches in the article +buffer. These can't be avoided. + +It might be best to just use the toggling functions from the summary +buffer to avoid getting nasty surprises. (For instance, you enter the +group @samp{alt.sing-a-long} and, before you know it, @sc{mime} has +decoded the sound file in the article and some horrible sing-a-long song +comes screaming out your speakers, and you can't find the volume +button, because there isn't one, and people are starting to look at you, +and you try to stop the program, but you can't, and you can't find the +program to control the volume, and everybody else in the room suddenly +decides to look at you disdainfully, and you'll feel rather stupid.) + +Any similarity to real events and people is purely coincidental. Ahem. + + +@node Customizing Articles +@section Customizing Articles +@cindex article customization + +@vindex gnus-article-display-hook +The @code{gnus-article-display-hook} is called after the article has +been inserted into the article buffer. It is meant to handle all +treatment of the article before it is displayed. + +@findex gnus-article-maybe-highlight +@findex gnus-article-maybe-hide-headers +By default this hook just contains +@code{gnus-article-maybe-hide-headers}, +@code{gnus-hide-boring-headers}, @code{gnus-article-treat-overstrike}, +and @code{gnus-article-maybe-highlight} (and under XEmacs, +@code{gnus-article-display-x-face}), but there are thousands, nay +millions, of functions you can put in this hook. For an overview of +functions @pxref{Article Highlighting}, @pxref{Article Hiding}, +@pxref{Article Washing}, @pxref{Article Buttons} and @pxref{Article +Date}. Note that the order of functions in this hook might affect +things, so you may have to fiddle a bit to get the desired results. + +You can, of course, write your own functions. The functions are called +from the article buffer, and you can do anything you like, pretty much. +There is no information that you have to keep in the buffer---you can +change everything. However, you shouldn't delete any headers. Instead +make them invisible if you want to make them go away. + + +@node Article Keymap +@section Article Keymap + +Most of the keystrokes in the summary buffer can also be used in the +article buffer. They should behave as if you typed them in the summary +buffer, which means that you don't actually have to have a summary +buffer displayed while reading. You can do it all from the article +buffer. + +A few additional keystrokes are available: + +@table @kbd + +@item SPACE +@kindex SPACE (Article) +@findex gnus-article-next-page +Scroll forwards one page (@code{gnus-article-next-page}). + +@item DEL +@kindex DEL (Article) +@findex gnus-article-prev-page +Scroll backwards one page (@code{gnus-article-prev-page}). + +@item C-c ^ +@kindex C-c ^ (Article) +@findex gnus-article-refer-article +If point is in the neighborhood of a @code{Message-ID} and you press +@kbd{C-c ^}, Gnus will try to get that article from the server +(@code{gnus-article-refer-article}). + +@item C-c C-m +@kindex C-c C-m (Article) +@findex gnus-article-mail +Send a reply to the address near point (@code{gnus-article-mail}). If +given a prefix, include the mail. + +@item s +@kindex s (Article) +@findex gnus-article-show-summary +Reconfigure the buffers so that the summary buffer becomes visible +(@code{gnus-article-show-summary}). + +@item ? +@kindex ? (Article) +@findex gnus-article-describe-briefly +Give a very brief description of the available keystrokes +(@code{gnus-article-describe-briefly}). + +@item TAB +@kindex TAB (Article) +@findex gnus-article-next-button +Go to the next button, if any (@code{gnus-article-next-button}). This +only makes sense if you have buttonizing turned on. + +@item M-TAB +@kindex M-TAB (Article) +@findex gnus-article-prev-button +Go to the previous button, if any (@code{gnus-article-prev-button}). + +@end table + + +@node Misc Article +@section Misc Article + +@table @code + +@item gnus-single-article-buffer +@vindex gnus-single-article-buffer +If non-@code{nil}, use the same article buffer for all the groups. +(This is the default.) If @code{nil}, each group will have its own +article buffer. + +@vindex gnus-article-prepare-hook +@item gnus-article-prepare-hook +This hook is called right after the article has been inserted into the +article buffer. It is mainly intended for functions that do something +depending on the contents; it should probably not be used for changing +the contents of the article buffer. + +@vindex gnus-article-display-hook +@item gnus-article-display-hook +This hook is called as the last thing when displaying an article, and is +intended for modifying the contents of the buffer, doing highlights, +hiding headers, and the like. + +@item gnus-article-mode-hook +@vindex gnus-article-mode-hook +Hook called in article mode buffers. + +@item gnus-article-mode-syntax-table +@vindex gnus-article-mode-syntax-table +Syntax table used in article buffers. It is initialized from +@code{text-mode-syntax-table}. + +@vindex gnus-article-mode-line-format +@item gnus-article-mode-line-format +This variable is a format string along the same lines as +@code{gnus-summary-mode-line-format} (@pxref{Mode Line Formatting}). It +accepts the same format specifications as that variable, with one +extension: + +@table @samp +@item w +The @dfn{wash status} of the article. This is a short string with one +character for each possible article wash operation that may have been +performed. +@end table + +@vindex gnus-break-pages + +@item gnus-break-pages +Controls whether @dfn{page breaking} is to take place. If this variable +is non-@code{nil}, the articles will be divided into pages whenever a +page delimiter appears in the article. If this variable is @code{nil}, +paging will not be done. + +@item gnus-page-delimiter +@vindex gnus-page-delimiter +This is the delimiter mentioned above. By default, it is @samp{^L} +(formfeed). +@end table + + +@node Composing Messages +@chapter Composing Messages +@cindex composing messages +@cindex messages +@cindex mail +@cindex sending mail +@cindex reply +@cindex followup +@cindex post + +@kindex C-c C-c (Post) +All commands for posting and mailing will put you in a message buffer +where you can edit the article all you like, before you send the article +by pressing @kbd{C-c C-c}. @xref{Top, , Top, message, The Message +Manual}. If you are in a foreign news group, and you wish to post the +article using the foreign server, you can give a prefix to @kbd{C-c C-c} +to make Gnus try to post using the foreign server. + +@menu +* Mail:: Mailing and replying. +* Post:: Posting and following up. +* Posting Server:: What server should you post via? +* Mail and Post:: Mailing and posting at the same time. +* Archived Messages:: Where Gnus stores the messages you've sent. +* Posting Styles:: An easier way to specify who you are. +* Drafts:: Postponing messages and rejected messages. +* Rejected Articles:: What happens if the server doesn't like your article? +@end menu + +Also see @pxref{Canceling and Superseding} for information on how to +remove articles you shouldn't have posted. + + +@node Mail +@section Mail + +Variables for customizing outgoing mail: + +@table @code +@item gnus-uu-digest-headers +@vindex gnus-uu-digest-headers +List of regexps to match headers included in digested messages. The +headers will be included in the sequence they are matched. + +@item gnus-add-to-list +@vindex gnus-add-to-list +If non-@code{nil}, add a @code{to-list} group parameter to mail groups +that have none when you do a @kbd{a}. + +@end table + + +@node Post +@section Post + +Variables for composing news articles: + +@table @code +@item gnus-sent-message-ids-file +@vindex gnus-sent-message-ids-file +Gnus will keep a @code{Message-ID} history file of all the mails it has +sent. If it discovers that it has already sent a mail, it will ask the +user whether to re-send the mail. (This is primarily useful when +dealing with @sc{soup} packets and the like where one is apt to send the +same packet multiple times.) This variable says what the name of this +history file is. It is @file{~/News/Sent-Message-IDs} by default. Set +this variable to @code{nil} if you don't want Gnus to keep a history +file. + +@item gnus-sent-message-ids-length +@vindex gnus-sent-message-ids-length +This variable says how many @code{Message-ID}s to keep in the history +file. It is 1000 by default. + +@end table + + +@node Posting Server +@section Posting Server + +When you press those magical @kbd{C-c C-c} keys to ship off your latest +(extremely intelligent, of course) article, where does it go? + +Thank you for asking. I hate you. + +@vindex gnus-post-method + +It can be quite complicated. Normally, Gnus will use the same native +server. However. If your native server doesn't allow posting, just +reading, you probably want to use some other server to post your +(extremely intelligent and fabulously interesting) articles. You can +then set the @code{gnus-post-method} to some other method: + +@lisp +(setq gnus-post-method '(nnspool "")) +@end lisp + +Now, if you've done this, and then this server rejects your article, or +this server is down, what do you do then? To override this variable you +can use a non-zero prefix to the @kbd{C-c C-c} command to force using +the ``current'' server for posting. + +If you give a zero prefix (i.e., @kbd{C-u 0 C-c C-c}) to that command, +Gnus will prompt you for what method to use for posting. + +You can also set @code{gnus-post-method} to a list of select methods. +If that's the case, Gnus will always prompt you for what method to use +for posting. + +Finally, if you want to always post using the same select method as +you're reading from (which might be convenient if you're reading lots of +groups from different private servers), you can set this variable to +@code{current}. + + +@node Mail and Post +@section Mail and Post + +Here's a list of variables relevant to both mailing and +posting: + +@table @code +@item gnus-mailing-list-groups +@findex gnus-mailing-list-groups +@cindex mailing lists + +If your news server offers groups that are really mailing lists +gatewayed to the @sc{nntp} server, you can read those groups without +problems, but you can't post/followup to them without some difficulty. +One solution is to add a @code{to-address} to the group parameters +(@pxref{Group Parameters}). An easier thing to do is set the +@code{gnus-mailing-list-groups} to a regexp that matches the groups that +really are mailing lists. Then, at least, followups to the mailing +lists will work most of the time. Posting to these groups (@kbd{a}) is +still a pain, though. + +@end table + +You may want to do spell-checking on messages that you send out. Or, if +you don't want to spell-check by hand, you could add automatic +spell-checking via the @code{ispell} package: + +@cindex ispell +@findex ispell-message +@lisp +(add-hook 'message-send-hook 'ispell-message) +@end lisp + + +@node Archived Messages +@section Archived Messages +@cindex archived messages +@cindex sent messages + +Gnus provides a few different methods for storing the mail and news you +send. The default method is to use the @dfn{archive virtual server} to +store the messages. If you want to disable this completely, the +@code{gnus-message-archive-group} variable should be @code{nil}, which +is the default. + +@vindex gnus-message-archive-method +@code{gnus-message-archive-method} says what virtual server Gnus is to +use to store sent messages. The default is: + +@lisp +(nnfolder "archive" + (nnfolder-directory "~/Mail/archive") + (nnfolder-active-file "~/Mail/archive/active") + (nnfolder-get-new-mail nil) + (nnfolder-inhibit-expiry t)) +@end lisp + +You can, however, use any mail select method (@code{nnml}, +@code{nnmbox}, etc.). @code{nnfolder} is a quite likeable select method +for doing this sort of thing, though. If you don't like the default +directory chosen, you could say something like: + +@lisp +(setq gnus-message-archive-method + '(nnfolder "archive" + (nnfolder-inhibit-expiry t) + (nnfolder-active-file "~/News/sent-mail/active") + (nnfolder-directory "~/News/sent-mail/"))) +@end lisp + +@vindex gnus-message-archive-group +@cindex Gcc +Gnus will insert @code{Gcc} headers in all outgoing messages that point +to one or more group(s) on that server. Which group to use is +determined by the @code{gnus-message-archive-group} variable. + +This variable can be used to do the following: + +@itemize @bullet +@item a string +Messages will be saved in that group. +@item a list of strings +Messages will be saved in all those groups. +@item an alist of regexps, functions and forms +When a key ``matches'', the result is used. +@item @code{nil} +No message archiving will take place. This is the default. +@end itemize + +Let's illustrate: + +Just saving to a single group called @samp{MisK}: +@lisp +(setq gnus-message-archive-group "MisK") +@end lisp + +Saving to two groups, @samp{MisK} and @samp{safe}: +@lisp +(setq gnus-message-archive-group '("MisK" "safe")) +@end lisp + +Save to different groups based on what group you are in: +@lisp +(setq gnus-message-archive-group + '(("^alt" "sent-to-alt") + ("mail" "sent-to-mail") + (".*" "sent-to-misc"))) +@end lisp + +More complex stuff: +@lisp +(setq gnus-message-archive-group + '((if (message-news-p) + "misc-news" + "misc-mail"))) +@end lisp + +How about storing all news messages in one file, but storing all mail +messages in one file per month: + +@lisp +(setq gnus-message-archive-group + '((if (message-news-p) + "misc-news" + (concat "mail." (format-time-string + "%Y-%m" (current-time)))))) +@end lisp + +(XEmacs 19.13 doesn't have @code{format-time-string}, so you'll have to +use a different value for @code{gnus-message-archive-group} there.) + +Now, when you send a message off, it will be stored in the appropriate +group. (If you want to disable storing for just one particular message, +you can just remove the @code{Gcc} header that has been inserted.) The +archive group will appear in the group buffer the next time you start +Gnus, or the next time you press @kbd{F} in the group buffer. You can +enter it and read the articles in it just like you'd read any other +group. If the group gets really big and annoying, you can simply rename +if (using @kbd{G r} in the group buffer) to something +nice---@samp{misc-mail-september-1995}, or whatever. New messages will +continue to be stored in the old (now empty) group. + +That's the default method of archiving sent messages. Gnus offers a +different way for the people who don't like the default method. In that +case you should set @code{gnus-message-archive-group} to @code{nil}; +this will disable archiving. + +@table @code +@item gnus-outgoing-message-group +@vindex gnus-outgoing-message-group +All outgoing messages will be put in this group. If you want to store +all your outgoing mail and articles in the group @samp{nnml:archive}, +you set this variable to that value. This variable can also be a list of +group names. + +If you want to have greater control over what group to put each +message in, you can set this variable to a function that checks the +current newsgroup name and then returns a suitable group name (or list +of names). + +This variable can be used instead of @code{gnus-message-archive-group}, +but the latter is the preferred method. +@end table + + +@node Posting Styles +@section Posting Styles +@cindex posting styles +@cindex styles + +All them variables, they make my head swim. + +So what if you want a different @code{Organization} and signature based +on what groups you post to? And you post both from your home machine +and your work machine, and you want different @code{From} lines, and so +on? + +@vindex gnus-posting-styles +One way to do stuff like that is to write clever hooks that change the +variables you need to have changed. That's a bit boring, so somebody +came up with the bright idea of letting the user specify these things in +a handy alist. Here's an example of a @code{gnus-posting-styles} +variable: + +@lisp +((".*" + (signature "Peace and happiness") + (organization "What me?")) + ("^comp" + (signature "Death to everybody")) + ("comp.emacs.i-love-it" + (organization "Emacs is it"))) +@end lisp + +As you might surmise from this example, this alist consists of several +@dfn{styles}. Each style will be applicable if the first element +``matches'', in some form or other. The entire alist will be iterated +over, from the beginning towards the end, and each match will be +applied, which means that attributes in later styles that match override +the same attributes in earlier matching styles. So +@samp{comp.programming.literate} will have the @samp{Death to everybody} +signature and the @samp{What me?} @code{Organization} header. + +The first element in each style is called the @code{match}. If it's a +string, then Gnus will try to regexp match it against the group name. +If it's a function symbol, that function will be called with no +arguments. If it's a variable symbol, then the variable will be +referenced. If it's a list, then that list will be @code{eval}ed. In +any case, if this returns a non-@code{nil} value, then the style is said +to @dfn{match}. + +Each style may contain a arbitrary amount of @dfn{attributes}. Each +attribute consists of a @var{(name . value)} pair. The attribute name +can be one of @code{signature}, @code{signature-file}, +@code{organization}, @code{address}, @code{name} or @code{body}. The +attribute name can also be a string. In that case, this will be used as +a header name, and the value will be inserted in the headers of the +article. + +The attribute value can be a string (used verbatim), a function (the +return value will be used), a variable (its value will be used) or a +list (it will be @code{eval}ed and the return value will be used). + +If you wish to check whether the message you are about to compose is +meant to be a news article or a mail message, you can check the values +of the two dynamically bound variables @code{message-this-is-news} and +@code{message-this-is-mail}. + +@vindex message-this-is-mail +@vindex message-this-is-news + +So here's a new example: + +@lisp +(setq gnus-posting-styles + '((".*" + (signature-file "~/.signature") + (name "User Name") + ("X-Home-Page" (getenv "WWW_HOME")) + (organization "People's Front Against MWM")) + ("^rec.humor" + (signature my-funny-signature-randomizer)) + ((equal (system-name) "gnarly") + (signature my-quote-randomizer)) + (message-this-is-news + (signature my-news-signature)) + (posting-from-work-p + (signature-file "~/.work-signature") + (address "user@@bar.foo") + (body "You are fired.\n\nSincerely, your boss.") + (organization "Important Work, Inc")) + ("^nn.+:" + (signature-file "~/.mail-signature")))) +@end lisp + + +@node Drafts +@section Drafts +@cindex drafts + +If you are writing a message (mail or news) and suddenly remember that +you have a steak in the oven (or some pesto in the food processor, you +craaazy vegetarians), you'll probably wish there was a method to save +the message you are writing so that you can continue editing it some +other day, and send it when you feel its finished. + +Well, don't worry about it. Whenever you start composing a message of +some sort using the Gnus mail and post commands, the buffer you get will +automatically associate to an article in a special @dfn{draft} group. +If you save the buffer the normal way (@kbd{C-x C-s}, for instance), the +article will be saved there. (Auto-save files also go to the draft +group.) + +@cindex nndraft +@vindex nndraft-directory +The draft group is a special group (which is implemented as an +@code{nndraft} group, if you absolutely have to know) called +@samp{nndraft:drafts}. The variable @code{nndraft-directory} says where +@code{nndraft} is to store its files. What makes this group special is +that you can't tick any articles in it or mark any articles as +read---all articles in the group are permanently unread. + +If the group doesn't exist, it will be created and you'll be subscribed +to it. The only way to make it disappear from the Group buffer is to +unsubscribe it. + +@c @findex gnus-dissociate-buffer-from-draft +@c @kindex C-c M-d (Mail) +@c @kindex C-c M-d (Post) +@c @findex gnus-associate-buffer-with-draft +@c @kindex C-c C-d (Mail) +@c @kindex C-c C-d (Post) +@c If you're writing some super-secret message that you later want to +@c encode with PGP before sending, you may wish to turn the auto-saving +@c (and association with the draft group) off. You never know who might be +@c interested in reading all your extremely valuable and terribly horrible +@c and interesting secrets. The @kbd{C-c M-d} +@c (@code{gnus-dissociate-buffer-from-draft}) command does that for you. +@c If you change your mind and want to turn the auto-saving back on again, +@c @kbd{C-c C-d} (@code{gnus-associate-buffer-with-draft} does that. +@c +@c @vindex gnus-use-draft +@c To leave association with the draft group off by default, set +@c @code{gnus-use-draft} to @code{nil}. It is @code{t} by default. + +@findex gnus-draft-edit-message +@kindex D e (Draft) +When you want to continue editing the article, you simply enter the +draft group and push @kbd{D e} (@code{gnus-draft-edit-message}) to do +that. You will be placed in a buffer where you left off. + +Rejected articles will also be put in this draft group (@pxref{Rejected +Articles}). + +@findex gnus-draft-send-all-messages +@findex gnus-draft-send-message +If you have lots of rejected messages you want to post (or mail) without +doing further editing, you can use the @kbd{D s} command +(@code{gnus-draft-send-message}). This command understands the +process/prefix convention (@pxref{Process/Prefix}). The @kbd{D S} +command (@code{gnus-draft-send-all-messages}) will ship off all messages +in the buffer. + +If you have some messages that you wish not to send, you can use the +@kbd{D t} (@code{gnus-draft-toggle-sending}) command to mark the message +as unsendable. This is a toggling command. + + +@node Rejected Articles +@section Rejected Articles +@cindex rejected articles + +Sometimes a news server will reject an article. Perhaps the server +doesn't like your face. Perhaps it just feels miserable. Perhaps +@emph{there be demons}. Perhaps you have included too much cited text. +Perhaps the disk is full. Perhaps the server is down. + +These situations are, of course, totally beyond the control of Gnus. +(Gnus, of course, loves the way you look, always feels great, has angels +fluttering around inside of it, doesn't care about how much cited text +you include, never runs full and never goes down.) So Gnus saves these +articles until some later time when the server feels better. + +The rejected articles will automatically be put in a special draft group +(@pxref{Drafts}). When the server comes back up again, you'd then +typically enter that group and send all the articles off. + + +@node Select Methods +@chapter Select Methods +@cindex foreign groups +@cindex select methods + +A @dfn{foreign group} is a group not read by the usual (or +default) means. It could be, for instance, a group from a different +@sc{nntp} server, it could be a virtual group, or it could be your own +personal mail group. + +A foreign group (or any group, really) is specified by a @dfn{name} and +a @dfn{select method}. To take the latter first, a select method is a +list where the first element says what backend to use (e.g. @code{nntp}, +@code{nnspool}, @code{nnml}) and the second element is the @dfn{server +name}. There may be additional elements in the select method, where the +value may have special meaning for the backend in question. + +One could say that a select method defines a @dfn{virtual server}---so +we do just that (@pxref{The Server Buffer}). + +The @dfn{name} of the group is the name the backend will recognize the +group as. + +For instance, the group @samp{soc.motss} on the @sc{nntp} server +@samp{some.where.edu} will have the name @samp{soc.motss} and select +method @code{(nntp "some.where.edu")}. Gnus will call this group +@samp{nntp+some.where.edu:soc.motss}, even though the @code{nntp} +backend just knows this group as @samp{soc.motss}. + +The different methods all have their peculiarities, of course. + +@menu +* The Server Buffer:: Making and editing virtual servers. +* Getting News:: Reading USENET news with Gnus. +* Getting Mail:: Reading your personal mail with Gnus. +* Other Sources:: Reading directories, files, SOUP packets. +* Combined Groups:: Combining groups into one group. +* Gnus Unplugged:: Reading news and mail offline. +@end menu + + +@node The Server Buffer +@section The Server Buffer + +Traditionally, a @dfn{server} is a machine or a piece of software that +one connects to, and then requests information from. Gnus does not +connect directly to any real servers, but does all transactions through +one backend or other. But that's just putting one layer more between +the actual media and Gnus, so we might just as well say that each +backend represents a virtual server. + +For instance, the @code{nntp} backend may be used to connect to several +different actual @sc{nntp} servers, or, perhaps, to many different ports +on the same actual @sc{nntp} server. You tell Gnus which backend to +use, and what parameters to set by specifying a @dfn{select method}. + +These select method specifications can sometimes become quite +complicated---say, for instance, that you want to read from the +@sc{nntp} server @samp{news.funet.fi} on port number 13, which +hangs if queried for @sc{nov} headers and has a buggy select. Ahem. +Anyways, if you had to specify that for each group that used this +server, that would be too much work, so Gnus offers a way of naming +select methods, which is what you do in the server buffer. + +To enter the server buffer, use the @kbd{^} +(@code{gnus-group-enter-server-mode}) command in the group buffer. + +@menu +* Server Buffer Format:: You can customize the look of this buffer. +* Server Commands:: Commands to manipulate servers. +* Example Methods:: Examples server specifications. +* Creating a Virtual Server:: An example session. +* Server Variables:: Which variables to set. +* Servers and Methods:: You can use server names as select methods. +* Unavailable Servers:: Some servers you try to contact may be down. +@end menu + +@vindex gnus-server-mode-hook +@code{gnus-server-mode-hook} is run when creating the server buffer. + + +@node Server Buffer Format +@subsection Server Buffer Format +@cindex server buffer format + +@vindex gnus-server-line-format +You can change the look of the server buffer lines by changing the +@code{gnus-server-line-format} variable. This is a @code{format}-like +variable, with some simple extensions: + +@table @samp + +@item h +How the news is fetched---the backend name. + +@item n +The name of this server. + +@item w +Where the news is to be fetched from---the address. + +@item s +The opened/closed/denied status of the server. +@end table + +@vindex gnus-server-mode-line-format +The mode line can also be customized by using the +@code{gnus-server-mode-line-format} variable (@pxref{Mode Line +Formatting}). The following specs are understood: + +@table @samp +@item S +Server name. + +@item M +Server method. +@end table + +Also @pxref{Formatting Variables}. + + +@node Server Commands +@subsection Server Commands +@cindex server commands + +@table @kbd + +@item a +@kindex a (Server) +@findex gnus-server-add-server +Add a new server (@code{gnus-server-add-server}). + +@item e +@kindex e (Server) +@findex gnus-server-edit-server +Edit a server (@code{gnus-server-edit-server}). + +@item SPACE +@kindex SPACE (Server) +@findex gnus-server-read-server +Browse the current server (@code{gnus-server-read-server}). + +@item q +@kindex q (Server) +@findex gnus-server-exit +Return to the group buffer (@code{gnus-server-exit}). + +@item k +@kindex k (Server) +@findex gnus-server-kill-server +Kill the current server (@code{gnus-server-kill-server}). + +@item y +@kindex y (Server) +@findex gnus-server-yank-server +Yank the previously killed server (@code{gnus-server-yank-server}). + +@item c +@kindex c (Server) +@findex gnus-server-copy-server +Copy the current server (@code{gnus-server-copy-server}). + +@item l +@kindex l (Server) +@findex gnus-server-list-servers +List all servers (@code{gnus-server-list-servers}). + +@item s +@kindex s (Server) +@findex gnus-server-scan-server +Request that the server scan its sources for new articles +(@code{gnus-server-scan-server}). This is mainly sensible with mail +servers. + +@item g +@kindex g (Server) +@findex gnus-server-regenerate-server +Request that the server regenerate all its data structures +(@code{gnus-server-regenerate-server}). This can be useful if you have +a mail backend that has gotten out of synch. + +@end table + + +@node Example Methods +@subsection Example Methods + +Most select methods are pretty simple and self-explanatory: + +@lisp +(nntp "news.funet.fi") +@end lisp + +Reading directly from the spool is even simpler: + +@lisp +(nnspool "") +@end lisp + +As you can see, the first element in a select method is the name of the +backend, and the second is the @dfn{address}, or @dfn{name}, if you +will. + +After these two elements, there may be an arbitrary number of +@var{(variable form)} pairs. + +To go back to the first example---imagine that you want to read from +port 15 on that machine. This is what the select method should +look like then: + +@lisp +(nntp "news.funet.fi" (nntp-port-number 15)) +@end lisp + +You should read the documentation to each backend to find out what +variables are relevant, but here's an @code{nnmh} example: + +@code{nnmh} is a mail backend that reads a spool-like structure. Say +you have two structures that you wish to access: One is your private +mail spool, and the other is a public one. Here's the possible spec for +your private mail: + +@lisp +(nnmh "private" (nnmh-directory "~/private/mail/")) +@end lisp + +(This server is then called @samp{private}, but you may have guessed +that.) + +Here's the method for a public spool: + +@lisp +(nnmh "public" + (nnmh-directory "/usr/information/spool/") + (nnmh-get-new-mail nil)) +@end lisp + +If you are behind a firewall and only have access to the @sc{nntp} +server from the firewall machine, you can instruct Gnus to @code{rlogin} +on the firewall machine and telnet from there to the @sc{nntp} server. +Doing this can be rather fiddly, but your virtual server definition +should probably look something like this: + +@lisp +(nntp "firewall" + (nntp-address "the.firewall.machine") + (nntp-open-connection-function nntp-open-rlogin) + (nntp-end-of-line "\n") + (nntp-rlogin-parameters + ("telnet" "the.real.nntp.host" "nntp"))) +@end lisp + +If you want to use the wonderful @code{ssh} program to provide a +compressed connection over the modem line, you could create a virtual +server that would look something like this: + +@lisp +(nntp "news" + (nntp-address "copper.uio.no") + (nntp-rlogin-program "ssh") + (nntp-open-connection-function nntp-open-rlogin) + (nntp-end-of-line "\n") + (nntp-rlogin-parameters + ("telnet" "news.uio.no" "nntp"))) +@end lisp + +This means that you have to have set up @code{ssh-agent} correctly to +provide automatic authorization, of course. And to get a compressed +connection, you have to have the @samp{Compression} option in the +@code{ssh} @file{config} file. + + +@node Creating a Virtual Server +@subsection Creating a Virtual Server + +If you're saving lots of articles in the cache by using persistent +articles, you may want to create a virtual server to read the cache. + +First you need to add a new server. The @kbd{a} command does that. It +would probably be best to use @code{nnspool} to read the cache. You +could also use @code{nnml} or @code{nnmh}, though. + +Type @kbd{a nnspool RET cache RET}. + +You should now have a brand new @code{nnspool} virtual server called +@samp{cache}. You now need to edit it to have the right definitions. +Type @kbd{e} to edit the server. You'll be entered into a buffer that +will contain the following: + +@lisp +(nnspool "cache") +@end lisp + +Change that to: + +@lisp +(nnspool "cache" + (nnspool-spool-directory "~/News/cache/") + (nnspool-nov-directory "~/News/cache/") + (nnspool-active-file "~/News/cache/active")) +@end lisp + +Type @kbd{C-c C-c} to return to the server buffer. If you now press +@kbd{RET} over this virtual server, you should be entered into a browse +buffer, and you should be able to enter any of the groups displayed. + + +@node Server Variables +@subsection Server Variables + +One sticky point when defining variables (both on backends and in Emacs +in general) is that some variables are typically initialized from other +variables when the definition of the variables is being loaded. If you +change the "base" variable after the variables have been loaded, you +won't change the "derived" variables. + +This typically affects directory and file variables. For instance, +@code{nnml-directory} is @file{~/Mail/} by default, and all @code{nnml} +directory variables are initialized from that variable, so +@code{nnml-active-file} will be @file{~/Mail/active}. If you define a +new virtual @code{nnml} server, it will @emph{not} suffice to set just +@code{nnml-directory}---you have to explicitly set all the file +variables to be what you want them to be. For a complete list of +variables for each backend, see each backend's section later in this +manual, but here's an example @code{nnml} definition: + +@lisp +(nnml "public" + (nnml-directory "~/my-mail/") + (nnml-active-file "~/my-mail/active") + (nnml-newsgroups-file "~/my-mail/newsgroups")) +@end lisp + + +@node Servers and Methods +@subsection Servers and Methods + +Wherever you would normally use a select method +(e.g. @code{gnus-secondary-select-method}, in the group select method, +when browsing a foreign server) you can use a virtual server name +instead. This could potentially save lots of typing. And it's nice all +over. + + +@node Unavailable Servers +@subsection Unavailable Servers + +If a server seems to be unreachable, Gnus will mark that server as +@code{denied}. That means that any subsequent attempt to make contact +with that server will just be ignored. ``It can't be opened,'' Gnus +will tell you, without making the least effort to see whether that is +actually the case or not. + +That might seem quite naughty, but it does make sense most of the time. +Let's say you have 10 groups subscribed to on server +@samp{nephelococcygia.com}. This server is located somewhere quite far +away from you and the machine is quite slow, so it takes 1 minute just +to find out that it refuses connection to you today. If Gnus were to +attempt to do that 10 times, you'd be quite annoyed, so Gnus won't +attempt to do that. Once it has gotten a single ``connection refused'', +it will regard that server as ``down''. + +So, what happens if the machine was only feeling unwell temporarily? +How do you test to see whether the machine has come up again? + +You jump to the server buffer (@pxref{The Server Buffer}) and poke it +with the following commands: + +@table @kbd + +@item O +@kindex O (Server) +@findex gnus-server-open-server +Try to establish connection to the server on the current line +(@code{gnus-server-open-server}). + +@item C +@kindex C (Server) +@findex gnus-server-close-server +Close the connection (if any) to the server +(@code{gnus-server-close-server}). + +@item D +@kindex D (Server) +@findex gnus-server-deny-server +Mark the current server as unreachable +(@code{gnus-server-deny-server}). + +@item M-o +@kindex M-o (Server) +@findex gnus-server-open-all-servers +Open the connections to all servers in the buffer +(@code{gnus-server-open-all-servers}). + +@item M-c +@kindex M-c (Server) +@findex gnus-server-close-all-servers +Close the connections to all servers in the buffer +(@code{gnus-server-close-all-servers}). + +@item R +@kindex R (Server) +@findex gnus-server-remove-denials +Remove all marks to whether Gnus was denied connection from any servers +(@code{gnus-server-remove-denials}). + +@end table + + +@node Getting News +@section Getting News +@cindex reading news +@cindex news backends + +A newsreader is normally used for reading news. Gnus currently provides +only two methods of getting news---it can read from an @sc{nntp} server, +or it can read from a local spool. + +@menu +* NNTP:: Reading news from an @sc{nntp} server. +* News Spool:: Reading news from the local spool. +@end menu + + +@node NNTP +@subsection @sc{nntp} +@cindex nntp + +Subscribing to a foreign group from an @sc{nntp} server is rather easy. +You just specify @code{nntp} as method and the address of the @sc{nntp} +server as the, uhm, address. + +If the @sc{nntp} server is located at a non-standard port, setting the +third element of the select method to this port number should allow you +to connect to the right port. You'll have to edit the group info for +that (@pxref{Foreign Groups}). + +The name of the foreign group can be the same as a native group. In +fact, you can subscribe to the same group from as many different servers +you feel like. There will be no name collisions. + +The following variables can be used to create a virtual @code{nntp} +server: + +@table @code + +@item nntp-server-opened-hook +@vindex nntp-server-opened-hook +@cindex @sc{mode reader} +@cindex authinfo +@cindex authentification +@cindex nntp authentification +@findex nntp-send-authinfo +@findex nntp-send-mode-reader +is run after a connection has been made. It can be used to send +commands to the @sc{nntp} server after it has been contacted. By +default it sends the command @code{MODE READER} to the server with the +@code{nntp-send-mode-reader} function. This function should always be +present in this hook. + +@item nntp-authinfo-function +@vindex nntp-authinfo-function +@findex nntp-send-authinfo +@vindex nntp-authinfo-file +This function will be used to send @samp{AUTHINFO} to the @sc{nntp} +server. The default function is @code{nntp-send-authinfo}, which looks +through your @file{~/.authinfo} (or whatever you've set the +@code{nntp-authinfo-file} variable to) for applicable entries. If none +are found, it will prompt you for a login name and a password. The +format of the @file{~/.authinfo} file is (almost) the same as the +@code{ftp} @file{~/.netrc} file, which is defined in the @code{ftp} +manual page, but here are the salient facts: + +@enumerate +@item +The file contains one or more line, each of which define one server. + +@item +Each line may contain an arbitrary number of token/value pairs. The +valid tokens include @samp{machine}, @samp{login}, @samp{password}, +@samp{default} and @samp{force}. (The latter is not a valid +@file{.netrc}/@code{ftp} token, which is the only way the +@file{.authinfo} file format deviates from the @file{.netrc} file +format.) + +@end enumerate + +Here's an example file: + +@example +machine news.uio.no login larsi password geheimnis +machine nntp.ifi.uio.no login larsi force yes +@end example + +The token/value pairs may appear in any order; @samp{machine} doesn't +have to be first, for instance. + +In this example, both login name and password have been supplied for the +former server, while the latter has only the login name listed, and the +user will be prompted for the password. The latter also has the +@samp{force} tag, which means that the authinfo will be sent to the +@var{nntp} server upon connection; the default (i.e., when there is not +@samp{force} tag) is to not send authinfo to the @var{nntp} server +until the @var{nntp} server asks for it. + +You can also add @samp{default} lines that will apply to all servers +that don't have matching @samp{machine} lines. + +@example +default force yes +@end example + +This will force sending @samp{AUTHINFO} commands to all servers not +previously mentioned. + +Remember to not leave the @file{~/.authinfo} file world-readable. + +@item nntp-server-action-alist +@vindex nntp-server-action-alist +This is a list of regexps to match on server types and actions to be +taken when matches are made. For instance, if you want Gnus to beep +every time you connect to innd, you could say something like: + +@lisp +(setq nntp-server-action-alist + '(("innd" (ding)))) +@end lisp + +You probably don't want to do that, though. + +The default value is + +@lisp +'(("nntpd 1\\.5\\.11t" + (remove-hook 'nntp-server-opened-hook 'nntp-send-mode-reader))) +@end lisp + +This ensures that Gnus doesn't send the @code{MODE READER} command to +nntpd 1.5.11t, since that command chokes that server, I've been told. + +@item nntp-maximum-request +@vindex nntp-maximum-request +If the @sc{nntp} server doesn't support @sc{nov} headers, this backend +will collect headers by sending a series of @code{head} commands. To +speed things up, the backend sends lots of these commands without +waiting for reply, and then reads all the replies. This is controlled +by the @code{nntp-maximum-request} variable, and is 400 by default. If +your network is buggy, you should set this to 1. + +@item nntp-connection-timeout +@vindex nntp-connection-timeout +If you have lots of foreign @code{nntp} groups that you connect to +regularly, you're sure to have problems with @sc{nntp} servers not +responding properly, or being too loaded to reply within reasonable +time. This is can lead to awkward problems, which can be helped +somewhat by setting @code{nntp-connection-timeout}. This is an integer +that says how many seconds the @code{nntp} backend should wait for a +connection before giving up. If it is @code{nil}, which is the default, +no timeouts are done. + +@c @item nntp-command-timeout +@c @vindex nntp-command-timeout +@c @cindex PPP connections +@c @cindex dynamic IP addresses +@c If you're running Gnus on a machine that has a dynamically assigned +@c address, Gnus may become confused. If the address of your machine +@c changes after connecting to the @sc{nntp} server, Gnus will simply sit +@c waiting forever for replies from the server. To help with this +@c unfortunate problem, you can set this command to a number. Gnus will +@c then, if it sits waiting for a reply from the server longer than that +@c number of seconds, shut down the connection, start a new one, and resend +@c the command. This should hopefully be transparent to the user. A +@c likely number is 30 seconds. +@c +@c @item nntp-retry-on-break +@c @vindex nntp-retry-on-break +@c If this variable is non-@code{nil}, you can also @kbd{C-g} if Gnus +@c hangs. This will have much the same effect as the command timeout +@c described above. + +@item nntp-server-hook +@vindex nntp-server-hook +This hook is run as the last step when connecting to an @sc{nntp} +server. + +@findex nntp-open-rlogin +@findex nntp-open-telnet +@findex nntp-open-network-stream +@item nntp-open-connection-function +@vindex nntp-open-connection-function +This function is used to connect to the remote system. Four pre-made +functions are supplied: + +@table @code +@item nntp-open-network-stream +This is the default, and simply connects to some port or other on the +remote system. + +@item nntp-open-rlogin +Does an @samp{rlogin} on the +remote system, and then does a @samp{telnet} to the @sc{nntp} server +available there. + +@code{nntp-open-rlogin}-related variables: + +@table @code + +@item nntp-rlogin-program +@vindex nntp-rlogin-program +Program used to log in on remote machines. The default is @samp{rsh}, +but @samp{ssh} is a popular alternative. + +@item nntp-rlogin-parameters +@vindex nntp-rlogin-parameters +This list will be used as the parameter list given to @code{rsh}. + +@item nntp-rlogin-user-name +@vindex nntp-rlogin-user-name +User name on the remote system. + +@end table + +@item nntp-open-telnet +Does a @samp{telnet} to the remote system and then another @samp{telnet} +to get to the @sc{nntp} server. + +@code{nntp-open-telnet}-related variables: + +@table @code +@item nntp-telnet-command +@vindex nntp-telnet-command +Command used to start @code{telnet}. + +@item nntp-telnet-switches +@vindex nntp-telnet-switches +List of strings to be used as the switches to the @code{telnet} command. + +@item nntp-telnet-user-name +@vindex nntp-telnet-user-name +User name for log in on the remote system. + +@item nntp-telnet-passwd +@vindex nntp-telnet-passwd +Password to use when logging in. + +@item nntp-telnet-parameters +@vindex nntp-telnet-parameters +A list of strings executed as a command after logging in +via @code{telnet}. + +@item nntp-telnet-shell-prompt +@vindex nntp-telnet-shell-prompt +Regexp matching the shell prompt on the remote machine. The default is +@samp{bash\\|\$ *\r?$\\|> *\r?}. + +@item nntp-open-telnet-envuser +@vindex nntp-open-telnet-envuser +If non-@code{nil}, the @code{telnet} session (client and server both) +will support the @code{ENVIRON} option and not prompt for login name. +This works for Solaris @code{telnet}, for instance. + +@end table + +@findex nntp-open-ssl-stream +@item nntp-open-ssl-stream +Opens a connection to a server over a @dfn{secure} channel. To use this +you must have SSLay installed +(@file{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL}, and you also need +@file{ssl.el} (from the W3 distributeion, for instance). You then +define a server as follows: + +@lisp +;; Type `C-c C-c' after you've finished editing. +;; +;; "snews" is port 563 and is predefined in our /etc/services +;; +(nntp "snews.bar.com" + (nntp-open-connection-function nntp-open-ssl-stream) + (nntp-port-number "snews") + (nntp-address "snews.bar.com")) +@end lisp + +@end table + +@item nntp-end-of-line +@vindex nntp-end-of-line +String to use as end-of-line marker when talking to the @sc{nntp} +server. This is @samp{\r\n} by default, but should be @samp{\n} when +using @code{rlogin} to talk to the server. + +@item nntp-rlogin-user-name +@vindex nntp-rlogin-user-name +User name on the remote system when using the @code{rlogin} connect +function. + +@item nntp-address +@vindex nntp-address +The address of the remote system running the @sc{nntp} server. + +@item nntp-port-number +@vindex nntp-port-number +Port number to connect to when using the @code{nntp-open-network-stream} +connect function. + +@item nntp-buggy-select +@vindex nntp-buggy-select +Set this to non-@code{nil} if your select routine is buggy. + +@item nntp-nov-is-evil +@vindex nntp-nov-is-evil +If the @sc{nntp} server does not support @sc{nov}, you could set this +variable to @code{t}, but @code{nntp} usually checks automatically whether @sc{nov} +can be used. + +@item nntp-xover-commands +@vindex nntp-xover-commands +@cindex nov +@cindex XOVER +List of strings used as commands to fetch @sc{nov} lines from a +server. The default value of this variable is @code{("XOVER" +"XOVERVIEW")}. + +@item nntp-nov-gap +@vindex nntp-nov-gap +@code{nntp} normally sends just one big request for @sc{nov} lines to +the server. The server responds with one huge list of lines. However, +if you have read articles 2-5000 in the group, and only want to read +article 1 and 5001, that means that @code{nntp} will fetch 4999 @sc{nov} +lines that you will not need. This variable says how +big a gap between two consecutive articles is allowed to be before the +@code{XOVER} request is split into several request. Note that if your +network is fast, setting this variable to a really small number means +that fetching will probably be slower. If this variable is @code{nil}, +@code{nntp} will never split requests. The default is 5. + +@item nntp-prepare-server-hook +@vindex nntp-prepare-server-hook +A hook run before attempting to connect to an @sc{nntp} server. + +@item nntp-warn-about-losing-connection +@vindex nntp-warn-about-losing-connection +If this variable is non-@code{nil}, some noise will be made when a +server closes connection. + +@item nntp-record-commands +@vindex nntp-record-commands +If non-@code{nil}, @code{nntp} will log all commands it sends to the +@sc{nntp} server (along with a timestep) in the @samp{*nntp-log*} +buffer. This is useful if you are debugging a Gnus/@sc{nntp} connection +that doesn't seem to work. + +@end table + + +@node News Spool +@subsection News Spool +@cindex nnspool +@cindex news spool + +Subscribing to a foreign group from the local spool is extremely easy, +and might be useful, for instance, to speed up reading groups that +contain very big articles---@samp{alt.binaries.pictures.furniture}, for +instance. + +Anyways, you just specify @code{nnspool} as the method and @code{""} (or +anything else) as the address. + +If you have access to a local spool, you should probably use that as the +native select method (@pxref{Finding the News}). It is normally faster +than using an @code{nntp} select method, but might not be. It depends. +You just have to try to find out what's best at your site. + +@table @code + +@item nnspool-inews-program +@vindex nnspool-inews-program +Program used to post an article. + +@item nnspool-inews-switches +@vindex nnspool-inews-switches +Parameters given to the inews program when posting an article. + +@item nnspool-spool-directory +@vindex nnspool-spool-directory +Where @code{nnspool} looks for the articles. This is normally +@file{/usr/spool/news/}. + +@item nnspool-nov-directory +@vindex nnspool-nov-directory +Where @code{nnspool} will look for @sc{nov} files. This is normally +@file{/usr/spool/news/over.view/}. + +@item nnspool-lib-dir +@vindex nnspool-lib-dir +Where the news lib dir is (@file{/usr/lib/news/} by default). + +@item nnspool-active-file +@vindex nnspool-active-file +The path to the active file. + +@item nnspool-newsgroups-file +@vindex nnspool-newsgroups-file +The path to the group descriptions file. + +@item nnspool-history-file +@vindex nnspool-history-file +The path to the news history file. + +@item nnspool-active-times-file +@vindex nnspool-active-times-file +The path to the active date file. + +@item nnspool-nov-is-evil +@vindex nnspool-nov-is-evil +If non-@code{nil}, @code{nnspool} won't try to use any @sc{nov} files +that it finds. + +@item nnspool-sift-nov-with-sed +@vindex nnspool-sift-nov-with-sed +@cindex sed +If non-@code{nil}, which is the default, use @code{sed} to get the +relevant portion from the overview file. If nil, @code{nnspool} will +load the entire file into a buffer and process it there. + +@end table + + +@node Getting Mail +@section Getting Mail +@cindex reading mail +@cindex mail + +Reading mail with a newsreader---isn't that just plain WeIrD? But of +course. + +@menu +* Getting Started Reading Mail:: A simple cookbook example. +* Splitting Mail:: How to create mail groups. +* Mail Backend Variables:: Variables for customizing mail handling. +* Fancy Mail Splitting:: Gnus can do hairy splitting of incoming mail. +* Mail and Procmail:: Reading mail groups that procmail create. +* Incorporating Old Mail:: What about the old mail you have? +* Expiring Mail:: Getting rid of unwanted mail. +* Washing Mail:: Removing gruft from the mail you get. +* Duplicates:: Dealing with duplicated mail. +* Not Reading Mail:: Using mail backends for reading other files. +* Choosing a Mail Backend:: Gnus can read a variety of mail formats. +@end menu + + +@node Getting Started Reading Mail +@subsection Getting Started Reading Mail + +It's quite easy to use Gnus to read your new mail. You just plonk the +mail backend of your choice into @code{gnus-secondary-select-methods}, +and things will happen automatically. + +For instance, if you want to use @code{nnml} (which is a "one file per +mail" backend), you could put the following in your @file{.gnus} file: + +@lisp +(setq gnus-secondary-select-methods + '((nnml "private"))) +@end lisp + +Now, the next time you start Gnus, this backend will be queried for new +articles, and it will move all the messages in your spool file to its +directory, which is @code{~/Mail/} by default. The new group that will +be created (@samp{mail.misc}) will be subscribed, and you can read it +like any other group. + +You will probably want to split the mail into several groups, though: + +@lisp +(setq nnmail-split-methods + '(("junk" "^From:.*Lars Ingebrigtsen") + ("crazy" "^Subject:.*die\\|^Organization:.*flabby") + ("other" ""))) +@end lisp + +This will result in three new @code{nnml} mail groups being created: +@samp{nnml:junk}, @samp{nnml:crazy}, and @samp{nnml:other}. All the +mail that doesn't fit into the first two groups will be placed in the +last group. + +This should be sufficient for reading mail with Gnus. You might want to +give the other sections in this part of the manual a perusal, though. +Especially @pxref{Choosing a Mail Backend} and @pxref{Expiring Mail}. + + +@node Splitting Mail +@subsection Splitting Mail +@cindex splitting mail +@cindex mail splitting + +@vindex nnmail-split-methods +The @code{nnmail-split-methods} variable says how the incoming mail is +to be split into groups. + +@lisp +(setq nnmail-split-methods + '(("mail.junk" "^From:.*Lars Ingebrigtsen") + ("mail.crazy" "^Subject:.*die\\|^Organization:.*flabby") + ("mail.other" ""))) +@end lisp + +This variable is a list of lists, where the first element of each of +these lists is the name of the mail group (they do not have to be called +something beginning with @samp{mail}, by the way), and the second +element is a regular expression used on the header of each mail to +determine if it belongs in this mail group. The first string may +contain @samp{\\1} forms, like the ones used by @code{replace-match} to +insert sub-expressions from the matched text. For instance: + +@lisp +("list.\\1" "From:.*\\(.*\\)-list@@majordomo.com") +@end lisp + +The second element can also be a function. In that case, it will be +called narrowed to the headers with the first element of the rule as the +argument. It should return a non-@code{nil} value if it thinks that the +mail belongs in that group. + +The last of these groups should always be a general one, and the regular +expression should @emph{always} be @samp{} so that it matches any mails +that haven't been matched by any of the other regexps. (These rules are +processed from the beginning of the alist toward the end. The first +rule to make a match will "win", unless you have crossposting enabled. +In that case, all matching rules will "win".) + +If you like to tinker with this yourself, you can set this variable to a +function of your choice. This function will be called without any +arguments in a buffer narrowed to the headers of an incoming mail +message. The function should return a list of group names that it +thinks should carry this mail message. + +Note that the mail backends are free to maul the poor, innocent, +incoming headers all they want to. They all add @code{Lines} headers; +some add @code{X-Gnus-Group} headers; most rename the Unix mbox +@code{From<SPACE>} line to something else. + +@vindex nnmail-crosspost +The mail backends all support cross-posting. If several regexps match, +the mail will be ``cross-posted'' to all those groups. +@code{nnmail-crosspost} says whether to use this mechanism or not. Note +that no articles are crossposted to the general (@samp{}) group. + +@vindex nnmail-crosspost-link-function +@cindex crosspost +@cindex links +@code{nnmh} and @code{nnml} makes crossposts by creating hard links to +the crossposted articles. However, not all file systems support hard +links. If that's the case for you, set +@code{nnmail-crosspost-link-function} to @code{copy-file}. (This +variable is @code{add-name-to-file} by default.) + +@kindex M-x nnmail-split-history +@kindex nnmail-split-history +If you wish to see where the previous mail split put the messages, you +can use the @kbd{M-x nnmail-split-history} command. + +Gnus gives you all the opportunity you could possibly want for shooting +yourself in the foot. Let's say you create a group that will contain +all the mail you get from your boss. And then you accidentally +unsubscribe from the group. Gnus will still put all the mail from your +boss in the unsubscribed group, and so, when your boss mails you ``Have +that report ready by Monday or you're fired!'', you'll never see it and, +come Tuesday, you'll still believe that you're gainfully employed while +you really should be out collecting empty bottles to save up for next +month's rent money. + + +@node Mail Backend Variables +@subsection Mail Backend Variables + +These variables are (for the most part) pertinent to all the various +mail backends. + +@table @code +@vindex nnmail-read-incoming-hook +@item nnmail-read-incoming-hook +The mail backends all call this hook after reading new mail. You can +use this hook to notify any mail watch programs, if you want to. + +@vindex nnmail-spool-file +@item nnmail-spool-file +@cindex POP mail +@cindex MAILHOST +@cindex movemail +@vindex nnmail-pop-password +@vindex nnmail-pop-password-required +The backends will look for new mail in this file. If this variable is +@code{nil}, the mail backends will never attempt to fetch mail by +themselves. If you are using a POP mail server and your name is +@samp{larsi}, you should set this variable to @samp{po:larsi}. If +your name is not @samp{larsi}, you should probably modify that +slightly, but you may have guessed that already, you smart & handsome +devil! You can also set this variable to @code{pop}, and Gnus will try +to figure out the POP mail string by itself. In any case, Gnus will +call @code{movemail} which will contact the POP server named in the +@code{MAILHOST} environment variable. If the POP server needs a +password, you can either set @code{nnmail-pop-password-required} to +@code{t} and be prompted for the password, or set +@code{nnmail-pop-password} to the password itself. + +@code{nnmail-spool-file} can also be a list of mailboxes. + +Your Emacs has to have been configured with @samp{--with-pop} before +compilation. This is the default, but some installations have it +switched off. + +When you use a mail backend, Gnus will slurp all your mail from your +inbox and plonk it down in your home directory. Gnus doesn't move any +mail if you're not using a mail backend---you have to do a lot of magic +invocations first. At the time when you have finished drawing the +pentagram, lightened the candles, and sacrificed the goat, you really +shouldn't be too surprised when Gnus moves your mail. + +@vindex nnmail-use-procmail +@vindex nnmail-procmail-suffix +@item nnmail-use-procmail +If non-@code{nil}, the mail backends will look in +@code{nnmail-procmail-directory} for incoming mail. All the files in +that directory that have names ending in @code{nnmail-procmail-suffix} +will be considered incoming mailboxes, and will be searched for new +mail. + +@vindex nnmail-crash-box +@item nnmail-crash-box +When a mail backend reads a spool file, mail is first moved to this +file, which is @file{~/.gnus-crash-box} by default. If this file +already exists, it will always be read (and incorporated) before any +other spool files. + +@vindex nnmail-prepare-incoming-hook +@item nnmail-prepare-incoming-hook +This is run in a buffer that holds all the new incoming mail, and can be +used for, well, anything, really. + +@vindex nnmail-split-hook +@item nnmail-split-hook +@findex article-decode-rfc1522 +@findex RFC1522 decoding +Hook run in the buffer where the mail headers of each message is kept +just before the splitting based on these headers is done. The hook is +free to modify the buffer contents in any way it sees fit---the buffer +is discarded after the splitting has been done, and no changes performed +in the buffer will show up in any files. @code{gnus-article-decode-rfc1522} +is one likely function to add to this hook. + +@vindex nnmail-pre-get-new-mail-hook +@vindex nnmail-post-get-new-mail-hook +@item nnmail-pre-get-new-mail-hook +@itemx nnmail-post-get-new-mail-hook +These are two useful hooks executed when treating new incoming +mail---@code{nnmail-pre-get-new-mail-hook} (is called just before +starting to handle the new mail) and +@code{nnmail-post-get-new-mail-hook} (is called when the mail handling +is done). Here's and example of using these two hooks to change the +default file modes the new mail files get: + +@lisp +(add-hook 'gnus-pre-get-new-mail-hook + (lambda () (set-default-file-modes 511))) + +(add-hook 'gnus-post-get-new-mail-hook + (lambda () (set-default-file-modes 551))) +@end lisp + +@item nnmail-tmp-directory +@vindex nnmail-tmp-directory +This variable says where to move incoming mail to -- while processing +it. This is usually done in the same directory that the mail backend +inhabits (e.g., @file{~/Mail/}), but if this variable is non-@code{nil}, +it will be used instead. + +@item nnmail-movemail-program +@vindex nnmail-movemail-program +This program is executed to move mail from the user's inbox to her home +directory. The default is @samp{movemail}. + +This can also be a function. In that case, the function will be called +with two parameters -- the name of the inbox, and the file to be moved +to. + +@item nnmail-delete-incoming +@vindex nnmail-delete-incoming +@cindex incoming mail files +@cindex deleting incoming files +If non-@code{nil}, the mail backends will delete the temporary incoming +file after splitting mail into the proper groups. This is @code{t} by +default. + +@c This is @code{nil} by +@c default for reasons of security. + +@c Since Red Gnus is an alpha release, it is to be expected to lose mail. +(No Gnus release since (ding) Gnus 0.10 (or something like that) have +lost mail, I think, but that's not the point. (Except certain versions +of Red Gnus.)) By not deleting the Incoming* files, one can be sure not +to lose mail -- if Gnus totally whacks out, one can always recover what +was lost. + +You may delete the @file{Incoming*} files at will. + +@item nnmail-use-long-file-names +@vindex nnmail-use-long-file-names +If non-@code{nil}, the mail backends will use long file and directory +names. Groups like @samp{mail.misc} will end up in directories +(assuming use of @code{nnml} backend) or files (assuming use of +@code{nnfolder} backend) like @file{mail.misc}. If it is @code{nil}, +the same group will end up in @file{mail/misc}. + +@item nnmail-delete-file-function +@vindex nnmail-delete-file-function +@findex delete-file +Function called to delete files. It is @code{delete-file} by default. + +@item nnmail-cache-accepted-message-ids +@vindex nnmail-cache-accepted-message-ids +If non-@code{nil}, put the @code{Message-ID}s of articles imported into +the backend (via @code{Gcc}, for instance) into the mail duplication +discovery cache. The default is @code{nil}. + +@end table + + +@node Fancy Mail Splitting +@subsection Fancy Mail Splitting +@cindex mail splitting +@cindex fancy mail splitting + +@vindex nnmail-split-fancy +@findex nnmail-split-fancy +If the rather simple, standard method for specifying how to split mail +doesn't allow you to do what you want, you can set +@code{nnmail-split-methods} to @code{nnmail-split-fancy}. Then you can +play with the @code{nnmail-split-fancy} variable. + +Let's look at an example value of this variable first: + +@lisp +;; Messages from the mailer daemon are not crossposted to any of +;; the ordinary groups. Warnings are put in a separate group +;; from real errors. +(| ("from" mail (| ("subject" "warn.*" "mail.warning") + "mail.misc")) + ;; Non-error messages are crossposted to all relevant + ;; groups, but we don't crosspost between the group for the + ;; (ding) list and the group for other (ding) related mail. + (& (| (any "ding@@ifi\\.uio\\.no" "ding.list") + ("subject" "ding" "ding.misc")) + ;; Other mailing lists... + (any "procmail@@informatik\\.rwth-aachen\\.de" "procmail.list") + (any "SmartList@@informatik\\.rwth-aachen\\.de" "SmartList.list") + ;; People... + (any "larsi@@ifi\\.uio\\.no" "people.Lars_Magne_Ingebrigtsen")) + ;; Unmatched mail goes to the catch all group. + "misc.misc") +@end lisp + +This variable has the format of a @dfn{split}. A split is a (possibly) +recursive structure where each split may contain other splits. Here are +the five possible split syntaxes: + +@enumerate + +@item +@samp{group}: If the split is a string, that will be taken as a group +name. Normal regexp match expansion will be done. See below for +examples. + +@item +@var{(FIELD VALUE SPLIT)}: If the split is a list, the first element of +which is a string, then store the message as specified by SPLIT, if +header FIELD (a regexp) contains VALUE (also a regexp). + +@item +@var{(| SPLIT...)}: If the split is a list, and the first element is +@code{|} (vertical bar), then process each SPLIT until one of them +matches. A SPLIT is said to match if it will cause the mail message to +be stored in one or more groups. + +@item +@var{(& SPLIT...)}: If the split is a list, and the first element is +@code{&}, then process all SPLITs in the list. + +@item +@code{junk}: If the split is the symbol @code{junk}, then don't save +this message. Use with extreme caution. + +@item +@var{(: function arg1 arg2 ...)}: If the split is a list, and the first +element is @code{:}, then the second element will be called as a +function with @var{args} given as arguments. The function should return +a SPLIT. + +@item +@code{nil}: If the split is @code{nil}, it is ignored. + +@end enumerate + +In these splits, @var{FIELD} must match a complete field name. +@var{VALUE} must match a complete word according to the fundamental mode +syntax table. You can use @code{.*} in the regexps to match partial +field names or words. In other words, all @var{VALUE}'s are wrapped in +@samp{\<} and @samp{\>} pairs. + +@vindex nnmail-split-abbrev-alist +@var{FIELD} and @var{VALUE} can also be lisp symbols, in that case they +are expanded as specified by the variable +@code{nnmail-split-abbrev-alist}. This is an alist of cons cells, where +the @code{car} of a cell contains the key, and the @code{cdr} contains the associated +value. + +@vindex nnmail-split-fancy-syntax-table +@code{nnmail-split-fancy-syntax-table} is the syntax table in effect +when all this splitting is performed. + +If you want to have Gnus create groups dynamically based on some +information in the headers (i.e., do @code{replace-match}-like +substitutions in the group names), you can say things like: + +@example +(any "debian-\\b\\(\\w+\\)@@lists.debian.org" "mail.debian.\\1") +@end example + +If the string contains the element @samp{\&}, then the previously +matched string will be substituted. Similarly, the elements @samp{\\1} +up to @samp{\\9} will be substituted with the text matched by the +groupings 1 through 9. + + +@node Mail and Procmail +@subsection Mail and Procmail +@cindex procmail + +@cindex slocal +@cindex elm +Many people use @code{procmail} (or some other mail filter program or +external delivery agent---@code{slocal}, @code{elm}, etc) to split +incoming mail into groups. If you do that, you should set +@code{nnmail-spool-file} to @code{procmail} to ensure that the mail +backends never ever try to fetch mail by themselves. + +If you have a combined @code{procmail}/POP/mailbox setup, you can do +something like the following: + +@vindex nnmail-use-procmail +@lisp +(setq nnmail-use-procmail t) +(setq nnmail-spool-file + '("/usr/spool/mail/my-name" "po:my-name")) +@end lisp + +This also means that you probably don't want to set +@code{nnmail-split-methods} either, which has some, perhaps, unexpected +side effects. + +When a mail backend is queried for what groups it carries, it replies +with the contents of that variable, along with any groups it has figured +out that it carries by other means. None of the backends, except +@code{nnmh}, actually go out to the disk and check what groups actually +exist. (It's not trivial to distinguish between what the user thinks is +a basis for a newsgroup and what is just a plain old file or directory.) + +This means that you have to tell Gnus (and the backends) by hand what +groups exist. + +Let's take the @code{nnmh} backend as an example: + +The folders are located in @code{nnmh-directory}, say, @file{~/Mail/}. +There are three folders, @file{foo}, @file{bar} and @file{mail.baz}. + +Go to the group buffer and type @kbd{G m}. When prompted, answer +@samp{foo} for the name and @samp{nnmh} for the method. Repeat +twice for the two other groups, @samp{bar} and @samp{mail.baz}. Be sure +to include all your mail groups. + +That's it. You are now set to read your mail. An active file for this +method will be created automatically. + +@vindex nnmail-procmail-suffix +@vindex nnmail-procmail-directory +If you use @code{nnfolder} or any other backend that store more than a +single article in each file, you should never have procmail add mails to +the file that Gnus sees. Instead, procmail should put all incoming mail +in @code{nnmail-procmail-directory}. To arrive at the file name to put +the incoming mail in, append @code{nnmail-procmail-suffix} to the group +name. The mail backends will read the mail from these files. + +@vindex nnmail-resplit-incoming +When Gnus reads a file called @file{mail.misc.spool}, this mail will be +put in the @code{mail.misc}, as one would expect. However, if you want +Gnus to split the mail the normal way, you could set +@code{nnmail-resplit-incoming} to @code{t}. + +@vindex nnmail-keep-last-article +If you use @code{procmail} to split things directly into an @code{nnmh} +directory (which you shouldn't do), you should set +@code{nnmail-keep-last-article} to non-@code{nil} to prevent Gnus from +ever expiring the final article (i.e., the article with the highest +article number) in a mail newsgroup. This is quite, quite important. + +Here's an example setup: The incoming spools are located in +@file{~/incoming/} and have @samp{""} as suffixes (i.e., the incoming +spool files have the same names as the equivalent groups). The +@code{nnfolder} backend is to be used as the mail interface, and the +@code{nnfolder} directory is @file{~/fMail/}. + +@lisp +(setq nnfolder-directory "~/fMail/") +(setq nnmail-spool-file 'procmail) +(setq nnmail-procmail-directory "~/incoming/") +(setq gnus-secondary-select-methods '((nnfolder ""))) +(setq nnmail-procmail-suffix "") +@end lisp + + +@node Incorporating Old Mail +@subsection Incorporating Old Mail + +Most people have lots of old mail stored in various file formats. If +you have set up Gnus to read mail using one of the spiffy Gnus mail +backends, you'll probably wish to have that old mail incorporated into +your mail groups. + +Doing so can be quite easy. + +To take an example: You're reading mail using @code{nnml} +(@pxref{Mail Spool}), and have set @code{nnmail-split-methods} to a +satisfactory value (@pxref{Splitting Mail}). You have an old Unix mbox +file filled with important, but old, mail. You want to move it into +your @code{nnml} groups. + +Here's how: + +@enumerate +@item +Go to the group buffer. + +@item +Type `G f' and give the path to the mbox file when prompted to create an +@code{nndoc} group from the mbox file (@pxref{Foreign Groups}). + +@item +Type `SPACE' to enter the newly created group. + +@item +Type `M P b' to process-mark all articles in this group's buffer +(@pxref{Setting Process Marks}). + +@item +Type `B r' to respool all the process-marked articles, and answer +@samp{nnml} when prompted (@pxref{Mail Group Commands}). +@end enumerate + +All the mail messages in the mbox file will now also be spread out over +all your @code{nnml} groups. Try entering them and check whether things +have gone without a glitch. If things look ok, you may consider +deleting the mbox file, but I wouldn't do that unless I was absolutely +sure that all the mail has ended up where it should be. + +Respooling is also a handy thing to do if you're switching from one mail +backend to another. Just respool all the mail in the old mail groups +using the new mail backend. + + +@node Expiring Mail +@subsection Expiring Mail +@cindex article expiry + +Traditional mail readers have a tendency to remove mail articles when +you mark them as read, in some way. Gnus takes a fundamentally +different approach to mail reading. + +Gnus basically considers mail just to be news that has been received in +a rather peculiar manner. It does not think that it has the power to +actually change the mail, or delete any mail messages. If you enter a +mail group, and mark articles as ``read'', or kill them in some other +fashion, the mail articles will still exist on the system. I repeat: +Gnus will not delete your old, read mail. Unless you ask it to, of +course. + +To make Gnus get rid of your unwanted mail, you have to mark the +articles as @dfn{expirable}. This does not mean that the articles will +disappear right away, however. In general, a mail article will be +deleted from your system if, 1) it is marked as expirable, AND 2) it is +more than one week old. If you do not mark an article as expirable, it +will remain on your system until hell freezes over. This bears +repeating one more time, with some spurious capitalizations: IF you do +NOT mark articles as EXPIRABLE, Gnus will NEVER delete those ARTICLES. + +@vindex gnus-auto-expirable-newsgroups +You do not have to mark articles as expirable by hand. Groups that +match the regular expression @code{gnus-auto-expirable-newsgroups} will +have all articles that you read marked as expirable automatically. All +articles marked as expirable have an @samp{E} in the first +column in the summary buffer. + +By default, if you have auto expiry switched on, Gnus will mark all the +articles you read as expirable, no matter if they were read or unread +before. To avoid having articles marked as read marked as expirable +automatically, you can put something like the following in your +@file{.gnus} file: + +@vindex gnus-mark-article-hook +@lisp +(remove-hook 'gnus-mark-article-hook + 'gnus-summary-mark-read-and-unread-as-read) +(add-hook 'gnus-mark-article-hook 'gnus-summary-mark-unread-as-read) +@end lisp + +Note that making a group auto-expirable doesn't mean that all read +articles are expired---only the articles marked as expirable +will be expired. Also note that using the @kbd{d} command won't make +groups expirable---only semi-automatic marking of articles as read will +mark the articles as expirable in auto-expirable groups. + +Let's say you subscribe to a couple of mailing lists, and you want the +articles you have read to disappear after a while: + +@lisp +(setq gnus-auto-expirable-newsgroups + "mail.nonsense-list\\|mail.nice-list") +@end lisp + +Another way to have auto-expiry happen is to have the element +@code{auto-expire} in the group parameters of the group. + +If you use adaptive scoring (@pxref{Adaptive Scoring}) and +auto-expiring, you'll have problems. Auto-expiring and adaptive scoring +don't really mix very well. + +@vindex nnmail-expiry-wait +The @code{nnmail-expiry-wait} variable supplies the default time an +expirable article has to live. Gnus starts counting days from when the +message @emph{arrived}, not from when it was sent. The default is seven +days. + +Gnus also supplies a function that lets you fine-tune how long articles +are to live, based on what group they are in. Let's say you want to +have one month expiry period in the @samp{mail.private} group, a one day +expiry period in the @samp{mail.junk} group, and a six day expiry period +everywhere else: + +@vindex nnmail-expiry-wait-function +@lisp +(setq nnmail-expiry-wait-function + (lambda (group) + (cond ((string= group "mail.private") + 31) + ((string= group "mail.junk") + 1) + ((string= group "important") + 'never) + (t + 6)))) +@end lisp + +The group names this function is fed are ``unadorned'' group +names---no @samp{nnml:} prefixes and the like. + +The @code{nnmail-expiry-wait} variable and +@code{nnmail-expiry-wait-function} function can either be a number (not +necessarily an integer) or one of the symbols @code{immediate} or +@code{never}. + +You can also use the @code{expiry-wait} group parameter to selectively +change the expiry period (@pxref{Group Parameters}). + +@vindex nnmail-keep-last-article +If @code{nnmail-keep-last-article} is non-@code{nil}, Gnus will never +expire the final article in a mail newsgroup. This is to make life +easier for procmail users. + +@vindex gnus-total-expirable-newsgroups +By the way: That line up there, about Gnus never expiring non-expirable +articles, is a lie. If you put @code{total-expire} in the group +parameters, articles will not be marked as expirable, but all read +articles will be put through the expiry process. Use with extreme +caution. Even more dangerous is the +@code{gnus-total-expirable-newsgroups} variable. All groups that match +this regexp will have all read articles put through the expiry process, +which means that @emph{all} old mail articles in the groups in question +will be deleted after a while. Use with extreme caution, and don't come +crying to me when you discover that the regexp you used matched the +wrong group and all your important mail has disappeared. Be a +@emph{man}! Or a @emph{woman}! Whatever you feel more comfortable +with! So there! + +Most people make most of their mail groups total-expirable, though. + + +@node Washing Mail +@subsection Washing Mail +@cindex mail washing +@cindex list server brain damage +@cindex incoming mail treatment + +Mailers and list servers are notorious for doing all sorts of really, +really stupid things with mail. ``Hey, RFC822 doesn't explicitly +prohibit us from adding the string @code{wE aRe ElItE!!!!!1!!} to the +end of all lines passing through our server, so let's do that!!!!1!'' +Yes, but RFC822 wasn't designed to be read by morons. Things that were +considered to be self-evident were not discussed. So. Here we are. + +Case in point: The German version of Microsoft Exchange adds @samp{AW: +} to the subjects of replies instead of @samp{Re: }. I could pretend to +be shocked and dismayed by this, but I haven't got the energy. It is to +laugh. + +Gnus provides a plethora of functions for washing articles while +displaying them, but it might be nicer to do the filtering before +storing the mail to disc. For that purpose, we have three hooks and +various functions that can be put in these hooks. + +@table @code +@item nnmail-prepare-incoming-hook +@vindex nnmail-prepare-incoming-hook +This hook is called before doing anything with the mail and is meant for +grand, sweeping gestures. Functions to be used include: + +@table @code +@item nnheader-ms-strip-cr +@findex nnheader-ms-strip-cr +Remove trailing carriage returns from each line. This is default on +Emacs running on MS machines. + +@end table + +@item nnmail-prepare-incoming-header-hook +@vindex nnmail-prepare-incoming-header-hook +This hook is called narrowed to each header. It can be used when +cleaning up the headers. Functions that can be used include: + +@table @code +@item nnmail-remove-leading-whitespace +@findex nnmail-remove-leading-whitespace +Clear leading white space that ``helpful'' listservs have added to the +headers to make them look nice. Aaah. + +@item nnmail-remove-list-identifiers +@findex nnmail-remove-list-identifiers +Some list servers add an identifier---for example, @samp{(idm)}---to the +beginning of all @code{Subject} headers. I'm sure that's nice for +people who use stone age mail readers. This function will remove +strings that match the @code{nnmail-list-identifiers} regexp, which can +also be a list of regexp. + +For instance, if you want to remove the @samp{(idm)} and the +@samp{nagnagnag} identifiers: + +@lisp +(setq nnmail-list-identifiers + '("(idm)" "nagnagnag")) +@end lisp + +@item nnmail-remove-tabs +@findex nnmail-remove-tabs +Translate all @samp{TAB} characters into @samp{SPACE} characters. + +@end table + +@item nnmail-prepare-incoming-message-hook +@vindex nnmail-prepare-incoming-message-hook +This hook is called narrowed to each message. Functions to be used +include: + +@table @code +@item article-de-quoted-unreadable +@findex article-de-quoted-unreadable +Decode Quoted Readable encoding. + +@end table +@end table + + +@node Duplicates +@subsection Duplicates + +@vindex nnmail-treat-duplicates +@vindex nnmail-message-id-cache-length +@vindex nnmail-message-id-cache-file +@cindex duplicate mails +If you are a member of a couple of mailing lists, you will sometimes +receive two copies of the same mail. This can be quite annoying, so +@code{nnmail} checks for and treats any duplicates it might find. To do +this, it keeps a cache of old @code{Message-ID}s--- +@code{nnmail-message-id-cache-file}, which is @file{~/.nnmail-cache} by +default. The approximate maximum number of @code{Message-ID}s stored +there is controlled by the @code{nnmail-message-id-cache-length} +variable, which is 1000 by default. (So 1000 @code{Message-ID}s will be +stored.) If all this sounds scary to you, you can set +@code{nnmail-treat-duplicates} to @code{warn} (which is what it is by +default), and @code{nnmail} won't delete duplicate mails. Instead it +will insert a warning into the head of the mail saying that it thinks +that this is a duplicate of a different message. + +This variable can also be a function. If that's the case, the function +will be called from a buffer narrowed to the message in question with +the @code{Message-ID} as a parameter. The function must return either +@code{nil}, @code{warn}, or @code{delete}. + +You can turn this feature off completely by setting the variable to +@code{nil}. + +If you want all the duplicate mails to be put into a special +@dfn{duplicates} group, you could do that using the normal mail split +methods: + +@lisp +(setq nnmail-split-fancy + '(| ;; Messages duplicates go to a separate group. + ("gnus-warning" "duplication of message" "duplicate") + ;; Message from daemons, postmaster, and the like to another. + (any mail "mail.misc") + ;; Other rules. + [ ... ] )) +@end lisp + +Or something like: +@lisp +(setq nnmail-split-methods + '(("duplicates" "^Gnus-Warning:") + ;; Other rules. + [...])) +@end lisp + +Here's a neat feature: If you know that the recipient reads her mail +with Gnus, and that she has @code{nnmail-treat-duplicates} set to +@code{delete}, you can send her as many insults as you like, just by +using a @code{Message-ID} of a mail that you know that she's already +received. Think of all the fun! She'll never see any of it! Whee! + + +@node Not Reading Mail +@subsection Not Reading Mail + +If you start using any of the mail backends, they have the annoying +habit of assuming that you want to read mail with them. This might not +be unreasonable, but it might not be what you want. + +If you set @code{nnmail-spool-file} to @code{nil}, none of the backends +will ever attempt to read incoming mail, which should help. + +@vindex nnbabyl-get-new-mail +@vindex nnmbox-get-new-mail +@vindex nnml-get-new-mail +@vindex nnmh-get-new-mail +@vindex nnfolder-get-new-mail +This might be too much, if, for instance, you are reading mail quite +happily with @code{nnml} and just want to peek at some old @sc{rmail} +file you have stashed away with @code{nnbabyl}. All backends have +variables called backend-@code{get-new-mail}. If you want to disable +the @code{nnbabyl} mail reading, you edit the virtual server for the +group to have a setting where @code{nnbabyl-get-new-mail} to @code{nil}. + +All the mail backends will call @code{nn}*@code{-prepare-save-mail-hook} +narrowed to the article to be saved before saving it when reading +incoming mail. + + +@node Choosing a Mail Backend +@subsection Choosing a Mail Backend + +Gnus will read the mail spool when you activate a mail group. The mail +file is first copied to your home directory. What happens after that +depends on what format you want to store your mail in. + +@menu +* Unix Mail Box:: Using the (quite) standard Un*x mbox. +* Rmail Babyl:: Emacs programs use the rmail babyl format. +* Mail Spool:: Store your mail in a private spool? +* MH Spool:: An mhspool-like backend. +* Mail Folders:: Having one file for each group. +@end menu + + +@node Unix Mail Box +@subsubsection Unix Mail Box +@cindex nnmbox +@cindex unix mail box + +@vindex nnmbox-active-file +@vindex nnmbox-mbox-file +The @dfn{nnmbox} backend will use the standard Un*x mbox file to store +mail. @code{nnmbox} will add extra headers to each mail article to say +which group it belongs in. + +Virtual server settings: + +@table @code +@item nnmbox-mbox-file +@vindex nnmbox-mbox-file +The name of the mail box in the user's home directory. + +@item nnmbox-active-file +@vindex nnmbox-active-file +The name of the active file for the mail box. + +@item nnmbox-get-new-mail +@vindex nnmbox-get-new-mail +If non-@code{nil}, @code{nnmbox} will read incoming mail and split it +into groups. +@end table + + +@node Rmail Babyl +@subsubsection Rmail Babyl +@cindex nnbabyl +@cindex rmail mbox + +@vindex nnbabyl-active-file +@vindex nnbabyl-mbox-file +The @dfn{nnbabyl} backend will use a babyl mail box (aka. @dfn{rmail +mbox}) to store mail. @code{nnbabyl} will add extra headers to each mail +article to say which group it belongs in. + +Virtual server settings: + +@table @code +@item nnbabyl-mbox-file +@vindex nnbabyl-mbox-file +The name of the rmail mbox file. + +@item nnbabyl-active-file +@vindex nnbabyl-active-file +The name of the active file for the rmail box. + +@item nnbabyl-get-new-mail +@vindex nnbabyl-get-new-mail +If non-@code{nil}, @code{nnbabyl} will read incoming mail. +@end table + + +@node Mail Spool +@subsubsection Mail Spool +@cindex nnml +@cindex mail @sc{nov} spool + +The @dfn{nnml} spool mail format isn't compatible with any other known +format. It should be used with some caution. + +@vindex nnml-directory +If you use this backend, Gnus will split all incoming mail into files, +one file for each mail, and put the articles into the corresponding +directories under the directory specified by the @code{nnml-directory} +variable. The default value is @file{~/Mail/}. + +You do not have to create any directories beforehand; Gnus will take +care of all that. + +If you have a strict limit as to how many files you are allowed to store +in your account, you should not use this backend. As each mail gets its +own file, you might very well occupy thousands of inodes within a few +weeks. If this is no problem for you, and it isn't a problem for you +having your friendly systems administrator walking around, madly, +shouting ``Who is eating all my inodes?! Who? Who!?!'', then you should +know that this is probably the fastest format to use. You do not have +to trudge through a big mbox file just to read your new mail. + +@code{nnml} is probably the slowest backend when it comes to article +splitting. It has to create lots of files, and it also generates +@sc{nov} databases for the incoming mails. This makes it the fastest +backend when it comes to reading mail. + +Virtual server settings: + +@table @code +@item nnml-directory +@vindex nnml-directory +All @code{nnml} directories will be placed under this directory. + +@item nnml-active-file +@vindex nnml-active-file +The active file for the @code{nnml} server. + +@item nnml-newsgroups-file +@vindex nnml-newsgroups-file +The @code{nnml} group descriptions file. @xref{Newsgroups File +Format}. + +@item nnml-get-new-mail +@vindex nnml-get-new-mail +If non-@code{nil}, @code{nnml} will read incoming mail. + +@item nnml-nov-is-evil +@vindex nnml-nov-is-evil +If non-@code{nil}, this backend will ignore any @sc{nov} files. + +@item nnml-nov-file-name +@vindex nnml-nov-file-name +The name of the @sc{nov} files. The default is @file{.overview}. + +@item nnml-prepare-save-mail-hook +@vindex nnml-prepare-save-mail-hook +Hook run narrowed to an article before saving. + +@end table + +@findex nnml-generate-nov-databases +If your @code{nnml} groups and @sc{nov} files get totally out of whack, +you can do a complete update by typing @kbd{M-x +nnml-generate-nov-databases}. This command will trawl through the +entire @code{nnml} hierarchy, looking at each and every article, so it +might take a while to complete. A better interface to this +functionality can be found in the server buffer (@pxref{Server +Commands}). + + +@node MH Spool +@subsubsection MH Spool +@cindex nnmh +@cindex mh-e mail spool + +@code{nnmh} is just like @code{nnml}, except that is doesn't generate +@sc{nov} databases and it doesn't keep an active file. This makes +@code{nnmh} a @emph{much} slower backend than @code{nnml}, but it also +makes it easier to write procmail scripts for. + +Virtual server settings: + +@table @code +@item nnmh-directory +@vindex nnmh-directory +All @code{nnmh} directories will be located under this directory. + +@item nnmh-get-new-mail +@vindex nnmh-get-new-mail +If non-@code{nil}, @code{nnmh} will read incoming mail. + +@item nnmh-be-safe +@vindex nnmh-be-safe +If non-@code{nil}, @code{nnmh} will go to ridiculous lengths to make +sure that the articles in the folder are actually what Gnus thinks they +are. It will check date stamps and stat everything in sight, so +setting this to @code{t} will mean a serious slow-down. If you never +use anything but Gnus to read the @code{nnmh} articles, you do not have +to set this variable to @code{t}. +@end table + + +@node Mail Folders +@subsubsection Mail Folders +@cindex nnfolder +@cindex mbox folders +@cindex mail folders + +@code{nnfolder} is a backend for storing each mail group in a separate +file. Each file is in the standard Un*x mbox format. @code{nnfolder} +will add extra headers to keep track of article numbers and arrival +dates. + +Virtual server settings: + +@table @code +@item nnfolder-directory +@vindex nnfolder-directory +All the @code{nnfolder} mail boxes will be stored under this directory. + +@item nnfolder-active-file +@vindex nnfolder-active-file +The name of the active file. + +@item nnfolder-newsgroups-file +@vindex nnfolder-newsgroups-file +The name of the group descriptions file. @xref{Newsgroups File Format}. + +@item nnfolder-get-new-mail +@vindex nnfolder-get-new-mail +If non-@code{nil}, @code{nnfolder} will read incoming mail. + +@item nnfolder-save-buffer-hook +@vindex nnfolder-save-buffer-hook +@cindex backup files +Hook run before saving the folders. Note that Emacs does the normal +backup renaming of files even with the @code{nnfolder} buffers. If you +wish to switch this off, you could say something like the following in +your @file{.emacs} file: + +@lisp +(defun turn-off-backup () + (set (make-local-variable 'backup-inhibited) t)) + +(add-hook 'nnfolder-save-buffer-hook 'turn-off-backup) +@end lisp + +@end table + + +@findex nnfolder-generate-active-file +@kindex M-x nnfolder-generate-active-file +If you have lots of @code{nnfolder}-like files you'd like to read with +@code{nnfolder}, you can use the @kbd{M-x nnfolder-generate-active-file} +command to make @code{nnfolder} aware of all likely files in +@code{nnfolder-directory}. + + +@node Other Sources +@section Other Sources + +Gnus can do more than just read news or mail. The methods described +below allow Gnus to view directories and files as if they were +newsgroups. + +@menu +* Directory Groups:: You can read a directory as if it was a newsgroup. +* Anything Groups:: Dired? Who needs dired? +* Document Groups:: Single files can be the basis of a group. +* SOUP:: Reading @sc{SOUP} packets ``offline''. +* Web Searches:: Creating groups from articles that match a string. +* Mail-To-News Gateways:: Posting articles via mail-to-news gateways. +@end menu + + +@node Directory Groups +@subsection Directory Groups +@cindex nndir +@cindex directory groups + +If you have a directory that has lots of articles in separate files in +it, you might treat it as a newsgroup. The files have to have numerical +names, of course. + +This might be an opportune moment to mention @code{ange-ftp} (and its +successor @code{efs}), that most wonderful of all wonderful Emacs +packages. When I wrote @code{nndir}, I didn't think much about it---a +backend to read directories. Big deal. + +@code{ange-ftp} changes that picture dramatically. For instance, if you +enter the @code{ange-ftp} file name +@file{/ftp.hpc.uh.edu:/pub/emacs/ding-list/} as the directory name, +@code{ange-ftp} or @code{efs} will actually allow you to read this +directory over at @samp{sina} as a newsgroup. Distributed news ahoy! + +@code{nndir} will use @sc{nov} files if they are present. + +@code{nndir} is a ``read-only'' backend---you can't delete or expire +articles with this method. You can use @code{nnmh} or @code{nnml} for +whatever you use @code{nndir} for, so you could switch to any of those +methods if you feel the need to have a non-read-only @code{nndir}. + + +@node Anything Groups +@subsection Anything Groups +@cindex nneething + +From the @code{nndir} backend (which reads a single spool-like +directory), it's just a hop and a skip to @code{nneething}, which +pretends that any arbitrary directory is a newsgroup. Strange, but +true. + +When @code{nneething} is presented with a directory, it will scan this +directory and assign article numbers to each file. When you enter such +a group, @code{nneething} must create ``headers'' that Gnus can use. +After all, Gnus is a newsreader, in case you're +forgetting. @code{nneething} does this in a two-step process. First, it +snoops each file in question. If the file looks like an article (i.e., +the first few lines look like headers), it will use this as the head. +If this is just some arbitrary file without a head (e.g. a C source +file), @code{nneething} will cobble up a header out of thin air. It +will use file ownership, name and date and do whatever it can with these +elements. + +All this should happen automatically for you, and you will be presented +with something that looks very much like a newsgroup. Totally like a +newsgroup, to be precise. If you select an article, it will be displayed +in the article buffer, just as usual. + +If you select a line that represents a directory, Gnus will pop you into +a new summary buffer for this @code{nneething} group. And so on. You can +traverse the entire disk this way, if you feel like, but remember that +Gnus is not dired, really, and does not intend to be, either. + +There are two overall modes to this action---ephemeral or solid. When +doing the ephemeral thing (i.e., @kbd{G D} from the group buffer), Gnus +will not store information on what files you have read, and what files +are new, and so on. If you create a solid @code{nneething} group the +normal way with @kbd{G m}, Gnus will store a mapping table between +article numbers and file names, and you can treat this group like any +other groups. When you activate a solid @code{nneething} group, you will +be told how many unread articles it contains, etc., etc. + +Some variables: + +@table @code +@item nneething-map-file-directory +@vindex nneething-map-file-directory +All the mapping files for solid @code{nneething} groups will be stored +in this directory, which defaults to @file{~/.nneething/}. + +@item nneething-exclude-files +@vindex nneething-exclude-files +All files that match this regexp will be ignored. Nice to use to exclude +auto-save files and the like, which is what it does by default. + +@item nneething-map-file +@vindex nneething-map-file +Name of the map files. +@end table + + +@node Document Groups +@subsection Document Groups +@cindex nndoc +@cindex documentation group +@cindex help group + +@code{nndoc} is a cute little thing that will let you read a single file +as a newsgroup. Several files types are supported: + +@table @code +@cindex babyl +@cindex rmail mbox + +@item babyl +The babyl (rmail) mail box. +@cindex mbox +@cindex Unix mbox + +@item mbox +The standard Unix mbox file. + +@cindex MMDF mail box +@item mmdf +The MMDF mail box format. + +@item news +Several news articles appended into a file. + +@item rnews +@cindex rnews batch files +The rnews batch transport format. +@cindex forwarded messages + +@item forward +Forwarded articles. + +@item mime-parts +MIME multipart messages, besides digests. + +@item mime-digest +@cindex digest +@cindex MIME digest +@cindex 1153 digest +@cindex RFC 1153 digest +@cindex RFC 341 digest +MIME (RFC 1341) digest format. + +@item standard-digest +The standard (RFC 1153) digest format. + +@item slack-digest +Non-standard digest format---matches most things, but does it badly. +@end table + +You can also use the special ``file type'' @code{guess}, which means +that @code{nndoc} will try to guess what file type it is looking at. +@code{digest} means that @code{nndoc} should guess what digest type the +file is. + +@code{nndoc} will not try to change the file or insert any extra headers into +it---it will simply, like, let you use the file as the basis for a +group. And that's it. + +If you have some old archived articles that you want to insert into your +new & spiffy Gnus mail backend, @code{nndoc} can probably help you with +that. Say you have an old @file{RMAIL} file with mail that you now want +to split into your new @code{nnml} groups. You look at that file using +@code{nndoc} (using the @kbd{G f} command in the group buffer +(@pxref{Foreign Groups})), set the process mark on all the articles in +the buffer (@kbd{M P b}, for instance), and then re-spool (@kbd{B r}) +using @code{nnml}. If all goes well, all the mail in the @file{RMAIL} +file is now also stored in lots of @code{nnml} directories, and you can +delete that pesky @file{RMAIL} file. If you have the guts! + +Virtual server variables: + +@table @code +@item nndoc-article-type +@vindex nndoc-article-type +This should be one of @code{mbox}, @code{babyl}, @code{digest}, +@code{news}, @code{rnews}, @code{mmdf}, @code{forward}, @code{rfc934}, +@code{rfc822-forward}, @code{mime-parts}, @code{mime-digest}, +@code{standard-digest}, @code{slack-digest}, @code{clari-briefs} or +@code{guess}. + +@item nndoc-post-type +@vindex nndoc-post-type +This variable says whether Gnus is to consider the group a news group or +a mail group. There are two valid values: @code{mail} (the default) +and @code{news}. +@end table + +@menu +* Document Server Internals:: How to add your own document types. +@end menu + + +@node Document Server Internals +@subsubsection Document Server Internals + +Adding new document types to be recognized by @code{nndoc} isn't +difficult. You just have to whip up a definition of what the document +looks like, write a predicate function to recognize that document type, +and then hook into @code{nndoc}. + +First, here's an example document type definition: + +@example +(mmdf + (article-begin . "^\^A\^A\^A\^A\n") + (body-end . "^\^A\^A\^A\^A\n")) +@end example + +The definition is simply a unique @dfn{name} followed by a series of +regexp pseudo-variable settings. Below are the possible +variables---don't be daunted by the number of variables; most document +types can be defined with very few settings: + +@table @code +@item first-article +If present, @code{nndoc} will skip past all text until it finds +something that match this regexp. All text before this will be +totally ignored. + +@item article-begin +This setting has to be present in all document type definitions. It +says what the beginning of each article looks like. + +@item head-begin-function +If present, this should be a function that moves point to the head of +the article. + +@item nndoc-head-begin +If present, this should be a regexp that matches the head of the +article. + +@item nndoc-head-end +This should match the end of the head of the article. It defaults to +@samp{^$}---the empty line. + +@item body-begin-function +If present, this function should move point to the beginning of the body +of the article. + +@item body-begin +This should match the beginning of the body of the article. It defaults +to @samp{^\n}. + +@item body-end-function +If present, this function should move point to the end of the body of +the article. + +@item body-end +If present, this should match the end of the body of the article. + +@item file-end +If present, this should match the end of the file. All text after this +regexp will be totally ignored. + +@end table + +So, using these variables @code{nndoc} is able to dissect a document +file into a series of articles, each with a head and a body. However, a +few more variables are needed since not all document types are all that +news-like---variables needed to transform the head or the body into +something that's palatable for Gnus: + +@table @code +@item prepare-body-function +If present, this function will be called when requesting an article. It +will be called with point at the start of the body, and is useful if the +document has encoded some parts of its contents. + +@item article-transform-function +If present, this function is called when requesting an article. It's +meant to be used for more wide-ranging transformation of both head and +body of the article. + +@item generate-head-function +If present, this function is called to generate a head that Gnus can +understand. It is called with the article number as a parameter, and is +expected to generate a nice head for the article in question. It is +called when requesting the headers of all articles. + +@end table + +Let's look at the most complicated example I can come up with---standard +digests: + +@example +(standard-digest + (first-article . ,(concat "^" (make-string 70 ?-) "\n\n+")) + (article-begin . ,(concat "\n\n" (make-string 30 ?-) "\n\n+")) + (prepare-body-function . nndoc-unquote-dashes) + (body-end-function . nndoc-digest-body-end) + (head-end . "^ ?$") + (body-begin . "^ ?\n") + (file-end . "^End of .*digest.*[0-9].*\n\\*\\*\\|^End of.*Digest *$") + (subtype digest guess)) +@end example + +We see that all text before a 70-width line of dashes is ignored; all +text after a line that starts with that @samp{^End of} is also ignored; +each article begins with a 30-width line of dashes; the line separating +the head from the body may contain a single space; and that the body is +run through @code{nndoc-unquote-dashes} before being delivered. + +To hook your own document definition into @code{nndoc}, use the +@code{nndoc-add-type} function. It takes two parameters---the first is +the definition itself and the second (optional) parameter says where in +the document type definition alist to put this definition. The alist is +traversed sequentially, and @code{nndoc-TYPE-type-p} is called for a given type @code{TYPE}. So @code{nndoc-mmdf-type-p} is called to see whether a document +is of @code{mmdf} type, and so on. These type predicates should return +@code{nil} if the document is not of the correct type; @code{t} if it is +of the correct type; and a number if the document might be of the +correct type. A high number means high probability; a low number means +low probability with @samp{0} being the lowest valid number. + + +@node SOUP +@subsection SOUP +@cindex SOUP +@cindex offline + +In the PC world people often talk about ``offline'' newsreaders. These +are thingies that are combined reader/news transport monstrosities. +With built-in modem programs. Yecchh! + +Of course, us Unix Weenie types of human beans use things like +@code{uucp} and, like, @code{nntpd} and set up proper news and mail +transport things like Ghod intended. And then we just use normal +newsreaders. + +However, it can sometimes be convenient to do something a that's a bit +easier on the brain if you have a very slow modem, and you're not really +that interested in doing things properly. + +A file format called @sc{soup} has been developed for transporting news +and mail from servers to home machines and back again. It can be a bit +fiddly. + +First some terminology: + +@table @dfn + +@item server +This is the machine that is connected to the outside world and where you +get news and/or mail from. + +@item home machine +This is the machine that you want to do the actual reading and responding +on. It is typically not connected to the rest of the world in any way. + +@item packet +Something that contains messages and/or commands. There are two kinds +of packets: + +@table @dfn +@item message packets +These are packets made at the server, and typically contain lots of +messages for you to read. These are called @file{SoupoutX.tgz} by +default, where @var{X} is a number. + +@item response packets +These are packets made at the home machine, and typically contains +replies that you've written. These are called @file{SoupinX.tgz} by +default, where @var{X} is a number. + +@end table + +@end table + + +@enumerate + +@item +You log in on the server and create a @sc{soup} packet. You can either +use a dedicated @sc{soup} thingie (like the @code{awk} program), or you +can use Gnus to create the packet with its @sc{soup} commands (@kbd{O +s} and/or @kbd{G s b}; and then @kbd{G s p}) (@pxref{SOUP Commands}). + +@item +You transfer the packet home. Rail, boat, car or modem will do fine. + +@item +You put the packet in your home directory. + +@item +You fire up Gnus on your home machine using the @code{nnsoup} backend as +the native or secondary server. + +@item +You read articles and mail and answer and followup to the things you +want (@pxref{SOUP Replies}). + +@item +You do the @kbd{G s r} command to pack these replies into a @sc{soup} +packet. + +@item +You transfer this packet to the server. + +@item +You use Gnus to mail this packet out with the @kbd{G s s} command. + +@item +You then repeat until you die. + +@end enumerate + +So you basically have a bipartite system---you use @code{nnsoup} for +reading and Gnus for packing/sending these @sc{soup} packets. + +@menu +* SOUP Commands:: Commands for creating and sending @sc{soup} packets +* SOUP Groups:: A backend for reading @sc{soup} packets. +* SOUP Replies:: How to enable @code{nnsoup} to take over mail and news. +@end menu + + +@node SOUP Commands +@subsubsection SOUP Commands + +These are commands for creating and manipulating @sc{soup} packets. + +@table @kbd +@item G s b +@kindex G s b (Group) +@findex gnus-group-brew-soup +Pack all unread articles in the current group +(@code{gnus-group-brew-soup}). This command understands the +process/prefix convention. + +@item G s w +@kindex G s w (Group) +@findex gnus-soup-save-areas +Save all @sc{soup} data files (@code{gnus-soup-save-areas}). + +@item G s s +@kindex G s s (Group) +@findex gnus-soup-send-replies +Send all replies from the replies packet +(@code{gnus-soup-send-replies}). + +@item G s p +@kindex G s p (Group) +@findex gnus-soup-pack-packet +Pack all files into a @sc{soup} packet (@code{gnus-soup-pack-packet}). + +@item G s r +@kindex G s r (Group) +@findex nnsoup-pack-replies +Pack all replies into a replies packet (@code{nnsoup-pack-replies}). + +@item O s +@kindex O s (Summary) +@findex gnus-soup-add-article +This summary-mode command adds the current article to a @sc{soup} packet +(@code{gnus-soup-add-article}). It understands the process/prefix +convention (@pxref{Process/Prefix}). + +@end table + + +There are a few variables to customize where Gnus will put all these +thingies: + +@table @code + +@item gnus-soup-directory +@vindex gnus-soup-directory +Directory where Gnus will save intermediate files while composing +@sc{soup} packets. The default is @file{~/SoupBrew/}. + +@item gnus-soup-replies-directory +@vindex gnus-soup-replies-directory +This is what Gnus will use as a temporary directory while sending our +reply packets. @file{~/SoupBrew/SoupReplies/} is the default. + +@item gnus-soup-prefix-file +@vindex gnus-soup-prefix-file +Name of the file where Gnus stores the last used prefix. The default is +@samp{gnus-prefix}. + +@item gnus-soup-packer +@vindex gnus-soup-packer +A format string command for packing a @sc{soup} packet. The default is +@samp{tar cf - %s | gzip > $HOME/Soupout%d.tgz}. + +@item gnus-soup-unpacker +@vindex gnus-soup-unpacker +Format string command for unpacking a @sc{soup} packet. The default is +@samp{gunzip -c %s | tar xvf -}. + +@item gnus-soup-packet-directory +@vindex gnus-soup-packet-directory +Where Gnus will look for reply packets. The default is @file{~/}. + +@item gnus-soup-packet-regexp +@vindex gnus-soup-packet-regexp +Regular expression matching @sc{soup} reply packets in +@code{gnus-soup-packet-directory}. + +@end table + + +@node SOUP Groups +@subsubsection @sc{soup} Groups +@cindex nnsoup + +@code{nnsoup} is the backend for reading @sc{soup} packets. It will +read incoming packets, unpack them, and put them in a directory where +you can read them at leisure. + +These are the variables you can use to customize its behavior: + +@table @code + +@item nnsoup-tmp-directory +@vindex nnsoup-tmp-directory +When @code{nnsoup} unpacks a @sc{soup} packet, it does it in this +directory. (@file{/tmp/} by default.) + +@item nnsoup-directory +@vindex nnsoup-directory +@code{nnsoup} then moves each message and index file to this directory. +The default is @file{~/SOUP/}. + +@item nnsoup-replies-directory +@vindex nnsoup-replies-directory +All replies will be stored in this directory before being packed into a +reply packet. The default is @file{~/SOUP/replies/"}. + +@item nnsoup-replies-format-type +@vindex nnsoup-replies-format-type +The @sc{soup} format of the replies packets. The default is @samp{?n} +(rnews), and I don't think you should touch that variable. I probably +shouldn't even have documented it. Drats! Too late! + +@item nnsoup-replies-index-type +@vindex nnsoup-replies-index-type +The index type of the replies packet. The default is @samp{?n}, which +means ``none''. Don't fiddle with this one either! + +@item nnsoup-active-file +@vindex nnsoup-active-file +Where @code{nnsoup} stores lots of information. This is not an ``active +file'' in the @code{nntp} sense; it's an Emacs Lisp file. If you lose +this file or mess it up in any way, you're dead. The default is +@file{~/SOUP/active}. + +@item nnsoup-packer +@vindex nnsoup-packer +Format string command for packing a reply @sc{soup} packet. The default +is @samp{tar cf - %s | gzip > $HOME/Soupin%d.tgz}. + +@item nnsoup-unpacker +@vindex nnsoup-unpacker +Format string command for unpacking incoming @sc{soup} packets. The +default is @samp{gunzip -c %s | tar xvf -}. + +@item nnsoup-packet-directory +@vindex nnsoup-packet-directory +Where @code{nnsoup} will look for incoming packets. The default is +@file{~/}. + +@item nnsoup-packet-regexp +@vindex nnsoup-packet-regexp +Regular expression matching incoming @sc{soup} packets. The default is +@samp{Soupout}. + +@item nnsoup-always-save +@vindex nnsoup-always-save +If non-@code{nil}, save the replies buffer after each posted message. + +@end table + + +@node SOUP Replies +@subsubsection SOUP Replies + +Just using @code{nnsoup} won't mean that your postings and mailings end +up in @sc{soup} reply packets automagically. You have to work a bit +more for that to happen. + +@findex nnsoup-set-variables +The @code{nnsoup-set-variables} command will set the appropriate +variables to ensure that all your followups and replies end up in the +@sc{soup} system. + +In specific, this is what it does: + +@lisp +(setq message-send-news-function 'nnsoup-request-post) +(setq message-send-mail-function 'nnsoup-request-mail) +@end lisp + +And that's it, really. If you only want news to go into the @sc{soup} +system you just use the first line. If you only want mail to be +@sc{soup}ed you use the second. + + +@node Web Searches +@subsection Web Searches +@cindex nnweb +@cindex DejaNews +@cindex Alta Vista +@cindex InReference +@cindex Usenet searches +@cindex searching the Usenet + +It's, like, too neat to search the Usenet for articles that match a +string, but it, like, totally @emph{sucks}, like, totally, to use one of +those, like, Web browsers, and you, like, have to, rilly, like, look at +the commercials, so, like, with Gnus you can do @emph{rad}, rilly, +searches without having to use a browser. + +The @code{nnweb} backend allows an easy interface to the mighty search +engine. You create an @code{nnweb} group, enter a search pattern, and +then enter the group and read the articles like you would any normal +group. The @kbd{G w} command in the group buffer (@pxref{Foreign +Groups}) will do this in an easy-to-use fashion. + +@code{nnweb} groups don't really lend themselves to being solid +groups---they have a very fleeting idea of article numbers. In fact, +each time you enter an @code{nnweb} group (not even changing the search +pattern), you are likely to get the articles ordered in a different +manner. Not even using duplicate suppression (@pxref{Duplicate +Suppression}) will help, since @code{nnweb} doesn't even know the +@code{Message-ID} of the articles before reading them using some search +engines (DejaNews, for instance). The only possible way to keep track +of which articles you've read is by scoring on the @code{Date} +header---mark all articles posted before the last date you read the +group as read. + +If the search engine changes its output substantially, @code{nnweb} +won't be able to parse it and will fail. One could hardly fault the Web +providers if they were to do this---their @emph{raison d'être} is to +make money off of advertisements, not to provide services to the +community. Since @code{nnweb} washes the ads off all the articles, one +might think that the providers might be somewhat miffed. We'll see. + +You must have the @code{url} and @code{w3} package installed to be able +to use @code{nnweb}. + +Virtual server variables: + +@table @code +@item nnweb-type +@vindex nnweb-type +What search engine type is being used. The currently supported types +are @code{dejanews}, @code{dejanewsold}, @code{altavista} and +@code{reference}. + +@item nnweb-search +@vindex nnweb-search +The search string to feed to the search engine. + +@item nnweb-max-hits +@vindex nnweb-max-hits +Advisory maximum number of hits per search to display. The default is +100. + +@item nnweb-type-definition +@vindex nnweb-type-definition +Type-to-definition alist. This alist says what @code{nnweb} should do +with the various search engine types. The following elements must be +present: + +@table @code +@item article +Function to decode the article and provide something that Gnus +understands. + +@item map +Function to create an article number to message header and URL alist. + +@item search +Function to send the search string to the search engine. + +@item address +The address the aforementioned function should send the search string +to. + +@item id +Format string URL to fetch an article by @code{Message-ID}. +@end table + +@end table + + + +@node Mail-To-News Gateways +@subsection Mail-To-News Gateways +@cindex mail-to-news gateways +@cindex gateways + +If your local @code{nntp} server doesn't allow posting, for some reason +or other, you can post using one of the numerous mail-to-news gateways. +The @code{nngateway} backend provides the interface. + +Note that you can't read anything from this backend---it can only be +used to post with. + +Server variables: + +@table @code +@item nngateway-address +@vindex nngateway-address +This is the address of the mail-to-news gateway. + +@item nngateway-header-transformation +@vindex nngateway-header-transformation +News headers often have to be transformed in some odd way or other +for the mail-to-news gateway to accept it. This variable says what +transformation should be called, and defaults to +@code{nngateway-simple-header-transformation}. The function is called +narrowed to the headers to be transformed and with one parameter---the +gateway address. + +This default function just inserts a new @code{To} header based on the +@code{Newsgroups} header and the gateway address. +For instance, an article with this @code{Newsgroups} header: + +@example +Newsgroups: alt.religion.emacs +@end example + +will get this @code{From} header inserted: + +@example +To: alt-religion-emacs@@GATEWAY +@end example + +The following pre-defined functions exist: + +@findex nngateway-simple-header-transformation +@table @code + +@item nngateway-simple-header-transformation +Creates a @code{To} header that looks like +@var{newsgroup}@@@code{nngateway-address}. + +@findex nngateway-mail2news-header-transformation + +@item nngateway-mail2news-header-transformation +Creates a @code{To} header that looks like +@code{nngateway-address}. + +Here's an example: + +@lisp +(setq gnus-post-method + '(nngateway "mail2news@@replay.com" + (nngateway-header-transformation + nngateway-mail2news-header-transformation))) +@end lisp + +@end table + + +@end table + +So, to use this, simply say something like: + +@lisp +(setq gnus-post-method '(nngateway "GATEWAY.ADDRESS")) +@end lisp + + +@node Combined Groups +@section Combined Groups + +Gnus allows combining a mixture of all the other group types into bigger +groups. + +@menu +* Virtual Groups:: Combining articles from many groups. +* Kibozed Groups:: Looking through parts of the newsfeed for articles. +@end menu + + +@node Virtual Groups +@subsection Virtual Groups +@cindex nnvirtual +@cindex virtual groups +@cindex merging groups + +An @dfn{nnvirtual group} is really nothing more than a collection of +other groups. + +For instance, if you are tired of reading many small groups, you can +put them all in one big group, and then grow tired of reading one +big, unwieldy group. The joys of computing! + +You specify @code{nnvirtual} as the method. The address should be a +regexp to match component groups. + +All marks in the virtual group will stick to the articles in the +component groups. So if you tick an article in a virtual group, the +article will also be ticked in the component group from whence it came. +(And vice versa---marks from the component groups will also be shown in +the virtual group.) + +Here's an example @code{nnvirtual} method that collects all Andrea Dworkin +newsgroups into one, big, happy newsgroup: + +@lisp +(nnvirtual "^alt\\.fan\\.andrea-dworkin$\\|^rec\\.dworkin.*") +@end lisp + +The component groups can be native or foreign; everything should work +smoothly, but if your computer explodes, it was probably my fault. + +Collecting the same group from several servers might actually be a good +idea if users have set the Distribution header to limit distribution. +If you would like to read @samp{soc.motss} both from a server in Japan +and a server in Norway, you could use the following as the group regexp: + +@example +"^nntp\\+server\\.jp:soc\\.motss$\\|^nntp\\+server\\.no:soc\\.motss$" +@end example + +(Remember, though, that if you're creating the group with @kbd{G m}, you +shouldn't double the backslashes, and you should leave off the quote +characters at the beginning and the end of the string.) + +This should work kinda smoothly---all articles from both groups should +end up in this one, and there should be no duplicates. Threading (and +the rest) will still work as usual, but there might be problems with the +sequence of articles. Sorting on date might be an option here +(@pxref{Selecting a Group}). + +One limitation, however---all groups included in a virtual +group have to be alive (i.e., subscribed or unsubscribed). Killed or +zombie groups can't be component groups for @code{nnvirtual} groups. + +@vindex nnvirtual-always-rescan +If the @code{nnvirtual-always-rescan} is non-@code{nil}, +@code{nnvirtual} will always scan groups for unread articles when +entering a virtual group. If this variable is @code{nil} (which is the +default) and you read articles in a component group after the virtual +group has been activated, the read articles from the component group +will show up when you enter the virtual group. You'll also see this +effect if you have two virtual groups that have a component group in +common. If that's the case, you should set this variable to @code{t}. +Or you can just tap @code{M-g} on the virtual group every time before +you enter it---it'll have much the same effect. + +@code{nnvirtual} can have both mail and news groups as component groups. +When responding to articles in @code{nnvirtual} groups, @code{nnvirtual} +has to ask the backend of the component group the article comes from +whether it is a news or mail backend. However, when you do a @kbd{^}, +there is typically no sure way for the component backend to know this, +and in that case @code{nnvirtual} tells Gnus that the article came from a +not-news backend. (Just to be on the safe side.) + +@kbd{C-c C-t} in the message buffer will insert the @code{Newsgroups} +line from the article you respond to in these cases. + + + +@node Kibozed Groups +@subsection Kibozed Groups +@cindex nnkiboze +@cindex kibozing + +@dfn{Kibozing} is defined by @sc{oed} as ``grepping through (parts of) +the news feed''. @code{nnkiboze} is a backend that will do this for +you. Oh joy! Now you can grind any @sc{nntp} server down to a halt +with useless requests! Oh happiness! + +@kindex G k (Group) +To create a kibozed group, use the @kbd{G k} command in the group +buffer. + +The address field of the @code{nnkiboze} method is, as with +@code{nnvirtual}, a regexp to match groups to be ``included'' in the +@code{nnkiboze} group. That's where most similarities between @code{nnkiboze} +and @code{nnvirtual} end. + +In addition to this regexp detailing component groups, an @code{nnkiboze} group +must have a score file to say what articles are to be included in +the group (@pxref{Scoring}). + +@kindex M-x nnkiboze-generate-groups +@findex nnkiboze-generate-groups +You must run @kbd{M-x nnkiboze-generate-groups} after creating the +@code{nnkiboze} groups you want to have. This command will take time. Lots of +time. Oodles and oodles of time. Gnus has to fetch the headers from +all the articles in all the component groups and run them through the +scoring process to determine if there are any articles in the groups +that are to be part of the @code{nnkiboze} groups. + +Please limit the number of component groups by using restrictive +regexps. Otherwise your sysadmin may become annoyed with you, and the +@sc{nntp} site may throw you off and never let you back in again. +Stranger things have happened. + +@code{nnkiboze} component groups do not have to be alive---they can be dead, +and they can be foreign. No restrictions. + +@vindex nnkiboze-directory +The generation of an @code{nnkiboze} group means writing two files in +@code{nnkiboze-directory}, which is @file{~/News/} by default. One +contains the @sc{nov} header lines for all the articles in the group, +and the other is an additional @file{.newsrc} file to store information +on what groups have been searched through to find component articles. + +Articles marked as read in the @code{nnkiboze} group will have +their @sc{nov} lines removed from the @sc{nov} file. + + +@node Gnus Unplugged +@section Gnus Unplugged +@cindex offline +@cindex unplugged +@cindex Agent +@cindex Gnus Agent +@cindex Gnus Unplugged + +In olden times (ca. February '88), people used to run their newsreaders +on big machines with permanent connections to the net. News transport +was dealt with by news servers, and all the newsreaders had to do was to +read news. Believe it or not. + +Nowadays most people read news and mail at home, and use some sort of +modem to connect to the net. To avoid running up huge phone bills, it +would be nice to have a way to slurp down all the news and mail, hang up +the phone, read for several hours, and then upload any responses you +have to make. And then you repeat the procedure. + +Of course, you can use news servers for doing this as well. I've used +@code{inn} together with @code{slurp}, @code{pop} and @code{sendmail} +for some years, but doing that's a bore. Moving the news server +functionality up to the newsreader makes sense if you're the only person +reading news on a machine. + +Using Gnus as an ``offline'' newsreader is quite simple. + +@itemize @bullet +@item +First, set up Gnus as you would do if you were running it on a machine +that has full connection to the net. Go ahead. I'll still be waiting +here. + +@item +Then, put the following magical incantation at the end of your +@file{.gnus.el} file: + +@lisp +(gnus-agentize) +@end lisp +@end itemize + +That's it. Gnus is now an ``offline'' newsreader. + +Of course, to use it as such, you have to learn a few new commands. + +@menu +* Agent Basics:: How it all is supposed to work. +* Agent Categories:: How to tell the Gnus Agent what to download. +* Agent Commands:: New commands for all the buffers. +* Agent Expiry:: How to make old articles go away. +* Outgoing Messages:: What happens when you post/mail something? +* Agent Variables:: Customizing is fun. +* Example Setup:: An example @file{.gnus.el} file for offline people. +* Batching Agents:: How to fetch news from a @code{cron} job. +@end menu + + +@node Agent Basics +@subsection Agent Basics + +First, let's get some terminology out of the way. + +The Gnus Agent is said to be @dfn{unplugged} when you have severed the +connection to the net (and notified the Agent that this is the case). +When the connection to the net is up again (and Gnus knows this), the +Agent is @dfn{plugged}. + +The @dfn{local} machine is the one you're running on, and which isn't +connected to the net continuously. + +@dfn{Downloading} means fetching things from the net to your local +machine. @dfn{Uploading} is doing the opposite. + +Let's take a typical Gnus session using the Agent. + +@itemize @bullet + +@item +You start Gnus with @code{gnus-unplugged}. This brings up the Gnus +Agent in a disconnected state. You can read all the news that you have +already fetched while in this mode. + +@item +You then decide to see whether any new news has arrived. You connect +your machine to the net (using PPP or whatever), and then hit @kbd{J j} +to make Gnus become @dfn{plugged}. + +@item +You can then read the new news immediately, or you can download the news +onto your local machine. If you want to do the latter, you press @kbd{J +s} to fetch all the eligible articles in all the groups. (To let Gnus +know which articles you want to download, @pxref{Agent Categories}.) + +@item +After fetching the articles, you press @kbd{J j} to make Gnus become +unplugged again, and you shut down the PPP thing (or whatever). And +then you read the news offline. + +@item +And then you go to step 2. +@end itemize + +Here are some things you should do the first time (or so) that you use +the Agent. + +@itemize @bullet + +@item +Decide which servers should be covered by the Agent. If you have a mail +backend, it would probably be nonsensical to have it covered by the +Agent. Go to the server buffer (@kbd{^} in the group buffer) and press +@kbd{J a} the server (or servers) that you wish to have covered by the +Agent (@pxref{Server Agent Commands}). This will typically be only the +primary select method, which is listed on the bottom in the buffer. + +@item +Decide on download policy. @xref{Agent Categories}. + +@item +Uhm... that's it. +@end itemize + + +@node Agent Categories +@subsection Agent Categories + +One of the main reasons to integrate the news transport layer into the +newsreader is to allow greater control over what articles to download. +There's not much point in downloading huge amounts of articles, just to +find out that you're not interested in reading any of them. It's better +to be somewhat more conservative in choosing what to download, and then +mark the articles for downloading manually if it should turn out that +you're interested in the articles anyway. + +The main way to control what is to be downloaded is to create a +@dfn{category} and then assign some (or all) groups to this category. +Gnus has its own buffer for creating and managing categories. + +@menu +* Category Syntax:: What a category looks like. +* The Category Buffer:: A buffer for maintaining categories. +* Category Variables:: Customize'r'Us. +@end menu + + +@node Category Syntax +@subsubsection Category Syntax + +A category consists of two things. + +@enumerate +@item +A predicate which (generally) gives a rough outline of which articles +are eligible for downloading; and + +@item +a score rule which (generally) gives you a finer granularity when +deciding what articles to download. (Note that this @dfn{download +score} is wholly unrelated to normal scores.) +@end enumerate + +A predicate consists of predicates with logical operators sprinkled in +between. + +Perhaps some examples are in order. + +Here's a simple predicate. (It's the default predicate, in fact, used +for all groups that don't belong to any other category.) + +@lisp +short +@end lisp + +Quite simple, eh? This predicate is true if and only if the article is +short (for some value of ``short''). + +Here's a more complex predicate: + +@lisp +(or high + (and + (not low) + (not long))) +@end lisp + +This means that an article should be downloaded if it has a high score, +or if the score is not low and the article is not long. You get the +drift. + +The available logical operators are @code{or}, @code{and} and +@code{not}. (If you prefer, you can use the more ``C''-ish operators +@samp{|}, @code{&} and @code{!} instead.) + +The following predicates are pre-defined, but if none of these fit what +you want to do, you can write your own. + +@table @code +@item short +True iff the article is shorter than @code{gnus-agent-short-article} +lines; default 100. + +@item long +True iff the article is longer than @code{gnus-agent-long-article} +lines; default 200. + +@item low +True iff the article has a download score less than +@code{gnus-agent-low-score}; default 0. + +@item high +True iff the article has a download score greater than +@code{gnus-agent-high-score}; default 0. + +@item spam +True iff the Gnus Agent guesses that the article is spam. The +heuristics may change over time, but at present it just computes a +checksum and sees whether articles match. + +@item true +Always true. + +@item false +Always false. +@end table + +If you want to create your own predicate function, here's what you have +to know: The functions are called with no parameters, but the +@code{gnus-headers} and @code{gnus-score} dynamic variables are bound to +useful values. + +Now, the syntax of the download score is the same as the syntax of +normal score files, except that all elements that require actually +seeing the article itself are verboten. This means that only the +following headers can be scored on: @code{From}, @code{Subject}, +@code{Date}, @code{Xref}, @code{Lines}, @code{Chars}, @code{Message-ID}, +and @code{References}. + + +@node The Category Buffer +@subsubsection The Category Buffer + +You'd normally do all category maintenance from the category buffer. +When you enter it for the first time (with the @kbd{J c} command from +the group buffer), you'll only see the @code{default} category. + +The following commands are available in this buffer: + +@table @kbd +@item q +@kindex q (Category) +@findex gnus-category-exit +Return to the group buffer (@code{gnus-category-exit}). + +@item k +@kindex k (Category) +@findex gnus-category-kill +Kill the current category (@code{gnus-category-kill}). + +@item c +@kindex c (Category) +@findex gnus-category-copy +Copy the current category (@code{gnus-category-copy}). + +@item a +@kindex a (Category) +@findex gnus-category-add +Add a new category (@code{gnus-category-add}). + +@item p +@kindex p (Category) +@findex gnus-category-edit-predicate +Edit the predicate of the current category +(@code{gnus-category-edit-predicate}). + +@item g +@kindex g (Category) +@findex gnus-category-edit-groups +Edit the list of groups belonging to the current category +(@code{gnus-category-edit-groups}). + +@item s +@kindex s (Category) +@findex gnus-category-edit-score +Edit the download score rule of the current category +(@code{gnus-category-edit-score}). + +@item l +@kindex l (Category) +@findex gnus-category-list +List all the categories (@code{gnus-category-list}). +@end table + + +@node Category Variables +@subsubsection Category Variables + +@table @code +@item gnus-category-mode-hook +@vindex gnus-category-mode-hook +Hook run in category buffers. + +@item gnus-category-line-format +@vindex gnus-category-line-format +Format of the lines in the category buffer (@pxref{Formatting +Variables}). Valid elements are: + +@table @samp +@item c +The name of the category. + +@item g +The number of groups in the category. +@end table + +@item gnus-category-mode-line-format +@vindex gnus-category-mode-line-format +Format of the category mode line (@pxref{Mode Line Formatting}). + +@item gnus-agent-short-article +@vindex gnus-agent-short-article +Articles that have fewer lines than this are short. Default 100. + +@item gnus-agent-long-article +@vindex gnus-agent-long-article +Articles that have more lines than this are long. Default 200. + +@item gnus-agent-low-score +@vindex gnus-agent-low-score +Articles that have a score lower than this have a low score. Default +0. + +@item gnus-agent-high-score +@vindex gnus-agent-high-score +Articles that have a score higher than this have a high score. Default +0. + +@end table + + +@node Agent Commands +@subsection Agent Commands + +All the Gnus Agent commands are on the @kbd{J} submap. The @kbd{J j} +(@code{gnus-agent-toggle-plugged} command works in all modes, and +toggles the plugged/unplugged state of the Gnus Agent. + + +@menu +* Group Agent Commands:: +* Summary Agent Commands:: +* Server Agent Commands:: +@end menu + +You can run a complete batch fetch from the command line with the +following incantation: + +@cindex gnus-agent-batch-fetch +@example +$ emacs -batch -l ~/.gnus.el -f gnus-agent-batch-fetch +@end example + + + +@node Group Agent Commands +@subsubsection Group Agent Commands + +@table @kbd +@item J u +@kindex J u (Agent Group) +@findex gnus-agent-fetch-groups +Fetch all eligible articles in the current group +(@code{gnus-agent-fetch-groups}). + +@item J c +@kindex J c (Agent Group) +@findex gnus-enter-category-buffer +Enter the Agent category buffer (@code{gnus-enter-category-buffer}). + +@item J s +@kindex J s (Agent Group) +@findex gnus-agent-fetch-session +Fetch all eligible articles in all groups +(@code{gnus-agent-fetch-session}). + +@item J S +@kindex J S (Agent Group) +@findex gnus-group-send-drafts +Send all sendable messages in the draft group +(@code{gnus-agent-fetch-session}). @xref{Drafts}. + +@item J a +@kindex J a (Agent Group) +@findex gnus-agent-add-group +Add the current group to an Agent category +(@code{gnus-agent-add-group}). + +@end table + + +@node Summary Agent Commands +@subsubsection Summary Agent Commands + +@table @kbd +@item J # +@kindex J # (Agent Summary) +@findex gnus-agent-mark-article +Mark the article for downloading (@code{gnus-agent-mark-article}). + +@item J M-# +@kindex J M-# (Agent Summary) +@findex gnus-agent-unmark-article +Remove the downloading mark from the article +(@code{gnus-agent-unmark-article}). + +@item @@ +@kindex @@ (Agent Summary) +@findex gnus-agent-toggle-mark +Toggle whether to download the article (@code{gnus-agent-toggle-mark}). + +@item J c +@kindex J c (Agent Summary) +@findex gnus-agent-catchup +Mark all undownloaded articles as read (@code{gnus-agent-catchup}). + +@end table + + +@node Server Agent Commands +@subsubsection Server Agent Commands + +@table @kbd +@item J a +@kindex J a (Agent Server) +@findex gnus-agent-add-server +Add the current server to the list of servers covered by the Gnus Agent +(@code{gnus-agent-add-server}). + +@item J r +@kindex J r (Agent Server) +@findex gnus-agent-remove-server +Remove the current server from the list of servers covered by the Gnus +Agent (@code{gnus-agent-remove-server}). + +@end table + + +@node Agent Expiry +@subsection Agent Expiry + +@vindex gnus-agent-expire-days +@findex gnus-agent-expire +@kindex M-x gnus-agent-expire +@cindex Agent expire +@cindex Gnus Agent expire +@cindex expiry + +@code{nnagent} doesn't handle expiry. Instead, there's a special +@code{gnus-agent-expire} command that will expire all read articles that +are older than @code{gnus-agent-expire-days} days. It can be run +whenever you feel that you're running out of space. It's not +particularly fast or efficient, and it's not a particularly good idea to +interrupt it (with @kbd{C-g} or anything else) once you've started it. + +@vindex gnus-agent-expire-all +if @code{gnus-agent-expire-all} is non-@code{nil}, this command will +expire all articles---unread, read, ticked and dormant. If @code{nil} +(which is the default), only read articles are eligible for expiry, and +unread, ticked and dormant articles will be kept indefinitely. + + +@node Outgoing Messages +@subsection Outgoing Messages + +When Gnus is unplugged, all outgoing messages (both mail and news) are +stored in the draft groups (@pxref{Drafts}). You can view them there +after posting, and edit them at will. + +When Gnus is plugged again, you can send the messages either from the +draft group with the special commands available there, or you can use +the @kbd{J S} command in the group buffer to send all the sendable +messages in the draft group. + + + +@node Agent Variables +@subsection Agent Variables + +@table @code +@item gnus-agent-directory +@vindex gnus-agent-directory +Where the Gnus Agent will store its files. The default is +@file{~/News/agent/}. + +@item gnus-agent-handle-level +@vindex gnus-agent-handle-level +Groups on levels (@pxref{Group Levels}) higher than this variable will +be ignored by the Agent. The default is @code{gnus-level-subscribed}, +which means that only subscribed group will be considered by the Agent +by default. + +@item gnus-agent-plugged-hook +@vindex gnus-agent-plugged-hook +Hook run when connecting to the network. + +@item gnus-agent-unplugged-hook +@vindex gnus-agent-unplugged-hook +Hook run when disconnecting from the network. + +@end table + + +@node Example Setup +@subsection Example Setup + +If you don't want to read this manual, and you have a fairly standard +setup, you may be able to use something like the following as your +@file{.gnus.el} file to get started. + +@lisp +;;; Define how Gnus is to fetch news. We do this over NNTP +;;; from your ISP's server. +(setq gnus-select-method '(nntp "nntp.your-isp.com")) + +;;; Define how Gnus is to read your mail. We read mail from +;;; your ISP's POP server. +(setenv "MAILHOST" "pop.your-isp.com") +(setq nnmail-spool-file "po:username") + +;;; Say how Gnus is to store the mail. We use nnml groups. +(setq gnus-secondary-select-methods '((nnml ""))) + +;;; Make Gnus into an offline newsreader. +(gnus-agentize) +@end lisp + +That should be it, basically. Put that in your @file{~/.gnus.el} file, +edit to suit your needs, start up PPP (or whatever), and type @kbd{M-x +gnus}. + +If this is the first time you've run Gnus, you will be subscribed +automatically to a few default newsgroups. You'll probably want to +subscribe to more groups, and to do that, you have to query the +@sc{nntp} server for a complete list of groups with the @kbd{A A} +command. This usually takes quite a while, but you only have to do it +once. + +After reading and parsing a while, you'll be presented with a list of +groups. Subscribe to the ones you want to read with the @kbd{u} +command. @kbd{l} to make all the killed groups disappear after you've +subscribe to all the groups you want to read. (@kbd{A k} will bring +back all the killed groups.) + +You can now read the groups at once, or you can download the articles +with the @kbd{J s} command. And then read the rest of this manual to +find out which of the other gazillion things you want to customize. + + +@node Batching Agents +@subsection Batching Agents + +Having the Gnus Agent fetch articles (and post whatever messages you've +written) is quite easy once you've gotten things set up properly. The +following shell script will do everything that is necessary: + +@example +#!/bin/sh +emacs -batch -l ~/.emacs -f gnus-agent-batch >/dev/null +@end example + + + +@node Scoring +@chapter Scoring +@cindex scoring + +Other people use @dfn{kill files}, but we here at Gnus Towers like +scoring better than killing, so we'd rather switch than fight. They do +something completely different as well, so sit up straight and pay +attention! + +@vindex gnus-summary-mark-below +All articles have a default score (@code{gnus-summary-default-score}), +which is 0 by default. This score may be raised or lowered either +interactively or by score files. Articles that have a score lower than +@code{gnus-summary-mark-below} are marked as read. + +Gnus will read any @dfn{score files} that apply to the current group +before generating the summary buffer. + +There are several commands in the summary buffer that insert score +entries based on the current article. You can, for instance, ask Gnus to +lower or increase the score of all articles with a certain subject. + +There are two sorts of scoring entries: Permanent and temporary. +Temporary score entries are self-expiring entries. Any entries that are +temporary and have not been used for, say, a week, will be removed +silently to help keep the sizes of the score files down. + +@menu +* Summary Score Commands:: Adding score entries for the current group. +* Group Score Commands:: General score commands. +* Score Variables:: Customize your scoring. (My, what terminology). +* Score File Format:: What a score file may contain. +* Score File Editing:: You can edit score files by hand as well. +* Adaptive Scoring:: Big Sister Gnus knows what you read. +* Home Score File:: How to say where new score entries are to go. +* Followups To Yourself:: Having Gnus notice when people answer you. +* Scoring Tips:: How to score effectively. +* Reverse Scoring:: That problem child of old is not problem. +* Global Score Files:: Earth-spanning, ear-splitting score files. +* Kill Files:: They are still here, but they can be ignored. +* Converting Kill Files:: Translating kill files to score files. +* GroupLens:: Getting predictions on what you like to read. +* Advanced Scoring:: Using logical expressions to build score rules. +* Score Decays:: It can be useful to let scores wither away. +@end menu + + +@node Summary Score Commands +@section Summary Score Commands +@cindex score commands + +The score commands that alter score entries do not actually modify real +score files. That would be too inefficient. Gnus maintains a cache of +previously loaded score files, one of which is considered the +@dfn{current score file alist}. The score commands simply insert +entries into this list, and upon group exit, this list is saved. + +The current score file is by default the group's local score file, even +if no such score file actually exists. To insert score commands into +some other score file (e.g. @file{all.SCORE}), you must first make this +score file the current one. + +General score commands that don't actually change the score file: + +@table @kbd + +@item V s +@kindex V s (Summary) +@findex gnus-summary-set-score +Set the score of the current article (@code{gnus-summary-set-score}). + +@item V S +@kindex V S (Summary) +@findex gnus-summary-current-score +Display the score of the current article +(@code{gnus-summary-current-score}). + +@item V t +@kindex V t (Summary) +@findex gnus-score-find-trace +Display all score rules that have been used on the current article +(@code{gnus-score-find-trace}). + +@item V R +@kindex V R (Summary) +@findex gnus-summary-rescore +Run the current summary through the scoring process +(@code{gnus-summary-rescore}). This might be useful if you're playing +around with your score files behind Gnus' back and want to see the +effect you're having. + +@item V c +@kindex V c (Summary) +@findex gnus-score-change-score-file +Make a different score file the current +(@code{gnus-score-change-score-file}). + +@item V e +@kindex V e (Summary) +@findex gnus-score-edit-current-scores +Edit the current score file (@code{gnus-score-edit-current-scores}). +You will be popped into a @code{gnus-score-mode} buffer (@pxref{Score +File Editing}). + +@item V f +@kindex V f (Summary) +@findex gnus-score-edit-file +Edit a score file and make this score file the current one +(@code{gnus-score-edit-file}). + +@item V F +@kindex V F (Summary) +@findex gnus-score-flush-cache +Flush the score cache (@code{gnus-score-flush-cache}). This is useful +after editing score files. + +@item V C +@kindex V C (Summary) +@findex gnus-score-customize +Customize a score file in a visually pleasing manner +(@code{gnus-score-customize}). + +@end table + +The rest of these commands modify the local score file. + +@table @kbd + +@item V m +@kindex V m (Summary) +@findex gnus-score-set-mark-below +Prompt for a score, and mark all articles with a score below this as +read (@code{gnus-score-set-mark-below}). + +@item V x +@kindex V x (Summary) +@findex gnus-score-set-expunge-below +Prompt for a score, and add a score rule to the current score file to +expunge all articles below this score +(@code{gnus-score-set-expunge-below}). +@end table + +The keystrokes for actually making score entries follow a very regular +pattern, so there's no need to list all the commands. (Hundreds of +them.) + +@findex gnus-summary-increase-score +@findex gnus-summary-lower-score + +@enumerate +@item +The first key is either @kbd{I} (upper case i) for increasing the score +or @kbd{L} for lowering the score. +@item +The second key says what header you want to score on. The following +keys are available: +@table @kbd + +@item a +Score on the author name. + +@item s +Score on the subject line. + +@item x +Score on the Xref line---i.e., the cross-posting line. + +@item r +Score on the References line. + +@item d +Score on the date. + +@item l +Score on the number of lines. + +@item i +Score on the Message-ID. + +@item f +Score on followups. + +@item b +Score on the body. + +@item h +Score on the head. + +@item t +Score on thead. + +@end table + +@item +The third key is the match type. Which match types are valid depends on +what headers you are scoring on. + +@table @code + +@item strings + +@table @kbd + +@item e +Exact matching. + +@item s +Substring matching. + +@item f +Fuzzy matching (@pxref{Fuzzy Matching}). + +@item r +Regexp matching +@end table + +@item date +@table @kbd + +@item b +Before date. + +@item a +After date. + +@item n +This date. +@end table + +@item number +@table @kbd + +@item < +Less than number. + +@item = +Equal to number. + +@item > +Greater than number. +@end table +@end table + +@item +The fourth and final key says whether this is a temporary (i.e., expiring) +score entry, or a permanent (i.e., non-expiring) score entry, or whether +it is to be done immediately, without adding to the score file. +@table @kbd + +@item t +Temporary score entry. + +@item p +Permanent score entry. + +@item i +Immediately scoring. +@end table + +@end enumerate + +So, let's say you want to increase the score on the current author with +exact matching permanently: @kbd{I a e p}. If you want to lower the +score based on the subject line, using substring matching, and make a +temporary score entry: @kbd{L s s t}. Pretty easy. + +To make things a bit more complicated, there are shortcuts. If you use +a capital letter on either the second or third keys, Gnus will use +defaults for the remaining one or two keystrokes. The defaults are +``substring'' and ``temporary''. So @kbd{I A} is the same as @kbd{I a s +t}, and @kbd{I a R} is the same as @kbd{I a r t}. + +These functions take both the numerical prefix and the symbolic prefix +(@pxref{Symbolic Prefixes}). A numerical prefix says how much to lower +(or increase) the score of the article. A symbolic prefix of @code{a} +says to use the @file{all.SCORE} file for the command instead of the +current score file. + +@vindex gnus-score-mimic-keymap +The @code{gnus-score-mimic-keymap} says whether these commands will +pretend they are keymaps or not. + + +@node Group Score Commands +@section Group Score Commands +@cindex group score commands + +There aren't many of these as yet, I'm afraid. + +@table @kbd + +@item W f +@kindex W f (Group) +@findex gnus-score-flush-cache +Gnus maintains a cache of score alists to avoid having to reload them +all the time. This command will flush the cache +(@code{gnus-score-flush-cache}). + +@end table + +You can do scoring from the command line by saying something like: + +@findex gnus-batch-score +@cindex batch scoring +@example +$ emacs -batch -l ~/.emacs -l gnus -f gnus-batch-score +@end example + + +@node Score Variables +@section Score Variables +@cindex score variables + +@table @code + +@item gnus-use-scoring +@vindex gnus-use-scoring +If @code{nil}, Gnus will not check for score files, and will not, in +general, do any score-related work. This is @code{t} by default. + +@item gnus-kill-killed +@vindex gnus-kill-killed +If this variable is @code{nil}, Gnus will never apply score files to +articles that have already been through the kill process. While this +may save you lots of time, it also means that if you apply a kill file +to a group, and then change the kill file and want to run it over you +group again to kill more articles, it won't work. You have to set this +variable to @code{t} to do that. (It is @code{t} by default.) + +@item gnus-kill-files-directory +@vindex gnus-kill-files-directory +All kill and score files will be stored in this directory, which is +initialized from the @code{SAVEDIR} environment variable by default. +This is @file{~/News/} by default. + +@item gnus-score-file-suffix +@vindex gnus-score-file-suffix +Suffix to add to the group name to arrive at the score file name +(@samp{SCORE} by default.) + +@item gnus-score-uncacheable-files +@vindex gnus-score-uncacheable-files +@cindex score cache +All score files are normally cached to avoid excessive re-loading of +score files. However, if this might make you Emacs grow big and +bloated, so this regexp can be used to weed out score files unlikely to be needed again. It would be a bad idea to deny caching of +@file{all.SCORE}, while it might be a good idea to not cache +@file{comp.infosystems.www.authoring.misc.ADAPT}. In fact, this +variable is @samp{ADAPT$} by default, so no adaptive score files will +be cached. + +@item gnus-save-score +@vindex gnus-save-score +If you have really complicated score files, and do lots of batch +scoring, then you might set this variable to @code{t}. This will make +Gnus save the scores into the @file{.newsrc.eld} file. + +@item gnus-score-interactive-default-score +@vindex gnus-score-interactive-default-score +Score used by all the interactive raise/lower commands to raise/lower +score with. Default is 1000, which may seem excessive, but this is to +ensure that the adaptive scoring scheme gets enough room to play with. +We don't want the small changes from the adaptive scoring to overwrite +manually entered data. + +@item gnus-summary-default-score +@vindex gnus-summary-default-score +Default score of an article, which is 0 by default. + +@item gnus-summary-expunge-below +@vindex gnus-summary-expunge-below +Don't display the summary lines of articles that have scores lower than +this variable. This is @code{nil} by default, which means that no +articles will be hidden. This variable is local to the summary buffers, +and has to be set from @code{gnus-summary-mode-hook}. + +@item gnus-score-over-mark +@vindex gnus-score-over-mark +Mark (in the third column) used for articles with a score over the +default. Default is @samp{+}. + +@item gnus-score-below-mark +@vindex gnus-score-below-mark +Mark (in the third column) used for articles with a score below the +default. Default is @samp{-}. + +@item gnus-score-find-score-files-function +@vindex gnus-score-find-score-files-function +Function used to find score files for the current group. This function +is called with the name of the group as the argument. + +Predefined functions available are: +@table @code + +@item gnus-score-find-single +@findex gnus-score-find-single +Only apply the group's own score file. + +@item gnus-score-find-bnews +@findex gnus-score-find-bnews +Apply all score files that match, using bnews syntax. This is the +default. If the current group is @samp{gnu.emacs.gnus}, for instance, +@file{all.emacs.all.SCORE}, @file{not.alt.all.SCORE} and +@file{gnu.all.SCORE} would all apply. In short, the instances of +@samp{all} in the score file names are translated into @samp{.*}, and +then a regexp match is done. + +This means that if you have some score entries that you want to apply to +all groups, then you put those entries in the @file{all.SCORE} file. + +The score files are applied in a semi-random order, although Gnus will +try to apply the more general score files before the more specific score +files. It does this by looking at the number of elements in the score +file names---discarding the @samp{all} elements. + +@item gnus-score-find-hierarchical +@findex gnus-score-find-hierarchical +Apply all score files from all the parent groups. This means that you +can't have score files like @file{all.SCORE}, but you can have +@file{SCORE}, @file{comp.SCORE} and @file{comp.emacs.SCORE}. + +@end table +This variable can also be a list of functions. In that case, all these +functions will be called, and all the returned lists of score files will +be applied. These functions can also return lists of score alists +directly. In that case, the functions that return these non-file score +alists should probably be placed before the ``real'' score file +functions, to ensure that the last score file returned is the local +score file. Phu. + +@item gnus-score-expiry-days +@vindex gnus-score-expiry-days +This variable says how many days should pass before an unused score file +entry is expired. If this variable is @code{nil}, no score file entries +are expired. It's 7 by default. + +@item gnus-update-score-entry-dates +@vindex gnus-update-score-entry-dates +If this variable is non-@code{nil}, matching score entries will have +their dates updated. (This is how Gnus controls expiry---all +non-matching entries will become too old while matching entries will +stay fresh and young.) However, if you set this variable to @code{nil}, +even matching entries will grow old and will have to face that oh-so +grim reaper. + +@item gnus-score-after-write-file-function +@vindex gnus-score-after-write-file-function +Function called with the name of the score file just written. + +@item gnus-score-thread-simplify +@vindex gnus-score-thread-simplify +If this variable is non-@code{nil}, article subjects will be simplified +for subject scoring purposes in the same manner as with +threading---according to the current value of +gnus-simplify-subject-functions. If the scoring entry uses +@code{substring} or @code{exact} matching, the match will also be +simplified in this manner. + +@end table + + +@node Score File Format +@section Score File Format +@cindex score file format + +A score file is an @code{emacs-lisp} file that normally contains just a +single form. Casual users are not expected to edit these files; +everything can be changed from the summary buffer. + +Anyway, if you'd like to dig into it yourself, here's an example: + +@lisp +(("from" + ("Lars Ingebrigtsen" -10000) + ("Per Abrahamsen") + ("larsi\\|lmi" -50000 nil R)) + ("subject" + ("Ding is Badd" nil 728373)) + ("xref" + ("alt.politics" -1000 728372 s)) + ("lines" + (2 -100 nil <)) + (mark 0) + (expunge -1000) + (mark-and-expunge -10) + (read-only nil) + (orphan -10) + (adapt t) + (files "/hom/larsi/News/gnu.SCORE") + (exclude-files "all.SCORE") + (local (gnus-newsgroup-auto-expire t) + (gnus-summary-make-false-root empty)) + (eval (ding))) +@end lisp + +This example demonstrates most score file elements. For a different +approach, see @pxref{Advanced Scoring}. + +Even though this looks much like lisp code, nothing here is actually +@code{eval}ed. The lisp reader is used to read this form, though, so it +has to be valid syntactically, if not semantically. + +Six keys are supported by this alist: + +@table @code + +@item STRING +If the key is a string, it is the name of the header to perform the +match on. Scoring can only be performed on these eight headers: +@code{From}, @code{Subject}, @code{References}, @code{Message-ID}, +@code{Xref}, @code{Lines}, @code{Chars} and @code{Date}. In addition to +these headers, there are three strings to tell Gnus to fetch the entire +article and do the match on larger parts of the article: @code{Body} +will perform the match on the body of the article, @code{Head} will +perform the match on the head of the article, and @code{All} will +perform the match on the entire article. Note that using any of these +last three keys will slow down group entry @emph{considerably}. The +final ``header'' you can score on is @code{Followup}. These score +entries will result in new score entries being added for all follow-ups +to articles that matches these score entries. + +Following this key is a arbitrary number of score entries, where each +score entry has one to four elements. +@enumerate + +@item +The first element is the @dfn{match element}. On most headers this will +be a string, but on the Lines and Chars headers, this must be an +integer. + +@item +If the second element is present, it should be a number---the @dfn{score +element}. This number should be an integer in the neginf to posinf +interval. This number is added to the score of the article if the match +is successful. If this element is not present, the +@code{gnus-score-interactive-default-score} number will be used +instead. This is 1000 by default. + +@item +If the third element is present, it should be a number---the @dfn{date +element}. This date says when the last time this score entry matched, +which provides a mechanism for expiring the score entries. It this +element is not present, the score entry is permanent. The date is +represented by the number of days since December 31, 1 BCE. + +@item +If the fourth element is present, it should be a symbol---the @dfn{type +element}. This element specifies what function should be used to see +whether this score entry matches the article. What match types that can +be used depends on what header you wish to perform the match on. +@table @dfn + +@item From, Subject, References, Xref, Message-ID +For most header types, there are the @code{r} and @code{R} (regexp), as +well as @code{s} and @code{S} (substring) types, and @code{e} and +@code{E} (exact match), and @code{w} (word match) types. If this +element is not present, Gnus will assume that substring matching should +be used. @code{R}, @code{S}, and @code{E} differ from the others in +that the matches will be done in a case-sensitive manner. All these +one-letter types are really just abbreviations for the @code{regexp}, +@code{string}, @code{exact}, and @code{word} types, which you can use +instead, if you feel like. + +@item Lines, Chars +These two headers use different match types: @code{<}, @code{>}, +@code{=}, @code{>=} and @code{<=}. + +These predicates are true if + +@example +(PREDICATE HEADER MATCH) +@end example + +evaluates to non-@code{nil}. For instance, the advanced match +@code{("lines" 4 <)} (@pxref{Advanced Scoring}) will result in the +following form: + +@lisp +(< header-value 4) +@end lisp + +Or to put it another way: When using @code{<} on @code{Lines} with 4 as +the match, we get the score added if the article has less than 4 lines. +(It's easy to get confused and think it's the other way around. But +it's not. I think.) + +When matching on @code{Lines}, be careful because some backends (like +@code{nndir}) do not generate @code{Lines} header, so every article ends +up being marked as having 0 lines. This can lead to strange results if +you happen to lower score of the articles with few lines. + +@item Date +For the Date header we have three kinda silly match types: +@code{before}, @code{at} and @code{after}. I can't really imagine this +ever being useful, but, like, it would feel kinda silly not to provide +this function. Just in case. You never know. Better safe than sorry. +Once burnt, twice shy. Don't judge a book by its cover. Never not have +sex on a first date. (I have been told that at least one person, and I +quote, ``found this function indispensable'', however.) + +@cindex ISO8601 +@cindex date +A more useful match type is @code{regexp}. With it, you can match the +date string using a regular expression. The date is normalized to +ISO8601 compact format first---@var{YYYYMMDD}@code{T}@var{HHMMSS}. If +you want to match all articles that have been posted on April 1st in +every year, you could use @samp{....0401.........} as a match string, +for instance. (Note that the date is kept in its original time zone, so +this will match articles that were posted when it was April 1st where +the article was posted from. Time zones are such wholesome fun for the +whole family, eh?) + +@item Head, Body, All +These three match keys use the same match types as the @code{From} (etc) +header uses. + +@item Followup +This match key is somewhat special, in that it will match the +@code{From} header, and affect the score of not only the matching +articles, but also all followups to the matching articles. This allows +you e.g. increase the score of followups to your own articles, or +decrease the score of followups to the articles of some known +trouble-maker. Uses the same match types as the @code{From} header +uses. (Using this match key will lead to creation of @file{ADAPT} +files.) + +@item Thread +This match key works along the same lines as the @code{Followup} match +key. If you say that you want to score on a (sub-)thread started by an article with a @code{Message-ID} @var{X}, then you add a +@samp{thread} match. This will add a new @samp{thread} match for each +article that has @var{X} in its @code{References} header. (These new +@samp{thread} matches will use the @code{Message-ID}s of these matching +articles.) This will ensure that you can raise/lower the score of an +entire thread, even though some articles in the thread may not have +complete @code{References} headers. Note that using this may lead to +undeterministic scores of the articles in the thread. (Using this match +key will lead to creation of @file{ADAPT} files.) +@end table +@end enumerate + +@cindex Score File Atoms +@item mark +The value of this entry should be a number. Any articles with a score +lower than this number will be marked as read. + +@item expunge +The value of this entry should be a number. Any articles with a score +lower than this number will be removed from the summary buffer. + +@item mark-and-expunge +The value of this entry should be a number. Any articles with a score +lower than this number will be marked as read and removed from the +summary buffer. + +@item thread-mark-and-expunge +The value of this entry should be a number. All articles that belong to +a thread that has a total score below this number will be marked as read +and removed from the summary buffer. @code{gnus-thread-score-function} +says how to compute the total score for a thread. + +@item files +The value of this entry should be any number of file names. These files +are assumed to be score files as well, and will be loaded the same way +this one was. + +@item exclude-files +The clue of this entry should be any number of files. These files will +not be loaded, even though they would normally be so, for some reason or +other. + +@item eval +The value of this entry will be @code{eval}el. This element will be +ignored when handling global score files. + +@item read-only +Read-only score files will not be updated or saved. Global score files +should feature this atom (@pxref{Global Score Files}). (Note: +@dfn{Global} here really means @dfn{global}; not your personal +apply-to-all-groups score files.) + +@item orphan +The value of this entry should be a number. Articles that do not have +parents will get this number added to their scores. Imagine you follow +some high-volume newsgroup, like @samp{comp.lang.c}. Most likely you +will only follow a few of the threads, also want to see any new threads. + +You can do this with the following two score file entries: + +@example + (orphan -500) + (mark-and-expunge -100) +@end example + +When you enter the group the first time, you will only see the new +threads. You then raise the score of the threads that you find +interesting (with @kbd{I T} or @kbd{I S}), and ignore (@kbd{C y}) the +rest. Next time you enter the group, you will see new articles in the +interesting threads, plus any new threads. + +I.e.---the orphan score atom is for high-volume groups where there +exist a few interesting threads which can't be found automatically by +ordinary scoring rules. + +@item adapt +This entry controls the adaptive scoring. If it is @code{t}, the +default adaptive scoring rules will be used. If it is @code{ignore}, no +adaptive scoring will be performed on this group. If it is a list, this +list will be used as the adaptive scoring rules. If it isn't present, +or is something other than @code{t} or @code{ignore}, the default +adaptive scoring rules will be used. If you want to use adaptive +scoring on most groups, you'd set @code{gnus-use-adaptive-scoring} to +@code{t}, and insert an @code{(adapt ignore)} in the groups where you do +not want adaptive scoring. If you only want adaptive scoring in a few +groups, you'd set @code{gnus-use-adaptive-scoring} to @code{nil}, and +insert @code{(adapt t)} in the score files of the groups where you want +it. + +@item adapt-file +All adaptive score entries will go to the file named by this entry. It +will also be applied when entering the group. This atom might be handy +if you want to adapt on several groups at once, using the same adaptive +file for a number of groups. + +@item local +@cindex local variables +The value of this entry should be a list of @code{(VAR VALUE)} pairs. +Each @var{var} will be made buffer-local to the current summary buffer, +and set to the value specified. This is a convenient, if somewhat +strange, way of setting variables in some groups if you don't like hooks +much. Note that the @var{value} won't be evaluated. +@end table + + +@node Score File Editing +@section Score File Editing + +You normally enter all scoring commands from the summary buffer, but you +might feel the urge to edit them by hand as well, so we've supplied you +with a mode for that. + +It's simply a slightly customized @code{emacs-lisp} mode, with these +additional commands: + +@table @kbd + +@item C-c C-c +@kindex C-c C-c (Score) +@findex gnus-score-edit-done +Save the changes you have made and return to the summary buffer +(@code{gnus-score-edit-done}). + +@item C-c C-d +@kindex C-c C-d (Score) +@findex gnus-score-edit-insert-date +Insert the current date in numerical format +(@code{gnus-score-edit-insert-date}). This is really the day number, if +you were wondering. + +@item C-c C-p +@kindex C-c C-p (Score) +@findex gnus-score-pretty-print +The adaptive score files are saved in an unformatted fashion. If you +intend to read one of these files, you want to @dfn{pretty print} it +first. This command (@code{gnus-score-pretty-print}) does that for +you. + +@end table + +Type @kbd{M-x gnus-score-mode} to use this mode. + +@vindex gnus-score-mode-hook +@code{gnus-score-menu-hook} is run in score mode buffers. + +In the summary buffer you can use commands like @kbd{V f} and @kbd{V +e} to begin editing score files. + + +@node Adaptive Scoring +@section Adaptive Scoring +@cindex adaptive scoring + +If all this scoring is getting you down, Gnus has a way of making it all +happen automatically---as if by magic. Or rather, as if by artificial +stupidity, to be precise. + +@vindex gnus-use-adaptive-scoring +When you read an article, or mark an article as read, or kill an +article, you leave marks behind. On exit from the group, Gnus can sniff +these marks and add score elements depending on what marks it finds. +You turn on this ability by setting @code{gnus-use-adaptive-scoring} to +@code{t} or @code{(line)}. If you want score adaptively on separate +words appearing in the subjects, you should set this variable to +@code{(word)}. If you want to use both adaptive methods, set this +variable to @code{(word line)}. + +@vindex gnus-default-adaptive-score-alist +To give you complete control over the scoring process, you can customize +the @code{gnus-default-adaptive-score-alist} variable. For instance, it +might look something like this: + +@lisp +(defvar gnus-default-adaptive-score-alist + '((gnus-unread-mark) + (gnus-ticked-mark (from 4)) + (gnus-dormant-mark (from 5)) + (gnus-del-mark (from -4) (subject -1)) + (gnus-read-mark (from 4) (subject 2)) + (gnus-expirable-mark (from -1) (subject -1)) + (gnus-killed-mark (from -1) (subject -3)) + (gnus-kill-file-mark) + (gnus-ancient-mark) + (gnus-low-score-mark) + (gnus-catchup-mark (from -1) (subject -1)))) +@end lisp + +As you see, each element in this alist has a mark as a key (either a +variable name or a ``real'' mark---a character). Following this key is +a arbitrary number of header/score pairs. If there are no header/score +pairs following the key, no adaptive scoring will be done on articles +that have that key as the article mark. For instance, articles with +@code{gnus-unread-mark} in the example above will not get adaptive score +entries. + +Each article can have only one mark, so just a single of these rules +will be applied to each article. + +To take @code{gnus-del-mark} as an example---this alist says that all +articles that have that mark (i.e., are marked with @samp{D}) will have a +score entry added to lower based on the @code{From} header by -4, and +lowered by @code{Subject} by -1. Change this to fit your prejudices. + +If you have marked 10 articles with the same subject with +@code{gnus-del-mark}, the rule for that mark will be applied ten times. +That means that that subject will get a score of ten times -1, which +should be, unless I'm much mistaken, -10. + +If you have auto-expirable (mail) groups (@pxref{Expiring Mail}), all +the read articles will be marked with the @samp{E} mark. This'll +probably make adaptive scoring slightly impossible, so auto-expiring and +adaptive scoring doesn't really mix very well. + +The headers you can score on are @code{from}, @code{subject}, +@code{message-id}, @code{references}, @code{xref}, @code{lines}, +@code{chars} and @code{date}. In addition, you can score on +@code{followup}, which will create an adaptive score entry that matches +on the @code{References} header using the @code{Message-ID} of the +current article, thereby matching the following thread. + +You can also score on @code{thread}, which will try to score all +articles that appear in a thread. @code{thread} matches uses a +@code{Message-ID} to match on the @code{References} header of the +article. If the match is made, the @code{Message-ID} of the article is +added to the @code{thread} rule. (Think about it. I'd recommend two +aspirins afterwards.) + +If you use this scheme, you should set the score file atom @code{mark} +to something small---like -300, perhaps, to avoid having small random +changes result in articles getting marked as read. + +After using adaptive scoring for a week or so, Gnus should start to +become properly trained and enhance the authors you like best, and kill +the authors you like least, without you having to say so explicitly. + +You can control what groups the adaptive scoring is to be performed on +by using the score files (@pxref{Score File Format}). This will also +let you use different rules in different groups. + +@vindex gnus-adaptive-file-suffix +The adaptive score entries will be put into a file where the name is the +group name with @code{gnus-adaptive-file-suffix} appended. The default +is @samp{ADAPT}. + +@vindex gnus-score-exact-adapt-limit +When doing adaptive scoring, substring or fuzzy matching would probably +give you the best results in most cases. However, if the header one +matches is short, the possibility for false positives is great, so if +the length of the match is less than +@code{gnus-score-exact-adapt-limit}, exact matching will be used. If +this variable is @code{nil}, exact matching will always be used to avoid +this problem. + +@vindex gnus-default-adaptive-word-score-alist +As mentioned above, you can adapt either on individual words or entire +headers. If you adapt on words, the +@code{gnus-default-adaptive-word-score-alist} variable says what score +each instance of a word should add given a mark. + +@lisp +(setq gnus-default-adaptive-word-score-alist + `((,gnus-read-mark . 30) + (,gnus-catchup-mark . -10) + (,gnus-killed-mark . -20) + (,gnus-del-mark . -15))) +@end lisp + +This is the default value. If you have adaption on words enabled, every +word that appears in subjects of articles marked with +@code{gnus-read-mark} will result in a score rule that increase the +score with 30 points. + +@vindex gnus-default-ignored-adaptive-words +@vindex gnus-ignored-adaptive-words +Words that appear in the @code{gnus-default-ignored-adaptive-words} list +will be ignored. If you wish to add more words to be ignored, use the +@code{gnus-ignored-adaptive-words} list instead. + +@vindex gnus-adaptive-word-syntax-table +When the scoring is done, @code{gnus-adaptive-word-syntax-table} is the +syntax table in effect. It is similar to the standard syntax table, but +it considers numbers to be non-word-constituent characters. + +@vindex gnus-adaptive-word-minimum +If @code{gnus-adaptive-word-minimum} is set to a number, the adaptive +word scoring process will never bring down the score of an article to +below this number. The default is @code{nil}. + +After using this scheme for a while, it might be nice to write a +@code{gnus-psychoanalyze-user} command to go through the rules and see +what words you like and what words you don't like. Or perhaps not. + +Note that the adaptive word scoring thing is highly experimental and is +likely to change in the future. Initial impressions seem to indicate +that it's totally useless as it stands. Some more work (involving more +rigorous statistical methods) will have to be done to make this useful. + + +@node Home Score File +@section Home Score File + +The score file where new score file entries will go is called the +@dfn{home score file}. This is normally (and by default) the score file +for the group itself. For instance, the home score file for +@samp{gnu.emacs.gnus} is @file{gnu.emacs.gnus.SCORE}. + +However, this may not be what you want. It is often convenient to share +a common home score file among many groups---all @samp{emacs} groups +could perhaps use the same home score file. + +@vindex gnus-home-score-file +The variable that controls this is @code{gnus-home-score-file}. It can +be: + +@enumerate +@item +A string. Then this file will be used as the home score file for all +groups. + +@item +A function. The result of this function will be used as the home score +file. The function will be called with the name of the group as the +parameter. + +@item +A list. The elements in this list can be: + +@enumerate +@item +@var{(regexp file-name)}. If the @var{regexp} matches the group name, +the @var{file-name} will will be used as the home score file. + +@item +A function. If the function returns non-nil, the result will be used as +the home score file. + +@item +A string. Use the string as the home score file. +@end enumerate + +The list will be traversed from the beginning towards the end looking +for matches. + +@end enumerate + +So, if you want to use just a single score file, you could say: + +@lisp +(setq gnus-home-score-file + "my-total-score-file.SCORE") +@end lisp + +If you want to use @file{gnu.SCORE} for all @samp{gnu} groups and +@file{rec.SCORE} for all @samp{rec} groups (and so on), you can say: + +@findex gnus-hierarchial-home-score-file +@lisp +(setq gnus-home-score-file + 'gnus-hierarchial-home-score-file) +@end lisp + +This is a ready-made function provided for your convenience. +Other functions include + +@table @code +@item gnus-current-home-score-file +@findex gnus-current-home-score-file +Return the ``current'' regular score file. This will make scoring +commands add entry to the ``innermost'' matching score file. + +@end table + +If you want to have one score file for the @samp{emacs} groups and +another for the @samp{comp} groups, while letting all other groups use +their own home score files: + +@lisp +(setq gnus-home-score-file + ;; All groups that match the regexp "\\.emacs" + '(("\\.emacs" "emacs.SCORE") + ;; All the comp groups in one score file + ("^comp" "comp.SCORE"))) +@end lisp + +@vindex gnus-home-adapt-file +@code{gnus-home-adapt-file} works exactly the same way as +@code{gnus-home-score-file}, but says what the home adaptive score file +is instead. All new adaptive file entries will go into the file +specified by this variable, and the same syntax is allowed. + +In addition to using @code{gnus-home-score-file} and +@code{gnus-home-adapt-file}, you can also use group parameters +(@pxref{Group Parameters}) and topic parameters (@pxref{Topic +Parameters}) to achieve much the same. Group and topic parameters take +precedence over this variable. + + +@node Followups To Yourself +@section Followups To Yourself + +Gnus offers two commands for picking out the @code{Message-ID} header in +the current buffer. Gnus will then add a score rule that scores using +this @code{Message-ID} on the @code{References} header of other +articles. This will, in effect, increase the score of all articles that +respond to the article in the current buffer. Quite useful if you want +to easily note when people answer what you've said. + +@table @code + +@item gnus-score-followup-article +@findex gnus-score-followup-article +This will add a score to articles that directly follow up your own +article. + +@item gnus-score-followup-thread +@findex gnus-score-followup-thread +This will add a score to all articles that appear in a thread ``below'' +your own article. +@end table + +@vindex message-sent-hook +These two functions are both primarily meant to be used in hooks like +@code{message-sent-hook}. + +If you look closely at your own @code{Message-ID}, you'll notice that +the first two or three characters are always the same. Here's two of +mine: + +@example +<x6u3u47icf.fsf@@eyesore.no> +<x6sp9o7ibw.fsf@@eyesore.no> +@end example + +So ``my'' ident on this machine is @samp{x6}. This can be +exploited---the following rule will raise the score on all followups to +myself: + +@lisp +("references" + ("<x6[0-9a-z]+\\.fsf\\(_-_\\)?@@.*eyesore.no>" + 1000 nil r)) +@end lisp + +Whether it's the first two or first three characters that are ``yours'' +is system-dependent. + + +@node Scoring Tips +@section Scoring Tips +@cindex scoring tips + +@table @dfn + +@item Crossposts +@cindex crossposts +@cindex scoring crossposts +If you want to lower the score of crossposts, the line to match on is +the @code{Xref} header. +@lisp +("xref" (" talk.politics.misc:" -1000)) +@end lisp + +@item Multiple crossposts +If you want to lower the score of articles that have been crossposted to +more than, say, 3 groups: +@lisp +("xref" ("[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+ +[^:\n]+:[0-9]+" -1000 nil r)) +@end lisp + +@item Matching on the body +This is generally not a very good idea---it takes a very long time. +Gnus actually has to fetch each individual article from the server. But +you might want to anyway, I guess. Even though there are three match +keys (@code{Head}, @code{Body} and @code{All}), you should choose one +and stick with it in each score file. If you use any two, each article +will be fetched @emph{twice}. If you want to match a bit on the +@code{Head} and a bit on the @code{Body}, just use @code{All} for all +the matches. + +@item Marking as read +You will probably want to mark articles that has a score below a certain +number as read. This is most easily achieved by putting the following +in your @file{all.SCORE} file: +@lisp +((mark -100)) +@end lisp +You may also consider doing something similar with @code{expunge}. + +@item Negated character classes +If you say stuff like @code{[^abcd]*}, you may get unexpected results. +That will match newlines, which might lead to, well, The Unknown. Say +@code{[^abcd\n]*} instead. +@end table + + +@node Reverse Scoring +@section Reverse Scoring +@cindex reverse scoring + +If you want to keep just articles that have @samp{Sex with Emacs} in the +subject header, and expunge all other articles, you could put something +like this in your score file: + +@lisp +(("subject" + ("Sex with Emacs" 2)) + (mark 1) + (expunge 1)) +@end lisp + +So, you raise all articles that match @samp{Sex with Emacs} and mark the +rest as read, and expunge them to boot. + + +@node Global Score Files +@section Global Score Files +@cindex global score files + +Sure, other newsreaders have ``global kill files''. These are usually +nothing more than a single kill file that applies to all groups, stored +in the user's home directory. Bah! Puny, weak newsreaders! + +What I'm talking about here are Global Score Files. Score files from +all over the world, from users everywhere, uniting all nations in one +big, happy score file union! Ange-score! New and untested! + +@vindex gnus-global-score-files +All you have to do to use other people's score files is to set the +@code{gnus-global-score-files} variable. One entry for each score file, +or each score file directory. Gnus will decide by itself what score +files are applicable to which group. + +Say you want to use the score file +@file{/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE} and +all score files in the @file{/ftp@@ftp.some-where:/pub/score} directory: + +@lisp +(setq gnus-global-score-files + '("/ftp@@ftp.gnus.org:/pub/larsi/ding/score/soc.motss.SCORE" + "/ftp@@ftp.some-where:/pub/score/")) +@end lisp + +@findex gnus-score-search-global-directories +Simple, eh? Directory names must end with a @samp{/}. These +directories are typically scanned only once during each Gnus session. +If you feel the need to manually re-scan the remote directories, you can +use the @code{gnus-score-search-global-directories} command. + +Note that, at present, using this option will slow down group entry +somewhat. (That is---a lot.) + +If you want to start maintaining score files for other people to use, +just put your score file up for anonymous ftp and announce it to the +world. Become a retro-moderator! Participate in the retro-moderator +wars sure to ensue, where retro-moderators battle it out for the +sympathy of the people, luring them to use their score files on false +premises! Yay! The net is saved! + +Here are some tips for the would-be retro-moderator, off the top of my +head: + +@itemize @bullet + +@item +Articles heavily crossposted are probably junk. +@item +To lower a single inappropriate article, lower by @code{Message-ID}. +@item +Particularly brilliant authors can be raised on a permanent basis. +@item +Authors that repeatedly post off-charter for the group can safely be +lowered out of existence. +@item +Set the @code{mark} and @code{expunge} atoms to obliterate the nastiest +articles completely. + +@item +Use expiring score entries to keep the size of the file down. You +should probably have a long expiry period, though, as some sites keep +old articles for a long time. +@end itemize + +... I wonder whether other newsreaders will support global score files +in the future. @emph{Snicker}. Yup, any day now, newsreaders like Blue +Wave, xrn and 1stReader are bound to implement scoring. Should we start +holding our breath yet? + + +@node Kill Files +@section Kill Files +@cindex kill files + +Gnus still supports those pesky old kill files. In fact, the kill file +entries can now be expiring, which is something I wrote before Daniel +Quinlan thought of doing score files, so I've left the code in there. + +In short, kill processing is a lot slower (and I do mean @emph{a lot}) +than score processing, so it might be a good idea to rewrite your kill +files into score files. + +Anyway, a kill file is a normal @code{emacs-lisp} file. You can put any +forms into this file, which means that you can use kill files as some +sort of primitive hook function to be run on group entry, even though +that isn't a very good idea. + +Normal kill files look like this: + +@lisp +(gnus-kill "From" "Lars Ingebrigtsen") +(gnus-kill "Subject" "ding") +(gnus-expunge "X") +@end lisp + +This will mark every article written by me as read, and remove the +marked articles from the summary buffer. Very useful, you'll agree. + +Other programs use a totally different kill file syntax. If Gnus +encounters what looks like a @code{rn} kill file, it will take a stab at +interpreting it. + +Two summary functions for editing a GNUS kill file: + +@table @kbd + +@item M-k +@kindex M-k (Summary) +@findex gnus-summary-edit-local-kill +Edit this group's kill file (@code{gnus-summary-edit-local-kill}). + +@item M-K +@kindex M-K (Summary) +@findex gnus-summary-edit-global-kill +Edit the general kill file (@code{gnus-summary-edit-global-kill}). +@end table + +Two group mode functions for editing the kill files: + +@table @kbd + +@item M-k +@kindex M-k (Group) +@findex gnus-group-edit-local-kill +Edit this group's kill file (@code{gnus-group-edit-local-kill}). + +@item M-K +@kindex M-K (Group) +@findex gnus-group-edit-global-kill +Edit the general kill file (@code{gnus-group-edit-global-kill}). +@end table + +Kill file variables: + +@table @code +@item gnus-kill-file-name +@vindex gnus-kill-file-name +A kill file for the group @samp{soc.motss} is normally called +@file{soc.motss.KILL}. The suffix appended to the group name to get +this file name is detailed by the @code{gnus-kill-file-name} variable. +The ``global'' kill file (not in the score file sense of ``global'', of +course) is just called @file{KILL}. + +@vindex gnus-kill-save-kill-file +@item gnus-kill-save-kill-file +If this variable is non-@code{nil}, Gnus will save the +kill file after processing, which is necessary if you use expiring +kills. + +@item gnus-apply-kill-hook +@vindex gnus-apply-kill-hook +@findex gnus-apply-kill-file-unless-scored +@findex gnus-apply-kill-file +A hook called to apply kill files to a group. It is +@code{(gnus-apply-kill-file)} by default. If you want to ignore the +kill file if you have a score file for the same group, you can set this +hook to @code{(gnus-apply-kill-file-unless-scored)}. If you don't want +kill files to be processed, you should set this variable to @code{nil}. + +@item gnus-kill-file-mode-hook +@vindex gnus-kill-file-mode-hook +A hook called in kill-file mode buffers. + +@end table + + +@node Converting Kill Files +@section Converting Kill Files +@cindex kill files +@cindex converting kill files + +If you have loads of old kill files, you may want to convert them into +score files. If they are ``regular'', you can use +the @file{gnus-kill-to-score.el} package; if not, you'll have to do it +by hand. + +The kill to score conversion package isn't included in Gnus by default. +You can fetch it from +@file{http://www.stud.ifi.uio.no/~larsi/ding-other/gnus-kill-to-score}. + +If your old kill files are very complex---if they contain more +non-@code{gnus-kill} forms than not, you'll have to convert them by +hand. Or just let them be as they are. Gnus will still use them as +before. + + +@node GroupLens +@section GroupLens +@cindex GroupLens + +GroupLens is a collaborative filtering system that helps you work +together with other people to find the quality news articles out of the +huge volume of news articles generated every day. + +To accomplish this the GroupLens system combines your opinions about +articles you have already read with the opinions of others who have done +likewise and gives you a personalized prediction for each unread news +article. Think of GroupLens as a matchmaker. GroupLens watches how you +rate articles, and finds other people that rate articles the same way. +Once it has found some people you agree with it tells you, in the form +of a prediction, what they thought of the article. You can use this +prediction to help you decide whether or not you want to read the +article. + +@menu +* Using GroupLens:: How to make Gnus use GroupLens. +* Rating Articles:: Letting GroupLens know how you rate articles. +* Displaying Predictions:: Displaying predictions given by GroupLens. +* GroupLens Variables:: Customizing GroupLens. +@end menu + + +@node Using GroupLens +@subsection Using GroupLens + +To use GroupLens you must register a pseudonym with your local Better +Bit Bureau (BBB). +@samp{http://www.cs.umn.edu/Research/GroupLens/bbb.html} is the only +better bit in town at the moment. + +Once you have registered you'll need to set a couple of variables. + +@table @code + +@item gnus-use-grouplens +@vindex gnus-use-grouplens +Setting this variable to a non-@code{nil} value will make Gnus hook into +all the relevant GroupLens functions. + +@item grouplens-pseudonym +@vindex grouplens-pseudonym +This variable should be set to the pseudonym you got when registering +with the Better Bit Bureau. + +@item grouplens-newsgroups +@vindex grouplens-newsgroups +A list of groups that you want to get GroupLens predictions for. + +@end table + +That's the minimum of what you need to get up and running with GroupLens. +Once you've registered, GroupLens will start giving you scores for +articles based on the average of what other people think. But, to get +the real benefit of GroupLens you need to start rating articles +yourself. Then the scores GroupLens gives you will be personalized for +you, based on how the people you usually agree with have already rated. + + +@node Rating Articles +@subsection Rating Articles + +In GroupLens, an article is rated on a scale from 1 to 5, inclusive. +Where 1 means something like this article is a waste of bandwidth and 5 +means that the article was really good. The basic question to ask +yourself is, "on a scale from 1 to 5 would I like to see more articles +like this one?" + +There are four ways to enter a rating for an article in GroupLens. + +@table @kbd + +@item r +@kindex r (GroupLens) +@findex bbb-summary-rate-article +This function will prompt you for a rating on a scale of one to five. + +@item k +@kindex k (GroupLens) +@findex grouplens-score-thread +This function will prompt you for a rating, and rate all the articles in +the thread. This is really useful for some of those long running giant +threads in rec.humor. + +@end table + +The next two commands, @kbd{n} and @kbd{,} take a numerical prefix to be +the score of the article you're reading. + +@table @kbd + +@item 1-5 n +@kindex n (GroupLens) +@findex grouplens-next-unread-article +Rate the article and go to the next unread article. + +@item 1-5 , +@kindex , (GroupLens) +@findex grouplens-best-unread-article +Rate the article and go to the next unread article with the highest score. + +@end table + +If you want to give the current article a score of 4 and then go to the +next article, just type @kbd{4 n}. + + +@node Displaying Predictions +@subsection Displaying Predictions + +GroupLens makes a prediction for you about how much you will like a +news article. The predictions from GroupLens are on a scale from 1 to +5, where 1 is the worst and 5 is the best. You can use the predictions +from GroupLens in one of three ways controlled by the variable +@code{gnus-grouplens-override-scoring}. + +@vindex gnus-grouplens-override-scoring +There are three ways to display predictions in grouplens. You may +choose to have the GroupLens scores contribute to, or override the +regular gnus scoring mechanism. override is the default; however, some +people prefer to see the Gnus scores plus the grouplens scores. To get +the separate scoring behavior you need to set +@code{gnus-grouplens-override-scoring} to @code{'separate}. To have the +GroupLens predictions combined with the grouplens scores set it to +@code{'override} and to combine the scores set +@code{gnus-grouplens-override-scoring} to @code{'combine}. When you use +the combine option you will also want to set the values for +@code{grouplens-prediction-offset} and +@code{grouplens-score-scale-factor}. + +@vindex grouplens-prediction-display +In either case, GroupLens gives you a few choices for how you would like +to see your predictions displayed. The display of predictions is +controlled by the @code{grouplens-prediction-display} variable. + +The following are valid values for that variable. + +@table @code +@item prediction-spot +The higher the prediction, the further to the right an @samp{*} is +displayed. + +@item confidence-interval +A numeric confidence interval. + +@item prediction-bar +The higher the prediction, the longer the bar. + +@item confidence-bar +Numerical confidence. + +@item confidence-spot +The spot gets bigger with more confidence. + +@item prediction-num +Plain-old numeric value. + +@item confidence-plus-minus +Prediction +/- confidence. + +@end table + + +@node GroupLens Variables +@subsection GroupLens Variables + +@table @code + +@item gnus-summary-grouplens-line-format +The summary line format used in GroupLens-enhanced summary buffers. It +accepts the same specs as the normal summary line format (@pxref{Summary +Buffer Lines}). The default is @samp{%U%R%z%l%I%(%[%4L: %-20,20n%]%) +%s\n}. + +@item grouplens-bbb-host +Host running the bbbd server. @samp{grouplens.cs.umn.edu} is the +default. + +@item grouplens-bbb-port +Port of the host running the bbbd server. The default is 9000. + +@item grouplens-score-offset +Offset the prediction by this value. In other words, subtract the +prediction value by this number to arrive at the effective score. The +default is 0. + +@item grouplens-score-scale-factor +This variable allows the user to magnify the effect of GroupLens scores. +The scale factor is applied after the offset. The default is 1. + +@end table + + +@node Advanced Scoring +@section Advanced Scoring + +Scoring on Subjects and From headers is nice enough, but what if you're +really interested in what a person has to say only when she's talking +about a particular subject? Or what if you really don't want to +read what person A has to say when she's following up to person B, but +want to read what she says when she's following up to person C? + +By using advanced scoring rules you may create arbitrarily complex +scoring patterns. + +@menu +* Advanced Scoring Syntax:: A definition. +* Advanced Scoring Examples:: What they look like. +* Advanced Scoring Tips:: Getting the most out of it. +@end menu + + +@node Advanced Scoring Syntax +@subsection Advanced Scoring Syntax + +Ordinary scoring rules have a string as the first element in the rule. +Advanced scoring rules have a list as the first element. The second +element is the score to be applied if the first element evaluated to a +non-@code{nil} value. + +These lists may consist of three logical operators, one redirection +operator, and various match operators. + +Logical operators: + +@table @code +@item & +@itemx and +This logical operator will evaluate each of its arguments until it finds +one that evaluates to @code{false}, and then it'll stop. If all arguments +evaluate to @code{true} values, then this operator will return +@code{true}. + +@item | +@itemx or +This logical operator will evaluate each of its arguments until it finds +one that evaluates to @code{true}. If no arguments are @code{true}, +then this operator will return @code{false}. + +@item ! +@itemx not +@itemx ¬ +This logical operator only takes a single argument. It returns the +logical negation of the value of its argument. + +@end table + +There is an @dfn{indirection operator} that will make its arguments +apply to the ancestors of the current article being scored. For +instance, @code{1-} will make score rules apply to the parent of the +current article. @code{2-} will make score rules apply to the +grandparent of the current article. Alternatively, you can write +@code{^^}, where the number of @code{^}s (carets) says how far back into +the ancestry you want to go. + +Finally, we have the match operators. These are the ones that do the +real work. Match operators are header name strings followed by a match +and a match type. A typical match operator looks like @samp{("from" +"Lars Ingebrigtsen" s)}. The header names are the same as when using +simple scoring, and the match types are also the same. + + +@node Advanced Scoring Examples +@subsection Advanced Scoring Examples + +Let's say you want to increase the score of articles written by Lars +when he's talking about Gnus: + +@example +((& + ("from" "Lars Ingebrigtsen") + ("subject" "Gnus")) + 1000) +@end example + +Quite simple, huh? + +When he writes long articles, he sometimes has something nice to say: + +@example +((& + ("from" "Lars Ingebrigtsen") + (| + ("subject" "Gnus") + ("lines" 100 >))) + 1000) +@end example + +However, when he responds to things written by Reig Eigil Logge, you +really don't want to read what he's written: + +@example +((& + ("from" "Lars Ingebrigtsen") + (1- ("from" "Reig Eigir Logge"))) + -100000) +@end example + +Everybody that follows up Redmondo when he writes about disappearing +socks should have their scores raised, but only when they talk about +white socks. However, when Lars talks about socks, it's usually not +very interesting: + +@example +((& + (1- + (& + ("from" "redmondo@@.*no" r) + ("body" "disappearing.*socks" t))) + (! ("from" "Lars Ingebrigtsen")) + ("body" "white.*socks")) + 1000) +@end example + +The possibilities are endless. + + +@node Advanced Scoring Tips +@subsection Advanced Scoring Tips + +The @code{&} and @code{|} logical operators do short-circuit logic. +That is, they stop processing their arguments when it's clear what the +result of the operation will be. For instance, if one of the arguments +of an @code{&} evaluates to @code{false}, there's no point in evaluating +the rest of the arguments. This means that you should put slow matches +(@samp{body}, @samp{header}) last and quick matches (@samp{from}, +@samp{subject}) first. + +The indirection arguments (@code{1-} and so on) will make their +arguments work on previous generations of the thread. If you say +something like: + +@example +... +(1- + (1- + ("from" "lars"))) +... +@end example + +Then that means "score on the from header of the grandparent of the +current article". An indirection is quite fast, but it's better to say: + +@example +(1- + (& + ("from" "Lars") + ("subject" "Gnus"))) +@end example + +than it is to say: + +@example +(& + (1- ("from" "Lars")) + (1- ("subject" "Gnus"))) +@end example + + +@node Score Decays +@section Score Decays +@cindex score decays +@cindex decays + +You may find that your scores have a tendency to grow without +bounds, especially if you're using adaptive scoring. If scores get too +big, they lose all meaning---they simply max out and it's difficult to +use them in any sensible way. + +@vindex gnus-decay-scores +@findex gnus-decay-score +@vindex gnus-decay-score-function +Gnus provides a mechanism for decaying scores to help with this problem. +When score files are loaded and @code{gnus-decay-scores} is +non-@code{nil}, Gnus will run the score files through the decaying +mechanism thereby lowering the scores of all non-permanent score rules. +The decay itself if performed by the @code{gnus-decay-score-function} +function, which is @code{gnus-decay-score} by default. Here's the +definition of that function: + +@lisp +(defun gnus-decay-score (score) + "Decay SCORE. +This is done according to `gnus-score-decay-constant' +and `gnus-score-decay-scale'." + (floor + (- score + (* (if (< score 0) 1 -1) + (min (abs score) + (max gnus-score-decay-constant + (* (abs score) + gnus-score-decay-scale))))))) +@end lisp + +@vindex gnus-score-decay-scale +@vindex gnus-score-decay-constant +@code{gnus-score-decay-constant} is 3 by default and +@code{gnus-score-decay-scale} is 0.05. This should cause the following: + +@enumerate +@item +Scores between -3 and 3 will be set to 0 when this function is called. + +@item +Scores with magnitudes between 3 and 60 will be shrunk by 3. + +@item +Scores with magnitudes greater than 60 will be shrunk by 5% of the +score. +@end enumerate + +If you don't like this decay function, write your own. It is called +with the score to be decayed as its only parameter, and it should return +the new score, which should be an integer. + +Gnus will try to decay scores once a day. If you haven't run Gnus for +four days, Gnus will decay the scores four times, for instance. + + +@node Various +@chapter Various + +@menu +* Process/Prefix:: A convention used by many treatment commands. +* Interactive:: Making Gnus ask you many questions. +* Symbolic Prefixes:: How to supply some Gnus functions with options. +* Formatting Variables:: You can specify what buffers should look like. +* Windows Configuration:: Configuring the Gnus buffer windows. +* Faces and Fonts:: How to change how faces look. +* Compilation:: How to speed Gnus up. +* Mode Lines:: Displaying information in the mode lines. +* Highlighting and Menus:: Making buffers look all nice and cozy. +* Buttons:: Get tendonitis in ten easy steps! +* Daemons:: Gnus can do things behind your back. +* NoCeM:: How to avoid spam and other fatty foods. +* Undo:: Some actions can be undone. +* Moderation:: What to do if you're a moderator. +* XEmacs Enhancements:: There are more pictures and stuff under XEmacs. +* Fuzzy Matching:: What's the big fuzz? +* Thwarting Email Spam:: A how-to on avoiding unsolicited commercial email. +* Various Various:: Things that are really various. +@end menu + + +@node Process/Prefix +@section Process/Prefix +@cindex process/prefix convention + +Many functions, among them functions for moving, decoding and saving +articles, use what is known as the @dfn{Process/Prefix convention}. + +This is a method for figuring out what articles the user wants the +command to be performed on. + +It goes like this: + +If the numeric prefix is N, perform the operation on the next N +articles, starting with the current one. If the numeric prefix is +negative, perform the operation on the previous N articles, starting +with the current one. + +@vindex transient-mark-mode +If @code{transient-mark-mode} in non-@code{nil} and the region is +active, all articles in the region will be worked upon. + +If there is no numeric prefix, but some articles are marked with the +process mark, perform the operation on the articles marked with +the process mark. + +If there is neither a numeric prefix nor any articles marked with the +process mark, just perform the operation on the current article. + +Quite simple, really, but it needs to be made clear so that surprises +are avoided. + +Commands that react to the process mark will push the current list of +process marked articles onto a stack and will then clear all process +marked articles. You can restore the previous configuration with the +@kbd{M P y} command (@pxref{Setting Process Marks}). + +@vindex gnus-summary-goto-unread +One thing that seems to shock & horrify lots of people is that, for +instance, @kbd{3 d} does exactly the same as @kbd{d} @kbd{d} @kbd{d}. +Since each @kbd{d} (which marks the current article as read) by default +goes to the next unread article after marking, this means that @kbd{3 d} +will mark the next three unread articles as read, no matter what the +summary buffer looks like. Set @code{gnus-summary-goto-unread} to +@code{nil} for a more straightforward action. + + +@node Interactive +@section Interactive +@cindex interaction + +@table @code + +@item gnus-novice-user +@vindex gnus-novice-user +If this variable is non-@code{nil}, you are either a newcomer to the +World of Usenet, or you are very cautious, which is a nice thing to be, +really. You will be given questions of the type ``Are you sure you want +to do this?'' before doing anything dangerous. This is @code{t} by +default. + +@item gnus-expert-user +@vindex gnus-expert-user +If this variable is non-@code{nil}, you will seldom be asked any +questions by Gnus. It will simply assume you know what you're doing, no +matter how strange. + +@item gnus-interactive-catchup +@vindex gnus-interactive-catchup +Require confirmation before catching up a group if non-@code{nil}. It +is @code{t} by default. + +@item gnus-interactive-exit +@vindex gnus-interactive-exit +Require confirmation before exiting Gnus. This variable is @code{t} by +default. +@end table + + +@node Symbolic Prefixes +@section Symbolic Prefixes +@cindex symbolic prefixes + +Quite a lot of Emacs commands react to the (numeric) prefix. For +instance, @kbd{C-u 4 C-f} moves point four characters forward, and +@kbd{C-u 9 0 0 I s s p} adds a permanent @code{Subject} substring score +rule of 900 to the current article. + +This is all nice and well, but what if you want to give a command some +additional information? Well, what most commands do is interpret the +``raw'' prefix in some special way. @kbd{C-u 0 C-x C-s} means that one +doesn't want a backup file to be created when saving the current buffer, +for instance. But what if you want to save without making a backup +file, and you want Emacs to flash lights and play a nice tune at the +same time? You can't, and you're probably perfectly happy that way. + +@kindex M-i (Summary) +@findex gnus-symbolic-argument +I'm not, so I've added a second prefix---the @dfn{symbolic prefix}. The +prefix key is @kbd{M-i} (@code{gnus-symbolic-argument}), and the next +character typed in is the value. You can stack as many @kbd{M-i} +prefixes as you want. @kbd{M-i a M-C-u} means ``feed the @kbd{M-C-u} +command the symbolic prefix @code{a}''. @kbd{M-i a M-i b M-C-u} means +``feed the @kbd{M-C-u} command the symbolic prefixes @code{a} and +@code{b}''. You get the drift. + +Typing in symbolic prefixes to commands that don't accept them doesn't +hurt, but it doesn't do any good either. Currently not many Gnus +functions make use of the symbolic prefix. + +If you're interested in how Gnus implements this, @pxref{Extended +Interactive}. + + +@node Formatting Variables +@section Formatting Variables +@cindex formatting variables + +Throughout this manual you've probably noticed lots of variables called +things like @code{gnus-group-line-format} and +@code{gnus-summary-mode-line-format}. These control how Gnus is to +output lines in the various buffers. There's quite a lot of them. +Fortunately, they all use the same syntax, so there's not that much to +be annoyed by. + +Here's an example format spec (from the group buffer): @samp{%M%S%5y: +%(%g%)\n}. We see that it is indeed extremely ugly, and that there are +lots of percentages everywhere. + +@menu +* Formatting Basics:: A formatting variable is basically a format string. +* Mode Line Formatting:: Some rules about mode line formatting variables. +* Advanced Formatting:: Modifying output in various ways. +* User-Defined Specs:: Having Gnus call your own functions. +* Formatting Fonts:: Making the formatting look colorful and nice. +@end menu + +Currently Gnus uses the following formatting variables: +@code{gnus-group-line-format}, @code{gnus-summary-line-format}, +@code{gnus-server-line-format}, @code{gnus-topic-line-format}, +@code{gnus-group-mode-line-format}, +@code{gnus-summary-mode-line-format}, +@code{gnus-article-mode-line-format}, +@code{gnus-server-mode-line-format}, and +@code{gnus-summary-pick-line-format}. + +All these format variables can also be arbitrary elisp forms. In that +case, they will be @code{eval}ed to insert the required lines. + +@kindex M-x gnus-update-format +@findex gnus-update-format +Gnus includes a command to help you while creating your own format +specs. @kbd{M-x gnus-update-format} will @code{eval} the current form, +update the spec in question and pop you to a buffer where you can +examine the resulting lisp code to be run to generate the line. + + + +@node Formatting Basics +@subsection Formatting Basics + +Each @samp{%} element will be replaced by some string or other when the +buffer in question is generated. @samp{%5y} means ``insert the @samp{y} +spec, and pad with spaces to get a 5-character field''. + +As with normal C and Emacs Lisp formatting strings, the numerical +modifier between the @samp{%} and the formatting type character will +@dfn{pad} the output so that it is always at least that long. +@samp{%5y} will make the field always (at least) five characters wide by +padding with spaces to the left. If you say @samp{%-5y}, it will pad to +the right instead. + +You may also wish to limit the length of the field to protect against +particularly wide values. For that you can say @samp{%4,6y}, which +means that the field will never be more than 6 characters wide and never +less than 4 characters wide. + + +@node Mode Line Formatting +@subsection Mode Line Formatting + +Mode line formatting variables (e.g., +@code{gnus-summary-mode-line-format}) follow the same rules as other, +buffer line oriented formatting variables (@pxref{Formatting Basics}) +with the following two differences: + +@enumerate + +@item +There must be no newline (@samp{\n}) at the end. + +@item +The special @samp{%%b} spec can be used to display the buffer name. +Well, it's no spec at all, really---@samp{%%} is just a way to quote +@samp{%} to allow it to pass through the formatting machinery unmangled, +so that Emacs receives @samp{%b}, which is something the Emacs mode line +display interprets to mean ``show the buffer name''. For a full list of +mode line specs Emacs understands, see the documentation of the +@code{mode-line-format} variable. + +@end enumerate + + +@node Advanced Formatting +@subsection Advanced Formatting + +It is frequently useful to post-process the fields in some way. +Padding, limiting, cutting off parts and suppressing certain values can +be achieved by using @dfn{tilde modifiers}. A typical tilde spec might +look like @samp{%~(cut 3)~(ignore "0")y}. + +These are the valid modifiers: + +@table @code +@item pad +@itemx pad-left +Pad the field to the left with spaces until it reaches the required +length. + +@item pad-right +Pad the field to the right with spaces until it reaches the required +length. + +@item max +@itemx max-left +Cut off characters from the left until it reaches the specified length. + +@item max-right +Cut off characters from the right until it reaches the specified +length. + +@item cut +@itemx cut-left +Cut off the specified number of characters from the left. + +@item cut-right +Cut off the specified number of characters from the right. + +@item ignore +Return an empty string if the field is equal to the specified value. + +@item form +Use the specified form as the field value when the @samp{@@} spec is +used. +@end table + +Let's take an example. The @samp{%o} spec in the summary mode lines +will return a date in compact ISO8601 format---@samp{19960809T230410}. +This is quite a mouthful, so we want to shave off the century number and +the time, leaving us with a six-character date. That would be +@samp{%~(cut-left 2)~(max-right 6)~(pad 6)o}. (Cutting is done before +maxing, and we need the padding to ensure that the date is never less +than 6 characters to make it look nice in columns.) + +Ignoring is done first; then cutting; then maxing; and then as the very +last operation, padding. + +If you use lots of these advanced thingies, you'll find that Gnus gets +quite slow. This can be helped enormously by running @kbd{M-x +gnus-compile} when you are satisfied with the look of your lines. +@xref{Compilation}. + + +@node User-Defined Specs +@subsection User-Defined Specs + +All the specs allow for inserting user defined specifiers---@samp{u}. +The next character in the format string should be a letter. Gnus +will call the function @code{gnus-user-format-function-}@samp{X}, where +@samp{X} is the letter following @samp{%u}. The function will be passed +a single parameter---what the parameter means depends on what buffer +it's being called from. The function should return a string, which will +be inserted into the buffer just like information from any other +specifier. This function may also be called with dummy values, so it +should protect against that. + +You can also use tilde modifiers (@pxref{Advanced Formatting} to achieve +much the same without defining new functions. Here's an example: +@samp{%~(form (count-lines (point-min) (point)))@@}. The form +given here will be evaluated to yield the current line number, and then +inserted. + + +@node Formatting Fonts +@subsection Formatting Fonts + +There are specs for highlighting, and these are shared by all the format +variables. Text inside the @samp{%(} and @samp{%)} specifiers will get +the special @code{mouse-face} property set, which means that it will be +highlighted (with @code{gnus-mouse-face}) when you put the mouse pointer +over it. + +Text inside the @samp{%@{} and @samp{%@}} specifiers will have their +normal faces set using @code{gnus-face-0}, which is @code{bold} by +default. If you say @samp{%1@{}, you'll get @code{gnus-face-1} instead, +and so on. Create as many faces as you wish. The same goes for the +@code{mouse-face} specs---you can say @samp{%3(hello%)} to have +@samp{hello} mouse-highlighted with @code{gnus-mouse-face-3}. + +Here's an alternative recipe for the group buffer: + +@lisp +;; Create three face types. +(setq gnus-face-1 'bold) +(setq gnus-face-3 'italic) + +;; We want the article count to be in +;; a bold and green face. So we create +;; a new face called `my-green-bold'. +(copy-face 'bold 'my-green-bold) +;; Set the color. +(set-face-foreground 'my-green-bold "ForestGreen") +(setq gnus-face-2 'my-green-bold) + +;; Set the new & fancy format. +(setq gnus-group-line-format + "%M%S%3@{%5y%@}%2[:%] %(%1@{%g%@}%)\n") +@end lisp + +I'm sure you'll be able to use this scheme to create totally unreadable +and extremely vulgar displays. Have fun! + +Note that the @samp{%(} specs (and friends) do not make any sense on the +mode-line variables. + + +@node Windows Configuration +@section Windows Configuration +@cindex windows configuration + +No, there's nothing here about X, so be quiet. + +@vindex gnus-use-full-window +If @code{gnus-use-full-window} non-@code{nil}, Gnus will delete all +other windows and occupy the entire Emacs screen by itself. It is +@code{t} by default. + +@vindex gnus-buffer-configuration +@code{gnus-buffer-configuration} describes how much space each Gnus +buffer should be given. Here's an excerpt of this variable: + +@lisp +((group (vertical 1.0 (group 1.0 point) + (if gnus-carpal (group-carpal 4)))) + (article (vertical 1.0 (summary 0.25 point) + (article 1.0)))) +@end lisp + +This is an alist. The @dfn{key} is a symbol that names some action or +other. For instance, when displaying the group buffer, the window +configuration function will use @code{group} as the key. A full list of +possible names is listed below. + +The @dfn{value} (i.e., the @dfn{split}) says how much space each buffer +should occupy. To take the @code{article} split as an example - + +@lisp +(article (vertical 1.0 (summary 0.25 point) + (article 1.0))) +@end lisp + +This @dfn{split} says that the summary buffer should occupy 25% of upper +half of the screen, and that it is placed over the article buffer. As +you may have noticed, 100% + 25% is actually 125% (yup, I saw y'all +reaching for that calculator there). However, the special number +@code{1.0} is used to signal that this buffer should soak up all the +rest of the space available after the rest of the buffers have taken +whatever they need. There should be only one buffer with the @code{1.0} +size spec per split. + +Point will be put in the buffer that has the optional third element +@code{point}. In a @code{frame} split, the last subsplit having a leaf +split where the tag @code{frame-focus} is a member (i.e. is the third or +fourth element in the list, depending on whether the @code{point} tag is +present) gets focus. + +Here's a more complicated example: + +@lisp +(article (vertical 1.0 (group 4) + (summary 0.25 point) + (if gnus-carpal (summary-carpal 4)) + (article 1.0))) +@end lisp + +If the size spec is an integer instead of a floating point number, +then that number will be used to say how many lines a buffer should +occupy, not a percentage. + +If the @dfn{split} looks like something that can be @code{eval}ed (to be +precise---if the @code{car} of the split is a function or a subr), this +split will be @code{eval}ed. If the result is non-@code{nil}, it will +be used as a split. This means that there will be three buffers if +@code{gnus-carpal} is @code{nil}, and four buffers if @code{gnus-carpal} +is non-@code{nil}. + +Not complicated enough for you? Well, try this on for size: + +@lisp +(article (horizontal 1.0 + (vertical 0.5 + (group 1.0) + (gnus-carpal 4)) + (vertical 1.0 + (summary 0.25 point) + (summary-carpal 4) + (article 1.0)))) +@end lisp + +Whoops. Two buffers with the mystery 100% tag. And what's that +@code{horizontal} thingie? + +If the first element in one of the split is @code{horizontal}, Gnus will +split the window horizontally, giving you two windows side-by-side. +Inside each of these strips you may carry on all you like in the normal +fashion. The number following @code{horizontal} says what percentage of +the screen is to be given to this strip. + +For each split, there @emph{must} be one element that has the 100% tag. +The splitting is never accurate, and this buffer will eat any leftover +lines from the splits. + +To be slightly more formal, here's a definition of what a valid split +may look like: + +@example +split = frame | horizontal | vertical | buffer | form +frame = "(frame " size *split ")" +horizontal = "(horizontal " size *split ")" +vertical = "(vertical " size *split ")" +buffer = "(" buffer-name " " size *[ "point" ] *[ "frame-focus"] ")" +size = number | frame-params +buffer-name = group | article | summary ... +@end example + +The limitations are that the @code{frame} split can only appear as the +top-level split. @var{form} should be an Emacs Lisp form that should +return a valid split. We see that each split is fully recursive, and +may contain any number of @code{vertical} and @code{horizontal} splits. + +@vindex gnus-window-min-width +@vindex gnus-window-min-height +@cindex window height +@cindex window width +Finding the right sizes can be a bit complicated. No window may be less +than @code{gnus-window-min-height} (default 1) characters high, and all +windows must be at least @code{gnus-window-min-width} (default 1) +characters wide. Gnus will try to enforce this before applying the +splits. If you want to use the normal Emacs window width/height limit, +you can just set these two variables to @code{nil}. + +If you're not familiar with Emacs terminology, @code{horizontal} and +@code{vertical} splits may work the opposite way of what you'd expect. +Windows inside a @code{horizontal} split are shown side-by-side, and +windows within a @code{vertical} split are shown above each other. + +@findex gnus-configure-frame +If you want to experiment with window placement, a good tip is to call +@code{gnus-configure-frame} directly with a split. This is the function +that does all the real work when splitting buffers. Below is a pretty +nonsensical configuration with 5 windows; two for the group buffer and +three for the article buffer. (I said it was nonsensical.) If you +@code{eval} the statement below, you can get an idea of how that would +look straight away, without going through the normal Gnus channels. +Play with it until you're satisfied, and then use +@code{gnus-add-configuration} to add your new creation to the buffer +configuration list. + +@lisp +(gnus-configure-frame + '(horizontal 1.0 + (vertical 10 + (group 1.0) + (article 0.3 point)) + (vertical 1.0 + (article 1.0) + (horizontal 4 + (group 1.0) + (article 10))))) +@end lisp + +You might want to have several frames as well. No prob---just use the +@code{frame} split: + +@lisp +(gnus-configure-frame + '(frame 1.0 + (vertical 1.0 + (summary 0.25 point frame-focus) + (article 1.0)) + (vertical ((height . 5) (width . 15) + (user-position . t) + (left . -1) (top . 1)) + (picon 1.0)))) + +@end lisp + +This split will result in the familiar summary/article window +configuration in the first (or ``main'') frame, while a small additional +frame will be created where picons will be shown. As you can see, +instead of the normal @code{1.0} top-level spec, each additional split +should have a frame parameter alist as the size spec. +@xref{Frame Parameters, , Frame Parameters, elisp, The GNU Emacs Lisp +Reference Manual}. Under XEmacs, a frame property list will be +accepted, too---for instance, @code{(height 5 width 15 left -1 top 1)} +is such a plist. + +Here's a list of all possible keys for +@code{gnus-buffer-configuration}: + +@code{group}, @code{summary}, @code{article}, @code{server}, +@code{browse}, @code{message}, @code{pick}, @code{info}, +@code{summary-faq}, @code{edit-group}, @code{edit-server}, +@code{edit-score}, @code{post}, @code{reply}, @code{forward}, +@code{reply-yank}, @code{mail-bounce}, @code{draft}, @code{pipe}, +@code{bug}, @code{compose-bounce}, and @code{score-trace}. + +Note that the @code{message} key is used for both +@code{gnus-group-mail} and @code{gnus-summary-mail-other-window}. If +it is desirable to distinguish between the two, something like this +might be used: + +@lisp +(message (horizontal 1.0 + (vertical 1.0 (message 1.0 point)) + (vertical 0.24 + (if (buffer-live-p gnus-summary-buffer) + '(summary 0.5)) + (group 1.0))))) +@end lisp + +@findex gnus-add-configuration +Since the @code{gnus-buffer-configuration} variable is so long and +complicated, there's a function you can use to ease changing the config +of a single setting: @code{gnus-add-configuration}. If, for instance, +you want to change the @code{article} setting, you could say: + +@lisp +(gnus-add-configuration + '(article (vertical 1.0 + (group 4) + (summary .25 point) + (article 1.0)))) +@end lisp + +You'd typically stick these @code{gnus-add-configuration} calls in your +@file{.gnus.el} file or in some startup hook---they should be run after +Gnus has been loaded. + +@vindex gnus-always-force-window-configuration +If all windows mentioned in the configuration are already visible, Gnus +won't change the window configuration. If you always want to force the +``right'' window configuration, you can set +@code{gnus-always-force-window-configuration} to non-@code{nil}. + + +@node Faces and Fonts +@section Faces and Fonts +@cindex faces +@cindex fonts +@cindex colors + +Fiddling with fonts and faces used to be very difficult, but these days +it is very simple. You simply say @kbd{M-x customize-face}, pick out +the face you want to alter, and alter it via the standard Customize +interface. + + +@node Compilation +@section Compilation +@cindex compilation +@cindex byte-compilation + +@findex gnus-compile + +Remember all those line format specification variables? +@code{gnus-summary-line-format}, @code{gnus-group-line-format}, and so +on. Now, Gnus will of course heed whatever these variables are, but, +unfortunately, changing them will mean a quite significant slow-down. +(The default values of these variables have byte-compiled functions +associated with them, while the user-generated versions do not, of +course.) + +To help with this, you can run @kbd{M-x gnus-compile} after you've +fiddled around with the variables and feel that you're (kind of) +satisfied. This will result in the new specs being byte-compiled, and +you'll get top speed again. Gnus will save these compiled specs in the +@file{.newsrc.eld} file. (User-defined functions aren't compiled by +this function, though---you should compile them yourself by sticking +them into the @code{.gnus.el} file and byte-compiling that file.) + + +@node Mode Lines +@section Mode Lines +@cindex mode lines + +@vindex gnus-updated-mode-lines +@code{gnus-updated-mode-lines} says what buffers should keep their mode +lines updated. It is a list of symbols. Supported symbols include +@code{group}, @code{article}, @code{summary}, @code{server}, +@code{browse}, and @code{tree}. If the corresponding symbol is present, +Gnus will keep that mode line updated with information that may be +pertinent. If this variable is @code{nil}, screen refresh may be +quicker. + +@cindex display-time + +@vindex gnus-mode-non-string-length +By default, Gnus displays information on the current article in the mode +lines of the summary and article buffers. The information Gnus wishes +to display (e.g. the subject of the article) is often longer than the +mode lines, and therefore have to be cut off at some point. The +@code{gnus-mode-non-string-length} variable says how long the other +elements on the line is (i.e., the non-info part). If you put +additional elements on the mode line (e.g. a clock), you should modify +this variable: + +@c Hook written by Francesco Potorti` <pot@cnuce.cnr.it> +@lisp +(add-hook 'display-time-hook + (lambda () (setq gnus-mode-non-string-length + (+ 21 + (if line-number-mode 5 0) + (if column-number-mode 4 0) + (length display-time-string))))) +@end lisp + +If this variable is @code{nil} (which is the default), the mode line +strings won't be chopped off, and they won't be padded either. Note +that the default is unlikely to be desirable, as even the percentage +complete in the buffer may be crowded off the mode line; the user should +configure this variable appropriately for her configuration. + + +@node Highlighting and Menus +@section Highlighting and Menus +@cindex visual +@cindex highlighting +@cindex menus + +@vindex gnus-visual +The @code{gnus-visual} variable controls most of the Gnus-prettifying +aspects. If @code{nil}, Gnus won't attempt to create menus or use fancy +colors or fonts. This will also inhibit loading the @file{gnus-vis.el} +file. + +This variable can be a list of visual properties that are enabled. The +following elements are valid, and are all included by default: + +@table @code +@item group-highlight +Do highlights in the group buffer. +@item summary-highlight +Do highlights in the summary buffer. +@item article-highlight +Do highlights in the article buffer. +@item highlight +Turn on highlighting in all buffers. +@item group-menu +Create menus in the group buffer. +@item summary-menu +Create menus in the summary buffers. +@item article-menu +Create menus in the article buffer. +@item browse-menu +Create menus in the browse buffer. +@item server-menu +Create menus in the server buffer. +@item score-menu +Create menus in the score buffers. +@item menu +Create menus in all buffers. +@end table + +So if you only want highlighting in the article buffer and menus in all +buffers, you could say something like: + +@lisp +(setq gnus-visual '(article-highlight menu)) +@end lisp + +If you want highlighting only and no menus whatsoever, you'd say: + +@lisp +(setq gnus-visual '(highlight)) +@end lisp + +If @code{gnus-visual} is @code{t}, highlighting and menus will be used +in all Gnus buffers. + +Other general variables that influence the look of all buffers include: + +@table @code +@item gnus-mouse-face +@vindex gnus-mouse-face +This is the face (i.e., font) used for mouse highlighting in Gnus. No +mouse highlights will be done if @code{gnus-visual} is @code{nil}. + +@end table + +There are hooks associated with the creation of all the different menus: + +@table @code + +@item gnus-article-menu-hook +@vindex gnus-article-menu-hook +Hook called after creating the article mode menu. + +@item gnus-group-menu-hook +@vindex gnus-group-menu-hook +Hook called after creating the group mode menu. + +@item gnus-summary-menu-hook +@vindex gnus-summary-menu-hook +Hook called after creating the summary mode menu. + +@item gnus-server-menu-hook +@vindex gnus-server-menu-hook +Hook called after creating the server mode menu. + +@item gnus-browse-menu-hook +@vindex gnus-browse-menu-hook +Hook called after creating the browse mode menu. + +@item gnus-score-menu-hook +@vindex gnus-score-menu-hook +Hook called after creating the score mode menu. + +@end table + + +@node Buttons +@section Buttons +@cindex buttons +@cindex mouse +@cindex click + +Those new-fangled @dfn{mouse} contraptions is very popular with the +young, hep kids who don't want to learn the proper way to do things +these days. Why, I remember way back in the summer of '89, when I was +using Emacs on a Tops 20 system. Three hundred users on one single +machine, and every user was running Simula compilers. Bah! + +Right. + +@vindex gnus-carpal +Well, you can make Gnus display bufferfuls of buttons you can click to +do anything by setting @code{gnus-carpal} to @code{t}. Pretty simple, +really. Tell the chiropractor I sent you. + + +@table @code + +@item gnus-carpal-mode-hook +@vindex gnus-carpal-mode-hook +Hook run in all carpal mode buffers. + +@item gnus-carpal-button-face +@vindex gnus-carpal-button-face +Face used on buttons. + +@item gnus-carpal-header-face +@vindex gnus-carpal-header-face +Face used on carpal buffer headers. + +@item gnus-carpal-group-buffer-buttons +@vindex gnus-carpal-group-buffer-buttons +Buttons in the group buffer. + +@item gnus-carpal-summary-buffer-buttons +@vindex gnus-carpal-summary-buffer-buttons +Buttons in the summary buffer. + +@item gnus-carpal-server-buffer-buttons +@vindex gnus-carpal-server-buffer-buttons +Buttons in the server buffer. + +@item gnus-carpal-browse-buffer-buttons +@vindex gnus-carpal-browse-buffer-buttons +Buttons in the browse buffer. +@end table + +All the @code{buttons} variables are lists. The elements in these list +are either cons cells where the @code{car} contains a text to be displayed and +the @code{cdr} contains a function symbol, or a simple string. + + +@node Daemons +@section Daemons +@cindex demons +@cindex daemons + +Gnus, being larger than any program ever written (allegedly), does lots +of strange stuff that you may wish to have done while you're not +present. For instance, you may want it to check for new mail once in a +while. Or you may want it to close down all connections to all servers +when you leave Emacs idle. And stuff like that. + +Gnus will let you do stuff like that by defining various +@dfn{handlers}. Each handler consists of three elements: A +@var{function}, a @var{time}, and an @var{idle} parameter. + +Here's an example of a handler that closes connections when Emacs has +been idle for thirty minutes: + +@lisp +(gnus-demon-close-connections nil 30) +@end lisp + +Here's a handler that scans for PGP headers every hour when Emacs is +idle: + +@lisp +(gnus-demon-scan-pgp 60 t) +@end lisp + +This @var{time} parameter and than @var{idle} parameter work together +in a strange, but wonderful fashion. Basically, if @var{idle} is +@code{nil}, then the function will be called every @var{time} minutes. + +If @var{idle} is @code{t}, then the function will be called after +@var{time} minutes only if Emacs is idle. So if Emacs is never idle, +the function will never be called. But once Emacs goes idle, the +function will be called every @var{time} minutes. + +If @var{idle} is a number and @var{time} is a number, the function will +be called every @var{time} minutes only when Emacs has been idle for +@var{idle} minutes. + +If @var{idle} is a number and @var{time} is @code{nil}, the function +will be called once every time Emacs has been idle for @var{idle} +minutes. + +And if @var{time} is a string, it should look like @samp{07:31}, and +the function will then be called once every day somewhere near that +time. Modified by the @var{idle} parameter, of course. + +@vindex gnus-demon-timestep +(When I say ``minute'' here, I really mean @code{gnus-demon-timestep} +seconds. This is 60 by default. If you change that variable, +all the timings in the handlers will be affected.) + +@vindex gnus-use-demon +To set the whole thing in motion, though, you have to set +@code{gnus-use-demon} to @code{t}. + +So, if you want to add a handler, you could put something like this in +your @file{.gnus} file: + +@findex gnus-demon-add-handler +@lisp +(gnus-demon-add-handler 'gnus-demon-close-connections 30 t) +@end lisp + +@findex gnus-demon-add-nocem +@findex gnus-demon-add-scanmail +@findex gnus-demon-add-rescan +@findex gnus-demon-add-scan-timestamps +@findex gnus-demon-add-disconnection +Some ready-made functions to do this have been created: +@code{gnus-demon-add-nocem}, @code{gnus-demon-add-disconnection}, +@code{gnus-demon-add-nntp-close-connection}, +@code{gnus-demon-add-scan-timestamps}, @code{gnus-demon-add-rescan}, and +@code{gnus-demon-add-scanmail}. Just put those functions in your +@file{.gnus} if you want those abilities. + +@findex gnus-demon-init +@findex gnus-demon-cancel +@vindex gnus-demon-handlers +If you add handlers to @code{gnus-demon-handlers} directly, you should +run @code{gnus-demon-init} to make the changes take hold. To cancel all +daemons, you can use the @code{gnus-demon-cancel} function. + +Note that adding daemons can be pretty naughty if you over do it. Adding +functions that scan all news and mail from all servers every two seconds +is a sure-fire way of getting booted off any respectable system. So +behave. + + +@node NoCeM +@section NoCeM +@cindex nocem +@cindex spam + +@dfn{Spamming} is posting the same article lots and lots of times. +Spamming is bad. Spamming is evil. + +Spamming is usually canceled within a day or so by various anti-spamming +agencies. These agencies usually also send out @dfn{NoCeM} messages. +NoCeM is pronounced ``no see-'em'', and means what the name +implies---these are messages that make the offending articles, like, go +away. + +What use are these NoCeM messages if the articles are canceled anyway? +Some sites do not honor cancel messages and some sites just honor cancels +from a select few people. Then you may wish to make use of the NoCeM +messages, which are distributed in the @samp{alt.nocem.misc} newsgroup. + +Gnus can read and parse the messages in this group automatically, and +this will make spam disappear. + +There are some variables to customize, of course: + +@table @code +@item gnus-use-nocem +@vindex gnus-use-nocem +Set this variable to @code{t} to set the ball rolling. It is @code{nil} +by default. + +@item gnus-nocem-groups +@vindex gnus-nocem-groups +Gnus will look for NoCeM messages in the groups in this list. The +default is @code{("news.lists.filters" "news.admin.net-abuse.bulletins" +"alt.nocem.misc" "news.admin.net-abuse.announce")}. + +@item gnus-nocem-issuers +@vindex gnus-nocem-issuers +There are many people issuing NoCeM messages. This list says what +people you want to listen to. The default is @code{("Automoose-1" +"rbraver@@ohww.norman.ok.us" "clewis@@ferret.ocunix.on.ca" +"jem@@xpat.com" "snowhare@@xmission.com" "red@@redpoll.mrfs.oh.us +(Richard E. Depew)")}; fine, upstanding citizens all of them. + +Known despammers that you can put in this list include: + +@table @samp +@item clewis@@ferret.ocunix.on.ca; +@cindex Chris Lewis +Chris Lewis---Major Canadian despammer who has probably canceled more +usenet abuse than anybody else. + +@item Automoose-1 +@cindex CancelMoose[tm] +The CancelMoose[tm] on autopilot. The CancelMoose[tm] is reputed to be +Norwegian, and was the person(s) who invented NoCeM. + +@item jem@@xpat.com; +@cindex Jem +John Milburn---despammer located in Korea who is getting very busy these +days. + +@item red@@redpoll.mrfs.oh.us (Richard E. Depew) +Richard E. Depew---lone American despammer. He mostly cancels binary +postings to non-binary groups and removes spews (regurgitated articles). +@end table + +You do not have to heed NoCeM messages from all these people---just the +ones you want to listen to. You also don't have to accept all NoCeM +messages from the people you like. Each NoCeM message has a @dfn{type} +header that gives the message a (more or less, usually less) rigorous +definition. Common types are @samp{spam}, @samp{spew}, @samp{mmf}, +@samp{binary}, and @samp{troll}. To specify this, you have to use +@var{(issuer conditions ...)} elements in the list. Each condition is +either a string (which is a regexp that matches types you want to use) +or a list on the form @code{(not STRING)}, where @var{string} is a +regexp that matches types you don't want to use. + +For instance, if you want all NoCeM messages from Chris Lewis except his +@samp{troll} messages, you'd say: + +@lisp +("clewis@@ferret.ocunix.on.ca" ".*" (not "troll")) +@end lisp + +On the other hand, if you just want nothing but his @samp{spam} and +@samp{spew} messages, you'd say: + +@lisp +("clewis@@ferret.ocunix.on.ca" (not ".*") "spew" "spam") +@end lisp + +The specs are applied left-to-right. + + +@item gnus-nocem-verifyer +@vindex gnus-nocem-verifyer +@findex mc-verify +This should be a function for verifying that the NoCeM issuer is who she +says she is. The default is @code{mc-verify}, which is a Mailcrypt +function. If this is too slow and you don't care for verification +(which may be dangerous), you can set this variable to @code{nil}. + +If you want signed NoCeM messages to be verified and unsigned messages +not to be verified (but used anyway), you could do something like: + +@lisp +(setq gnus-nocem-verifyer 'my-gnus-mc-verify) + +(defun my-gnus-mc-verify () + (not (eq 'forged + (ignore-errors + (if (mc-verify) + t + 'forged))))) +@end lisp + +This might be dangerous, though. + +@item gnus-nocem-directory +@vindex gnus-nocem-directory +This is where Gnus will store its NoCeM cache files. The default is +@file{~/News/NoCeM/}. + +@item gnus-nocem-expiry-wait +@vindex gnus-nocem-expiry-wait +The number of days before removing old NoCeM entries from the cache. +The default is 15. If you make it shorter Gnus will be faster, but you +might then see old spam. + +@end table + +Using NoCeM could potentially be a memory hog. If you have many living +(i. e., subscribed or unsubscribed groups), your Emacs process will grow +big. If this is a problem, you should kill off all (or most) of your +unsubscribed groups (@pxref{Subscription Commands}). + + +@node Undo +@section Undo +@cindex undo + +It is very useful to be able to undo actions one has done. In normal +Emacs buffers, it's easy enough---you just push the @code{undo} button. +In Gnus buffers, however, it isn't that simple. + +The things Gnus displays in its buffer is of no value whatsoever to +Gnus---it's all just data designed to look nice to the user. +Killing a group in the group buffer with @kbd{C-k} makes the line +disappear, but that's just a side-effect of the real action---the +removal of the group in question from the internal Gnus structures. +Undoing something like that can't be done by the normal Emacs +@code{undo} function. + +Gnus tries to remedy this somewhat by keeping track of what the user +does and coming up with actions that would reverse the actions the user +takes. When the user then presses the @code{undo} key, Gnus will run +the code to reverse the previous action, or the previous actions. +However, not all actions are easily reversible, so Gnus currently offers +a few key functions to be undoable. These include killing groups, +yanking groups, and changing the list of read articles of groups. +That's it, really. More functions may be added in the future, but each +added function means an increase in data to be stored, so Gnus will +never be totally undoable. + +@findex gnus-undo-mode +@vindex gnus-use-undo +@findex gnus-undo +The undoability is provided by the @code{gnus-undo-mode} minor mode. It +is used if @code{gnus-use-undo} is non-@code{nil}, which is the +default. The @kbd{M-C-_} key performs the @code{gnus-undo} command +command, which should feel kinda like the normal Emacs @code{undo} +command. + + +@node Moderation +@section Moderation +@cindex moderation + +If you are a moderator, you can use the @file{gnus-mdrtn.el} package. +It is not included in the standard Gnus package. Write a mail to +@samp{larsi@@gnus.org} and state what group you moderate, and you'll +get a copy. + +The moderation package is implemented as a minor mode for summary +buffers. Put + +@lisp +(add-hook 'gnus-summary-mode-hook 'gnus-moderate) +@end lisp + +in your @file{.gnus.el} file. + +If you are the moderator of @samp{rec.zoofle}, this is how it's +supposed to work: + +@enumerate +@item +You split your incoming mail by matching on +@samp{Newsgroups:.*rec.zoofle}, which will put all the to-be-posted +articles in some mail group---for instance, @samp{nnml:rec.zoofle}. + +@item +You enter that group once in a while and post articles using the @kbd{e} +(edit-and-post) or @kbd{s} (just send unedited) commands. + +@item +If, while reading the @samp{rec.zoofle} newsgroup, you happen upon some +articles that weren't approved by you, you can cancel them with the +@kbd{c} command. +@end enumerate + +To use moderation mode in these two groups, say: + +@lisp +(setq gnus-moderated-list + "^nnml:rec.zoofle$\\|^rec.zoofle$") +@end lisp + + +@node XEmacs Enhancements +@section XEmacs Enhancements +@cindex XEmacs + +XEmacs is able to display pictures and stuff, so Gnus has taken +advantage of that. + +@menu +* Picons:: How to display pictures of what your reading. +* Smileys:: Show all those happy faces the way they were meant to be shown. +* Toolbar:: Click'n'drool. +* XVarious:: Other XEmacsy Gnusey variables. +@end menu + + +@node Picons +@subsection Picons + +So... You want to slow down your news reader even more! This is a +good way to do so. Its also a great way to impress people staring +over your shoulder as you read news. + +@menu +* Picon Basics:: What are picons and How do I get them. +* Picon Requirements:: Don't go further if you aren't using XEmacs. +* Easy Picons:: Displaying Picons---the easy way. +* Hard Picons:: The way you should do it. You'll learn something. +* Picon Useless Configuration:: Other variables you can trash/tweak/munge/play with. +@end menu + + +@node Picon Basics +@subsubsection Picon Basics + +What are Picons? To quote directly from the Picons Web site: + +@quotation +@dfn{Picons} is short for ``personal icons''. They're small, +constrained images used to represent users and domains on the net, +organized into databases so that the appropriate image for a given +e-mail address can be found. Besides users and domains, there are picon +databases for Usenet newsgroups and weather forecasts. The picons are +in either monochrome @code{XBM} format or color @code{XPM} and +@code{GIF} formats. +@end quotation + +@vindex gnus-picons-piconsearch-url +If you have a permanent connection to the Internet you can use Steve +Kinzler's Picons Search engine by setting +@code{gnus-picons-piconsearch-url} to the string @* +@file{http://www.cs.indiana.edu/picons/search.html}. + +@vindex gnus-picons-database +Otherwise you need a local copy of his database. For instructions on +obtaining and installing the picons databases, point your Web browser at @* +@file{http://www.cs.indiana.edu/picons/ftp/index.html}. Gnus expects +picons to be installed into a location pointed to by +@code{gnus-picons-database}. + + +@node Picon Requirements +@subsubsection Picon Requirements + +To have Gnus display Picons for you, you must be running XEmacs +19.13 or greater since all other versions of Emacs aren't yet able to +display images. + +Additionally, you must have @code{x} support compiled into XEmacs. To +display color picons which are much nicer than the black & white one, +you also need one of @code{xpm} or @code{gif} compiled into XEmacs. + +@vindex gnus-picons-convert-x-face +If you want to display faces from @code{X-Face} headers, you should have +the @code{xface} support compiled into XEmacs. Otherwise you must have +the @code{netpbm} utilities installed, or munge the +@code{gnus-picons-convert-x-face} variable to use something else. + + +@node Easy Picons +@subsubsection Easy Picons + +To enable displaying picons, simply put the following line in your +@file{~/.gnus} file and start Gnus. + +@lisp +(setq gnus-use-picons t) +(add-hook 'gnus-article-display-hook + 'gnus-article-display-picons t) +(add-hook 'gnus-article-display-hook + 'gnus-picons-article-display-x-face) +@end lisp + +and make sure @code{gnus-picons-database} points to the directory +containing the Picons databases. + +Alternatively if you want to use the web piconsearch engine add this: + +@lisp +(setq gnus-picons-piconsearch-url + "http://www.cs.indiana.edu:800/piconsearch") +@end lisp + + +@node Hard Picons +@subsubsection Hard Picons + +Gnus can display picons for you as you enter and leave groups and +articles. It knows how to interact with three sections of the picons +database. Namely, it can display the picons newsgroup pictures, +author's face picture(s), and the authors domain. To enable this +feature, you need to select where to get the picons from, and where to +display them. + +@table @code + +@item gnus-picons-database +@vindex gnus-picons-database +The location of the picons database. Should point to a directory +containing the @file{news}, @file{domains}, @file{users} (and so on) +subdirectories. This is only useful if +@code{gnus-picons-piconsearch-url} is @code{nil}. Defaults to +@file{/usr/local/faces/}. + +@item gnus-picons-piconsearch-url +@vindex gnus-picons-piconsearch-url +The URL for the web picons search engine. The only currently known +engine is @file{http://www.cs.indiana.edu:800/piconsearch}. To +workaround network delays, icons will be fetched in the background. If +this is @code{nil} 'the default), then picons are fetched from local +database indicated by @code{gnus-picons-database}. + +@item gnus-picons-display-where +@vindex gnus-picons-display-where +Where the picon images should be displayed. It is @code{picons} by +default (which by default maps to the buffer @samp{*Picons*}). Other +valid places could be @code{article}, @code{summary}, or +@samp{*scratch*} for all I care. Just make sure that you've made the +buffer visible using the standard Gnus window configuration +routines---@pxref{Windows Configuration}. + +@item gnus-picons-group-excluded-groups +@vindex gnus-picons-group-excluded-groups +Groups that are matched by this regexp won't have their group icons +displayed. + +@end table + +Note: If you set @code{gnus-use-picons} to @code{t}, it will set up your +window configuration for you to include the @code{picons} buffer. + +Now that you've made those decision, you need to add the following +functions to the appropriate hooks so these pictures will get displayed +at the right time. + +@vindex gnus-article-display-hook +@vindex gnus-picons-display-where +@table @code +@item gnus-article-display-picons +@findex gnus-article-display-picons +Looks up and displays the picons for the author and the author's domain +in the @code{gnus-picons-display-where} buffer. Should be added to the +@code{gnus-article-display-hook}. + +@item gnus-picons-article-display-x-face +@findex gnus-article-display-picons +Decodes and displays the X-Face header if present. This function +should be added to @code{gnus-article-display-hook}. + +@end table + +Note: You must append them to the hook, so make sure to specify 't' +for the append flag of @code{add-hook}: + +@lisp +(add-hook 'gnus-article-display-hook 'gnus-article-display-picons t) +@end lisp + + +@node Picon Useless Configuration +@subsubsection Picon Useless Configuration + +The following variables offer further control over how things are +done, where things are located, and other useless stuff you really +don't need to worry about. + +@table @code + +@item gnus-picons-news-directories +@vindex gnus-picons-news-directories +List of subdirectories to search in @code{gnus-picons-database} for +newsgroups faces. @code{("news")} is the default. + +@item gnus-picons-user-directories +@vindex gnus-picons-user-directories +List of subdirectories to search in @code{gnus-picons-database} for user +faces. @code{("local" "users" "usenix" "misc")} is the default. + +@item gnus-picons-domain-directories +@vindex gnus-picons-domain-directories +List of subdirectories to search in @code{gnus-picons-database} for +domain name faces. Defaults to @code{("domains")}. Some people may +want to add @samp{"unknown"} to this list. + +@item gnus-picons-convert-x-face +@vindex gnus-picons-convert-x-face +If you don't have @code{xface} support builtin XEmacs, this is the +command to use to convert the @code{X-Face} header to an X bitmap +(@code{xbm}). Defaults to @code{(format "@{ echo '/* Width=48, +Height=48 */'; uncompface; @} | icontopbm | pbmtoxbm > %s" +gnus-picons-x-face-file-name)} + +@item gnus-picons-x-face-file-name +@vindex gnus-picons-x-face-file-name +Names a temporary file to store the @code{X-Face} bitmap in. Defaults +to @code{(format "/tmp/picon-xface.%s.xbm" (user-login-name))}. + +@item gnus-picons-has-modeline-p +@vindex gnus-picons-has-modeline-p +If you have set @code{gnus-picons-display-where} to @code{picons}, your +XEmacs frame will become really cluttered. To alleviate this a bit you +can set @code{gnus-picons-has-modeline-p} to @code{nil}; this will +remove the mode line from the Picons buffer. This is only useful if +@code{gnus-picons-display-where} is @code{picons}. + +@item gnus-picons-refresh-before-display +@vindex gnus-picons-refresh-before-display +If non-nil, display the article buffer before computing the picons. +Defaults to @code{nil}. + +@item gnus-picons-display-as-address +@vindex gnus-picons-display-as-address +If @code{t} display textual email addresses along with pictures. +Defaults to @code{t}. + +@item gnus-picons-file-suffixes +@vindex gnus-picons-file-suffixes +Ordered list of suffixes on picon file names to try. Defaults to +@code{("xpm" "gif" "xbm")} minus those not builtin your XEmacs. + +@item gnus-picons-display-article-move-p +@vindex gnus-picons-display-article-move-p +Whether to move point to first empty line when displaying picons. This +has only an effect if `gnus-picons-display-where' has value `article'. + +@item gnus-picons-clear-cache-on-shutdown +@vindex gnus-picons-clear-cache-on-shutdown +Whether to clear the picons cache when exiting gnus. Gnus caches every +picons it finds while it is running. This saves some time in the search +process but eats some memory. If this variable is set to @code{nil}, +Gnus will never clear the cache itself; you will have to manually call +@code{gnus-picons-clear-cache} to clear it. Otherwise the cache will be +cleared every time you exit Gnus. Defaults to @code{t}. + +@end table + +@node Smileys +@subsection Smileys +@cindex smileys + +@dfn{Smiley} is a package separate from Gnus, but since Gnus is +currently the only package that uses Smiley, it is documented here. + +In short---to use Smiley in Gnus, put the following in your +@file{.gnus.el} file: + +@lisp +(add-hook 'gnus-article-display-hook 'gnus-smiley-display t) +@end lisp + +Smiley maps text smiley faces---@samp{:-)}, @samp{:-=}, @samp{:-(} and +the like---to pictures and displays those instead of the text smiley +faces. The conversion is controlled by a list of regexps that matches +text and maps that to file names. + +@vindex smiley-nosey-regexp-alist +@vindex smiley-deformed-regexp-alist +Smiley supplies two example conversion alists by default: +@code{smiley-deformed-regexp-alist} (which matches @samp{:)}, @samp{:(} +and so on), and @code{smiley-nosey-regexp-alist} (which matches +@samp{:-)}, @samp{:-(} and so on). + +The alist used is specified by the @code{smiley-regexp-alist} variable, +which defaults to the value of @code{smiley-deformed-regexp-alist}. + +The first item in each element is the regexp to be matched; the second +element is the regexp match group that is to be replaced by the picture; +and the third element is the name of the file to be displayed. + +The following variables customize where Smiley will look for these +files, as well as the color to be used and stuff: + +@table @code + +@item smiley-data-directory +@vindex smiley-data-directory +Where Smiley will look for smiley faces files. + +@item smiley-flesh-color +@vindex smiley-flesh-color +Skin color. The default is @samp{yellow}, which is really racist. + +@item smiley-features-color +@vindex smiley-features-color +Color of the features of the face. The default is @samp{black}. + +@item smiley-tongue-color +@vindex smiley-tongue-color +Color of the tongue. The default is @samp{red}. + +@item smiley-circle-color +@vindex smiley-circle-color +Color of the circle around the face. The default is @samp{black}. + +@item smiley-mouse-face +@vindex smiley-mouse-face +Face used for mouse highlighting over the smiley face. + +@end table + + +@node Toolbar +@subsection Toolbar + +@table @code + +@item gnus-use-toolbar +@vindex gnus-use-toolbar +If @code{nil}, don't display toolbars. If non-@code{nil}, it should be +one of @code{default-toolbar}, @code{top-toolbar}, @code{bottom-toolbar}, +@code{right-toolbar}, or @code{left-toolbar}. + +@item gnus-group-toolbar +@vindex gnus-group-toolbar +The toolbar in the group buffer. + +@item gnus-summary-toolbar +@vindex gnus-summary-toolbar +The toolbar in the summary buffer. + +@item gnus-summary-mail-toolbar +@vindex gnus-summary-mail-toolbar +The toolbar in the summary buffer of mail groups. + +@end table + + +@node XVarious +@subsection Various XEmacs Variables + +@table @code +@item gnus-xmas-glyph-directory +@vindex gnus-xmas-glyph-directory +This is where Gnus will look for pictures. Gnus will normally +auto-detect this directory, but you may set it manually if you have an +unusual directory structure. + +@item gnus-xmas-logo-color-alist +@vindex gnus-xmas-logo-color-alist +This is an alist where the key is a type symbol and the values are the +foreground and background color of the splash page glyph. + +@item gnus-xmas-logo-color-style +@vindex gnus-xmas-logo-color-style +This is the key used to look up the color in the alist described above. +Valid values include @code{flame}, @code{pine}, @code{moss}, +@code{irish}, @code{sky}, @code{tin}, @code{velvet}, @code{grape}, +@code{labia}, @code{berry}, @code{neutral}, and @code{september}. + +@item gnus-xmas-modeline-glyph +@vindex gnus-xmas-modeline-glyph +A glyph displayed in all Gnus mode lines. It is a tiny gnu head by +default. + +@end table + + + + +@node Fuzzy Matching +@section Fuzzy Matching +@cindex fuzzy matching + +Gnus provides @dfn{fuzzy matching} of @code{Subject} lines when doing +things like scoring, thread gathering and thread comparison. + +As opposed to regular expression matching, fuzzy matching is very fuzzy. +It's so fuzzy that there's not even a definition of what @dfn{fuzziness} +means, and the implementation has changed over time. + +Basically, it tries to remove all noise from lines before comparing. +@samp{Re: }, parenthetical remarks, white space, and so on, are filtered +out of the strings before comparing the results. This often leads to +adequate results---even when faced with strings generated by text +manglers masquerading as newsreaders. + + +@node Thwarting Email Spam +@section Thwarting Email Spam +@cindex email spam +@cindex spam +@cindex UCE +@cindex unsolicited commercial email + +In these last days of the Usenet, commercial vultures are hanging about +and grepping through news like crazy to find email addresses they can +foist off their scams and products to. As a reaction to this, many +people have started putting nonsense addresses into their @code{From} +lines. I think this is counterproductive---it makes it difficult for +people to send you legitimate mail in response to things you write, as +well as making it difficult to see who wrote what. This rewriting may +perhaps be a bigger menace than the unsolicited commercial email itself +in the end. + +The biggest problem I have with email spam is that it comes in under +false pretenses. I press @kbd{g} and Gnus merrily informs me that I +have 10 new emails. I say ``Golly gee! Happy is me!'' and select the +mail group, only to find two pyramid schemes, seven advertisements +(``New! Miracle tonic for growing full, lustrous hair on your toes!'') +and one mail asking me to repent and find some god. + +This is annoying. + +The way to deal with this is having Gnus split out all spam into a +@samp{spam} mail group (@pxref{Splitting Mail}). + +First, pick one (1) valid mail address that you can be reached at, and +put it in your @code{From} header of all your news articles. (I've +chosen @samp{larsi@@trym.ifi.uio.no}, but for many addresses on the form +@samp{larsi+usenet@@ifi.uio.no} will be a better choice. Ask your +sysadm whether your sendmail installation accepts keywords in the local +part of the mail address.) + +@lisp +(setq message-default-news-headers + "From: Lars Magne Ingebrigtsen <larsi@@trym.ifi.uio.no>\n") +@end lisp + +Then put the following split rule in @code{nnmail-split-fancy} +(@pxref{Fancy Mail Splitting}): + +@lisp +( + ... + (to "larsi@@trym.ifi.uio.no" + (| ("subject" "re:.*" "misc") + ("references" ".*@@.*" "misc") + "spam")) + ... +) +@end lisp + +This says that all mail to this address is suspect, but if it has a +@code{Subject} that starts with a @samp{Re:} or has a @code{References} +header, it's probably ok. All the rest goes to the @samp{spam} group. +(This idea probably comes from Tim Pierce.) + +In addition, many mail spammers talk directly to your @code{smtp} server +and do not include your email address explicitly in the @code{To} +header. Why they do this is unknown---perhaps it's to thwart this +thwarting scheme? In any case, this is trivial to deal with---you just +put anything not addressed to you in the @samp{spam} group by ending +your fancy split rule in this way: + +@lisp +( + ... + (to "larsi" "misc") + "spam") +@end lisp + +In my experience, this will sort virtually everything into the right +group. You still have to check the @samp{spam} group from time to time to +check for legitimate mail, though. If you feel like being a good net +citizen, you can even send off complaints to the proper authorities on +each unsolicited commercial email---at your leisure. + +If you are also a lazy net citizen, you will probably prefer complaining +automatically with the @file{gnus-junk.el} package, available FOR FREE +at @* @file{<URL:http://stud2.tuwien.ac.at/~e9426626/gnus-junk.html>}. +Since most e-mail spam is sent automatically, this may reconcile the +cosmic balance somewhat. + +This works for me. It allows people an easy way to contact me (they can +just press @kbd{r} in the usual way), and I'm not bothered at all with +spam. It's a win-win situation. Forging @code{From} headers to point +to non-existent domains is yucky, in my opinion. + + +@node Various Various +@section Various Various +@cindex mode lines +@cindex highlights + +@table @code + +@item gnus-home-directory +All Gnus path variables will be initialized from this variable, which +defaults to @file{~/}. + +@item gnus-directory +@vindex gnus-directory +Most Gnus storage path variables will be initialized from this variable, +which defaults to the @samp{SAVEDIR} environment variable, or +@file{~/News/} if that variable isn't set. + +Note that Gnus is mostly loaded when the @file{.gnus.el} file is read. +This means that other directory variables that are initialized from this +variable won't be set properly if you set this variable in +@file{.gnus.el}. Set this variable in @file{.emacs} instead. + +@item gnus-default-directory +@vindex gnus-default-directory +Not related to the above variable at all---this variable says what the +default directory of all Gnus buffers should be. If you issue commands +like @kbd{C-x C-f}, the prompt you'll get starts in the current buffer's +default directory. If this variable is @code{nil} (which is the +default), the default directory will be the default directory of the +buffer you were in when you started Gnus. + +@item gnus-verbose +@vindex gnus-verbose +This variable is an integer between zero and ten. The higher the value, +the more messages will be displayed. If this variable is zero, Gnus +will never flash any messages, if it is seven (which is the default), +most important messages will be shown, and if it is ten, Gnus won't ever +shut up, but will flash so many messages it will make your head swim. + +@item gnus-verbose-backends +@vindex gnus-verbose-backends +This variable works the same way as @code{gnus-verbose}, but it applies +to the Gnus backends instead of Gnus proper. + +@item nnheader-max-head-length +@vindex nnheader-max-head-length +When the backends read straight heads of articles, they all try to read +as little as possible. This variable (default 4096) specifies +the absolute max length the backends will try to read before giving up +on finding a separator line between the head and the body. If this +variable is @code{nil}, there is no upper read bound. If it is +@code{t}, the backends won't try to read the articles piece by piece, +but read the entire articles. This makes sense with some versions of +@code{ange-ftp} or @code{efs}. + +@item nnheader-head-chop-length +@vindex nnheader-head-chop-length +This variable (default 2048) says how big a piece of each article to +read when doing the operation described above. + +@item nnheader-file-name-translation-alist +@vindex nnheader-file-name-translation-alist +@cindex file names +@cindex invalid characters in file names +@cindex characters in file names +This is an alist that says how to translate characters in file names. +For instance, if @samp{:} is invalid as a file character in file names +on your system (you OS/2 user you), you could say something like: + +@lisp +(setq nnheader-file-name-translation-alist + '((?: . ?_))) +@end lisp + +In fact, this is the default value for this variable on OS/2 and MS +Windows (phooey) systems. + +@item gnus-hidden-properties +@vindex gnus-hidden-properties +This is a list of properties to use to hide ``invisible'' text. It is +@code{(invisible t intangible t)} by default on most systems, which +makes invisible text invisible and intangible. + +@item gnus-parse-headers-hook +@vindex gnus-parse-headers-hook +A hook called before parsing headers. It can be used, for instance, to +gather statistics on the headers fetched, or perhaps you'd like to prune +some headers. I don't see why you'd want that, though. + +@item gnus-shell-command-separator +@vindex gnus-shell-command-separator +String used to separate two shell commands. The default is @samp{;}. + + +@end table + + +@node The End +@chapter The End + +Well, that's the manual---you can get on with your life now. Keep in +touch. Say hello to your cats from me. + +My @strong{ghod}---I just can't stand goodbyes. Sniffle. + +Ol' Charles Reznikoff said it pretty well, so I leave the floor to him: + +@quotation +@strong{Te Deum} + +@sp 1 +Not because of victories @* +I sing,@* +having none,@* +but for the common sunshine,@* +the breeze,@* +the largess of the spring. + +@sp 1 +Not for victory@* +but for the day's work done@* +as well as I was able;@* +not for a seat upon the dais@* +but at the common table.@* +@end quotation + + +@node Appendices +@chapter Appendices + +@menu +* History:: How Gnus got where it is today. +* Terminology:: We use really difficult, like, words here. +* Customization:: Tailoring Gnus to your needs. +* Troubleshooting:: What you might try if things do not work. +* A Programmers Guide to Gnus:: Rilly, rilly technical stuff. +* Emacs for Heathens:: A short introduction to Emacsian terms. +* Frequently Asked Questions:: A question-and-answer session. +@end menu + + +@node History +@section History + +@cindex history +@sc{gnus} was written by Masanobu @sc{Umeda}. When autumn crept up in +'94, Lars Magne Ingebrigtsen grew bored and decided to rewrite Gnus. + +If you want to investigate the person responsible for this outrage, you +can point your (feh!) web browser to +@file{http://www.stud.ifi.uio.no/~larsi/}. This is also the primary +distribution point for the new and spiffy versions of Gnus, and is known +as The Site That Destroys Newsrcs And Drives People Mad. + +During the first extended alpha period of development, the new Gnus was +called ``(ding) Gnus''. @dfn{(ding)} is, of course, short for +@dfn{ding is not Gnus}, which is a total and utter lie, but who cares? +(Besides, the ``Gnus'' in this abbreviation should probably be +pronounced ``news'' as @sc{Umeda} intended, which makes it a more +appropriate name, don't you think?) + +In any case, after spending all that energy on coming up with a new and +spunky name, we decided that the name was @emph{too} spunky, so we +renamed it back again to ``Gnus''. But in mixed case. ``Gnus'' vs. +``@sc{gnus}''. New vs. old. + +The first ``proper'' release of Gnus 5 was done in November 1995 when it +was included in the Emacs 19.30 distribution (132 (ding) Gnus releases +plus 15 Gnus 5.0 releases). + +In May 1996 the next Gnus generation (aka. ``September Gnus'' (after 99 +releases)) was released under the name ``Gnus 5.2'' (40 releases). + +On July 28th 1996 work on Red Gnus was begun, and it was released on +January 25th 1997 (after 84 releases) as ``Gnus 5.4'' (67 releases). + +On September 13th 1997, Quassia Gnus was started and lasted 37 +releases. If was released as ``Gnus 5.6 on March 8th 1998. + +If you happen upon a version of Gnus that has a prefixed name -- +``(ding) Gnus'', ``September Gnus'', ``Red Gnus'', ``Quassia Gnus'' -- +don't panic. Don't let it know that you're frightened. Back away. +Slowly. Whatever you do, don't run. Walk away, calmly, until you're +out of its reach. Find a proper released version of Gnus and snuggle up +to that instead. + +@menu +* Why?:: What's the point of Gnus? +* Compatibility:: Just how compatible is Gnus with @sc{gnus}? +* Conformity:: Gnus tries to conform to all standards. +* Emacsen:: Gnus can be run on a few modern Emacsen. +* Contributors:: Oodles of people. +* New Features:: Pointers to some of the new stuff in Gnus. +* Newest Features:: Features so new that they haven't been written yet. +@end menu + + +@node Why? +@subsection Why? + +What's the point of Gnus? + +I want to provide a ``rad'', ``happening'', ``way cool'' and ``hep'' +newsreader, that lets you do anything you can think of. That was my +original motivation, but while working on Gnus, it has become clear to +me that this generation of newsreaders really belong in the stone age. +Newsreaders haven't developed much since the infancy of the net. If the +volume continues to rise with the current rate of increase, all current +newsreaders will be pretty much useless. How do you deal with +newsgroups that have thousands of new articles each day? How do you +keep track of millions of people who post? + +Gnus offers no real solutions to these questions, but I would very much +like to see Gnus being used as a testing ground for new methods of +reading and fetching news. Expanding on @sc{Umeda}-san's wise decision +to separate the newsreader from the backends, Gnus now offers a simple +interface for anybody who wants to write new backends for fetching mail +and news from different sources. I have added hooks for customizations +everywhere I could imagine it being useful. By doing so, I'm inviting +every one of you to explore and invent. + +May Gnus never be complete. @kbd{C-u 100 M-x all-hail-emacs} and +@kbd{C-u 100 M-x all-hail-xemacs}. + + +@node Compatibility +@subsection Compatibility + +@cindex compatibility +Gnus was designed to be fully compatible with @sc{gnus}. Almost all key +bindings have been kept. More key bindings have been added, of course, +but only in one or two obscure cases have old bindings been changed. + +Our motto is: +@quotation +@cartouche +@center In a cloud bones of steel. +@end cartouche +@end quotation + +All commands have kept their names. Some internal functions have changed +their names. + +The @code{gnus-uu} package has changed drastically. @xref{Decoding +Articles}. + +One major compatibility question is the presence of several summary +buffers. All variables relevant while reading a group are +buffer-local to the summary buffer they belong in. Although many +important variables have their values copied into their global +counterparts whenever a command is executed in the summary buffer, this +change might lead to incorrect values being used unless you are careful. + +All code that relies on knowledge of @sc{gnus} internals will probably +fail. To take two examples: Sorting @code{gnus-newsrc-alist} (or +changing it in any way, as a matter of fact) is strictly verboten. Gnus +maintains a hash table that points to the entries in this alist (which +speeds up many functions), and changing the alist directly will lead to +peculiar results. + +@cindex hilit19 +@cindex highlighting +Old hilit19 code does not work at all. In fact, you should probably +remove all hilit code from all Gnus hooks +(@code{gnus-group-prepare-hook} and @code{gnus-summary-prepare-hook}). +Gnus provides various integrated functions for highlighting. These are +faster and more accurate. To make life easier for everybody, Gnus will +by default remove all hilit calls from all hilit hooks. Uncleanliness! +Away! + +Packages like @code{expire-kill} will no longer work. As a matter of +fact, you should probably remove all old @sc{gnus} packages (and other +code) when you start using Gnus. More likely than not, Gnus already +does what you have written code to make @sc{gnus} do. (Snicker.) + +Even though old methods of doing things are still supported, only the +new methods are documented in this manual. If you detect a new method of +doing something while reading this manual, that does not mean you have +to stop doing it the old way. + +Gnus understands all @sc{gnus} startup files. + +@kindex M-x gnus-bug +@findex gnus-bug +@cindex reporting bugs +@cindex bugs +Overall, a casual user who hasn't written much code that depends on +@sc{gnus} internals should suffer no problems. If problems occur, +please let me know by issuing that magic command @kbd{M-x gnus-bug}. + +@vindex gnus-bug-create-help-buffer +If you are in the habit of sending bug reports @emph{very} often, you +may find the helpful help buffer annoying after a while. If so, set +@code{gnus-bug-create-help-buffer} to @code{nil} to avoid having it pop +up at you. + + +@node Conformity +@subsection Conformity + +No rebels without a clue here, ma'am. We conform to all standards known +to (wo)man. Except for those standards and/or conventions we disagree +with, of course. + +@table @strong + +@item RFC 822 +@cindex RFC 822 +There are no known breaches of this standard. + +@item RFC 1036 +@cindex RFC 1036 +There are no known breaches of this standard, either. + +@item Son-of-RFC 1036 +@cindex Son-of-RFC 1036 +We do have some breaches to this one. + +@table @emph + +@item MIME +Gnus does no MIME handling, and this standard-to-be seems to think that +MIME is the bees' knees, so we have major breakage here. + +@item X-Newsreader +This is considered to be a ``vanity header'', while I consider it to be +consumer information. After seeing so many badly formatted articles +coming from @code{tin} and @code{Netscape} I know not to use either of +those for posting articles. I would not have known that if it wasn't +for the @code{X-Newsreader} header. +@end table + +@end table + +If you ever notice Gnus acting non-compliant with regards to the texts +mentioned above, don't hesitate to drop a note to Gnus Towers and let us +know. + + +@node Emacsen +@subsection Emacsen +@cindex Emacsen +@cindex XEmacs +@cindex Mule +@cindex Emacs + +Gnus should work on : + +@itemize @bullet + +@item +Emacs 19.32 and up. + +@item +XEmacs 19.14 and up. + +@item +Mule versions based on Emacs 19.32 and up. + +@end itemize + +Gnus will absolutely not work on any Emacsen older than that. Not +reliably, at least. + +There are some vague differences between Gnus on the various +platforms---XEmacs features more graphics (a logo and a toolbar)---but +other than that, things should look pretty much the same under all +Emacsen. + + +@node Contributors +@subsection Contributors +@cindex contributors + +The new Gnus version couldn't have been done without the help of all the +people on the (ding) mailing list. Every day for over a year I have +gotten billions of nice bug reports from them, filling me with joy, +every single one of them. Smooches. The people on the list have been +tried beyond endurance, what with my ``oh, that's a neat idea <type +type>, yup, I'll release it right away <ship off> no wait, that doesn't +work at all <type type>, yup, I'll ship that one off right away <ship +off> no, wait, that absolutely does not work'' policy for releases. +Micro$oft---bah. Amateurs. I'm @emph{much} worse. (Or is that +``worser''? ``much worser''? ``worsest''?) + +I would like to take this opportunity to thank the Academy for... oops, +wrong show. + +@itemize @bullet + +@item +Masanobu @sc{Umeda}---the writer of the original @sc{gnus}. + +@item +Per Abrahamsen---custom, scoring, highlighting and @sc{soup} code (as +well as numerous other things). + +@item +Luis Fernandes---design and graphics. + +@item +Erik Naggum---help, ideas, support, code and stuff. + +@item +Wes Hardaker---@file{gnus-picon.el} and the manual section on +@dfn{picons} (@pxref{Picons}). + +@item +Kim-Minh Kaplan---further work on the picon code. + +@item +Brad Miller---@file{gnus-gl.el} and the GroupLens manual section +(@pxref{GroupLens}). + +@item +Sudish Joseph---innumerable bug fixes. + +@item +Ilja Weis---@file{gnus-topic.el}. + +@item +Steven L. Baur---lots and lots and lots of bugs detections and fixes. + +@item +Vladimir Alexiev---the refcard and reference booklets. + +@item +Felix Lee & Jamie Zawinski---I stole some pieces from the XGnus +distribution by Felix Lee and JWZ. + +@item +Scott Byer---@file{nnfolder.el} enhancements & rewrite. + +@item +Peter Mutsaers---orphan article scoring code. + +@item +Ken Raeburn---POP mail support. + +@item +Hallvard B Furuseth---various bits and pieces, especially dealing with +.newsrc files. + +@item +Brian Edmonds---@file{gnus-bbdb.el}. + +@item +David Moore---rewrite of @file{nnvirtual.el} and many other things. + +@item +Kevin Davidson---came up with the name @dfn{ding}, so blame him. + +@item +François Pinard---many, many interesting and thorough bug reports, as +well as autoconf support. + +@end itemize + +This manual was proof-read by Adrian Aichner, with Ricardo Nassif, Mark +Borges, and Jost Krieger proof-reading parts of the manual. + +The following people have contributed many patches and suggestions: + +Christopher Davis, +Andrew Eskilsson, +Kai Grossjohann, +David Kågedal, +Richard Pieri, +Fabrice Popineau, +Daniel Quinlan, +Jason L. Tibbitts, III, +and +Jack Vinson. + +Also thanks to the following for patches and stuff: + +Jari Aalto, +Adrian Aichner, +Vladimir Alexiev, +Russ Allbery, +Peter Arius, +Matt Armstrong, +Marc Auslander, +Frank Bennett, +Robert Bihlmeyer, +Chris Bone, +Mark Borges, +Mark Boyns, +Lance A. Brown, +Kees de Bruin, +Martin Buchholz, +Joe Buehler, +Kevin Buhr, +Alastair Burt, +Joao Cachopo, +Zlatko Calusic, +Massimo Campostrini, +Castor, +David Charlap, +Dan Christensen, +Kevin Christian, +Michael R. Cook, +Glenn Coombs, +Frank D. Cringle, +Geoffrey T. Dairiki, +Andre Deparade, +Ulrik Dickow, +Dave Disser, +Rui-Tao Dong, @c ? +Joev Dubach, +Michael Welsh Duggan, +Dave Edmondson, +Paul Eggert, +Enami Tsugutomo, @c Enami +Michael Ernst, +Luc Van Eycken, +Sam Falkner, +Nelson Jose dos Santos Ferreira, +Sigbjorn Finne, +Decklin Foster, +Gary D. Foster, +Paul Franklin, +Guy Geens, +Arne Georg Gleditsch, +David S. Goldberg, +Michelangelo Grigni, +D. Hall, +Magnus Hammerin, +Kenichi Handa, @c Handa +Raja R. Harinath, +Yoshiki Hayashi, @c ? +P. E. Jareth Hein, +Hisashige Kenji, @c Hisashige +Marc Horowitz, +Gunnar Horrigmo, +Richard Hoskins, +Brad Howes, +François Felix Ingrand, +Ishikawa Ichiro, @c Ishikawa +Lee Iverson, +Iwamuro Motonori, @c Iwamuro +Rajappa Iyer, +Andreas Jaeger, +Randell Jesup, +Fred Johansen, +Gareth Jones, +Simon Josefsson, +Greg Klanderman, +Karl Kleinpaste, +Peter Skov Knudsen, +Shuhei Kobayashi, @c Kobayashi +Koseki Yoshinori, @c Koseki +Thor Kristoffersen, +Jens Lautenbacher, +Martin Larose, +Seokchan Lee, @c Lee +Carsten Leonhardt, +James LewisMoss, +Christian Limpach, +Markus Linnala, +Dave Love, +Mike McEwan, +Tonny Madsen, +Shlomo Mahlab, +Nat Makarevitch, +Istvan Marko, +David Martin, +Jason R. Mastaler, +Gordon Matzigkeit, +Timo Metzemakers, +Richard Mlynarik, +Lantz Moore, +Morioka Tomohiko, @c Morioka +Erik Toubro Nielsen, +Hrvoje Niksic, +Andy Norman, +Fred Oberhauser, +C. R. Oldham, +Alexandre Oliva, +Ken Olstad, +Masaharu Onishi, @c Onishi +Hideki Ono, @c Ono +William Perry, +Stephen Peters, +Jens-Ulrik Holger Petersen, +Ulrich Pfeifer, +Matt Pharr, +John McClary Prevost, +Bill Pringlemeir, +Mike Pullen, +Jim Radford, +Colin Rafferty, +Lasse Rasinen, +Lars Balker Rasmussen, +Joe Reiss, +Renaud Rioboo, +Roland B. Roberts, +Bart Robinson, +Christian von Roques, +Jason Rumney, +Wolfgang Rupprecht, +Jay Sachs, +Dewey M. Sasser, +Loren Schall, +Dan Schmidt, +Ralph Schleicher, +Philippe Schnoebelen, +Andreas Schwab, +Randal L. Schwartz, +Justin Sheehy, +Danny Siu, +Matt Simmons, +Paul D. Smith, +Jeff Sparkes, +Toby Speight, +Michael Sperber, +Darren Stalder, +Richard Stallman, +Greg Stark, +Sam Steingold, +Paul Stodghill, +Kurt Swanson, +Samuel Tardieu, +Teddy, +Chuck Thompson, +Philippe Troin, +James Troup, +Trung Tran-Duc, +Aaron M. Ucko, +Aki Vehtari, +Didier Verna, +Jan Vroonhof, +Stefan Waldherr, +Pete Ware, +Barry A. Warsaw, +Christoph Wedler, +Joe Wells, +Katsumi Yamaoka, @c Yamaoka +and +Shenghuo Zhu. @c Zhu + +For a full overview of what each person has done, the ChangeLogs +included in the Gnus alpha distributions should give ample reading +(550kB and counting). + +Apologies to everybody that I've forgotten, of which there are many, I'm +sure. + +Gee, that's quite a list of people. I guess that must mean that there +actually are people who are using Gnus. Who'd'a thunk it! + + +@node New Features +@subsection New Features +@cindex new features + +@menu +* ding Gnus:: New things in Gnus 5.0/5.1, the first new Gnus. +* September Gnus:: The Thing Formally Known As Gnus 5.3/5.3. +* Red Gnus:: Third time best---Gnus 5.4/5.5. +* Quassia Gnus:: Two times two is four, or Gnus 5.6/5.7. +@end menu + +These lists are, of course, just @emph{short} overviews of the +@emph{most} important new features. No, really. There are tons more. +Yes, we have feeping creaturism in full effect. + + +@node ding Gnus +@subsubsection (ding) Gnus + +New features in Gnus 5.0/5.1: + +@itemize @bullet + +@item +The look of all buffers can be changed by setting format-like variables +(@pxref{Group Buffer Format} and @pxref{Summary Buffer Format}). + +@item +Local spool and several @sc{nntp} servers can be used at once +(@pxref{Select Methods}). + +@item +You can combine groups into virtual groups (@pxref{Virtual Groups}). + +@item +You can read a number of different mail formats (@pxref{Getting Mail}). +All the mail backends implement a convenient mail expiry scheme +(@pxref{Expiring Mail}). + +@item +Gnus can use various strategies for gathering threads that have lost +their roots (thereby gathering loose sub-threads into one thread) or it +can go back and retrieve enough headers to build a complete thread +(@pxref{Customizing Threading}). + +@item +Killed groups can be displayed in the group buffer, and you can read +them as well (@pxref{Listing Groups}). + +@item +Gnus can do partial group updates---you do not have to retrieve the +entire active file just to check for new articles in a few groups +(@pxref{The Active File}). + +@item +Gnus implements a sliding scale of subscribedness to groups +(@pxref{Group Levels}). + +@item +You can score articles according to any number of criteria +(@pxref{Scoring}). You can even get Gnus to find out how to score +articles for you (@pxref{Adaptive Scoring}). + +@item +Gnus maintains a dribble buffer that is auto-saved the normal Emacs +manner, so it should be difficult to lose much data on what you have +read if your machine should go down (@pxref{Auto Save}). + +@item +Gnus now has its own startup file (@file{.gnus}) to avoid cluttering up +the @file{.emacs} file. + +@item +You can set the process mark on both groups and articles and perform +operations on all the marked items (@pxref{Process/Prefix}). + +@item +You can grep through a subset of groups and create a group from the +results (@pxref{Kibozed Groups}). + +@item +You can list subsets of groups according to, well, anything +(@pxref{Listing Groups}). + +@item +You can browse foreign servers and subscribe to groups from those +servers (@pxref{Browse Foreign Server}). + +@item +Gnus can fetch articles, asynchronously, on a second connection to the +server (@pxref{Asynchronous Fetching}). + +@item +You can cache articles locally (@pxref{Article Caching}). + +@item +The uudecode functions have been expanded and generalized +(@pxref{Decoding Articles}). + +@item +You can still post uuencoded articles, which was a little-known feature +of @sc{gnus}' past (@pxref{Uuencoding and Posting}). + +@item +Fetching parents (and other articles) now actually works without +glitches (@pxref{Finding the Parent}). + +@item +Gnus can fetch FAQs and group descriptions (@pxref{Group Information}). + +@item +Digests (and other files) can be used as the basis for groups +(@pxref{Document Groups}). + +@item +Articles can be highlighted and customized (@pxref{Customizing +Articles}). + +@item +URLs and other external references can be buttonized (@pxref{Article +Buttons}). + +@item +You can do lots of strange stuff with the Gnus window & frame +configuration (@pxref{Windows Configuration}). + +@item +You can click on buttons instead of using the keyboard +(@pxref{Buttons}). + +@end itemize + + +@node September Gnus +@subsubsection September Gnus + +New features in Gnus 5.2/5.3: + +@itemize @bullet + +@item +A new message composition mode is used. All old customization variables +for @code{mail-mode}, @code{rnews-reply-mode} and @code{gnus-msg} are +now obsolete. + +@item +Gnus is now able to generate @dfn{sparse} threads---threads where +missing articles are represented by empty nodes (@pxref{Customizing +Threading}). + +@lisp +(setq gnus-build-sparse-threads 'some) +@end lisp + +@item +Outgoing articles are stored on a special archive server +(@pxref{Archived Messages}). + +@item +Partial thread regeneration now happens when articles are +referred. + +@item +Gnus can make use of GroupLens predictions (@pxref{GroupLens}). + +@item +Picons (personal icons) can be displayed under XEmacs (@pxref{Picons}). + +@item +A @code{trn}-like tree buffer can be displayed (@pxref{Tree Display}). + +@lisp +(setq gnus-use-trees t) +@end lisp + +@item +An @code{nn}-like pick-and-read minor mode is available for the summary +buffers (@pxref{Pick and Read}). + +@lisp +(add-hook 'gnus-summary-mode-hook 'gnus-pick-mode) +@end lisp + +@item +In binary groups you can use a special binary minor mode (@pxref{Binary +Groups}). + +@item +Groups can be grouped in a folding topic hierarchy (@pxref{Group +Topics}). + +@lisp +(add-hook 'gnus-group-mode-hook 'gnus-topic-mode) +@end lisp + +@item +Gnus can re-send and bounce mail (@pxref{Summary Mail Commands}). + +@item +Groups can now have a score, and bubbling based on entry frequency +is possible (@pxref{Group Score}). + +@lisp +(add-hook 'gnus-summary-exit-hook 'gnus-summary-bubble-group) +@end lisp + +@item +Groups can be process-marked, and commands can be performed on +groups of groups (@pxref{Marking Groups}). + +@item +Caching is possible in virtual groups. + +@item +@code{nndoc} now understands all kinds of digests, mail boxes, rnews +news batches, ClariNet briefs collections, and just about everything +else (@pxref{Document Groups}). + +@item +Gnus has a new backend (@code{nnsoup}) to create/read SOUP packets +(@pxref{SOUP}). + +@item +The Gnus cache is much faster. + +@item +Groups can be sorted according to many criteria (@pxref{Sorting +Groups}). + +@item +New group parameters have been introduced to set list-addresses and +expiry times (@pxref{Group Parameters}). + +@item +All formatting specs allow specifying faces to be used +(@pxref{Formatting Fonts}). + +@item +There are several more commands for setting/removing/acting on process +marked articles on the @kbd{M P} submap (@pxref{Setting Process Marks}). + +@item +The summary buffer can be limited to show parts of the available +articles based on a wide range of criteria. These commands have been +bound to keys on the @kbd{/} submap (@pxref{Limiting}). + +@item +Articles can be made persistent with the @kbd{*} command +(@pxref{Persistent Articles}). + +@item +All functions for hiding article elements are now toggles. + +@item +Article headers can be buttonized (@pxref{Article Washing}). + +@lisp +(add-hook 'gnus-article-display-hook + 'gnus-article-add-buttons-to-head) +@end lisp + +@item +All mail backends support fetching articles by @code{Message-ID}. + +@item +Duplicate mail can now be treated properly (@pxref{Duplicates}). + +@item +All summary mode commands are available directly from the article +buffer (@pxref{Article Keymap}). + +@item +Frames can be part of @code{gnus-buffer-configuration} (@pxref{Windows +Configuration}). + +@item +Mail can be re-scanned by a daemonic process (@pxref{Daemons}). + +@item +Gnus can make use of NoCeM files to weed out spam (@pxref{NoCeM}). + +@lisp +(setq gnus-use-nocem t) +@end lisp + +@item +Groups can be made permanently visible (@pxref{Listing Groups}). + +@lisp +(setq gnus-permanently-visible-groups "^nnml:") +@end lisp + +@item +Many new hooks have been introduced to make customizing easier. + +@item +Gnus respects the @code{Mail-Copies-To} header. + +@item +Threads can be gathered by looking at the @code{References} header +(@pxref{Customizing Threading}). + +@lisp +(setq gnus-summary-thread-gathering-function + 'gnus-gather-threads-by-references) +@end lisp + +@item +Read articles can be stored in a special backlog buffer to avoid +refetching (@pxref{Article Backlog}). + +@lisp +(setq gnus-keep-backlog 50) +@end lisp + +@item +A clean copy of the current article is always stored in a separate +buffer to allow easier treatment. + +@item +Gnus can suggest where to save articles (@pxref{Saving Articles}). + +@item +Gnus doesn't have to do as much prompting when saving (@pxref{Saving +Articles}). + +@lisp +(setq gnus-prompt-before-saving t) +@end lisp + +@item +@code{gnus-uu} can view decoded files asynchronously while fetching +articles (@pxref{Other Decode Variables}). + +@lisp +(setq gnus-uu-grabbed-file-functions 'gnus-uu-grab-view) +@end lisp + +@item +Filling in the article buffer now works properly on cited text +(@pxref{Article Washing}). + +@item +Hiding cited text adds buttons to toggle hiding, and how much +cited text to hide is now customizable (@pxref{Article Hiding}). + +@lisp +(setq gnus-cited-lines-visible 2) +@end lisp + +@item +Boring headers can be hidden (@pxref{Article Hiding}). + +@lisp +(add-hook 'gnus-article-display-hook + 'gnus-article-hide-boring-headers t) +@end lisp + +@item +Default scoring values can now be set from the menu bar. + +@item +Further syntax checking of outgoing articles have been added. + +@end itemize + + +@node Red Gnus +@subsubsection Red Gnus + +New features in Gnus 5.4/5.5: + +@itemize @bullet + +@item +@file{nntp.el} has been totally rewritten in an asynchronous fashion. + +@item +Article prefetching functionality has been moved up into +Gnus (@pxref{Asynchronous Fetching}). + +@item +Scoring can now be performed with logical operators like @code{and}, +@code{or}, @code{not}, and parent redirection (@pxref{Advanced +Scoring}). + +@item +Article washing status can be displayed in the +article mode line (@pxref{Misc Article}). + +@item +@file{gnus.el} has been split into many smaller files. + +@item +Suppression of duplicate articles based on Message-ID can be done +(@pxref{Duplicate Suppression}). + +@lisp +(setq gnus-suppress-duplicates t) +@end lisp + +@item +New variables for specifying what score and adapt files are to be +considered home score and adapt files (@pxref{Home Score File}) have +been added. + +@item +@code{nndoc} was rewritten to be easily extendable (@pxref{Document +Server Internals}). + +@item +Groups can inherit group parameters from parent topics (@pxref{Topic +Parameters}). + +@item +Article editing has been revamped and is now actually usable. + +@item +Signatures can be recognized in more intelligent fashions +(@pxref{Article Signature}). + +@item +Summary pick mode has been made to look more @code{nn}-like. Line +numbers are displayed and the @kbd{.} command can be used to pick +articles (@code{Pick and Read}). + +@item +Commands for moving the @file{.newsrc.eld} from one server to +another have been added (@pxref{Changing Servers}). + +@item +There's a way now to specify that ``uninteresting'' fields be suppressed +when generating lines in buffers (@pxref{Advanced Formatting}). + +@item +Several commands in the group buffer can be undone with @kbd{M-C-_} +(@pxref{Undo}). + +@item +Scoring can be done on words using the new score type @code{w} +(@pxref{Score File Format}). + +@item +Adaptive scoring can be done on a Subject word-by-word basis +(@pxref{Adaptive Scoring}). + +@lisp +(setq gnus-use-adaptive-scoring '(word)) +@end lisp + +@item +Scores can be decayed (@pxref{Score Decays}). + +@lisp +(setq gnus-decay-scores t) +@end lisp + +@item +Scoring can be performed using a regexp on the Date header. The Date is +normalized to compact ISO 8601 format first (@pxref{Score File Format}). + +@item +A new command has been added to remove all data on articles from +the native server (@pxref{Changing Servers}). + +@item +A new command for reading collections of documents +(@code{nndoc} with @code{nnvirtual} on top) has been added---@kbd{M-C-d} +(@pxref{Really Various Summary Commands}). + +@item +Process mark sets can be pushed and popped (@pxref{Setting Process +Marks}). + +@item +A new mail-to-news backend makes it possible to post even when the NNTP +server doesn't allow posting (@pxref{Mail-To-News Gateways}). + +@item +A new backend for reading searches from Web search engines +(@dfn{DejaNews}, @dfn{Alta Vista}, @dfn{InReference}) has been added +(@pxref{Web Searches}). + +@item +Groups inside topics can now be sorted using the standard sorting +functions, and each topic can be sorted independently (@pxref{Topic +Sorting}). + +@item +Subsets of the groups can be sorted independently (@code{Sorting +Groups}). + +@item +Cached articles can be pulled into the groups (@pxref{Summary Generation +Commands}). + +@item +Score files are now applied in a more reliable order (@pxref{Score +Variables}). + +@item +Reports on where mail messages end up can be generated (@pxref{Splitting +Mail}). + +@item +More hooks and functions have been added to remove junk from incoming +mail before saving the mail (@pxref{Washing Mail}). + +@item +Emphasized text can be properly fontisized: + +@lisp +(add-hook 'gnus-article-display-hook + 'gnus-article-emphasize) +@end lisp + +@end itemize + + +@node Quassia Gnus +@subsubsection Quassia Gnus + +New features in Gnus 5.6: + +@itemize @bullet + +@item +New functionality for using Gnus as an offline newsreader has been +added. A plethora of new commands and modes have been added. See +@pxref{Gnus Unplugged} for the full story. + +@item + The @code{nndraft} backend has returned, but works differently than +before. All Message buffers are now also articles in the @code{nndraft} +group, which is created automatically. + +@item +@code{gnus-alter-header-function} can now be used to alter header +values. + +@item + @code{gnus-summary-goto-article} now accept Message-ID's. + +@item + A new Message command for deleting text in the body of a message +outside the region: @kbd{C-c C-v}. + +@item + You can now post to component group in @code{nnvirtual} groups with +@kbd{C-u C-c C-c}. + +@item + @code{nntp-rlogin-program}---new variable to ease customization. + +@item + @code{C-u C-c C-c} in @code{gnus-article-edit-mode} will now inhibit +re-highlighting of the article buffer. + +@item + New element in @code{gnus-boring-article-headers}---@code{long-to}. + +@item + @kbd{M-i} symbolic prefix command. See the section "Symbolic +Prefixes" in the Gnus manual for details. + +@item + @kbd{L} and @kbd{I} in the summary buffer now take the symbolic prefix +@kbd{a} to add the score rule to the "all.SCORE" file. + +@item + @code{gnus-simplify-subject-functions} variable to allow greater +control over simplification. + +@item + @kbd{A T}---new command for fetching the current thread. + +@item + @kbd{/ T}---new command for including the current thread in the +limit. + +@item + @kbd{M-RET} is a new Message command for breaking cited text. + +@item + @samp{\\1}-expressions are now valid in @code{nnmail-split-methods}. + +@item + The @code{custom-face-lookup} function has been removed. +If you used this function in your initialization files, you must +rewrite them to use @code{face-spec-set} instead. + +@item + Canceling now uses the current select method. Symbolic prefix +@kbd{a} forces normal posting method. + +@item + New command to translate M******** sm*rtq**t*s into proper +text---@kbd{W d}. + +@item + For easier debugging of @code{nntp}, you can set +@code{nntp-record-commands} to a non-@code{nil} value. + +@item + @code{nntp} now uses @file{~/.authinfo}, a @file{.netrc}-like file, for +controlling where and how to send @sc{authinfo} to @sc{nntp} servers. + +@item + A command for editing group parameters from the summary buffer +has been added. + +@item + A history of where mails have been split is available. + +@item + A new article date command has been added---@code{article-date-iso8601}. + +@item + Subjects can be simplified when threading by setting +@code{gnus-score-thread-simplify}. + +@item + A new function for citing in Message has been +added---@code{message-cite-original-without-signature}. + +@item + @code{article-strip-all-blank-lines}---new article command. + +@item + A new Message command to kill to the end of the article has +been added. + +@item + A minimum adaptive score can be specified by using the +@code{gnus-adaptive-word-minimum} variable. + +@item + The "lapsed date" article header can be kept continually +updated by the @code{gnus-start-date-timer} command. + +@item + Web listserv archives can be read with the @code{nnlistserv} backend. + +@item + Old dejanews archives can now be read by @code{nnweb}. + +@end itemize + + +@node Newest Features +@subsection Newest Features +@cindex todo + +Also known as the @dfn{todo list}. Sure to be implemented before the +next millennium. + +Be afraid. Be very afraid. + +(That a feature appears in this list doesn't necessarily mean that I've +decided to actually implement it. It just means that I think it sounds +interesting.) + +(Yes, this is the actual, up-to-the-second todo list.) + +@itemize @bullet + +@item +Native @sc{mime} support is something that should be done. + +@item +Really do unbinhexing. + +@item + I would like the zombie-page to contain an URL to the source of the +latest version of gnus or some explanation on where to find it. + +@item + A way to continue editing the latest Message composition. + +@item + http://www.sonicnet.com/feature/ari3/ + +@item + facep is not declared. + +@item + Include a section in the manual on why the number of articles +isn't the same in the group buffer and on the SPC prompt. + +@item + Interacting with rmail fcc isn't easy. + +@item +@example + Hypermail: +<URL:http://www.falch.no/people/pepper/DSSSL-Lite/archives/> +<URL:http://www.eit.com/software/hypermail/hypermail.html> +<URL:http://homer.ncm.com/> +<URL:http://www.yahoo.com/Computers_and_Internet/Internet/World_Wide_Web/HTML_Converters/> +http://www.uwsg.indiana.edu/hypermail/linux/kernel/9610/index.html +<URL:http://union.ncsa.uiuc.edu/HyperNews/get/www/html/converters.html> +http://www.miranova.com/gnus-list/ + +@end example + +@item +@samp{^-- } is made into - in LaTeX. + +@item + gnus-kill is much slower than it was in GNUS 4.1.3. + +@item + when expunging articles on low score, the sparse nodes keep hanging on? +@item + starting the first time seems to hang Gnus on some systems. Does +NEWGROUPS answer too fast? +@item + nndir doesn't read gzipped files. +@item + FAQ doesn't have an up node? +@item + when moving mail from a procmail spool to the crash-box, +the crash-box is only appropriate to one specific group. +@item + `t' `t' makes X-Faces disappear. +@item + nnmh-be-safe means that crossposted articles will +be marked as unread. +@item + Orphan score entries don't show on "V t" score trace +@item + when clearing out data, the cache data should also be reset. +@item + rewrite gnus-summary-limit-children to be non-recursive +to avoid exceeding lisp nesting on huge groups. +@item + expunged articles are counted when computing scores. +@item + implement gnus-batch-brew-soup +@item + ticked articles aren't easy to read in pick mode -- `n' and +stuff just skips past them. Read articles are the same. +@item + topics that contain just groups with ticked +articles aren't displayed. +@item + nndoc should always allocate unique Message-IDs. +@item + If there are mail groups the first time you use Gnus, Gnus'll +make the mail groups killed. +@item + no "no news is good news" when using topics. +@item + when doing crosspost marking, the cache has to be consulted +and articles have to be removed. +@item + nnweb should fetch complete articles when they are split into several +parts. +@item + scoring on head immediate doesn't work. +@item + finding short score file names takes forever. +@item + canceling articles in foreign groups. +@item + nntp-open-rlogin no longer works. +@item + C-u C-x C-s (Summary) switches to the group buffer. +@item + move nnmail-split-history out to the backends. +@item + nnweb doesn't work properly. +@item + using a virtual server name as `gnus-select-method' doesn't work? +@item + when killing/yanking a group from one topic to another in a slave, the +master will yank it first to one topic and then add it to another. +Perhaps. + +@item + warn user about `=' redirection of a group in the active file? +@item + really unbinhex binhex files. +@item + take over the XEmacs menubar and offer a toggle between the XEmacs +bar and the Gnus bar. +@item +@example + push active file and NOV file parsing down into C code. +`(canonize-message-id id)' +`(mail-parent-message-id references n)' +`(parse-news-nov-line &optional dependency-hashtb)' +`(parse-news-nov-region beg end &optional dependency-hashtb fullp)' +`(parse-news-active-region beg end hashtb)' + +@end example + +@item + nnml .overview directory with splits. +@item + asynchronous cache +@item + postponed commands. +@item + the selected article show have its Subject displayed in its summary line. +@item + when entering groups, get the real number of unread articles from +the server? +@item + sort after gathering threads -- make false roots have the +headers of the oldest orphan with a 0 article number? +@item + nndoc groups should inherit the score files of their parents? Also +inherit copy prompts and save files. +@item + command to start up Gnus (if not running) and enter a mail mode buffer. +@item + allow editing the group description from the group buffer +for backends that support that. +@item +gnus-hide,show-all-topics +@item + groups and sub-topics should be allowed to mingle inside each topic, +and not just list all subtopics at the end. +@item + a command to remove all read articles that are not needed to connect +threads -- `gnus-summary-limit-to-sparse-unread'? +@item + a variable to turn off limiting/cutting of threads in the tree buffer. +@item + a variable to limit how many files are uudecoded. +@item + add zombie groups to a special "New Groups" topic. +@item + server mode command: close/open all connections +@item + put a file date in gnus-score-alist and check whether the file +has been changed before using it. +@item + on exit from a digest group, go to the next article in the parent group. +@item + hide (sub)threads with low score. +@item + when expiring, remove all marks from expired articles. +@item + gnus-summary-limit-to-body +@item + a regexp alist that says what level groups are to be subscribed +on. Eg. -- `(("nnml:" . 1))'. +@item + easier interface to nnkiboze to create ephemeral groups that +contain groups that match a regexp. +@item + allow newlines in <URL:> urls, but remove them before using +the URL. +@item + If there is no From line, the mail backends should fudge one from the +"From " line. +@item + fuzzy simplifying should strip all non-alpha-numerical info +from subject lines. +@item + gnus-soup-brew-soup-with-high-scores. +@item + nntp-ping-before-connect +@item + command to check whether NOV is evil. "list overview.fmt". +@item + when entering a group, Gnus should look through the score +files very early for `local' atoms and set those local variables. +@item + message annotations. +@item + topics are always yanked before groups, and that's not good. +@item + (set-extent-property extent 'help-echo "String to display in minibuf") +to display help in the minibuffer on buttons under XEmacs. +@item + allow group line format spec to say how many articles there +are in the cache. +@item + AUTHINFO GENERIC +@item + support qmail maildir spools +@item + `run-with-idle-timer' in gnus-demon. +@item + stop using invisible text properties and start using overlays instead +@item + C-c C-f C-e to add an Expires header. +@item + go from one group to the next; everything is expunged; go to the +next group instead of going to the group buffer. +@item + gnus-renumber-cache -- to renumber the cache using "low" numbers. +@item + record topic changes in the dribble buffer. +@item + `nnfolder-generate-active-file' should look at the folders it +finds and generate proper active ranges. +@item + nneething-look-in-files-for-article-heads variable to control +whether nneething should sniff all files in the directories. +@item + gnus-fetch-article -- start Gnus, enter group, display article +@item + gnus-dont-move-articles-to-same-group variable when respooling. +@item + when messages are crossposted between several auto-expirable groups, +articles aren't properly marked as expirable. +@item + nneething should allow deletion/moving. +@item + TAB on the last button should go to the first button. +@item + if the car of an element in `mail-split-methods' is a function, +and the function returns non-nil, use that as the name of the group(s) to +save mail in. +@item + command for listing all score files that have been applied. +@item + a command in the article buffer to return to `summary' config. +@item + `gnus-always-post-using-current-server' -- variable to override +`C-c C-c' when posting. +@item + nnmail-group-spool-alist -- says where each group should use +as a spool file. +@item + when an article is crossposted to an auto-expirable group, the article +should be marker as expirable. +@item + article mode command/menu for "send region as URL to browser". +@item + on errors, jump to info nodes that explain the error. For instance, +on invalid From headers, or on error messages from the nntp server. +@item + when gathering threads, make the article that has no "Re: " the parent. +Also consult Date headers. +@item + a token in splits to call shrink-window-if-larger-than-buffer +@item + `1 0 A M' to do matches on the active hashtb. +@item + duplicates -- command to remove Gnus-Warning header, use the read +Message-ID, delete the "original". +@item + when replying to several messages at once, put the "other" message-ids +into a See-Also header. +@item + support setext: URL:http://www.bsdi.com/setext/ +@item + support ProleText: <URL:http://proletext.clari.net/prole/proletext.html> +@item + when browsing a foreign server, the groups that are already subscribed +should be listed as such and not as "K". +@item + generate font names dynamically. +@item + score file mode auto-alist. +@item + allow nndoc to change/add/delete things from documents. Implement +methods for each format for adding an article to the document. +@item + `gnus-fetch-old-headers' `all' value to incorporate +absolutely all headers there is. +@item + function like `|', but concatenate all marked articles +and pipe them to the process. +@item + cache the list of killed (or active) groups in a separate file. Update +the file whenever we read the active file or the list +of killed groups in the .eld file reaches a certain length. +@item + function for starting to edit a file to put into +the current mail group. +@item + score-find-trace should display the total score of the article. +@item + "ghettozie" -- score on Xref header and nix it out after using it +to avoid marking as read in other groups it has been crossposted to. +@item + look at procmail splitting. The backends should create +the groups automatically if a spool file exists for that group. +@item + function for backends to register themselves with Gnus. +@item + when replying to several process-marked articles, +have all the From end up in Cc headers? Variable to toggle. +@item + command to delete a crossposted mail article from all +groups it has been mailed to. +@item + `B c' and `B m' should be crosspost aware. +@item + hide-pgp should also hide PGP public key blocks. +@item + Command in the group buffer to respool process-marked groups. +@item + `gnus-summary-find-matching' should accept +pseudo-"headers" like "body", "head" and "all" +@item + When buttifying <URL: > things, all white space (including +newlines) should be ignored. +@item + Process-marking all groups in a topic should process-mark +groups in subtopics as well. +@item + Add non-native groups to the list of killed groups when killing them. +@item + nntp-suggest-kewl-config to probe the nntp server and suggest +variable settings. +@item + add edit and forward secondary marks. +@item + nnml shouldn't visit its .overview files. +@item + allow customizing sorting within gathered threads. +@item + `B q' shouldn't select the current article. +@item + nnmbox should support a newsgroups file for descriptions. +@item + allow fetching mail from several pop servers. +@item + Be able to specify whether the saving commands save the original +or the formatted article. +@item + a command to reparent with the child process-marked (cf. `T ^'.). +@item + I think the possibility to send a password with nntp-open-rlogin +should be a feature in Red Gnus. +@item + The `Z n' command should be possible to execute from a mouse click. +@item + more limiting functions -- date, etc. +@item + be able to limit on a random header; on body; using reverse matches. +@item + a group parameter (`absofucking-total-expiry') that will make Gnus expire +even unread articles. +@item + a command to print the article buffer as postscript. +@item + variable to disable password fetching when opening by nntp-open-telnet. +@item + manual: more example servers -- nntp with rlogin, telnet +@item + checking for bogus groups should clean topic alists as well. +@item + canceling articles in foreign groups. +@item + article number in folded topics isn't properly updated by +Xref handling. +@item + Movement in the group buffer to the next unread group should go to the +next closed topic with unread messages if no group can be found. +@item + Extensive info pages generated on the fly with help everywhere -- +in the "*Gnus edit*" buffers, for instance. +@item + Topic movement commands -- like thread movement. Up, down, forward, next. +@item + a way to tick/mark as read Gcc'd articles. +@item + a way to say that all groups within a specific topic comes +from a particular server? Hm. +@item + `gnus-article-fill-if-long-lines' -- a function to fill +the article buffer if there are any looong lines there. +@item + `T h' should jump to the parent topic and fold it. +@item + a command to create an ephemeral nndoc group out of a file, +and then splitting it/moving it to some other group/backend. +@item + a group parameter for nnkiboze groups that says that +all kibozed articles should be entered into the cache. +@item + It should also probably be possible to delimit what +`gnus-jog-cache' does -- for instance, work on just some groups, or on +some levels, and entering just articles that have a score higher than +a certain number. +@item + nnfolder should append to the folder instead of re-writing +the entire folder to disk when accepting new messages. +@item + allow all backends to do the proper thing with .gz files. +@item + a backend for reading collections of babyl files nnbabylfolder? +@item + a command for making the native groups into foreign groups. +@item + server mode command for clearing read marks from all groups +from a server. +@item + when following up multiple articles, include all To, Cc, etc headers +from all articles. +@item + a command for deciding what the total score of the current +thread is. Also a way to highlight based on this. +@item + command to show and edit group scores +@item + a gnus-tree-minimize-horizontal to minimize tree buffers +horizontally. +@item + command to generate nnml overview file for one group. +@item + `C-u C-u a' -- prompt for many crossposted groups. +@item + keep track of which mail groups have received new articles (in this session). +Be able to generate a report and perhaps do some marking in the group +buffer. +@item + gnus-build-sparse-threads to a number -- build only sparse threads +that are of that length. +@item + have nnmh respect mh's unseen sequence in .mh_profile. +@item + cache the newsgroups descriptions locally. +@item + asynchronous posting under nntp. +@item + be able to control word adaptive scoring from the score files. +@item + a variable to make `C-c C-c' post using the "current" select method. +@item + `limit-exclude-low-scored-articles'. +@item + if `gnus-summary-show-thread' is a number, hide threads that have +a score lower than this number. +@item + split newsgroup subscription variable up into "order" and "method". +@item + buttonize ange-ftp file names. +@item + a command to make a duplicate copy of the current article +so that each copy can be edited separately. +@item + nnweb should allow fetching from the local nntp server. +@item + record the sorting done in the summary buffer so that +it can be repeated when limiting/regenerating the buffer. +@item + nnml-generate-nov-databses should generate for +all nnml servers. +@item + when the user does commands in the group buffer, check +the modification time of the .newsrc.eld file and use +ask-user-about-supersession-threat. Also warn when trying +to save .newsrc.eld and it has changed. +@item + M-g on a topic will display all groups with 0 articles in +the topic. +@item + command to remove all topic stuff. +@item + allow exploding incoming digests when reading incoming mail +and splitting the resulting digests. +@item + nnsoup shouldn't set the `message-' variables. +@item + command to nix out all nnoo state information. +@item + nnmail-process-alist that calls functions if group names +matches an alist -- before saving. +@item + use buffer-invisibility-spec everywhere for hiding text. +@item + variable to activate each group before entering them +to get the (new) number of articles. `gnus-activate-before-entering'. +@item + command to fetch a Message-ID from any buffer, even +starting Gnus first if necessary. +@item + when posting and checking whether a group exists or not, just +ask the nntp server instead of relying on the active hashtb. +@item + buttonize the output of `C-c C-a' in an apropos-like way. +@item + `G p' should understand process/prefix, and allow editing +of several groups at once. +@item + command to create an ephemeral nnvirtual group that +matches some regexp(s). +@item + nndoc should understand "Content-Type: message/rfc822" forwarded messages. +@item + it should be possible to score "thread" on the From header. +@item + hitting RET on a "gnus-uu-archive" pseudo article should unpack it. +@item + `B i' should display the article at once in the summary buffer. +@item + remove the "*" mark at once when unticking an article. +@item + `M-s' should highlight the matching text. +@item + when checking for duplicated mails, use Resent-Message-ID if present. +@item + killing and yanking groups in topics should be better. If killing one copy +of a group that exists in multiple topics, only that copy should +be removed. Yanking should insert the copy, and yanking topics +should be possible to be interspersed with the other yankings. +@item + command for enter a group just to read the cached articles. A way to say +"ignore the nntp connection; just read from the cache." +@item + `X u' should decode base64 articles. +@item + a way to hide all "inner" cited text, leaving just the most +recently cited text. +@item + nnvirtual should be asynchronous. +@item + after editing an article, gnus-original-article-buffer should +be invalidated. +@item + there should probably be a way to make Gnus not connect to the +server and just read the articles in the server +@item + allow a `set-default' (or something) to change the default +value of nnoo variables. +@item + a command to import group infos from a .newsrc.eld file. +@item + groups from secondary servers have the entire select method +listed in each group info. +@item + a command for just switching from the summary buffer to the group +buffer. +@item + a way to specify that some incoming mail washing functions +should only be applied to some groups. +@item + Message `C-f C-t' should ask the user whether to heed +mail-copies-to: never. +@item + new group parameter -- `post-to-server' that says to post +using the current server. Also a variable to do the same. +@item + the slave dribble files should autosave to the slave file names. +@item + a group parameter that says what articles to display on group entry, based +on article marks. +@item + a way to visually distinguish slave Gnusae from masters. (Whip instead +of normal logo?) +@item + Use DJ Bernstein "From " quoting/dequoting, where applicable. +@item + Why is hide-citation-maybe and hide-citation different? Also +clear up info. +@item + group user-defined meta-parameters. + + + +From: John Griffith <griffith@@sfs.nphil.uni-tuebingen.de> +@item + I like the option for trying to retrieve the FAQ for a group and I was +thinking it would be great if for those newsgroups that had archives +you could also try to read the archive for that group. Part of the +problem is that archives are spread all over the net, unlike FAQs. +What would be best I suppose is to find the one closest to your site. + +In any case, there is a list of general news group archives at @* +ftp://ftp.neosoft.com/pub/users/claird/news.lists/newsgroup_archives.html + + + + +@item +@example +From: Jason L Tibbitts III <tibbs@@hpc.uh.edu> +(add-hook 'gnus-select-group-hook + (lambda () + (gnus-group-add-parameter group + (cons 'gnus-group-date-last-entered (list (current-time-string)))))) + +(defun gnus-user-format-function-d (headers) + "Return the date the group was last read." + (cond ((car (gnus-group-get-parameter gnus-tmp-group 'gnus-group-date-last-entered))) + (t ""))) +@end example + +@item + tanken var at når du bruker `gnus-startup-file' som prefix (FOO) til å lete +opp en fil FOO-SERVER, FOO-SERVER.el, FOO-SERVER.eld, kan du la den være en +liste hvor du bruker hvert element i listen som FOO, istedet. da kunne man +hatt forskjellige serveres startup-filer forskjellige steder. + + +@item +LMI> Well, nnbabyl could alter the group info to heed labels like +LMI> answered and read, I guess. + +It could also keep them updated (the same for the Status: header of +unix mbox files). + +They could be used like this: + + +@example +`M l <name> RET' add label <name> to current message. +`M u <name> RET' remove label <name> from current message. +`/ l <expr> RET' limit summary buffer according to <expr>. + +<expr> would be a boolean expression on the labels, e.g. + +`/ l bug & !fixed RET' +@end example + +would show all the messages which are labeled `bug' but not labeled +`fixed'. + +One could also imagine the labels being used for highlighting, or +affect the summary line format. + + +@item +Sender: abraham@@dina.kvl.dk + +I'd like a gnus-find-file which work like find file, except that it +would recognize things that looks like messages or folders: + +- If it is a directory containing numbered files, create an nndir +summary buffer. + +- For other directories, create a nneething summary buffer. + +- For files matching "\\`From ", create a nndoc/mbox summary. + +- For files matching "\\`BABYL OPTIONS:", create a nndoc/baby summary. + +- For files matching "\\`[^ \t\n]+:", create an *Article* buffer. + +- For other files, just find them normally. + +I'd like `nneething' to use this function, so it would work on a +directory potentially containing mboxes or babyl files. + +@item +Please send a mail to bwarsaw@@cnri.reston.va.us (Barry A. Warsaw) and +tell him what you are doing. + +@item +Currently, I get prompted: + +decend into sci? +- type y +decend into sci.something ? +- type n +decend into ucd? + +The problem above is that since there is really only one subsection of +science, shouldn't it prompt you for only descending sci.something? If +there was a sci.somethingelse group or section, then it should prompt +for sci? first the sci.something? then sci.somethingelse?... + +@item +Ja, det burde være en måte å si slikt. Kanskje en ny variabel? +`gnus-use-few-score-files'? Så kunne score-regler legges til den +"mest" lokale score-fila. F. eks. ville no-gruppene betjenes av +"no.all.SCORE", osv. + +@item +What i want is for Gnus to treat any sequence or combination of the following +as a single spoiler warning and hide it all, replacing it with a "Next Page" +button: + + +^L's + +more than n blank lines + +more than m identical lines +(which should be replaced with button to show them) + +any whitespace surrounding any of the above + + +@item +Well, we could allow a new value to `gnus-thread-ignore-subject' -- +`spaces', or something. (We could even default to that.) And then +subjects that differ in white space only could be considered the +"same" subject for threading purposes. + +@item +Modes to preprocess the contents (e.g. jka-compr) use the second form +"(REGEXP FUNCTION NON-NIL)" while ordinary modes (e.g. tex) use the first +form "(REGEXP . FUNCTION)", so you could use it to distinguish between +those two types of modes. (auto-modes-alist, insert-file-contents-literally.) + +@item + Under XEmacs -- do funny article marks: +tick - thumb tack +killed - skull +soup - bowl of soup +score below - dim light bulb +score over - bright light bulb + +@item +Yes. I think the algorithm is as follows: + +@example +Group-mode + + show-list-of-articles-in-group + if (key-pressed == SPACE) + if (no-more-articles-in-group-to-select) + if (articles-selected) + start-reading-selected-articles; + junk-unread-articles; + next-group; + else + show-next-page; + + else if (key-pressed = '.') + if (consolidated-menus) # same as hide-thread in Gnus + select-thread-under-cursor; + else + select-article-under-cursor; + + +Article-mode + if (key-pressed == SPACE) + if (more-pages-in-article) + next-page; + else if (more-selected-articles-to-read) + next-article; + else + next-group; +@end example + +@item +My precise need here would have been to limit files to Incoming*. +One could think of some `nneething-only-files' variable, but I guess +it would have been unacceptable if one was using many unrelated such +nneething groups. + +A more useful approach would be to, in response to the `G D' prompt, be +allowed to say something like: `~/.mail/Incoming*', somewhat limiting +the top-level directory only (in case directories would be matched by +the wildcard expression). + +@item +It would be nice if it also handled + + <URL:news://sunsite.auc.dk/> + +which should correspond to `B nntp RET sunsite.auc.dk' in *Group*. + + +@item + + Take a look at w3-menu.el in the Emacs-W3 distribution - this works out +really well. Each menu is 'named' by a symbol that would be on a +gnus-*-menus (where * would be whatever, but at least group, summary, and +article versions) variable. + + So for gnus-summary-menus, I would set to '(sort mark dispose ...) + + A value of '1' would just put _all_ the menus in a single 'GNUS' menu in +the main menubar. This approach works really well for Emacs-W3 and VM. + + +@item + nndoc should take care to create unique Message-IDs for all its +articles. +@item + gnus-score-followup-article only works when you have a summary buffer +active. Make it work when posting from the group buffer as well. +(message-sent-hook). +@item + rewrite gnus-demon to use run-with-idle-timers. + +@item + * Enhancements to Gnus: + + Add two commands: + + * gnus-servers (gnus-start-server-buffer?)--enters Gnus and goes + straight to the server buffer, without opening any connections to + servers first. + + * gnus-server-read-server-newsrc--produces a buffer very similar to + the group buffer, but with only groups from that server listed; + quitting this buffer returns to the server buffer. + +@item + add a command to check the integrity of an nnfolder folder -- +go through the article numbers and see that there are no duplicates, +and stuff. + +@item + `unsmileyfy-buffer' to undo smileification. + +@item + a command to give all relevant info on an article, including all +secondary marks. + +@item + when doing `-request-accept-article', the backends should do +the nnmail duplicate checking. + +@item + allow `message-signature-file' to be a function to return the +value of the signature file. + +@item + In addition, I would love it if I could configure message-tab so that it +could call `bbdb-complete-name' in other headers. So, some sort of +interface like + +(setq message-tab-alist + '((message-header-regexp message-expand-group) + ("^\\(To\\|[cC]c\\|[bB]cc\\)" bbdb-complete-name))) + +then you could run the relevant function to complete the information in +the header + +@item + cache the newsgroups file locally to avoid reloading it all the time. + +@item + a command to import a buffer into a group. + +@item + nnweb should allow fetching by Message-ID from servers. + +@item + point in the article buffer doesn't always go to the +beginning of the buffer when selecting new articles. + +@item + a command to process mark all unread articles. + +@item + `gnus-gather-threads-by-references-and-subject' -- first +do gathering by references, and then go through the dummy roots and +do more gathering by subject. + +@item + gnus-uu-mark-in-numerical-order -- process mark articles in +article numerical order. + +@item + (gnus-thread-total-score + (gnus-id-to-thread (mail-header-id (gnus-summary-article-header)))) +bind to a key. + +@item + sorting by score is wrong when using sparse threads. + +@item + a command to fetch an arbitrary article -- without having to be +in the summary buffer. + +@item + a new nncvs backend. Each group would show an article, using +version branches as threading, checkin date as the date, etc. + +@item + http://www.dejanews.com/forms/dnsetfilter_exp.html ? +This filter allows one to construct advance queries on the Dejanews +database such as specifying start and end dates, subject, author, +and/or newsgroup name. + +@item + new Date header scoring type -- older, newer + +@item + use the summary toolbar in the article buffer. + +@item + a command to fetch all articles that are less than X days old. + +@item + in pick mode, `q' should save the list of selected articles in the +group info. The next time the group is selected, these articles +will automatically get the process mark. + +@item + Isn't it possible to (also?) allow M-^ to automatically try the +default server if it fails on the current server? (controlled by a +user variable, (nil, t, 'ask)). + +@item + make it possible to cancel articles using the select method for the +current group. + +@item + `gnus-summary-select-article-on-entry' or something. It'll default +to t and will select whatever article decided by `gnus-auto-select-first'. + +@item + a new variable to control which selection commands should be unselecting. +`first', `best', `next', `prev', `next-unread', `prev-unread' are +candidates. + +@item + be able to select groups that have no articles in them +to be able to post in them (using the current select method). + +@item + be able to post via DejaNews. + +@item + `x' should retain any sortings that have been performed. + +@item + allow the user to specify the precedence of the secondary marks. Also +allow them to be displayed separately. + +@item + gnus-summary-save-in-pipe should concatenate the results from +the processes when doing a process marked pipe. + +@item + a new match type, like Followup, but which adds Thread matches on all +articles that match a certain From header. + +@item + a function that can be read from kill-emacs-query-functions to offer +saving living summary buffers. + +@item + a function for selecting a particular group which will contain +the articles listed in a list of article numbers/id's. + +@item + a battery of character translation functions to translate common +Mac, MS (etc) characters into ISO 8859-1. + +@example +(defun article-fix-m$word () + "Fix M$Word smartquotes in an article." + (interactive) + (save-excursion + (let ((buffer-read-only nil)) + (goto-char (point-min)) + (while (search-forward "\221" nil t) + (replace-match "`" t t)) + (goto-char (point-min)) + (while (search-forward "\222" nil t) + (replace-match "'" t t)) + (goto-char (point-min)) + (while (search-forward "\223" nil t) + (replace-match "\"" t t)) + (goto-char (point-min)) + (while (search-forward "\224" nil t) + (replace-match "\"" t t))))) +@end example + +@item +@example + (add-hook 'gnus-exit-query-functions +'(lambda () + (if (and (file-exists-p nnmail-spool-file) + (> (nnheader-file-size nnmail-spool-file) 0)) + (yes-or-no-p "New mail has arrived. Quit Gnus anyways? ") + (y-or-n-p "Are you sure you want to quit Gnus? ")))) +@end example + +@item + allow message-default-headers to be a function. + +@item + new Date score match types -- < > = (etc) that take floating point +numbers and match on the age of the article. + +@item +@example +> > > If so, I've got one gripe: It seems that when I fire up gnus 5.2.25 +> > > under xemacs-19.14, it's creating a new frame, but is erasing the +> > > buffer in the frame that it was called from =:-O +> +> > Hm. How do you start up Gnus? From the toolbar or with +> > `M-x gnus-other-frame'? +> +> I normally start it up from the toolbar; at +> least that's the way I've caught it doing the +> deed before. +@end example + +@item + all commands that react to the process mark should push +the current process mark set onto the stack. + +@item + gnus-article-hide-pgp +Selv ville jeg nok ha valgt å slette den dersom teksten matcher +@example +"\\(This\s+\\)?[^ ]+ has been automatically signed by" +@end example +og det er maks hundre tegn mellom match-end og ----linja. Men -det- +er min type heuristikk og langt fra alles. + +@item + `gnus-subscribe-sorted' -- insert new groups where they would have been +sorted to if `gnus-group-sort-function' were run. + +@item + gnus-(group,summary)-highlight should respect any `face' text props set +on the lines. + +@item + use run-with-idle-timer for gnus-demon instead of the +home-brewed stuff for better reliability. + +@item + add a way to select which NoCeM type to apply -- spam, troll, etc. + +@item + nndraft-request-group should tally autosave files. + +@item + implement nntp-retry-on-break and nntp-command-timeout. + +@item + gnus-article-highlight-limit that says when not to highlight (long) +articles. + +@item + (nnoo-set SERVER VARIABLE VALUE) + +@item + nn*-spool-methods + +@item + interrupitng agent fetching of articles should save articles. + +@item + command to open a digest group, and copy all the articles there to the +current group. + +@item + a variable to disable article body highlights if there's more than +X characters in the body. + +@item + handle 480/381 authinfo requests separately. + +@item + include the texi/dir file in the distribution. + +@item + format spec to "tab" to a position. + +@item + Move all prompting to the new `M-n' default style. + +@item + command to display all dormant articles. + +@item + gnus-auto-select-next makeover -- list of things it should do. + +@item + a score match type that adds scores matching on From if From has replied +to something someone else has said. + +@item + Read Netscape discussion groups: +snews://secnews.netscape.com/netscape.communicator.unix + +@item +One command to edit the original version if an article, and one to edit +the displayed version. + +@item +@kbd{T v} -- make all process-marked articles the children of the +current article. + +@item +Switch from initial text to the new default text mechanism. + +@item +How about making it possible to expire local articles? Will it be +possible to make various constraints on when an article can be +expired, e.g. (read), (age > 14 days), or the more interesting (read +& age > 14 days)? + +@item +New limit command---limit to articles that have a certain string +in the head or body. + +@item +Allow breaking lengthy NNTP commands. + +@item +gnus-article-highlight-limit, to disable highlighting in big articles. + +@item +Editing an article should put the article to be edited +in a special, unique buffer. + +@item +A command to send a mail to the admin-address group param. + +@item +A Date scoring type that will match if the article +is less than a certain number of days old. + +@item +New spec: %~(tab 56) to put point on column 56 + +@item +Allow Gnus Agent scoring to use normal score files. + +@item +Rething the Agent active file thing. `M-g' doesn't update the active +file, for instance. + +@item +With dummy roots, `^' and then selecing the first article +in any other dummy thread will make Gnus highlight the +dummy root instead of the first article. + +@item +Propagate all group properties (marks, article numbers, etc) up to the +topics for displaying. + +@item +`n' in the group buffer with topics should go to the next group +with unread articles, even if that group is hidden in a topic. + +@item +gnus-posting-styles doesn't work in drafts. + +@item +gnus-summary-limit-include-cached is slow when there are +many articles in the cache, since it regenerates big parts of the +summary buffer for each article. + +@item +Implement gnus-batch-brew-soup. + +@item +Group parameters and summary commands for un/subscribing to mailing +lists. + +@item +Introduce nnmail-home-directory. + +@item +gnus-fetch-group and friends should exit Gnus when the user +exits the group. + +@item +Solve the halting problem. + +@c TODO +@end itemize + +@iftex + +@page +@node The Manual +@section The Manual +@cindex colophon +@cindex manual + +This manual was generated from a TeXinfo file and then run through +either @code{texi2dvi} +to get what you hold in your hands now. + +The following conventions have been used: + +@enumerate + +@item +This is a @samp{string} + +@item +This is a @kbd{keystroke} + +@item +This is a @file{file} + +@item +This is a @code{symbol} + +@end enumerate + +So if I were to say ``set @code{flargnoze} to @samp{yes}'', that would +mean: + +@lisp +(setq flargnoze "yes") +@end lisp + +If I say ``set @code{flumphel} to @code{yes}'', that would mean: + +@lisp +(setq flumphel 'yes) +@end lisp + +@samp{yes} and @code{yes} are two @emph{very} different things---don't +ever get them confused. + + +@end iftex + + +@page +@node Terminology +@section Terminology + +@cindex terminology +@table @dfn + +@item news +@cindex news +This is what you are supposed to use this thing for---reading news. +News is generally fetched from a nearby @sc{nntp} server, and is +generally publicly available to everybody. If you post news, the entire +world is likely to read just what you have written, and they'll all +snigger mischievously. Behind your back. + +@item mail +@cindex mail +Everything that's delivered to you personally is mail. Some news/mail +readers (like Gnus) blur the distinction between mail and news, but +there is a difference. Mail is private. News is public. Mailing is +not posting, and replying is not following up. + +@item reply +@cindex reply +Send a mail to the person who has written what you are reading. + +@item follow up +@cindex follow up +Post an article to the current newsgroup responding to the article you +are reading. + +@item backend +@cindex backend +Gnus gets fed articles from a number of backends, both news and mail +backends. Gnus does not handle the underlying media, so to speak---this +is all done by the backends. + +@item native +@cindex native +Gnus will always use one method (and backend) as the @dfn{native}, or +default, way of getting news. + +@item foreign +@cindex foreign +You can also have any number of foreign groups active at the same time. +These are groups that use non-native non-secondary backends for getting +news. + +@item secondary +@cindex secondary +Secondary backends are somewhere half-way between being native and being +foreign, but they mostly act like they are native. + +@item article +@cindex article +A message that has been posted as news. + +@item mail message +@cindex mail message +A message that has been mailed. + +@item message +@cindex message +A mail message or news article + +@item head +@cindex head +The top part of a message, where administrative information (etc.) is +put. + +@item body +@cindex body +The rest of an article. Everything not in the head is in the +body. + +@item header +@cindex header +A line from the head of an article. + +@item headers +@cindex headers +A collection of such lines, or a collection of heads. Or even a +collection of @sc{nov} lines. + +@item @sc{nov} +@cindex nov +When Gnus enters a group, it asks the backend for the headers of all +unread articles in the group. Most servers support the News OverView +format, which is more compact and much faster to read and parse than the +normal @sc{head} format. + +@item level +@cindex levels +Each group is subscribed at some @dfn{level} or other (1-9). The ones +that have a lower level are ``more'' subscribed than the groups with a +higher level. In fact, groups on levels 1-5 are considered +@dfn{subscribed}; 6-7 are @dfn{unsubscribed}; 8 are @dfn{zombies}; and 9 +are @dfn{killed}. Commands for listing groups and scanning for new +articles will all use the numeric prefix as @dfn{working level}. + +@item killed groups +@cindex killed groups +No information on killed groups is stored or updated, which makes killed +groups much easier to handle than subscribed groups. + +@item zombie groups +@cindex zombie groups +Just like killed groups, only slightly less dead. + +@item active file +@cindex active file +The news server has to keep track of what articles it carries, and what +groups exist. All this information in stored in the active file, which +is rather large, as you might surmise. + +@item bogus groups +@cindex bogus groups +A group that exists in the @file{.newsrc} file, but isn't known to the +server (i.e., it isn't in the active file), is a @emph{bogus group}. +This means that the group probably doesn't exist (any more). + +@item activating +@cindex activating groups +The act of asking the server for info on a group and computing the +number of unread articles is called @dfn{activating the group}. +Un-activated groups are listed with @samp{*} in the group buffer. + +@item server +@cindex server +A machine one can connect to and get news (or mail) from. + +@item select method +@cindex select method +A structure that specifies the backend, the server and the virtual +server settings. + +@item virtual server +@cindex virtual server +A named select method. Since a select method defines all there is to +know about connecting to a (physical) server, taking the thing as a +whole is a virtual server. + +@item washing +@cindex washing +Taking a buffer and running it through a filter of some sort. The +result will (more often than not) be cleaner and more pleasing than the +original. + +@item ephemeral groups +@cindex ephemeral groups +Most groups store data on what articles you have read. @dfn{Ephemeral} +groups are groups that will have no data stored---when you exit the +group, it'll disappear into the aether. + +@item solid groups +@cindex solid groups +This is the opposite of ephemeral groups. All groups listed in the +group buffer are solid groups. + +@item sparse articles +@cindex sparse articles +These are article placeholders shown in the summary buffer when +@code{gnus-build-sparse-threads} has been switched on. + +@item threading +@cindex threading +To put responses to articles directly after the articles they respond +to---in a hierarchical fashion. + +@item root +@cindex root +@cindex thread root +The first article in a thread is the root. It is the ancestor of all +articles in the thread. + +@item parent +@cindex parent +An article that has responses. + +@item child +@cindex child +An article that responds to a different article---its parent. + +@item digest +@cindex digest +A collection of messages in one file. The most common digest format is +specified by RFC1153. + +@end table + + +@page +@node Customization +@section Customization +@cindex general customization + +All variables are properly documented elsewhere in this manual. This +section is designed to give general pointers on how to customize Gnus +for some quite common situations. + +@menu +* Slow/Expensive Connection:: You run a local Emacs and get the news elsewhere. +* Slow Terminal Connection:: You run a remote Emacs. +* Little Disk Space:: You feel that having large setup files is icky. +* Slow Machine:: You feel like buying a faster machine. +@end menu + + +@node Slow/Expensive Connection +@subsection Slow/Expensive @sc{nntp} Connection + +If you run Emacs on a machine locally, and get your news from a machine +over some very thin strings, you want to cut down on the amount of data +Gnus has to get from the @sc{nntp} server. + +@table @code + +@item gnus-read-active-file +Set this to @code{nil}, which will inhibit Gnus from requesting the +entire active file from the server. This file is often v. large. You +also have to set @code{gnus-check-new-newsgroups} and +@code{gnus-check-bogus-newsgroups} to @code{nil} to make sure that Gnus +doesn't suddenly decide to fetch the active file anyway. + +@item gnus-nov-is-evil +This one has to be @code{nil}. If not, grabbing article headers from +the @sc{nntp} server will not be very fast. Not all @sc{nntp} servers +support @sc{xover}; Gnus will detect this by itself. +@end table + + +@node Slow Terminal Connection +@subsection Slow Terminal Connection + +Let's say you use your home computer for dialing up the system that runs +Emacs and Gnus. If your modem is slow, you want to reduce (as much as +possible) the amount of data sent over the wires. + +@table @code + +@item gnus-auto-center-summary +Set this to @code{nil} to inhibit Gnus from re-centering the summary +buffer all the time. If it is @code{vertical}, do only vertical +re-centering. If it is neither @code{nil} nor @code{vertical}, do both +horizontal and vertical recentering. + +@item gnus-visible-headers +Cut down on the headers included in the articles to the +minimum. You can, in fact, make do without them altogether---most of the +useful data is in the summary buffer, anyway. Set this variable to +@samp{^NEVVVVER} or @samp{From:}, or whatever you feel you need. + +@item gnus-article-display-hook +Set this hook to all the available hiding commands: +@lisp +(setq gnus-article-display-hook + '(gnus-article-hide-headers + gnus-article-hide-signature + gnus-article-hide-citation)) +@end lisp + +@item gnus-use-full-window +By setting this to @code{nil}, you can make all the windows smaller. +While this doesn't really cut down much generally, it means that you +have to see smaller portions of articles before deciding that you didn't +want to read them anyway. + +@item gnus-thread-hide-subtree +If this is non-@code{nil}, all threads in the summary buffer will be +hidden initially. + +@item gnus-updated-mode-lines +If this is @code{nil}, Gnus will not put information in the buffer mode +lines, which might save some time. +@end table + + +@node Little Disk Space +@subsection Little Disk Space +@cindex disk space + +The startup files can get rather large, so you may want to cut their +sizes a bit if you are running out of space. + +@table @code + +@item gnus-save-newsrc-file +If this is @code{nil}, Gnus will never save @file{.newsrc}---it will +only save @file{.newsrc.eld}. This means that you will not be able to +use any other newsreaders than Gnus. This variable is @code{t} by +default. + +@item gnus-save-killed-list +If this is @code{nil}, Gnus will not save the list of dead groups. You +should also set @code{gnus-check-new-newsgroups} to @code{ask-server} +and @code{gnus-check-bogus-newsgroups} to @code{nil} if you set this +variable to @code{nil}. This variable is @code{t} by default. + +@end table + + +@node Slow Machine +@subsection Slow Machine +@cindex slow machine + +If you have a slow machine, or are just really impatient, there are a +few things you can do to make Gnus run faster. + +Set @code{gnus-check-new-newsgroups} and +@code{gnus-check-bogus-newsgroups} to @code{nil} to make startup faster. + +Set @code{gnus-show-threads}, @code{gnus-use-cross-reference} and +@code{gnus-nov-is-evil} to @code{nil} to make entering and exiting the +summary buffer faster. + +Set @code{gnus-article-display-hook} to @code{nil} to make article +processing a bit faster. + + +@page +@node Troubleshooting +@section Troubleshooting +@cindex troubleshooting + +Gnus works @emph{so} well straight out of the box---I can't imagine any +problems, really. + +Ahem. + +@enumerate + +@item +Make sure your computer is switched on. + +@item +Make sure that you really load the current Gnus version. If you have +been running @sc{gnus}, you need to exit Emacs and start it up again before +Gnus will work. + +@item +Try doing an @kbd{M-x gnus-version}. If you get something that looks +like @samp{Gnus v5.46; nntp 4.0} you have the right files loaded. If, +on the other hand, you get something like @samp{NNTP 3.x} or @samp{nntp +flee}, you have some old @file{.el} files lying around. Delete these. + +@item +Read the help group (@kbd{G h} in the group buffer) for a FAQ and a +how-to. + +@item +@vindex max-lisp-eval-depth +Gnus works on many recursive structures, and in some extreme (and very +rare) cases Gnus may recurse down ``too deeply'' and Emacs will beep at +you. If this happens to you, set @code{max-lisp-eval-depth} to 500 or +something like that. +@end enumerate + +If all else fails, report the problem as a bug. + +@cindex bugs +@cindex reporting bugs + +@kindex M-x gnus-bug +@findex gnus-bug +If you find a bug in Gnus, you can report it with the @kbd{M-x gnus-bug} +command. @kbd{M-x set-variable RET debug-on-error RET t RET}, and send +me the backtrace. I will fix bugs, but I can only fix them if you send +me a precise description as to how to reproduce the bug. + +You really can never be too detailed in a bug report. Always use the +@kbd{M-x gnus-bug} command when you make bug reports, even if it creates +a 10Kb mail each time you use it, and even if you have sent me your +environment 500 times before. I don't care. I want the full info each +time. + +It is also important to remember that I have no memory whatsoever. If +you send a bug report, and I send you a reply, and then you just send +back ``No, it's not! Moron!'', I will have no idea what you are +insulting me about. Always over-explain everything. It's much easier +for all of us---if I don't have all the information I need, I will just +mail you and ask for more info, and everything takes more time. + +If the problem you're seeing is very visual, and you can't quite explain +it, copy the Emacs window to a file (with @code{xwd}, for instance), put +it somewhere it can be reached, and include the URL of the picture in +the bug report. + +If you just need help, you are better off asking on +@samp{gnu.emacs.gnus}. I'm not very helpful. + +@cindex gnu.emacs.gnus +@cindex ding mailing list +You can also ask on the ding mailing list---@samp{ding@@gnus.org}. +Write to @samp{ding-request@@gnus.org} to subscribe. + + +@page +@node A Programmers Guide to Gnus +@section A Programmer@'s Guide to Gnus + +It is my hope that other people will figure out smart stuff that Gnus +can do, and that other people will write those smart things as well. To +facilitate that I thought it would be a good idea to describe the inner +workings of Gnus. And some of the not-so-inner workings, while I'm at +it. + +You can never expect the internals of a program not to change, but I +will be defining (in some details) the interface between Gnus and its +backends (this is written in stone), the format of the score files +(ditto), data structures (some are less likely to change than others) +and general methods of operation. + +@menu +* Gnus Utility Functions:: Common functions and variable to use. +* Backend Interface:: How Gnus communicates with the servers. +* Score File Syntax:: A BNF definition of the score file standard. +* Headers:: How Gnus stores headers internally. +* Ranges:: A handy format for storing mucho numbers. +* Group Info:: The group info format. +* Extended Interactive:: Symbolic prefixes and stuff. +* Emacs/XEmacs Code:: Gnus can be run under all modern Emacsen. +* Various File Formats:: Formats of files that Gnus use. +@end menu + + +@node Gnus Utility Functions +@subsection Gnus Utility Functions +@cindex Gnus utility functions +@cindex utility functions +@cindex functions +@cindex internal variables + +When writing small functions to be run from hooks (and stuff), it's +vital to have access to the Gnus internal functions and variables. +Below is a list of the most common ones. + +@table @code + +@item gnus-newsgroup-name +@vindex gnus-newsgroup-name +This variable holds the name of the current newsgroup. + +@item gnus-find-method-for-group +@findex gnus-find-method-for-group +A function that returns the select method for @var{group}. + +@item gnus-group-real-name +@findex gnus-group-real-name +Takes a full (prefixed) Gnus group name, and returns the unprefixed +name. + +@item gnus-group-prefixed-name +@findex gnus-group-prefixed-name +Takes an unprefixed group name and a select method, and returns the full +(prefixed) Gnus group name. + +@item gnus-get-info +@findex gnus-get-info +Returns the group info list for @var{group}. + +@item gnus-group-unread +@findex gnus-group-unread +The number of unread articles in @var{group}, or @code{t} if that is +unknown. + +@item gnus-active +@findex gnus-active +The active entry for @var{group}. + +@item gnus-set-active +@findex gnus-set-active +Set the active entry for @var{group}. + +@item gnus-add-current-to-buffer-list +@findex gnus-add-current-to-buffer-list +Adds the current buffer to the list of buffers to be killed on Gnus +exit. + +@item gnus-continuum-version +@findex gnus-continuum-version +Takes a Gnus version string as a parameter and returns a floating point +number. Earlier versions will always get a lower number than later +versions. + +@item gnus-group-read-only-p +@findex gnus-group-read-only-p +Says whether @var{group} is read-only or not. + +@item gnus-news-group-p +@findex gnus-news-group-p +Says whether @var{group} came from a news backend. + +@item gnus-ephemeral-group-p +@findex gnus-ephemeral-group-p +Says whether @var{group} is ephemeral or not. + +@item gnus-server-to-method +@findex gnus-server-to-method +Returns the select method corresponding to @var{server}. + +@item gnus-server-equal +@findex gnus-server-equal +Says whether two virtual servers are equal. + +@item gnus-group-native-p +@findex gnus-group-native-p +Says whether @var{group} is native or not. + +@item gnus-group-secondary-p +@findex gnus-group-secondary-p +Says whether @var{group} is secondary or not. + +@item gnus-group-foreign-p +@findex gnus-group-foreign-p +Says whether @var{group} is foreign or not. + +@item group-group-find-parameter +@findex group-group-find-parameter +Returns the parameter list of @var{group}. If given a second parameter, +returns the value of that parameter for @var{group}. + +@item gnus-group-set-parameter +@findex gnus-group-set-parameter +Takes three parameters; @var{group}, @var{parameter} and @var{value}. + +@item gnus-narrow-to-body +@findex gnus-narrow-to-body +Narrows the current buffer to the body of the article. + +@item gnus-check-backend-function +@findex gnus-check-backend-function +Takes two parameters, @var{function} and @var{group}. If the backend +@var{group} comes from supports @var{function}, return non-@code{nil}. + +@lisp +(gnus-check-backend-function "request-scan" "nnml:misc") +=> t +@end lisp + +@item gnus-read-method +@findex gnus-read-method +Prompts the user for a select method. + +@end table + + +@node Backend Interface +@subsection Backend Interface + +Gnus doesn't know anything about @sc{nntp}, spools, mail or virtual +groups. It only knows how to talk to @dfn{virtual servers}. A virtual +server is a @dfn{backend} and some @dfn{backend variables}. As examples +of the first, we have @code{nntp}, @code{nnspool} and @code{nnmbox}. As +examples of the latter we have @code{nntp-port-number} and +@code{nnmbox-directory}. + +When Gnus asks for information from a backend---say @code{nntp}---on +something, it will normally include a virtual server name in the +function parameters. (If not, the backend should use the ``current'' +virtual server.) For instance, @code{nntp-request-list} takes a virtual +server as its only (optional) parameter. If this virtual server hasn't +been opened, the function should fail. + +Note that a virtual server name has no relation to some physical server +name. Take this example: + +@lisp +(nntp "odd-one" + (nntp-address "ifi.uio.no") + (nntp-port-number 4324)) +@end lisp + +Here the virtual server name is @samp{odd-one} while the name of +the physical server is @samp{ifi.uio.no}. + +The backends should be able to switch between several virtual servers. +The standard backends implement this by keeping an alist of virtual +server environments that they pull down/push up when needed. + +There are two groups of interface functions: @dfn{required functions}, +which must be present, and @dfn{optional functions}, which Gnus will +always check for presence before attempting to call 'em. + +All these functions are expected to return data in the buffer +@code{nntp-server-buffer} (@samp{ *nntpd*}), which is somewhat +unfortunately named, but we'll have to live with it. When I talk about +@dfn{resulting data}, I always refer to the data in that buffer. When I +talk about @dfn{return value}, I talk about the function value returned by +the function call. Functions that fail should return @code{nil} as the +return value. + +Some backends could be said to be @dfn{server-forming} backends, and +some might be said not to be. The latter are backends that generally +only operate on one group at a time, and have no concept of ``server'' +-- they have a group, and they deliver info on that group and nothing +more. + +In the examples and definitions I will refer to the imaginary backend +@code{nnchoke}. + +@cindex @code{nnchoke} + +@menu +* Required Backend Functions:: Functions that must be implemented. +* Optional Backend Functions:: Functions that need not be implemented. +* Error Messaging:: How to get messages and report errors. +* Writing New Backends:: Extending old backends. +* Hooking New Backends Into Gnus:: What has to be done on the Gnus end. +* Mail-like Backends:: Some tips on mail backends. +@end menu + + +@node Required Backend Functions +@subsubsection Required Backend Functions + +@table @code + +@item (nnchoke-retrieve-headers ARTICLES &optional GROUP SERVER FETCH-OLD) + +@var{articles} is either a range of article numbers or a list of +@code{Message-ID}s. Current backends do not fully support either---only +sequences (lists) of article numbers, and most backends do not support +retrieval of @code{Message-ID}s. But they should try for both. + +The result data should either be HEADs or NOV lines, and the result +value should either be @code{headers} or @code{nov} to reflect this. +This might later be expanded to @code{various}, which will be a mixture +of HEADs and NOV lines, but this is currently not supported by Gnus. + +If @var{fetch-old} is non-@code{nil} it says to try fetching "extra +headers", in some meaning of the word. This is generally done by +fetching (at most) @var{fetch-old} extra headers less than the smallest +article number in @code{articles}, and filling the gaps as well. The +presence of this parameter can be ignored if the backend finds it +cumbersome to follow the request. If this is non-@code{nil} and not a +number, do maximum fetches. + +Here's an example HEAD: + +@example +221 1056 Article retrieved. +Path: ifi.uio.no!sturles +From: sturles@@ifi.uio.no (Sturle Sunde) +Newsgroups: ifi.discussion +Subject: Re: Something very droll +Date: 27 Oct 1994 14:02:57 +0100 +Organization: Dept. of Informatics, University of Oslo, Norway +Lines: 26 +Message-ID: <38o8e1$a0o@@holmenkollen.ifi.uio.no> +References: <38jdmq$4qu@@visbur.ifi.uio.no> +NNTP-Posting-Host: holmenkollen.ifi.uio.no +. +@end example + +So a @code{headers} return value would imply that there's a number of +these in the data buffer. + +Here's a BNF definition of such a buffer: + +@example +headers = *head +head = error / valid-head +error-message = [ "4" / "5" ] 2number " " <error message> eol +valid-head = valid-message *header "." eol +valid-message = "221 " <number> " Article retrieved." eol +header = <text> eol +@end example + +If the return value is @code{nov}, the data buffer should contain +@dfn{network overview database} lines. These are basically fields +separated by tabs. + +@example +nov-buffer = *nov-line +nov-line = 8*9 [ field <TAB> ] eol +field = <text except TAB> +@end example + +For a closer look at what should be in those fields, +@pxref{Headers}. + + +@item (nnchoke-open-server SERVER &optional DEFINITIONS) + +@var{server} is here the virtual server name. @var{definitions} is a +list of @code{(VARIABLE VALUE)} pairs that define this virtual server. + +If the server can't be opened, no error should be signaled. The backend +may then choose to refuse further attempts at connecting to this +server. In fact, it should do so. + +If the server is opened already, this function should return a +non-@code{nil} value. There should be no data returned. + + +@item (nnchoke-close-server &optional SERVER) + +Close connection to @var{server} and free all resources connected +to it. Return @code{nil} if the server couldn't be closed for some +reason. + +There should be no data returned. + + +@item (nnchoke-request-close) + +Close connection to all servers and free all resources that the backend +have reserved. All buffers that have been created by that backend +should be killed. (Not the @code{nntp-server-buffer}, though.) This +function is generally only called when Gnus is shutting down. + +There should be no data returned. + + +@item (nnchoke-server-opened &optional SERVER) + +If @var{server} is the current virtual server, and the connection to the +physical server is alive, then this function should return a +non-@code{nil} vlue. This function should under no circumstances +attempt to reconnect to a server we have lost connection to. + +There should be no data returned. + + +@item (nnchoke-status-message &optional SERVER) + +This function should return the last error message from @var{server}. + +There should be no data returned. + + +@item (nnchoke-request-article ARTICLE &optional GROUP SERVER TO-BUFFER) + +The result data from this function should be the article specified by +@var{article}. This might either be a @code{Message-ID} or a number. +It is optional whether to implement retrieval by @code{Message-ID}, but +it would be nice if that were possible. + +If @var{to-buffer} is non-@code{nil}, the result data should be returned +in this buffer instead of the normal data buffer. This is to make it +possible to avoid copying large amounts of data from one buffer to +another, while Gnus mainly requests articles to be inserted directly +into its article buffer. + +If it is at all possible, this function should return a cons cell where +the @code{car} is the group name the article was fetched from, and the @code{cdr} is +the article number. This will enable Gnus to find out what the real +group and article numbers are when fetching articles by +@code{Message-ID}. If this isn't possible, @code{t} should be returned +on successful article retrieval. + + +@item (nnchoke-request-group GROUP &optional SERVER FAST) + +Get data on @var{group}. This function also has the side effect of +making @var{group} the current group. + +If @var{FAST}, don't bother to return useful data, just make @var{group} +the current group. + +Here's an example of some result data and a definition of the same: + +@example +211 56 1000 1059 ifi.discussion +@end example + +The first number is the status, which should be 211. Next is the +total number of articles in the group, the lowest article number, the +highest article number, and finally the group name. Note that the total +number of articles may be less than one might think while just +considering the highest and lowest article numbers, but some articles +may have been canceled. Gnus just discards the total-number, so +whether one should take the bother to generate it properly (if that is a +problem) is left as an exercise to the reader. + +@example +group-status = [ error / info ] eol +error = [ "4" / "5" ] 2<number> " " <Error message> +info = "211 " 3* [ <number> " " ] <string> +@end example + + +@item (nnchoke-close-group GROUP &optional SERVER) + +Close @var{group} and free any resources connected to it. This will be +a no-op on most backends. + +There should be no data returned. + + +@item (nnchoke-request-list &optional SERVER) + +Return a list of all groups available on @var{server}. And that means +@emph{all}. + +Here's an example from a server that only carries two groups: + +@example +ifi.test 0000002200 0000002000 y +ifi.discussion 3324 3300 n +@end example + +On each line we have a group name, then the highest article number in +that group, the lowest article number, and finally a flag. + +@example +active-file = *active-line +active-line = name " " <number> " " <number> " " flags eol +name = <string> +flags = "n" / "y" / "m" / "x" / "j" / "=" name +@end example + +The flag says whether the group is read-only (@samp{n}), is moderated +(@samp{m}), is dead (@samp{x}), is aliased to some other group +(@samp{=other-group}) or none of the above (@samp{y}). + + +@item (nnchoke-request-post &optional SERVER) + +This function should post the current buffer. It might return whether +the posting was successful or not, but that's not required. If, for +instance, the posting is done asynchronously, it has generally not been +completed by the time this function concludes. In that case, this +function should set up some kind of sentinel to beep the user loud and +clear if the posting could not be completed. + +There should be no result data from this function. + +@end table + + +@node Optional Backend Functions +@subsubsection Optional Backend Functions + +@table @code + +@item (nnchoke-retrieve-groups GROUPS &optional SERVER) + +@var{groups} is a list of groups, and this function should request data +on all those groups. How it does it is of no concern to Gnus, but it +should attempt to do this in a speedy fashion. + +The return value of this function can be either @code{active} or +@code{group}, which says what the format of the result data is. The +former is in the same format as the data from +@code{nnchoke-request-list}, while the latter is a buffer full of lines +in the same format as @code{nnchoke-request-group} gives. + +@example +group-buffer = *active-line / *group-status +@end example + + +@item (nnchoke-request-update-info GROUP INFO &optional SERVER) + +A Gnus group info (@pxref{Group Info}) is handed to the backend for +alterations. This comes in handy if the backend really carries all the +information (as is the case with virtual and imap groups). This +function should destructively alter the info to suit its needs, and +should return the (altered) group info. + +There should be no result data from this function. + + +@item (nnchoke-request-type GROUP &optional ARTICLE) + +When the user issues commands for ``sending news'' (@kbd{F} in the +summary buffer, for instance), Gnus has to know whether the article the +user is following up on is news or mail. This function should return +@code{news} if @var{article} in @var{group} is news, @code{mail} if it +is mail and @code{unknown} if the type can't be decided. (The +@var{article} parameter is necessary in @code{nnvirtual} groups which +might very well combine mail groups and news groups.) Both @var{group} +and @var{article} may be @code{nil}. + +There should be no result data from this function. + + +@item (nnchoke-request-update-mark GROUP ARTICLE MARK) + +If the user tries to set a mark that the backend doesn't like, this +function may change the mark. Gnus will use whatever this function +returns as the mark for @var{article} instead of the original +@var{mark}. If the backend doesn't care, it must return the original +@var{mark}, and not @code{nil} or any other type of garbage. + +The only use for this I can see is what @code{nnvirtual} does with +it---if a component group is auto-expirable, marking an article as read +in the virtual group should result in the article being marked as +expirable. + +There should be no result data from this function. + + +@item (nnchoke-request-scan &optional GROUP SERVER) + +This function may be called at any time (by Gnus or anything else) to +request that the backend check for incoming articles, in one way or +another. A mail backend will typically read the spool file or query the +POP server when this function is invoked. The @var{group} doesn't have +to be heeded---if the backend decides that it is too much work just +scanning for a single group, it may do a total scan of all groups. It +would be nice, however, to keep things local if that's practical. + +There should be no result data from this function. + + +@item (nnchoke-request-group-description GROUP &optional SERVER) + +The result data from this function should be a description of +@var{group}. + +@example +description-line = name <TAB> description eol +name = <string> +description = <text> +@end example + +@item (nnchoke-request-list-newsgroups &optional SERVER) + +The result data from this function should be the description of all +groups available on the server. + +@example +description-buffer = *description-line +@end example + + +@item (nnchoke-request-newgroups DATE &optional SERVER) + +The result data from this function should be all groups that were +created after @samp{date}, which is in normal human-readable date +format. The data should be in the active buffer format. + + +@item (nnchoke-request-create-group GROUP &optional SERVER) + +This function should create an empty group with name @var{group}. + +There should be no return data. + + +@item (nnchoke-request-expire-articles ARTICLES &optional GROUP SERVER FORCE) + +This function should run the expiry process on all articles in the +@var{articles} range (which is currently a simple list of article +numbers.) It is left up to the backend to decide how old articles +should be before they are removed by this function. If @var{force} is +non-@code{nil}, all @var{articles} should be deleted, no matter how new +they are. + +This function should return a list of articles that it did not/was not +able to delete. + +There should be no result data returned. + + +@item (nnchoke-request-move-article ARTICLE GROUP SERVER ACCEPT-FORM +&optional LAST) + +This function should move @var{article} (which is a number) from +@var{group} by calling @var{accept-form}. + +This function should ready the article in question for moving by +removing any header lines it has added to the article, and generally +should ``tidy up'' the article. Then it should @code{eval} +@var{accept-form} in the buffer where the ``tidy'' article is. This +will do the actual copying. If this @code{eval} returns a +non-@code{nil} value, the article should be removed. + +If @var{last} is @code{nil}, that means that there is a high likelihood +that there will be more requests issued shortly, so that allows some +optimizations. + +The function should return a cons where the @code{car} is the group name and +the @code{cdr} is the article number that the article was entered as. + +There should be no data returned. + + +@item (nnchoke-request-accept-article GROUP &optional SERVER LAST) + +This function takes the current buffer and inserts it into @var{group}. +If @var{last} in @code{nil}, that means that there will be more calls to +this function in short order. + +The function should return a cons where the @code{car} is the group name and +the @code{cdr} is the article number that the article was entered as. + +There should be no data returned. + + +@item (nnchoke-request-replace-article ARTICLE GROUP BUFFER) + +This function should remove @var{article} (which is a number) from +@var{group} and insert @var{buffer} there instead. + +There should be no data returned. + + +@item (nnchoke-request-delete-group GROUP FORCE &optional SERVER) + +This function should delete @var{group}. If @var{force}, it should +really delete all the articles in the group, and then delete the group +itself. (If there is such a thing as ``the group itself''.) + +There should be no data returned. + + +@item (nnchoke-request-rename-group GROUP NEW-NAME &optional SERVER) + +This function should rename @var{group} into @var{new-name}. All +articles in @var{group} should move to @var{new-name}. + +There should be no data returned. + +@end table + + +@node Error Messaging +@subsubsection Error Messaging + +@findex nnheader-report +@findex nnheader-get-report +The backends should use the function @code{nnheader-report} to report +error conditions---they should not raise errors when they aren't able to +perform a request. The first argument to this function is the backend +symbol, and the rest are interpreted as arguments to @code{format} if +there are multiple of them, or just a string if there is one of them. +This function must always returns @code{nil}. + +@lisp +(nnheader-report 'nnchoke "You did something totally bogus") + +(nnheader-report 'nnchoke "Could not request group %s" group) +@end lisp + +Gnus, in turn, will call @code{nnheader-get-report} when it gets a +@code{nil} back from a server, and this function returns the most +recently reported message for the backend in question. This function +takes one argument---the server symbol. + +Internally, these functions access @var{backend}@code{-status-string}, +so the @code{nnchoke} backend will have its error message stored in +@code{nnchoke-status-string}. + + +@node Writing New Backends +@subsubsection Writing New Backends + +Many backends are quite similar. @code{nnml} is just like +@code{nnspool}, but it allows you to edit the articles on the server. +@code{nnmh} is just like @code{nnml}, but it doesn't use an active file, +and it doesn't maintain overview databases. @code{nndir} is just like +@code{nnml}, but it has no concept of ``groups'', and it doesn't allow +editing articles. + +It would make sense if it were possible to ``inherit'' functions from +backends when writing new backends. And, indeed, you can do that if you +want to. (You don't have to if you don't want to, of course.) + +All the backends declare their public variables and functions by using a +package called @code{nnoo}. + +To inherit functions from other backends (and allow other backends to +inherit functions from the current backend), you should use the +following macros: + +@table @code + +@item nnoo-declare +This macro declares the first parameter to be a child of the subsequent +parameters. For instance: + +@lisp +(nnoo-declare nndir + nnml nnmh) +@end lisp + +@code{nndir} has declared here that it intends to inherit functions from +both @code{nnml} and @code{nnmh}. + +@item defvoo +This macro is equivalent to @code{defvar}, but registers the variable as +a public server variable. Most state-oriented variables should be +declared with @code{defvoo} instead of @code{defvar}. + +In addition to the normal @code{defvar} parameters, it takes a list of +variables in the parent backends to map the variable to when executing +a function in those backends. + +@lisp +(defvoo nndir-directory nil + "Where nndir will look for groups." + nnml-current-directory nnmh-current-directory) +@end lisp + +This means that @code{nnml-current-directory} will be set to +@code{nndir-directory} when an @code{nnml} function is called on behalf +of @code{nndir}. (The same with @code{nnmh}.) + +@item nnoo-define-basics +This macro defines some common functions that almost all backends should +have. + +@example +(nnoo-define-basics nndir) +@end example + +@item deffoo +This macro is just like @code{defun} and takes the same parameters. In +addition to doing the normal @code{defun} things, it registers the +function as being public so that other backends can inherit it. + +@item nnoo-map-functions +This macro allows mapping of functions from the current backend to +functions from the parent backends. + +@example +(nnoo-map-functions nndir + (nnml-retrieve-headers 0 nndir-current-group 0 0) + (nnmh-request-article 0 nndir-current-group 0 0)) +@end example + +This means that when @code{nndir-retrieve-headers} is called, the first, +third, and fourth parameters will be passed on to +@code{nnml-retrieve-headers}, while the second parameter is set to the +value of @code{nndir-current-group}. + +@item nnoo-import +This macro allows importing functions from backends. It should be the +last thing in the source file, since it will only define functions that +haven't already been defined. + +@example +(nnoo-import nndir + (nnmh + nnmh-request-list + nnmh-request-newgroups) + (nnml)) +@end example + +This means that calls to @code{nndir-request-list} should just be passed +on to @code{nnmh-request-list}, while all public functions from +@code{nnml} that haven't been defined in @code{nndir} yet should be +defined now. + +@end table + +Below is a slightly shortened version of the @code{nndir} backend. + +@lisp +;;; nndir.el --- single directory newsgroup access for Gnus +;; Copyright (C) 1995,96 Free Software Foundation, Inc. + +;;; Code: + +(require 'nnheader) +(require 'nnmh) +(require 'nnml) +(require 'nnoo) +(eval-when-compile (require 'cl)) + +(nnoo-declare nndir + nnml nnmh) + +(defvoo nndir-directory nil + "Where nndir will look for groups." + nnml-current-directory nnmh-current-directory) + +(defvoo nndir-nov-is-evil nil + "*Non-nil means that nndir will never retrieve NOV headers." + nnml-nov-is-evil) + +(defvoo nndir-current-group "" nil nnml-current-group nnmh-current-group) +(defvoo nndir-top-directory nil nil nnml-directory nnmh-directory) +(defvoo nndir-get-new-mail nil nil nnml-get-new-mail nnmh-get-new-mail) + +(defvoo nndir-status-string "" nil nnmh-status-string) +(defconst nndir-version "nndir 1.0") + +;;; Interface functions. + +(nnoo-define-basics nndir) + +(deffoo nndir-open-server (server &optional defs) + (setq nndir-directory + (or (cadr (assq 'nndir-directory defs)) + server)) + (unless (assq 'nndir-directory defs) + (push `(nndir-directory ,server) defs)) + (push `(nndir-current-group + ,(file-name-nondirectory (directory-file-name nndir-directory))) + defs) + (push `(nndir-top-directory + ,(file-name-directory (directory-file-name nndir-directory))) + defs) + (nnoo-change-server 'nndir server defs)) + +(nnoo-map-functions nndir + (nnml-retrieve-headers 0 nndir-current-group 0 0) + (nnmh-request-article 0 nndir-current-group 0 0) + (nnmh-request-group nndir-current-group 0 0) + (nnmh-close-group nndir-current-group 0)) + +(nnoo-import nndir + (nnmh + nnmh-status-message + nnmh-request-list + nnmh-request-newgroups)) + +(provide 'nndir) +@end lisp + + +@node Hooking New Backends Into Gnus +@subsubsection Hooking New Backends Into Gnus + +@vindex gnus-valid-select-methods +Having Gnus start using your new backend is rather easy---you just +declare it with the @code{gnus-declare-backend} functions. This will +enter the backend into the @code{gnus-valid-select-methods} variable. + +@code{gnus-declare-backend} takes two parameters---the backend name and +an arbitrary number of @dfn{abilities}. + +Here's an example: + +@lisp +(gnus-declare-backend "nnchoke" 'mail 'respool 'address) +@end lisp + +The abilities can be: + +@table @code +@item mail +This is a mailish backend---followups should (probably) go via mail. +@item post +This is a newsish backend---followups should (probably) go via news. +@item post-mail +This backend supports both mail and news. +@item none +This is neither a post nor mail backend---it's something completely +different. +@item respool +It supports respooling---or rather, it is able to modify its source +articles and groups. +@item address +The name of the server should be in the virtual server name. This is +true for almost all backends. +@item prompt-address +The user should be prompted for an address when doing commands like +@kbd{B} in the group buffer. This is true for backends like +@code{nntp}, but not @code{nnmbox}, for instance. +@end table + + +@node Mail-like Backends +@subsubsection Mail-like Backends + +One of the things that separate the mail backends from the rest of the +backends is the heavy dependence by the mail backends on common +functions in @file{nnmail.el}. For instance, here's the definition of +@code{nnml-request-scan}: + +@lisp +(deffoo nnml-request-scan (&optional group server) + (setq nnml-article-file-alist nil) + (nnmail-get-new-mail 'nnml 'nnml-save-nov nnml-directory group)) +@end lisp + +It simply calls @code{nnmail-get-new-mail} with a few parameters, +and @code{nnmail} takes care of all the moving and splitting of the +mail. + +This function takes four parameters. + +@table @var +@item method +This should be a symbol to designate which backend is responsible for +the call. + +@item exit-function +This function should be called after the splitting has been performed. + +@item temp-directory +Where the temporary files should be stored. + +@item group +This optional argument should be a group name if the splitting is to be +performed for one group only. +@end table + +@code{nnmail-get-new-mail} will call @var{backend}@code{-save-mail} to +save each article. @var{backend}@code{-active-number} will be called to +find the article number assigned to this article. + +The function also uses the following variables: +@var{backend}@code{-get-new-mail} (to see whether to get new mail for +this backend); and @var{backend}@code{-group-alist} and +@var{backend}@code{-active-file} to generate the new active file. +@var{backend}@code{-group-alist} should be a group-active alist, like +this: + +@example +(("a-group" (1 . 10)) + ("some-group" (34 . 39))) +@end example + + +@node Score File Syntax +@subsection Score File Syntax + +Score files are meant to be easily parseable, but yet extremely +mallable. It was decided that something that had the same read syntax +as an Emacs Lisp list would fit that spec. + +Here's a typical score file: + +@lisp +(("summary" + ("win95" -10000 nil s) + ("Gnus")) + ("from" + ("Lars" -1000)) + (mark -100)) +@end lisp + +BNF definition of a score file: + +@example +score-file = "" / "(" *element ")" +element = rule / atom +rule = string-rule / number-rule / date-rule +string-rule = "(" quote string-header quote space *string-match ")" +number-rule = "(" quote number-header quote space *number-match ")" +date-rule = "(" quote date-header quote space *date-match ")" +quote = <ascii 34> +string-header = "subject" / "from" / "references" / "message-id" / + "xref" / "body" / "head" / "all" / "followup" +number-header = "lines" / "chars" +date-header = "date" +string-match = "(" quote <string> quote [ "" / [ space score [ "" / + space date [ "" / [ space string-match-t ] ] ] ] ] ")" +score = "nil" / <integer> +date = "nil" / <natural number> +string-match-t = "nil" / "s" / "substring" / "S" / "Substring" / + "r" / "regex" / "R" / "Regex" / + "e" / "exact" / "E" / "Exact" / + "f" / "fuzzy" / "F" / "Fuzzy" +number-match = "(" <integer> [ "" / [ space score [ "" / + space date [ "" / [ space number-match-t ] ] ] ] ] ")" +number-match-t = "nil" / "=" / "<" / ">" / ">=" / "<=" +date-match = "(" quote <string> quote [ "" / [ space score [ "" / + space date [ "" / [ space date-match-t ] ] ] ] ")" +date-match-t = "nil" / "at" / "before" / "after" +atom = "(" [ required-atom / optional-atom ] ")" +required-atom = mark / expunge / mark-and-expunge / files / + exclude-files / read-only / touched +optional-atom = adapt / local / eval +mark = "mark" space nil-or-number +nil-or-number = "nil" / <integer> +expunge = "expunge" space nil-or-number +mark-and-expunge = "mark-and-expunge" space nil-or-number +files = "files" *[ space <string> ] +exclude-files = "exclude-files" *[ space <string> ] +read-only = "read-only" [ space "nil" / space "t" ] +adapt = "adapt" [ space "ignore" / space "t" / space adapt-rule ] +adapt-rule = "(" *[ <string> *[ "(" <string> <integer> ")" ] ")" +local = "local" *[ space "(" <string> space <form> ")" ] +eval = "eval" space <form> +space = *[ " " / <TAB> / <NEWLINE> ] +@end example + +Any unrecognized elements in a score file should be ignored, but not +discarded. + +As you can see, white space is needed, but the type and amount of white +space is irrelevant. This means that formatting of the score file is +left up to the programmer---if it's simpler to just spew it all out on +one looong line, then that's ok. + +The meaning of the various atoms are explained elsewhere in this +manual (@pxref{Score File Format}). + + +@node Headers +@subsection Headers + +Internally Gnus uses a format for storing article headers that +corresponds to the @sc{nov} format in a mysterious fashion. One could +almost suspect that the author looked at the @sc{nov} specification and +just shamelessly @emph{stole} the entire thing, and one would be right. + +@dfn{Header} is a severely overloaded term. ``Header'' is used in +RFC1036 to talk about lines in the head of an article (e.g., +@code{From}). It is used by many people as a synonym for +``head''---``the header and the body''. (That should be avoided, in my +opinion.) And Gnus uses a format internally that it calls ``header'', +which is what I'm talking about here. This is a 9-element vector, +basically, with each header (ouch) having one slot. + +These slots are, in order: @code{number}, @code{subject}, @code{from}, +@code{date}, @code{id}, @code{references}, @code{chars}, @code{lines}, +@code{xref}. There are macros for accessing and setting these +slots---they all have predictable names beginning with +@code{mail-header-} and @code{mail-header-set-}, respectively. + +The @code{xref} slot is really a @code{misc} slot. Any extra info will +be put in there. + + +@node Ranges +@subsection Ranges + +@sc{gnus} introduced a concept that I found so useful that I've started +using it a lot and have elaborated on it greatly. + +The question is simple: If you have a large amount of objects that are +identified by numbers (say, articles, to take a @emph{wild} example) +that you want to qualify as being ``included'', a normal sequence isn't +very useful. (A 200,000 length sequence is a bit long-winded.) + +The solution is as simple as the question: You just collapse the +sequence. + +@example +(1 2 3 4 5 6 10 11 12) +@end example + +is transformed into + +@example +((1 . 6) (10 . 12)) +@end example + +To avoid having those nasty @samp{(13 . 13)} elements to denote a +lonesome object, a @samp{13} is a valid element: + +@example +((1 . 6) 7 (10 . 12)) +@end example + +This means that comparing two ranges to find out whether they are equal +is slightly tricky: + +@example +((1 . 5) 7 8 (10 . 12)) +@end example + +and + +@example +((1 . 5) (7 . 8) (10 . 12)) +@end example + +are equal. In fact, any non-descending list is a range: + +@example +(1 2 3 4 5) +@end example + +is a perfectly valid range, although a pretty long-winded one. This is +also valid: + +@example +(1 . 5) +@end example + +and is equal to the previous range. + +Here's a BNF definition of ranges. Of course, one must remember the +semantic requirement that the numbers are non-descending. (Any number +of repetition of the same number is allowed, but apt to disappear in +range handling.) + +@example +range = simple-range / normal-range +simple-range = "(" number " . " number ")" +normal-range = "(" start-contents ")" +contents = "" / simple-range *[ " " contents ] / + number *[ " " contents ] +@end example + +Gnus currently uses ranges to keep track of read articles and article +marks. I plan on implementing a number of range operators in C if The +Powers That Be are willing to let me. (I haven't asked yet, because I +need to do some more thinking on what operators I need to make life +totally range-based without ever having to convert back to normal +sequences.) + + +@node Group Info +@subsection Group Info + +Gnus stores all permanent info on groups in a @dfn{group info} list. +This list is from three to six elements (or more) long and exhaustively +describes the group. + +Here are two example group infos; one is a very simple group while the +second is a more complex one: + +@example +("no.group" 5 (1 . 54324)) + +("nnml:my.mail" 3 ((1 . 5) 9 (20 . 55)) + ((tick (15 . 19)) (replied 3 6 (19 . 3))) + (nnml "") + ((auto-expire . t) (to-address . "ding@@gnus.org"))) +@end example + +The first element is the @dfn{group name}---as Gnus knows the group, +anyway. The second element is the @dfn{subscription level}, which +normally is a small integer. (It can also be the @dfn{rank}, which is a +cons cell where the @code{car} is the level and the @code{cdr} is the +score.) The third element is a list of ranges of read articles. The +fourth element is a list of lists of article marks of various kinds. +The fifth element is the select method (or virtual server, if you like). +The sixth element is a list of @dfn{group parameters}, which is what +this section is about. + +Any of the last three elements may be missing if they are not required. +In fact, the vast majority of groups will normally only have the first +three elements, which saves quite a lot of cons cells. + +Here's a BNF definition of the group info format: + +@example +info = "(" group space ralevel space read + [ "" / [ space marks-list [ "" / [ space method [ "" / + space parameters ] ] ] ] ] ")" +group = quote <string> quote +ralevel = rank / level +level = <integer in the range of 1 to inf> +rank = "(" level "." score ")" +score = <integer in the range of 1 to inf> +read = range +marks-lists = nil / "(" *marks ")" +marks = "(" <string> range ")" +method = "(" <string> *elisp-forms ")" +parameters = "(" *elisp-forms ")" +@end example + +Actually that @samp{marks} rule is a fib. A @samp{marks} is a +@samp{<string>} consed on to a @samp{range}, but that's a bitch to say +in pseudo-BNF. + +If you have a Gnus info and want to access the elements, Gnus offers a +series of macros for getting/setting these elements. + +@table @code +@item gnus-info-group +@itemx gnus-info-set-group +@findex gnus-info-group +@findex gnus-info-set-group +Get/set the group name. + +@item gnus-info-rank +@itemx gnus-info-set-rank +@findex gnus-info-rank +@findex gnus-info-set-rank +Get/set the group rank (@pxref{Group Score}). + +@item gnus-info-level +@itemx gnus-info-set-level +@findex gnus-info-level +@findex gnus-info-set-level +Get/set the group level. + +@item gnus-info-score +@itemx gnus-info-set-score +@findex gnus-info-score +@findex gnus-info-set-score +Get/set the group score (@pxref{Group Score}). + +@item gnus-info-read +@itemx gnus-info-set-read +@findex gnus-info-read +@findex gnus-info-set-read +Get/set the ranges of read articles. + +@item gnus-info-marks +@itemx gnus-info-set-marks +@findex gnus-info-marks +@findex gnus-info-set-marks +Get/set the lists of ranges of marked articles. + +@item gnus-info-method +@itemx gnus-info-set-method +@findex gnus-info-method +@findex gnus-info-set-method +Get/set the group select method. + +@item gnus-info-params +@itemx gnus-info-set-params +@findex gnus-info-params +@findex gnus-info-set-params +Get/set the group parameters. +@end table + +All the getter functions take one parameter---the info list. The setter +functions take two parameters---the info list and the new value. + +The last three elements in the group info aren't mandatory, so it may be +necessary to extend the group info before setting the element. If this +is necessary, you can just pass on a non-@code{nil} third parameter to +the three final setter functions to have this happen automatically. + + +@node Extended Interactive +@subsection Extended Interactive +@cindex interactive +@findex gnus-interactive + +Gnus extends the standard Emacs @code{interactive} specification +slightly to allow easy use of the symbolic prefix (@pxref{Symbolic +Prefixes}). Here's an example of how this is used: + +@lisp +(defun gnus-summary-increase-score (&optional score symp) + (interactive (gnus-interactive "P\ny")) + ... + ) +@end lisp + +The best thing to do would have been to implement +@code{gnus-interactive} as a macro which would have returned an +@code{interactive} form, but this isn't possible since Emacs checks +whether a function is interactive or not by simply doing an @code{assq} +on the lambda form. So, instead we have @code{gnus-interactive} +function that takes a string and returns values that are usable to +@code{interactive}. + +This function accepts (almost) all normal @code{interactive} specs, but +adds a few more. + +@table @samp +@item y +@vindex gnus-current-prefix-symbol +The current symbolic prefix---the @code{gnus-current-prefix-symbol} +variable. + +@item Y +@vindex gnus-current-prefix-symbols +A list of the current symbolic prefixes---the +@code{gnus-current-prefix-symbol} variable. + +@item A +The current article number---the @code{gnus-summary-article-number} +function. + +@item H +The current article header---the @code{gnus-summary-article-header} +function. + +@item g +The current group name---the @code{gnus-group-group-name} +function. + +@end table + + +@node Emacs/XEmacs Code +@subsection Emacs/XEmacs Code +@cindex XEmacs +@cindex Emacsen + +While Gnus runs under Emacs, XEmacs and Mule, I decided that one of the +platforms must be the primary one. I chose Emacs. Not because I don't +like XEmacs or Mule, but because it comes first alphabetically. + +This means that Gnus will byte-compile under Emacs with nary a warning, +while XEmacs will pump out gigabytes of warnings while byte-compiling. +As I use byte-compilation warnings to help me root out trivial errors in +Gnus, that's very useful. + +I've also consistently used Emacs function interfaces, but have used +Gnusey aliases for the functions. To take an example: Emacs defines a +@code{run-at-time} function while XEmacs defines a @code{start-itimer} +function. I then define a function called @code{gnus-run-at-time} that +takes the same parameters as the Emacs @code{run-at-time}. When running +Gnus under Emacs, the former function is just an alias for the latter. +However, when running under XEmacs, the former is an alias for the +following function: + +@lisp +(defun gnus-xmas-run-at-time (time repeat function &rest args) + (start-itimer + "gnus-run-at-time" + `(lambda () + (,function ,@@args)) + time repeat)) +@end lisp + +This sort of thing has been done for bunches of functions. Gnus does +not redefine any native Emacs functions while running under XEmacs---it +does this @code{defalias} thing with Gnus equivalents instead. Cleaner +all over. + +In the cases where the XEmacs function interface was obviously cleaner, +I used it instead. For example @code{gnus-region-active-p} is an alias +for @code{region-active-p} in XEmacs, whereas in Emacs it is a function. + +Of course, I could have chosen XEmacs as my native platform and done +mapping functions the other way around. But I didn't. The performance +hit these indirections impose on Gnus under XEmacs should be slight. + + +@node Various File Formats +@subsection Various File Formats + +@menu +* Active File Format:: Information on articles and groups available. +* Newsgroups File Format:: Group descriptions. +@end menu + + +@node Active File Format +@subsubsection Active File Format + +The active file lists all groups available on the server in +question. It also lists the highest and lowest current article numbers +in each group. + +Here's an excerpt from a typical active file: + +@example +soc.motss 296030 293865 y +alt.binaries.pictures.fractals 3922 3913 n +comp.sources.unix 1605 1593 m +comp.binaries.ibm.pc 5097 5089 y +no.general 1000 900 y +@end example + +Here's a pseudo-BNF definition of this file: + +@example +active = *group-line +group-line = group space high-number space low-number space flag <NEWLINE> +group = <non-white-space string> +space = " " +high-number = <non-negative integer> +low-number = <positive integer> +flag = "y" / "n" / "m" / "j" / "x" / "=" group +@end example + +For a full description of this file, see the manual pages for +@samp{innd}, in particular @samp{active(5)}. + + +@node Newsgroups File Format +@subsubsection Newsgroups File Format + +The newsgroups file lists groups along with their descriptions. Not all +groups on the server have to be listed, and not all groups in the file +have to exist on the server. The file is meant purely as information to +the user. + +The format is quite simple; a group name, a tab, and the description. +Here's the definition: + +@example +newsgroups = *line +line = group tab description <NEWLINE> +group = <non-white-space string> +tab = <TAB> +description = <string> +@end example + + +@page +@node Emacs for Heathens +@section Emacs for Heathens + +Believe it or not, but some people who use Gnus haven't really used +Emacs much before they embarked on their journey on the Gnus Love Boat. +If you are one of those unfortunates whom ``@kbd{M-C-a}'', ``kill the +region'', and ``set @code{gnus-flargblossen} to an alist where the key +is a regexp that is used for matching on the group name'' are magical +phrases with little or no meaning, then this appendix is for you. If +you are already familiar with Emacs, just ignore this and go fondle your +cat instead. + +@menu +* Keystrokes:: Entering text and executing commands. +* Emacs Lisp:: The built-in Emacs programming language. +@end menu + + +@node Keystrokes +@subsection Keystrokes + +@itemize @bullet +@item +Q: What is an experienced Emacs user? + +@item +A: A person who wishes that the terminal had pedals. +@end itemize + +Yes, when you use Emacs, you are apt to use the control key, the shift +key and the meta key a lot. This is very annoying to some people +(notably @code{vi}le users), and the rest of us just love the hell out +of it. Just give up and submit. Emacs really does stand for +``Escape-Meta-Alt-Control-Shift'', and not ``Editing Macros'', as you +may have heard from other disreputable sources (like the Emacs author). + +The shift keys are normally located near your pinky fingers, and are +normally used to get capital letters and stuff. You probably use it all +the time. The control key is normally marked ``CTRL'' or something like +that. The meta key is, funnily enough, never marked as such on any +keyboard. The one I'm currently at has a key that's marked ``Alt'', +which is the meta key on this keyboard. It's usually located somewhere +to the left hand side of the keyboard, usually on the bottom row. + +Now, us Emacs people don't say ``press the meta-control-m key'', +because that's just too inconvenient. We say ``press the @kbd{M-C-m} +key''. @kbd{M-} is the prefix that means ``meta'' and ``C-'' is the +prefix that means ``control''. So ``press @kbd{C-k}'' means ``press +down the control key, and hold it down while you press @kbd{k}''. +``Press @kbd{M-C-k}'' means ``press down and hold down the meta key and +the control key and then press @kbd{k}''. Simple, ay? + +This is somewhat complicated by the fact that not all keyboards have a +meta key. In that case you can use the ``escape'' key. Then @kbd{M-k} +means ``press escape, release escape, press @kbd{k}''. That's much more +work than if you have a meta key, so if that's the case, I respectfully +suggest you get a real keyboard with a meta key. You can't live without +it. + + + +@node Emacs Lisp +@subsection Emacs Lisp + +Emacs is the King of Editors because it's really a Lisp interpreter. +Each and every key you tap runs some Emacs Lisp code snippet, and since +Emacs Lisp is an interpreted language, that means that you can configure +any key to run any arbitrary code. You just, like, do it. + +Gnus is written in Emacs Lisp, and is run as a bunch of interpreted +functions. (These are byte-compiled for speed, but it's still +interpreted.) If you decide that you don't like the way Gnus does +certain things, it's trivial to have it do something a different way. +(Well, at least if you know how to write Lisp code.) However, that's +beyond the scope of this manual, so we are simply going to talk about +some common constructs that you normally use in your @file{.emacs} file +to customize Gnus. + +If you want to set the variable @code{gnus-florgbnize} to four (4), you +write the following: + +@lisp +(setq gnus-florgbnize 4) +@end lisp + +This function (really ``special form'') @code{setq} is the one that can +set a variable to some value. This is really all you need to know. Now +you can go and fill your @code{.emacs} file with lots of these to change +how Gnus works. + +If you have put that thing in your @code{.emacs} file, it will be read +and @code{eval}ed (which is lisp-ese for ``run'') the next time you +start Emacs. If you want to change the variable right away, simply say +@kbd{C-x C-e} after the closing parenthesis. That will @code{eval} the +previous ``form'', which is a simple @code{setq} statement here. + +Go ahead---just try it, if you're located at your Emacs. After you +@kbd{C-x C-e}, you will see @samp{4} appear in the echo area, which +is the return value of the form you @code{eval}ed. + +Some pitfalls: + +If the manual says ``set @code{gnus-read-active-file} to @code{some}'', +that means: + +@lisp +(setq gnus-read-active-file 'some) +@end lisp + +On the other hand, if the manual says ``set @code{gnus-nntp-server} to +@samp{nntp.ifi.uio.no}'', that means: + +@lisp +(setq gnus-nntp-server "nntp.ifi.uio.no") +@end lisp + +So be careful not to mix up strings (the latter) with symbols (the +former). The manual is unambiguous, but it can be confusing. + +@page +@include gnus-faq.texi + +@node Index +@chapter Index +@printindex cp + +@node Key Index +@chapter Key Index +@printindex ky + +@summarycontents +@contents +@bye + + +@c End: + diff --git a/man/help.texi b/man/help.texi new file mode 100644 index 00000000000..2503a5731e9 --- /dev/null +++ b/man/help.texi @@ -0,0 +1,479 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Help, Mark, M-x, Top +@chapter Help +@kindex Help +@cindex help +@cindex self-documentation +@findex help-command +@kindex C-h +@kindex F1 + + Emacs provides extensive help features accessible through a single +character, @kbd{C-h}. @kbd{C-h} is a prefix key that is used only for +documentation-printing commands. The characters that you can type after +@kbd{C-h} are called @dfn{help options}. One help option is @kbd{C-h}; +that is how you ask for help about using @kbd{C-h}. To cancel, type +@kbd{C-g}. The function key @key{F1} is equivalent to @kbd{C-h}. + +@kindex C-h C-h +@findex help-for-help + @kbd{C-h C-h} (@code{help-for-help}) displays a list of the possible +help options, each with a brief description. Before you type a help +option, you can use @key{SPC} or @key{DEL} to scroll through the list. + + @kbd{C-h} or @key{F1} means ``help'' in various other contexts as +well. For example, in the middle of @code{query-replace}, it describes +the options available for how to operate on the current match. After a +prefix key, it displays a list of the alternatives that can follow the +prefix key. (A few prefix keys don't support @kbd{C-h}, because they +define other meanings for it, but they all support @key{F1}.) + + Most help buffers use a special major mode, Help mode, which lets you +scroll conveniently with @key{SPC} and @key{DEL}. + +@menu +* Help Summary:: Brief list of all Help commands. +* Key Help:: Asking what a key does in Emacs. +* Name Help:: Asking about a command, variable or function name. +* Apropos:: Asking what pertains to a given topic. +* Library Keywords:: Finding Lisp libraries by keywords (topics). +* Language Help:: Help relating to international language support. +* Help Mode:: Special features of Help mode and Help buffers. +* Misc Help:: Other help commands. +@end menu + +@iftex +@node Help Summary +@end iftex +@ifinfo +@node Help Summary +@section Help Summary +@end ifinfo + + Here is a summary of the defined help commands. + +@table @kbd +@item C-h a @var{regexp} @key{RET} +Display a list of commands whose names match @var{regexp} +(@code{apropos-command}). +@item C-h b +Display a table of all key bindings in effect now, in this order: minor +mode bindings, major mode bindings, and global bindings +(@code{describe-bindings}). +@item C-h c @var{key} +Print the name of the command that @var{key} runs +(@code{describe-key-briefly}). Here @kbd{c} stands for `character'. For more +extensive information on @var{key}, use @kbd{C-h k}. +@item C-h f @var{function} @key{RET} +Display documentation on the Lisp function named @var{function} +(@code{describe-function}). Since commands are Lisp functions, +a command name may be used. +@item C-h h +Display the @file{hello} file, which shows examples of various character +sets. +@item C-h i +Run Info, the program for browsing documentation files (@code{info}). +The complete Emacs manual is available on-line in Info. +@item C-h k @var{key} +Display the name and documentation of the command that @var{key} runs +(@code{describe-key}). +@item C-h l +Display a description of the last 100 characters you typed +(@code{view-lossage}). +@item C-h m +Display documentation of the current major mode (@code{describe-mode}). +@item C-h n +Display documentation of Emacs changes, most recent first +(@code{view-emacs-news}). +@item C-h p +Find packages by topic keyword (@code{finder-by-keyword}). +@item C-h s +Display current contents of the syntax table, plus an explanation of +what they mean (@code{describe-syntax}). @xref{Syntax}. +@item C-h t +Enter the Emacs interactive tutorial (@code{help-with-tutorial}). +@item C-h v @var{var} @key{RET} +Display the documentation of the Lisp variable @var{var} +(@code{describe-variable}). +@item C-h w @var{command} @key{RET} +Print which keys run the command named @var{command} (@code{where-is}). +@item C-h C @var{coding} @key{RET} +Describe coding system @var{coding} +(@code{describe-coding-system}). +@item C-h C @key{RET} +Describe the coding systems currently in use. +@item C-h I @var{method} @key{RET} +Describe an input method (@code{describe-input-method}). +@item C-h L @var{language-env} @key{RET} +Describe information on the character sets, coding systems and input +methods used for language environment @var{language-env} +(@code{describe-language-environment}). +@item C-h C-c +Display the copying conditions for GNU Emacs. +@item C-h C-d +Display information about getting new versions of GNU Emacs. +@item C-h C-f @var{function} @key{RET} +Enter Info and go to the node documenting the Emacs function @var{function} +(@code{Info-goto-emacs-command-node}). +@item C-h C-k @var{key} +Enter Info and go to the node where the key sequence @var{key} is +documented (@code{Info-goto-emacs-key-command-node}). +@item C-h C-p +Display information about the GNU Project. +@item C-h @key{TAB} @var{symbol} @key{RET} +Display the Info documentation on symbol @var{symbol} according to the +programming language you are editing (@code{info-lookup-symbol}). +@end table + +@node Key Help +@section Documentation for a Key + +@kindex C-h c +@findex describe-key-briefly + The most basic @kbd{C-h} options are @kbd{C-h c} +(@code{describe-key-briefly}) and @w{@kbd{C-h k}} (@code{describe-key}). +@kbd{C-h c @var{key}} prints in the echo area the name of the command +that @var{key} is bound to. For example, @kbd{C-h c C-f} prints +@samp{forward-char}. Since command names are chosen to describe what +the commands do, this is a good way to get a very brief description of +what @var{key} does. + +@kindex C-h k +@findex describe-key + @kbd{C-h k @var{key}} is similar but gives more information: it +displays the documentation string of the command as well as its name. +This is too big for the echo area, so a window is used for the display. + + @kbd{C-h c} and @kbd{C-h k} work for any sort of key sequences, +including function keys and mouse events. + +@node Name Help +@section Help by Command or Variable Name + +@kindex C-h f +@findex describe-function + @kbd{C-h f} (@code{describe-function}) reads the name of a Lisp function +using the minibuffer, then displays that function's documentation string +in a window. Since commands are Lisp functions, you can use this to get +the documentation of a command that you know by name. For example, + +@example +C-h f auto-fill-mode @key{RET} +@end example + +@noindent +displays the documentation of @code{auto-fill-mode}. This is the only +way to get the documentation of a command that is not bound to any key +(one which you would normally run using @kbd{M-x}). + + @kbd{C-h f} is also useful for Lisp functions that you are planning to +use in a Lisp program. For example, if you have just written the +expression @code{(make-vector len)} and want to check that you are using +@code{make-vector} properly, type @kbd{C-h f make-vector @key{RET}}. +Because @kbd{C-h f} allows all function names, not just command names, +you may find that some of your favorite abbreviations that work in +@kbd{M-x} don't work in @kbd{C-h f}. An abbreviation may be unique +among command names yet fail to be unique when other function names are +allowed. + + The function name for @kbd{C-h f} to describe has a default which is +used if you type @key{RET} leaving the minibuffer empty. The default is +the function called by the innermost Lisp expression in the buffer around +point, @emph{provided} that is a valid, defined Lisp function name. For +example, if point is located following the text @samp{(make-vector (car +x)}, the innermost list containing point is the one that starts with +@samp{(make-vector}, so the default is to describe the function +@code{make-vector}. + + @kbd{C-h f} is often useful just to verify that you have the right +spelling for the function name. If @kbd{C-h f} mentions a name from the +buffer as the default, that name must be defined as a Lisp function. If +that is all you want to know, just type @kbd{C-g} to cancel the @kbd{C-h +f} command, then go on editing. + +@kindex C-h w +@findex where-is + @kbd{C-h w @var{command} @key{RET}} tells you what keys are bound to +@var{command}. It prints a list of the keys in the echo area. If it +says the command is not on any key, you must use @kbd{M-x} to run it. +@kbd{C-h w} runs the command @code{where-is}. + + @kbd{C-h v} (@code{describe-variable}) is like @kbd{C-h f} but describes +Lisp variables instead of Lisp functions. Its default is the Lisp symbol +around or before point, but only if that is the name of a known Lisp +variable. @xref{Variables}.@refill + +@node Apropos +@section Apropos + +@kindex C-h a +@findex apropos-command +@cindex apropos + A more sophisticated sort of question to ask is, ``What are the +commands for working with files?'' To ask this question, type @kbd{C-h +a file @key{RET}}, which displays a list of all command names that +contain @samp{file}, including @code{copy-file}, @code{find-file}, and +so on. With each command name appears a brief description of how to use +the command, and what keys you can currently invoke it with. For +example, it would say that you can invoke @code{find-file} by typing +@kbd{C-x C-f}. The @kbd{a} in @kbd{C-h a} stands for `Apropos'; +@kbd{C-h a} runs the command @code{apropos-command}. This command +normally checks only commands (interactive functions); if you specify a +prefix argument, it checks noninteractive functions as well. + + Because @kbd{C-h a} looks only for functions whose names contain the +string you specify, you must use ingenuity in choosing the +string. If you are looking for commands for killing backwards and +@kbd{C-h a kill-backwards @key{RET}} doesn't reveal any, don't give up. +Try just @kbd{kill}, or just @kbd{backwards}, or just @kbd{back}. Be +persistent. Also note that you can use a regular expression as the +argument, for more flexibility (@pxref{Regexps}). + + Here is a set of arguments to give to @kbd{C-h a} that covers many +classes of Emacs commands, since there are strong conventions for naming +the standard Emacs commands. By giving you a feel for the naming +conventions, this set should also serve to aid you in developing a +technique for picking @code{apropos} strings. + +@quotation +char, line, word, sentence, paragraph, region, page, sexp, list, defun, +rect, buffer, frame, window, face, file, dir, register, mode, beginning, end, +forward, backward, next, previous, up, down, search, goto, kill, delete, +mark, insert, yank, fill, indent, case, change, set, what, list, find, +view, describe, default. +@end quotation + +@findex apropos-variable + To list all user variables that match a regexp, use the command +@kbd{M-x apropos-variable}. This command shows only user variables and +customization options by default; if you specify a prefix argument, it +checks all variables. + +@findex apropos + To list all Lisp symbols that contain a match for a regexp, not just +the ones that are defined as commands, use the command @kbd{M-x apropos} +instead of @kbd{C-h a}. This command does not check key bindings by +default; specify a numeric argument if you want it to check them. + +@findex apropos-documentation + The @code{apropos-documentation} command is like @code{apropos} except +that it searches documentation strings as well as symbol names for +matches for the specified regular expression. + +@findex apropos-value + The @code{apropos-value} command is like @code{apropos} except that it +searches symbols' values for matches for the specified regular +expression. This command does not check function definitions or +property lists by default; specify a numeric argument if you want it to +check them. + +@vindex apropos-do-all + If the variable @code{apropos-do-all} is non-@code{nil}, the commands +above all behave as if they had been given a prefix argument. + + If you want more information about a function definition, variable or +symbol property listed in the Apropos buffer, you can click on it with +@kbd{Mouse-2} or move there and type @key{RET}. + +@node Library Keywords +@section Keyword Search for Lisp Libraries + +@kindex C-h p +@findex finder-by-keyword +The @kbd{C-h p} command lets you search the standard Emacs Lisp +libraries by topic keywords. Here is a partial list of keywords you can +use: + +@display +abbrev --- abbreviation handling, typing shortcuts, macros. +bib --- support for the bibliography processor @code{bib}. +c --- C and C++ language support. +calendar --- calendar and time management support. +comm --- communications, networking, remote access to files. +data --- support for editing files of data. +docs --- support for Emacs documentation. +emulations --- emulations of other editors. +extensions --- Emacs Lisp language extensions. +faces --- support for using faces (fonts and colors; @pxref{Faces}). +frames --- support for Emacs frames and window systems. +games --- games, jokes and amusements. +hardware --- support for interfacing with exotic hardware. +help --- support for on-line help systems. +hypermedia --- support for links within text, or other media types. +i18n --- internationalization and alternate character-set support. +internal --- code for Emacs internals, build process, defaults. +languages --- specialized modes for editing programming languages. +lisp --- support for using Lisp (including Emacs Lisp). +local --- libraries local to your site. +maint --- maintenance aids for the Emacs development group. +mail --- modes for electronic-mail handling. +matching --- searching and matching. +news --- support for netnews reading and posting. +non-text --- support for editing files that are not ordinary text. +oop --- support for object-oriented programming. +outlines --- hierarchical outlining. +processes --- process, subshell, compilation, and job control support. +terminals --- support for terminal types. +tex --- support for the @TeX{} formatter. +tools --- programming tools. +unix --- front-ends/assistants for, or emulators of, Unix features. +vms --- support code for VMS. +wp --- word processing. +@end display + +@node Language Help +@section Help for International Language Support + + You can use the command @kbd{C-h L} +(@code{describe-language-environment}) to find out the support for a +specific language environment. @xref{Language Environments}. This +tells you which languages this language environment is useful for, and +lists the character sets, coding systems, and input methods that go with +it. It also shows some sample text to illustrate scripts. + + The command @kbd{C-h h} (@code{view-hello-file}) displays the file +@file{etc/HELLO}, which shows how to say ``hello'' in many languages. + + The command @kbd{C-h I} (@code{describe-input-method}) describes +information about input methods---either a specified input method, or by +default the input method in use. @xref{Input Methods}. + + The command @kbd{C-h C} (@code{describe-coding-system}) describes +information about coding systems---either a specified coding system, or +the ones currently in use. @xref{Coding Systems}. + +@node Help Mode +@section Help Mode Commands + + Help buffers provide the commands of View mode (@pxref{Misc File +Ops}), plus a few special commands of their own. + +@table @kbd +@item @key{SPC} +Scroll forward. +@item @key{DEL} +Scroll backward. +@item @key{RET} +Follow a cross reference at point. +@item @key{TAB} +Move point forward to the next cross reference. +@item S-@key{TAB} +Move point back to the previous cross reference. +@item Mouse-2 +Follow a cross reference that you click on. +@end table + + When a command name (@pxref{M-x,, Running Commands by Name}) or +variable name (@pxref{Variables}) appears in the documentation, it +normally appears inside paired single-quotes. You can click on the name +with @kbd{Mouse-2}, or move point there and type @key{RET}, to view the +documentation of that command or variable. Use @kbd{C-c C-b} to retrace +your steps. + +@kindex @key{TAB} @r{(Help mode)} +@findex help-next-ref +@kindex S-@key{TAB} @r{(Help mode)} +@findex help-previous-ref + There are convenient commands for moving point to cross references in +the help text. @key{TAB} (@code{help-next-ref}) moves point down to the +next cross reference. Use @kbd{S-@key{TAB}} to move point up to the +previous cross reference (@code{help-previous-ref}). + +@node Misc Help +@section Other Help Commands + +@kindex C-h i +@findex info +@cindex Info +@cindex manuals, on-line +@cindex on-line manuals + @kbd{C-h i} (@code{info}) runs the Info program, which is used for +browsing through structured documentation files. The entire Emacs manual +is available within Info. Eventually all the documentation of the GNU +system will be available. Type @kbd{h} after entering Info to run +a tutorial on using Info. + + If you specify a numeric argument, @kbd{C-h i} prompts for the name of +a documentation file. This way, you can browse a file which doesn't +have an entry in the top-level Info menu. It is also handy when you +need to get to the documentation quickly, and you know the exact name of +the file. + +@kindex C-h C-f +@kindex C-h C-k +@findex Info-goto-emacs-key-command-node +@findex Info-goto-emacs-command-node + There are two special help commands for accessing Emacs documentation +through Info. @kbd{C-h C-f @var{function} @key{RET}} enters Info and +goes straight to the documentation of the Emacs function +@var{function}. @kbd{C-h C-k @var{key}} enters Info and goes straight +to the documentation of the key @var{key}. These two keys run the +commands @code{Info-goto-emacs-command-node} and +@code{Info-goto-emacs-key-command-node}. + + When editing a program, if you have an Info version of the manual for +the programming language, you can use the command @kbd{C-h C-i} to refer +to the manual documentation for a symbol (keyword, function or +variable). The details of how this command works depend on the major +mode. + +@kindex C-h l +@findex view-lossage + If something surprising happens, and you are not sure what commands you +typed, use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} prints the last +100 command characters you typed in. If you see commands that you don't +know, you can use @kbd{C-h c} to find out what they do. + +@kindex C-h m +@findex describe-mode + Emacs has numerous major modes, each of which redefines a few keys and +makes a few other changes in how editing works. @kbd{C-h m} +(@code{describe-mode}) prints documentation on the current major mode, +which normally describes all the commands that are changed in this +mode. + +@kindex C-h b +@findex describe-bindings + @kbd{C-h b} (@code{describe-bindings}) and @kbd{C-h s} +(@code{describe-syntax}) present other information about the current +Emacs mode. @kbd{C-h b} displays a list of all the key bindings now in +effect; the local bindings defined by the current minor modes first, +then the local bindings defined by the current major mode, and finally +the global bindings (@pxref{Key Bindings}). @kbd{C-h s} displays the +contents of the syntax table, with explanations of each character's +syntax (@pxref{Syntax}). + + You can get a similar list for a particular prefix key by typing +@kbd{C-h} after the prefix key. (There are a few prefix keys for which +this does not work---those that provide their own bindings for +@kbd{C-h}. One of these is @key{ESC}, because @kbd{@key{ESC} C-h} is +actually @kbd{C-M-h}, which marks a defun.) + +@kindex C-h F +@findex view-emacs-FAQ +@kindex C-h n +@findex view-emacs-news +@kindex C-h C-c +@findex describe-copying +@kindex C-h C-d +@findex describe-distribution +@kindex C-h C-w +@findex describe-no-warranty +@kindex C-h C-p +@findex describe-project + The other @kbd{C-h} options display various files of useful +information. @kbd{C-h C-w} displays the full details on the complete +absence of warranty for GNU Emacs. @kbd{C-h n} (@code{view-emacs-news}) +displays the file @file{emacs/etc/NEWS}, which contains documentation on +Emacs changes arranged chronologically. @kbd{C-h F} +(@code{view-emacs-FAQ}) displays the Emacs frequently-answered-questions +list. @kbd{C-h t} (@code{help-with-tutorial}) displays the +learn-by-doing Emacs tutorial. @kbd{C-h C-c} (@code{describe-copying}) +displays the file @file{emacs/etc/COPYING}, which tells you the +conditions you must obey in distributing copies of Emacs. @kbd{C-h C-d} +(@code{describe-distribution}) displays the file +@file{emacs/etc/DISTRIB}, which tells you how you can order a copy of +the latest version of Emacs. @kbd{C-h C-p} (@code{describe-project}) +displays general information about the GNU Project. diff --git a/man/indent.texi b/man/indent.texi new file mode 100644 index 00000000000..2947932cac8 --- /dev/null +++ b/man/indent.texi @@ -0,0 +1,205 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Indentation, Text, Major Modes, Top +@chapter Indentation +@cindex indentation +@cindex columns (indentation) + + This chapter describes the Emacs commands that add, remove, or +adjust indentation. + +@c WideCommands +@table @kbd +@item @key{TAB} +Indent current line ``appropriately'' in a mode-dependent fashion. +@item @kbd{C-j} +Perform @key{RET} followed by @key{TAB} (@code{newline-and-indent}). +@item M-^ +Merge two lines (@code{delete-indentation}). This would cancel out +the effect of @kbd{C-j}. +@item C-M-o +Split line at point; text on the line after point becomes a new line +indented to the same column that it now starts in (@code{split-line}). +@item M-m +Move (forward or back) to the first nonblank character on the current +line (@code{back-to-indentation}). +@item C-M-\ +Indent several lines to same column (@code{indent-region}). +@item C-x @key{TAB} +Shift block of lines rigidly right or left (@code{indent-rigidly}). +@item M-i +Indent from point to the next prespecified tab stop column +(@code{tab-to-tab-stop}). +@item M-x indent-relative +Indent from point to under an indentation point in the previous line. +@end table + + Most programming languages have some indentation convention. For Lisp +code, lines are indented according to their nesting in parentheses. The +same general idea is used for C code, though many details are different. + +@kindex TAB + Whatever the language, to indent a line, use the @key{TAB} command. Each +major mode defines this command to perform the sort of indentation +appropriate for the particular language. In Lisp mode, @key{TAB} aligns +the line according to its depth in parentheses. No matter where in the +line you are when you type @key{TAB}, it aligns the line as a whole. In C +mode, @key{TAB} implements a subtle and sophisticated indentation style that +knows about many aspects of C syntax. + + In Text mode, @key{TAB} runs the command @code{tab-to-tab-stop}, which +indents to the next tab stop column. You can set the tab stops with +@kbd{M-x edit-tab-stops}. + +@menu +* Indentation Commands:: Various commands and techniques for indentation. +* Tab Stops:: You can set arbitrary "tab stops" and then + indent to the next tab stop when you want to. +* Just Spaces:: You can request indentation using just spaces. +@end menu + +@node Indentation Commands, Tab Stops, Indentation, Indentation +@section Indentation Commands and Techniques + +@kindex M-m +@findex back-to-indentation + To move over the indentation on a line, do @kbd{M-m} +(@code{back-to-indentation}). This command, given anywhere on a line, +positions point at the first nonblank character on the line. + + To insert an indented line before the current line, do @kbd{C-a C-o +@key{TAB}}. To make an indented line after the current line, use +@kbd{C-e C-j}. + + If you just want to insert a tab character in the buffer, you can type +@kbd{C-q @key{TAB}}. + +@kindex C-M-o +@findex split-line + @kbd{C-M-o} (@code{split-line}) moves the text from point to the end of +the line vertically down, so that the current line becomes two lines. +@kbd{C-M-o} first moves point forward over any spaces and tabs. Then it +inserts after point a newline and enough indentation to reach the same +column point is on. Point remains before the inserted newline; in this +regard, @kbd{C-M-o} resembles @kbd{C-o}. + +@kindex M-^ +@findex delete-indentation + To join two lines cleanly, use the @kbd{M-^} +(@code{delete-indentation}) command. It deletes the indentation at the +front of the current line, and the line boundary as well, replacing them +with a single space. As a special case (useful for Lisp code) the +single space is omitted if the characters to be joined are consecutive +open parentheses or closing parentheses, or if the junction follows +another newline. To delete just the indentation of a line, go to the +beginning of the line and use @kbd{M-\} +(@code{delete-horizontal-space}), which deletes all spaces and tabs +around the cursor. + + If you have a fill prefix, @kbd{M-^} deletes the fill prefix if it +appears after the newline that is deleted. @xref{Fill Prefix}. + +@kindex C-M-\ +@kindex C-x TAB +@findex indent-region +@findex indent-rigidly + There are also commands for changing the indentation of several lines +at once. @kbd{C-M-\} (@code{indent-region}) applies to all the lines +that begin in the region; it indents each line in the ``usual'' way, as +if you had typed @key{TAB} at the beginning of the line. A numeric +argument specifies the column to indent to, and each line is shifted +left or right so that its first nonblank character appears in that +column. @kbd{C-x @key{TAB}} (@code{indent-rigidly}) moves all of the +lines in the region right by its argument (left, for negative +arguments). The whole group of lines moves rigidly sideways, which is +how the command gets its name.@refill + +@findex indent-relative + @kbd{M-x indent-relative} indents at point based on the previous line +(actually, the last nonempty line). It inserts whitespace at point, moving +point, until it is underneath an indentation point in the previous line. +An indentation point is the end of a sequence of whitespace or the end of +the line. If point is farther right than any indentation point in the +previous line, the whitespace before point is deleted and the first +indentation point then applicable is used. If no indentation point is +applicable even then, @code{indent-relative} runs @code{tab-to-tab-stop} +@ifinfo +(@pxref{Tab Stops}). +@end ifinfo +@iftex +(see next section). +@end iftex + + @code{indent-relative} is the definition of @key{TAB} in Indented Text +mode. @xref{Text}. + + @xref{Format Indentation}, for another way of specifying the +indentation for part of your text. + +@node Tab Stops, Just Spaces, Indentation Commands, Indentation +@section Tab Stops + +@cindex tab stops +@cindex using tab stops in making tables +@cindex tables, indentation for +@kindex M-i +@findex tab-to-tab-stop + For typing in tables, you can use Text mode's definition of @key{TAB}, +@code{tab-to-tab-stop}. This command inserts indentation before point, +enough to reach the next tab stop column. If you are not in Text mode, +this command can be found on the key @kbd{M-i}. + +@findex edit-tab-stops +@findex edit-tab-stops-note-changes +@kindex C-c C-c @r{(Edit Tab Stops)} +@vindex tab-stop-list + You can specify the tab stops used by @kbd{M-i}. They are stored in a +variable called @code{tab-stop-list}, as a list of column-numbers in +increasing order. + + The convenient way to set the tab stops is with @kbd{M-x +edit-tab-stops}, which creates and selects a buffer containing a +description of the tab stop settings. You can edit this buffer to +specify different tab stops, and then type @kbd{C-c C-c} to make those +new tab stops take effect. @code{edit-tab-stops} records which buffer +was current when you invoked it, and stores the tab stops back in that +buffer; normally all buffers share the same tab stops and changing them +in one buffer affects all, but if you happen to make +@code{tab-stop-list} local in one buffer then @code{edit-tab-stops} in +that buffer will edit the local settings. + + Here is what the text representing the tab stops looks like for ordinary +tab stops every eight columns. + +@example + : : : : : : +0 1 2 3 4 +0123456789012345678901234567890123456789012345678 +To install changes, type C-c C-c +@end example + + The first line contains a colon at each tab stop. The remaining lines +are present just to help you see where the colons are and know what to do. + + Note that the tab stops that control @code{tab-to-tab-stop} have nothing +to do with displaying tab characters in the buffer. @xref{Display Vars}, +for more information on that. + +@node Just Spaces,, Tab Stops, Indentation +@section Tabs vs. Spaces + +@vindex indent-tabs-mode + Emacs normally uses both tabs and spaces to indent lines. If you prefer, +all indentation can be made from spaces only. To request this, set +@code{indent-tabs-mode} to @code{nil}. This is a per-buffer variable; +altering the variable affects only the current buffer, but there is a +default value which you can change as well. @xref{Locals}. + +@findex tabify +@findex untabify + There are also commands to convert tabs to spaces or vice versa, always +preserving the columns of all nonblank text. @kbd{M-x tabify} scans the +region for sequences of spaces, and converts sequences of at least three +spaces to tabs if that can be done without changing indentation. @kbd{M-x +untabify} changes all tabs in the region to appropriate numbers of spaces. diff --git a/man/killing.texi b/man/killing.texi new file mode 100644 index 00000000000..ef5e51a14a0 --- /dev/null +++ b/man/killing.texi @@ -0,0 +1,548 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@iftex +@chapter Killing and Moving Text + + @dfn{Killing} means erasing text and copying it into the @dfn{kill +ring}, from which it can be retrieved by @dfn{yanking} it. Some systems +use the terms ``cutting'' and ``pasting'' for these operations. + + The commonest way of moving or copying text within Emacs is to kill it +and later yank it elsewhere in one or more places. This is very safe +because Emacs remembers several recent kills, not just the last one. It +is versatile, because the many commands for killing syntactic units can +also be used for moving those units. But there are other ways of +copying text for special purposes. + + Emacs has only one kill ring for all buffers, so you can kill text in +one buffer and yank it in another buffer. + +@end iftex + +@node Killing, Yanking, Mark, Top +@section Deletion and Killing + +@cindex killing text +@cindex cutting text +@cindex deletion + Most commands which erase text from the buffer save it in the kill +ring so that you can move or copy it to other parts of the buffer. +These commands are known as @dfn{kill} commands. The rest of the +commands that erase text do not save it in the kill ring; they are known +as @dfn{delete} commands. (This distinction is made only for erasure of +text in the buffer.) If you do a kill or delete command by mistake, you +can use the @kbd{C-x u} (@code{undo}) command to undo it +(@pxref{Undo}). + + The delete commands include @kbd{C-d} (@code{delete-char}) and +@key{DEL} (@code{delete-backward-char}), which delete only one character at +a time, and those commands that delete only spaces or newlines. Commands +that can destroy significant amounts of nontrivial data generally kill. +The commands' names and individual descriptions use the words @samp{kill} +and @samp{delete} to say which they do. + +@menu +* Deletion:: Commands for deleting small amounts of text and + blank areas. +* Killing by Lines:: How to kill entire lines of text at one time. +* Other Kill Commands:: Commands to kill large regions of text and + syntactic units such as words and sentences. +@end menu + +@node Deletion +@subsection Deletion +@c ??? Should be backward-delete-char +@findex delete-backward-char +@findex delete-char +@kindex DEL +@kindex C-d + +@table @kbd +@item C-d +Delete next character (@code{delete-char}). +@item @key{DEL} +Delete previous character (@code{delete-backward-char}). +@item M-\ +Delete spaces and tabs around point (@code{delete-horizontal-space}). +@item M-@key{SPC} +Delete spaces and tabs around point, leaving one space +(@code{just-one-space}). +@item C-x C-o +Delete blank lines around the current line (@code{delete-blank-lines}). +@item M-^ +Join two lines by deleting the intervening newline, along with any +indentation following it (@code{delete-indentation}). +@end table + + The most basic delete commands are @kbd{C-d} (@code{delete-char}) and +@key{DEL} (@code{delete-backward-char}). @kbd{C-d} deletes the +character after point, the one the cursor is ``on top of.'' This +doesn't move point. @key{DEL} deletes the character before the cursor, +and moves point back. You can delete newlines like any other characters +in the buffer; deleting a newline joins two lines. Actually, @kbd{C-d} +and @key{DEL} aren't always delete commands; when given arguments, they +kill instead, since they can erase more than one character this way. + +@kindex M-\ +@findex delete-horizontal-space +@kindex M-SPC +@findex just-one-space + The other delete commands are those which delete only whitespace +characters: spaces, tabs and newlines. @kbd{M-\} +(@code{delete-horizontal-space}) deletes all the spaces and tab +characters before and after point. @kbd{M-@key{SPC}} +(@code{just-one-space}) does likewise but leaves a single space after +point, regardless of the number of spaces that existed previously (even +zero). + + @kbd{C-x C-o} (@code{delete-blank-lines}) deletes all blank lines +after the current line. If the current line is blank, it deletes all +blank lines preceding the current line as well (leaving one blank line, +the current line). + + @kbd{M-^} (@code{delete-indentation}) joins the current line and the +previous line, by deleting a newline and all surrounding spaces, usually +leaving a single space. @xref{Indentation,M-^}. + +@node Killing by Lines +@subsection Killing by Lines + +@table @kbd +@item C-k +Kill rest of line or one or more lines (@code{kill-line}). +@end table + +@kindex C-k +@findex kill-line + The simplest kill command is @kbd{C-k}. If given at the beginning of +a line, it kills all the text on the line, leaving it blank. When used +on a blank line, it kills the whole line including its newline. To kill +an entire non-blank line, go to the beginning and type @kbd{C-k} twice. + + More generally, @kbd{C-k} kills from point up to the end of the line, +unless it is at the end of a line. In that case it kills the newline +following point, thus merging the next line into the current one. +Spaces and tabs that you can't see at the end of the line are ignored +when deciding which case applies, so if point appears to be at the end +of the line, you can be sure @kbd{C-k} will kill the newline. + + When @kbd{C-k} is given a positive argument, it kills that many lines +and the newlines that follow them (however, text on the current line +before point is spared). With a negative argument @minus{}@var{n}, it +kills @var{n} lines preceding the current line (together with the text +on the current line before point). Thus, @kbd{C-u - 2 C-k} at the front +of a line kills the two previous lines. + + @kbd{C-k} with an argument of zero kills the text before point on the +current line. + +@vindex kill-whole-line + If the variable @code{kill-whole-line} is non-@code{nil}, @kbd{C-k} at +the very beginning of a line kills the entire line including the +following newline. This variable is normally @code{nil}. + +@node Other Kill Commands +@subsection Other Kill Commands +@findex kill-region +@kindex C-w + +@c DoubleWideCommands +@table @kbd +@item C-w +Kill region (from point to the mark) (@code{kill-region}). +@item M-d +Kill word (@code{kill-word}). @xref{Words}. +@item M-@key{DEL} +Kill word backwards (@code{backward-kill-word}). +@item C-x @key{DEL} +Kill back to beginning of sentence (@code{backward-kill-sentence}). +@xref{Sentences}. +@item M-k +Kill to end of sentence (@code{kill-sentence}). +@item C-M-k +Kill sexp (@code{kill-sexp}). @xref{Lists}. +@item M-z @var{char} +Kill through the next occurrence of @var{char} (@code{zap-to-char}). +@end table + + A kill command which is very general is @kbd{C-w} +(@code{kill-region}), which kills everything between point and the +mark. With this command, you can kill any contiguous sequence of +characters, if you first set the region around them. + +@kindex M-z +@findex zap-to-char + A convenient way of killing is combined with searching: @kbd{M-z} +(@code{zap-to-char}) reads a character and kills from point up to (and +including) the next occurrence of that character in the buffer. A +numeric argument acts as a repeat count. A negative argument means to +search backward and kill text before point. + + Other syntactic units can be killed: words, with @kbd{M-@key{DEL}} and +@kbd{M-d} (@pxref{Words}); sexps, with @kbd{C-M-k} (@pxref{Lists}); and +sentences, with @kbd{C-x @key{DEL}} and @kbd{M-k} +(@pxref{Sentences}).@refill + + You can use kill commands in read-only buffers. They don't actually +change the buffer, and they beep to warn you of that, but they do copy +the text you tried to kill into the kill ring, so you can yank it into +other buffers. Most of the kill commands move point across the text +they copy in this way, so that successive kill commands build up a +single kill ring entry as usual. + +@node Yanking, Accumulating Text, Killing, Top +@section Yanking +@cindex moving text +@cindex copying text +@cindex kill ring +@cindex yanking +@cindex pasting + + @dfn{Yanking} means reinserting text previously killed. This is what +some systems call ``pasting.'' The usual way to move or copy text is to +kill it and then yank it elsewhere one or more times. + +@table @kbd +@item C-y +Yank last killed text (@code{yank}). +@item M-y +Replace text just yanked with an earlier batch of killed text +(@code{yank-pop}). +@item M-w +Save region as last killed text without actually killing it +(@code{kill-ring-save}). +@item C-M-w +Append next kill to last batch of killed text (@code{append-next-kill}). +@end table + +@menu +* Kill Ring:: Where killed text is stored. Basic yanking. +* Appending Kills:: Several kills in a row all yank together. +* Earlier Kills:: Yanking something killed some time ago. +@end menu + +@node Kill Ring +@subsection The Kill Ring + + All killed text is recorded in the @dfn{kill ring}, a list of blocks of +text that have been killed. There is only one kill ring, shared by all +buffers, so you can kill text in one buffer and yank it in another buffer. +This is the usual way to move text from one file to another. +(@xref{Accumulating Text}, for some other ways.) + +@kindex C-y +@findex yank + The command @kbd{C-y} (@code{yank}) reinserts the text of the most recent +kill. It leaves the cursor at the end of the text. It sets the mark at +the beginning of the text. @xref{Mark}. + + @kbd{C-u C-y} leaves the cursor in front of the text, and sets the +mark after it. This happens only if the argument is specified with just +a @kbd{C-u}, precisely. Any other sort of argument, including @kbd{C-u} +and digits, specifies an earlier kill to yank (@pxref{Earlier Kills}). + +@kindex M-w +@findex kill-ring-save + To copy a block of text, you can use @kbd{M-w} +(@code{kill-ring-save}), which copies the region into the kill ring +without removing it from the buffer. This is approximately equivalent +to @kbd{C-w} followed by @kbd{C-x u}, except that @kbd{M-w} does not +alter the undo history and does not temporarily change the screen. + +@node Appending Kills +@subsection Appending Kills + +@cindex appending kills in the ring +@cindex television + Normally, each kill command pushes a new entry onto the kill ring. +However, two or more kill commands in a row combine their text into a +single entry, so that a single @kbd{C-y} yanks all the text as a unit, +just as it was before it was killed. + + Thus, if you want to yank text as a unit, you need not kill all of it +with one command; you can keep killing line after line, or word after +word, until you have killed it all, and you can still get it all back at +once. + + Commands that kill forward from point add onto the end of the previous +killed text. Commands that kill backward from point add text onto the +beginning. This way, any sequence of mixed forward and backward kill +commands puts all the killed text into one entry without rearrangement. +Numeric arguments do not break the sequence of appending kills. For +example, suppose the buffer contains this text: + +@example +This is a line @point{}of sample text. +@end example + +@noindent +with point shown by @point{}. If you type @kbd{M-d M-@key{DEL} M-d +M-@key{DEL}}, killing alternately forward and backward, you end up with +@samp{a line of sample} as one entry in the kill ring, and @samp{This +is@ @ text.} in the buffer. (Note the double space, which you can clean +up with @kbd{M-@key{SPC}} or @kbd{M-q}.) + + Another way to kill the same text is to move back two words with +@kbd{M-b M-b}, then kill all four words forward with @kbd{C-u M-d}. +This produces exactly the same results in the buffer and in the kill +ring. @kbd{M-f M-f C-u M-@key{DEL}} kills the same text, all going +backward; once again, the result is the same. The text in the kill ring +entry always has the same order that it had in the buffer before you +killed it. + +@kindex C-M-w +@findex append-next-kill + If a kill command is separated from the last kill command by other +commands (not just numeric arguments), it starts a new entry on the kill +ring. But you can force it to append by first typing the command +@kbd{C-M-w} (@code{append-next-kill}) right before it. The @kbd{C-M-w} +tells the following command, if it is a kill command, to append the text +it kills to the last killed text, instead of starting a new entry. With +@kbd{C-M-w}, you can kill several separated pieces of text and +accumulate them to be yanked back in one place.@refill + + A kill command following @kbd{M-w} does not append to the text that +@kbd{M-w} copied into the kill ring. + +@node Earlier Kills +@subsection Yanking Earlier Kills + +@cindex yanking previous kills +@kindex M-y +@findex yank-pop + To recover killed text that is no longer the most recent kill, use the +@kbd{M-y} command (@code{yank-pop}). It takes the text previously +yanked and replaces it with the text from an earlier kill. So, to +recover the text of the next-to-the-last kill, first use @kbd{C-y} to +yank the last kill, and then use @kbd{M-y} to replace it with the +previous kill. @kbd{M-y} is allowed only after a @kbd{C-y} or another +@kbd{M-y}. + + You can understand @kbd{M-y} in terms of a ``last yank'' pointer which +points at an entry in the kill ring. Each time you kill, the ``last +yank'' pointer moves to the newly made entry at the front of the ring. +@kbd{C-y} yanks the entry which the ``last yank'' pointer points to. +@kbd{M-y} moves the ``last yank'' pointer to a different entry, and the +text in the buffer changes to match. Enough @kbd{M-y} commands can move +the pointer to any entry in the ring, so you can get any entry into the +buffer. Eventually the pointer reaches the end of the ring; the next +@kbd{M-y} moves it to the first entry again. + + @kbd{M-y} moves the ``last yank'' pointer around the ring, but it does +not change the order of the entries in the ring, which always runs from +the most recent kill at the front to the oldest one still remembered. + + @kbd{M-y} can take a numeric argument, which tells it how many entries +to advance the ``last yank'' pointer by. A negative argument moves the +pointer toward the front of the ring; from the front of the ring, it +moves ``around'' to the last entry and continues forward from there. + + Once the text you are looking for is brought into the buffer, you can +stop doing @kbd{M-y} commands and it will stay there. It's just a copy +of the kill ring entry, so editing it in the buffer does not change +what's in the ring. As long as no new killing is done, the ``last +yank'' pointer remains at the same place in the kill ring, so repeating +@kbd{C-y} will yank another copy of the same previous kill. + + If you know how many @kbd{M-y} commands it would take to find the text +you want, you can yank that text in one step using @kbd{C-y} with a +numeric argument. @kbd{C-y} with an argument restores the text the +specified number of entries back in the kill ring. Thus, @kbd{C-u 2 +C-y} gets the next-to-the-last block of killed text. It is equivalent +to @kbd{C-y M-y}. @kbd{C-y} with a numeric argument starts counting +from the ``last yank'' pointer, and sets the ``last yank'' pointer to +the entry that it yanks. + +@vindex kill-ring-max + The length of the kill ring is controlled by the variable +@code{kill-ring-max}; no more than that many blocks of killed text are +saved. + +@vindex kill-ring + The actual contents of the kill ring are stored in a variable named +@code{kill-ring}; you can view the entire contents of the kill ring with +the command @kbd{C-h v kill-ring}. + +@node Accumulating Text, Rectangles, Yanking, Top +@section Accumulating Text +@findex append-to-buffer +@findex prepend-to-buffer +@findex copy-to-buffer +@findex append-to-file + +@cindex accumulating scattered text + Usually we copy or move text by killing it and yanking it, but there +are other methods convenient for copying one block of text in many +places, or for copying many scattered blocks of text into one place. To +copy one block to many places, store it in a register +(@pxref{Registers}). Here we describe the commands to accumulate +scattered pieces of text into a buffer or into a file. + +@table @kbd +@item M-x append-to-buffer +Append region to contents of specified buffer. +@item M-x prepend-to-buffer +Prepend region to contents of specified buffer. +@item M-x copy-to-buffer +Copy region into specified buffer, deleting that buffer's old contents. +@item M-x insert-buffer +Insert contents of specified buffer into current buffer at point. +@item M-x append-to-file +Append region to contents of specified file, at the end. +@end table + + To accumulate text into a buffer, use @kbd{M-x append-to-buffer}. +This reads a buffer name, then inserts a copy of the region into the +buffer specified. If you specify a nonexistent buffer, +@code{append-to-buffer} creates the buffer. The text is inserted +wherever point is in that buffer. If you have been using the buffer for +editing, the copied text goes into the middle of the text of the buffer, +wherever point happens to be in it. + + Point in that buffer is left at the end of the copied text, so +successive uses of @code{append-to-buffer} accumulate the text in the +specified buffer in the same order as they were copied. Strictly +speaking, @code{append-to-buffer} does not always append to the text +already in the buffer---it appends only if point in that buffer is at the end. +However, if @code{append-to-buffer} is the only command you use to alter +a buffer, then point is always at the end. + + @kbd{M-x prepend-to-buffer} is just like @code{append-to-buffer} +except that point in the other buffer is left before the copied text, so +successive prependings add text in reverse order. @kbd{M-x +copy-to-buffer} is similar except that any existing text in the other +buffer is deleted, so the buffer is left containing just the text newly +copied into it. + + To retrieve the accumulated text from another buffer, use the command +@kbd{M-x insert-buffer}; this too takes @var{buffername} as an argument. +It inserts a copy of the text in buffer @var{buffername} into the +selected buffer. You can alternatively select the other buffer for +editing, then optionally move text from it by killing. @xref{Buffers}, +for background information on buffers. + + Instead of accumulating text within Emacs, in a buffer, you can append +text directly into a file with @kbd{M-x append-to-file}, which takes +@var{filename} as an argument. It adds the text of the region to the end +of the specified file. The file is changed immediately on disk. + + You should use @code{append-to-file} only with files that are +@emph{not} being visited in Emacs. Using it on a file that you are +editing in Emacs would change the file behind Emacs's back, which +can lead to losing some of your editing. + +@node Rectangles, Registers, Accumulating Text, Top +@section Rectangles +@cindex rectangle +@cindex columns (and rectangles) +@cindex killing rectangular areas of text + + The rectangle commands operate on rectangular areas of the text: all +the characters between a certain pair of columns, in a certain range of +lines. Commands are provided to kill rectangles, yank killed rectangles, +clear them out, fill them with blanks or text, or delete them. Rectangle +commands are useful with text in multicolumn formats, and for changing +text into or out of such formats. + + When you must specify a rectangle for a command to work on, you do it +by putting the mark at one corner and point at the opposite corner. The +rectangle thus specified is called the @dfn{region-rectangle} because +you control it in about the same way the region is controlled. But +remember that a given combination of point and mark values can be +interpreted either as a region or as a rectangle, depending on the +command that uses them. + + If point and the mark are in the same column, the rectangle they +delimit is empty. If they are in the same line, the rectangle is one +line high. This asymmetry between lines and columns comes about +because point (and likewise the mark) is between two columns, but within +a line. + +@table @kbd +@item C-x r k +Kill the text of the region-rectangle, saving its contents as the +``last killed rectangle'' (@code{kill-rectangle}). +@item C-x r d +Delete the text of the region-rectangle (@code{delete-rectangle}). +@item C-x r y +Yank the last killed rectangle with its upper left corner at point +(@code{yank-rectangle}). +@item C-x r o +Insert blank space to fill the space of the region-rectangle +(@code{open-rectangle}). This pushes the previous contents of the +region-rectangle rightward. +@item M-x clear-rectangle +Clear the region-rectangle by replacing its contents with spaces. +@item M-x delete-whitespace-rectangle +Delete whitespace in each of the lines on the specified rectangle, +starting from the left edge column of the rectangle. +@item C-x r t @key{RET} @var{string} @key{RET} +Insert @var{string} on each line of the region-rectangle +(@code{string-rectangle}). +@end table + + The rectangle operations fall into two classes: commands deleting and +inserting rectangles, and commands for blank rectangles. + +@kindex C-x r k +@kindex C-x r d +@findex kill-rectangle +@findex delete-rectangle + There are two ways to get rid of the text in a rectangle: you can +discard the text (delete it) or save it as the ``last killed'' +rectangle. The commands for these two ways are @kbd{C-x r d} +(@code{delete-rectangle}) and @kbd{C-x r k} (@code{kill-rectangle}). In +either case, the portion of each line that falls inside the rectangle's +boundaries is deleted, causing following text (if any) on the line to +move left into the gap. + + Note that ``killing'' a rectangle is not killing in the usual sense; the +rectangle is not stored in the kill ring, but in a special place that +can only record the most recent rectangle killed. This is because yanking +a rectangle is so different from yanking linear text that different yank +commands have to be used and yank-popping is hard to make sense of. + +@kindex C-x r y +@findex yank-rectangle + To yank the last killed rectangle, type @kbd{C-x r y} +(@code{yank-rectangle}). Yanking a rectangle is the opposite of killing +one. Point specifies where to put the rectangle's upper left corner. +The rectangle's first line is inserted there, the rectangle's second +line is inserted at a position one line vertically down, and so on. The +number of lines affected is determined by the height of the saved +rectangle. + + You can convert single-column lists into double-column lists using +rectangle killing and yanking; kill the second half of the list as a +rectangle and then yank it beside the first line of the list. +@xref{Two-Column}, for another way to edit multi-column text. + + You can also copy rectangles into and out of registers with @kbd{C-x r +r @var{r}} and @kbd{C-x r i @var{r}}. @xref{RegRect,,Rectangle +Registers}. + +@kindex C-x r o +@findex open-rectangle +@findex clear-rectangle + There are two commands you can use for making blank rectangles: +@kbd{M-x clear-rectangle} which blanks out existing text, and @kbd{C-x r +o} (@code{open-rectangle}) which inserts a blank rectangle. Clearing a +rectangle is equivalent to deleting it and then inserting a blank +rectangle of the same size. + +@findex delete-whitespace-rectangle + The command @kbd{M-x delete-whitespace-rectangle} deletes horizontal +whitespace starting from a particular column. This applies to each of +the lines in the rectangle, and the column is specified by the left +edge of the rectangle. The right edge of the rectangle does not make +any difference to this command. + +@kindex C-x r t +@findex string-rectangle + The command @kbd{C-x r t} (@code{M-x string-rectangle}) replaces the +rectangle with a specified string (inserted once on each line). The +string's width need not be the same as the width of the rectangle. If +the string's width is less, the text after the rectangle shifts left; if +the string is wider than the rectangle, the text after the rectangle +shifts right. diff --git a/man/m-x.texi b/man/m-x.texi new file mode 100644 index 00000000000..785b18c34c8 --- /dev/null +++ b/man/m-x.texi @@ -0,0 +1,72 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node M-x, Help, Minibuffer, Top +@chapter Running Commands by Name + + The Emacs commands that are used often or that must be quick to type are +bound to keys---short sequences of characters---for convenient use. Other +Emacs commands that do not need to be brief are not bound to keys; to run +them, you must refer to them by name. + + A command name is, by convention, made up of one or more words, +separated by hyphens; for example, @code{auto-fill-mode} or +@code{manual-entry}. The use of English words makes the command name +easier to remember than a key made up of obscure characters, even though +it is more characters to type. + +@kindex M-x + The way to run a command by name is to start with @kbd{M-x}, type the +command name, and finish it with @key{RET}. @kbd{M-x} uses the +minibuffer to read the command name. @key{RET} exits the minibuffer and +runs the command. The string @samp{M-x} appears at the beginning of the +minibuffer as a @dfn{prompt} to remind you to enter the name of a +command to be run. @xref{Minibuffer}, for full information on the +features of the minibuffer. + + You can use completion to enter the command name. For example, the +command @code{forward-char} can be invoked by name by typing + +@example +M-x forward-char @key{RET} +@end example + +@noindent +or + +@example +M-x forw @key{TAB} c @key{RET} +@end example + +@noindent +Note that @code{forward-char} is the same command that you invoke with +the key @kbd{C-f}. You can run any Emacs command by name using +@kbd{M-x}, whether or not any keys are bound to it. + + If you type @kbd{C-g} while the command name is being read, you cancel +the @kbd{M-x} command and get out of the minibuffer, ending up at top level. + + To pass a numeric argument to the command you are invoking with +@kbd{M-x}, specify the numeric argument before the @kbd{M-x}. @kbd{M-x} +passes the argument along to the command it runs. The argument value +appears in the prompt while the command name is being read. + +@vindex suggest-key-bindings + If the command you type has a key binding of its own, Emacs mentions +this in the echo area, two seconds after the command finishes (if you +don't type anything else first). For example, if you type @kbd{M-x +forward-word}, the message says that you can run the same command more +easily by typing @kbd{M-f}. You can turn off these messages by setting +@code{suggest-key-bindings} to @code{nil}. + + Normally, when describing in this manual a command that is run by +name, we omit the @key{RET} that is needed to terminate the name. Thus +we might speak of @kbd{M-x auto-fill-mode} rather than @kbd{M-x +auto-fill-mode @key{RET}}. We mention the @key{RET} only when there is +a need to emphasize its presence, such as when we show the command +together with following arguments. + +@findex execute-extended-command + @kbd{M-x} works by running the command +@code{execute-extended-command}, which is responsible for reading the +name of another command and invoking it. diff --git a/man/major.texi b/man/major.texi new file mode 100644 index 00000000000..e7ab4176060 --- /dev/null +++ b/man/major.texi @@ -0,0 +1,169 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Major Modes, Indentation, International, Top +@chapter Major Modes +@cindex major modes +@cindex mode, major +@kindex TAB @r{(and major modes)} +@kindex DEL @r{(and major modes)} +@kindex C-j @r{(and major modes)} + + Emacs provides many alternative @dfn{major modes}, each of which +customizes Emacs for editing text of a particular sort. The major modes +are mutually exclusive, and each buffer has one major mode at any time. +The mode line normally shows the name of the current major mode, in +parentheses (@pxref{Mode Line}). + + The least specialized major mode is called @dfn{Fundamental mode}. +This mode has no mode-specific redefinitions or variable settings, so +that each Emacs command behaves in its most general manner, and each +option is in its default state. For editing text of a specific type +that Emacs knows about, such as Lisp code or English text, you should +switch to the appropriate major mode, such as Lisp mode or Text mode. + + Selecting a major mode changes the meanings of a few keys to become +more specifically adapted to the language being edited. The ones that +are changed frequently are @key{TAB}, @key{DEL}, and @kbd{C-j}. The +prefix key @kbd{C-c} normally contains mode-specific commands. In +addition, the commands which handle comments use the mode to determine +how comments are to be delimited. Many major modes redefine the +syntactical properties of characters appearing in the buffer. +@xref{Syntax}. + + The major modes fall into three major groups. Lisp mode (which has +several variants), C mode, Fortran mode and others are for specific +programming languages. Text mode, Nroff mode, @TeX{} mode and Outline +mode are for editing English text. The remaining major modes are not +intended for use on users' files; they are used in buffers created for +specific purposes by Emacs, such as Dired mode for buffers made by Dired +(@pxref{Dired}), Mail mode for buffers made by @kbd{C-x m} +(@pxref{Sending Mail}), and Shell mode for buffers used for +communicating with an inferior shell process (@pxref{Interactive +Shell}). + + Most programming-language major modes specify that only blank lines +separate paragraphs. This is to make the paragraph commands useful. +(@xref{Paragraphs}.) They also cause Auto Fill mode to use the +definition of @key{TAB} to indent the new lines it creates. This is +because most lines in a program are usually indented. +(@xref{Indentation}.) + +@menu +* Choosing Modes:: How major modes are specified or chosen. +@end menu + +@node Choosing Modes,,Major Modes,Major Modes +@section How Major Modes are Chosen + +@cindex choosing a major mode + You can select a major mode explicitly for the current buffer, but +most of the time Emacs determines which mode to use based on the file +name or on special text in the file. + + Explicit selection of a new major mode is done with a @kbd{M-x} command. +From the name of a major mode, add @code{-mode} to get the name of a +command to select that mode. Thus, you can enter Lisp mode by executing +@kbd{M-x lisp-mode}. + +@vindex auto-mode-alist + When you visit a file, Emacs usually chooses the right major mode based +on the file's name. For example, files whose names end in @samp{.c} are +edited in C mode. The correspondence between file names and major modes is +controlled by the variable @code{auto-mode-alist}. Its value is a list in +which each element has this form, + +@example +(@var{regexp} . @var{mode-function}) +@end example + +@noindent +or this form, + +@example +(@var{regexp} @var{mode-function} @var{flag}) +@end example + +@noindent +For example, one element normally found in the list has the form +@code{(@t{"\\.c\\'"} . c-mode)}, and it is responsible for selecting C +mode for files whose names end in @file{.c}. (Note that @samp{\\} is +needed in Lisp syntax to include a @samp{\} in the string, which is +needed to suppress the special meaning of @samp{.} in regexps.) If the +element has the form @code{(@var{regexp} @var{mode-function} +@var{flag})} and @var{flag} is non-@code{nil}, then after calling +@var{function}, the suffix that matched @var{regexp} is discarded and +the list is searched again for another match. + + You can specify which major mode should be used for editing a certain +file by a special sort of text in the first nonblank line of the file. The +mode name should appear in this line both preceded and followed by +@samp{-*-}. Other text may appear on the line as well. For example, + +@example +;-*-Lisp-*- +@end example + +@noindent +tells Emacs to use Lisp mode. Such an explicit specification overrides +any defaulting based on the file name. Note how the semicolon is used +to make Lisp treat this line as a comment. + + Another format of mode specification is + +@example +-*- mode: @var{modename};-*- +@end example + +@noindent +which allows you to specify local variables as well, like this: + +@example +-*- mode: @var{modename}; @var{var}: @var{value}; @dots{} -*- +@end example + +@noindent +@xref{File Variables}, for more information about this. + +@vindex interpreter-mode-alist + When a file's contents begin with @samp{#!}, it can serve as an +executable shell command, which works by running an interpreter named on +the file's first line. The rest of the file is used as input to the +interpreter. + + When you visit such a file in Emacs, if the file's name does not +specify a major mode, Emacs uses the interpreter name on the first line +to choose a mode. If the first line is the name of a recognized +interpreter program, such as @samp{perl} or @samp{tcl}, Emacs uses a +mode appropriate for programs for that interpreter. The variable +@code{interpreter-mode-alist} specifies the correspondence between +interpreter program names and major modes. + + When the first line starts with @samp{#!}, you cannot (on many +systems) use the @samp{-*-} feature on the first line, because the +system would get confused when running the interpreter. So Emacs looks +for @samp{-*-} on the second line in such files as well as on the +first line. + +@vindex default-major-mode + When you visit a file that does not specify a major mode to use, or +when you create a new buffer with @kbd{C-x b}, the variable +@code{default-major-mode} specifies which major mode to use. Normally +its value is the symbol @code{fundamental-mode}, which specifies +Fundamental mode. If @code{default-major-mode} is @code{nil}, the major +mode is taken from the previously selected buffer. + +@findex normal-mode + If you change the major mode of a buffer, you can go back to the major +mode Emacs would choose automatically: use the command @kbd{M-x +normal-mode} to do this. This is the same function that +@code{find-file} calls to choose the major mode. It also processes +the file's local variables list if any. + +@vindex change-major-mode-with-file-name + The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to +a new major mode if the new file name implies a mode (@pxref{Saving}). +However, this does not happen if the buffer contents specify a major +mode, and certain ``special'' major modes do not allow the mode to +change. You can turn off this mode-changing feature by setting +@code{change-major-mode-with-file-name} to @code{nil}. diff --git a/man/mark.texi b/man/mark.texi new file mode 100644 index 00000000000..311a0c6923b --- /dev/null +++ b/man/mark.texi @@ -0,0 +1,351 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Mark, Killing, Help, Top +@chapter The Mark and the Region +@cindex mark +@cindex setting a mark +@cindex region + + Many Emacs commands operate on an arbitrary contiguous part of the +current buffer. To specify the text for such a command to operate on, +you set @dfn{the mark} at one end of it, and move point to the other +end. The text between point and the mark is called @dfn{the region}. +Emacs highlights the region whenever there is one, if you enable +Transient Mark mode (@pxref{Transient Mark}). + + You can move point or the mark to adjust the boundaries of the region. +It doesn't matter which one is set first chronologically, or which one +comes earlier in the text. Once the mark has been set, it remains where +you put it until you set it again at another place. Each Emacs buffer +has its own mark, so that when you return to a buffer that had been +selected previously, it has the same mark it had before. + + Many commands that insert text, such as @kbd{C-y} (@code{yank}) and +@kbd{M-x insert-buffer}, position point and the mark at opposite ends of +the inserted text, so that the region contains the text just inserted. + + Aside from delimiting the region, the mark is also useful for +remembering a spot that you may want to go back to. To make this +feature more useful, each buffer remembers 16 previous locations of the +mark in the @dfn{mark ring}. + +@menu +* Setting Mark:: Commands to set the mark. +* Transient Mark:: How to make Emacs highlight the region-- + when there is one. +* Using Region:: Summary of ways to operate on contents of the region. +* Marking Objects:: Commands to put region around textual units. +* Mark Ring:: Previous mark positions saved so you can go back there. +* Global Mark Ring:: Previous mark positions in various buffers. +@end menu + +@node Setting Mark +@section Setting the Mark + + Here are some commands for setting the mark: + +@c WideCommands +@table @kbd +@item C-@key{SPC} +Set the mark where point is (@code{set-mark-command}). +@item C-@@ +The same. +@item C-x C-x +Interchange mark and point (@code{exchange-point-and-mark}). +@item Drag-Mouse-1 +Set point and the mark around the text you drag across. +@item Mouse-3 +Set the mark where point is, then move point to where you click +(@code{mouse-save-then-kill}). +@end table + + For example, suppose you wish to convert part of the buffer to +upper case, using the @kbd{C-x C-u} (@code{upcase-region}) command, +which operates on the text in the region. You can first go to the +beginning of the text to be capitalized, type @kbd{C-@key{SPC}} to put +the mark there, move to the end, and then type @kbd{C-x C-u}. Or, you +can set the mark at the end of the text, move to the beginning, and then +type @kbd{C-x C-u}. + +@kindex C-SPC +@findex set-mark-command + The most common way to set the mark is with the @kbd{C-@key{SPC}} command +(@code{set-mark-command}). This sets the mark where point is. Then you +can move point away, leaving the mark behind. + + There are two ways to set the mark with the mouse. You can drag mouse +button one across a range of text; that puts point where you release the +mouse button, and sets the mark at the other end of that range. Or you +can click mouse button three, which sets the mark at point (like +@kbd{C-@key{SPC}}) and then moves point (like @kbd{Mouse-1}). Both of +these methods copy the region into the kill ring in addition to setting +the mark; that gives behavior consistent with other window-driven +applications, but if you don't want to modify the kill ring, you must +use keyboard commands to set the mark. @xref{Mouse Commands}. + +@kindex C-x C-x +@findex exchange-point-and-mark + Ordinary terminals have only one cursor, so there is no way for Emacs +to show you where the mark is located. You have to remember. The usual +solution to this problem is to set the mark and then use it soon, before +you forget where it is. Alternatively, you can see where the mark is +with the command @kbd{C-x C-x} (@code{exchange-point-and-mark}) which +puts the mark where point was and point where the mark was. The extent +of the region is unchanged, but the cursor and point are now at the +previous position of the mark. In Transient Mark mode, this command +reactivates the mark. + + @kbd{C-x C-x} is also useful when you are satisfied with the position +of point but want to move the other end of the region (where the mark +is); do @kbd{C-x C-x} to put point at that end of the region, and then +move it. A second use of @kbd{C-x C-x}, if necessary, puts the mark at +the new position with point back at its original position. + +@kindex C-@@ + There is no such character as @kbd{C-@key{SPC}} in ASCII; when you +type @key{SPC} while holding down @key{CTRL}, what you get on most +ordinary terminals is the character @kbd{C-@@}. This key is actually +bound to @code{set-mark-command}. But unless you are unlucky enough to +have a terminal where typing @kbd{C-@key{SPC}} does not produce +@kbd{C-@@}, you might as well think of this character as +@kbd{C-@key{SPC}}. Under X, @kbd{C-@key{SPC}} is actually a distinct +character, but its binding is still @code{set-mark-command}. + +@node Transient Mark +@section Transient Mark Mode +@cindex mode, Transient Mark +@cindex Transient Mark mode +@cindex highlighting region +@cindex region highlighting + + Emacs can highlight the current region, using X Windows. But normally +it does not. Why not? + + Highlighting the region doesn't work well ordinarily in Emacs, because +once you have set a mark, there is @emph{always} a region (in that +buffer). And highlighting the region all the time would be a nuisance. + + You can turn on region highlighting by enabling Transient Mark mode. +This is a more rigid mode of operation in which the region ``lasts'' +only temporarily, so you must set up a region for each command that uses +one. In Transient Mark mode, most of the time there is no region; +therefore, highlighting the region when it exists is convenient. + +@findex transient-mark-mode + To enable Transient Mark mode, type @kbd{M-x transient-mark-mode}. +This command toggles the mode, so you can repeat the command to turn off +the mode. + + Here are the details of Transient Mark mode: + +@itemize @bullet +@item +To set the mark, type @kbd{C-@key{SPC}} (@code{set-mark-command}). +This makes the mark active; as you move point, you will see the region +highlighting grow and shrink. + +@item +The mouse commands for specifying the mark also make it active. So do +keyboard commands whose purpose is to specify a region, including +@kbd{M-@@}, @kbd{C-M-@@}, @kbd{M-h}, @kbd{C-M-h}, @kbd{C-x C-p}, and +@kbd{C-x h}. + +@item +When the mark is active, you can execute commands that operate on the +region, such as killing, indenting, or writing to a file. + +@item +Any change to the buffer, such as inserting or deleting a character, +deactivates the mark. This means any subsequent command that operates +on a region will get an error and refuse to operate. You can make the +region active again by typing @kbd{C-x C-x}. + +@item +Commands like @kbd{M->} and @kbd{C-s} that ``leave the mark behind'' in +addition to some other primary purpose do not activate the new mark. +You can activate the new region by executing @kbd{C-x C-x} +(@code{exchange-point-and-mark}). + +@item +@kbd{C-s} when the mark is active does not alter the mark. + +@item +Quitting with @kbd{C-g} deactivates the mark. +@end itemize + + Highlighting of the region uses the @code{region} face; you can +customize how the region is highlighted by changing this face. +@xref{Face Customization}. + +@vindex highlight-nonselected-windows + When multiple windows show the same buffer, they can have different +regions, because they can have different values of point (though they +all share one common mark position). Ordinarily, only the selected +window highlights its region (@pxref{Windows}). However, if the +variable @code{highlight-nonselected-windows} is non-@code{nil}, then +each window highlights its own region (provided that Transient Mark mode +is enabled and the window's buffer's mark is active). + + When Transient Mark mode is not enabled, every command that sets the +mark also activates it, and nothing ever deactivates it. + +@vindex mark-even-if-inactive + If the variable @code{mark-even-if-inactive} is non-@code{nil} in +Transient Mark mode, then commands can use the mark and the region +even when it is inactive. Region highlighting appears and disappears +just as it normally does in Transient Mark mode, but the mark doesn't +really go away when the highlighting disappears. + +@cindex Zmacs mode + Transient Mark mode is also sometimes known as ``Zmacs mode'' +because the Zmacs editor on the MIT Lisp Machine handled the mark in a +similar way. + +@node Using Region +@section Operating on the Region + +@cindex operations on a marked region + Once you have a region and the mark is active, here are some of the +ways you can operate on the region: + +@itemize @bullet +@item +Kill it with @kbd{C-w} (@pxref{Killing}). +@item +Save it in a register with @kbd{C-x r s} (@pxref{Registers}). +@item +Save it in a buffer or a file (@pxref{Accumulating Text}). +@item +Convert case with @kbd{C-x C-l} or @kbd{C-x C-u} (@pxref{Case}). +@item +Indent it with @kbd{C-x @key{TAB}} or @kbd{C-M-\} (@pxref{Indentation}). +@item +Fill it as text with @kbd{M-x fill-region} (@pxref{Filling}). +@item +Print hardcopy with @kbd{M-x print-region} (@pxref{Hardcopy}). +@item +Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}). +@end itemize + + Most commands that operate on the text in the +region have the word @code{region} in their names. + +@node Marking Objects +@section Commands to Mark Textual Objects + +@cindex marking sections of text + Here are the commands for placing point and the mark around a textual +object such as a word, list, paragraph or page. + +@table @kbd +@item M-@@ +Set mark after end of next word (@code{mark-word}). This command and +the following one do not move point. +@item C-M-@@ +Set mark after end of next Lisp expression (@code{mark-sexp}). +@item M-h +Put region around current paragraph (@code{mark-paragraph}). +@item C-M-h +Put region around current Lisp defun (@code{mark-defun}). +@item C-x h +Put region around entire buffer (@code{mark-whole-buffer}). +@item C-x C-p +Put region around current page (@code{mark-page}). +@end table + +@kbd{M-@@} (@code{mark-word}) puts the mark at the end of the next word, +while @kbd{C-M-@@} (@code{mark-sexp}) puts it at the end of the next Lisp +expression. These commands handle arguments just like @kbd{M-f} and +@kbd{C-M-f}. + +@kindex C-x h +@findex mark-whole-buffer + Other commands set both point and mark, to delimit an object in the +buffer. For example, @kbd{M-h} (@code{mark-paragraph}) moves point to +the beginning of the paragraph that surrounds or follows point, and puts +the mark at the end of that paragraph (@pxref{Paragraphs}). It prepares +the region so you can indent, case-convert, or kill a whole paragraph. + + @kbd{C-M-h} (@code{mark-defun}) similarly puts point before and the +mark after the current or following defun (@pxref{Defuns}). @kbd{C-x +C-p} (@code{mark-page}) puts point before the current page, and mark at +the end (@pxref{Pages}). The mark goes after the terminating page +delimiter (to include it), while point goes after the preceding page +delimiter (to exclude it). A numeric argument specifies a later page +(if positive) or an earlier page (if negative) instead of the current +page. + + Finally, @kbd{C-x h} (@code{mark-whole-buffer}) sets up the entire +buffer as the region, by putting point at the beginning and the mark at +the end. + + In Transient Mark mode, all of these commands activate the mark. + +@node Mark Ring +@section The Mark Ring + +@kindex C-u C-SPC +@cindex mark ring +@kindex C-u C-@@ + Aside from delimiting the region, the mark is also useful for +remembering a spot that you may want to go back to. To make this +feature more useful, each buffer remembers 16 previous locations of the +mark, in the @dfn{mark ring}. Commands that set the mark also push the +old mark onto this ring. To return to a marked location, use @kbd{C-u +C-@key{SPC}} (or @kbd{C-u C-@@}); this is the command +@code{set-mark-command} given a numeric argument. It moves point to +where the mark was, and restores the mark from the ring of former +marks. Thus, repeated use of this command moves point to all of the old +marks on the ring, one by one. The mark positions you move through in +this way are not lost; they go to the end of the ring. + + Each buffer has its own mark ring. All editing commands use the current +buffer's mark ring. In particular, @kbd{C-u C-@key{SPC}} always stays in +the same buffer. + + Many commands that can move long distances, such as @kbd{M-<} +(@code{beginning-of-buffer}), start by setting the mark and saving the +old mark on the mark ring. This is to make it easier for you to move +back later. Searches set the mark if they move point. You can tell +when a command sets the mark because it displays @samp{Mark Set} in the +echo area. + + If you want to move back to the same place over and over, the mark +ring may not be convenient enough. If so, you can record the position +in a register for later retrieval (@pxref{RegPos}). + +@vindex mark-ring-max + The variable @code{mark-ring-max} specifies the maximum number of +entries to keep in the mark ring. If that many entries exist and +another one is pushed, the last one in the list is discarded. Repeating +@kbd{C-u C-@key{SPC}} cycles through the positions currently in the +ring. + +@vindex mark-ring + The variable @code{mark-ring} holds the mark ring itself, as a list of +marker objects, with the most recent first. This variable is local in +every buffer. + +@node Global Mark Ring +@section The Global Mark Ring +@cindex global mark ring + + In addition to the ordinary mark ring that belongs to each buffer, +Emacs has a single @dfn{global mark ring}. It records a sequence of +buffers in which you have recently set the mark, so you can go back +to those buffers. + + Setting the mark always makes an entry on the current buffer's mark +ring. If you have switched buffers since the previous mark setting, the +new mark position makes an entry on the global mark ring also. The +result is that the global mark ring records a sequence of buffers that +you have been in, and, for each buffer, a place where you set the mark. + +@kindex C-x C-@key{SPC} +@findex pop-global-mark + The command @kbd{C-x C-@key{SPC}} (@code{pop-global-mark}) jumps to +the buffer and position of the latest entry in the global ring. It also +rotates the ring, so that successive uses of @kbd{C-x C-@key{SPC}} take +you to earlier and earlier buffers. + diff --git a/man/message.texi b/man/message.texi new file mode 100644 index 00000000000..054b0036a7e --- /dev/null +++ b/man/message.texi @@ -0,0 +1,1325 @@ +\input texinfo @c -*-texinfo-*- + +@setfilename ../info/message +@settitle Message 5.7 Manual +@synindex fn cp +@synindex vr cp +@synindex pg cp +@direntry +* Message: (message). Mail and news composition mode that goes with Gnus. +@end direntry +@iftex +@finalout +@end iftex +@setchapternewpage odd + +@ifinfo + +This file documents Message, the Emacs message composition mode. + +Copyright (C) 1996 Free Software Foundation, Inc. + +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 +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + +@tex + +@titlepage +@title Message 5.7 Manual + +@author by Lars Magne Ingebrigtsen +@page + +@vskip 0pt plus 1filll +Copyright @copyright{} 1996 Free Software Foundation, Inc. + +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. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. + +@end titlepage +@page + +@end tex + +@node Top +@top Message + +All message composition from Gnus (both mail and news) takes place in +Message mode buffers. + +@menu +* Interface:: Setting up message buffers. +* Commands:: Commands you can execute in message mode buffers. +* Variables:: Customizing the message buffers. +* Compatibility:: Making Message backwards compatible. +* Appendices:: More technical things. +* Index:: Variable, function and concept index. +* Key Index:: List of Message mode keys. +@end menu + +This manual corresponds to Message 5.7. Message is distributed with +the Gnus distribution bearing the same version number as this manual +has. + + +@node Interface +@chapter Interface + +When a program (or a person) wants to respond to a message -- reply, +follow up, forward, cancel -- the program (or person) should just put +point in the buffer where the message is and call the required command. +@code{Message} will then pop up a new @code{message} mode buffer with +appropriate headers filled out, and the user can edit the message before +sending it. + +@menu +* New Mail Message:: Editing a brand new mail message. +* New News Message:: Editing a brand new news message. +* Reply:: Replying via mail. +* Wide Reply:: Responding to all people via mail. +* Followup:: Following up via news. +* Canceling News:: Canceling a news article. +* Superseding:: Superseding a message. +* Forwarding:: Forwarding a message via news or mail. +* Resending:: Resending a mail message. +* Bouncing:: Bouncing a mail message. +@end menu + + +@node New Mail Message +@section New Mail Message + +@findex message-mail +The @code{message-mail} command pops up a new message buffer. + +Two optional parameters are accepted: The first will be used as the +@code{To} header and the second as the @code{Subject} header. If these +are @code{nil}, those two headers will be empty. + + +@node New News Message +@section New News Message + +@findex message-news +The @code{message-news} command pops up a new message buffer. + +This function accepts two optional parameters. The first will be used +as the @code{Newsgroups} header and the second as the @code{Subject} +header. If these are @code{nil}, those two headers will be empty. + + +@node Reply +@section Reply + +@findex message-reply +The @code{message-reply} function pops up a message buffer that's a +reply to the message in the current buffer. + +@vindex message-reply-to-function +Message uses the normal methods to determine where replies are to go +(@pxref{Responses}), but you can change the behavior to suit your needs +by fiddling with the @code{message-reply-to-function} variable. + +If you want the replies to go to the @code{Sender} instead of the +@code{From}, you could do something like this: + +@lisp +(setq message-reply-to-function + (lambda () + (cond ((equal (mail-fetch-field "from") "somebody") + (mail-fetch-field "sender")) + (t + nil)))) +@end lisp + +This function will be called narrowed to the head of the article that is +being replied to. + +As you can see, this function should return a string if it has an +opinion as to what the To header should be. If it does not, it should +just return @code{nil}, and the normal methods for determining the To +header will be used. + +This function can also return a list. In that case, each list element +should be a cons, where the car should be the name of an header +(eg. @code{Cc}) and the cdr should be the header value +(eg. @samp{larsi@@ifi.uio.no}). All these headers will be inserted into +the head of the outgoing mail. + + +@node Wide Reply +@section Wide Reply + +@findex message-wide-reply +The @code{message-wide-reply} pops up a message buffer that's a wide +reply to the message in the current buffer. A @dfn{wide reply} is a +reply that goes out to all people listed in the @code{To}, @code{From} +(or @code{Reply-to}) and @code{Cc} headers. + +@vindex message-wide-reply-to-function +Message uses the normal methods to determine where wide replies are to go, +but you can change the behavior to suit your needs by fiddling with the +@code{message-wide-reply-to-function}. It is used in the same way as +@code{message-reply-to-function} (@pxref{Reply}). + +@findex rmail-dont-reply-to-names +Addresses that match the @code{rmail-dont-reply-to-names} regular +expression will be removed from the @code{Cc} header. + + +@node Followup +@section Followup + +@findex message-followup +The @code{message-followup} command pops up a message buffer that's a +followup to the message in the current buffer. + +@vindex message-followup-to-function +Message uses the normal methods to determine where followups are to go, +but you can change the behavior to suit your needs by fiddling with the +@code{message-followup-to-function}. It is used in the same way as +@code{message-reply-to-function} (@pxref{Reply}). + +@vindex message-use-followup-to +The @code{message-use-followup-to} variable says what to do about +@code{Followup-To} headers. If it is @code{use}, always use the value. +If it is @code{ask} (which is the default), ask whether to use the +value. If it is @code{t}, use the value unless it is @samp{poster}. If +it is @code{nil}, don't use the value. + + +@node Canceling News +@section Canceling News + +@findex message-cancel-news +The @code{message-cancel-news} command cancels the article in the +current buffer. + + +@node Superseding +@section Superseding + +@findex message-supersede +The @code{message-supersede} command pops up a message buffer that will +supersede the message in the current buffer. + +@vindex message-ignored-supersedes-headers +Headers matching the @code{message-ignored-supersedes-headers} are +removed before popping up the new message buffer. The default is@* +@samp{^Path:\\|^Date\\|^NNTP-Posting-Host:\\|^Xref:\\|^Lines:\\|@* +^Received:\\|^X-From-Line:\\|Return-Path:\\|^Supersedes:}. + + + +@node Forwarding +@section Forwarding + +@findex message-forward +The @code{message-forward} command pops up a message buffer to forward +the message in the current buffer. If given a prefix, forward using +news. + +@table @code +@item message-forward-start-separator +@vindex message-forward-start-separator +Delimiter inserted before forwarded messages. The default is@* +@samp{------- Start of forwarded message -------\n}. + +@vindex message-forward-end-separator +@item message-forward-end-separator +@vindex message-forward-end-separator +Delimiter inserted after forwarded messages. The default is@* +@samp{------- End of forwarded message -------\n}. + +@item message-signature-before-forwarded-message +@vindex message-signature-before-forwarded-message +If this variable is @code{t}, which it is by default, your personal +signature will be inserted before the forwarded message. If not, the +forwarded message will be inserted first in the new mail. + +@item message-included-forward-headers +@vindex message-included-forward-headers +Regexp matching header lines to be included in forwarded messages. + +@item message-make-forward-subject-function +@vindex message-make-forward-subject-function +A list of functions that are called to generate a subject header for +forwarded messages. The subject generated by the previous function is +passed into each successive function. + +The provided functions are: + +@table @code +@item message-forward-subject-author-subject +@findex message-forward-subject-author-subject +Source of article (author or newsgroup), in brackets followed by the +subject. + +@item message-forward-subject-fwd +Subject of article with @samp{Fwd:} prepended to it. +@end table + +@item message-wash-forwarded-subjects +@vindex message-wash-forwarded-subjects +If this variable is @code{t}, the subjects of forwarded messages have +the evidence of previous forwards (such as @samp{Fwd:}, @samp{Re:}, +@samp{(fwd)}) removed before the new subject is +constructed. The default value is @code{nil}. + +@end table + + +@node Resending +@section Resending + +@findex message-resend +The @code{message-resend} command will prompt the user for an address +and resend the message in the current buffer to that address. + +@vindex message-ignored-resent-headers +Headers that match the @code{message-ignored-resent-headers} regexp will +be removed before sending the message. The default is +@samp{^Return-receipt}. + + +@node Bouncing +@section Bouncing + +@findex message-bounce +The @code{message-bounce} command will, if the current buffer contains a +bounced mail message, pop up a message buffer stripped of the bounce +information. A @dfn{bounced message} is typically a mail you've sent +out that has been returned by some @code{mailer-daemon} as +undeliverable. + +@vindex message-ignored-bounced-headers +Headers that match the @code{message-ignored-bounced-headers} regexp +will be removed before popping up the buffer. The default is +@samp{^\\(Received\\|Return-Path\\):}. + + +@node Commands +@chapter Commands + +@menu +* Header Commands:: Commands for moving to headers. +* Movement:: Moving around in message buffers. +* Insertion:: Inserting things into message buffers. +* Various Commands:: Various things. +* Sending:: Actually sending the message. +* Mail Aliases:: How to use mail aliases. +@end menu + + +@node Header Commands +@section Header Commands + +All these commands move to the header in question. If it doesn't exist, +it will be inserted. + +@table @kbd + +@item C-c ? +@kindex C-c ? +@findex message-goto-to +Describe the message mode. + +@item C-c C-f C-t +@kindex C-c C-f C-t +@findex message-goto-to +Go to the @code{To} header (@code{message-goto-to}). + +@item C-c C-f C-b +@kindex C-c C-f C-b +@findex message-goto-bcc +Go to the @code{Bcc} header (@code{message-goto-bcc}). + +@item C-c C-f C-f +@kindex C-c C-f C-f +@findex message-goto-fcc +Go to the @code{Fcc} header (@code{message-goto-fcc}). + +@item C-c C-f C-c +@kindex C-c C-f C-c +@findex message-goto-cc +Go to the @code{Cc} header (@code{message-goto-cc}). + +@item C-c C-f C-s +@kindex C-c C-f C-s +@findex message-goto-subject +Go to the @code{Subject} header (@code{message-goto-subject}). + +@item C-c C-f C-r +@kindex C-c C-f C-r +@findex message-goto-reply-to +Go to the @code{Reply-To} header (@code{message-goto-reply-to}). + +@item C-c C-f C-n +@kindex C-c C-f C-n +@findex message-goto-newsgroups +Go to the @code{Newsgroups} header (@code{message-goto-newsgroups}). + +@item C-c C-f C-d +@kindex C-c C-f C-d +@findex message-goto-distribution +Go to the @code{Distribution} header (@code{message-goto-distribution}). + +@item C-c C-f C-o +@kindex C-c C-f C-o +@findex message-goto-followup-to +Go to the @code{Followup-To} header (@code{message-goto-followup-to}). + +@item C-c C-f C-k +@kindex C-c C-f C-k +@findex message-goto-keywords +Go to the @code{Keywords} header (@code{message-goto-keywords}). + +@item C-c C-f C-u +@kindex C-c C-f C-u +@findex message-goto-summary +Go to the @code{Summary} header (@code{message-goto-summary}). + +@end table + + +@node Movement +@section Movement + +@table @kbd +@item C-c C-b +@kindex C-c C-b +@findex message-goto-body +Move to the beginning of the body of the message +(@code{message-goto-body}). + +@item C-c C-i +@kindex C-c C-i +@findex message-goto-signature +Move to the signature of the message (@code{message-goto-signature}). + +@end table + + +@node Insertion +@section Insertion + +@table @kbd + +@item C-c C-y +@kindex C-c C-y +@findex message-yank-original +Yank the message that's being replied to into the message buffer +(@code{message-yank-original}). + +@item C-c C-q +@kindex C-c C-q +@findex message-fill-yanked-message +Fill the yanked message (@code{message-fill-yanked-message}). Warning: +Can severely mess up the yanked text if its quoting conventions are +strange. You'll quickly get a feel for when it's safe, though. Anyway, +just remember that @kbd{C-x u} (@code{undo}) is available and you'll be +all right. + + +@item C-c C-w +@kindex C-c C-w +@findex message-insert-signature +Insert a signature at the end of the buffer +(@code{message-insert-signature}). + +@end table + +@table @code +@item message-ignored-cited-headers +@vindex message-ignored-cited-headers +All headers that match this regexp will be removed from yanked +messages. The default is @samp{.}, which means that all headers will be +removed. + +@item message-citation-line-function +@vindex message-citation-line-function +Function called to insert the citation line. The default is +@code{message-insert-citation-line}, which will lead to citation lines +that look like: + +@example +Hallvard B Furuseth <h.b.furuseth@@usit.uio.no> writes: +@end example + +Point will be at the beginning of the body of the message when this +function is called. + +@item message-yank-prefix +@vindex message-yank-prefix +@cindex yanking +@cindex quoting +When you are replying to or following up an article, you normally want +to quote the person you are answering. Inserting quoted text is done by +@dfn{yanking}, and each quoted line you yank will have +@code{message-yank-prefix} prepended to it. The default is @samp{> }. +If it is @code{nil}, just indent the message. + +@item message-indentation-spaces +@vindex message-indentation-spaces +Number of spaces to indent yanked messages. + +@item message-cite-function +@vindex message-cite-function +@findex message-cite-original +@findex sc-cite-original +@findex message-cite-original-without-signature +@cindex Supercite +Function for citing an original message. The default is +@code{message-cite-original}, which simply inserts the original message +and prepends @samp{> } to each line. +@code{message-cite-original-without-signature} does the same, but elides +the signature. You can also set it to @code{sc-cite-original} to use +Supercite. + +@item message-indent-citation-function +@vindex message-indent-citation-function +Function for modifying a citation just inserted in the mail buffer. +This can also be a list of functions. Each function can find the +citation between @code{(point)} and @code{(mark t)}. And each function +should leave point and mark around the citation text as modified. + +@item message-signature +@vindex message-signature +String to be inserted at the end of the message buffer. If @code{t} +(which is the default), the @code{message-signature-file} file will be +inserted instead. If a function, the result from the function will be +used instead. If a form, the result from the form will be used instead. +If this variable is @code{nil}, no signature will be inserted at all. + +@item message-signature-file +@vindex message-signature-file +File containing the signature to be inserted at the end of the buffer. +The default is @samp{~/.signature}. + +@end table + +Note that RFC1036bis says that a signature should be preceded by the three +characters @samp{-- } on a line by themselves. This is to make it +easier for the recipient to automatically recognize and process the +signature. So don't remove those characters, even though you might feel +that they ruin your beautiful design, like, totally. + +Also note that no signature should be more than four lines long. +Including ASCII graphics is an efficient way to get everybody to believe +that you are silly and have nothing important to say. + + + +@node Various Commands +@section Various Commands + +@table @kbd + +@item C-c C-r +@kindex C-c C-r +@findex message-caesar-buffer-body +Caesar rotate (aka. rot13) the current message +(@code{message-caesar-buffer-body}). If narrowing is in effect, just +rotate the visible portion of the buffer. A numerical prefix says how +many places to rotate the text. The default is 13. + +@item C-c C-e +@kindex C-c C-e +@findex message-elide-region +Elide the text between point and mark (@code{message-elide-region}). +The text is killed and an ellipsis (@samp{[...]}) will be inserted in +its place. + +@item C-c C-z +@kindex C-c C-x +@findex message-kill-to-signature +Kill all the text up to the signature, or if that's missing, up to the +end of the message (@code{message-kill-to-signature}). + +@item C-c C-v +@kindex C-c C-v +@findex message-delete-not-region +Delete all text in the body of the message that is outside the region +(@code{message-delete-not-region}). + +@item M-RET +@kindex M-RET +@kindex message-newline-and-reformat +Insert four newlines, and then reformat if inside quoted text. + +Here's an example: + +@example +> This is some quoted text. And here's more quoted text. +@end example + +If point is before @samp{And} and you press @kbd{M-RET}, you'll get: + +@example +> This is some quoted text. + +* + +> And here's more quoted text. +@end example + +@samp{*} says where point will be placed. + +@item C-c C-t +@kindex C-c C-t +@findex message-insert-to +Insert a @code{To} header that contains the @code{Reply-To} or +@code{From} header of the message you're following up +(@code{message-insert-to}). + +@item C-c C-n +@kindex C-c C-n +@findex message-insert-newsgroups +Insert a @code{Newsgroups} header that reflects the @code{Followup-To} +or @code{Newsgroups} header of the article you're replying to +(@code{message-insert-newsgroups}). + +@item C-c M-r +@kindex C-c M-r +@findex message-rename-buffer +Rename the buffer (@code{message-rename-buffer}). If given a prefix, +prompt for a new buffer name. + +@end table + + +@node Sending +@section Sending + +@table @kbd +@item C-c C-c +@kindex C-c C-c +@findex message-send-and-exit +Send the message and bury the current buffer +(@code{message-send-and-exit}). + +@item C-c C-s +@kindex C-c C-s +@findex message-send +Send the message (@code{message-send}). + +@item C-c C-d +@kindex C-c C-d +@findex message-dont-send +Bury the message buffer and exit (@code{message-dont-send}). + +@item C-c C-k +@kindex C-c C-k +@findex message-kill-buffer +Kill the message buffer and exit (@code{message-kill-buffer}). + +@end table + + + +@node Mail Aliases +@section Mail Aliases +@cindex mail aliases +@cindex aliases + +@vindex message-mail-alias-type +The @code{message-mail-alias-type} variable controls what type of mail +alias expansion to use. Currently only one form is supported---Message +uses @code{mailabbrev} to handle mail aliases. If this variable is +@code{nil}, no mail alias expansion will be performed. + +@code{mailabbrev} works by parsing the @file{/etc/mailrc} and +@file{~/.mailrc} files. These files look like: + +@example +alias lmi "Lars Magne Ingebrigtsen <larsi@@ifi.uio.no>" +alias ding "ding@@ifi.uio.no (ding mailing list)" +@end example + +After adding lines like this to your @file{~/.mailrc} file, you should +be able to just write @samp{lmi} in the @code{To} or @code{Cc} (and so +on) headers and press @kbd{SPC} to expand the alias. + +No expansion will be performed upon sending of the message---all +expansions have to be done explicitly. + + + +@node Variables +@chapter Variables + +@menu +* Message Headers:: General message header stuff. +* Mail Headers:: Customizing mail headers. +* Mail Variables:: Other mail variables. +* News Headers:: Customizing news headers. +* News Variables:: Other news variables. +* Various Message Variables:: Other message variables. +* Sending Variables:: Variables for sending. +* Message Buffers:: How Message names its buffers. +* Message Actions:: Actions to be performed when exiting. +@end menu + + +@node Message Headers +@section Message Headers + +Message is quite aggressive on the message generation front. It has to +be -- it's a combined news and mail agent. To be able to send combined +messages, it has to generate all headers itself (instead of letting the +mail/news system do it) to ensure that mail and news copies of messages +look sufficiently similar. + +@table @code + +@item message-generate-headers-first +@vindex message-generate-headers-first +If non-@code{nil}, generate all headers before starting to compose the +message. + +@item message-from-style +@vindex message-from-style +Specifies how @code{From} headers should look. There are four valid +values: + +@table @code +@item nil +Just the address -- @samp{king@@grassland.com}. + +@item parens +@samp{king@@grassland.com (Elvis Parsley)}. + +@item angles +@samp{Elvis Parsley <king@@grassland.com>}. + +@item default +Look like @code{angles} if that doesn't require quoting, and +@code{parens} if it does. If even @code{parens} requires quoting, use +@code{angles} anyway. + +@end table + +@item message-deletable-headers +@vindex message-deletable-headers +Headers in this list that were previously generated by Message will be +deleted before posting. Let's say you post an article. Then you decide +to post it again to some other group, you naughty boy, so you jump back +to the @code{*post-buf*} buffer, edit the @code{Newsgroups} line, and +ship it off again. By default, this variable makes sure that the old +generated @code{Message-ID} is deleted, and a new one generated. If +this isn't done, the entire empire would probably crumble, anarchy would +prevail, and cats would start walking on two legs and rule the world. +Allegedly. + +@item message-default-headers +@vindex message-default-headers +This string is inserted at the end of the headers in all message +buffers. + +@item message-subject-re-regexp +@vindex message-subject-re-regexp +Responses to messages have subjects that start with @samp{Re: }. This +is @emph{not} an abbreviation of the English word ``response'', but in +Latin, and means ``in response to''. Some illiterate nincompoops have +failed to grasp this fact, and have ``internationalized'' their software +to use abonimations like @samp{Aw: } (``antwort'') or @samp{Sv: } +(``svar'') instead, which is meaningless and evil. However, you may +have to deal with users that use these evil tools, in which case you may +set this variable to a regexp that matches these prefixes. Myself, I +just throw away non-compliant mail. + +@end table + + +@node Mail Headers +@section Mail Headers + +@table @code +@item message-required-mail-headers +@vindex message-required-mail-headers +@xref{News Headers}, for the syntax of this variable. It is +@code{(From Date Subject (optional . In-Reply-To) Message-ID Lines +(optional . X-Mailer))} by default. + +@item message-ignored-mail-headers +@vindex message-ignored-mail-headers +Regexp of headers to be removed before mailing. The default is +@samp{^[GF]cc:\\|^Resent-Fcc:}. + +@item message-default-mail-headers +@vindex message-default-mail-headers +This string is inserted at the end of the headers in all message +buffers that are initialized as mail. + +@end table + + +@node Mail Variables +@section Mail Variables + +@table @code +@item message-send-mail-function +@vindex message-send-mail-function +Function used to send the current buffer as mail. The default is +@code{message-send-mail-with-sendmail}. If you prefer using MH +instead, set this variable to @code{message-send-mail-with-mh}. + +@item message-mh-deletable-headers +@vindex message-mh-deletable-headers +Most versions of MH doesn't like being fed messages that contain the +headers in this variable. If this variable is non-@code{nil} (which is +the default), these headers will be removed before mailing when sending +messages via MH. Set it to @code{nil} if your MH can handle these +headers. + +@end table + + +@node News Headers +@section News Headers + +@vindex message-required-news-headers +@code{message-required-news-headers} a list of header symbols. These +headers will either be automatically generated, or, if that's +impossible, they will be prompted for. The following symbols are valid: + +@table @code + +@item From +@cindex From +@findex user-full-name +@findex user-mail-address +This required header will be filled out with the result of the +@code{message-make-from} function, which depends on the +@code{message-from-style}, @code{user-full-name}, +@code{user-mail-address} variables. + +@item Subject +@cindex Subject +This required header will be prompted for if not present already. + +@item Newsgroups +@cindex Newsgroups +This required header says which newsgroups the article is to be posted +to. If it isn't present already, it will be prompted for. + +@item Organization +@cindex organization +This optional header will be filled out depending on the +@code{message-user-organization} variable. +@code{message-user-organization-file} will be used if this variable is +@code{t}. This variable can also be a string (in which case this string +will be used), or it can be a function (which will be called with no +parameters and should return a string to be used). + +@item Lines +@cindex Lines +This optional header will be computed by Message. + +@item Message-ID +@cindex Message-ID +@vindex mail-host-address +@findex system-name +@cindex Sun +This required header will be generated by Message. A unique ID will be +created based on the date, time, user name and system name. Message will +use @code{mail-host-address} as the fully qualified domain name (FQDN) +of the machine if that variable is defined. If not, it will use +@code{system-name}, which doesn't report a FQDN on some machines -- +notably Suns. + +@item X-Newsreader +@cindex X-Newsreader +This optional header will be filled out according to the +@code{message-newsreader} local variable. + +@item X-Mailer +This optional header will be filled out according to the +@code{message-mailer} local variable, unless there already is an +@code{X-Newsreader} header present. + +@item In-Reply-To +This optional header is filled out using the @code{Date} and @code{From} +header of the article being replied to. + +@item Expires +@cindex Expires +This extremely optional header will be inserted according to the +@code{message-expires} variable. It is highly deprecated and shouldn't +be used unless you know what you're doing. + +@item Distribution +@cindex Distribution +This optional header is filled out according to the +@code{message-distribution-function} variable. It is a deprecated and +much misunderstood header. + +@item Path +@cindex path +This extremely optional header should probably never be used. +However, some @emph{very} old servers require that this header is +present. @code{message-user-path} further controls how this +@code{Path} header is to look. If it is @code{nil}, use the server name +as the leaf node. If it is a string, use the string. If it is neither +a string nor @code{nil}, use the user name only. However, it is highly +unlikely that you should need to fiddle with this variable at all. +@end table + +@findex yow +@cindex Mime-Version +In addition, you can enter conses into this list. The car of this cons +should be a symbol. This symbol's name is the name of the header, and +the cdr can either be a string to be entered verbatim as the value of +this header, or it can be a function to be called. This function should +return a string to be inserted. For instance, if you want to insert +@code{Mime-Version: 1.0}, you should enter @code{(Mime-Version . "1.0")} +into the list. If you want to insert a funny quote, you could enter +something like @code{(X-Yow . yow)} into the list. The function +@code{yow} will then be called without any arguments. + +If the list contains a cons where the car of the cons is +@code{optional}, the cdr of this cons will only be inserted if it is +non-@code{nil}. + +Other variables for customizing outgoing news articles: + +@table @code + +@item message-syntax-checks +@vindex message-syntax-checks +Controls what syntax checks should not be performed on outgoing posts. +To disable checking of long signatures, for instance, add + +@lisp +(signature . disabled) +@end lisp + +to this list. + +Valid checks are: + +@table @code +@item subject-cmsg +Check the subject for commands. +@item sender +@cindex Sender +Insert a new @code{Sender} header if the @code{From} header looks odd. +@item multiple-headers +Check for the existence of multiple equal headers. +@item sendsys +@cindex sendsys +Check for the existence of version and sendsys commands. +@item message-id +Check whether the @code{Message-ID} looks ok. +@item from +Check whether the @code{From} header seems nice. +@item long-lines +@cindex long lines +Check for too long lines. +@item control-chars +Check for invalid characters. +@item size +Check for excessive size. +@item new-text +Check whether there is any new text in the messages. +@item signature +Check the length of the signature. +@item approved +@cindex approved +Check whether the article has an @code{Approved} header, which is +something only moderators should include. +@item empty +Check whether the article is empty. +@item empty-headers +Check whether any of the headers are empty. +@item existing-newsgroups +Check whether the newsgroups mentioned in the @code{Newsgroups} and +@code{Followup-To} headers exist. +@item valid-newsgroups +Check whether the @code{Newsgroups} and @code{Followup-to} headers +are valid syntactically. +@item repeated-newsgroups +Check whether the @code{Newsgroups} and @code{Followup-to} headers +contains repeated group names. +@item shorten-followup-to +Check whether to add a @code{Followup-to} header to shorten the number +of groups to post to. +@end table + +All these conditions are checked by default. + +@item message-ignored-news-headers +@vindex message-ignored-news-headers +Regexp of headers to be removed before posting. The default is@* +@samp{^NNTP-Posting-Host:\\|^Xref:\\|^[BGF]cc:\\|^Resent-Fcc:}. + +@item message-default-news-headers +@vindex message-default-news-headers +This string is inserted at the end of the headers in all message +buffers that are initialized as news. + +@end table + + +@node News Variables +@section News Variables + +@table @code +@item message-send-news-function +@vindex message-send-news-function +Function used to send the current buffer as news. The default is +@code{message-send-news}. + +@item message-post-method +@vindex message-post-method +Gnusish @dfn{select method} (see the Gnus manual for details) used for +posting a prepared news message. + +@end table + + +@node Various Message Variables +@section Various Message Variables + +@table @code +@item message-signature-separator +@vindex message-signature-separator +Regexp matching the signature separator. It is @samp{^-- *$} by +default. + +@item mail-header-separator +@vindex mail-header-separator +String used to separate the headers from the body. It is @samp{--text +follows this line--} by default. + +@item message-directory +@vindex message-directory +Directory used by many mailey things. The default is @file{~/Mail/}. + +@item message-signature-setup-hook +@vindex message-signature-setup-hook +Hook run when initializing the message buffer. It is run after the +headers have been inserted but before the signature has been inserted. + +@item message-setup-hook +@vindex message-setup-hook +Hook run as the last thing when the message buffer has been initialized, +but before yanked text is inserted. + +@item message-header-setup-hook +@vindex message-header-setup-hook +Hook called narrowed to the headers after initializing the headers. + +For instance, if you're running Gnus and wish to insert a +@samp{Mail-Copies-To} header in all your news articles and all messages +you send to mailing lists, you could do something like the following: + +@lisp +(defun my-message-header-setup-hook () + (let ((group (or gnus-newsgroup-name ""))) + (when (or (message-fetch-field "newsgroups") + (gnus-group-find-parameter group 'to-address) + (gnus-group-find-parameter group 'to-list)) + (insert "Mail-Copies-To: never\n")))) + +(add-hook 'message-header-setup-hook + 'my-message-header-setup-hook) +@end lisp + +@item message-send-hook +@vindex message-send-hook +Hook run before sending messages. + +If you want to add certain headers before sending, you can use the +@code{message-add-header} function in this hook. For instance: +@findex message-add-header + +@lisp +(add-hook 'message-send-hook 'my-message-add-content) +(defun my-message-add-content () + (message-add-header + "Mime-Version: 1.0" + "Content-Type: text/plain" + "Content-Transfer-Encoding: 7bit")) +@end lisp + +This function won't add the header if the header is already present. + +@item message-send-mail-hook +@vindex message-send-mail-hook +Hook run before sending mail messages. + +@item message-send-news-hook +@vindex message-send-news-hook +Hook run before sending news messages. + +@item message-sent-hook +@vindex message-sent-hook +Hook run after sending messages. + +@item message-mode-syntax-table +@vindex message-mode-syntax-table +Syntax table used in message mode buffers. + +@item message-send-method-alist +@vindex message-send-method-alist + +Alist of ways to send outgoing messages. Each element has the form + +@lisp +(TYPE PREDICATE FUNCTION) +@end lisp + +@table @var +@item type +A symbol that names the method. + +@item predicate +A function called without any parameters to determine whether the +message is a message of type @var{type}. + +@item function +A function to be called if @var{predicate} returns non-@code{nil}. +@var{function} is called with one parameter -- the prefix. +@end table + +@lisp +((news message-news-p message-send-via-news) + (mail message-mail-p message-send-via-mail)) +@end lisp + + + +@end table + + + +@node Sending Variables +@section Sending Variables + +@table @code + +@item message-fcc-handler-function +@vindex message-fcc-handler-function +A function called to save outgoing articles. This function will be +called with the name of the file to store the article in. The default +function is @code{message-output} which saves in Unix mailbox format. + +@item message-courtesy-message +@vindex message-courtesy-message +When sending combined messages, this string is inserted at the start of +the mailed copy. If the string contains the format spec @samp{%s}, the +newsgroups the article has been posted to will be inserted there. If +this variable is @code{nil}, no such courtesy message will be added. +The default value is @samp{"The following message is a courtesy copy of +an article\nthat has been posted to %s as well.\n\n"}. + +@end table + + +@node Message Buffers +@section Message Buffers + +Message will generate new buffers with unique buffer names when you +request a message buffer. When you send the message, the buffer isn't +normally killed off. Its name is changed and a certain number of old +message buffers are kept alive. + +@table @code +@item message-generate-new-buffers +@vindex message-generate-new-buffers +If non-@code{nil}, generate new buffers. The default is @code{t}. If +this is a function, call that function with three parameters: The type, +the to address and the group name. (Any of these may be @code{nil}.) +The function should return the new buffer name. + +@item message-max-buffers +@vindex message-max-buffers +This variable says how many old message buffers to keep. If there are +more message buffers than this, the oldest buffer will be killed. The +default is 10. If this variable is @code{nil}, no old message buffers +will ever be killed. + +@item message-send-rename-function +@vindex message-send-rename-function +After sending a message, the buffer is renamed from, for instance, +@samp{*reply to Lars*} to @samp{*sent reply to Lars*}. If you don't +like this, set this variable to a function that renames the buffer in a +manner you like. If you don't want to rename the buffer at all, you can +say: + +@lisp +(setq message-send-rename-function 'ignore) +@end lisp + +@item message-kill-buffer-on-exit +@findex message-kill-buffer-on-exit +If non-@code{nil}, kill the buffer immediately on exit. + +@end table + + +@node Message Actions +@section Message Actions + +When Message is being used from a news/mail reader, the reader is likely +to want to perform some task after the message has been sent. Perhaps +return to the previous window configuration or mark an article as +replied. + +@vindex message-kill-actions +@vindex message-postpone-actions +@vindex message-exit-actions +@vindex message-send-actions +The user may exit from the message buffer in various ways. The most +common is @kbd{C-c C-c}, which sends the message and exits. Other +possibilities are @kbd{C-c C-s} which just sends the message, @kbd{C-c +C-d} which postpones the message editing and buries the message buffer, +and @kbd{C-c C-k} which kills the message buffer. Each of these actions +have lists associated with them that contains actions to be executed: +@code{message-send-actions}, @code{message-exit-actions}, +@code{message-postpone-actions}, and @code{message-kill-actions}. + +Message provides a function to interface with these lists: +@code{message-add-action}. The first parameter is the action to be +added, and the rest of the arguments are which lists to add this action +to. Here's an example from Gnus: + +@lisp + (message-add-action + `(set-window-configuration ,(current-window-configuration)) + 'exit 'postpone 'kill) +@end lisp + +This restores the Gnus window configuration when the message buffer is +killed, postponed or exited. + +An @dfn{action} can be either: a normal function, or a list where the +@code{car} is a function and the @code{cdr} is the list of arguments, or +a form to be @code{eval}ed. + + +@node Compatibility +@chapter Compatibility +@cindex compatibility + +Message uses virtually only its own variables---older @code{mail-} +variables aren't consulted. To force Message to take those variables +into account, you can put the following in your @code{.emacs} file: + +@lisp +(require 'messcompat) +@end lisp + +This will initialize many Message variables from the values in the +corresponding mail variables. + + +@node Appendices +@chapter Appendices + +@menu +* Responses:: Standard rules for determining where responses go. +@end menu + + +@node Responses +@section Responses + +To determine where a message is to go, the following algorithm is used +by default. + +@table @dfn +@item reply +A @dfn{reply} is when you want to respond @emph{just} to the person who +sent the message via mail. There will only be one recipient. To +determine who the recipient will be, the following headers are +consulted, in turn: + +@table @code +@item Reply-To + +@item From +@end table + + +@item wide reply +A @dfn{wide reply} is a mail response that includes @emph{all} entities +mentioned in the message you are responded to. All mailboxes from the +following headers will be concatenated to form the outgoing +@code{To}/@code{Cc} headers: + +@table @code +@item From +(unless there's a @code{Reply-To}, in which case that is used instead). + +@item Cc + +@item To +@end table + +If a @code{Mail-Copies-To} header is present, it will also be included +in the list of mailboxes. If this header is @samp{never}, that means +that the @code{From} (or @code{Reply-To}) mailbox will be suppressed. + + +@item followup +A @dfn{followup} is a response sent via news. The following headers +(listed in order of precedence) determine where the response is to be +sent: + +@table @code + +@item Followup-To + +@item Newsgroups + +@end table + +If a @code{Mail-Copies-To} header is present, it will be used as the +basis of the new @code{Cc} header, except if this header is +@samp{never}. + +@end table + + + +@node Index +@chapter Index +@printindex cp + +@node Key Index +@chapter Key Index +@printindex ky + +@summarycontents +@contents +@bye + +@c End: diff --git a/man/mh-e.texi b/man/mh-e.texi new file mode 100644 index 00000000000..0e6082e692a --- /dev/null +++ b/man/mh-e.texi @@ -0,0 +1,4096 @@ +\input texinfo @c -*-texinfo-*- +@c $Id: mh-e.texi,v 1.17 95/08/23 07:00:16 wohler Exp $ +@c %**start of header +@setfilename ../info/mh-e +@settitle mh-e +@c %**end of header + +@setchapternewpage odd + +@dircategory Editors +@direntry +* MH-E: (mh-e). Emacs interface to the MH mail system. +@end direntry + +@c Version variables. +@set EDITION 1.2 +@set VERSION 5.0.2 +@set UPDATED 22 August 1995 +@set UPDATE-MONTH August 1995 + +@ifinfo +This is Edition @value{EDITION}, last updated @value{UPDATED}, of +@cite{mh-e, The Emacs Interface to MH}, for mh-e, Version +@value{VERSION}. + +Copyright 1995 Free Software Foundation, Inc. + +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 a 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 +Permission is granted to copy and distribute modified +versions of this manual under the conditions for +verbatim copying, provided also that the section +entitled ``Copying'' +is included exactly as in the original, and provided +that the entire resulting derived work is distributed +under the terms of a permission notice identical to this +one. + +Permission is granted to copy and distribute +translations of this manual into another language, +under the above conditions for modified versions, +except that this permission notice may be stated in a +translation approved by the Free Software Foundation. +@end ifinfo + +@titlepage +@sp 10 +@center @titlefont{mh-e} +@sp 2 +@center The Emacs Interface to MH +@sp 2 +@center by Bill Wohler +@sp 2 +@center Edition @value{EDITION} for mh-e Version @value{VERSION} +@sp 2 +@center @value{UPDATE-MONTH} + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1995 Free Software Foundation, Inc. + +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. + +Permission is granted to copy and distribute modified +versions of this manual under the conditions for +verbatim copying, provided also that the section +entitled ``The GNU General Public License'' +is included exactly as in the original, and provided +that the entire resulting derived work is distributed +under the terms of a permission notice identical to this +one. + +Permission is granted to copy and distribute +translations of this manual into another language, +under the above conditions for modified versions, +except that this permission notice may be stated in a +translation approved by the Free Software Foundation. +@end titlepage + +@ifinfo +@node Top, Preface, (dir), (dir) +@top MH and Emacs +This is Edition @value{EDITION} of @cite{mh-e, The Emacs Interface to +MH}, last updated @value{UPDATED} for mh-e Version @value{VERSION}. + +@menu +* Preface:: Introduction to mh-e. +* Tour Through mh-e:: Use mh-e quickly! +* Using mh-e:: Documentation for all commands. +* Customizing mh-e:: Documentation for all variables. +* Odds and Ends:: Getting mh-e, reporting bugs, mailing + list and FAQ. +* History:: The authors speak up! +* Changes to mh-e:: Actual changes between Versions 3 and beyond. +* Copying:: The GNU General Public License +* Command Index:: +* Variable Index:: +* Concept Index:: +@end menu +@end ifinfo + +@node Preface, Tour Through mh-e, Top, Top +@unnumbered Preface + +@cindex Emacs +@cindex Unix commands, Emacs + +These chapters introduce another interface to MH that is accessible +through the GNU Emacs editor, namely, @emph{mh-e}. mh-e is easy to use. +I don't assume that you know GNU Emacs or even MH at this point, since I +didn't know either of them when I discovered mh-e. However, mh-e was +the tip of the iceberg, and I discovered more and more niceties about +GNU Emacs and MH@. Now I'm fully hooked on both of them. + +@cindex history + +The mh-e package is distributed with GNU Emacs, @footnote{Note that mh-e +is supported with MH 6 and either @w{Emacs 18} or @w{Emacs 19}. +Reportedly, large parts of it work with @w{MH 5} and also with +Lucid/XEmacs and Epoch, but there are no guarantees. It is also +distributed with Lucid/XEmacs, as well as with MH itself.} so you shouldn't +have to do anything special to use it. But it's important to note a +brief history of mh-e. @w{Version 3} was prevalent through the @w{Emacs +18} and early @w{Emacs 19} years. Then @w{Version 4} came out (@w{Emacs +19.23}), which introduced several new and changed commands. Finally, +@w{Version 5.0} was released, which fixed some bugs and +incompatibilities. This is the version covered by this manual. +@ref{Getting Started} will help you decide which version you +have. + +If you don't already use GNU Emacs but want to learn more, you can read +an online tutorial by starting GNU Emacs and typing @kbd{C-h t} +(@code{help-with-tutorial}). (This notation is described in +@ref{Conventions}.) If you want to take the plunge, consult the +@iftex +@cite{GNU Emacs Manual}, +@end iftex +@ifinfo +@ref{top, , GNU Emacs Manual, emacs, The GNU Emacs Manual}, +@end ifinfo +from the Free Software Foundation. + +If more information is needed, you can go to the Unix manual pages of +the individual MH commands. When the name is not obvious, I'll guide +you to a relevant MH manual page that describes the action more fully. + +I hope you enjoy these chapters! If you have any comments, or +suggestions for this document, please let me know. + +@noindent +Bill Wohler <@i{wohler@@newt.com}>@* +8 February 1995 + +@node Tour Through mh-e, Using mh-e, Preface, Top +@chapter Tour Through mh-e + +This chapter introduces some of the terms you'll need to know and then +takes you on a tour of mh-e. @footnote{The keys mentioned in these +chapters refer to the default key bindings. If you've changed the +bindings, refer to the command summaries at the beginning of each major +section in @ref{Using mh-e}, for a mapping between default key bindings +and function names.} When you're done, you'll be able to send, read, +and file mail, which is all that a lot of people ever do. But if you're +the curious type, you'll read @ref{Using mh-e} to be able to use all +the features of mh-e. If you're the adventurous type, you'll read +@ref{Customizing mh-e} to make mh-e do what you want. I suggest you +read this chapter first to get the big picture, and then you can read +the other two as you wish. + +@menu +* Conventions:: GNU Emacs Terms and Conventions +* Getting Started:: +* Sending Mail Tour:: +* Reading Mail Tour:: +* Processing Mail Tour:: +* Leaving mh-e:: +* More About mh-e:: +@end menu + +@node Conventions, Getting Started, Tour Through mh-e, Tour Through mh-e +@section GNU Emacs Terms and Conventions + +@cindex Emacs, terms and conventions + +@cindex Emacs +@cindex Unix commands, Emacs + +If you're an experienced Emacs user, you can skip the following +conventions and definition of terms and go directly to @ref{Getting +Started} below. The conventions are as follows: + +@table @kbd +@item C-x +Hold down the @key{CTRL} (Control) key and press the @kbd{x} key. +@item M-x +Hold down the @key{META} or @key{ALT} key and press the @kbd{x} key. + +Since some keyboards don't have a @key{META} key, you can generate +@kbd{M-x}, for example, by pressing @key{ESC} (Escape), @emph{releasing +it}, @footnote{This is emphasized because pressing ESC twice or holding +it down a second too long so that it repeats gives you an error message.} +and then pressing the @kbd{x} key. +@item RET +Press the @key{RETURN} or @key{ENTER} key. This is normally used to +complete a command. +@item SPC +Press the space bar. +@item TAB +Press the @key{TAB} key. +@item DEL +Press the @key{DELETE} key. This may also be a Backspace key, depending +on your keyboard or Emacs configuration. +@end table + +@cindex Emacs, prefix argument +@cindex prefix argument + +A @dfn{prefix argument} allows you to pass an argument to any Emacs +function. To pass an argument, type @kbd{C-u} before the Emacs command +or keystroke. Numeric arguments can be passed as well. For example, to +insert five f's, use @kbd{C-u 5 f}. There is a default of four when +using @kbd{C-u}, and you can use multiple prefix arguments to provide +arguments of powers of four. To continue our example, you could insert +four f's with @kbd{C-u f}, 16 f's with @kbd{C-u C-u f}, 64 f's with +@kbd{C-u C-u C-u f}, and so on. Numeric and valueless negative +arguments can also be inserted with the @key{META} key. Examples +include @kbd{M-5} to specify an argument of 5, or @kbd{M--} which +specifies a negative argument with no particular value. + +@sp 2 +@need 1000 +@center @strong{NOTE} + +@quotation +The prefix @kbd{C-u} or @kbd{M-} is not necessary in mh-e's MH-Folder +modes (@pxref{Reading Mail Tour}). In these modes, simply enter the +numerical argument before entering the command. +@end quotation + +@cindex point +@cindex Emacs, point +@cindex mark +@cindex Emacs, mark +@cindex region +@cindex Emacs, region + +There are several other terms that are used in Emacs that you should +know. The @dfn{point} is where the cursor currently is. You can save +your current place in the file by setting a @dfn{mark}. This operation +is useful in several ways. The mark can be later used when defining a +@dfn{region}, which is the text between the point and mark. Many +commands operate on regions, such as those for deleting text or filling +paragraphs. A mark can be set with @kbd{C-@@} (or @kbd{C-SPC}). + +@cindex minibuffer +@cindex Emacs, minibuffer +@cindex file completion +@cindex Emacs, file completion + +The @dfn{minibuffer} is the bottom line of the Emacs window, where all +prompting and multiple-character input is directed. If you are prompted +for information in the minibuffer, such as a filename, Emacs can help +you complete your answer if you type @key{SPC} or @key{TAB}. A second +@key{SPC} or @key{TAB} will list all possibilities at that point. The +minibuffer is also where you enter Emacs function names after typing +@kbd{M-x}. For example, in the first paragraph, I mentioned that you +could obtain help with @kbd{C-h t} (@code{help-with-tutorial}). What +this means is that you can get a tutorial by typing either @kbd{C-h t} +or @kbd{M-x help-with-tutorial}. In the latter case, you are prompted +for @samp{help-with-tutorial} in the minibuffer after typing @kbd{M-x}. + +@cindex interrupting +@cindex Emacs, interrupting +@cindex quitting +@cindex Emacs, quitting + +@i{In case of trouble:} Emacs can be interrupted at any time with +@kbd{C-g}. For example, if you've started a command that requests that +you enter something in the minibuffer, but then you change your mind, +type @kbd{C-g} and you'll be back where you started. If you want to +exit Emacs entirely, use @kbd{C-x C-c}. + +@node Getting Started, Sending Mail Tour, Conventions, Tour Through mh-e +@section Getting Started + +Because there are many old versions of mh-e out there, it is important to +know which version you have. I'll be talking about @w{Version 5} which +is similar to @w{Version 4} and vastly different from @w{Version 3}. + +First, enter @kbd{M-x load-library @key{RET} mh-e +@key{RET}}. @footnote{You wouldn't ordinarily do this.} The message, +@samp{Loading mh-e...done}, should be displayed in the minibuffer. If +you get @samp{Cannot open load file: mh-e}, then your Emacs is very +badly configured, or mh-e is missing. You may wish to have your system +administrator install a new Emacs or at least the latest mh-e files. + +Having loaded mh-e successfully, enter @kbd{M-x mh-version @key{RET}}. +The version of mh-e should be displayed. Hopefully it says that you're +running @w{Version @value{VERSION}} which is the latest version as of +this printing. If instead Emacs beeps and says @samp{[No match]}, then +you're running an old version of mh-e. + +If these tests reveal a non-existent or old version of mh-e, please +consider obtaining a new version. You can have your system +administrator upgrade the system-wide version, or you can install your +own personal version. It's really quite easy; instructions for getting +and installing mh-e are in @ref{Getting mh-e}. In the meantime, see +@ref{Changes to mh-e}, which compares the old and new names of commands, +functions, variables, and buffers. + +@cindex @code{install-mh} +@cindex MH commands, @code{install-mh} + +Also, older versions of mh-e assumed that you had already set up your MH +environment. Newer versions set up a new MH environment for you by +running @code{install-mh} and notifying you of this fact with the +message in a temporary buffer: + +@example +I'm going to create the standard MH path for you. +@end example + +Therefore, if you've never run MH before and you're using an old version +of mh-e, you need to run @code{install-mh} from the shell before you +continue the tour. If you don't, you'll be greeted with the error +message: @samp{Can't find MH profile}. + +@cindex @file{.emacs} +@cindex files, @file{.emacs} + +If, during the tour described in this chapter, you see a message like: +@samp{Searching for program: no such file or directory, +/usr/local/bin/mhpath}, it means that the MH programs and files are kept +in a nonstandard directory. In this case, simply add the following to +@file{~/.emacs} and restart @code{emacs}. + +@vindex @code{mh-progs}, example +@vindex @code{mh-lib}, example + +@c XXX Real example for really naive user? +@example +@group +(setq mh-progs "@var{/path/to/MH/binary/directory/}") +(setq mh-lib "@var{/path/to/MH/library/directory/}") +@end group +@end example + +@cindex ~ + +The @samp{~} notation used by @file{~/.emacs} above represents your home +directory. This is used by the @code{bash} and @code{csh} shells. If +your shell does not support this feature, you could use the environment +variable @samp{$HOME} (such as @file{$HOME/.emacs}) or the absolute path +(as in @file{/home/wohler/.emacs}) instead. + +At this point, you should see something like the screen in the +figure in @ref{Reading Mail Tour}. We're now ready to move on. + +@node Sending Mail Tour, Reading Mail Tour, Getting Started, Tour Through mh-e +@section Sending Mail + +@cindex sending mail +@findex @code{mh-smail} + +Let's start our tour by sending ourselves a message which we can later +read and process. Enter @kbd{M-x mh-smail} to invoke the mh-e program +to send messages. You will be prompted in the minibuffer by @samp{To:}. +Enter your login name. The next prompt is @samp{cc:}. Hit @key{RET} to +indicate that no carbon copies are to be sent. At the @samp{Subject:} +prompt, enter @kbd{Test} or anything else that comes to mind. + +@cindex MH-Letter mode +@cindex modes, MH-Letter +@cindex mode + +Once you've specified the recipients and subject, your message appears +in an Emacs buffer whose mode @footnote{A @dfn{mode} changes Emacs to +make it easier to edit a particular type of text.} is MH-Letter. +Enter some text in the body of the message, using normal Emacs commands. +You should now have something like this: @footnote{If you're running Emacs +under the X Window System, then you would also see a menubar. I've left +out the menubar in all of the example screens.} + +@example +@group +@cartouche + + + + + + +-----Emacs: *scratch* (Lisp Interaction)--All--------------------- +To: wohler +cc: +Subject: Test +-------- + This is a test message to get the wheels churning...# + + +--**-@{draft@} (MH-Letter)--All---------------------------------------- + +@end cartouche +@i{mh-e message composition window} +@end group +@end example + +@cindex MH-Letter mode +@cindex modes, MH-Letter + +Note the line of dashes that separates the header and the body of the +message. It is essential that these dashes (or a blank line) are +present or the body of your message will be considered to be part of +the header. + +There are several commands specific to MH-Letter mode, but at +this time we'll only use @kbd{C-c C-c} to send your message. Type +@kbd{C-c C-c} now. That's all there is to it! + +@node Reading Mail Tour, Processing Mail Tour, Sending Mail Tour, Tour Through mh-e +@section Receiving Mail + +@cindex reading mail +@findex @code{mh-rmail} +@cindex @code{inc} +@cindex MH commands, @code{inc} +@cindex @code{scan} +@cindex MH commands, @code{scan} +@cindex MH-Folder mode +@cindex modes, MH-Folder + +To read the mail you've just sent yourself, enter @kbd{M-x mh-rmail}. +This incorporates the new mail and put the output from @code{inc} +(called @dfn{scan lines} after the MH program @code{scan} which prints a +one-line summary of each message) into a buffer called @samp{+inbox} +whose major mode is MH-Folder. + +@sp 2 +@need 1000 +@center @strong{NOTE} + +@quotation +The @kbd{M-x mh-rmail} command will show you only new mail, not old +mail. If you were to run this tour again, you would use @kbd{M-r} to +pull all your messages into mh-e. +@end quotation + +You should see the scan line for your message, and perhaps others. Use +@kbd{n} or @kbd{p} to move the cursor to your test message and type +@key{RET} to read your message. You should see something like: + +@example +@group +@cartouche + 3 24Aug root received fax files on Wed Aug 24 11:00:13 PDT 1994 +# 4+ 24Aug To:wohler Test<<This is a test message to get the wheels chu + +--%%-@{+inbox@} 4 msgs (1-4) (MH-Folder Show)--Bot--------------------- +To: wohler +Subject: Test +Date: Wed, 24 Aug 1994 13:01:13 -0700 +From: Bill Wohler <wohler@@newt.com> + + This is a test message to get the wheels churning... + + + + + +-----@{show-+inbox@} 4 (MH-Show)--Bot---------------------------------- + +@end cartouche +@i{After incorporating new messages} +@end group +@end example + +If you typed a long message, you can view subsequent pages with @key{SPC} +and previous pages with @key{DEL}. + +@node Processing Mail Tour, Leaving mh-e, Reading Mail Tour, Tour Through mh-e +@section Processing Mail + +@cindex processing mail + +The first thing we want to do is reply to the message that we sent +ourselves. Ensure that the cursor is still on the same line as your +test message and type @kbd{r}. You are prompted in the minibuffer with +@samp{Reply to whom:}. Here mh-e is asking whether you'd like to reply +to the original sender only, to the sender and primary recipients, or to +the sender and all recipients. If you simply hit @key{RET}, you'll +reply only to the sender. Hit @key{RET} now. + +You'll find yourself in an Emacs buffer similar to that when you were +sending the original message, like this: + +@example +@group +@cartouche +To: wohler +Subject: Re: Test +In-reply-to: Bill Wohler's message of Wed, 24 Aug 1994 13:01:13 -0700 + <199408242001.NAA00505@@newt.com> +-------- +# + +--**-@{draft@} (MH-Letter)--All---------------------------------------- +To: wohler +Subject: Test +Date: Wed, 24 Aug 1994 13:01:13 -0700 +From: Bill Wohler <wohler@@newt.com> + + This is a test message to get the wheels churning... + +-----@{show-+inbox@} 4 (MH-Show)--Bot---------------------------------- +Composing a reply...done +@end cartouche +@i{Composition window during reply} +@end group +@end example + +By default, MH will not add you to the address list of your replies, so +if you find that the @samp{To:} header field is missing, don't worry. +In this case, type @kbd{C-c C-f C-t} to create and go to the @samp{To:} +field, where you can type your login name again. You can move around +with the arrow keys or with @kbd{C-p} (@code{previous-line}), @kbd{C-n} +(@code{next-line}), @kbd{C-b} (@code{backward-char}), and @kbd{C-f} +(@code{forward-char}) and can delete the previous character with +@key{DEL}. When you're finished editing your message, send it with +@kbd{C-c C-c} as before. + +@cindex folder + +You'll often want to save messages that were sent to you in an organized +fashion. This is done with @dfn{folders}. You can use folders to keep +messages from your friends, or messages related to a particular topic. +With your cursor in the MH-Folder buffer and positioned on the message +you sent to yourself, type @kbd{o} to output (@code{refile} in MH +parlance) that message to a folder. Enter @kbd{test} at the +@samp{Destination:} prompt and type @kbd{y} (or @key{SPC}) when mh-e +asks to create the folder @samp{+test}. Note that a @samp{^} (caret) +appears next to the message number, which means that the message has +been marked for refiling but has not yet been refiled. We'll talk about +how the refile is actually carried out in a moment. + +@cindex MH-Folder mode +@cindex modes, MH-Folder + +Your previous reply is now waiting in the system mailbox. You +incorporate this mail into your MH-Folder buffer named @samp{+inbox} +with the @kbd{i} command. Do this now. After the mail is incorporated, +use @kbd{n} or @kbd{p} to move the cursor to the new message, and read +it with @key{RET}. Let's delete this message by typing @kbd{d}. Note +that a @samp{D} appears next to the message number. This means that the +message is marked for deletion but is not yet deleted. To perform the +deletion (and the refile we did previously), use the @kbd{x} command. + +@findex @code{mh-smail} + +If you want to send another message you can use @kbd{m} instead of +@kbd{M-x mh-smail}. So go ahead, send some mail to your friends! + +@node Leaving mh-e, More About mh-e, Processing Mail Tour, Tour Through mh-e +@section Leaving mh-e + +@cindex Emacs, quitting +@cindex quitting + +You may now wish to exit @code{emacs} entirely. Use @kbd{C-x C-c} to +exit @code{emacs}. If you exited without running @kbd{x} in the +@samp{+inbox} buffer, Emacs will offer to save it for you. Type @kbd{y} +or @key{SPC} to save @samp{+inbox} changes, which means to perform any refiles +and deletes that you did there. + +If you don't want to leave Emacs, you can type @kbd{q} to bury (hide) +the mh-e folder or delete them entirely with @kbd{C-x k}. You can then +later recall them with @kbd{C-x b} or @kbd{M-x mh-rmail}. + +@node More About mh-e, , Leaving mh-e, Tour Through mh-e +@section More About mh-e + +These are the basic commands to get you going, but there are plenty +more. If you think that mh-e is for you, read @ref{Using mh-e} and +@ref{Customizing mh-e} to find out how you can: + +@itemize @bullet +@item +Print your messages. (@ref{Printing} and @ref{Customizing Printing}.) +@item +Edit messages and include your signature. (@ref{Draft Editing} +and @ref{Customizing Draft Editing}.) +@item +Forward messages. (@ref{Forwarding} and @ref{Customizing Forwarding}.) +@item +Read digests. (@ref{Viewing}.) +@item +Edit bounced messages. (@ref{Old Drafts} and @ref{Customizing Old Drafts}.) +@item +Send multimedia messages. (@ref{Editing MIME} and @ref{Customizing Editing MIME}.) +@item +Process mail that was sent with @code{shar} or @code{uuencode}. +(@ref{Files and Pipes}.) +@item +Use sequences conveniently. (@ref{Sequences}.) +@item +Show header fields in different fonts. (@ref{Customizing Viewing}.) +@item +Find previously refiled messages. (@ref{Searching}.) +@item +Place messages in a file. (@ref{Files and Pipes}.) +@end itemize + +Remember that you can also use MH commands when you're not running mh-e +(and when you are!). + +@node Using mh-e, Customizing mh-e, Tour Through mh-e, Top +@chapter Using mh-e + +This chapter leaves the tutorial style and goes into more detail about +every mh-e command. The default, or "out of the box," behavior is +documented. If this is not to your liking (for instance, you print with +something other than @code{lpr)}, see the associated section in +@ref{Customizing mh-e} which is organized exactly like this chapter. + +@cindex Emacs, functions; describe-mode +@cindex Emacs, online help +@cindex online help + +There are many commands, but don't get intimidated. There are command +summaries at the beginning of each section. In case you have or would +like to rebind the keys, the command summaries also list the associated +Emacs Lisp function. Furthermore, even if you're stranded on a desert +island with a laptop and are without your manuals, you can get a summary +of all these commands with GNU Emacs online help: use @kbd{C-h m} +(@code{describe-mode}) for a brief summary of commands or @kbd{C-h i} to +read this manual via Info. The online help is quite good; try running +@kbd{C-h C-h C-h}. This brings up a list of available help topics, one +of which displays the documentation for a given key (like @kbd{C-h k +C-n}). In addition, review @ref{Conventions}, if any of the GNU Emacs +conventions are strange to you. + +Let's get started! + +@menu +* Reading Mail:: +* Sending Mail:: +* Draft Editing:: +* Moving Mail:: +* Searching:: +* Sequences:: +* Miscellaneous:: +@end menu + +@node Reading Mail, Sending Mail, Using mh-e, Using mh-e +@section Reading Your Mail + +@cindex reading mail +@findex @code{mh-rmail} +@cindex MH-Folder mode +@cindex modes, MH-Folder + +The mh-e entry point for reading mail is @kbd{M-x mh-rmail}. This +command incorporates your mail and creates a buffer called @samp{+inbox} +in MH-Folder mode. The @kbd{M-x mh-rmail} command shows you only new +mail, not old mail. @footnote{If you want to see your old mail as well, +use @kbd{M-r} to pull all your messages into mh-e. Or, give a prefix +argument to @code{mh-rmail} so it will prompt you for folder to visit +like @kbd{M-f} (for example, @kbd{C-u M-x mh-rmail @key{RET} bob +@key{RET}}). Both @kbd{M-r} and @kbd{M-f} are described in +@ref{Organizing}.} The @samp{+inbox} buffer contains @dfn{scan lines}, +which are one-line summaries of each incorporated message. You can +perform most MH commands on these messages via one-letter commands +discussed in this chapter. See @code{scan}(1) for a description of the +contents of the scan lines, and see the Figure in @ref{Reading Mail +Tour}, for an example. + +@table @kbd +@item RET +Display a message (@code{mh-show}). + +@item SPC +Go to next page in message (@code{mh-page-msg}). + +@item DEL +Go to previous page in message (@code{mh-previous-page}). + +@item , (comma) +Display a message with all header fields (@code{mh-header-display}). + +@item M-SPC +Go to next message in digest (@code{mh-page-digest}). + +@item M-DEL +Go to previous message in digest (@code{mh-page-digest-backwards}). + +@item M-b +Break up digest into separate messages (@code{mh-burst-digest}). + +@item n +Display next message (@code{mh-next-undeleted-msg}). + +@item p +Display previous message (@code{mh-previous-undeleted-msg}). + +@item g +Go to a message (@code{mh-goto-msg}). + +@item M-< +Go to first message (@code{mh-first-msg}). + +@item M-> +Go to last message (@code{mh-last-msg}). + +@item t +Toggle between MH-Folder and MH-Folder Show modes (@code{mh-toggle-showing}). +@end table + +@menu +* Viewing:: +* Moving Around:: +@end menu + +@node Viewing, Moving Around, Reading Mail, Reading Mail +@subsection Viewing Your Mail + +@findex @code{mh-show} +@findex @code{mh-page-msg} +@findex @code{mh-previous-page} + +The @kbd{RET} (@code{mh-show}) command displays the message that the +cursor is on. If the message is already displayed, it scrolls to the +beginning of the message. Use @key{SPC} (@code{mh-page-msg}) and +@key{DEL} (@code{mh-previous-page}) to move forwards and backwards one +page at a time through the message. You can give either of these +commands a prefix argument that specifies the number of lines to scroll +(such as @kbd{10 SPC}). mh-e normally hides a lot of the +superfluous header fields that mailers add to a message, but if you wish +to see all of them, use the @kbd{,} (comma; @code{mh-header-display}) +command. + +@menu +* Reading Digests:: +* Reading MIME:: +@end menu + +@node Reading Digests, Reading MIME, Viewing, Viewing +@subsubsection Reading Digests + +@cindex digests +@findex @code{mh-page-digest} +@findex @code{mh-page-digest-backwards} + +A digest is a message that contains other messages. Special mh-e +commands let you read digests conveniently. You can use @key{SPC} and +@key{DEL} to page through the digest as if it were a normal message, but +if you wish to skip to the next message in the digest, use @kbd{M-SPC} +(@code{mh-page-digest}). To return to a previous message, use +@kbd{M-DEL} (@code{mh-page-digest-backwards}). + +@cindex @code{burst} +@cindex MH commands, @code{burst} +@cindex MH-Folder Show mode +@cindex modes, MH-Folder Show +@findex @code{mh-burst-digest} + +@c There was a page break at the colon in the following paragraph which +@c broke the transition to the example. +@need 2000 + +Another handy command is @kbd{M-b} (@code{mh-burst-digest}). This +command uses the MH command @code{burst} to break out each message in +the digest into its own message. Using this command, you can quickly +delete unwanted messages, like this: Once the digest is split up, toggle +out of MH-Folder Show mode with @kbd{t} (@pxref{Moving Around}) so that +the scan lines fill the screen and messages aren't displayed. Then use +@kbd{d} (@pxref{Deleting}) to quickly delete messages that you don't +want to read (based on the @samp{Subject:} header field). You can also +burst the digest to reply directly to the people who posted the messages +in the digest. One problem you may encounter is that the @samp{From:} +header fields are preceded with a @samp{>} so that your reply can't +create the @samp{To:} field correctly. In this case, you must correct +the @samp{To:} field yourself. This is described later in @ref{Editing +Textual}. + +@node Reading MIME, , Reading Digests, Viewing +@subsubsection Reading Multimedia Mail + +@cindex multimedia mail +@cindex MIME +@cindex @code{show} +@cindex MH commands, @code{show} +@cindex @code{mhn} +@cindex MH commands, @code{mhn} + +MH has the ability to read @dfn{@sc{mime}} (Multipurpose Internet Mail +Extensions) messages. Unfortunately, mh-e does not yet have this +ability, so you have to use the MH commands @code{show} or @code{mhn} +from the shell to read @sc{mime} messages. @footnote{You can call them +directly from Emacs if you're running the X Window System: type @kbd{M-! +xterm -e mhn @var{message-number}}. You can leave out the @code{xterm +-e} if you use @code{mhn -list} or @code{mhn -store}.} + +@node Moving Around, , Viewing, Reading Mail +@subsection Moving Around + +@cindex moving between messages +@findex @code{mh-next-undeleted-msg} +@findex @code{mh-previous-undeleted-msg} +@findex @code{mh-goto-msg} +@findex @code{mh-last-msg} +@findex @code{mh-first-msg} + +To move on to the next message, use the @kbd{n} +(@code{mh-next-undeleted-msg}) command; use the @kbd{p} +(@code{mh-previous-undeleted-msg}) command to read the previous message. +Both of these commands can be given a prefix argument to specify how +many messages to skip (for example, @kbd{5 n}). You can also move to a +specific message with @kbd{g} (@code{mh-goto-msg}). You can enter the +message number either before or after typing @kbd{g}. In the latter +case, Emacs prompts you. Finally, you can go to the first or last +message with @kbd{M-<} (@code{mh-first-msg}) and @kbd{M->} +(@code{mh-last-msg}) respectively. + +@cindex MH-Folder mode +@cindex modes, MH-Folder + +You can also use the Emacs commands @kbd{C-p} (@code{previous-line}) and +@kbd{C-n} (@code{next-line}) to move up and down the scan lines in the +MH-Folder window. These commands can be used in conjunction with +@kbd{RET} to look at deleted or refiled messages. + +@cindex MH-Folder mode +@cindex modes, MH-Folder +@cindex MH-Folder Show mode +@cindex modes, MH-Folder Show +@cindex junk mail +@findex @code{mh-toggle-showing} + +The command @kbd{t} (@code{mh-toggle-showing}) switches between +MH-Folder mode and MH-Folder Show mode. @footnote{For you Emacs +wizards, this is implemented as an Emacs minor mode.} MH-Folder mode +turns off the associated show buffer so that you can perform operations +on the messages quickly without reading them. This is an excellent way +to prune out your junk mail or to refile a group of messages to another +folder for later examination. + +@node Sending Mail, Draft Editing, Reading Mail, Using mh-e +@section Sending Mail + +@cindex sending mail +@findex @code{mh-smail} + +You can send a mail message in several ways. You can call @kbd{M-x +mh-smail} directly, or from the command line like this: + +@cindex starting from command line + +@example +% @kbd{emacs -f mh-smail} +@end example + +From within mh-e's MH-Folder mode, other methods of sending mail +are available as well: + +@table @kbd +@item m +Compose a message (@code{mh-send}). + +@item r +Reply to a message (@code{mh-reply}). + +@item f +Forward message(s) (@code{mh-forward}). + +@item M-d +Redistribute a message (@code{mh-redistribute}). + +@item M-e +Edit a message that was bounced by mailer (@code{mh-extract-rejected-mail}). + +@item M-a +Edit a message to send it again (@code{mh-edit-again}). +@end table + +@cindex MH-Folder mode +@cindex modes, MH-Folder +@cindex MH-Letter mode +@cindex modes, MH-Letter +@findex @code{mh-send} + +From within a MH-Folder buffer, you can simply use the command @kbd{m} +(@code{mh-send}). However you invoke @code{mh-send}, you are prompted +for the @samp{To:}, @samp{cc:}, and @samp{Subject:} header fields. Once +you've specified the recipients and subject, your message appears in an +Emacs buffer whose mode is MH-Letter (see the Figure in @ref{Sending +Mail} to see what the buffer looks like). MH-Letter mode allows you to +edit your message, to check the validity of the recipients, to insert +other messages into your message, and to send the message. We'll go +more into depth about editing a @dfn{draft} @footnote{I highly recommend +that you use a @dfn{draft folder} so that you can edit several drafts in +parallel. To do so, create a folder (e.g., @file{+drafts}), and add a +profile component called @samp{Draft-Folder:} which contains +@file{+drafts} (see @code{mh-profile}(5)).} (a message you're composing) +in just a moment. + +@findex @code{mh-smail} +@findex @code{mh-smail-other-window} + +@code{mh-smail} always creates a two-window layout with the current +buffer on top and the draft on the bottom. If you would rather preserve +the window layout, use @kbd{M-x mh-smail-other-window}. + +@menu +* Replying:: +* Forwarding:: +* Redistributing:: +* Old Drafts:: +@end menu + +@node Replying, Forwarding, Sending Mail, Sending Mail +@subsection Replying to Mail + +@cindex replying +@cindex @code{mhl} +@cindex MH commands, @code{mhl} +@cindex @file{mhl.reply} +@cindex files, @file{mhl.reply} +@findex @code{mh-reply} + +To compose a reply to a message, use the @kbd{r} (@code{mh-reply}) +command. If you supply a prefix argument (as in @kbd{C-u r}), the +message you are replying to is inserted in your reply after having first +been run through @code{mhl} with the format file @file{mhl.reply}. See +@code{mhl}(1) to see how you can modify the default @file{mhl.reply} +file. + +When you reply to a message, you are first prompted with @samp{Reply to +whom?}. You have several choices here. + +@example +@group +@b{Response} @b{Reply Goes To} + +@kbd{from} @r{The person who sent the message. This is the default,} + @r{so @key{RET} is sufficient.} + +@kbd{to} @r{Replies to the sender, plus all recipients in the} + @r{@samp{To:} header field.} + +@kbd{all} +@kbd{cc} @r{Forms a reply to the sender, plus all recipients.} +@end group +@end example + +@cindex @code{repl} +@cindex MH commands, @code{repl} + +Depending on your answer, @code{repl} is given a different argument to +form your reply. Specifically, a choice of @kbd{from} or none at all +runs @code{repl -nocc all}, and a choice of @kbd{to} runs @code{repl -cc +to}. Finally, either @kbd{cc} or @kbd{all} runs @code{repl -cc all +-nocc me}. + +@cindex MH-Letter mode +@cindex modes, MH-Letter + +Two windows are then created. One window contains the message to which +you are replying. Your draft, in MH-Letter mode (described in +@ref{Draft Editing}), is in the other window. + +If you wish to customize the header or other parts of the reply draft, +please see @code{repl}(1) and @code{mh-format}(5). + +@node Forwarding, Redistributing, Replying, Sending Mail +@subsection Forwarding Mail + +@cindex forwarding +@cindex @code{forw} +@cindex MH commands, @code{forw} +@findex @code{mh-forward} + +To forward a message, use the @kbd{f} (@code{mh-forward}) command. You +are given a draft to edit that looks like it would if you had run the MH +command @code{forw}. You are given a chance to add some text (see +@ref{Draft Editing}). + +You can forward several messages by using a prefix argument; in this +case, you are prompted for the name of a @dfn{sequence}, a symbolic name +that represents a list or range of message numbers (for example, +@kbd{C-u f forbob @key{RET}}). All of the messages in the sequence are +inserted into your draft. By the way, although sequences are often +mentioned in this chapter, you don't have to worry about them for now; +the full description of sequences in mh-e is at the end in +@ref{Sequences}. To learn more about sequences in general, please see +@code{mh-sequence}(5). + +@node Redistributing, Old Drafts, Forwarding, Sending Mail +@subsection Redistributing Your Mail + +@cindex redistributing +@findex @code{mh-redistribute} + +The command @kbd{M-d} (@code{mh-redistribute}) is similar in function to +forwarding mail, but it does not allow you to edit the message, nor does +it add your name to the @samp{From:} header field. It appears to the +recipient as if the message had come from the original sender. For more +information on redistributing messages, see @code{dist}(1). Also +investigate the @kbd{M-a} (@code{mh-edit-again}) command in @ref{Old +Drafts}, for another way to redistribute messages. + +@node Old Drafts, , Redistributing, Sending Mail +@subsection Editing Old Drafts and Bounced Messages + +@cindex re-editing drafts +@cindex @file{draft} +@cindex files, @file{draft} +@findex @code{mh-edit-again} + +If you don't complete a draft for one reason or another, and if the +draft buffer is no longer available, you can pick your draft up again +with @kbd{M-a} (@code{mh-edit-again}). If you don't use a draft folder, +your last @file{draft} file will be used. If you use draft folders, +you'll need to visit the draft folder with @kbd{M-f drafts @key{RET}}, +use @kbd{n} to move to the appropriate message, and then use @kbd{M-a} +to prepare the message for editing. + +The @kbd{M-a} command can also be used to take messages that were sent +to you and to send them to more people. + +@cindex Mailer-Daemon +@findex @code{mh-extract-rejected-mail} + +Don't use @kbd{M-a} to re-edit a message from a @i{Mailer-Daemon} who +complained that your mail wasn't posted for some reason or another. In +this case, use @kbd{M-e} (@code{mh-extract-rejected-mail}) to prepare +the message for editing by removing the @i{Mailer-Daemon} envelope and +unneeded header fields. Fix whatever addressing problem you had, and +send the message again with @kbd{C-c C-c}. + +@node Draft Editing, Moving Mail, Sending Mail, Using mh-e +@section Editing a Draft + +@cindex editing draft +@cindex MH-Letter mode +@cindex modes, MH-Letter + +When you edit a message that you want to send (called a @dfn{draft} in +this case), the mode used is MH-Letter. This mode provides +several commands in addition to the normal Emacs editing commands to +help you edit your draft. + +@table @kbd +@item C-c C-y +Insert contents of message to which you're replying (@code{mh-yank-cur-msg}). + +@item C-c C-i +Insert a message from a folder (@code{mh-insert-letter}). + +@item C-c C-f C-t +Move to @samp{To:} header field (@code{mh-to-field}). + +@item C-c C-f C-c +Move to @samp{cc:} header field (@code{mh-to-field}). + +@item C-c C-f C-s +Move to @samp{Subject:} header field (@code{mh-to-field}). + +@item C-c C-f C-f +Move to @samp{From:} header field (@code{mh-to-field}). + +@item C-c C-f C-b +Move to @samp{Bcc:} header field (@code{mh-to-field}). + +@item C-c C-f C-f +Move to @samp{Fcc:} header field (@code{mh-to-fcc}). + +@item C-c C-f C-d +Move to @samp{Dcc:} header field (@code{mh-to-field}). + +@item C-c C-w +Display expanded recipient list (@code{mh-check-whom}). + +@item C-c C-s +Insert signature in message (@code{mh-insert-signature}). + +@item C-c C-m C-f +Include forwarded message (@sc{mime}) (@code{mh-mhn-compose-forw}). + +@item C-c C-m C-e +Include anonymous ftp reference (@sc{mime}) (@code{mh-mhn-compose-anon-ftp}). + +@item C-c C-m C-t +Include anonymous ftp reference to compressed tar file (@sc{mime}) +(@code{mh-mhn-compose-external-compressed-tar}). + +@item C-c C-m C-i +Include binary, image, sound, etc. (@sc{mime}) +(@code{mh-mhn-compose-insertion}). + +@item C-c C-e +Run through @code{mhn} before sending (@code{mh-edit-mhn}). + +@item C-c C-m C-u +Undo effects of @code{mhn} (@code{mh-revert-mhn-edit}). + +@item C-c C-c +Save draft and send message (@code{mh-send-letter}). + +@item C-c C-q +Quit editing and delete draft message (@code{mh-fully-kill-draft}). +@end table + +@menu +* Editing Textual:: +* Editing MIME:: +* Sending Message:: +* Killing Draft:: +@end menu + +@node Editing Textual, Editing MIME, Draft Editing, Draft Editing +@subsection Editing Textual Messages + +The following sections show you how to edit a draft. +The commands described here are also applicable to messages that have +multimedia components. + +@menu +* Inserting Letter:: +* Inserting Messages:: +* Header:: +* Recipients:: +* Signature:: +@end menu + +@node Inserting Letter, Inserting Messages, Editing Textual, Editing Textual +@subsubsection Inserting letter to which you're replying + +@cindex inserting messages +@findex @code{mh-yank-cur-msg} + +It is often useful to insert a snippet of text from a letter that +someone mailed to provide some context for your reply. The command +@kbd{C-c C-y} (@code{mh-yank-cur-msg}) does this by yanking a portion of +text from the message to which you're replying and inserting @samp{> } +before each line. + +@cindex mark +@cindex Emacs, mark +@cindex point +@cindex Emacs, point +@cindex region +@cindex Emacs, region + +You can control how much text is included when you run this command. If +you run this command right away, without entering the buffer containing +the message to you, this command will yank the entire message, as is, +into your reply. @footnote{If you'd rather have the header cleaned up, +use @kbd{C-u r} instead of @kbd{r} when replying (see @ref{Replying}).} +If you enter the buffer containing the message sent to you and move the +cursor to a certain point and return to your reply and run @kbd{C-c +C-y}, then the text yanked will range from that point to the end of the +message. Finally, the most common action you'll perform is to enter the +message sent to you, move the cursor to the beginning of a paragraph or +phrase, set the @dfn{mark} with @kbd{C-SPC} or @kbd{C-@@}, and move the +cursor to the end of the paragraph or phrase. The cursor position is +called the @dfn{point}, and the space between the mark and point is +called the @dfn{region}. Having done that, @kbd{C-c C-y} will insert +the region you selected. + +@node Inserting Messages, Header, Inserting Letter, Editing Textual +@subsubsection Inserting messages + +@cindex inserting messages +@findex @code{mh-insert-letter} + +Messages can be inserted with @kbd{C-c C-i} (@code{mh-insert-letter}). +This command prompts you for the folder and message number and inserts +the message, indented by @samp{> }. Certain undesirable header fields +are removed before insertion. If given a prefix argument (like @kbd{C-u +C-c C-i}), the header is left intact, the message is not indented, and +@samp{> } is not inserted before each line. + +@node Header, Recipients, Inserting Messages, Editing Textual +@subsubsection Editing the header + +@cindex editing header +@findex @code{mh-to-field} + +Because the header is part of the message, you can edit the header +fields as you wish. However, several convenience functions exist to +help you create and edit them. For example, the command @kbd{C-c C-f +C-t} (@code{mh-to-field}; alternatively, @kbd{C-c C-f t}) moves the +cursor to the @samp{To:} header field, creating it if necessary. The +functions to move to the @samp{cc:}, @samp{Subject:}, @samp{From:}, +@samp{Bcc:}, and @samp{Dcc:} header fields are similar. + +@findex @code{mh-to-fcc} + +One function behaves differently from the others, namely, @kbd{C-c C-f +C-f} (@code{mh-to-fcc}; alternatively, @kbd{C-c C-f f}). This function +will prompt you for the folder name in which to file a copy of the draft. + +Be sure to leave a row of dashes or a blank line between the header and +the body of the message. + +@node Recipients, Signature, Header, Editing Textual +@subsubsection Checking recipients + +@cindex checking recipients +@cindex @code{whom} +@cindex MH commands, @code{whom} +@findex @code{mh-check-whom} + +The @kbd{C-c C-w} (@code{mh-check-whom}) command expands aliases so you +can check the actual address(es) in the alias. A new buffer is created +with the output of @code{whom}. + +@node Signature, , Recipients, Editing Textual +@subsubsection Inserting your signature + +@cindex inserting signature +@cindex signature +@cindex @file{.signature} +@cindex files, @file{.signature} +@findex @code{mh-insert-signature} + +You can insert your signature at the current cursor location with the +@kbd{C-c C-s} (@code{mh-insert-signature}) command. The text of your +signature is taken from the file @file{~/.signature}. + +@node Editing MIME, Sending Message, Editing Textual, Draft Editing +@subsection Editing Multimedia Messages + +@cindex MIME +@cindex multimedia mail +@cindex @code{mhn} +@cindex MH commands, @code{mhn} + +mh-e has the capability to create multimedia messages. It uses the +@sc{mime} (Multipurpose Internet Mail Extensions) protocol. The +@sc{mime} protocol allows you to incorporate images, sound, video, +binary files, and even commands that fetch a file with @samp{ftp} when +your recipient reads the message! If you were to create a multimedia +message with plain MH commands, you would use @code{mhn}. Indeed, the +mh-e @sc{mime} commands merely insert @code{mhn} directives which are +later expanded by @code{mhn}. + +Each of the mh-e commands for editing multimedia messages or for +incorporating multimedia objects is prefixed with @kbd{C-c C-m} . + +@cindex content types +@cindex MIME, content types + +Several @sc{mime} objects are defined. They are called @dfn{content +types}. The table in @ref{Customizing Draft Editing} contains a list of +the content types that mh-e currently knows about. Several of the mh-e +commands fill in the content type for you, whereas others require you to +enter one. Most of the time, it should be obvious which one to use +(e.g., use @kbd{image/jpeg} to include a @sc{jpeg} image). If not, you +can refer to @sc{rfc} 1521, +@c Footnotes are very fragile. Hence the duplication. +@c The line break in the footnote was necessary since TeX wasn't creating one. +@ifclear html +@footnote{This @sc{rfc} (Request For Comments) is +available via the @sc{url} @* +@file{ftp://ds.internic.net/rfc/rfc1521.txt}.} +@end ifclear +@ifset html +@footnote{This @sc{rfc} (Request For Comments) is +available via the @sc{url} @* +@file{<A HREF="ftp://ds.internic.net/rfc/rfc1521.txt">ftp://ds.internic.net/rfc/rfc1521.txt</A>}.} +@end ifset +which defines the @sc{mime} protocol, for a list of valid content types. + +@cindex content description +@cindex MIME, content description + +You are also sometimes asked for a @dfn{content description}. This is +simply an optional brief phrase, in your own words, that describes the +object. If you don't care to enter a content description, just press +return and none will be included; however, a reader may skip over +multimedia fields unless the content description is compelling. + +Remember: you can always add @code{mhn} directives by hand. + +@menu +* Forwarding MIME:: +* FTP:: +* Tar:: +* Other MIME Objects:: +* Sending MIME:: +@end menu + +@node Forwarding MIME, FTP, Editing MIME, Editing MIME +@subsubsection Forwarding multimedia messages + +@findex @code{mh-mhn-compose-forw} + +Mail may be forwarded with @sc{mime} using the command @kbd{C-c C-m C-f} +(@code{mh-mhn-compose-forw}). You are prompted for a content +description, the name of the folder in which the messages to forward are +located, and the messages' numbers. + +@node FTP, Tar, Forwarding MIME, Editing MIME +@subsubsection Including an ftp reference + +@cindex @code{ftp} +@cindex Unix commands, @code{ftp} +@cindex MIME, @code{ftp} +@findex @code{mh-mhn-compose-anon-ftp} + +You can even have your message initiate an @code{ftp} transfer when the +recipient reads the message. To do this, use the @kbd{C-c C-m C-e} +(@code{mh-mhn-compose-anon-ftp}) command. You are prompted for the +remote host and pathname, the content type, and the content description. + +@node Tar, Other MIME Objects, FTP, Editing MIME +@subsubsection Including tar files + +@cindex @code{tar} +@cindex Unix commands, @code{tar} +@cindex MIME, @code{tar} +@cindex @code{ftp} +@cindex Unix commands, @code{ftp} +@cindex MIME, @code{ftp} +@findex @code{mh-mhn-compose-external-compressed-tar} + +If the remote file (@pxref{FTP}) is a compressed tar file, you can use +@kbd{C-c C-m C-t} (@code{mh-mhn-compose-external-compressed-tar}). +Then, in addition to retrieving the file via anonymous @emph{ftp}, the +file will also be uncompressed and untarred. You are prompted for the +remote host and pathname and the content description. The pathname +should contain at least one @samp{/} (slash), because the pathname is +broken up into directory and name components. + +@node Other MIME Objects, Sending MIME, Tar, Editing MIME +@subsubsection Including other multimedia objects + +@cindex images +@cindex MIME, images +@cindex sound +@cindex MIME, sound +@cindex video +@cindex MIME, video +@findex @code{mh-mhn-compose-insertion} + +Images, sound, and video can be inserted in your message with the +@kbd{C-c C-m C-i} (@code{mh-mhn-compose-insertion}) command. You are +prompted for the filename containing the object, the content type, and a +content description of the object. + +@node Sending MIME, , Other MIME Objects, Editing MIME +@subsubsection Readying multimedia messages for sending + +When you are finished editing a @sc{mime} message, it might look like this: + +@example +@group +@cartouche + 3 24Aug root received fax files on Wed Aug 24 11:00:13 + 4+ 24Aug To:wohler Test<<This is a test message to get the wh + + + + + +--%%-@{+inbox@} 4 msgs (1-4) (MH-Folder Show)--Bot------------------- +To: wohler +cc: +Subject: Test of MIME +-------- +#@@application/octet-stream [Nonexistent ftp test file] \ +access-type=anon-ftp; site=berzerk.com; name=panacea.tar.gz; \ +directory="/pub/" +#audio/basic [Test sound bite] /tmp/noise.au +--**-@{draft@} (MH-Letter)--All-------------------------------------- + +@end cartouche +@i{mh-e @sc{mime} draft} +@end group +@end example + +@cindex @code{mhn} +@cindex MH commands, @code{mhn} +@findex @code{mh-edit-mhn} + +The lines added by the previous commands are @code{mhn} directives and +need to be converted to @sc{mime} directives before sending. This is +accomplished by the command @kbd{C-c C-e} (@code{mh-edit-mhn}), which +runs @code{mhn} on the message. The following screen shows what those +commands look like in full @sc{mime} format. You can see why mail user +agents are usually built to hide these details from the user. + +@example +@group +@cartouche +To: wohler +cc: +Subject: Test of MIME +MIME-Version: 1.0 +Content-Type: multipart/mixed; boundary="----- =_aaaaaaaaaa0" +Content-ID: <1623.777796162.0@@newt.com> + +------- =_aaaaaaaaaa0 +Content-Type: message/external-body; access-type="anon-ftp"; + site="berzerk.com"; name="panacea.tar.gz"; directory="/pub/" + +Content-Type: application/octet-stream +Content-ID: <1623.777796162.1@@newt.com> +Content-Description: Nonexistent ftp test file + +------- =_aaaaaaaaaa0 +Content-Type: audio/basic +Content-ID: <1623.777796162.2@@newt.com> +Content-Description: Test sound bite +Content-Transfer-Encoding: base64 + +Q3JlYXRpdmUgVm9pY2UgRmlsZRoaAAoBKREBQh8AgwCAgH9/f35+fn59fX5+fn5+f39/f39/f3 +f4B/f39/f39/f39/f39/f39+f39+f39/f39/f4B/f39/fn5/f39/f3+Af39/f39/gH9/f39/fn +-----@{draft@} (MH-Letter)--Top-------------------------------------- + +@end cartouche +@i{mh-e @sc{mime} draft ready to send} +@end group +@end example + +@findex @code{mh-revert-mhn-edit} + +This action can be undone by running @kbd{C-c C-m C-u} +(@code{mh-revert-mhn-edit}). It does this by reverting to a backup +file. You are prompted to confirm this action, but you can avoid the +confirmation by adding an argument (for example, @kbd{C-u C-c C-m C-u}). + +@node Sending Message, Killing Draft, Editing MIME, Draft Editing +@subsection Sending a Message + +@cindex sending mail +@findex @code{mh-send-letter} + +When you are all through editing a message, you send it with the +@kbd{C-c C-c} (@code{mh-send-letter}) command. You can give an argument +(as in @kbd{C-u C-c C-c}) to monitor the first stage of the delivery. + +@node Killing Draft, , Sending Message, Draft Editing +@subsection Killing the Draft + +@cindex killing draft +@findex @code{mh-fully-kill-draft} + +If for some reason you are not happy with the draft, you can kill it +instead with @kbd{C-c C-q} (@code{mh-fully-kill-draft}). Emacs then +kills the draft buffer and deletes the draft message. + +@node Moving Mail, Searching, Draft Editing, Using mh-e +@section Moving Your Mail Around + +@cindex processing mail + +This section covers how messages and folders can be moved about or +manipulated. Messages may be incorporated into your @file{+inbox}, +deleted, and refiled. Messages containing @code{shar} or +@code{uuencode} output can be stored. Folders can be visited, sorted, +packed, or deleted. Here's a list of the available commands to do these +things: + +@c Stephen thinks that ? should be documented here, since it also shows +@c which folders a message will be refiled to. + +@table @kbd +@item i +Incorporate new mail into folder (@code{mh-inc-folder}). + +@item d +Delete message (@code{mh-delete-msg}). + +@item C-d +Delete message, don't move to next message (@code{mh-delete-msg-no-motion}). + +@item M-s +Find messages that meet search criteria (@code{mh-search-folder}). + +@item o +Output (refile) message to folder (@code{mh-refile-msg}). + +@item c +Copy message to folder (@code{mh-copy-msg}). + +@item C-o +Output (write) message to file (@code{mh-write-msg-to-file}). + +@item ! +Repeat last output command (@code{mh-refile-or-write-again}). + +@item l +Print message with @code{lpr} (@code{mh-print-msg}). + +@item | +Pipe message through shell command (@code{mh-pipe-msg}). + +@item M-n +Unpack message created with @code{uudecode} or @code{shar} +(@code{mh-store-msg}). + +@item M-l +List all folders (@code{mh-list-folders}). + +@item M-f +Visit folder (@code{mh-visit-folder}). + +@item M-r +Regenerate scan lines (@code{mh-rescan-folder}). + +@item M-x mh-sort-folder +Sort folder. + +@item M-p +Pack folder (@code{mh-pack-folder}). + +@item M-k +Remove folder (@code{mh-kill-folder}). + +@item x +Execute pending refiles and deletes (@code{mh-execute-commands}). + +@item u +Undo pending refile or delete (@code{mh-undo}). + +@item M-u +Undo all pending refiles and deletes (@code{mh-undo-folder}). + +@item q +Quit (@code{mh-quit}). +@end table + +@menu +* Incorporating:: +* Deleting:: +* Organizing:: +* Printing:: +* Files and Pipes:: +* Finishing Up:: +@end menu + +@node Incorporating, Deleting, Moving Mail, Moving Mail +@subsection Incorporating Your Mail + +@cindex incorporating +@findex @code{mh-inc-folder} + +If at any time you receive new mail, incorporate the new mail into your +@samp{+inbox} buffer with @kbd{i} (@code{mh-inc-folder}). Note that +@kbd{i} will display the @samp{+inbox} buffer, even if there isn't any +new mail. You can incorporate mail from any file into the current +folder by specifying a prefix argument; you'll be prompted for the name +of the file to use (for example, @kbd{C-u i ~/mbox @key{RET}}). + +@cindex Emacs, notification of new mail +@cindex notification of new mail +@cindex new mail +@cindex @file{.emacs} +@cindex files, @file{.emacs} + +Emacs can notify you when you have new mail by displaying @samp{Mail} in +the mode line. To enable this behavior, and to have a clock in the mode +line besides, add the following to @file{~/.emacs}: + +@findex @code{display-time} + +@lisp +(display-time) +@end lisp + +@node Deleting, Organizing, Incorporating, Moving Mail +@subsection Deleting Your Mail + +@cindex deleting +@findex @code{mh-delete-msg} +@findex @code{mh-delete-msg-no-motion} + +To mark a message for deletion, use the @kbd{d} (@code{mh-delete-msg}) +command. A @samp{D} is placed by the message in the scan window, and +the next message is displayed. If the previous command had been +@kbd{p}, then the next message displayed is the message previous to the +message just deleted. If you specify a prefix argument, you will be +prompted for a sequence (@pxref{Sequences}) to delete (for example, +@kbd{C-u d frombob RET}). The @kbd{x} command actually carries out the +deletion (@pxref{Finishing Up}). @kbd{C-d} +(@code{mh-delete-msg-no-motion}) marks the message for deletion but +leaves the cursor at the current message in case you wish to perform +other operations on the message. + +@node Organizing, Printing, Deleting, Moving Mail +@subsection Organizing Your Mail with Folders + +@cindex using folders +@cindex @code{folder} +@cindex MH commands, @code{folder} +@cindex @code{refile} +@cindex MH commands, @code{refile} +@findex @code{mh-refile-msg} + +mh-e has analogies for each of the MH @code{folder} and @code{refile} +commands. To refile a message in another folder, use the @kbd{o} +(@code{mh-refile-msg}) (mnemonic: ``output'') command. You are prompted +for the folder name. + +@findex @code{mh-refile-or-write-again} + +If you are refiling several messages into the same folder, you can use +the @kbd{!} (@code{mh-refile-or-write-again}) command to repeat the last +refile or write (see the description of @kbd{C-o} in @ref{Files and +Pipes}). Or, place the messages into a sequence (@ref{Sequences}) and +specify a prefix argument to @kbd{o}, in which case you'll be prompted +for the name of the sequence (for example, @kbd{C-u o search RET}). + +@findex @code{mh-copy-msg} + +If you wish to copy a message to another folder, you can use the @kbd{c} +(@code{mh-copy-msg}) command (see the @code{-link} argument to +@code{refile}(1)). You are prompted for a folder, and you can specify a +prefix argument if you want to copy a sequence into another folder. In +this case, you are then prompted for the sequence. Note that unlike the +@kbd{o} command, the copy takes place immediately. The original copy +remains in the current folder. + +@findex @code{mh-visit-folder} + +When you want to read the messages that you have refiled into folders, +use the @kbd{M-f} (@code{mh-visit-folder}) command to visit the folder. +You are prompted for the folder name. + +@findex @code{mh-list-folders} +@findex @code{mh-visit-folder} +@findex @code{mh-sort-folder} +@findex @code{mh-pack-folder} +@findex @code{mh-rescan-folder} + +Other commands you can perform on folders include: @kbd{M-l} +(@code{mh-list-folders}), to list all the folders in your mail +directory; @kbd{M-k} (@code{mh-kill-folder}), to remove a folder; +@kbd{M-x mh-sort-folder}, to sort the messages by date (see +@code{sortm}(1) to see how to sort by other criteria); @kbd{M-p} +(@code{mh-pack-folder}), to pack a folder, removing gaps from the +numbering sequence; and @kbd{M-r} (@code{mh-rescan-folder}), to rescan +the folder, which is useful to grab all messages in your @file{+inbox} +after processing your new mail for the first time. If you don't want to +rescan the entire folder, give @kbd{M-r} or @kbd{M-p} a prefix argument +and you'll be prompted for a range of messages to display (for instance, +@kbd{C-u M-r last:50 RET}). + +@node Printing, Files and Pipes, Organizing, Moving Mail +@subsection Printing Your Mail + +@cindex printing +@cindex @code{mhl} +@cindex MH commands, @code{mhl} +@cindex @code{lpr} +@cindex Unix commands, @code{lpr} +@findex @code{mh-print-msg} + +Printing mail is simple. Enter @kbd{l} (@code{mh-print-msg}) (for +@i{l}ine printer or @i{l}pr). The message is formatted with @code{mhl} +and printed with the @code{lpr} command. You can print all the messages +in a sequence by specifying a prefix argument, in which case you are +prompted for the name of the sequence (as in @kbd{C-u l frombob RET}). + +@node Files and Pipes, Finishing Up, Printing, Moving Mail +@subsection Files and Pipes + +@cindex using files +@cindex using pipes +@findex @code{mh-write-msg-to-file} + +mh-e does offer a couple of commands that are not a part of MH@. The +first one, @kbd{C-o} (@code{mh-write-msg-to-file}), writes a message to +a file (think of the @kbd{o} as in "output"). You are prompted for the +filename. If the file already exists, the message is appended to it. +You can also write the message to the file without the header by +specifying a prefix argument (such as @kbd{C-u C-o /tmp/foobar RET}). +Subsequent writes to the same file can be made with the @kbd{!} +command. + +@findex @code{mh-pipe-msg} + +You can also pipe the message through a Unix shell command with the +@kbd{|} (@code{mh-pipe-msg}) command. You are prompted for the +Unix command through which you wish to run your message. If you +give an argument to this command, the message header is included in the +text passed to the command (the contrived example @kbd{C-u | lpr} +would be done with the @kbd{l} command instead). + +@cindex @code{shar} +@cindex Unix commands, @code{shar} +@cindex @code{uuencode} +@cindex Unix commands, @code{uuencode} +@findex @code{mh-store-msg} + +If the message is a shell archive @code{shar} or has been run through +@code{uuencode} use @kbd{M-n} (@code{mh-store-msg}) to extract the body +of the message. The default directory for extraction is the current +directory, and you have a chance to specify a different extraction +directory. The next time you use this command, the default directory is +the last directory you used. + +@node Finishing Up, , Files and Pipes, Moving Mail +@subsection Finishing Up + +@cindex expunging refiles and deletes +@findex @code{mh-undo} +@findex @code{mh-undo-folder} + +If you've deleted a message or refiled it, but changed your mind, you +can cancel the action before you've executed it. Use @kbd{u} +(@code{mh-undo}) to undo a refile on or deletion of a single message. +You can also undo refiles and deletes for messages that belong to a +given sequence by specifying a prefix argument. You'll be prompted for +the name of the sequence (as in @kbd{C-u u frombob RET}). +Alternatively, you can use @kbd{M-u} (@code{mh-undo-folder}) to undo all +refiles or deletes in the current folder. + +@findex @code{mh-execute-commands} + +If you've marked messages to be deleted or refiled and you want to go +ahead and delete or refile the messages, use @kbd{x} +(@code{mh-execute-commands}). Many mh-e commands that may affect the +numbering of the messages (such as @kbd{M-r} or @kbd{M-p}) will ask if you +want to process refiles or deletes first and then either run @kbd{x} for +you or undo the pending refiles and deletes, which are lost. + +@findex @code{mh-rmail} +@findex @code{mh-quit} + +When you want to quit using mh-e and go back to editing, you can use the +@kbd{q} (@code{mh-quit}) command. This buries the buffers of the +current mh-e folder and restores the buffers that were present when you +first ran @kbd{M-x mh-rmail}. You can later restore your mh-e session +by selecting the @samp{+inbox} buffer or by running @kbd{M-x mh-rmail} +again. + +@node Searching, Sequences, Moving Mail, Using mh-e +@section Searching Through Messages + +@cindex searching +@findex @code{mh-search-folder} + +You can search a folder for messages to or from a particular person or +about a particular subject. In fact, you can also search for messages +containing selected strings in any arbitrary header field or any string +found within the messages. Use the @kbd{M-s} (@code{mh-search-folder}) +command. You are first prompted for the name of the folder to search +and then placed in the following buffer in MH-Pick mode: + +@example +@group +@cartouche +From: # +To: +Cc: +Date: +Subject: +-------- + + + + + + + + + +--**-Emacs: pick-pattern (MH-Pick)------All---------------------------- + +@end cartouche +@i{Pick window} +@end group +@end example + +@cindex @code{pick} +@cindex MH commands, @code{pick} + +Edit this template by entering your search criteria in an appropriate +header field that is already there, or create a new field yourself. If +the string you're looking for could be anywhere in a message, then place +the string underneath the row of dashes. The @kbd{M-s} command uses the +MH command @code{pick} to do the real work, so read @code{pick}(1) to +find out more about how to enter the criteria. + +There are no semantics associated with the search criteria---they are +simply treated as strings. Case is ignored when all lowercase is used, +and regular expressions (a la @code{ed}) are available. It is all right +to specify several search criteria. What happens then is that a logical +@emph{and} of the various fields is performed. If you prefer a logical +@emph{or} operation, run @kbd{M-s} multiple times. + +As an example, let's say that we want to find messages from Ginnean +about horseback riding in the Kosciusko National Park (Australia) during +January, 1994. Normally we would start with a broad search and narrow +it down if necessary to produce a manageable amount of data, but we'll +cut to the chase and create a fairly restrictive set of criteria as +follows: + +@example +@group +From: ginnean +To: +Cc: +Date: Jan 1994 +Subject: horse.*kosciusko +-------- +@end group +@end example + +@findex @code{mh-to-field} + +As with MH-Letter mode, MH-Pick provides commands like +@kbd{C-c C-f C-t} to help you fill in the blanks. + +@table @kbd +@item C-c C-f C-t +Move to @samp{To:} header field (@code{mh-to-field}). + +@item C-c C-f C-c +Move to @samp{cc:} header field (@code{mh-to-field}). + +@item C-c C-f C-s +Move to @samp{Subject:} header field (@code{mh-to-field}). + +@item C-c C-f C-f +Move to @samp{From:} header field (@code{mh-to-field}). + +@item C-c C-f C-b +Move to @samp{Bcc:} header field (@code{mh-to-field}). + +@item C-c C-f C-f +Move to @samp{Fcc:} header field (@code{mh-to-field}). + +@item C-c C-f C-d +Move to @samp{Dcc:} header field (@code{mh-to-field}). + +@item C-c C-c +Execute the search (@code{mh-do-pick-search}). +@end table + +@findex @code{mh-do-pick-search} + +To perform the search, type @kbd{C-c C-c} (@code{mh-do-pick-search}). +The selected messages are placed in the @i{search} sequence, which you +can use later in forwarding (@pxref{Forwarding}), printing +(@pxref{Printing}), or narrowing your field of view (@pxref{Sequences}). +Subsequent searches are appended to the @i{search} sequence. If, +however, you wish to start with a clean slate, first delete the +@i{search} sequence (how to do this is discussed in @ref{Sequences}). + +@cindex MH-Folder mode +@cindex modes, MH-Folder + +If you're searching in a folder that is already displayed in a +MH-Folder buffer, only those messages contained in the buffer are +used for the search. Therefore, if you want to search in all messages, +first kill the folder's buffer with @kbd{C-x k} or scan the entire +folder with @kbd{M-r}. + +@node Sequences, Miscellaneous, Searching, Using mh-e +@section Using Sequences + +@cindex sequences + +For the whole scoop on MH sequences, refer to @code{mh-sequence}(5). As +you've read, several of the mh-e commands can operate on a sequence, +which is a shorthand for a range or group of messages. For example, you +might want to forward several messages to a friend or colleague. Here's +how to manipulate sequences. + +@table @kbd +@item % +Put message in a sequence (@code{mh-put-msg-in-seq}). + +@item ? +Display sequences that message belongs to (@code{mh-msg-is-in-seq}). + +@item M-q +List all sequences in folder (@code{mh-list-sequences}). + +@item M-% +Remove message from sequence (@code{mh-delete-msg-from-seq}). + +@item M-# +Delete sequence (@code{mh-delete-seq}). + +@item C-x n +Restrict display to messages in sequence (@code{mh-narrow-to-seq}). + +@item C-x w +Remove restriction; display all messages (@code{mh-widen}). + +@item M-x mh-update-sequences +Push mh-e's state out to MH@. +@end table + +@cindex @code{pick} +@cindex MH commands, @code{pick} +@findex @code{mh-put-msg-in-seq} + +To place a message in a sequence, use @kbd{%} (@code{mh-put-msg-in-seq}) +to do it manually, or use the MH command @code{pick} or the mh-e version +of @code{pick} (@ref{Searching}) which create a sequence automatically. +Give @kbd{%} a prefix argument and you can add all the messages in one +sequence to another sequence (for example, @kbd{C-u % SourceSequence +RET}). + +@cindex MH-Folder mode +@cindex modes, MH-Folder +@findex @code{mh-narrow-to-seq} +@findex @code{mh-widen} + +Once you've placed some messages in a sequence, you may wish to narrow +the field of view to just those messages in the sequence you've created. +To do this, use @kbd{C-x n} (@code{mh-narrow-to-seq}). You are prompted +for the name of the sequence. What this does is show only those +messages that are in the selected sequence in the MH-Folder buffer. In +addition, it limits further mh-e searches to just those messages. When +you want to widen the view to all your messages again, use @kbd{C-x w} +(@code{mh-widen}). + +@findex @code{mh-msg-is-in-seq} +@findex @code{mh-list-sequences} + +You can see which sequences a message is in with the @kbd{?} +(@code{mh-msg-is-in-seq}) command. +@c Doesn't work: +@c use a prefix argument to query a +@c message other than the current one (as in @kbd{C-u ? 42 RET}). +Or, you can list all sequences in a selected folder (default is current +folder) with @kbd{M-q} (@code{mh-list-sequences}). + +@findex @code{mh-delete-msg-from-seq} +@findex @code{mh-delete-seq} + +If you want to remove a message from a sequence, use @kbd{M-%} +(@code{mh-delete-msg-from-seq}), and if you want to delete an entire +sequence, use @kbd{M-#} (@code{mh-delete-seq}). In the latter case you +are prompted for the sequence to delete. Note that this deletes only +the sequence, not the messages in the sequence. If you want to delete +the messages, use @kbd{C-u d} (see @ref{Deleting} above). + +@cindex @code{mark} +@cindex MH commands, @code{mark} + +@findex @code{mh-update-sequences} + +Two sequences are maintained internally by mh-e and pushed out to MH +when you type either the @kbd{x} or @kbd{q} command. They are the +sequence specified by your @samp{Unseen-Sequence:} profile entry and +@i{cur}. However, you can also just update MH's state with the command +@kbd{M-x mh-update-sequences}. See @ref{Customizing Viewing} for an +example of how this command might be used. + +With the exceptions of @kbd{C-x n} and @kbd{C-x w}, the underlying MH +command dealing with sequences is @code{mark}. + +@node Miscellaneous, , Sequences, Using mh-e +@section Miscellaneous Commands + +@findex @code{mh-version} + +One other command worth noting is @kbd{M-x mh-version}. Since there +were a few changes in command letters between @w{Versions 3} and 4, use +this command to see which version you are running. This command didn't +exist before @w{Version 4}, so the message @samp{[No match]} +indicates that it's time to upgrade (@pxref{Getting mh-e}). In the +meantime, use the older commands that are listed in @ref{Changes to +mh-e}. The output of @kbd{M-x mh-version} should also be included with +any bug report you send (@pxref{Bug Reports}). + +@node Customizing mh-e, Odds and Ends, Using mh-e, Top +@chapter Customizing mh-e + +Until now, we've talked about the mh-e commands as they work ``out of the +box.'' Of course, it is also possible to reconfigure mh-e +@c to fit the needs of even the most demanding user. ??? +beyond recognition. The following sections describe all of the +customization variables, show the defaults, and make recommendations for +customization. The outline of this chapter is identical to that of +@ref{Using mh-e}, to make it easier to find the variables you'd need to +modify to affect a particular command. + +However, when customizing your mail environment, first try to change +what you want in MH, and only change mh-e if changing MH is not +possible. That way you will get the same behavior inside and outside +GNU Emacs. Note that mh-e does not provide hooks for customizations +that can be done in MH; this omission is intentional. + +@cindex @file{.emacs} +@cindex files, @file{.emacs} + +Many string or integer variables are easy enough to modify using Emacs +Lisp. Any such modifications should be placed in a file called +@file{.emacs} in your home directory (that is, @file{~/.emacs}). For +example, to modify the variable that controls printing, you could add: + +@vindex @code{mh-lpr-command-format}, example + +@lisp +(setq mh-lpr-command-format "nenscript -G -r -2 -i'%s'") +@end lisp + +@ref{Customizing Printing} talks more about this variable. + +@cindex setting variables +@cindex Emacs, setting variables + +Variables can also hold Boolean values. In Emacs Lisp, the Boolean +values are @code{nil}, which means false, and @code{t}, which means true. +Usually, variables are turned off by setting their value to @code{nil}, as +in + +@vindex @code{mh-bury-show-buffer}, example + +@lisp +(setq mh-bury-show-buffer nil) +@end lisp + +which keeps the MH-Show buffer at the top of the buffer stack. +To turn a variable on, you use + +@lisp +(setq mh-bury-show-buffer t) +@end lisp + +which places the MH-Show buffer at the bottom of the buffer +stack. However, the text says to turn on a variable by setting it to a +@emph{non-@code{nil}} value, because sometimes values other than @code{t} are +meaningful (for example, see @code{mhl-formfile}, described in +@ref{Customizing Viewing}). Other variables, such as hooks, involve a +little more Emacs Lisp programming expertise. + +You can also ``preview'' the effects of changing variables before +committing the changes to @file{~/.emacs}. Variables can be changed in +the current Emacs session by using @kbd{M-x set-variable}. + +@c XXX Stephen says: would be easier to just call them functions, which +@c you mostly do. +In general, @dfn{commands} in this text refer to Emacs Lisp functions. +Programs outside of Emacs are specifically called MH commands, shell +commands, or Unix commands. + +@cindex Emacs, Emacs Lisp manual +@cindex Emacs, online help +@cindex online help +@cindex Emacs, info +@cindex info + +I hope I've included enough examples here to get you well on your way. +If you want to explore Emacs Lisp further, a programming manual does +exist, +@c Yes, some of the stuff in the following sections is redundant, but +@c TeX barfs if the @ifs are inside the @footnote. +@iftex +@footnote{The @cite{GNU Emacs Lisp Reference Manual} may be available +online in the Info system by typing @kbd{C-h i m Emacs Lisp RET}. If +not, you can order a printed manual, which has the desirable side-effect +of helping to support the Free Software Foundation which made all this +great software available. You can find an order form by running +@kbd{C-h C-d}, or you can request an order form from +@i{gnu@@gnu.org}.} +@end iftex +@ifinfo +@footnote{Perhaps you can find the online version of @ref{Top, The GNU +Emacs Lisp Reference Manual, , elisp, GNU Emacs Lisp Reference Manual}. +If not, you can order a printed manual, which has the desirable +side-effect of helping to support the Free Software Foundation which +made all this great software available. You can find an order form by +running @kbd{C-h C-d}, or you can request an order form from +@i{gnu@@gnu.org}.} +@end ifinfo +and you can look at the code itself for examples. Look in the Emacs +Lisp directory on your system (such as @file{/usr/local/lib/emacs/lisp}) +and find all the @file{mh-*.el} files there. When calling mh-e and +other Emacs Lisp functions directly from Emacs Lisp code, you'll need to +know the correct arguments. Use the online help for this. For example, +try @kbd{C-h f mh-execute-commands RET}. If you write your own +functions, please do not prefix your symbols (variables and functions) +with @code{mh-}. This prefix is reserved for the mh-e package. To +avoid conflicts with existing mh-e symbols, use a prefix like @code{my-} +or your initials. + +@menu +* Customizing Reading:: +* Customizing Sending:: +* Customizing Draft Editing:: +* Customizing Moving Mail:: +* Customizing Searching:: +@end menu + +@node Customizing Reading, Customizing Sending, Customizing mh-e, Customizing mh-e +@section Reading Your Mail + +@cindex reading mail +@cindex @file{.emacs} +@cindex files, @file{.emacs} + +I'll start out by including a function that I use as a front end to +mh-e. @footnote{Stephen Gildea's favorite binding is +@kbd{(global-set-key "\C-cr" 'mh-rmail)}.} It toggles between your +working window configuration, which may be quite involved---windows +filled with source, compilation output, man pages, and other +documentation---and your mh-e window configuration. Like the rest of +the customization described in this chapter, simply add the following +code to @file{~/.emacs}. Don't be intimidated by the size of this +example; most customizations are only one line. + +@iftex +@filbreak +@end iftex + +@findex @code{mh-rmail}, example + +@lisp +@group +@i{Starting mh-e} + +(defvar my-mh-screen-saved nil + "Set to non-@code{nil} when mh-e window configuration shown.") +(defvar my-normal-screen nil "Normal window configuration.") +(defvar my-mh-screen nil "mh-e window configuration.") + +(defun my-mh-rmail (&optional arg) + "Toggle between mh-e and normal screen configurations. +With non-@code{nil} or prefix argument, @i{inc} mailbox as well +when going into mail." + (interactive "P") ; @r{user callable function, P=prefix arg} + (setq my-mh-screen-saved ; @r{save state} + (cond + ;; @r{Bring up mh-e screen if arg or normal window configuration.} + ;; @r{If arg or +inbox buffer doesn't exist, run mh-rmail.} + ((or arg (null my-mh-screen-saved)) + (setq my-normal-screen (current-window-configuration)) + (if (or arg (null (get-buffer "+inbox"))) + (mh-rmail) + (set-window-configuration my-mh-screen)) + t) ; @r{set my-mh-screen-saved to @code{t}} + ;; @r{Otherwise, save mh-e screen and restore normal screen.} + (t + (setq my-mh-screen (current-window-configuration)) + (set-window-configuration my-normal-screen) + nil)))) ; @r{set my-mh-screen-saved to nil} + +(global-set-key "\C-x\r" 'my-mh-rmail) ;@r{ call with C-x RET} +@end group +@end lisp + +If you type an argument (@kbd{C-u}) or if @code{my-mh-screen-saved} +is @code{nil} (meaning a non-mh-e window configuration), the current window +configuration is saved, either +inbox is displayed or @code{mh-rmail} is +run, and the mh-e window configuration is shown. Otherwise, the mh-e +window configuration is saved and the original configuration is +displayed. + +Now to configure mh-e. The following table lists general mh-e variables +and variables that are used while reading mail. +@c XXX Seth wishes the descriptions to be more parallel. That is, +@c some are actions, and some are objects. Hmmm. + +@table @code +@item mh-progs +Directory containing MH programs (default: dynamic). + +@item mh-lib +Directory containing MH support files and programs (default: dynamic). + +@item mh-do-not-confirm +Don't confirm on non-reversible commands (default: @code{nil}). + +@item mh-summary-height +Number of scan lines to show (includes mode line) (default: 4). + +@item mh-folder-mode-hook +Functions to run in MH-Folder mode (default: @code{nil}). + +@item mh-clean-message-header +Remove extraneous headers (default: @code{nil}). + +@item mh-invisible-headers +Headers to hide (default: @samp{"^Received: \\| ^Message-Id: \\| +^Remailed-\\| ^Via: \\| ^Mail-from: \\| ^Return-Path: \\| ^In-Reply-To: +\\| ^Resent-"}). + +@item mh-visible-headers +Headers to display (default: @code{nil}). + +@item mhl-formfile +Format file for @code{mhl} (default: @code{nil}). + +@item mh-show-hook +Functions to run when showing message (default: @code{nil}). + +@item mh-show-mode-hook +Functions to run when showing message (default: @code{nil}). + +@item mh-bury-show-buffer +Leave show buffer at bottom of stack (default: @code{t}). + +@item mh-show-buffer-mode-line-buffer-id +Name of show buffer in mode line (default: @samp{"@{show-%s@} %d"}). +@end table + +@vindex @code{mh-progs} +@vindex @code{mh-lib} + +The two variables @code{mh-progs} and @code{mh-lib} are used to tell +mh-e where the MH programs and supporting files are kept, respectively. +mh-e does try to figure out where they are kept for itself by looking in +common places and in the user's @samp{PATH} environment variable, but if +it cannot find the directories, or finds the wrong ones, you should set +these variables. The name of the directory should be placed in double +quotes, and there should be a +trailing slash (@samp{/}). See the example in @ref{Getting Started}. + +@vindex @code{mh-do-not-confirm} + +If you never make mistakes, and you do not like confirmations for your +actions, you can set @code{mh-do-not-confirm} to a non-@code{nil} value to +disable confirmation for unrecoverable commands such as @kbd{M-k} +(@code{mh-kill-folder}) and @kbd{M-u} (@code{mh-undo-folder}). Here's +how you set boolean values: + +@lisp +(setq mh-do-not-confirm t) +@end lisp + +@vindex @code{mh-summary-height} +@cindex MH-Folder mode +@cindex modes, MH-Folder + +@c Prevent page break between paragraph and example. +@need 2000 +The variable @code{mh-summary-height} controls the number of scan lines +displayed in the MH-Folder window, including the mode line. The +default value of 4 means that 3 scan lines are displayed. Here's how +you set numerical values: + +@lisp +(setq mh-summary-height 2) ; @r{only show the current scan line} +@end lisp + +@vindex @code{mh-bury-show-buffer} +@cindex MH-Folder mode +@cindex modes, MH-Folder + +Normally the buffer for displaying messages is buried at the bottom at +the buffer stack. You may wish to disable this feature by setting +@code{mh-bury-show-buffer} to @code{nil}. One advantage of not burying the +show buffer is that one can delete the show buffer more easily in an +electric buffer list because of its proximity to its associated +MH-Folder buffer. Try running @kbd{M-x electric-buffer-list} to +see what I mean. + +@vindex @code{mh-folder-mode-hook} +@cindex MH-Folder mode +@cindex modes, MH-Folder + +The hook @code{mh-folder-mode-hook} is called when a new folder is +created with MH-Folder mode. This could be used to set your own +key bindings, for example: + +@vindex @code{mh-folder-mode-hook}, example + +@lisp +@group +@i{Create additional key bindings via mh-folder-mode-hook} + +(defvar my-mh-init-done nil "Non-@code{nil} when one-time mh-e settings made.") + +(defun my-mh-folder-mode-hook () + "Hook to set key bindings in MH-Folder mode." + (if (not my-mh-init-done) ; @r{only need to bind the keys once } + (progn + (local-set-key "/" 'search-msg) + (local-set-key "b" 'mh-burst-digest) ; @r{better use of @kbd{b}} + (setq my-mh-init-done t)))) + +;;; @r{Emacs 19} +(add-hook 'mh-folder-mode-hook 'my-mh-folder-mode-hook) +;;; @r{Emacs 18} +;;; @r{(setq mh-folder-mode-hook (cons 'my-mh-folder-mode-hook} +;;; @r{mh-folder-mode-hook))} + +(defun search-msg () + "Search for a regexp in the current message." + (interactive) ; @r{user function} + (save-window-excursion + (other-window 1) ; @r{go to next window} + (isearch-forward-regexp))) ; @r{string search; hit return (ESC} + ; @r{in Emacs 18) when done} +@end group +@end lisp + +@menu +* Customizing Viewing:: +* Customizing Moving Around:: +@end menu + +@node Customizing Viewing, Customizing Moving Around, Customizing Reading, Customizing Reading +@subsection Viewing Your Mail + +@vindex @code{mh-clean-message-header} +@vindex @code{mh-invisible-headers} +@vindex @code{mh-visible-headers} + +Several variables control what displayed messages look like. Normally +messages are delivered with a handful of uninteresting header fields. +You can make them go away by setting @code{mh-clean-message-header} to a +non-@code{nil} value. The header can then be cleaned up in two ways. By +default, the header fields in @code{mh-invisible-headers} are removed. +On the other hand, you could set @code{mh-visible-headers} to the fields +that you would like to see. If this variable is set, +@code{mh-invisible-headers} is ignored. I suggest that you not set +@code{mh-visible-headers} since if you use this variable, you might miss +a lot of header fields that you'd rather not miss. As an example of how +to set a string variable, @code{mh-visible-headers} can be set to show a +minimum set of header fields (see (@ref{Regexps, , Syntax of Regular +Expressions, emacs, The GNU Emacs Manual}, for a description of the +special characters in this string): + +@lisp +(setq mh-visible-headers "^From: \\|^Subject: \\|^Date: ") +@end lisp + +@cindex @code{mhl} +@cindex MH commands, @code{mhl} +@vindex @code{mhl-formfile} + +Normally mh-e takes care of displaying messages itself (rather than +calling an MH program to do the work). If you'd rather have @code{mhl} +display the message (within mh-e), set the variable @code{mhl-formfile} +to a non-@code{nil} value. You can set this variable either to @code{t} +to use the default format file or to a filename if you have your own +format file (@code{mhl}(1) tells you how to write one). When writing +your own format file, use a nonzero value for @code{overflowoffset} to +ensure the header is RFC 822 compliant and parsable by mh-e. +@code{mhl} is always used for printing and forwarding; in this case, the +value of @code{mhl-formfile} is consulted if it is a filename. + +@vindex @code{mh-show-mode-hook} + +Two hooks can be used to control how messages are displayed. The first +hook, @code{mh-show-mode-hook}, is called early on in the process of +displaying of messages. It is used to perform some actions on the +contents of messages, such as highlighting the header fields. If you're +running Emacs 19 under the X Window System, the following example will +highlight the @samp{From:} and @samp{Subject:} header fields. This is a +very nice feature indeed. + +@vindex @code{mh-show-mode-hook}, example + +@lisp +@group +@i{Emphasize header fields in different fonts via mh-show-mode-hook} + +(defvar my-mh-keywords + '(("^From: \\(.*\\)" 1 'bold t) + ("^Subject: \\(.*\\)" 1 'highlight t)) + "mh-e additions for font-lock-keywords.") + +(defun my-mh-show-mode-hook () + "Hook to turn on and customize fonts." + (require 'font-lock) ; @r{for font-lock-keywords below} + (make-local-variable 'font-lock-mode-hook) ; @r{don't affect other buffers} + (add-hook 'font-lock-mode-hook ; @r{set a hook with inline function} + (function ; @r{modifies font-lock-keywords when} + (lambda () ; @r{font-lock-mode run} + (setq font-lock-keywords + (append my-mh-keywords font-lock-keywords))))) + (font-lock-mode 1)) ; @r{change the typefaces} + +(if window-system ; @r{can't do this on @sc{ASCII} terminal} + (add-hook 'mh-show-mode-hook 'my-mh-show-mode-hook)) +@end group +@end lisp + +@vindex @code{mh-show-hook} + +The second hook, @code{mh-show-hook}, is the last thing called after +messages are displayed. It's used to affect the behavior of mh-e in +general or when @code{mh-show-mode-hook} is too early. For example, if +you wanted to keep mh-e in sync with MH, you could use +@code{mh-show-hook} as follows: + +@vindex @code{mh-show-hook}, example + +@lisp +(add-hook 'mh-show-hook 'mh-update-sequences) +@end lisp + +@vindex @code{mh-show-buffer-mode-line-buffer-id} +@cindex MH-Show mode +@cindex modes, MH-Show + +The function @code{mh-update-sequences} is documented in @ref{Finishing +Up}. For those who like to modify their mode lines, use +@code{mh-show-buffer-mode-line-buffer-id} to modify the mode line in the +MH-Show buffers. Place the two escape strings @samp{%s} and @samp{%d}, +which will display the folder name and the message number, respectively, +somewhere in the string in that order. The default value of +@samp{"@{show-%s@} %d"} yields a mode line of + +@example +-----@{show-+inbox@} 4 (MH-Show)--Bot---------------------------------- +@end example + +@node Customizing Moving Around, , Customizing Viewing, Customizing Reading +@subsection Moving Around + +@cindex moving between messages +@cindex MH-Show mode +@cindex modes, MH-Show +@cindex MH-Folder mode +@cindex modes, MH-Folder +@vindex @code{mh-recenter-summary-p} + +When you use @kbd{t} (@code{mh-toggle-showing}) to toggle between show +mode and scan mode, the MH-Show buffer is hidden and the +MH-Folder buffer is left alone. Setting +@code{mh-recenter-summary-p} to a non-@code{nil} value causes the toggle to +display as many scan lines as possible, with the cursor at the middle. +The effect of @code{mh-recenter-summary-p} is rather useful, but it can +be annoying on a slow network connection. + +@node Customizing Sending, Customizing Draft Editing, Customizing Reading, Customizing mh-e +@section Sending Mail + +@cindex sending mail + +You may wish to start off by adding the following useful key bindings to +your @file{.emacs} file: + +@lisp +(global-set-key "\C-xm" 'mh-smail) +(global-set-key "\C-x4m" 'mh-smail-other-window) +@end lisp + +In addition, several variables are useful when sending mail or replying +to mail. They are summarized in the following table. + +@table @code +@item mh-comp-formfile +Format file for drafts (default: @samp{"components"}). + +@item mh-repl-formfile +Format file for replies (default: @samp{"replcomps"}). + +@item mh-letter-mode-hook +Functions to run in MH-Letter mode (default: @code{nil}). + +@item mh-compose-letter-function +Functions to run when starting a new draft (default: @code{nil}). + +@item mh-reply-default-reply-to +Whom reply goes to (default: @code{nil}). + +@item mh-forward-subject-format +Format string for forwarded message subject (default: @samp{"%s: %s"}). + +@item mh-redist-full-contents +@code{send} requires entire message (default: @code{nil}). + +@item mh-new-draft-cleaned-headers +Remove these header fields from re-edited draft (default: +@samp{"^Date:\\| ^Received:\\| ^Message-Id:\\| ^From:\\| ^Sender:\\| +^Delivery-Date:\\| ^Return-Path:"}). +@end table + +@cindex @code{comp} +@cindex MH commands, @code{comp} +@vindex @code{mh-comp-formfile} +@cindex @file{components} +@cindex files, @file{components} +@cindex @code{repl} +@cindex MH commands, @code{repl} +@cindex @file{replcomps} +@cindex files, @file{replcomps} +@vindex @code{mh-repl-formfile} + +Since mh-e does not use @code{comp} to create the initial draft, you +need to set @code{mh-comp-formfile} to the name of your components file +if it isn't @file{components}. This is the name of the file that +contains the form for composing messages. If it does not contain an +absolute pathname, mh-e searches for the file first in your MH directory +and then in the system MH library directory (such as +@file{/usr/local/lib/mh}). Replies, on the other hand, are built using +@code{repl}. You can change the location of the field file from the +default of @file{replcomps} by modifying @code{mh-repl-formfile}. + +@vindex @code{mh-letter-mode-hook} +@cindex @code{repl} +@cindex MH commands, @code{repl} +@cindex @file{components} +@cindex files, @file{components} + +Two hooks are provided to run commands on your freshly created draft. +The first hook, @code{mh-letter-mode-hook}, allows you to do some +processing before editing a letter. For example, you may wish to modify +the header after @code{repl} has done its work, or you may have a +complicated @file{components} file and need to tell mh-e where the +cursor should go. Here's an example of how you would use this hook---all +of the other hooks are set in this fashion as well. + +@findex @code{mh-insert-signature}, example + +@lisp +@group +@i{Prepare draft for editing via mh-letter-mode-hook} + +(defvar letter-mode-init-done nil + "Non-@code{nil} when one-time mh-e settings have made.") + +(defun my-mh-letter-mode-hook () + "Hook to prepare letter for editing." + (if (not letter-mode-init-done) ; @r{only need to bind the keys once} + (progn + (local-set-key "\C-ctb" 'add-enriched-text) + (local-set-key "\C-cti" 'add-enriched-text) + (local-set-key "\C-ctf" 'add-enriched-text) + (local-set-key "\C-cts" 'add-enriched-text) + (local-set-key "\C-ctB" 'add-enriched-text) + (local-set-key "\C-ctu" 'add-enriched-text) + (local-set-key "\C-ctc" 'add-enriched-text) + (setq letter-mode-init-done t))) + (setq fill-prefix " ") ; @r{I find indented text easier to read} + (save-excursion + (goto-char (point-max)) ; @r{go to end of message to} + (mh-insert-signature))) ; @r{insert signature} + +(add-hook 'mh-letter-mode-hook 'my-mh-letter-mode-hook) +@end group +@end lisp + +The function, @code{add-enriched-text} is defined in the example in +@ref{Customizing Editing MIME}. + +@vindex @code{mh-compose-letter-function} + +The second hook, a function really, is +@code{mh-compose-letter-function}. Like @code{mh-letter-mode-hook}, it +is called just before editing a new message; however, it is the last +function called before you edit your message. The consequence of this +is that you can write a function to write and send the message for you. +This function is passed three arguments: the contents of the @samp{To:}, +@samp{Subject:}, and @samp{cc:} header fields. + +@menu +* Customizing Replying:: +* Customizing Forwarding:: +* Customizing Redistributing:: +* Customizing Old Drafts:: +@end menu + +@node Customizing Replying, Customizing Forwarding, Customizing Sending, Customizing Sending +@subsection Replying to Mail + +@cindex replying +@vindex @code{mh-reply-default-reply-to} + +If you find that most of the time that you specify @kbd{cc} when you +reply to a message, set @code{mh-reply-default-reply-to} to @samp{cc}. +This variable is normally set to @code{nil} so that you are prompted for +the recipient of a reply. It can be set to one of @samp{from}, +@samp{to}, or @samp{cc}; you are then no longer prompted for the +recipient(s) of your reply. + +@node Customizing Forwarding, Customizing Redistributing, Customizing Replying, Customizing Sending +@subsection Forwarding Mail + +@cindex forwarding +@vindex @code{mh-forward-subject-format} + +When forwarding a message, the format of the @samp{Subject:} header +field can be modified by the variable @code{mh-forward-subject-format}. +This variable is a string which includes two escapes (@samp{%s}). The +first @samp{%s} is replaced with the sender of the original message, and +the second one is replaced with the original @samp{Subject:}. The +default value of @samp{"%s: %s"} takes a message with the header: + +@example +@group +To: Bill Wohler <wohler@@newt.com> +Subject: Re: 49er football +From: Greg DesBrisay <gd@@cellnet.com> +@end group +@end example + +and creates a subject header field of: + +@example +Subject: Greg DesBrisay: Re: 49er football +@end example + +@node Customizing Redistributing, Customizing Old Drafts, Customizing Forwarding, Customizing Sending +@subsection Redistributing Your Mail + +@cindex redistributing +@vindex @code{mh-redist-full-contents} +@cindex @code{dist} +@cindex MH commands, @code{dist} +@cindex @code{send} +@cindex MH commands, @code{send} + +The variable @code{mh-redist-full-contents} must be set to non-@code{nil} if +@code{dist} requires the whole letter for redistribution, which is the +case if @code{send} is compiled with the @sc{berk} @footnote{To see which +options your copy of MH was compiled with, use @kbd{M-x mh-version} +(@ref{Miscellaneous}).} option (which many people abhor). If you find +that MH will not allow you to redistribute a message that has been +redistributed before, this variable should be set to @code{nil}. + +@node Customizing Old Drafts, , Customizing Redistributing, Customizing Sending +@subsection Editing Old Drafts and Bounced Messages + +@cindex re-editing drafts +@vindex @code{mh-new-draft-cleaned-headers} + +The header fields specified by @code{mh-new-draft-cleaned-headers} are +removed from an old draft that has been recreated with @kbd{M-e} +(@code{mh-extract-rejected-mail}) or @kbd{M-a} (@code{mh-edit-again}). +If when you edit an old draft with these commands you find that there +are header fields that you don't want included, you can append them to +this variable. For example, + +@vindex @code{mh-new-draft-cleaned-headers}, example + +@lisp +(setq mh-new-draft-cleaned-headers + (concat mh-new-draft-cleaned-headers "\\|^Some-Field:")) +@end lisp + +@cindex regular expressions + +This appends the regular expression @samp{\\|^Some-Field:} to the +variable (@pxref{Regexps, , Syntax of Regular Expressions, emacs, The +GNU Emacs Manual}). The @samp{\\|} means @emph{or}, and the @samp{^} +(caret) matches the beginning of the line. This is done to be very +specific about which fields match. The literal @samp{:} is appended for +the same reason. + +@node Customizing Draft Editing, Customizing Moving Mail, Customizing Sending, Customizing mh-e +@section Editing a Draft + +@cindex editing draft + +There are several variables used during the draft editing phase. +Examples include changing the name of the file that holds your signature +or telling mh-e about new multimedia types. They are: + +@table @code +@item mh-yank-from-start-of-msg +How to yank when region not set (default: @code{t}). + +@item mh-ins-buf-prefix +Indent for yanked messages (default: @samp{"> "}). + +@item mail-citation-hook +Functions to run on yanked messages (default: @code{nil}). + +@item mh-delete-yanked-msg-window +Delete message window on yank (default: @code{nil}). + +@c Need the @* because otherwise TeX fills it wrong and complains +@c about overfull hbox. +@item mh-mime-content-types +List of valid content types (default: @samp{'(("text/plain")@* +("text/richtext") ("multipart/mixed") ("multipart/alternative")@* +("multipart/digest") ("multipart/parallel") ("message/rfc822")@* +("message/partial") ("message/external-body")@* +("application/octet-stream") ("application/postscript")@* +("image/jpeg") ("image/gif") ("audio/basic") ("video/mpeg"))}). + +@item mh-mhn-args +Additional arguments for @code{mhn} (default: @code{nil}). + +@item mh-signature-file-name +File containing signature (default: @samp{"~/.signature"}). + +@item mh-before-send-letter-hook +Functions to run before sending draft (default: @code{nil}). + +@item mh-send-prog +MH program used to send messages (default: @samp{"send"}). +@end table + +@menu +* Customizing Editing Textual:: +* Customizing Editing MIME:: +* Customizing Sending Message:: +@end menu + +@node Customizing Editing Textual, Customizing Editing MIME, Customizing Draft Editing, Customizing Draft Editing +@subsection Editing Textual Messages + +The following two sections include variables that customize the way you +edit a draft. The discussion here applies to editing multimedia +messages as well. + +@menu +* Customizing Inserting Letter:: +* Customizing Signature:: +@end menu + +@node Customizing Inserting Letter, Customizing Signature, Customizing Editing Textual, Customizing Editing Textual +@subsubsection Inserting letter to which you're replying + +@cindex inserting messages +@vindex @code{mh-yank-from-start-of-msg} +@vindex @code{mh-ins-buf-prefix} +@vindex @code{mail-citation-hook} +@vindex @code{mh-ins-buf-prefix} +@vindex @code{mh-delete-yanked-msg-window} + +To control how much of the message to which you are replying is yanked +by @kbd{C-c C-y} (@code{mh-yank-cur-msg}) into your reply, modify +@code{mh-yank-from-start-of-msg}. The default value of @code{t} means +that the entire message is copied. If it is set to @code{'body} (don't +forget the apostrophe), then only the message body is copied. If it is +set to @code{nil}, only the part of the message following point (the +current cursor position in the message's buffer) is copied. In any +case, this variable is ignored if a region is set in the message you are +replying to. The string contained in @code{mh-ins-buf-prefix} is +inserted before each line of a message that is inserted into a draft +with @kbd{C-c C-y} (@code{mh-yank-cur-msg}). I suggest that you not +modify this variable. The default value of @samp{"> "} is the default +string for many mailers and news readers: messages are far easier to +read if several included messages have all been indented by the same +string. The variable @code{mail-citation-hook} is @code{nil} by +default, which means that when a message is inserted into the letter, +each line is prefixed by @code{mh-ins-buf-prefix}. Otherwise, it can be +set to a function that modifies an included +@cindex Emacs, packages, supercite +citation. +@c Footnotes are fragile; hence the redundancy. +@c TeX not inserting a line break; hence the @* +@ifclear html +@footnote{@emph{Supercite} is an example of a full-bodied, full-featured +citation package. It is in Emacs versions 19.15 and later, and can be +found via anonymous @code{ftp} on @samp{archive.cis.ohio-state.edu} in +@* @file{/pub/gnu/emacs/elisp-archive/packages/sc3.1.tar.Z}} +@end ifclear +@ifset html +@footnote{@emph{Supercite} is an example of a full-bodied, +full-featured citation package. It is in Emacs versions 19.15 and +later, and its @sc{url} is @* +@file{<A HREF="ftp://archive.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive/packages/sc3.1.tar.Z">ftp://archive.cis.ohio-state.edu/pub/gnu/emacs/elisp-archive/packages/sc3.1.tar.Z</A>}} +@end ifset +If you like to yank all the text from the message you're replying to in +one go, set @code{mh-delete-yanked-msg-window} to non-@code{nil} to delete +the window containing the original message after yanking it to make more +room on your screen for your reply. + +@node Customizing Signature, , Customizing Inserting Letter, Customizing Editing Textual +@subsubsection Inserting your signature + +@cindex inserting signature +@cindex signature +@vindex @code{mh-signature-file-name} +@cindex @file{.signature} +@cindex files, @file{.signature} + +You can change the name of the file inserted with @kbd{C-c C-s} +(@code{mh-insert-signature}) by changing @code{mh-signature-file-name} +(default: @file{"~/.signature"}). + +@node Customizing Editing MIME, Customizing Sending Message, Customizing Editing Textual, Customizing Draft Editing +@subsection Editing Multimedia Messages + +@cindex MIME +@cindex multimedia mail +@vindex @code{mh-mime-content-types} + +The variable @code{mh-mime-content-types} contains a list of the +currently valid content types. They are listed in the table in +@ref{Customizing Draft Editing}. If you encounter a new content type, +you can add it like this: + +@vindex @code{mh-mime-content-types}, example + +@lisp +(setq mh-mime-content-types (append mh-mime-content-types + '(("@var{new/type}")))) +@end lisp + +Emacs macros can be used to insert enriched text directives like +@samp{<bold>}. The following code will make, for example, @kbd{C-c t +b} insert the @samp{<bold>} directive. + +@lisp +@group +@i{Emacs macros for entering enriched text} + +(defvar enriched-text-types '(("b" . "bold") ("i" . "italic") ("f" . "fixed") + ("s" . "smaller") ("B" . "bigger") + ("u" . "underline") ("c" . "center")) + "Alist of (final-character . directive) choices for add-enriched-text. +Additional types can be found in RFC 1563.") + +(defun add-enriched-text (begin end) + "Add enriched text directives around region. +The directive used comes from the list enriched-text-types and is +specified by the last keystroke of the command. When called from Lisp, +arguments are BEGIN and END@." + (interactive "r") + ;; @r{Set type to the directive indicated by the last keystroke.} + (let ((type (cdr (assoc (char-to-string (logior last-input-char ?@w{`})) + enriched-text-types)))) + (save-restriction ; @r{restores state from narrow-to-region} + (narrow-to-region begin end) ; @r{narrow view to region} + (goto-char (point-min)) ; @r{move to beginning of text} + (insert "<" type ">") ; @r{insert beginning directive} + (goto-char (point-max)) ; @r{move to end of text} + (insert "</" type ">")))) ; @r{insert terminating directive} +@end group +@end lisp + +To use the function @code{add-enriched-text}, first create keybindings +for it (@pxref{Customizing Sending}). Then, set the mark with +@kbd{C-@@} or @kbd{C-SPC}, type in the text to be highlighted, and type +@kbd{C-c t b}. This adds @samp{<bold>} where you set the mark and +adds @samp{</bold>} at the location of your cursor, giving you something +like: @samp{You should be <bold>very</bold>}. You may also be +interested in investigating @code{sgml-mode}. + +@menu +* Customizing Sending MIME:: +@end menu + +@node Customizing Sending MIME, , Customizing Editing MIME, Customizing Editing MIME +@subsubsection Readying multimedia messages for sending + +@vindex @code{mh-mhn-args} + +If you wish to pass additional arguments to @code{mhn} to affect how it +builds your message, use the variable @code{mh-mhn-args}. For example, +you can build a consistency check into the message by setting +@code{mh-mhn-args} to @code{-check}. The recipient of your message can +then run @code{mhn -check} on the message---@code{mhn} will complain if +the message has been corrupted on the way. The @kbd{C-c C-e} +(@code{mh-mhn-edit}) command only consults this variable when given a +prefix argument. + +@node Customizing Sending Message, , Customizing Editing MIME, Customizing Draft Editing +@subsection Sending a Message + +@cindex sending mail +@cindex spell check +@vindex @code{mh-before-send-letter-hook} + +If you want to check your spelling in your message before sending, use +@code{mh-before-send-letter-hook} like this: + +@i{Spell-check message via mh-before-send-letter-hook} + +@vindex @code{mh-before-send-letter-hook}, example + +@lisp +(add-hook 'mh-before-send-letter-hook 'ispell-message) +@end lisp + +@cindex @code{send} +@cindex MH commands, @code{send} +@vindex @code{mh-send-prog} + +In case the MH @code{send} program is installed under a different name, +use @code{mh-send-prog} to tell mh-e the name. + +@node Customizing Moving Mail, Customizing Searching, Customizing Draft Editing, Customizing mh-e +@section Moving Your Mail Around + +@cindex processing mail + +If you change the name of some of the MH programs or have your own +printing programs, the following variables can help you. +They are described in detail in the subsequent sections. + +@table @code +@item mh-inc-prog +Program to incorporate mail (default: @samp{"inc"}). + +@item mh-inc-folder-hook +Functions to run when incorporating mail (default: @code{nil}). + +@item mh-delete-msg-hook +Functions to run when deleting messages (default: @code{nil}). + +@item mh-print-background +Print in foreground or background (default: @code{nil}). + +@item mh-lpr-command-format +Command used to print (default: @samp{"lpr -J '%s'"}). + +@item mh-default-folder-for-message-function +Function to generate a default folder (default: @code{nil}). + +@item mh-auto-folder-collect +Collect folder names in background at startup (default: @code{t}). + +@item mh-recursive-folders +Collect nested folders (default: @code{nil}). + +@item mh-refile-msg-hook +Functions to run when refiling message (default: @code{nil}). + +@item mh-store-default-directory +Default directory for storing files created by @code{uuencode} or @code{shar} +(default: @code{nil}). + +@item mh-sortm-args +Additional arguments for @code{sortm} (default: @code{nil}). + +@item mh-scan-prog +Program to scan messages (default: @samp{"scan"}). + +@item mh-before-quit-hook +Functions to run before quitting (default: @code{nil}). See also +@code{mh-quit-hook}. + +@item mh-quit-hook +Functions to run after quitting (default: @code{nil}). See also +@code{mh-before-quit-hook}. +@end table + +@menu +* Customizing Incorporating:: +* Customizing Deleting:: +* Customizing Organizing:: +* Customizing Printing:: +* Customizing Files and Pipes:: +* Customizing Finishing Up:: +@end menu + +@node Customizing Incorporating, Customizing Deleting, Customizing Moving Mail, Customizing Moving Mail +@subsection Incorporating Your Mail + +@cindex incorporating +@vindex @code{mh-inc-prog} +@cindex @code{inc} +@cindex MH commands, @code{inc} +@vindex @code{mh-progs} +@vindex @code{mh-scan-prog} +@vindex @code{mh-inc-folder-hook} + +The name of the program that incorporates new mail is stored in +@code{mh-inc-prog}; it is @samp{"inc"} by default. This program +generates a one-line summary for each of the new messages. Unless it is +an absolute pathname, the file is assumed to be in the @code{mh-progs} +directory. You may also link a file to @code{inc} that uses a different +format (see @code{mh-profile}(5)). You'll then need to modify several +variables appropriately; see @code{mh-scan-prog} below. You can set the +hook @code{mh-inc-folder-hook}, which is called after new mail is +incorporated by the @kbd{i} (@code{mh-inc-folder}) command. A good use +of this hook is to rescan the whole folder either after running @kbd{M-x +mh-rmail} the first time or when you've changed the message numbers from +outside of mh-e. + +@findex @code{mh-execute-commands} +@findex @code{mh-rescan-folder}, example +@findex @code{mh-show}, example +@vindex @code{mh-inc-folder-hook}, example + +@lisp +@group +@i{Rescan folder after incorporating new mail via mh-inc-folder-hook} + +(defun my-mh-inc-folder-hook () + "Hook to rescan folder after incorporating mail." + (if (buffer-modified-p) ; @r{if outstanding refiles and deletes,} + (mh-execute-commands)) ; @r{carry them out} + (mh-rescan-folder) ; @r{synchronize with +inbox} + (mh-show)) ; @r{show the current message} + +(add-hook 'mh-inc-folder-hook 'my-mh-inc-folder-hook) +@end group +@end lisp + +@node Customizing Deleting, Customizing Organizing, Customizing Incorporating, Customizing Moving Mail +@subsection Deleting Your Mail + +@cindex deleting +@vindex @code{mh-delete-msg-hook} + +The hook @code{mh-delete-msg-hook} is called after you mark a message +for deletion. For example, the current maintainer of mh-e used this +once when he kept statistics on his mail usage. + +@node Customizing Organizing, Customizing Printing, Customizing Deleting, Customizing Moving Mail +@subsection Organizing Your Mail with Folders + +@cindex using folders +@vindex @code{mh-recursive-folders} +@vindex @code{mh-auto-folder-collect} + +By default, operations on folders work only one level at a time. Set +@code{mh-recursive-folders} to non-@code{nil} to operate on all folders. +This mostly means that you'll be able to see all your folders when you +press @key{TAB} when prompted for a folder name. The variable +@code{mh-auto-folder-collect} is normally turned on to generate a list +of folder names in the background as soon as mh-e is loaded. Otherwise, +the list is generated when you need a folder name the first time (as +with @kbd{o} (@code{mh-refile-msg})). If you have a lot of folders and +you have @code{mh-recursive-folders} set, this could take a while, which +is why it's nice to do the folder collection in the background. + +@vindex @code{mh-default-folder-for-message-function} +@findex @code{mh-refile-msg} +@findex @code{mh-to-fcc} +@cindex @file{.emacs} +@cindex files, @file{.emacs} + +The function @code{mh-default-folder-for-message-function} is used by +@kbd{o} (@code{mh-refile-msg}) and @kbd{C-c C-f C-f} (@code{mh-to-fcc}) +to generate a default folder. The generated folder name should be a +string with a @samp{+} before it. For each of my correspondents, I use the +same name for both an alias and a folder. So, I wrote a function that +takes the address in the @samp{From:} header field, finds it in my alias +file, and returns the alias, which is used as a default folder name. +This is the most complicated example given here, and it demonstrates +several features of Emacs Lisp programming. You should be able to drop +this into @file{~/.emacs}, however. If you use this to store messages +in a subfolder of your Mail directory, you can modify the line that +starts @samp{(format +%s...} and insert your subfolder after the folder +symbol @samp{+}. +@c Note for me: if I insert a new version, don't forget to remove the +@c "a/" from the folder name. + +@iftex +@filbreak +@end iftex + +@vindex @code{mh-default-folder-for-message-function}, example +@vindex @code{mh-user-path}, example + +@lisp +@group +@i{Creating useful default folder for refiling via mh-default-folder-for-message-function} + +(defun my-mh-folder-from-address () + "Determine folder name from address. +Takes the address in the From: header field, and returns its corresponding +alias from the user's personal aliases file. Returns @code{nil} if the address +was not found." + (require 'rfc822) ; @r{for the rfc822 functions} + (search-forward-regexp "^From: \\(.*\\)") ; @r{grab header field contents} + (save-excursion ; @r{save state} + (let ((addr (car (rfc822-addresses ; @r{get address} + (buffer-substring (match-beginning 1) + (match-end 1))))) + (buffer (get-buffer-create " *temp*")) ; @r{set local variables} + folder) + (set-buffer buffer) ; @r{jump to temporary buffer} + (unwind-protect ; @r{run kill-buffer when done} + (progn ; @r{function grouping construct} + (insert-file-contents (expand-file-name "aliases" + mh-user-path)) + (goto-char (point-min)) ; @r{grab aliases file and go to start} + (setq folder + ;; @r{Search for the given address, even commented-out} + ;; @r{addresses are found!} + ;; @r{The function search-forward-regexp sets values that are} + ;; @r{later used by match-beginning and match-end.} + (if (search-forward-regexp (format "^;*\\(.*\\):.*%s" + addr) nil t) + ;; @r{NOTE WELL: this is what the return value looks like.} + ;; @r{You can modify the format string to match your own} + ;; @r{Mail hierarchy.} + (format "+%s" (buffer-substring (match-beginning 1) + (match-end 1)))))) + (kill-buffer buffer)) ; @r{get rid of our temporary buffer} + folder))) ; @r{function's return value} + +(setq mh-default-folder-for-message-function 'my-mh-folder-from-address) +@end group +@end lisp + +@vindex @code{mh-refile-msg-hook} + +The hook @code{mh-refile-msg-hook} is called after a message is marked +to be refiled. + +@vindex @code{mh-sortm-args} +@cindex @code{sortm} +@cindex MH commands, @code{sortm} +@findex @code{mh-sort-folder} +@cindex MH profile components, @code{sortm} +@cindex @file{.mh_profile} +@cindex files, @file{.mh_profile} + +The variable @code{mh-sortm-args} holds extra arguments to pass on to +the @code{sortm} command. Note: this variable is only consulted when a +prefix argument is given to @kbd{M-x mh-sort-folder}. It is used to +override any arguments given in a @code{sortm:} entry in your MH profile +(@file{~/.mh_profile}). + +@menu +* Customizing Scan Line Formats:: +@end menu + +@node Customizing Scan Line Formats, , Customizing Organizing, Customizing Organizing +@subsubsection Scan line formatting + +@vindex @code{mh-scan-prog} +@cindex @code{scan} +@cindex MH commands, @code{scan} +@vindex @code{mh-progs} + +The name of the program that generates a listing of one line per message +is held in @code{mh-scan-prog} (default: @samp{"scan"}). Unless this +variable contains an absolute pathname, it is assumed to be in the +@code{mh-progs} directory. You may link another program to @code{scan} +(see @code{mh-profile}(5)) to produce a different type of listing. + +If you change the format of the scan lines you'll need to tell mh-e how +to parse the new format. As you see, quite a lot of variables are +involved to do that. The first variable has to do with pruning out +garbage. + +@table @code +@item mh-valid-scan-line +@vindex @code{mh-valid-scan-line} +@cindex @code{inc} +@cindex MH commands, @code{inc} +@cindex @code{scan} +@cindex MH commands, @code{scan} +This regular expression describes a valid scan line. This is used to +eliminate error messages that are occasionally produced by @code{inc} or +@code{scan} (default: @samp{"^ *[0-9]"}). +@end table + +Next, two variables control how the message numbers are parsed. + +@table @code + +@item mh-msg-number-regexp +@vindex @code{mh-msg-number-regexp} +This regular expression is used to extract the message number from a +scan line. Note that the message number must be placed in quoted +parentheses, (\\(...\\)), as in the default of @w{@samp{"^ +*\\([0-9]+\\)"}}. + +@item mh-msg-search-regexp +@vindex @code{mh-msg-search-regexp} +Given a message number (which is inserted in @samp{%d}), this regular +expression will match the scan line that it represents (default: +@samp{"^[^0-9]*%d[^0-9]"}). +@end table + +Finally, there are a slew of variables that control how mh-e marks up +the scan lines. + +@table @code +@item mh-cmd-note +@vindex @code{mh-cmd-note} +Number of characters to skip over before inserting notation (default: +4). Note how it relates to the following regular expressions. + +@item mh-deleted-msg-regexp +@vindex @code{mh-deleted-msg-regexp} +This regular expression describes deleted messages (default: +@samp{"^....D"}). See also @code{mh-note-deleted}. + +@item mh-refiled-msg-regexp +@vindex @code{mh-refiled-msg-regexp} +This regular expression describes refiled messages (default: +@samp{"^....\\^"}). See also @code{mh-note-refiled}. + +@item mh-cur-scan-msg-regexp +@vindex @code{mh-cur-scan-msg-regexp} +This regular expression matches the current message (default: +@samp{"^....\\+"}). See also @code{mh-note-cur}. + +@item mh-good-msg-regexp +@vindex @code{mh-good-msg-regexp} +This regular expression describes which messages should be shown when +mh-e goes to the next or previous message. Normally, deleted or refiled +messages are skipped over (default: @samp{"^....[^D^]"}). + +@item mh-note-deleted +@vindex @code{mh-note-deleted} +Messages that have been deleted to are marked by this string (default: +@samp{"D"}). See also @code{mh-deleted-msg-regexp}. + +@item mh-note-refiled +@vindex @code{mh-note-refiled} +Messages that have been refiled are marked by this string (default: +@samp{"^"}). See also @code{mh-refiled-msg-regexp}. + +@item mh-note-copied +@vindex @code{mh-note-copied} +Messages that have been copied are marked by this string (default: +@samp{"C"}). + +@item mh-note-cur +@vindex @code{mh-note-cur} +The current message (in MH, not in mh-e) is marked by this string +(default: @samp{"+"}). See also @code{mh-cur-scan-msg-regexp}. + +@item mh-note-repl +@vindex @code{mh-note-repl} +Messages that have been replied to are marked by this string (default: +@samp{"-"}). + +@item mh-note-forw +@vindex @code{mh-note-forw} +Messages that have been forwarded are marked by this string (default: +@samp{"F"}). + +@item mh-note-dist +@vindex @code{mh-note-dist} +Messages that have been redistributed are marked by this string +(default: @samp{"R"}). + +@item mh-note-printed +@vindex @code{mh-note-printed} +Messages that have been printed are marked by this string (default: +@samp{"P"}). + +@item mh-note-seq +@vindex @code{mh-note-seq} +Messages in a sequence are marked by this string (default: @samp{"%"}). +@end table + +@node Customizing Printing, Customizing Files and Pipes, Customizing Organizing, Customizing Moving Mail +@subsection Printing Your Mail + +@cindex printing +@vindex @code{mh-print-background} +@vindex @code{mh-lpr-command-format} +@cindex @code{lpr} +@cindex Unix commands, @code{lpr} + +Normally messages are printed in the foreground. If this is slow on +your system, you may elect to set @code{mh-print-background} to +non-@code{nil} to print in the background. If you do this, do not delete +the message until it is printed or else the output may be truncated. +The variable @code{mh-lpr-command-format} controls how the printing is +actually done. The string can contain one escape, @samp{%s}, which is +filled with the name of the folder and the message number and is useful +for print job names. As an example, the default is @samp{"lpr -J +'%s'"}. + +@node Customizing Files and Pipes, Customizing Finishing Up, Customizing Printing, Customizing Moving Mail +@subsection Files and Pipes + +@cindex using files +@cindex using pipes +@findex @code{mh-store-msg} +@vindex @code{mh-store-default-directory} + +The initial directory for the @code{mh-store-msg} command is held in +@code{mh-store-default-directory}. Since I almost always run +@code{mh-store-msg} on sources, I set it to my personal source directory +like this: + +@vindex @code{mh-store-default-directory}, example + +@lisp +(setq mh-store-default-directory (expand-file-name "~/src/")) +@end lisp + +@findex @code{mh-store-buffer} +@cindex @code{uuencode} +@cindex Unix commands, @code{uuencode} +@cindex @code{shar} +@cindex Unix commands, @code{shar} + +Subsequent incarnations of @code{mh-store-msg} offer the last directory +used as the default. By the way, @code{mh-store-msg} calls the Emacs +Lisp function @code{mh-store-buffer}. I mention this because you can use +it directly if you're editing a buffer that contains a file that has +been run through @code{uuencode} or @code{shar}. For example, you can +extract the contents of the current buffer in your home directory by +typing @kbd{M-x mh-store-buffer @key{RET} ~ @key{RET}}. + +@node Customizing Finishing Up, , Customizing Files and Pipes, Customizing Moving Mail +@subsection Finishing Up + +@cindex quitting +@vindex @code{mh-before-quit-hook} +@vindex @code{mh-quit-hook} +@findex @code{mh-execute-commands} + +The two variables @code{mh-before-quit-hook} and @code{mh-quit-hook} are +called by @kbd{q} (@code{mh-quit}). The former one is called before the +quit occurs, so you might use it to perform any mh-e operations; you +could perform some query and abort the quit or call +@code{mh-execute-commands}, for example. The latter is not run in an +mh-e context, so you might use it to modify the window setup. + +@node Customizing Searching, , Customizing Moving Mail, Customizing mh-e +@section Searching Through Messages +@cindex searching + +@vindex @code{mh-pick-mode-hook} +@vindex @code{mh-partial-folder-mode-line-annotation} + +If you find that you do the same thing over and over when editing the +search template, you may wish to bind some shortcuts to keys. This can +be done with the variable @code{mh-pick-mode-hook}, which is called when +@kbd{M-s} (@code{mh-search-folder}) is run on a new pattern. + +The string +@code{mh-partial-folder-mode-line-annotation} is used to annotate the +mode line when only a portion of the folder is shown. For example, this +will be displayed after running @kbd{M-s} (@code{mh-search-folder}) to +list messages based on some search criteria (see @ref{Searching}). The +default annotation of @samp{"select"} yields a mode line that looks +like: + +@example +--%%-@{+inbox/select@} 2 msgs (2-3) (MH-Folder)--All----------------- +@end example + +@node Odds and Ends, History, Customizing mh-e, Top +@appendix Odds and Ends + +This appendix covers a few topics that don't fit elsewhere. Here I tell +you how to report bugs and how to get on the mh-e mailing list. I also +point out some additional sources of information. + +@menu +* Bug Reports:: +* Mailing List:: +* MH FAQ:: +* Getting mh-e:: +@end menu + +@node Bug Reports, Mailing List, Odds and Ends, Odds and Ends +@appendixsec Bug Reports + +@cindex bugs +@cindex Gildea, Stephen + +The current maintainer of mh-e is Stephen Gildea +<@i{gildea@@lcs.mit.edu}>. Please mail bug reports directly to him, as +well as any praise or suggestions. Please include the output of +@kbd{M-x mh-version} (@pxref{Miscellaneous}) in any bug report you send. + +@node Mailing List, MH FAQ, Bug Reports, Odds and Ends +@appendixsec mh-e Mailing List + +@cindex mailing list + +There is a mailing list, @i{mh-e@@x.org}, for discussion of mh-e and +announcements of new versions. Send a ``subscribe'' message to +@i{mh-e-request@@x.org} to be added. Do not report bugs on this list; +mail them directly to the maintainer (@pxref{Bug Reports}). + +@node MH FAQ, Getting mh-e, Mailing List, Odds and Ends +@appendixsec MH FAQ + +@cindex MH FAQ +@cindex FAQ + +An FAQ appears monthly in the newsgroup @samp{comp.mail.mh}. While very +little is there that deals with mh-e specifically, there is an +incredible wealth of material about MH itself which you will find +useful. The subject of the FAQ is @cite{MH Frequently Asked Questions +(FAQ) with Answers}. + +The FAQ can be also obtained by anonymous @code{ftp} or via the +World Wide Web (WWW)@. It is located at: + +@ifclear html +@example +ftp://rtfm.mit.edu/pub/usenet/news.answers/mail/mh-faq/part1 +http://www.cis.ohio-state.edu/hypertext/faq/usenet/mail/mh-faq/part1/faq.html +@end example +@end ifclear + +@ifset html +@example +<A HREF="ftp://rtfm.mit.edu/pub/usenet/news.answers/mail/mh-faq/part1">ftp://rtfm.mit.edu/pub/usenet/news.answers/mail/mh-faq/part1</A> +<A HREF="http://www.cis.ohio-state.edu/hypertext/faq/usenet/mail/mh-faq/part1/faq.html">http://www.cis.ohio-state.edu/hypertext/faq/usenet/mail/mh-faq/part1/faq.html</A> +@end example +@end ifset + +Otherwise, you can use mail. Send mail to @i{mail-server@@rtfm.mit.edu} +containing the following: + +@example +send usenet/news.answers/mail/mh-faq/part1 +@end example + +@node Getting mh-e, , MH FAQ, Odds and Ends +@appendixsec Getting mh-e + +@cindex obtaining mh-e + +If you're running a pre-4.0 version of mh-e, please consider upgrading. +You can either have your system administrator upgrade your Emacs, or +just the files for mh-e. + +The MH distribution contains a copy of mh-e in @file{miscellany/mh-e}. +Make sure it is at least @w{Version 4.0}. + +The latest version of mh-e can be obtained via anonymous @code{ftp} from +@samp{ftp.x.org}. The file containing mh-e is currently +@ifclear html +@file{/misc/mh-e/mh-e-@value{VERSION}.tar.Z}. +@end ifclear +@ifset html +@file{<A HREF="ftp://ftp.x.org/misc/mh-e/mh-e-@value{VERSION}.tar.Z">/misc/mh-e/mh-e-@value{VERSION}.tar.Z</A>} +@end ifset +I suggest that you +extract the files from @file{mh-e-@value{VERSION}.tar.Z} in the +following fashion: + +@example +@group +% @kbd{cd} # @r{Start in your home directory} +% @kbd{mkdir lib lib/emacs} # @r{Create directory for mh-e} +% @kbd{cd lib/emacs} +% @kbd{zcat @var{path/to/}mh-e-@value{VERSION}.tar.Z | tar xvf -} # @r{Extract files} +@end group +@end example + +@cindex @file{.emacs} +@cindex files, @file{.emacs} + +To use these new files, add the following to @file{~/.emacs}: + +@lisp +(setq load-path (cons (expand-file-name "~/lib/emacs") load-path)) +@end lisp + +@cindex news +@cindex files, @samp{MH-E-NEWS} + +That's it! If you're already running Emacs, please quit that session +and start again to load in the new mh-e. Check that you're running the +new version with the command @kbd{M-x mh-version} after running any mh-e +command. The distribution comes with a file called @file{MH-E-NEWS} so +you can see what's new. + +@node History, Changes to mh-e, Odds and Ends, Top +@appendix History of mh-e + +@cindex history of mh-e + +mh-e was originally written by Brian Reid in 1983 and has changed hands +twice since then. Jim Larus wanted to do something similar for GNU +Emacs, and ended up completely rewriting it that same year. In 1989, +Stephen Gildea picked it up and is now currently improving and +maintaining it. + +@menu +* From Brian Reid:: +* From Jim Larus:: +* From Stephen Gildea:: +@end menu + +@node From Brian Reid, From Jim Larus, History, History +@appendixsec From Brian Reid + +@cindex Reid, Brian + +One day in 1983 I got the flu and had to stay home from work for three +days with nothing to do. I used that time to write MHE@. The +fundamental idea behind MHE was that it was a ``puppeteer'' driving the MH +programs underneath it. MH had a model that the editor was supposed to +run as a subprocess of the mailer, which seemed to me at the time to be +the tail wagging the dog. So I turned it around and made the editor +drive the MH programs. I made sure that the UCI people (who were +maintaining MH at the time) took in my changes and made them stick. + +Today, I still use my own version of MHE because I don't at all like the +way that GNU mh-e works and I've never gotten to be good enough at +hacking Emacs Lisp to make GNU mh-e do what I want. The Gosling-emacs +version of MHE and the GNU Emacs version of mh-e have almost nothing in +common except similar names. They work differently, have different +conceptual models, and have different key bindings. @footnote{After +reading this article, I questioned Brian about his version of MHE, and +received some great ideas for improving mh-e such as a dired-like method +of selecting folders; and removing the prompting when sending mail, +filling in the blanks in the draft buffer instead. I passed them on to +Stephen Gildea, the current maintainer, and he was excited about the +ideas as well. Perhaps one day, mh-e will again resemble MHE, although +none of these ideas are manifest in Version 5.0.} + +Brian Reid, June 1994 + +@node From Jim Larus, From Stephen Gildea, From Brian Reid, History +@appendixsec From Jim Larus + +@cindex Larus, Jim + +Brian Reid, while at CMU or shortly after going to Stanford wrote a mail +reading program called MHE for Gosling Emacs. It had much the same +structure as mh-e (i.e., invoked MH programs), though it was simpler and +the commands were slightly different. Unfortunately, I no longer have a +copy so the differences are lost in the mists of time. + +In '82-83, I was working at BBN and wrote a lot of mlisp code in Gosling +Emacs to make it look more like Tennex Emacs. One of the packages that +I picked up and improved was Reid's mail system. In '83, I went back to +Berkeley. About that time, Stallman's first version of GNU Emacs came +out and people started to move to it from Gosling Emacs (as I recall, +the transition took a year or two). I decided to port Reid's MHE and +used the mlisp to Emacs Lisp translator that came with GNU Emacs. It +did a lousy job and the resulting code didn't work, so I bit the bullet +and rewrote the code by hand (it was a lot smaller and simpler then, so +it took only a day or two). + +Soon after that, mh-e became part of the standard Emacs distribution and +suggestions kept dribbling in for improvements. mh-e soon reached +sufficient functionality to keep me happy, but I kept on improving it +because I was a graduate student with plenty of time on my hands and it +was more fun than my dissertation. In retrospect, the one thing that I +regret is not writing any documentation, which seriously limited the use +and appeal of the package. + +@cindex @code{xmh}, in mh-e history + +In '89, I came to Wisconsin as a professor and decided not to work on +mh-e. It was stable, except for minor bugs, and had enough +functionality, so I let it be for a few years. Stephen Gildea of BBN +began to pester me about the bugs, but I ignored them. In 1990, he went +off to the X Consortium, said good bye, and said that he would now be +using @code{xmh}. A few months later, he came back and said that he +couldn't stand @code{xmh} and could I put a few more bug fixes into +mh-e. At that point, I had no interest in fixing mh-e, so I gave the +responsibility of maintenance to him and he has done a fine job since +then. + +Jim Larus, June 1994 + +@node From Stephen Gildea, , From Jim Larus, History +@appendixsec From Stephen Gildea + +@cindex Gildea, Stephen + +In 1987 I went to work for Bolt Beranek and Newman, as Jim had before +me. In my previous job, I had been using RMAIL, but as my folders tend +to run large, I was frustrated with the speed of RMAIL@. However, I +stuck with it because I wanted the GNU Emacs interface. I am very +familiar and comfortable with the Emacs interface (with just a few +modifications of my own) and dislike having to use applications with +embedded editors; they never live up to Emacs. + +MH is the mail reader of choice at BBN, so I converted to it. Since I +didn't want to give up using an Emacs interface, I started using mh-e. +As is my wont, I started hacking on it almost immediately. I first used +version 3.4m. One of the first features I added was to treat the folder +buffer as a file-visiting buffer: you could lock it, save it, and be +warned of unsaved changes when killing it. I also worked to bring its +functionality a little closer to RMAIL@. Jim Larus was very cooperative +about merging in my changes, and my efforts first appeared in version +3.6, distributed with Emacs 18.52 in 1988. Next I decided mh-e was too +slow and optimized it a lot. Version, 3.7, distributed with Emacs 18.56 +in 1990, was noticeably faster. + +When I moved to the X Consortium I became the first person there to not +use xmh. (There is now one other engineer there using mh-e.) About +this point I took over maintenance of mh-e from Jim and was finally able +to add some features Jim hadn't accepted, such as the backward searching +undo. My first release was 3.8 (Emacs 18.58) in 1992. + +Now, in 1994, we see a flurry of releases, with both 4.0 and 5.0. +Version 4.0 added many new features, including background folder +collection and support for composing @sc{mime} messages. (Reading +@sc{mime} messages remains to be done, alas.) While writing this book, +Bill Wohler gave mh-e its closest examination ever, uncovering bugs and +inconsistencies that required a new major version to fix, and so version +5 was released. + +Stephen Gildea, June 1994 + +@node Changes to mh-e, Copying, History, Top +@appendix Changes to mh-e + +@cindex @code{mh-e}: comparison between versions + +mh-e had a fairly major facelift between @w{Versions 3} and 4. The +differences between @w{Versions 4} and 5 from the user's viewpoint are +relatively minor. The prompting order for the folder and message number +in a couple of functions had been switched inadvertently in @w{Version +4}. @w{Version 5} switches the order back. The @file{+inbox} folder is +no longer hard-coded, but rather uses the @samp{Inbox} MH Profile entry. +See the file @file{etc/MH-E-NEWS} in the Emacs distribution for more +details on the changes. + +This section documents the changes between @w{Version 3} and newer +versions so that you'll know which commands to use (or which commands +you won't have) in case you're stuck with an old version. + +The following tables summarize the changes to buffer names, commands +and variables. + +@unnumberedsec Buffer Mode Names + +@example +@group +@b{Version 3} @b{Version 4} + +mh-e folder MH-Folder +mh-e scan MH-Folder +mh-e show MH-Folder Show +Fundamental MH-Show +mh-e letter MH-Letter +mh-e letter MH-Pick +@end group +@end example + +@page + +@unnumberedsec Commands + +@example +@group + @b{Version 3} @b{Version 4} + +@b{Function} @b{Command} @b{Command} @b{Function} + +mh-first-msg < M-< mh-first-msg +- - M-> mh-last-msg +mh-show . RET mh-show +- - , mh-header-display +mh-reply a r mh-reply +mh-redistribute r M-d mh-redistribute +mh-unshar-msg - M-n mh-store-msg +mh-write-msg-to-file M-o C-o mh-write-msg-to-file +mh-delete-msg-from-seq C-u M-% M-# mh-delete-seq +- - M-q mh-list-sequences +mh-quit b q mh-quit +- - C-C C-f C-r mh-to-field (@samp{From:}) +- - C-C C-f C-d mh-to-field (@samp{Dcc:}) +@end group +@end example + +@unnumberedsec Variables + +@example +@group + @b{Version 3} @b{Version 4} + +@b{Variable} @b{Value} @b{Value} @b{Variable} + +mh-show-buffer- "@{%%b@} %s/%d" "@{show-%s@} %d" mh-show-buffer- +mode-line-buffer-id mode-line-buffer-id +mh-unshar-default- "" nil mh-store-default- +directory directory +@end group +@end example + + +@unnumberedsec New Variables + +@example +@group +mail-citation-hook mh-new-draft-cleaned-headers +mail-header-separator mh-pick-mode-hook +mh-auto-folder-collect mh-refile-msg-hook +mh-comp-formfile mh-scan-prog +mh-repl-formfile mh-send-prog +mh-delete-msg-hook mh-show-hook +mh-forward-subject-format mh-show-mode-hook +mh-inc-prog mh-signature-file-name +mh-mime-content-types mh-sortm-args +mh-default-folder-for-message-function mh-repl-formfile +mh-mhn-args +@end group +@end example + +@node Copying, Command Index, Changes to mh-e, Top +@appendix GNU GENERAL PUBLIC LICENSE +@center Version 2, June 1991 + +@display +Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc. +59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@appendixsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU 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. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), 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 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 show them these terms so they know 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. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + +@iftex +@appendixsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate 0 +@item +This License 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 derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term ``modification''.) Each licensee is addressed as ``you''. + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + +@item +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 License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +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. + +@item +You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +You must cause the modified files to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause any work that you distribute or publish, that in +whole or in part contains or is derived from the Program or any +part thereof, to be licensed as a whole at no charge to all third +parties under the terms of this License. + +@item +If the modified program normally reads commands interactively +when run, you must cause it, when started running for such +interactive use in the most ordinary 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 +License. (Exception: if the Program itself is interactive but +does not normally print such an announcement, your work based on +the Program is not required to print an announcement.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + +@enumerate a +@item +Accompany it with the complete corresponding machine-readable +source code, which must be distributed under the terms of Sections +1 and 2 above on a medium customarily used for software interchange; or, + +@item +Accompany it with a written offer, valid for at least three +years, to give any third party, for a charge no more than your +cost of physically performing source distribution, a complete +machine-readable copy of the corresponding source code, to be +distributed under the terms of Sections 1 and 2 above on a medium +customarily used for software interchange; or, + +@item +Accompany it with the information you received as to the offer +to distribute corresponding source code. (This alternative is +allowed only for noncommercial distribution and only if you +received the program in object code or executable form with such +an offer, in accord with Subsection b above.) +@end enumerate + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing 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 for copying, distributing or modifying +the Program or works based on it. + +@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. +You are not responsible for enforcing compliance by third parties to +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + +@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 this 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 +this 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 +@appendixsec 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 the public, 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 an 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 2 +of the License, 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., +59 Temple Place, Suite 330, Boston, MA 02111-1307, 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 @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, the +commands you use may be called something other than @samp{show w} and +@samp{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 is a sample; alter the names: + +@smallexample +@group +Yoyodyne, Inc., hereby disclaims all copyright +interest in the program `Gnomovision' +(which makes passes at compilers) written +by James Hacker. + +@var{signature of Ty Coon}, 1 April 1989 +Ty Coon, President of Vice +@end group +@end smallexample + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. + +@node Command Index, Variable Index, Copying, Top +@unnumbered Command Index + +@printindex fn + +@node Variable Index, Concept Index, Command Index, Top +@unnumbered Variable Index + +@printindex vr + +@node Concept Index, , Variable Index, Top +@unnumbered Concept Index + +@printindex cp + +@contents +@bye + +@c XXX In the sections on customizing mh-e, you can add cross-references +@c to the Emacs manual and the Emacs Lisp manual wherever they are +@c useful. @pxref{node, , section, emacs, The GNU Emacs Manual} diff --git a/man/mini.texi b/man/mini.texi new file mode 100644 index 00000000000..279cd98f60b --- /dev/null +++ b/man/mini.texi @@ -0,0 +1,534 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Minibuffer, M-x, Basic, Top +@chapter The Minibuffer +@cindex minibuffer + + The @dfn{minibuffer} is the facility used by Emacs commands to read +arguments more complicated than a single number. Minibuffer arguments +can be file names, buffer names, Lisp function names, Emacs command +names, Lisp expressions, and many other things, depending on the command +reading the argument. You can use the usual Emacs editing commands in +the minibuffer to edit the argument text. + +@cindex prompt + When the minibuffer is in use, it appears in the echo area, and the +terminal's cursor moves there. The beginning of the minibuffer line +displays a @dfn{prompt} which says what kind of input you should supply and +how it will be used. Often this prompt is derived from the name of the +command that the argument is for. The prompt normally ends with a colon. + +@cindex default argument + Sometimes a @dfn{default argument} appears in parentheses after the +colon; it too is part of the prompt. The default will be used as the +argument value if you enter an empty argument (for example, just type +@key{RET}). For example, commands that read buffer names always show a +default, which is the name of the buffer that will be used if you type +just @key{RET}. + + The simplest way to enter a minibuffer argument is to type the text +you want, terminated by @key{RET} which exits the minibuffer. You can +cancel the command that wants the argument, and get out of the +minibuffer, by typing @kbd{C-g}. + + Since the minibuffer uses the screen space of the echo area, it can +conflict with other ways Emacs customarily uses the echo area. Here is how +Emacs handles such conflicts: + +@itemize @bullet +@item +If a command gets an error while you are in the minibuffer, this does +not cancel the minibuffer. However, the echo area is needed for the +error message and therefore the minibuffer itself is hidden for a +while. It comes back after a few seconds, or as soon as you type +anything. + +@item +If in the minibuffer you use a command whose purpose is to print a +message in the echo area, such as @kbd{C-x =}, the message is printed +normally, and the minibuffer is hidden for a while. It comes back +after a few seconds, or as soon as you type anything. + +@item +Echoing of keystrokes does not take place while the minibuffer is in +use. +@end itemize + +@menu +* File: Minibuffer File. Entering file names with the minibuffer. +* Edit: Minibuffer Edit. How to edit in the minibuffer. +* Completion:: An abbreviation facility for minibuffer input. +* Minibuffer History:: Reusing recent minibuffer arguments. +* Repetition:: Re-executing commands that used the minibuffer. +@end menu + +@node Minibuffer File +@section Minibuffers for File Names + + Sometimes the minibuffer starts out with text in it. For example, when +you are supposed to give a file name, the minibuffer starts out containing +the @dfn{default directory}, which ends with a slash. This is to inform +you which directory the file will be found in if you do not specify a +directory. + +@c Separate paragraph to clean up ugly pagebreak--rms +@need 1500 + For example, the minibuffer might start out with these contents: + +@example +Find File: /u2/emacs/src/ +@end example + +@noindent +where @samp{Find File:@: } is the prompt. Typing @kbd{buffer.c} +specifies the file @file{/u2/emacs/src/buffer.c}. To find files in +nearby directories, use @kbd{..}; thus, if you type +@kbd{../lisp/simple.el}, you will get the file named +@file{/u2/emacs/lisp/simple.el}. Alternatively, you can kill with +@kbd{M-@key{DEL}} the directory names you don't want (@pxref{Words}). + + If you don't want any of the default, you can kill it with @kbd{C-a +C-k}. But you don't need to kill the default; you can simply ignore it. +Insert an absolute file name, one starting with a slash or a tilde, +after the default directory. For example, to specify the file +@file{/etc/termcap}, just insert that name, giving these minibuffer +contents: + +@example +Find File: /u2/emacs/src//etc/termcap +@end example + +@noindent +@cindex // in file name +@cindex double slash in file name +@cindex slashes repeated in file name +GNU Emacs gives a special meaning to a double slash (which is not +normally a useful thing to write): it means, ``ignore everything before +the second slash in the pair.'' Thus, @samp{/u2/emacs/src/} is ignored +in the example above, and you get the file @file{/etc/termcap}. + + If you set @code{insert-default-directory} to @code{nil}, the default +directory is not inserted in the minibuffer. This way, the minibuffer +starts out empty. But the name you type, if relative, is still +interpreted with respect to the same default directory. + +@node Minibuffer Edit +@section Editing in the Minibuffer + + The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual +Emacs commands are available for editing the text of an argument you are +entering. + + Since @key{RET} in the minibuffer is defined to exit the minibuffer, +you can't use it to insert a newline in the minibuffer. To do that, +type @kbd{C-o} or @kbd{C-q C-j}. (Recall that a newline is really the +character control-J.) + + The minibuffer has its own window which always has space on the screen +but acts as if it were not there when the minibuffer is not in use. When +the minibuffer is in use, its window is just like the others; you can +switch to another window with @kbd{C-x o}, edit text in other windows and +perhaps even visit more files, before returning to the minibuffer to submit +the argument. You can kill text in another window, return to the +minibuffer window, and then yank the text to use it in the argument. +@xref{Windows}. + +@findex resize-minibuffer-mode +@cindex Resize-Minibuffer mode +@cindex mode, Resize-Minibuffer +@cindex height of minibuffer +@cindex size of minibuffer +@cindex growing minibuffer + There are some restrictions on the use of the minibuffer window, +however. You cannot switch buffers in it---the minibuffer and its +window are permanently attached. Also, you cannot split or kill the +minibuffer window. But you can make it taller in the normal fashion +with @kbd{C-x ^}. If you enable Resize-Minibuffer mode, then the +minibuffer window expands vertically as necessary to hold the text that +you put in the minibuffer. Use @kbd{M-x resize-minibuffer-mode} to +enable or disable this minor mode (@pxref{Minor Modes}). + +@vindex minibuffer-scroll-overlap + Scrolling works specially in the minibuffer window. When the +minibuffer is just one line high, and it contains a long line of text +that won't fit on the screen, scrolling automatically maintains an +overlap of a certain number of characters from one continuation line to +the next. The variable @code{minibuffer-scroll-overlap} specifies how +many characters of overlap; the default is 20. + + If while in the minibuffer you issue a command that displays help text +of any sort in another window, you can use the @kbd{C-M-v} command while +in the minibuffer to scroll the help text. This lasts until you exit +the minibuffer. This feature is especially useful if a completing +minibuffer gives you a list of possible completions. @xref{Other Window}. + +@vindex enable-recursive-minibuffers + Emacs normally disallows most commands that use the minibuffer while +the minibuffer is active. This rule is to prevent recursive minibuffers +from confusing novice users. If you want to be able to use such +commands in the minibuffer, set the variable +@code{enable-recursive-minibuffers} to a non-@code{nil} value. + +@node Completion +@section Completion +@cindex completion + + For certain kinds of arguments, you can use @dfn{completion} to enter +the argument value. Completion means that you type part of the +argument, then Emacs visibly fills in the rest, or as much as +can be determined from the part you have typed. + + When completion is available, certain keys---@key{TAB}, @key{RET}, and +@key{SPC}---are rebound to complete the text present in the minibuffer +into a longer string that it stands for, by matching it against a set of +@dfn{completion alternatives} provided by the command reading the +argument. @kbd{?} is defined to display a list of possible completions +of what you have inserted. + + For example, when @kbd{M-x} uses the minibuffer to read the name of a +command, it provides a list of all available Emacs command names to +complete against. The completion keys match the text in the minibuffer +against all the command names, find any additional name characters +implied by the ones already present in the minibuffer, and add those +characters to the ones you have given. This is what makes it possible +to type @kbd{M-x ins @key{SPC} b @key{RET}} instead of @kbd{M-x +insert-buffer @key{RET}} (for example). + + Case is normally significant in completion, because it is significant +in most of the names that you can complete (buffer names, file names and +command names). Thus, @samp{fo} does not complete to @samp{Foo}. +Completion does ignore case distinctions for certain arguments in which +case does not matter. + +@menu +* Example: Completion Example. +* Commands: Completion Commands. +* Strict Completion:: +* Options: Completion Options. +@end menu + +@node Completion Example +@subsection Completion Example + +@kindex TAB @r{(completion)} +@findex minibuffer-complete + A concrete example may help here. If you type @kbd{M-x au @key{TAB}}, +the @key{TAB} looks for alternatives (in this case, command names) that +start with @samp{au}. There are several, including +@code{auto-fill-mode} and @code{auto-save-mode}---but they are all the +same as far as @code{auto-}, so the @samp{au} in the minibuffer changes +to @samp{auto-}.@refill + + If you type @key{TAB} again immediately, there are multiple +possibilities for the very next character---it could be any of +@samp{cfilrs}---so no more characters are added; instead, @key{TAB} +displays a list of all possible completions in another window. + + If you go on to type @kbd{f @key{TAB}}, this @key{TAB} sees +@samp{auto-f}. The only command name starting this way is +@code{auto-fill-mode}, so completion fills in the rest of that. You now +have @samp{auto-fill-mode} in the minibuffer after typing just @kbd{au +@key{TAB} f @key{TAB}}. Note that @key{TAB} has this effect because in +the minibuffer it is bound to the command @code{minibuffer-complete} +when completion is available. + +@node Completion Commands +@subsection Completion Commands + + Here is a list of the completion commands defined in the minibuffer +when completion is available. + +@table @kbd +@item @key{TAB} +Complete the text in the minibuffer as much as possible +(@code{minibuffer-complete}). +@item @key{SPC} +Complete the minibuffer text, but don't go beyond one word +(@code{minibuffer-complete-word}). +@item @key{RET} +Submit the text in the minibuffer as the argument, possibly completing +first as described below (@code{minibuffer-complete-and-exit}). +@item ? +Print a list of all possible completions of the text in the minibuffer +(@code{minibuffer-list-completions}). +@end table + +@kindex SPC +@findex minibuffer-complete-word + @key{SPC} completes much like @key{TAB}, but never goes beyond the +next hyphen or space. If you have @samp{auto-f} in the minibuffer and +type @key{SPC}, it finds that the completion is @samp{auto-fill-mode}, +but it stops completing after @samp{fill-}. This gives +@samp{auto-fill-}. Another @key{SPC} at this point completes all the +way to @samp{auto-fill-mode}. @key{SPC} in the minibuffer when +completion is available runs the command +@code{minibuffer-complete-word}. + + Here are some commands you can use to choose a completion from a +window that displays a list of completions: + +@table @kbd +@findex mouse-choose-completion +@item Mouse-2 +Clicking mouse button 2 on a completion in the list of possible +completions chooses that completion (@code{mouse-choose-completion}). +You normally use this command while point is in the minibuffer; but you +must click in the list of completions, not in the minibuffer itself. + +@findex switch-to-completions +@item @key{PRIOR} +@itemx M-v +Typing @key{PRIOR} or @key{PAGE-UP}, or @kbd{M-v}, while in the +minibuffer, selects the window showing the completion list buffer +(@code{switch-to-completions}). This paves the way for using the +commands below. (Selecting that window in the usual ways has the same +effect, but this way is more convenient.) + +@findex choose-completion +@item @key{RET} +Typing @key{RET} @emph{in the completion list buffer} chooses the +completion that point is in or next to (@code{choose-completion}). To +use this command, you must first switch windows to the window that shows +the list of completions. + +@findex next-completion +@item @key{RIGHT} +Typing the right-arrow key @key{RIGHT} @emph{in the completion list +buffer} moves point to the following completion (@code{next-completion}). + +@findex previous-completion +@item @key{LEFT} +Typing the left-arrow key @key{LEFT} @emph{in the completion list +buffer} moves point toward the beginning of the buffer, to the previous +completion (@code{previous-completion}). +@end table + +@node Strict Completion +@subsection Strict Completion + + There are three different ways that @key{RET} can work in completing +minibuffers, depending on how the argument will be used. + +@itemize @bullet +@item +@dfn{Strict} completion is used when it is meaningless to give any +argument except one of the known alternatives. For example, when +@kbd{C-x k} reads the name of a buffer to kill, it is meaningless to +give anything but the name of an existing buffer. In strict +completion, @key{RET} refuses to exit if the text in the minibuffer +does not complete to an exact match. + +@item +@dfn{Cautious} completion is similar to strict completion, except that +@key{RET} exits only if the text was an exact match already, not +needing completion. If the text is not an exact match, @key{RET} does +not exit, but it does complete the text. If it completes to an exact +match, a second @key{RET} will exit. + +Cautious completion is used for reading file names for files that must +already exist. + +@item +@dfn{Permissive} completion is used when any string whatever is +meaningful, and the list of completion alternatives is just a guide. +For example, when @kbd{C-x C-f} reads the name of a file to visit, any +file name is allowed, in case you want to create a file. In +permissive completion, @key{RET} takes the text in the minibuffer +exactly as given, without completing it. +@end itemize + + The completion commands display a list of all possible completions in +a window whenever there is more than one possibility for the very next +character. Also, typing @kbd{?} explicitly requests such a list. If +the list of completions is long, you can scroll it with @kbd{C-M-v} +(@pxref{Other Window}). + +@node Completion Options +@subsection Completion Options + +@vindex completion-ignored-extensions + When completion is done on file names, certain file names are usually +ignored. The variable @code{completion-ignored-extensions} contains a +list of strings; a file whose name ends in any of those strings is +ignored as a possible completion. The standard value of this variable +has several elements including @code{".o"}, @code{".elc"}, @code{".dvi"} +and @code{"~"}. The effect is that, for example, @samp{foo} can +complete to @samp{foo.c} even though @samp{foo.o} exists as well. +However, if @emph{all} the possible completions end in ``ignored'' +strings, then they are not ignored. Ignored extensions do not apply to +lists of completions---those always mention all possible completions. + +@vindex completion-auto-help + Normally, a completion command that finds the next character is undetermined +automatically displays a list of all possible completions. If the variable +@code{completion-auto-help} is set to @code{nil}, this does not happen, +and you must type @kbd{?} to display the possible completions. + +@pindex complete + The @code{complete} library implements a more powerful kind of +completion that can complete multiple words at a time. For example, it +can complete the command name abbreviation @code{p-b} into +@code{print-buffer}, because no other command starts with two words +whose initials are @samp{p} and @samp{b}. To use this library, put +@code{(load "complete")} in your @file{~/.emacs} file (@pxref{Init +File}). + +@cindex Icomplete mode + Icomplete mode presents a constantly-updated display that tells you +what completions are available for the text you've entered so far. The +command to enable or disable this minor mode is @kbd{M-x +icomplete-mode}. + +@node Minibuffer History +@section Minibuffer History +@cindex minibuffer history +@cindex history of minibuffer input + + Every argument that you enter with the minibuffer is saved on a +@dfn{minibuffer history list} so that you can use it again later in +another argument. Special commands load the text of an earlier argument +in the minibuffer. They discard the old minibuffer contents, so you can +think of them as moving through the history of previous arguments. + +@table @kbd +@item @key{UP} +@itemx M-p +Move to the next earlier argument string saved in the minibuffer history +(@code{previous-history-element}). +@item @key{DOWN} +@itemx M-n +Move to the next later argument string saved in the minibuffer history +(@code{next-history-element}). +@item M-r @var{regexp} @key{RET} +Move to an earlier saved argument in the minibuffer history that has a +match for @var{regexp} (@code{previous-matching-history-element}). +@item M-s @var{regexp} @key{RET} +Move to a later saved argument in the minibuffer history that has a +match for @var{regexp} (@code{next-matching-history-element}). +@end table + +@kindex M-p @r{(minibuffer history)} +@kindex M-n @r{(minibuffer history)} +@findex next-history-element +@findex previous-history-element + The simplest way to reuse the saved arguments in the history list is +to move through the history list one element at a time. While in the +minibuffer, use @kbd{M-p} or up-arrow (@code{previous-history-element}) +to ``move to'' the next earlier minibuffer input, and use @kbd{M-n} or +down-arrow (@code{next-history-element}) to ``move to'' the next later +input. + + The previous input that you fetch from the history entirely replaces +the contents of the minibuffer. To use it as the argument, exit the +minibuffer as usual with @key{RET}. You can also edit the text before +you reuse it; this does not change the history element that you +``moved'' to, but your new argument does go at the end of the history +list in its own right. + + For many minibuffer arguments there is a ``default'' value. In some +cases, the minibuffer history commands know the default value. Then you +can insert the default value into the minibuffer as text by using +@kbd{M-n} to move ``into the future'' in the history. Eventually we +hope to make this feature available whenever the minibuffer has a +default value. + +@findex previous-matching-history-element +@findex next-matching-history-element +@kindex M-r @r{(minibuffer history)} +@kindex M-s @r{(minibuffer history)} + There are also commands to search forward or backward through the +history; they search for history elements that match a regular +expression that you specify with the minibuffer. @kbd{M-r} +(@code{previous-matching-history-element}) searches older elements in +the history, while @kbd{M-s} (@code{next-matching-history-element}) +searches newer elements. By special dispensation, these commands can +use the minibuffer to read their arguments even though you are already +in the minibuffer when you issue them. As with incremental searching, +an uppercase letter in the regular expression makes the search +case-sensitive (@pxref{Search Case}). + +@ignore + We may change the precise way these commands read their arguments. +Perhaps they will search for a match for the string given so far in the +minibuffer; perhaps they will search for a literal match rather than a +regular expression match; perhaps they will only accept matches at the +beginning of a history element; perhaps they will read the string to +search for incrementally like @kbd{C-s}. To find out what interface is +actually available, type @kbd{C-h f previous-matching-history-element}. +@end ignore + + All uses of the minibuffer record your input on a history list, but +there are separate history lists for different kinds of arguments. For +example, there is a list for file names, used by all the commands that +read file names. (As a special feature, this history list records +the absolute file name, no more and no less, even if that is not how +you entered the file name.) + + There are several other very specific history lists, including one for +command names read by @kbd{M-x}, one for buffer names, one for arguments +of commands like @code{query-replace}, and one for compilation commands +read by @code{compile}. Finally, there is one ``miscellaneous'' history +list that most minibuffer arguments use. + +@vindex history-length + The variable @code{history-length} specifies the maximum length of a +minibuffer history list; once a list gets that long, the oldest element +is deleted each time an element is added. If the value of +@code{history-length} is @code{t}, though, there is no maximum length +and elements are never deleted. + +@node Repetition +@section Repeating Minibuffer Commands +@cindex command history +@cindex history of commands + + Every command that uses the minibuffer at least once is recorded on a +special history list, together with the values of its arguments, so that +you can repeat the entire command. In particular, every use of +@kbd{M-x} is recorded there, since @kbd{M-x} uses the minibuffer to read +the command name. + +@findex list-command-history +@c widecommands +@table @kbd +@item C-x @key{ESC} @key{ESC} +Re-execute a recent minibuffer command (@code{repeat-complex-command}). +@item M-x list-command-history +Display the entire command history, showing all the commands +@kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first. +@end table + +@kindex C-x ESC ESC +@findex repeat-complex-command + @kbd{C-x @key{ESC} @key{ESC}} is used to re-execute a recent +minibuffer-using command. With no argument, it repeats the last such +command. A numeric argument specifies which command to repeat; one +means the last one, and larger numbers specify earlier ones. + + @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command +into a Lisp expression and then entering a minibuffer initialized with +the text for that expression. If you type just @key{RET}, the command +is repeated as before. You can also change the command by editing the +Lisp expression. Whatever expression you finally submit is what will be +executed. The repeated command is added to the front of the command +history unless it is identical to the most recently executed command +already there. + + Even if you don't understand Lisp syntax, it will probably be obvious +which command is displayed for repetition. If you do not change the +text, it will repeat exactly as before. + + Once inside the minibuffer for @kbd{C-x @key{ESC} @key{ESC}}, you can +use the minibuffer history commands (@kbd{M-p}, @kbd{M-n}, @kbd{M-r}, +@kbd{M-s}; @pxref{Minibuffer History}) to move through the history list +of saved entire commands. After finding the desired previous command, +you can edit its expression as usual and then resubmit it by typing +@key{RET} as usual. + +@vindex command-history + The list of previous minibuffer-using commands is stored as a Lisp +list in the variable @code{command-history}. Each element is a Lisp +expression which describes one command and its arguments. Lisp programs +can re-execute a command by calling @code{eval} with the +@code{command-history} element. diff --git a/man/misc.texi b/man/misc.texi new file mode 100644 index 00000000000..996317adab9 --- /dev/null +++ b/man/misc.texi @@ -0,0 +1,1834 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@iftex +@chapter Miscellaneous Commands + + This chapter contains several brief topics that do not fit anywhere +else: reading netnews, running shell commands and shell subprocesses, +using a single shared Emacs for utilities that expect to run an editor +as a subprocess, printing hardcopy, sorting text, narrowing display to +part of the buffer, editing double-column files and binary files, saving +an Emacs session for later resumption, emulating other editors, and +various diversions and amusements. + +@end iftex +@node Gnus, Shell, Calendar/Diary, Top +@section Gnus +@cindex Gnus +@cindex reading netnews + +Gnus is an Emacs package primarily designed for reading and posting +Usenet news. It can also be used to read and respond to messages from a +number of other sources---mail, remote directories, digests, and so on. + +Here we introduce Gnus and describe several basic features. +@ifinfo +For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}. +@end ifinfo +@iftex +For full details on Gnus, type @kbd{M-x info} and then select the Gnus +manual. +@end iftex + +@findex gnus +To start Gnus, type @kbd{M-x gnus @key{RET}}. + +@menu +* Buffers of Gnus:: The group, summary, and article buffers. +* Gnus Startup:: What you should know about starting Gnus. +* Summary of Gnus:: A short description of the basic Gnus commands. +@end menu + +@node Buffers of Gnus +@subsection Gnus Buffers + +As opposed to most normal Emacs packages, Gnus uses a number of +different buffers to display information and to receive commands. The +three buffers users spend most of their time in are the @dfn{group +buffer}, the @dfn{summary buffer} and the @dfn{article buffer}. + +The @dfn{group buffer} contains a list of groups. This is the first +buffer Gnus displays when it starts up. It normally displays only the +groups to which you subscribe and that contain unread articles. Use +this buffer to select a specific group. + +The @dfn{summary buffer} lists one line for each article in a single +group. By default, the author, the subject and the line number are +displayed for each article, but this is customizable, like most aspects +of Gnus display. The summary buffer is created when you select a group +in the group buffer, and is killed when you exit the group. Use this +buffer to select an article. + +The @dfn{article buffer} displays the article. In normal Gnus usage, +you don't select this buffer---all useful article-oriented commands work +in the summary buffer. But you can select the article buffer, and +execute all Gnus commands from that buffer, if you want to. + +@node Gnus Startup +@subsection When Gnus Starts Up + +At startup, Gnus reads your @file{.newsrc} news initialization file +and attempts to communicate with the local news server, which is a +repository of news articles. The news server need not be the same +computer you are logged in on. + +If you start Gnus and connect to the server, but do not see any +newsgroups listed in the group buffer, type @kbd{L} or @kbd{A k} to get +a listing of all the groups. Then type @kbd{u} to toggle +subscription to groups. + +The first time you start Gnus, Gnus subscribes you to a few selected +groups. All other groups start out as @dfn{killed groups} for you; you +can list them with @kbd{A k}. All new groups that subsequently come to +exist at the news server become @dfn{zombie groups} for you; type @kbd{A +z} to list them. You can subscribe to a group shown in these lists +using the @kbd{u} command. + +When you quit Gnus with @kbd{q}, it automatically records in your +@file{.newsrc} and @file{.newsrc.eld} initialization files the +subscribed or unsubscribed status of all groups. You should normally +not edit these files manually, but you may if you know how. + +@node Summary of Gnus +@subsection Summary of Gnus Commands + +Reading news is a two step process: + +@enumerate +@item +Choose a group in the group buffer. + +@item +Select articles from the summary buffer. Each article selected is +displayed in the article buffer in a large window, below the summary +buffer in its small window. +@end enumerate + + Each Gnus buffer has its own special commands; however, the meanings +of any given key in the various Gnus buffers are usually analogous, even +if not identical. Here are commands for the group and summary buffers: + +@table @kbd +@kindex q @r{(Gnus Group mode)} +@findex gnus-group-exit +@item q +In the group buffer, update your @file{.newsrc} initialization file +and quit Gnus. + +In the summary buffer, exit the current group and return to the +group buffer. Thus, typing @kbd{q} twice quits Gnus. + +@kindex L @r{(Gnus Group mode)} +@findex gnus-group-list-all-groups +@item L +In the group buffer, list all the groups available on your news +server (except those you have killed). This may be a long list! + +@kindex l @r{(Gnus Group mode)} +@findex gnus-group-list-groups +@item l +In the group buffer, list only the groups to which you subscribe and +which contain unread articles. + +@kindex u @r{(Gnus Group mode)} +@findex gnus-group-unsubscribe-current-group +@cindex subscribe groups +@cindex unsubscribe groups +@item u +In the group buffer, unsubscribe from (or subscribe to) the group listed +in the line that point is on. When you quit Gnus by typing @kbd{q}, +Gnus lists in your @file{.newsrc} file which groups you have subscribed +to. The next time you start Gnus, you won't see this group, +because Gnus normally displays only subscribed-to groups. + +@kindex C-k @r{(Gnus)} +@findex gnus-group-kill-group +@item C-k +In the group buffer, ``kill'' the current line's group---don't +even list it in @file{.newsrc} from now on. This affects future +Gnus sessions as well as the present session. + +When you quit Gnus by typing @kbd{q}, Gnus writes information +in the file @file{.newsrc} describing all newsgroups except those you +have ``killed.'' + +@kindex SPC @r{(Gnus)} +@findex gnus-group-read-group +@item @key{SPC} +In the group buffer, select the group on the line under the cursor +and display the first unread article in that group. + +@need 1000 +In the summary buffer, + +@itemize @bullet +@item +Select the article on the line under the cursor if none is selected. + +@item +Scroll the text of the selected article (if there is one). + +@item +Select the next unread article if at the end of the current article. +@end itemize + +Thus, you can move through all the articles by repeatedly typing @key{SPC}. + +@kindex DEL @r{(Gnus)} +@item @key{DEL} +In the group buffer, move point to the previous group containing +unread articles. + +@findex gnus-summary-prev-page +In the summary buffer, scroll the text of the article backwards. + +@kindex n @r{(Gnus)} +@findex gnus-group-next-unread-group +@findex gnus-summary-next-unread-article +@item n +Move point to the next unread group, or select the next unread article. + +@kindex p @r{(Gnus)} +@findex gnus-group-prev-unread-group +@findex gnus-summary-prev-unread-article +@item p +Move point to the previous unread group, or select the previous +unread article. + +@kindex C-n @r{(Gnus Group mode)} +@findex gnus-group-next-group +@kindex C-p @r{(Gnus Group mode)} +@findex gnus-group-prev-group +@kindex C-n @r{(Gnus Summary mode)} +@findex gnus-summary-next-subject +@kindex C-p @r{(Gnus Summary mode)} +@findex gnus-summary-prev-subject +@item C-n +@itemx C-p +Move point to the next or previous item, even if it is marked as read. +This does not select the article or group on that line. + +@kindex s @r{(Gnus Summary mode)} +@findex gnus-summary-isearch-article +@item s +In the summary buffer, do an incremental search of the current text in +the article buffer, just as if you switched to the article buffer and +typed @kbd{C-s}. + +@kindex M-s @r{(Gnus Summary mode)} +@findex gnus-summary-search-article-forward +@item M-s @var{regexp} @key{RET} +In the summary buffer, search forward for articles containing a match +for @var{regexp}. + +@end table + +@ignore +@node Where to Look +@subsection Where to Look Further + +@c Too many references to the name of the manual if done with xref in TeX! +Gnus is powerful and customizable. Here are references to a few +@ifinfo +additional topics: + +@end ifinfo +@iftex +additional topics in @cite{The Gnus Manual}: + +@itemize @bullet +@item +Follow discussions on specific topics.@* +See section ``Threading.'' + +@item +Read digests. See section ``Document Groups.'' + +@item +Refer to and jump to the parent of the current article.@* +See section ``Finding the Parent.'' + +@item +Refer to articles by using Message-IDs included in the messages.@* +See section ``Article Keymap.'' + +@item +Save articles. See section ``Saving Articles.'' + +@item +Have Gnus score articles according to various criteria, like author +name, subject, or string in the body of the articles.@* +See section ``Scoring.'' + +@item +Send an article to a newsgroup.@* +See section ``Composing Messages.'' +@end itemize +@end iftex +@ifinfo +@itemize @bullet +@item +Follow discussions on specific topics.@* +@xref{Threading, , Reading Based on Conversation Threads, +gnus, The Gnus Manual}. + +@item +Read digests. @xref{Document Groups, , , gnus, The Gnus Manual}. + +@item +Refer to and jump to the parent of the current article.@* +@xref{Finding the Parent, , , gnus, The Gnus Manual}. + +@item +Refer to articles by using Message-IDs included in the messages.@* +@xref{Article Keymap, , , gnus, The Gnus Manual}. + +@item +Save articles. @xref{Saving Articles, , , gnus, The Gnus Manual}. + +@item +Have Gnus score articles according to various criteria, like author +name, subject, or string in the body of the articles.@* +@xref{Scoring, , , gnus, The Gnus Manual}. + +@item +Send an article to a newsgroup.@* +@xref{Composing Messages, , , gnus, The Gnus Manual}. +@end itemize +@end ifinfo +@end ignore + +@node Shell, Emacs Server, Gnus, Top +@section Running Shell Commands from Emacs +@cindex subshell +@cindex shell commands + + Emacs has commands for passing single command lines to inferior shell +processes; it can also run a shell interactively with input and output to +an Emacs buffer named @samp{*shell*}. + +@table @kbd +@item M-! @var{cmd} @key{RET} +Run the shell command line @var{cmd} and display the output +(@code{shell-command}). +@item M-| @var{cmd} @key{RET} +Run the shell command line @var{cmd} with region contents as input; +optionally replace the region with the output +(@code{shell-command-on-region}). +@item M-x shell +Run a subshell with input and output through an Emacs buffer. +You can then give commands interactively. +@end table + +@menu +* Single Shell:: How to run one shell command and return. +* Interactive Shell:: Permanent shell taking input via Emacs. +* Shell Mode:: Special Emacs commands used with permanent shell. +* History: Shell History. Repeating previous commands in a shell buffer. +* Options: Shell Options. Options for customizing Shell mode. +* Remote Host:: Connecting to another computer. +@end menu + +@node Single Shell +@subsection Single Shell Commands + +@kindex M-! +@findex shell-command + @kbd{M-!} (@code{shell-command}) reads a line of text using the +minibuffer and executes it as a shell command in a subshell made just +for that command. Standard input for the command comes from the null +device. If the shell command produces any output, the output goes into +an Emacs buffer named @samp{*Shell Command Output*}, which is displayed +in another window but not selected. A numeric argument, as in @kbd{M-1 +M-!}, directs this command to insert any output into the current buffer. +In that case, point is left before the output and the mark is set after +the output. + + If the shell command line ends in @samp{&}, it runs asynchronously. +For a synchronous shell command, @code{shell-command} returns the +command's exit status (0 means success), when it is called from a Lisp +program. + +@kindex M-| +@findex shell-command-on-region + @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but +passes the contents of the region as the standard input to the shell +command, instead of no input. If a numeric argument is used, meaning +insert the output in the current buffer, then the old region is deleted +first and the output replaces it as the contents of the region. It +returns the command's exit status when it is called from a Lisp program. + +@vindex shell-file-name +@cindex environment + Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify the +shell to use. This variable is initialized based on your @code{SHELL} +environment variable when Emacs is started. If the file name does not +specify a directory, the directories in the list @code{exec-path} are +searched; this list is initialized based on the environment variable +@code{PATH} when Emacs is started. Your @file{.emacs} file can override +either or both of these default initializations.@refill + + Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete. +To stop waiting, type @kbd{C-g} to quit; that terminates the shell +command with the signal @code{SIGINT}---the same signal that @kbd{C-c} +normally generates in the shell. Emacs waits until the command actually +terminates. If the shell command doesn't stop (because it ignores the +@code{SIGINT} signal), type @kbd{C-g} again; this sends the command a +@code{SIGKILL} signal which is impossible to ignore. + + To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command +@kbd{C-x @key{RET} c} immediately beforehand. @xref{Specify Coding}. + +@vindex shell-command-default-error-buffer + Error output from the command is normally intermixed with the regular +output. If you set the variable +@code{shell-command-default-error-buffer} to a string, which is a buffer +name, error output is inserted before point in the buffer of that name. + +@node Interactive Shell +@subsection Interactive Inferior Shell + +@findex shell + To run a subshell interactively, putting its typescript in an Emacs +buffer, use @kbd{M-x shell}. This creates (or reuses) a buffer named +@samp{*shell*} and runs a subshell with input coming from and output going +to that buffer. That is to say, any ``terminal output'' from the subshell +goes into the buffer, advancing point, and any ``terminal input'' for +the subshell comes from text in the buffer. To give input to the subshell, +go to the end of the buffer and type the input, terminated by @key{RET}. + + Emacs does not wait for the subshell to do anything. You can switch +windows or buffers and edit them while the shell is waiting, or while it is +running a command. Output from the subshell waits until Emacs has time to +process it; this happens whenever Emacs is waiting for keyboard input or +for time to elapse. + + To make multiple subshells, rename the buffer @samp{*shell*} to +something different using @kbd{M-x rename-uniquely}. Then type @kbd{M-x +shell} again to create a new buffer @samp{*shell*} with its own +subshell. If you rename this buffer as well, you can create a third +one, and so on. All the subshells run independently and in parallel. + +@vindex explicit-shell-file-name +@cindex @code{ESHELL} environment variable +@cindex @code{SHELL} environment variable + The file name used to load the subshell is the value of the variable +@code{explicit-shell-file-name}, if that is non-@code{nil}. Otherwise, +the environment variable @code{ESHELL} is used, or the environment +variable @code{SHELL} if there is no @code{ESHELL}. If the file name +specified is relative, the directories in the list @code{exec-path} are +searched; this list is initialized based on the environment variable +@code{PATH} when Emacs is started. Your @file{.emacs} file can override +either or both of these default initializations. + + To specify a coding system for the shell, you can use the command +@kbd{C-x @key{RET} c} immediately before @kbd{M-x shell}. You can also +specify a coding system after starting the shell by using @kbd{C-x +@key{RET} p} in the shell buffer. @xref{Specify Coding}. + + As soon as the subshell is started, it is sent as input the contents +of the file @file{~/.emacs_@var{shellname}}, if that file exists, where +@var{shellname} is the name of the file that the shell was loaded from. +For example, if you use bash, the file sent to it is +@file{~/.emacs_bash}. + +@vindex shell-pushd-regexp +@vindex shell-popd-regexp +@vindex shell-cd-regexp + @code{cd}, @code{pushd} and @code{popd} commands given to the inferior +shell are watched by Emacs so it can keep the @samp{*shell*} buffer's +default directory the same as the shell's working directory. These +commands are recognized syntactically by examining lines of input that are +sent. If you use aliases for these commands, you can tell Emacs to +recognize them also. For example, if the value of the variable +@code{shell-pushd-regexp} matches the beginning of a shell command line, +that line is regarded as a @code{pushd} command. Change this variable when +you add aliases for @samp{pushd}. Likewise, @code{shell-popd-regexp} and +@code{shell-cd-regexp} are used to recognize commands with the meaning of +@samp{popd} and @samp{cd}. These commands are recognized only at the +beginning of a shell command line.@refill + +@vindex shell-set-directory-error-hook + If Emacs gets an error while trying to handle what it believes is a +@samp{cd}, @samp{pushd} or @samp{popd} command, it runs the hook +@code{shell-set-directory-error-hook} (@pxref{Hooks}). + +@findex dirs + If Emacs does not properly track changes in the current directory of +the subshell, use the command @kbd{M-x dirs} to ask the shell what its +current directory is. This command works for shells that support the +most common command syntax; it may not work for unusual shells. + +@findex dirtrack-mode + You can also use @kbd{M-x dirtrack-mode} to enable (or disable) an +alternative and more aggressive method of tracking changes in the +current directory. + + Emacs defines the environment variable @code{EMACS} in the subshell, +with value @code{t}. A shell script can check this variable to +determine whether it has been run from an Emacs subshell. + +@node Shell Mode +@subsection Shell Mode +@cindex Shell mode +@cindex mode, Shell + + Shell buffers use Shell mode, which defines several special keys +attached to the @kbd{C-c} prefix. They are chosen to resemble the usual +editing and job control characters present in shells that are not under +Emacs, except that you must type @kbd{C-c} first. Here is a complete list +of the special key bindings of Shell mode: + +@table @kbd +@item @key{RET} +@kindex RET @r{(Shell mode)} +@findex comint-send-input +At end of buffer send line as input; otherwise, copy current line to end +of buffer and send it (@code{comint-send-input}). When a line is +copied, any text at the beginning of the line that matches the variable +@code{shell-prompt-pattern} is left out; this variable's value should be +a regexp string that matches the prompts that your shell uses. + +@item @key{TAB} +@kindex TAB @r{(Shell mode)} +@findex comint-dynamic-complete +Complete the command name or file name before point in the shell buffer +(@code{comint-dynamic-complete}). @key{TAB} also completes history +references (@pxref{History References}) and environment variable names. + +@vindex shell-completion-fignore +@vindex comint-completion-fignore +The variable @code{shell-completion-fignore} specifies a list of file +name extensions to ignore in Shell mode completion. The default setting +ignores file names ending in @samp{~}, @samp{#} or @samp{%}. Other +related Comint modes use the variable @code{comint-completion-fignore} +instead. + +@item M-? +@kindex M-? @r{(Shell mode)} +@findex comint-dynamic-list-filename@dots{} +Display temporarily a list of the possible completions of the file name +before point in the shell buffer +(@code{comint-dynamic-list-filename-completions}). + +@item C-d +@kindex C-d @r{(Shell mode)} +@findex comint-delchar-or-maybe-eof +Either delete a character or send @sc{EOF} +(@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell +buffer, @kbd{C-d} sends @sc{EOF} to the subshell. Typed at any other +position in the buffer, @kbd{C-d} deletes a character as usual. + +@item C-c C-a +@kindex C-c C-a @r{(Shell mode)} +@findex comint-bol +Move to the beginning of the line, but after the prompt if any +(@code{comint-bol}). If you repeat this command twice in a row, the +second time it moves back to the process mark, which is the beginning of +the input that you have not yet sent to the subshell. (Normally that is +the same place---the end of the prompt on this line---but after @kbd{C-c +@key{SPC}} the process mark may be in a previous line.) + +@item C-c @key{SPC} +Accumulate multiple lines of input, then send them together. This +command inserts a newline before point, but does not send the preceding +text as input to the subshell---at least, not yet. Both lines, the one +before this newline and the one after, will be sent together (along with +the newline that separates them), when you type @key{RET}. + +@item C-c C-u +@kindex C-c C-u @r{(Shell mode)} +@findex comint-kill-input +Kill all text pending at end of buffer to be sent as input +(@code{comint-kill-input}). + +@item C-c C-w +@kindex C-c C-w @r{(Shell mode)} +Kill a word before point (@code{backward-kill-word}). + +@item C-c C-c +@kindex C-c C-c @r{(Shell mode)} +@findex comint-interrupt-subjob +Interrupt the shell or its current subjob if any +(@code{comint-interrupt-subjob}). This command also kills +any shell input pending in the shell buffer and not yet sent. + +@item C-c C-z +@kindex C-c C-z @r{(Shell mode)} +@findex comint-stop-subjob +Stop the shell or its current subjob if any (@code{comint-stop-subjob}). +This command also kills any shell input pending in the shell buffer and +not yet sent. + +@item C-c C-\ +@findex comint-quit-subjob +@kindex C-c C-\ @r{(Shell mode)} +Send quit signal to the shell or its current subjob if any +(@code{comint-quit-subjob}). This command also kills any shell input +pending in the shell buffer and not yet sent. + +@item C-c C-o +@kindex C-c C-o @r{(Shell mode)} +@findex comint-kill-output +Kill the last batch of output from a shell command +(@code{comint-kill-output}). This is useful if a shell command spews +out lots of output that just gets in the way. + +@item C-c C-r +@itemx C-M-l +@kindex C-c C-r @r{(Shell mode)} +@kindex C-M-l @r{(Shell mode)} +@findex comint-show-output +Scroll to display the beginning of the last batch of output at the top +of the window; also move the cursor there (@code{comint-show-output}). + +@item C-c C-e +@kindex C-c C-e @r{(Shell mode)} +@findex comint-show-maximum-output +Scroll to put the end of the buffer at the bottom of the window +(@code{comint-show-maximum-output}). + +@item C-c C-f +@kindex C-c C-f @r{(Shell mode)} +@findex shell-forward-command +@vindex shell-command-regexp +Move forward across one shell command, but not beyond the current line +(@code{shell-forward-command}). The variable @code{shell-command-regexp} +specifies how to recognize the end of a command. + +@item C-c C-b +@kindex C-c C-b @r{(Shell mode)} +@findex shell-backward-command +Move backward across one shell command, but not beyond the current line +(@code{shell-backward-command}). + +@item C-c C-l +@kindex C-c C-l @r{(Shell mode)} +@findex comint-dynamic-list-input-ring +Display the buffer's history of shell commands in another window +(@code{comint-dynamic-list-input-ring}). + +@item M-x dirs +Ask the shell what its current directory is, so that Emacs can agree +with the shell. + +@item M-x send-invisible @key{RET} @var{text} @key{RET} +@findex send-invisible +Send @var{text} as input to the shell, after reading it without +echoing. This is useful when a shell command runs a program that asks +for a password. + +Alternatively, you can arrange for Emacs to notice password prompts +and turn off echoing for them, as follows: + +@example +(add-hook 'comint-output-filter-functions + 'comint-watch-for-password-prompt) +@end example + +@item M-x comint-continue-subjob +@findex comint-continue-subjob +Continue the shell process. This is useful if you accidentally suspend +the shell process.@footnote{You should not suspend the shell process. +Suspending a subjob of the shell is a completely different matter---that +is normal practice, but you must use the shell to continue the subjob; +this command won't do it.} + +@item M-x comint-strip-ctrl-m +@findex comint-strip-ctrl-m +Discard all control-M characters from the current group of shell output. +The most convenient way to use this command is to make it run +automatically when you get output from the subshell. To do that, +evaluate this Lisp expression: + +@example +(add-hook 'comint-output-filter-functions + 'comint-strip-ctrl-m) +@end example + +@item M-x comint-truncate-buffer +@findex comint-truncate-buffer +This command truncates the shell buffer to a certain maximum number of +lines, specified by the variable @code{comint-buffer-maximum-size}. +Here's how to do this automatically each time you get output from the +subshell: + +@example +(add-hook 'comint-output-filter-functions + 'comint-truncate-buffer) +@end example +@end table + + Shell mode also customizes the paragraph commands so that only shell +prompts start new paragraphs. Thus, a paragraph consists of an input +command plus the output that follows it in the buffer. + +@cindex Comint mode +@cindex mode, Comint + Shell mode is a derivative of Comint mode, a general-purpose mode for +communicating with interactive subprocesses. Most of the features of +Shell mode actually come from Comint mode, as you can see from the +command names listed above. The special features of Shell mode in +particular include the choice of regular expression for detecting +prompts, the directory tracking feature, and a few user commands. + + Other Emacs features that use variants of Comint mode include GUD +(@pxref{Debuggers}) and @kbd{M-x run-lisp} (@pxref{External Lisp}). + +@findex comint-run + You can use @kbd{M-x comint-run} to execute any program of your choice +in a subprocess using unmodified Comint mode---without the +specializations of Shell mode. + +@node Shell History +@subsection Shell Command History + + Shell buffers support three ways of repeating earlier commands. You +can use the same keys used in the minibuffer; these work much as they do +in the minibuffer, inserting text from prior commands while point +remains always at the end of the buffer. You can move through the +buffer to previous inputs in their original place, then resubmit them or +copy them to the end. Or you can use a @samp{!}-style history +reference. + +@menu +* Ring: Shell Ring. Fetching commands from the history list. +* Copy: Shell History Copying. Moving to a command and then copying it. +* History References:: Expanding @samp{!}-style history references. +@end menu + +@node Shell Ring +@subsubsection Shell History Ring + +@table @kbd +@findex comint-previous-input +@kindex M-p @r{(Shell mode)} +@item M-p +Fetch the next earlier old shell command. + +@kindex M-n @r{(Shell mode)} +@findex comint-next-input +@item M-n +Fetch the next later old shell command. + +@kindex M-r @r{(Shell mode)} +@kindex M-s @r{(Shell mode)} +@findex comint-previous-matching-input +@findex comint-next-matching-input +@item M-r @var{regexp} @key{RET} +@itemx M-s @var{regexp} @key{RET} +Search backwards or forwards for old shell commands that match @var{regexp}. + +@item C-c C-x @r{(Shell mode)} +@findex comint-get-next-from-history +Fetch the next subsequent command from the history. +@end table + + Shell buffers provide a history of previously entered shell commands. To +reuse shell commands from the history, use the editing commands @kbd{M-p}, +@kbd{M-n}, @kbd{M-r} and @kbd{M-s}. These work just like the minibuffer +history commands except that they operate on the text at the end of the +shell buffer, where you would normally insert text to send to the shell. + + @kbd{M-p} fetches an earlier shell command to the end of the shell buffer. +Successive use of @kbd{M-p} fetches successively earlier shell commands, +each replacing any text that was already present as potential shell input. +@kbd{M-n} does likewise except that it finds successively more recent shell +commands from the buffer. + + The history search commands @kbd{M-r} and @kbd{M-s} read a regular +expression and search through the history for a matching command. Aside +from the choice of which command to fetch, they work just like @kbd{M-p} +and @kbd{M-r}. If you enter an empty regexp, these commands reuse the +same regexp used last time. + + When you find the previous input you want, you can resubmit it by +typing @key{RET}, or you can edit it first and then resubmit it if you +wish. + + Often it is useful to reexecute several successive shell commands that +were previously executed in sequence. To do this, first find and +reexecute the first command of the sequence. Then type @kbd{C-c C-x}; +that will fetch the following command---the one that follows the command +you just repeated. Then type @key{RET} to reexecute this command. You +can reexecute several successive commands by typing @kbd{C-c C-x +@key{RET}} over and over. + + These commands get the text of previous shell commands from a special +history list, not from the shell buffer itself. Thus, editing the shell +buffer, or even killing large parts of it, does not affect the history +that these commands access. + +@vindex shell-input-ring-file-name + Some shells store their command histories in files so that you can +refer to previous commands from previous shell sessions. Emacs reads +the command history file for your chosen shell, to initialize its own +command history. The file name is @file{~/.bash_history} for bash, +@file{~/.sh_history} for ksh, and @file{~/.history} for other shells. + +@node Shell History Copying +@subsubsection Shell History Copying + +@table @kbd +@kindex C-c C-p @r{(Shell mode)} +@findex comint-previous-prompt +@item C-c C-p +Move point to the previous prompt (@code{comint-previous-prompt}). + +@kindex C-c C-n @r{(Shell mode)} +@findex comint-next-prompt +@item C-c C-n +Move point to the following prompt (@code{comint-next-prompt}). + +@kindex C-c RET @r{(Shell mode)} +@findex comint-copy-old-input +@item C-c @key{RET} +Copy the input command which point is in, inserting the copy at the end +of the buffer (@code{comint-copy-old-input}). This is useful if you +move point back to a previous command. After you copy the command, you +can submit the copy as input with @key{RET}. If you wish, you can +edit the copy before resubmitting it. +@end table + + Moving to a previous input and then copying it with @kbd{C-c +@key{RET}} produces the same results---the same buffer contents---that +you would get by using @kbd{M-p} enough times to fetch that previous +input from the history list. However, @kbd{C-c @key{RET}} copies the +text from the buffer, which can be different from what is in the history +list if you edit the input text in the buffer after it has been sent. + +@node History References +@subsubsection Shell History References +@cindex history reference + + Various shells including csh and bash support @dfn{history references} +that begin with @samp{!} and @samp{^}. Shell mode can understand these +constructs and perform the history substitution for you. If you insert +a history reference and type @key{TAB}, this searches the input history +for a matching command, performs substitution if necessary, and places +the result in the buffer in place of the history reference. For +example, you can fetch the most recent command beginning with @samp{mv} +with @kbd{! m v @key{TAB}}. You can edit the command if you wish, and +then resubmit the command to the shell by typing @key{RET}. + +@vindex shell-prompt-pattern +@vindex comint-prompt-regexp + History references take effect only following a shell prompt. The +variable @code{shell-prompt-pattern} specifies how to recognize a shell +prompt. Comint modes in general use the variable +@code{comint-prompt-regexp} to specify how to find a prompt; Shell mode +uses @code{shell-prompt-pattern} to set up the local value of +@code{comint-prompt-regexp}. + +@vindex comint-input-autoexpand + Shell mode can optionally expand history references in the buffer when +you send them to the shell. To request this, set the variable +@code{comint-input-autoexpand} to @code{input}. + +@findex comint-magic-space + You can make @key{SPC} perform history expansion by binding @key{SPC} to +the command @code{comint-magic-space}. + +@node Shell Options +@subsection Shell Mode Options + +@vindex comint-scroll-to-bottom-on-input + If the variable @code{comint-scroll-to-bottom-on-input} is +non-@code{nil}, insertion and yank commands scroll the selected window +to the bottom before inserting. + +@vindex comint-scroll-show-maximum-output + If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then +scrolling due to arrival of output tries to place the last line of text +at the bottom line of the window, so as to show as much useful text as +possible. (This mimics the scrolling behavior of many terminals.) +The default is @code{nil}. + +@vindex comint-scroll-to-bottom-on-output + By setting @code{comint-scroll-to-bottom-on-output}, you can opt for +having point jump to the end of the buffer whenever output arrives---no +matter where in the buffer point was before. If the value is +@code{this}, point jumps in the selected window. If the value is +@code{all}, point jumps in each window that shows the comint buffer. If +the value is @code{other}, point jumps in all nonselected windows that +show the current buffer. The default value is @code{nil}, which means +point does not jump to the end. + +@vindex comint-input-ignoredups + The variable @code{comint-input-ignoredups} controls whether successive +identical inputs are stored in the input history. A non-@code{nil} +value means to omit an input that is the same as the previous input. +The default is @code{nil}, which means to store each input even if it is +equal to the previous input. + +@vindex comint-completion-addsuffix +@vindex comint-completion-recexact +@vindex comint-completion-autolist + Three variables customize file name completion. The variable +@code{comint-completion-addsuffix} controls whether completion inserts a +space or a slash to indicate a fully completed file or directory name +(non-@code{nil} means do insert a space or slash). +@code{comint-completion-recexact}, if non-@code{nil}, directs @key{TAB} +to choose the shortest possible completion if the usual Emacs completion +algorithm cannot add even a single character. +@code{comint-completion-autolist}, if non-@code{nil}, says to list all +the possible completions whenever completion is not exact. + +@findex comint-dynamic-complete-variable + The command @code{comint-dynamic-complete-variable} does variable-name +completion using the environment variables as set within Emacs. The +variables controlling file name completion apply to variable-name +completion too. This command is normally available through the menu +bar. + +@vindex shell-command-execonly + Command completion normally considers only executable files. +If you set @code{shell-command-execonly} to @code{nil}, +it considers nonexecutable files as well. + +@findex shell-pushd-tohome +@findex shell-pushd-dextract +@findex shell-pushd-dunique + You can configure the behavior of @samp{pushd}. Variables control +whether @samp{pushd} behaves like @samp{cd} if no argument is given +(@code{shell-pushd-tohome}), pop rather than rotate with a numeric +argument (@code{shell-pushd-dextract}), and only add directories to the +directory stack if they are not already on it +(@code{shell-pushd-dunique}). The values you choose should match the +underlying shell, of course. + +@node Remote Host +@subsection Remote Host Shell +@cindex remote host +@cindex connecting to remote host +@cindex Telnet +@cindex Rlogin + + Emacs provides two commands for logging in to another computer +and communicating with it through an Emacs buffer. + +@table @kbd +@item M-x telnet @key{RET} @var{hostname} @key{RET} +Set up a Telnet connection to the computer named @var{hostname}. +@item M-x rlogin @key{RET} @var{hostname} @key{RET} +Set up an Rlogin connection to the computer named @var{hostname}. +@end table + +@findex telnet + Use @kbd{M-x telnet} to set up a Telnet connection to another +computer. (Telnet is the standard Internet protocol for remote login.) +It reads the host name of the other computer as an argument with the +minibuffer. Once the connection is established, talking to the other +computer works like talking to a subshell: you can edit input with the +usual Emacs commands, and send it a line at a time by typing @key{RET}. +The output is inserted in the Telnet buffer interspersed with the input. + +@findex rlogin +@vindex rlogin-explicit-args + Use @kbd{M-x rlogin} to set up an Rlogin connection. Rlogin is +another remote login communication protocol, essentially much like the +Telnet protocol but incompatible with it, and supported only by certain +systems. Rlogin's advantages are that you can arrange not to have to +give your user name and password when communicating between two machines +you frequently use, and that you can make an 8-bit-clean connection. +(To do that in Emacs, set @code{rlogin-explicit-args} to @code{("-8")} +before you run Rlogin.) + + @kbd{M-x rlogin} sets up the default file directory of the Emacs +buffer to access the remote host via FTP (@pxref{File Names}), and it +tracks the shell commands that change the current directory, just like +Shell mode. + +@findex rlogin-directory-tracking-mode + There are two ways of doing directory tracking in an Rlogin +buffer---either with remote directory names +@file{/@var{host}:@var{dir}/} or with local names (that works if the +``remote'' machine shares file systems with your machine of origin). +You can use the command @code{rlogin-directory-tracking-mode} to switch +modes. No argument means use remote directory names, a positive +argument means use local names, and a negative argument means turn +off directory tracking. + +@node Emacs Server, Hardcopy, Shell, Top +@section Using Emacs as a Server +@pindex emacsclient +@cindex Emacs as a server +@cindex server, using Emacs as +@cindex @code{EDITOR} environment variable + + Various programs such as @code{mail} can invoke your choice of editor +to edit a particular piece of text, such as a message that you are +sending. By convention, most of these programs use the environment +variable @code{EDITOR} to specify which editor to run. If you set +@code{EDITOR} to @samp{emacs}, they invoke Emacs---but in an +inconvenient fashion, by starting a new, separate Emacs process. This +is inconvenient because it takes time and because the new Emacs process +doesn't share the buffers in the existing Emacs process. + + You can arrange to use your existing Emacs process as the editor for +programs like @code{mail} by using the Emacs client and Emacs server +programs. Here is how. + +@cindex @code{TEXEDIT} environment variable + First, the preparation. Within Emacs, call the function +@code{server-start}. (Your @file{.emacs} file can do this automatically +if you add the expression @code{(server-start)} to it.) Then, outside +Emacs, set the @code{EDITOR} environment variable to @samp{emacsclient}. +(Note that some programs use a different environment variable; for +example, to make @TeX{} use @samp{emacsclient}, you should set the +@code{TEXEDIT} environment variable to @samp{emacsclient +%d %s}.) + +@kindex C-x # +@findex server-edit + Then, whenever any program invokes your specified @code{EDITOR} +program, the effect is to send a message to your principal Emacs telling +it to visit a file. (That's what the program @code{emacsclient} does.) +Emacs displays the buffer immediately and you can immediately begin +editing it. + + When you've finished editing that buffer, type @kbd{C-x #} +(@code{server-edit}). This saves the file and sends a message back to +the @code{emacsclient} program telling it to exit. The programs that +use @code{EDITOR} wait for the ``editor'' (actually, @code{emacsclient}) +to exit. @kbd{C-x #} also checks for other pending external requests +to edit various files, and selects the next such file. + + You can switch to a server buffer manually if you wish; you don't have +to arrive at it with @kbd{C-x #}. But @kbd{C-x #} is the only way to +say that you are ``finished'' with one. + +@vindex server-window + If you set the variable @code{server-window} to a window or a frame, +@kbd{C-x #} displays the server buffer in that window or in that frame. + + While @code{mail} or another application is waiting for +@code{emacsclient} to finish, @code{emacsclient} does not read terminal +input. So the terminal that @code{mail} was using is effectively +blocked for the duration. In order to edit with your principal Emacs, +you need to be able to use it without using that terminal. There are +two ways to do this: + +@itemize @bullet +@item +Using a window system, run @code{mail} and the principal Emacs in two +separate windows. While @code{mail} is waiting for @code{emacsclient}, +the window where it was running is blocked, but you can use Emacs by +switching windows. + +@item +Use Shell mode in Emacs to run the other program such as @code{mail}; +then, @code{emacsclient} blocks only the subshell under Emacs, and you +can still use Emacs to edit the file. +@end itemize + +@vindex server-temp-file-regexp + Some programs write temporary files for you to edit. After you edit +the temporary file, the program reads it back and deletes it. If the +Emacs server is later asked to edit the same file name, it should assume +this has nothing to do with the previous occasion for that file name. +The server accomplishes this by killing the temporary file's buffer when +you finish with the file. Use the variable +@code{server-temp-file-regexp} to specify which files are temporary in +this sense; its value should be a regular expression that matches file +names that are temporary. + + If you run @code{emacsclient} with the option @samp{--no-wait}, it +returns immediately without waiting for you to ``finish'' the buffer in +Emacs. + +@menu +* Invoking emacsclient:: +@end menu + +@node Invoking emacsclient,, Emacs Server, Emacs Server +@section Invoking @code{emacsclient} + + To run the @code{emacsclient} program, specify file names as arguments, +and optionally line numbers as well. Do it like this: + +@example +emacsclient @r{@{}@r{[}+@var{line}@r{]} @var{filename}@r{@}}@dots{} +@end example + +This tells Emacs to visit each of the specified files; if you specify a +line number for a certain file, Emacs moves to that line in the file. + +Ordinarily, @code{emacsclient} does not return until you use the +@kbd{C-x #} command on each of these buffers. When that happens, Emacs +sends a message to the @code{emacsclient} program telling it to return. + +But if you use the option @samp{-n} or @samp{--no-wait} when running +@code{emacsclient}, then it returns immediately. (You can take as long +as you like to edit the files in Emacs.) + + +@node Hardcopy, Postscript, Emacs Server, Top +@section Hardcopy Output +@cindex hardcopy + + The Emacs commands for making hardcopy let you print either an entire +buffer or just part of one, either with or without page headers. +See also the hardcopy commands of Dired (@pxref{Misc File Ops}) +and the diary (@pxref{Diary Commands}). + +@table @kbd +@item M-x print-buffer +Print hardcopy of current buffer with page headings containing the file +name and page number. +@item M-x lpr-buffer +Print hardcopy of current buffer without page headings. +@item M-x print-region +Like @code{print-buffer} but print only the current region. +@item M-x lpr-region +Like @code{lpr-buffer} but print only the current region. +@end table + +@findex print-buffer +@findex print-region +@findex lpr-buffer +@findex lpr-region +@vindex lpr-switches + The hardcopy commands (aside from the Postscript commands) pass extra +switches to the @code{lpr} program based on the value of the variable +@code{lpr-switches}. Its value should be a list of strings, each string +an option starting with @samp{-}. For example, to specify a line width +of 80 columns for all the printing you do in Emacs, set +@code{lpr-switches} like this: + +@example +(setq lpr-switches '("-w80")) +@end example + +@vindex printer-name + You can specify the printer to use by setting the variable +@code{printer-name}. + +@vindex lpr-headers-switches +@vindex lpr-commands +@vindex lpr-add-switches + The variable @code{lpr-command} specifies the name of the printer +program to run; the default value depends on your operating system type. +On most systems, the default is @code{"lpr"}. The variable +@code{lpr-headers-switches} similarly specifies the extra switches to +use to make page headers. The variable @code{lpr-add-switches} controls +whether to supply @samp{-T} and @samp{-J} options (suitable for +@code{lpr}) to the printer program: @code{nil} means don't add them. +@code{lpr-add-switches} should be @code{nil} if your printer program is +not compatible with @code{lpr}. + +@node Postscript, Postscript Variables, Hardcopy, Top +@section Postscript Hardcopy + + These commands convert buffer contents to Postscript, +either printing it or leaving it in another Emacs buffer. + +@table @kbd +@item M-x ps-print-buffer +Print hardcopy of the current buffer in Postscript form. +@item M-x ps-print-region +Print hardcopy of the current region in Postscript form. +@item M-x ps-print-buffer-with-faces +Print hardcopy of the current buffer in Postscript form, showing the +faces used in the text by means of Postscript features. +@item M-x ps-print-region-with-faces +Print hardcopy of the current region in Postscript form, showing the +faces used in the text. +@item M-x ps-spool-buffer +Generate Postscript for the current buffer text. +@item M-x ps-spool-region +Generate Postscript for the current region. +@item M-x ps-spool-buffer-with-faces +Generate Postscript for the current buffer, showing the faces used. +@item M-x ps-spool-region-with-faces +Generate Postscript for the current region, showing the faces used. +@end table + +@findex ps-print-region +@findex ps-print-buffer +@findex ps-print-region-with-faces +@findex ps-print-buffer-with-faces + The Postscript commands, @code{ps-print-buffer} and +@code{ps-print-region}, print buffer contents in Postscript form. One +command prints the entire buffer; the other, just the region. The +corresponding @samp{-with-faces} commands, +@code{ps-print-buffer-with-faces} and @code{ps-print-region-with-faces}, +use Postscript features to show the faces (fonts and colors) in the text +properties of the text being printed. + + If you are using a color display, you can print a buffer of program +code with color highlighting by turning on Font-Lock mode in that +buffer, and using @code{ps-print-buffer-with-faces}. + +@findex ps-spool-region +@findex ps-spool-buffer +@findex ps-spool-region-with-faces +@findex ps-spool-buffer-with-faces + The commands whose names have @samp{spool} instead of @samp{print} +generate the Postscript output in an Emacs buffer instead of sending +it to the printer. + +@ifinfo + The following section describes variables for customizing these commands. +@end ifinfo + +@node Postscript Variables, Sorting, Postscript, Top +@section Variables for Postscript Hardcopy + +@vindex ps-lpr-command +@vindex ps-lpr-switches +@vindex ps-printer-name + All the Postscript hardcopy commands use the variables +@code{ps-lpr-command} and @code{ps-lpr-switches} to specify how to print +the output. @code{ps-lpr-command} specifies the command name to run, +@code{ps-lpr-switches} specifies command line options to use, and +@code{ps-printer-name} specifies the printer. If you don't set the +first two variables yourself, they take their initial values from +@code{lpr-command} and @code{lpr-switches}. If @code{ps-printer-name} +is @code{nil}, @code{printer-name} is used. + +@vindex ps-print-header +@vindex ps-print-color-p + The variable @code{ps-print-header} controls whether these commands +add header lines to each page---set it to @code{nil} to turn headers +off. You can turn off color processing by setting +@code{ps-print-color-p} to @code{nil}. + +@vindex ps-paper-type +@vindex ps-page-dimensions-database + The variable @code{ps-paper-type} specifies which size of paper to +format for; legitimate values include @code{a4}, @code{a3}, +@code{a4small}, @code{b4}, @code{b5}, @code{executive}, @code{ledger}, +@code{legal}, @code{letter}, @code{letter-small}, @code{statement}, +@code{tabloid}. The default is @code{letter}. You can define +additional paper sizes by changing the variable +@code{ps-page-dimensions-database}. + +@vindex ps-landscape-mode + The variable @code{ps-landscape-mode} specifies the orientation of +printing on the page. The default is @code{nil}, which stands for +``portrait'' mode. Any non-@code{nil} value specifies ``landscape'' +mode. + +@vindex ps-number-of-columns + The variable @code{ps-number-of-columns} specifies the number of +columns; it takes effect in both landscape and portrait mode. The +default is 1. + +@vindex ps-font-family +@vindex ps-font-size +@vindex ps-font-info-database + The variable @code{ps-font-family} specifies which font family to use +for printing ordinary text. Legitimate values include @code{Courier}, +@code{Helvetica}, @code{NewCenturySchlbk}, @code{Palatino} and +@code{Times}. The variable @code{ps-font-size} specifies the size of +the font for ordinary text. It defaults to 8.5 points. + + Many other customization variables for these commands are defined and +described in the Lisp file @file{ps-print.el}. + +@node Sorting, Narrowing, Postscript Variables, Top +@section Sorting Text +@cindex sorting + + Emacs provides several commands for sorting text in the buffer. All +operate on the contents of the region (the text between point and the +mark). They divide the text of the region into many @dfn{sort records}, +identify a @dfn{sort key} for each record, and then reorder the records +into the order determined by the sort keys. The records are ordered so +that their keys are in alphabetical order, or, for numeric sorting, in +numeric order. In alphabetic sorting, all upper-case letters `A' through +`Z' come before lower-case `a', in accord with the ASCII character +sequence. + + The various sort commands differ in how they divide the text into sort +records and in which part of each record is used as the sort key. Most of +the commands make each line a separate sort record, but some commands use +paragraphs or pages as sort records. Most of the sort commands use each +entire sort record as its own sort key, but some use only a portion of the +record as the sort key. + +@findex sort-lines +@findex sort-paragraphs +@findex sort-pages +@findex sort-fields +@findex sort-numeric-fields +@table @kbd +@item M-x sort-lines +Divide the region into lines, and sort by comparing the entire +text of a line. A numeric argument means sort into descending order. + +@item M-x sort-paragraphs +Divide the region into paragraphs, and sort by comparing the entire +text of a paragraph (except for leading blank lines). A numeric +argument means sort into descending order. + +@item M-x sort-pages +Divide the region into pages, and sort by comparing the entire +text of a page (except for leading blank lines). A numeric +argument means sort into descending order. + +@item M-x sort-fields +Divide the region into lines, and sort by comparing the contents of +one field in each line. Fields are defined as separated by +whitespace, so the first run of consecutive non-whitespace characters +in a line constitutes field 1, the second such run constitutes field +2, etc. + +Specify which field to sort by with a numeric argument: 1 to sort by +field 1, etc. A negative argument means count fields from the right +instead of from the left; thus, minus 1 means sort by the last field. +If several lines have identical contents in the field being sorted, they +keep same relative order that they had in the original buffer. + +@item M-x sort-numeric-fields +Like @kbd{M-x sort-fields} except the specified field is converted +to an integer for each line, and the numbers are compared. @samp{10} +comes before @samp{2} when considered as text, but after it when +considered as a number. + +@item M-x sort-columns +Like @kbd{M-x sort-fields} except that the text within each line +used for comparison comes from a fixed range of columns. See below +for an explanation. + +@item M-x reverse-region +Reverse the order of the lines in the region. This is useful for +sorting into descending order by fields or columns, since those sort +commands do not have a feature for doing that. +@end table + + For example, if the buffer contains this: + +@smallexample +On systems where clash detection (locking of files being edited) is +implemented, Emacs also checks the first time you modify a buffer +whether the file has changed on disk since it was last visited or +saved. If it has, you are asked to confirm that you want to change +the buffer. +@end smallexample + +@noindent +applying @kbd{M-x sort-lines} to the entire buffer produces this: + +@smallexample +On systems where clash detection (locking of files being edited) is +implemented, Emacs also checks the first time you modify a buffer +saved. If it has, you are asked to confirm that you want to change +the buffer. +whether the file has changed on disk since it was last visited or +@end smallexample + +@noindent +where the upper-case @samp{O} sorts before all lower-case letters. If +you use @kbd{C-u 2 M-x sort-fields} instead, you get this: + +@smallexample +implemented, Emacs also checks the first time you modify a buffer +saved. If it has, you are asked to confirm that you want to change +the buffer. +On systems where clash detection (locking of files being edited) is +whether the file has changed on disk since it was last visited or +@end smallexample + +@noindent +where the sort keys were @samp{Emacs}, @samp{If}, @samp{buffer}, +@samp{systems} and @samp{the}. + +@findex sort-columns + @kbd{M-x sort-columns} requires more explanation. You specify the +columns by putting point at one of the columns and the mark at the other +column. Because this means you cannot put point or the mark at the +beginning of the first line of the text you want to sort, this command +uses an unusual definition of `region': all of the line point is in is +considered part of the region, and so is all of the line the mark is in, +as well as all the lines in between. + + For example, to sort a table by information found in columns 10 to 15, +you could put the mark on column 10 in the first line of the table, and +point on column 15 in the last line of the table, and then run +@code{sort-columns}. Equivalently, you could run it with the mark on +column 15 in the first line and point on column 10 in the last line. + + This can be thought of as sorting the rectangle specified by point and +the mark, except that the text on each line to the left or right of the +rectangle moves along with the text inside the rectangle. +@xref{Rectangles}. + +@vindex sort-fold-case + Many of the sort commands ignore case differences when comparing, if +@code{sort-fold-case} is non-@code{nil}. + +@node Narrowing, Two-Column, Sorting, Top +@section Narrowing +@cindex widening +@cindex restriction +@cindex narrowing +@cindex accessible portion + + @dfn{Narrowing} means focusing in on some portion of the buffer, +making the rest temporarily inaccessible. The portion which you can +still get to is called the @dfn{accessible portion}. Canceling the +narrowing, which makes the entire buffer once again accessible, is +called @dfn{widening}. The amount of narrowing in effect in a buffer at +any time is called the buffer's @dfn{restriction}. + + Narrowing can make it easier to concentrate on a single subroutine or +paragraph by eliminating clutter. It can also be used to restrict the +range of operation of a replace command or repeating keyboard macro. + +@c WideCommands +@table @kbd +@item C-x n n +Narrow down to between point and mark (@code{narrow-to-region}). +@item C-x n w +Widen to make the entire buffer accessible again (@code{widen}). +@item C-x n p +Narrow down to the current page (@code{narrow-to-page}). +@item C-x n d +Narrow down to the current defun (@code{narrow-to-defun}). +@end table + + When you have narrowed down to a part of the buffer, that part appears +to be all there is. You can't see the rest, you can't move into it +(motion commands won't go outside the accessible part), you can't change +it in any way. However, it is not gone, and if you save the file all +the inaccessible text will be saved. The word @samp{Narrow} appears in +the mode line whenever narrowing is in effect. + +@kindex C-x n n +@findex narrow-to-region + The primary narrowing command is @kbd{C-x n n} (@code{narrow-to-region}). +It sets the current buffer's restrictions so that the text in the current +region remains accessible but all text before the region or after the region +is inaccessible. Point and mark do not change. + +@kindex C-x n p +@findex narrow-to-page +@kindex C-x n d +@findex narrow-to-defun + Alternatively, use @kbd{C-x n p} (@code{narrow-to-page}) to narrow +down to the current page. @xref{Pages}, for the definition of a page. +@kbd{C-x n d} (@code{narrow-to-defun}) narrows down to the defun +containing point (@pxref{Defuns}). + +@kindex C-x n w +@findex widen + The way to cancel narrowing is to widen with @kbd{C-x n w} +(@code{widen}). This makes all text in the buffer accessible again. + + You can get information on what part of the buffer you are narrowed down +to using the @kbd{C-x =} command. @xref{Position Info}. + + Because narrowing can easily confuse users who do not understand it, +@code{narrow-to-region} is normally a disabled command. Attempting to use +this command asks for confirmation and gives you the option of enabling it; +if you enable the command, confirmation will no longer be required for +it. @xref{Disabling}. + +@node Two-Column, Editing Binary Files, Narrowing, Top +@section Two-Column Editing +@cindex two-column editing +@cindex splitting columns +@cindex columns, splitting + + Two-column mode lets you conveniently edit two side-by-side columns of +text. It uses two side-by-side windows, each showing its own +buffer. + + There are three ways to enter two-column mode: + +@table @asis +@item @kbd{@key{F2} 2} or @kbd{C-x 6 2} +@kindex F2 2 +@kindex C-x 6 2 +@findex 2C-two-columns +Enter two-column mode with the current buffer on the left, and on the +right, a buffer whose name is based on the current buffer's name +(@code{2C-two-columns}). If the right-hand buffer doesn't already +exist, it starts out empty; the current buffer's contents are not +changed. + +This command is appropriate when the current buffer is empty or contains +just one column and you want to add another column. + +@item @kbd{@key{F2} s} or @kbd{C-x 6 s} +@kindex F2 s +@kindex C-x 6 s +@findex 2C-split +Split the current buffer, which contains two-column text, into two +buffers, and display them side by side (@code{2C-split}). The current +buffer becomes the left-hand buffer, but the text in the right-hand +column is moved into the right-hand buffer. The current column +specifies the split point. Splitting starts with the current line and +continues to the end of the buffer. + +This command is appropriate when you have a buffer that already contains +two-column text, and you wish to separate the columns temporarily. + +@item @kbd{@key{F2} b @var{buffer} @key{RET}} +@itemx @kbd{C-x 6 b @var{buffer} @key{RET}} +@kindex F2 b +@kindex C-x 6 b +@findex 2C-associate-buffer +Enter two-column mode using the current buffer as the left-hand buffer, +and using buffer @var{buffer} as the right-hand buffer +(@code{2C-associate-buffer}). +@end table + + @kbd{@key{F2} s} or @kbd{C-x 6 s} looks for a column separator, which +is a string that appears on each line between the two columns. You can +specify the width of the separator with a numeric argument to +@kbd{@key{F2} s}; that many characters, before point, constitute the +separator string. By default, the width is 1, so the column separator +is the character before point. + + When a line has the separator at the proper place, @kbd{@key{F2} s} +puts the text after the separator into the right-hand buffer, and +deletes the separator. Lines that don't have the column separator at +the proper place remain unsplit; they stay in the left-hand buffer, and +the right-hand buffer gets an empty line to correspond. (This is the +way to write a line that ``spans both columns while in two-column +mode'': write it in the left-hand buffer, and put an empty line in the +right-hand buffer.) + +@kindex F2 RET +@kindex C-x 6 RET +@findex 2C-newline + The command @kbd{C-x 6 @key{RET}} or @kbd{@key{F2} @key{RET}} +(@code{2C-newline}) inserts a newline in each of the two buffers at +corresponding positions. This is the easiest way to add a new line to +the two-column text while editing it in split buffers. + +@kindex F2 1 +@kindex C-x 6 1 +@findex 2C-merge + When you have edited both buffers as you wish, merge them with +@kbd{@key{F2} 1} or @kbd{C-x 6 1} (@code{2C-merge}). This copies the +text from the right-hand buffer as a second column in the other buffer. +To go back to two-column editing, use @kbd{@key{F2} s}. + +@kindex F2 d +@kindex C-x 6 d +@findex 2C-dissociate + Use @kbd{@key{F2} d} or @kbd{C-x 6 d} to dissociate the two buffers, +leaving each as it stands (@code{2C-dissociate}). If the other buffer, +the one not current when you type @kbd{@key{F2} d}, is empty, +@kbd{@key{F2} d} kills it. + +@node Editing Binary Files, Saving Emacs Sessions, Two-Column, Top +@section Editing Binary Files + +@cindex Hexl mode +@cindex mode, Hexl +@cindex editing binary files + There is a special major mode for editing binary files: Hexl mode. To +use it, use @kbd{M-x hexl-find-file} instead of @kbd{C-x C-f} to visit +the file. This command converts the file's contents to hexadecimal and +lets you edit the translation. When you save the file, it is converted +automatically back to binary. + + You can also use @kbd{M-x hexl-mode} to translate an existing buffer +into hex. This is useful if you visit a file normally and then discover +it is a binary file. + + Ordinary text characters overwrite in Hexl mode. This is to reduce +the risk of accidentally spoiling the alignment of data in the file. +There are special commands for insertion. Here is a list of the +commands of Hexl mode: + +@c I don't think individual index entries for these commands are useful--RMS. +@table @kbd +@item C-M-d +Insert a byte with a code typed in decimal. + +@item C-M-o +Insert a byte with a code typed in octal. + +@item C-M-x +Insert a byte with a code typed in hex. + +@item C-x [ +Move to the beginning of a 1k-byte ``page.'' + +@item C-x ] +Move to the end of a 1k-byte ``page.'' + +@item M-g +Move to an address specified in hex. + +@item M-j +Move to an address specified in decimal. + +@item C-c C-c +Leave Hexl mode, going back to the major mode this buffer had before you +invoked @code{hexl-mode}. +@end table + +@node Saving Emacs Sessions, Recursive Edit, Editing Binary Files, Top +@section Saving Emacs Sessions +@cindex saving sessions +@cindex desktop + + You can use the Desktop library to save the state of Emacs from one +session to another. Saving the state means that Emacs starts up with +the same set of buffers, major modes, buffer positions, and so on that +the previous Emacs session had. + +@vindex desktop-enable + To use Desktop, you should use the Customization buffer (@pxref{Easy +Customization}) to set @code{desktop-enable} to a non-@code{nil} value, +or add these lines at the end of your @file{.emacs} file: + +@example +(desktop-load-default) +(desktop-read) +@end example + +@noindent +@findex desktop-save +The first time you save the state of the Emacs session, you must do it +manually, with the command @kbd{M-x desktop-save}. Once you have done +that, exiting Emacs will save the state again---not only the present +Emacs session, but also subsequent sessions. You can also save the +state at any time, without exiting Emacs, by typing @kbd{M-x +desktop-save} again. + + In order for Emacs to recover the state from a previous session, you +must start it with the same current directory as you used when you +started the previous session. This is because @code{desktop-read} looks +in the current directory for the file to read. This means that you can +have separate saved sessions in different directories; the directory in +which you start Emacs will control which saved session to use. + +@vindex desktop-files-not-to-save + The variable @code{desktop-files-not-to-save} controls which files are +excluded from state saving. Its value is a regular expression that +matches the files to exclude. By default, remote (ftp-accessed) files +are excluded; this is because visiting them again in the subsequent +session would be slow. If you want to include these files in state +saving, set @code{desktop-files-not-to-save} to @code{"^$"}. +@xref{Remote Files}. + +@node Recursive Edit, Emulation, Saving Emacs Sessions, Top +@section Recursive Editing Levels +@cindex recursive editing level +@cindex editing level, recursive + + A @dfn{recursive edit} is a situation in which you are using Emacs +commands to perform arbitrary editing while in the middle of another +Emacs command. For example, when you type @kbd{C-r} inside of a +@code{query-replace}, you enter a recursive edit in which you can change +the current buffer. On exiting from the recursive edit, you go back to +the @code{query-replace}. + +@kindex C-M-c +@findex exit-recursive-edit +@cindex exiting recursive edit + @dfn{Exiting} the recursive edit means returning to the unfinished +command, which continues execution. The command to exit is @kbd{C-M-c} +(@code{exit-recursive-edit}). + + You can also @dfn{abort} the recursive edit. This is like exiting, +but also quits the unfinished command immediately. Use the command +@kbd{C-]} (@code{abort-recursive-edit}) to do this. @xref{Quitting}. + + The mode line shows you when you are in a recursive edit by displaying +square brackets around the parentheses that always surround the major and +minor mode names. Every window's mode line shows this, in the same way, +since being in a recursive edit is true of Emacs as a whole rather than +any particular window or buffer. + + It is possible to be in recursive edits within recursive edits. For +example, after typing @kbd{C-r} in a @code{query-replace}, you may type a +command that enters the debugger. This begins a recursive editing level +for the debugger, within the recursive editing level for @kbd{C-r}. +Mode lines display a pair of square brackets for each recursive editing +level currently in progress. + + Exiting the inner recursive edit (such as, with the debugger @kbd{c} +command) resumes the command running in the next level up. When that +command finishes, you can then use @kbd{C-M-c} to exit another recursive +editing level, and so on. Exiting applies to the innermost level only. +Aborting also gets out of only one level of recursive edit; it returns +immediately to the command level of the previous recursive edit. If you +wish, you can then abort the next recursive editing level. + + Alternatively, the command @kbd{M-x top-level} aborts all levels of +recursive edits, returning immediately to the top-level command reader. + + The text being edited inside the recursive edit need not be the same text +that you were editing at top level. It depends on what the recursive edit +is for. If the command that invokes the recursive edit selects a different +buffer first, that is the buffer you will edit recursively. In any case, +you can switch buffers within the recursive edit in the normal manner (as +long as the buffer-switching keys have not been rebound). You could +probably do all the rest of your editing inside the recursive edit, +visiting files and all. But this could have surprising effects (such as +stack overflow) from time to time. So remember to exit or abort the +recursive edit when you no longer need it. + + In general, we try to minimize the use of recursive editing levels in +GNU Emacs. This is because they constrain you to ``go back'' in a +particular order---from the innermost level toward the top level. When +possible, we present different activities in separate buffers so that +you can switch between them as you please. Some commands switch to a +new major mode which provides a command to switch back. These +approaches give you more flexibility to go back to unfinished tasks in +the order you choose. + +@node Emulation, Dissociated Press, Recursive Edit, Top +@section Emulation +@cindex emulating other editors +@cindex other editors +@cindex EDT +@cindex vi + + GNU Emacs can be programmed to emulate (more or less) most other +editors. Standard facilities can emulate these: + +@table @asis +@item EDT (DEC VMS editor) +@findex edt-emulation-on +@findex edt-emulation-off +Turn on EDT emulation with @kbd{M-x edt-emulation-on}. @kbd{M-x +edt-emulation-off} restores normal Emacs command bindings. + +Most of the EDT emulation commands are keypad keys, and most standard +Emacs key bindings are still available. The EDT emulation rebindings +are done in the global keymap, so there is no problem switching +buffers or major modes while in EDT emulation. + +@item vi (Berkeley editor) +@findex viper-mode +Viper is the newest emulator for vi. It implements several levels of +emulation; level 1 is closest to vi itself, while level 5 departs +somewhat from strict emulation to take advantage of the capabilities of +Emacs. To invoke Viper, type @kbd{M-x viper-mode}; it will guide you +the rest of the way and ask for the emulation level. @inforef{Top, +Viper, viper}. + +@item vi (another emulator) +@findex vi-mode +@kbd{M-x vi-mode} enters a major mode that replaces the previously +established major mode. All of the vi commands that, in real vi, enter +``input'' mode are programmed instead to return to the previous major +mode. Thus, ordinary Emacs serves as vi's ``input'' mode. + +Because vi emulation works through major modes, it does not work +to switch buffers during emulation. Return to normal Emacs first. + +If you plan to use vi emulation much, you probably want to bind a key +to the @code{vi-mode} command. + +@item vi (alternate emulator) +@findex vip-mode +@kbd{M-x vip-mode} invokes another vi emulator, said to resemble real vi +more thoroughly than @kbd{M-x vi-mode}. ``Input'' mode in this emulator +is changed from ordinary Emacs so you can use @key{ESC} to go back to +emulated vi command mode. To get from emulated vi command mode back to +ordinary Emacs, type @kbd{C-z}. + +This emulation does not work through major modes, and it is possible +to switch buffers in various ways within the emulator. It is not +so necessary to assign a key to the command @code{vip-mode} as +it is with @code{vi-mode} because terminating insert mode does +not use it. + +@inforef{Top, VIP, vip}, for full information. +@end table + +@node Dissociated Press, Amusements, Emulation, Top +@section Dissociated Press + +@findex dissociated-press + @kbd{M-x dissociated-press} is a command for scrambling a file of text +either word by word or character by character. Starting from a buffer of +straight English, it produces extremely amusing output. The input comes +from the current Emacs buffer. Dissociated Press writes its output in a +buffer named @samp{*Dissociation*}, and redisplays that buffer after every +couple of lines (approximately) so you can read the output as it comes out. + + Dissociated Press asks every so often whether to continue generating +output. Answer @kbd{n} to stop it. You can also stop at any time by +typing @kbd{C-g}. The dissociation output remains in the +@samp{*Dissociation*} buffer for you to copy elsewhere if you wish. + +@cindex presidentagon + Dissociated Press operates by jumping at random from one point in the +buffer to another. In order to produce plausible output rather than +gibberish, it insists on a certain amount of overlap between the end of +one run of consecutive words or characters and the start of the next. +That is, if it has just printed out `president' and then decides to jump +to a different point in the file, it might spot the `ent' in `pentagon' +and continue from there, producing `presidentagon'.@footnote{This +dissociword actually appeared during the Vietnam War, when it was very +appropriate.} Long sample texts produce the best results. + +@cindex againformation + A positive argument to @kbd{M-x dissociated-press} tells it to operate +character by character, and specifies the number of overlap characters. A +negative argument tells it to operate word by word and specifies the number +of overlap words. In this mode, whole words are treated as the elements to +be permuted, rather than characters. No argument is equivalent to an +argument of two. For your againformation, the output goes only into the +buffer @samp{*Dissociation*}. The buffer you start with is not changed. + +@cindex Markov chain +@cindex ignoriginal +@cindex techniquitous + Dissociated Press produces nearly the same results as a Markov chain +based on a frequency table constructed from the sample text. It is, +however, an independent, ignoriginal invention. Dissociated Press +techniquitously copies several consecutive characters from the sample +between random choices, whereas a Markov chain would choose randomly for +each word or character. This makes for more plausible sounding results, +and runs faster. + +@cindex outragedy +@cindex buggestion +@cindex properbose +@cindex mustatement +@cindex developediment +@cindex userenced + It is a mustatement that too much use of Dissociated Press can be a +developediment to your real work. Sometimes to the point of outragedy. +And keep dissociwords out of your documentation, if you want it to be well +userenced and properbose. Have fun. Your buggestions are welcome. + +@node Amusements, Customization, Dissociated Press, Top +@section Other Amusements +@cindex boredom +@findex hanoi +@findex yow +@findex gomoku +@findex mpuz +@cindex tower of Hanoi + + If you are a little bit bored, you can try @kbd{M-x hanoi}. If you are +considerably bored, give it a numeric argument. If you are very very +bored, try an argument of 9. Sit back and watch. + +@cindex Go Moku + If you want a little more personal involvement, try @kbd{M-x gomoku}, +which plays the game Go Moku with you. + +@findex blackbox +@findex mpuz +@cindex puzzles + @kbd{M-x blackbox} and @kbd{M-x mpuz} are two kinds of puzzles. +@code{blackbox} challenges you to determine the location of objects +inside a box by tomography. @code{mpuz} displays a multiplication +puzzle with letters standing for digits in a code that you must +guess---to guess a value, type a letter and then the digit you think it +stands for. + +@findex dunnet + @kbd{M-x dunnet} runs an adventure-style exploration game, which is +a bigger sort of puzzle. + + When you are frustrated, try the famous Eliza program. Just do +@kbd{M-x doctor}. End each input by typing @key{RET} twice. + +@cindex Zippy + When you are feeling strange, type @kbd{M-x yow}. diff --git a/man/mule.texi b/man/mule.texi new file mode 100644 index 00000000000..c6377e7c77e --- /dev/null +++ b/man/mule.texi @@ -0,0 +1,1004 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1997, 1999 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node International, Major Modes, Frames, Top +@chapter International Character Set Support +@cindex MULE +@cindex international scripts +@cindex multibyte characters +@cindex encoding of characters + +@cindex Chinese +@cindex Devanagari +@cindex Hindi +@cindex Marathi +@cindex Ethiopian +@cindex Greek +@cindex IPA +@cindex Japanese +@cindex Korean +@cindex Lao +@cindex Russian +@cindex Thai +@cindex Tibetan +@cindex Vietnamese + Emacs supports a wide variety of international character sets, +including European variants of the Latin alphabet, as well as Chinese, +Devanagari (Hindi and Marathi), Ethiopian, Greek, IPA, Japanese, Korean, +Lao, Russian, Thai, Tibetan, and Vietnamese scripts. These features +have been merged from the modified version of Emacs known as MULE (for +``MULti-lingual Enhancement to GNU Emacs'') + +@menu +* International Intro:: Basic concepts of multibyte characters. +* Enabling Multibyte:: Controlling whether to use multibyte characters. +* Language Environments:: Setting things up for the language you use. +* Input Methods:: Entering text characters not on your keyboard. +* Select Input Method:: Specifying your choice of input methods. +* Multibyte Conversion:: How single-byte characters convert to multibyte. +* Coding Systems:: Character set conversion when you read and + write files, and so on. +* Recognize Coding:: How Emacs figures out which conversion to use. +* Specify Coding:: Various ways to choose which conversion to use. +* Fontsets:: Fontsets are collections of fonts + that cover the whole spectrum of characters. +* Defining Fontsets:: Defining a new fontset. +* Single-Byte European Support:: + You can pick one European character set + to use without multibyte characters. +@end menu + +@node International Intro +@section Introduction to International Character Sets + + The users of these scripts have established many more-or-less standard +coding systems for storing files. Emacs internally uses a single +multibyte character encoding, so that it can intermix characters from +all these scripts in a single buffer or string. This encoding +represents each non-ASCII character as a sequence of bytes in the range +0200 through 0377. Emacs translates between the multibyte character +encoding and various other coding systems when reading and writing +files, when exchanging data with subprocesses, and (in some cases) in +the @kbd{C-q} command (@pxref{Multibyte Conversion}). + +@kindex C-h h +@findex view-hello-file + The command @kbd{C-h h} (@code{view-hello-file}) displays the file +@file{etc/HELLO}, which shows how to say ``hello'' in many languages. +This illustrates various scripts. + + Keyboards, even in the countries where these character sets are used, +generally don't have keys for all the characters in them. So Emacs +supports various @dfn{input methods}, typically one for each script or +language, to make it convenient to type them. + +@kindex C-x RET + The prefix key @kbd{C-x @key{RET}} is used for commands that pertain +to multibyte characters, coding systems, and input methods. + +@node Enabling Multibyte +@section Enabling Multibyte Characters + + You can enable or disable multibyte character support, either for +Emacs as a whole, or for a single buffer. When multibyte characters are +disabled in a buffer, then each byte in that buffer represents a +character, even codes 0200 through 0377. The old features for +supporting the European character sets, ISO Latin-1 and ISO Latin-2, +work as they did in Emacs 19 and also work for the other ISO 8859 +character sets. + + However, there is no need to turn off multibyte character support to +use ISO Latin; the Emacs multibyte character set includes all the +characters in these character sets, and Emacs can translate +automatically to and from the ISO codes. + + To edit a particular file in unibyte representation, visit it using +@code{find-file-literally}. @xref{Visiting}. To convert a buffer in +multibyte representation into a single-byte representation of the same +characters, the easiest way is to save the contents in a file, kill the +buffer, and find the file again with @code{find-file-literally}. You +can also use @kbd{C-x @key{RET} c} +(@code{universal-coding-system-argument}) and specify @samp{raw-text} as +the coding system with which to find or save a file. @xref{Specify +Coding}. Finding a file as @samp{raw-text} doesn't disable format +conversion, uncompression and auto mode selection as +@code{find-file-literally} does. + +@vindex enable-multibyte-characters +@vindex default-enable-multibyte-characters + To turn off multibyte character support by default, start Emacs with +the @samp{--unibyte} option (@pxref{Initial Options}), or set the +environment variable @samp{EMACS_UNIBYTE}. You can also customize +@code{enable-multibyte-characters} or, equivalently, directly set the +variable @code{default-enable-multibyte-characters} in your init file to +have basically the same effect as @samp{--unibyte}. + + Multibyte strings are not created during initialization from the +values of environment variables, @file{/etc/passwd} entries etc.@: that +contain non-ASCII 8-bit characters. However, the initialization file is +normally read as multibyte---like Lisp files in general---even with +@samp{--unibyte}. To avoid multibyte strings being generated by +non-ASCII characters in it, put @samp{-*-unibyte: t;-*-} in a comment on +the first line. Do the same for initialization files for packages like +Gnus. + + The mode line indicates whether multibyte character support is enabled +in the current buffer. If it is, there are two or more characters (most +often two dashes) before the colon near the beginning of the mode line. +When multibyte characters are not enabled, just one dash precedes the +colon. + +@node Language Environments +@section Language Environments +@cindex language environments + + All supported character sets are supported in Emacs buffers whenever +multibyte characters are enabled; there is no need to select a +particular language in order to display its characters in an Emacs +buffer. However, it is important to select a @dfn{language environment} +in order to set various defaults. The language environment really +represents a choice of preferred script (more or less) rather than a +choice of language. + + The language environment controls which coding systems to recognize +when reading text (@pxref{Recognize Coding}). This applies to files, +incoming mail, netnews, and any other text you read into Emacs. It may +also specify the default coding system to use when you create a file. +Each language environment also specifies a default input method. + +@findex set-language-environment + The way to select a language environment is with the command @kbd{M-x +set-language-environment}. It makes no difference which buffer is +current when you use this command, because the effects apply globally to +the Emacs session. The supported language environments include: + +@quotation +Chinese-BIG5, Chinese-CNS, Chinese-GB, Cyrillic-Alternativnyj, +Cyrillic-ISO, Cyrillic-KOI8, Devanagari, English, Ethiopic, Greek, +Hebrew, Japanese, Korean, Lao, Latin-1, Latin-2, Latin-3, Latin-4, +Latin-5, Thai, Tibetan, and Vietnamese. +@end quotation + + Some operating systems let you specify the language you are using by +setting locale environment variables. Emacs handles one common special +case of this: if your locale name for character types contains the +string @samp{8859-@var{n}}, Emacs automatically selects the +corresponding language environment. + +@kindex C-h L +@findex describe-language-environment + To display information about the effects of a certain language +environment @var{lang-env}, use the command @kbd{C-h L @var{lang-env} +@key{RET}} (@code{describe-language-environment}). This tells you which +languages this language environment is useful for, and lists the +character sets, coding systems, and input methods that go with it. It +also shows some sample text to illustrate scripts used in this language +environment. By default, this command describes the chosen language +environment. + +@vindex set-language-environment-hook + You can customize any language environment with the normal hook +@code{set-language-environment-hook}. The command +@code{set-language-environment} runs that hook after setting up the new +language environment. The hook functions can test for a specific +language environment by checking the variable +@code{current-language-environment}. + +@vindex exit-language-environment-hook + Before it starts to set up the new language environment, +@code{set-language-environment} first runs the hook +@code{exit-language-environment-hook}. This hook is useful for undoing +customizations that were made with @code{set-language-environment-hook}. +For instance, if you set up a special key binding in a specific language +environment using @code{set-language-environment-hook}, you should set +up @code{exit-language-environment-hook} to restore the normal binding +for that key. + +@node Input Methods +@section Input Methods + +@cindex input methods + An @dfn{input method} is a kind of character conversion designed +specifically for interactive input. In Emacs, typically each language +has its own input method; sometimes several languages which use the same +characters can share one input method. A few languages support several +input methods. + + The simplest kind of input method works by mapping ASCII letters into +another alphabet. This is how the Greek and Russian input methods work. + + A more powerful technique is composition: converting sequences of +characters into one letter. Many European input methods use composition +to produce a single non-ASCII letter from a sequence that consists of a +letter followed by accent characters (or vice versa). For example, some +methods convert the sequence @kbd{a'} into a single accented letter. +These input methods have no special commands of their own; all they do +is compose sequences of printing characters. + + The input methods for syllabic scripts typically use mapping followed +by composition. The input methods for Thai and Korean work this way. +First, letters are mapped into symbols for particular sounds or tone +marks; then, sequences of these which make up a whole syllable are +mapped into one syllable sign. + + Chinese and Japanese require more complex methods. In Chinese input +methods, first you enter the phonetic spelling of a Chinese word (in +input method @code{chinese-py}, among others), or a sequence of portions +of the character (input methods @code{chinese-4corner} and +@code{chinese-sw}, and others). Since one phonetic spelling typically +corresponds to many different Chinese characters, you must select one of +the alternatives using special Emacs commands. Keys such as @kbd{C-f}, +@kbd{C-b}, @kbd{C-n}, @kbd{C-p}, and digits have special definitions in +this situation, used for selecting among the alternatives. @key{TAB} +displays a buffer showing all the possibilities. + + In Japanese input methods, first you input a whole word using +phonetic spelling; then, after the word is in the buffer, Emacs converts +it into one or more characters using a large dictionary. One phonetic +spelling corresponds to many differently written Japanese words, so you +must select one of them; use @kbd{C-n} and @kbd{C-p} to cycle through +the alternatives. + + Sometimes it is useful to cut off input method processing so that the +characters you have just entered will not combine with subsequent +characters. For example, in input method @code{latin-1-postfix}, the +sequence @kbd{e '} combines to form an @samp{e} with an accent. What if +you want to enter them as separate characters? + + One way is to type the accent twice; that is a special feature for +entering the separate letter and accent. For example, @kbd{e ' '} gives +you the two characters @samp{e'}. Another way is to type another letter +after the @kbd{e}---something that won't combine with that---and +immediately delete it. For example, you could type @kbd{e e @key{DEL} +'} to get separate @samp{e} and @samp{'}. + + Another method, more general but not quite as easy to type, is to use +@kbd{C-\ C-\} between two characters to stop them from combining. This +is the command @kbd{C-\} (@code{toggle-input-method}) used twice. +@ifinfo +@xref{Select Input Method}. +@end ifinfo + + @kbd{C-\ C-\} is especially useful inside an incremental search, +because it stops waiting for more characters to combine, and starts +searching for what you have already entered. + +@vindex input-method-verbose-flag +@vindex input-method-highlight-flag + The variables @code{input-method-highlight-flag} and +@code{input-method-verbose-flag} control how input methods explain what +is happening. If @code{input-method-highlight-flag} is non-@code{nil}, +the partial sequence is highlighted in the buffer. If +@code{input-method-verbose-flag} is non-@code{nil}, the list of possible +characters to type next is displayed in the echo area (but not when you +are in the minibuffer). + +@node Select Input Method +@section Selecting an Input Method + +@table @kbd +@item C-\ +Enable or disable use of the selected input method. + +@item C-x @key{RET} C-\ @var{method} @key{RET} +Select a new input method for the current buffer. + +@item C-h I @var{method} @key{RET} +@itemx C-h C-\ @var{method} @key{RET} +@findex describe-input-method +@kindex C-h I +@kindex C-h C-\ +Describe the input method @var{method} (@code{describe-input-method}). +By default, it describes the current input method (if any). +This description should give you the full details of how to +use any particular input method. + +@item M-x list-input-methods +Display a list of all the supported input methods. +@end table + +@findex set-input-method +@vindex current-input-method +@kindex C-x RET C-\ + To choose an input method for the current buffer, use @kbd{C-x +@key{RET} C-\} (@code{set-input-method}). This command reads the +input method name with the minibuffer; the name normally starts with the +language environment that it is meant to be used with. The variable +@code{current-input-method} records which input method is selected. + +@findex toggle-input-method +@kindex C-\ + Input methods use various sequences of ASCII characters to stand for +non-ASCII characters. Sometimes it is useful to turn off the input +method temporarily. To do this, type @kbd{C-\} +(@code{toggle-input-method}). To reenable the input method, type +@kbd{C-\} again. + + If you type @kbd{C-\} and you have not yet selected an input method, +it prompts for you to specify one. This has the same effect as using +@kbd{C-x @key{RET} C-\} to specify an input method. + +@vindex default-input-method + Selecting a language environment specifies a default input method for +use in various buffers. When you have a default input method, you can +select it in the current buffer by typing @kbd{C-\}. The variable +@code{default-input-method} specifies the default input method +(@code{nil} means there is none). + +@findex quail-set-keyboard-layout + Some input methods for alphabetic scripts work by (in effect) +remapping the keyboard to emulate various keyboard layouts commonly used +for those scripts. How to do this remapping properly depends on your +actual keyboard layout. To specify which layout your keyboard has, use +the command @kbd{M-x quail-set-keyboard-layout}. + +@findex list-input-methods + To display a list of all the supported input methods, type @kbd{M-x +list-input-methods}. The list gives information about each input +method, including the string that stands for it in the mode line. + +@node Multibyte Conversion +@section Unibyte and Multibyte Non-ASCII characters + + When multibyte characters are enabled, character codes 0240 (octal) +through 0377 (octal) are not really legitimate in the buffer. The valid +non-ASCII printing characters have codes that start from 0400. + + If you type a self-inserting character in the invalid range 0240 +through 0377, Emacs assumes you intended to use one of the ISO +Latin-@var{n} character sets, and converts it to the Emacs code +representing that Latin-@var{n} character. You select @emph{which} ISO +Latin character set to use through your choice of language environment +@iftex +(see above). +@end iftex +@ifinfo +(@pxref{Language Environments}). +@end ifinfo +If you do not specify a choice, the default is Latin-1. + + The same thing happens when you use @kbd{C-q} to enter an octal code +in this range. + +@node Coding Systems +@section Coding Systems +@cindex coding systems + + Users of various languages have established many more-or-less standard +coding systems for representing them. Emacs does not use these coding +systems internally; instead, it converts from various coding systems to +its own system when reading data, and converts the internal coding +system to other coding systems when writing data. Conversion is +possible in reading or writing files, in sending or receiving from the +terminal, and in exchanging data with subprocesses. + + Emacs assigns a name to each coding system. Most coding systems are +used for one language, and the name of the coding system starts with the +language name. Some coding systems are used for several languages; +their names usually start with @samp{iso}. There are also special +coding systems @code{no-conversion}, @code{raw-text} and +@code{emacs-mule} which do not convert printing characters at all. + +@cindex end-of-line conversion + In addition to converting various representations of non-ASCII +characters, a coding system can perform end-of-line conversion. Emacs +handles three different conventions for how to separate lines in a file: +newline, carriage-return linefeed, and just carriage-return. + +@table @kbd +@item C-h C @var{coding} @key{RET} +Describe coding system @var{coding}. + +@item C-h C @key{RET} +Describe the coding systems currently in use. + +@item M-x list-coding-systems +Display a list of all the supported coding systems. +@end table + +@kindex C-h C +@findex describe-coding-system + The command @kbd{C-h C} (@code{describe-coding-system}) displays +information about particular coding systems. You can specify a coding +system name as argument; alternatively, with an empty argument, it +describes the coding systems currently selected for various purposes, +both in the current buffer and as the defaults, and the priority list +for recognizing coding systems (@pxref{Recognize Coding}). + +@findex list-coding-systems + To display a list of all the supported coding systems, type @kbd{M-x +list-coding-systems}. The list gives information about each coding +system, including the letter that stands for it in the mode line +(@pxref{Mode Line}). + +@cindex end-of-line conversion +@cindex MS-DOS end-of-line conversion +@cindex Macintosh end-of-line conversion + Each of the coding systems that appear in this list---except for +@code{no-conversion}, which means no conversion of any kind---specifies +how and whether to convert printing characters, but leaves the choice of +end-of-line conversion to be decided based on the contents of each file. +For example, if the file appears to use the sequence carriage-return +linefeed to separate lines, DOS end-of-line conversion will be used. + + Each of the listed coding systems has three variants which specify +exactly what to do for end-of-line conversion: + +@table @code +@item @dots{}-unix +Don't do any end-of-line conversion; assume the file uses +newline to separate lines. (This is the convention normally used +on Unix and GNU systems.) + +@item @dots{}-dos +Assume the file uses carriage-return linefeed to separate lines, and do +the appropriate conversion. (This is the convention normally used on +Microsoft systems.@footnote{It is also specified for MIME `text/*' +bodies and in other network transport contexts. It is different +from the SGML reference syntax record-start/record-end format which +Emacs doesn't support directly.}) + +@item @dots{}-mac +Assume the file uses carriage-return to separate lines, and do the +appropriate conversion. (This is the convention normally used on the +Macintosh system.) +@end table + + These variant coding systems are omitted from the +@code{list-coding-systems} display for brevity, since they are entirely +predictable. For example, the coding system @code{iso-latin-1} has +variants @code{iso-latin-1-unix}, @code{iso-latin-1-dos} and +@code{iso-latin-1-mac}. + + The coding system @code{raw-text} is good for a file which is mainly +ASCII text, but may contain byte values above 127 which are not meant to +encode non-ASCII characters. With @code{raw-text}, Emacs copies those +byte values unchanged, and sets @code{enable-multibyte-characters} to +@code{nil} in the current buffer so that they will be interpreted +properly. @code{raw-text} handles end-of-line conversion in the usual +way, based on the data encountered, and has the usual three variants to +specify the kind of end-of-line conversion to use. + + In contrast, the coding system @code{no-conversion} specifies no +character code conversion at all---none for non-ASCII byte values and +none for end of line. This is useful for reading or writing binary +files, tar files, and other files that must be examined verbatim. It, +too, sets @code{enable-multibyte-characters} to @code{nil}. + + The easiest way to edit a file with no conversion of any kind is with +the @kbd{M-x find-file-literally} command. This uses +@code{no-conversion}, and also suppresses other Emacs features that +might convert the file contents before you see them. @xref{Visiting}. + + The coding system @code{emacs-mule} means that the file contains +non-ASCII characters stored with the internal Emacs encoding. It +handles end-of-line conversion based on the data encountered, and has +the usual three variants to specify the kind of end-of-line conversion. + +@node Recognize Coding +@section Recognizing Coding Systems + + Most of the time, Emacs can recognize which coding system to use for +any given file---once you have specified your preferences. + + Some coding systems can be recognized or distinguished by which byte +sequences appear in the data. However, there are coding systems that +cannot be distinguished, not even potentially. For example, there is no +way to distinguish between Latin-1 and Latin-2; they use the same byte +values with different meanings. + + Emacs handles this situation by means of a priority list of coding +systems. Whenever Emacs reads a file, if you do not specify the coding +system to use, Emacs checks the data against each coding system, +starting with the first in priority and working down the list, until it +finds a coding system that fits the data. Then it converts the file +contents assuming that they are represented in this coding system. + + The priority list of coding systems depends on the selected language +environment (@pxref{Language Environments}). For example, if you use +French, you probably want Emacs to prefer Latin-1 to Latin-2; if you use +Czech, you probably want Latin-2 to be preferred. This is one of the +reasons to specify a language environment. + +@findex prefer-coding-system + However, you can alter the priority list in detail with the command +@kbd{M-x prefer-coding-system}. This command reads the name of a coding +system from the minibuffer, and adds it to the front of the priority +list, so that it is preferred to all others. If you use this command +several times, each use adds one element to the front of the priority +list. + + If you use a coding system that specifies the end-of-line conversion +type, such as @code{iso-8859-1-dos}, what that means is that Emacs +should attempt to recognize @code{iso-8859-1} with priority, and should +use DOS end-of-line conversion in case it recognizes @code{iso-8859-1}. + +@vindex file-coding-system-alist + Sometimes a file name indicates which coding system to use for the +file. The variable @code{file-coding-system-alist} specifies this +correspondence. There is a special function +@code{modify-coding-system-alist} for adding elements to this list. For +example, to read and write all @samp{.txt} files using the coding system +@code{china-iso-8bit}, you can execute this Lisp expression: + +@smallexample +(modify-coding-system-alist 'file "\\.txt\\'" 'china-iso-8bit) +@end smallexample + +@noindent +The first argument should be @code{file}, the second argument should be +a regular expression that determines which files this applies to, and +the third argument says which coding system to use for these files. + +@vindex inhibit-eol-conversion + Emacs recognizes which kind of end-of-line conversion to use based on +the contents of the file: if it sees only carriage-returns, or only +carriage-return linefeed sequences, then it chooses the end-of-line +conversion accordingly. You can inhibit the automatic use of +end-of-line conversion by setting the variable @code{inhibit-eol-conversion} +to non-@code{nil}. + +@vindex coding + You can specify the coding system for a particular file using the +@samp{-*-@dots{}-*-} construct at the beginning of a file, or a local +variables list at the end (@pxref{File Variables}). You do this by +defining a value for the ``variable'' named @code{coding}. Emacs does +not really have a variable @code{coding}; instead of setting a variable, +it uses the specified coding system for the file. For example, +@samp{-*-mode: C; coding: latin-1;-*-} specifies use of the Latin-1 +coding system, as well as C mode. If you specify the coding explicitly +in the file, that overrides @code{file-coding-system-alist}. + +@vindex auto-coding-alist + The variable @code{auto-coding-alist} is the strongest way to specify +the coding system for certain patterns of file names; this variable even +overrides @samp{-*-coding:-*-} tags in the file itself. Emacs uses this +feature for tar and archive files, to prevent Emacs from being confused +by a @samp{-*-coding:-*-} tag in a member of the archive and thinking it +applies to the archive file as a whole. + +@vindex buffer-file-coding-system + Once Emacs has chosen a coding system for a buffer, it stores that +coding system in @code{buffer-file-coding-system} and uses that coding +system, by default, for operations that write from this buffer into a +file. This includes the commands @code{save-buffer} and +@code{write-region}. If you want to write files from this buffer using +a different coding system, you can specify a different coding system for +the buffer using @code{set-buffer-file-coding-system} (@pxref{Specify +Coding}). + +@vindex sendmail-coding-system + When you send a message with Mail mode (@pxref{Sending Mail}), Emacs has +four different ways to determine the coding system to use for encoding +the message text. It tries the buffer's own value of +@code{buffer-file-coding-system}, if that is non-@code{nil}. Otherwise, +it uses the value of @code{sendmail-coding-system}, if that is +non-@code{nil}. The third way is to use the default coding system for +new files, which is controlled by your choice of language environment, +if that is non-@code{nil}. If all of these three values are @code{nil}, +Emacs encodes outgoing mail using the Latin-1 coding system. + +@vindex rmail-decode-mime-charset + When you get new mail in Rmail, each message is translated +automatically from the coding system it is written in---as if it were a +separate file. This uses the priority list of coding systems that you +have specified. If a MIME message specifies a character set, Rmail +obeys that specification, unless @code{rmail-decode-mime-charset} is +@code{nil}. + +@vindex rmail-file-coding-system + For reading and saving Rmail files themselves, Emacs uses the coding +system specified by the variable @code{rmail-file-coding-system}. The +default value is @code{nil}, which means that Rmail files are not +translated (they are read and written in the Emacs internal character +code). + +@node Specify Coding +@section Specifying a Coding System + + In cases where Emacs does not automatically choose the right coding +system, you can use these commands to specify one: + +@table @kbd +@item C-x @key{RET} f @var{coding} @key{RET} +Use coding system @var{coding} for the visited file +in the current buffer. + +@item C-x @key{RET} c @var{coding} @key{RET} +Specify coding system @var{coding} for the immediately following +command. + +@item C-x @key{RET} k @var{coding} @key{RET} +Use coding system @var{coding} for keyboard input. + +@item C-x @key{RET} t @var{coding} @key{RET} +Use coding system @var{coding} for terminal output. + +@item C-x @key{RET} p @var{input-coding} @key{RET} @var{output-coding} @key{RET} +Use coding systems @var{input-coding} and @var{output-coding} for +subprocess input and output in the current buffer. + +@item C-x @key{RET} x @var{coding} @key{RET} +Use coding system @var{coding} for transferring selections to and from +other programs through the window system. + +@item C-x @key{RET} X @var{coding} @key{RET} +Use coding system @var{coding} for transferring @emph{one} +selection---the next one---to or from the window system. +@end table + +@kindex C-x RET f +@findex set-buffer-file-coding-system + The command @kbd{C-x @key{RET} f} (@code{set-buffer-file-coding-system}) +specifies the file coding system for the current buffer---in other +words, which coding system to use when saving or rereading the visited +file. You specify which coding system using the minibuffer. Since this +command applies to a file you have already visited, it affects only the +way the file is saved. + +@kindex C-x RET c +@findex universal-coding-system-argument + Another way to specify the coding system for a file is when you visit +the file. First use the command @kbd{C-x @key{RET} c} +(@code{universal-coding-system-argument}); this command uses the +minibuffer to read a coding system name. After you exit the minibuffer, +the specified coding system is used for @emph{the immediately following +command}. + + So if the immediately following command is @kbd{C-x C-f}, for example, +it reads the file using that coding system (and records the coding +system for when the file is saved). Or if the immediately following +command is @kbd{C-x C-w}, it writes the file using that coding system. +Other file commands affected by a specified coding system include +@kbd{C-x C-i} and @kbd{C-x C-v}, as well as the other-window variants of +@kbd{C-x C-f}. + + @kbd{C-x @key{RET} c} also affects commands that start subprocesses, +including @kbd{M-x shell} (@pxref{Shell}). + + However, if the immediately following command does not use the coding +system, then @kbd{C-x @key{RET} c} ultimately has no effect. + + An easy way to visit a file with no conversion is with the @kbd{M-x +find-file-literally} command. @xref{Visiting}. + +@vindex default-buffer-file-coding-system + The variable @code{default-buffer-file-coding-system} specifies the +choice of coding system to use when you create a new file. It applies +when you find a new file, and when you create a buffer and then save it +in a file. Selecting a language environment typically sets this +variable to a good choice of default coding system for that language +environment. + +@kindex C-x RET t +@findex set-terminal-coding-system + The command @kbd{C-x @key{RET} t} (@code{set-terminal-coding-system}) +specifies the coding system for terminal output. If you specify a +character code for terminal output, all characters output to the +terminal are translated into that coding system. + + This feature is useful for certain character-only terminals built to +support specific languages or character sets---for example, European +terminals that support one of the ISO Latin character sets. You need to +specify the terminal coding system when using multibyte text, so that +Emacs knows which characters the terminal can actually handle. + + By default, output to the terminal is not translated at all, unless +Emacs can deduce the proper coding system from your terminal type. + +@kindex C-x RET k +@findex set-keyboard-coding-system + The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system}) +specifies the coding system for keyboard input. Character-code +translation of keyboard input is useful for terminals with keys that +send non-ASCII graphic characters---for example, some terminals designed +for ISO Latin-1 or subsets of it. + + By default, keyboard input is not translated at all. + + There is a similarity between using a coding system translation for +keyboard input, and using an input method: both define sequences of +keyboard input that translate into single characters. However, input +methods are designed to be convenient for interactive use by humans, and +the sequences that are translated are typically sequences of ASCII +printing characters. Coding systems typically translate sequences of +non-graphic characters. + +@kindex C-x RET x +@kindex C-x RET X +@findex set-selection-coding-system +@findex set-next-selection-coding-system + The command @kbd{C-x @key{RET} x} (@code{set-selection-coding-system}) +specifies the coding system for sending selected text to the window +system, and for receiving the text of selections made in other +applications. This command applies to all subsequent selections, until +you override it by using the command again. The command @kbd{C-x +@key{RET} X} (@code{set-next-selection-coding-system}) specifies the +coding system for the next selection made in Emacs or read by Emacs. + +@kindex C-x RET p +@findex set-buffer-process-coding-system + The command @kbd{C-x @key{RET} p} (@code{set-buffer-process-coding-system}) +specifies the coding system for input and output to a subprocess. This +command applies to the current buffer; normally, each subprocess has its +own buffer, and thus you can use this command to specify translation to +and from a particular subprocess by giving the command in the +corresponding buffer. + + By default, process input and output are not translated at all. + +@vindex file-name-coding-system + The variable @code{file-name-coding-system} specifies a coding system +to use for encoding file names. If you set the variable to a coding +system name (as a Lisp symbol or a string), Emacs encodes file names +using that coding system for all file operations. This makes it +possible to use non-ASCII characters in file names---or, at least, those +non-ASCII characters which the specified coding system can encode. + + If @code{file-name-coding-system} is @code{nil}, Emacs uses a default +coding system determined by the selected language environment. In the +default language environment, any non-ASCII characters in file names are +not encoded specially; they appear in the file system using the internal +Emacs representation. + + @strong{Warning:} if you change @code{file-name-coding-system} (or the +language environment) in the middle of an Emacs session, problems can +result if you have already visited files whose names were encoded using +the earlier coding system and cannot be encoded (or are encoded +differently) under the new coding system. If you try to save one of +these buffers under the visited file name, saving may use the wrong file +name, or it may get an error. If such a problem happens, use @kbd{C-x +C-w} to specify a new file name for that buffer. + +@node Fontsets +@section Fontsets +@cindex fontsets + + A font for X Windows typically defines shapes for one alphabet or +script. Therefore, displaying the entire range of scripts that Emacs +supports requires a collection of many fonts. In Emacs, such a +collection is called a @dfn{fontset}. A fontset is defined by a list of +fonts, each assigned to handle a range of character codes. + + Each fontset has a name, like a font. The available X fonts are +defined by the X server; fontsets, however, are defined within Emacs +itself. Once you have defined a fontset, you can use it within Emacs by +specifying its name, anywhere that you could use a single font. Of +course, Emacs fontsets can use only the fonts that the X server +supports; if certain characters appear on the screen as hollow boxes, +this means that the fontset in use for them has no font for those +characters. + + Emacs creates two fontsets automatically: the @dfn{standard fontset} +and the @dfn{startup fontset}. The standard fontset is most likely to +have fonts for a wide variety of non-ASCII characters; however, this is +not the default for Emacs to use. (By default, Emacs tries to find a +font which has bold and italic variants.) You can specify use of the +standard fontset with the @samp{-fn} option, or with the @samp{Font} X +resource (@pxref{Font X}). For example, + +@example +emacs -fn fontset-standard +@end example + + A fontset does not necessarily specify a font for every character +code. If a fontset specifies no font for a certain character, or if it +specifies a font that does not exist on your system, then it cannot +display that character properly. It will display that character as an +empty box instead. + +@vindex highlight-wrong-size-font + The fontset height and width are determined by the ASCII characters +(that is, by the font used for ASCII characters in that fontset). If +another font in the fontset has a different height, or a different +width, then characters assigned to that font are clipped to the +fontset's size. If @code{highlight-wrong-size-font} is non-@code{nil}, +a box is displayed around these wrong-size characters as well. + +@node Defining Fontsets +@section Defining fontsets + +@vindex standard-fontset-spec +@cindex standard fontset + Emacs creates a standard fontset automatically according to the value +of @code{standard-fontset-spec}. This fontset's name is + +@example +-*-fixed-medium-r-normal-*-16-*-*-*-*-*-fontset-standard +@end example + +@noindent +or just @samp{fontset-standard} for short. + + Bold, italic, and bold-italic variants of the standard fontset are +created automatically. Their names have @samp{bold} instead of +@samp{medium}, or @samp{i} instead of @samp{r}, or both. + +@cindex startup fontset + If you specify a default ASCII font with the @samp{Font} resource or +the @samp{-fn} argument, Emacs generates a fontset from it +automatically. This is the @dfn{startup fontset} and its name is +@code{fontset-startup}. It does this by replacing the @var{foundry}, +@var{family}, @var{add_style}, and @var{average_width} fields of the +font name with @samp{*}, replacing @var{charset_registry} field with +@samp{fontset}, and replacing @var{charset_encoding} field with +@samp{startup}, then using the resulting string to specify a fontset. + + For instance, if you start Emacs this way, + +@example +emacs -fn "*courier-medium-r-normal--14-140-*-iso8859-1" +@end example + +@noindent +Emacs generates the following fontset and uses it for the initial X +window frame: + +@example +-*-*-medium-r-normal-*-14-140-*-*-*-*-fontset-startup +@end example + + With the X resource @samp{Emacs.Font}, you can specify a fontset name +just like an actual font name. But be careful not to specify a fontset +name in a wildcard resource like @samp{Emacs*Font}---that wildcard +specification applies to various other purposes, such as menus, and +menus cannot handle fontsets. + + You can specify additional fontsets using X resources named +@samp{Fontset-@var{n}}, where @var{n} is an integer starting from 0. +The resource value should have this form: + +@smallexample +@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}} +@end smallexample + +@noindent +@var{fontpattern} should have the form of a standard X font name, except +for the last two fields. They should have the form +@samp{fontset-@var{alias}}. + + The fontset has two names, one long and one short. The long name is +@var{fontpattern}. The short name is @samp{fontset-@var{alias}}. You +can refer to the fontset by either name. + + The construct @samp{@var{charset}:@var{font}} specifies which font to +use (in this fontset) for one particular character set. Here, +@var{charset} is the name of a character set, and @var{font} is the +font to use for that character set. You can use this construct any +number of times in defining one fontset. + + For the other character sets, Emacs chooses a font based on +@var{fontpattern}. It replaces @samp{fontset-@var{alias}} with values +that describe the character set. For the ASCII character font, +@samp{fontset-@var{alias}} is replaced with @samp{ISO8859-1}. + + In addition, when several consecutive fields are wildcards, Emacs +collapses them into a single wildcard. This is to prevent use of +auto-scaled fonts. Fonts made by scaling larger fonts are not usable +for editing, and scaling a smaller font is not useful because it is +better to use the smaller font in its own size, which Emacs does. + + Thus if @var{fontpattern} is this, + +@example +-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 +@end example + +@noindent +the font specification for ASCII characters would be this: + +@example +-*-fixed-medium-r-normal-*-24-*-ISO8859-1 +@end example + +@noindent +and the font specification for Chinese GB2312 characters would be this: + +@example +-*-fixed-medium-r-normal-*-24-*-gb2312*-* +@end example + + You may not have any Chinese font matching the above font +specification. Most X distributions include only Chinese fonts that +have @samp{song ti} or @samp{fangsong ti} in @var{family} field. In +such a case, @samp{Fontset-@var{n}} can be specified as below: + +@smallexample +Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\ + chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-* +@end smallexample + +@noindent +Then, the font specifications for all but Chinese GB2312 characters have +@samp{fixed} in the @var{family} field, and the font specification for +Chinese GB2312 characters has a wild card @samp{*} in the @var{family} +field. + +@findex create-fontset-from-fontset-spec + The function that processes the fontset resource value to create the +fontset is called @code{create-fontset-from-fontset-spec}. You can also +call this function explicitly to create a fontset. + + @xref{Font X}, for more information about font naming in X. + +@node Single-Byte European Support +@section Single-byte European Character Support + +@cindex European character sets +@cindex accented characters +@cindex ISO Latin character sets +@cindex Unibyte operation +@vindex enable-multibyte-characters + The ISO 8859 Latin-@var{n} character sets define character codes in +the range 160 to 255 to handle the accented letters and punctuation +needed by various European languages. If you disable multibyte +characters, Emacs can still handle @emph{one} of these character codes +at a time. To specify @emph{which} of these codes to use, invoke +@kbd{M-x set-language-environment} and specify a suitable language +environment such as @samp{Latin-@var{n}}. + + For more information about unibyte operation, see @ref{Enabling +Multibyte}. Note particularly that you probably want to ensure that +your initialization files are read as unibyte if they contain non-ASCII +characters. + +@vindex unibyte-display-via-language-environment + Emacs can also display those characters, provided the terminal or font +in use supports them. This works automatically. Alternatively, if you +are using a window system, Emacs can also display single-byte characters +through fontsets, in effect by displaying the equivalent multibyte +characters according to the current language environment. To request +this, set the variable @code{unibyte-display-via-language-environment} +to a non-@code{nil} value. + +@cindex @code{iso-ascii} library + If your terminal does not support display of the Latin-1 character +set, Emacs can display these characters as ASCII sequences which at +least give you a clear idea of what the characters are. To do this, +load the library @code{iso-ascii}. Similar libraries for other +Latin-@var{n} character sets could be implemented, but we don't have +them yet. + +@findex standard-display-8bit +@cindex 8-bit display + Normally non-ISO-8859 characters (between characters 128 and 159 +inclusive) are displayed as octal escapes. You can change this for +non-standard `extended' versions of ISO-8859 character sets by using the +function @code{standard-display-8bit} in the @code{disp-table} library. + + There are three different ways you can input single-byte non-ASCII +characters: + +@itemize @bullet +@item +If your keyboard can generate character codes 128 and up, representing +non-ASCII characters, execute the following expression to enable Emacs to +understand them: + +@example +(set-input-mode (car (current-input-mode)) + (nth 1 (current-input-mode)) + 0) +@end example + +@item +You can use an input method for the selected language environment. +@xref{Input Methods}. When you use an input method in a unibyte buffer, +the non-ASCII character you specify with it is converted to unibyte. + +@kindex C-x 8 +@cindex @code{iso-transl} library +@item +For Latin-1 only, you can use the +key @kbd{C-x 8} as a ``compose character'' prefix for entry of +non-ASCII Latin-1 printing characters. @kbd{C-x 8} is good for +insertion (in the minibuffer as well as other buffers), for searching, +and in any other context where a key sequence is allowed. + +@kbd{C-x 8} works by loading the @code{iso-transl} library. Once that +library is loaded, the @key{ALT} modifier key, if you have one, serves +the same purpose as @kbd{C-x 8}; use @key{ALT} together with an accent +character to modify the following letter. In addition, if you have keys +for the Latin-1 ``dead accent characters'', they too are defined to +compose with the following character, once @code{iso-transl} is loaded. +@end itemize diff --git a/man/picture.texi b/man/picture.texi new file mode 100644 index 00000000000..f16d5007d9a --- /dev/null +++ b/man/picture.texi @@ -0,0 +1,263 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Picture, Sending Mail, Abbrevs, Top +@chapter Editing Pictures +@cindex pictures +@cindex making pictures out of text characters +@findex edit-picture + + To edit a picture made out of text characters (for example, a picture +of the division of a register into fields, as a comment in a program), +use the command @kbd{M-x edit-picture} to enter Picture mode. + + In Picture mode, editing is based on the @dfn{quarter-plane} model of +text, according to which the text characters lie studded on an area that +stretches infinitely far to the right and downward. The concept of the end +of a line does not exist in this model; the most you can say is where the +last nonblank character on the line is found. + + Of course, Emacs really always considers text as a sequence of +characters, and lines really do have ends. But Picture mode replaces +the most frequently-used commands with variants that simulate the +quarter-plane model of text. They do this by inserting spaces or by +converting tabs to spaces. + + Most of the basic editing commands of Emacs are redefined by Picture mode +to do essentially the same thing but in a quarter-plane way. In addition, +Picture mode defines various keys starting with the @kbd{C-c} prefix to +run special picture editing commands. + + One of these keys, @kbd{C-c C-c}, is pretty important. Often a +picture is part of a larger file that is usually edited in some other +major mode. @kbd{M-x edit-picture} records the name of the previous +major mode so you can use the @kbd{C-c C-c} command +(@code{picture-mode-exit}) later to go back to that mode. @kbd{C-c C-c} +also deletes spaces from the ends of lines, unless given a numeric +argument. + + The special commands of Picture mode all work in other modes (provided +the @file{picture} library is loaded), but are not bound to keys except +in Picture mode. The descriptions below talk of moving ``one column'' +and so on, but all the picture mode commands handle numeric arguments as +their normal equivalents do. + +@vindex picture-mode-hook + Turning on Picture mode runs the hook @code{picture-mode-hook} +(@pxref{Hooks}). + +@menu +* Basic Picture:: Basic concepts and simple commands of Picture Mode. +* Insert in Picture:: Controlling direction of cursor motion + after "self-inserting" characters. +* Tabs in Picture:: Various features for tab stops and indentation. +* Rectangles in Picture:: Clearing and superimposing rectangles. +@end menu + +@node Basic Picture, Insert in Picture, Picture, Picture +@section Basic Editing in Picture Mode + +@findex picture-forward-column +@findex picture-backward-column +@findex picture-move-down +@findex picture-move-up +@cindex editing in Picture mode + + Most keys do the same thing in Picture mode that they usually do, but +do it in a quarter-plane style. For example, @kbd{C-f} is rebound to +run @code{picture-forward-column}, a command which moves point one +column to the right, inserting a space if necessary so that the actual +end of the line makes no difference. @kbd{C-b} is rebound to run +@code{picture-backward-column}, which always moves point left one +column, converting a tab to multiple spaces if necessary. @kbd{C-n} and +@kbd{C-p} are rebound to run @code{picture-move-down} and +@code{picture-move-up}, which can either insert spaces or convert tabs +as necessary to make sure that point stays in exactly the same column. +@kbd{C-e} runs @code{picture-end-of-line}, which moves to after the last +nonblank character on the line. There is no need to change @kbd{C-a}, +as the choice of screen model does not affect beginnings of +lines. + +@findex picture-newline + Insertion of text is adapted to the quarter-plane screen model through +the use of Overwrite mode (@pxref{Minor Modes}). Self-inserting characters +replace existing text, column by column, rather than pushing existing text +to the right. @key{RET} runs @code{picture-newline}, which just moves to +the beginning of the following line so that new text will replace that +line. + +@findex picture-backward-clear-column +@findex picture-clear-column +@findex picture-clear-line + Picture mode provides erasure instead of deletion and killing of +text. @key{DEL} (@code{picture-backward-clear-column}) replaces the +preceding character with a space rather than removing it; this moves +point backwards. @kbd{C-d} (@code{picture-clear-column}) replaces the +next character or characters with spaces, but does not move point. (If +you want to clear characters to spaces and move forward over them, use +@key{SPC}.) @kbd{C-k} (@code{picture-clear-line}) really kills the +contents of lines, but does not delete the newlines from the +buffer. + +@findex picture-open-line + To do actual insertion, you must use special commands. @kbd{C-o} +(@code{picture-open-line}) creates a blank line after the current line; +it never splits a line. @kbd{C-M-o} (@code{split-line}) makes sense in +Picture mode, so it is not changed. @kbd{C-j} +(@code{picture-duplicate-line}) inserts below the current line another +line with the same contents.@refill + +@kindex C-c C-d @r{(Picture mode)} + To do actual deletion in Picture mode, use @kbd{C-w}, @kbd{C-c C-d} +(which is defined as @code{delete-char}, as @kbd{C-d} is in other +modes), or one of the picture rectangle commands (@pxref{Rectangles in +Picture}). + +@node Insert in Picture, Tabs in Picture, Basic Picture, Picture +@section Controlling Motion after Insert + +@findex picture-movement-up +@findex picture-movement-down +@findex picture-movement-left +@findex picture-movement-right +@findex picture-movement-nw +@findex picture-movement-ne +@findex picture-movement-sw +@findex picture-movement-se +@kindex C-c < @r{(Picture mode)} +@kindex C-c > @r{(Picture mode)} +@kindex C-c ^ @r{(Picture mode)} +@kindex C-c . @r{(Picture mode)} +@kindex C-c ` @r{(Picture mode)} +@kindex C-c ' @r{(Picture mode)} +@kindex C-c / @r{(Picture mode)} +@kindex C-c \ @r{(Picture mode)} + Since ``self-inserting'' characters in Picture mode overwrite and move +point, there is no essential restriction on how point should be moved. +Normally point moves right, but you can specify any of the eight +orthogonal or diagonal directions for motion after a ``self-inserting'' +character. This is useful for drawing lines in the buffer. + +@table @kbd +@item C-c < +Move left after insertion (@code{picture-movement-left}). +@item C-c > +Move right after insertion (@code{picture-movement-right}). +@item C-c ^ +Move up after insertion (@code{picture-movement-up}). +@item C-c . +Move down after insertion (@code{picture-movement-down}). +@item C-c ` +Move up and left (``northwest'') after insertion (@code{picture-movement-nw}). +@item C-c ' +Move up and right (``northeast'') after insertion +(@code{picture-movement-ne}). +@item C-c / +Move down and left (``southwest'') after insertion +@*(@code{picture-movement-sw}). +@item C-c \ +Move down and right (``southeast'') after insertion +@*(@code{picture-movement-se}). +@end table + +@kindex C-c C-f @r{(Picture mode)} +@kindex C-c C-b @r{(Picture mode)} +@findex picture-motion +@findex picture-motion-reverse + Two motion commands move based on the current Picture insertion +direction. The command @kbd{C-c C-f} (@code{picture-motion}) moves in the +same direction as motion after ``insertion'' currently does, while @kbd{C-c +C-b} (@code{picture-motion-reverse}) moves in the opposite direction. + +@node Tabs in Picture, Rectangles in Picture, Insert in Picture, Picture +@section Picture Mode Tabs + +@kindex M-TAB @r{(Picture mode)} +@findex picture-tab-search +@vindex picture-tab-chars + Two kinds of tab-like action are provided in Picture mode. Use +@kbd{M-@key{TAB}} (@code{picture-tab-search}) for context-based tabbing. +With no argument, it moves to a point underneath the next +``interesting'' character that follows whitespace in the previous +nonblank line. ``Next'' here means ``appearing at a horizontal position +greater than the one point starts out at.'' With an argument, as in +@kbd{C-u M-@key{TAB}}, this command moves to the next such interesting +character in the current line. @kbd{M-@key{TAB}} does not change the +text; it only moves point. ``Interesting'' characters are defined by +the variable @code{picture-tab-chars}, which should define a set of +characters. The syntax for this variable is like the syntax used inside +of @samp{[@dots{}]} in a regular expression---but without the @samp{[} +and the @samp{]}. Its default value is @code{"!-~"}. + +@findex picture-tab + @key{TAB} itself runs @code{picture-tab}, which operates based on the +current tab stop settings; it is the Picture mode equivalent of +@code{tab-to-tab-stop}. Normally it just moves point, but with a numeric +argument it clears the text that it moves over. + +@kindex C-c TAB @r{(Picture mode)} +@findex picture-set-tab-stops + The context-based and tab-stop-based forms of tabbing are brought +together by the command @kbd{C-c @key{TAB}} (@code{picture-set-tab-stops}). +This command sets the tab stops to the positions which @kbd{M-@key{TAB}} +would consider significant in the current line. The use of this command, +together with @key{TAB}, can get the effect of context-based tabbing. But +@kbd{M-@key{TAB}} is more convenient in the cases where it is sufficient. + + It may be convenient to prevent use of actual tab characters in +pictures. For example, this prevents @kbd{C-x @key{TAB}} from messing +up the picture. You can do this by setting the variable +@code{indent-tabs-mode} to @code{nil}. @xref{Just Spaces}. + +@node Rectangles in Picture,, Tabs in Picture, Picture +@section Picture Mode Rectangle Commands +@cindex rectangles and Picture mode +@cindex Picture mode and rectangles + + Picture mode defines commands for working on rectangular pieces of the +text in ways that fit with the quarter-plane model. The standard rectangle +commands may also be useful (@pxref{Rectangles}). + +@table @kbd +@item C-c C-k +Clear out the region-rectangle with spaces +(@code{picture-clear-rectangle}). With argument, delete the text. +@item C-c C-w @var{r} +Similar but save rectangle contents in register @var{r} first +(@code{picture-clear-rectangle-to-register}). +@item C-c C-y +Copy last killed rectangle into the buffer by overwriting, with upper +left corner at point (@code{picture-yank-rectangle}). With argument, +insert instead. +@item C-c C-x @var{r} +Similar, but use the rectangle in register @var{r} +(@code{picture-yank-rectangle-from-register}). +@end table + +@kindex C-c C-k @r{(Picture mode)} +@kindex C-c C-w @r{(Picture mode)} +@findex picture-clear-rectangle +@findex picture-clear-rectangle-to-register + The picture rectangle commands @kbd{C-c C-k} +(@code{picture-clear-rectangle}) and @kbd{C-c C-w} +(@code{picture-clear-rectangle-to-register}) differ from the standard +rectangle commands in that they normally clear the rectangle instead of +deleting it; this is analogous with the way @kbd{C-d} is changed in Picture +mode. + + However, deletion of rectangles can be useful in Picture mode, so +these commands delete the rectangle if given a numeric argument. +@kbd{C-c C-k} either with or without a numeric argument saves the +rectangle for @kbd{C-c C-y}. + +@kindex C-c C-y @r{(Picture mode)} +@kindex C-c C-x @r{(Picture mode)} +@findex picture-yank-rectangle +@findex picture-yank-rectangle-from-register + The Picture mode commands for yanking rectangles differ from the +standard ones in overwriting instead of inserting. This is the same way +that Picture mode insertion of other text differs from other modes. +@kbd{C-c C-y} (@code{picture-yank-rectangle}) inserts (by overwriting) +the rectangle that was most recently killed, while @kbd{C-c C-x} +(@code{picture-yank-rectangle-from-register}) does likewise for the +rectangle found in a specified register. diff --git a/man/programs.texi b/man/programs.texi new file mode 100644 index 00000000000..573fd9d920b --- /dev/null +++ b/man/programs.texi @@ -0,0 +1,3341 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Programs, Building, Text, Top +@chapter Editing Programs +@cindex Lisp editing +@cindex C editing +@cindex program editing + + Emacs has many commands designed to understand the syntax of programming +languages such as Lisp and C. These commands can + +@itemize @bullet +@item +Move over or kill balanced expressions or @dfn{sexps} (@pxref{Lists}). +@item +Move over or mark top-level expressions---@dfn{defuns}, in Lisp; +functions, in C (@pxref{Defuns}). +@item +Show how parentheses balance (@pxref{Matching}). +@item +Insert, kill or align comments (@pxref{Comments}). +@item +Follow the usual indentation conventions of the language +(@pxref{Program Indent}). +@end itemize + + The commands for words, sentences and paragraphs are very useful in +editing code even though their canonical application is for editing +human language text. Most symbols contain words (@pxref{Words}); +sentences can be found in strings and comments (@pxref{Sentences}). +Paragraphs per se don't exist in code, but the paragraph commands are +useful anyway, because programming language major modes define +paragraphs to begin and end at blank lines (@pxref{Paragraphs}). +Judicious use of blank lines to make the program clearer will also +provide useful chunks of text for the paragraph commands to work +on. + + The selective display feature is useful for looking at the overall +structure of a function (@pxref{Selective Display}). This feature causes +only the lines that are indented less than a specified amount to appear +on the screen. + +@menu +* Program Modes:: Major modes for editing programs. +* Lists:: Expressions with balanced parentheses. +* List Commands:: The commands for working with list and sexps. +* Defuns:: Each program is made up of separate functions. + There are editing commands to operate on them. +* Program Indent:: Adjusting indentation to show the nesting. +* Matching:: Insertion of a close-delimiter flashes matching open. +* Comments:: Inserting, killing, and aligning comments. +* Balanced Editing:: Inserting two matching parentheses at once, etc. +* Symbol Completion:: Completion on symbol names of your program or language. +* Which Function:: Which Function mode shows which function you are in. +* Documentation:: Getting documentation of functions you plan to call. +* Change Log:: Maintaining a change history for your program. +* Tags:: Go direct to any function in your program in one + command. Tags remembers which file it is in. +* Emerge:: A convenient way of merging two versions of a program. +* C Modes:: Special commands of C, C++, Objective-C, + Java, and Pike modes. +* Fortran:: Fortran mode and its special features. +* Asm Mode:: Asm mode and its special features. +@end menu + +@node Program Modes +@section Major Modes for Programming Languages + +@cindex modes for programming languages +@cindex Perl mode +@cindex Icon mode +@cindex Awk mode +@cindex Makefile mode +@cindex Tcl mode +@cindex CPerl mode + Emacs also has major modes for the programming languages Lisp, Scheme +(a variant of Lisp), Awk, C, C++, Fortran, Icon, Java, Objective-C, +Pascal, Perl, Pike, CORBA IDL, and Tcl. There is also a major mode for +makefiles, called Makefile mode. An second alternative mode for Perl is +called CPerl mode. + + Ideally, a major mode should be implemented for each programming +language that you might want to edit with Emacs; but often the mode for +one language can serve for other syntactically similar languages. The +language modes that exist are those that someone decided to take the +trouble to write. + + There are several forms of Lisp mode, which differ in the way they +interface to Lisp execution. @xref{Executing Lisp}. + + Each of the programming language major modes defines the @key{TAB} key +to run an indentation function that knows the indentation conventions of +that language and updates the current line's indentation accordingly. +For example, in C mode @key{TAB} is bound to @code{c-indent-line}. +@kbd{C-j} is normally defined to do @key{RET} followed by @key{TAB}; +thus, it too indents in a mode-specific fashion. + +@kindex DEL @r{(programming modes)} +@findex backward-delete-char-untabify + In most programming languages, indentation is likely to vary from line to +line. So the major modes for those languages rebind @key{DEL} to treat a +tab as if it were the equivalent number of spaces (using the command +@code{backward-delete-char-untabify}). This makes it possible to rub out +indentation one column at a time without worrying whether it is made up of +spaces or tabs. Use @kbd{C-b C-d} to delete a tab character before point, +in these modes. + + Programming language modes define paragraphs to be separated only by +blank lines, so that the paragraph commands remain useful. Auto Fill mode, +if enabled in a programming language major mode, indents the new lines +which it creates. + +@cindex mode hook +@vindex c-mode-hook +@vindex lisp-mode-hook +@vindex emacs-lisp-mode-hook +@vindex lisp-interaction-mode-hook +@vindex scheme-mode-hook +@vindex muddle-mode-hook + Turning on a major mode runs a normal hook called the @dfn{mode hook}, +which is the value of a Lisp variable. Each major mode has a mode hook, +and the hook's name is always made from the mode command's name by +adding @samp{-hook}. For example, turning on C mode runs the hook +@code{c-mode-hook}, while turning on Lisp mode runs the hook +@code{lisp-mode-hook}. @xref{Hooks}. + +@node Lists +@section Lists and Sexps + +@cindex Control-Meta + By convention, Emacs keys for dealing with balanced expressions are +usually Control-Meta characters. They tend to be analogous in +function to their Control and Meta equivalents. These commands are +usually thought of as pertaining to expressions in programming +languages, but can be useful with any language in which some sort of +parentheses exist (including human languages). + +@cindex list +@cindex sexp +@cindex expression +@cindex parentheses, moving across +@cindex matching parenthesis, moving to + These commands fall into two classes. Some deal only with @dfn{lists} +(parenthetical groupings). They see nothing except parentheses, brackets, +braces (whichever ones must balance in the language you are working with), +and escape characters that might be used to quote those. + + The other commands deal with expressions or @dfn{sexps}. The word `sexp' +is derived from @dfn{s-expression}, the ancient term for an expression in +Lisp. But in Emacs, the notion of `sexp' is not limited to Lisp. It +refers to an expression in whatever language your program is written in. +Each programming language has its own major mode, which customizes the +syntax tables so that expressions in that language count as sexps. + + Sexps typically include symbols, numbers, and string constants, as well +as anything contained in parentheses, brackets or braces. + + In languages that use prefix and infix operators, such as C, it is not +possible for all expressions to be sexps. For example, C mode does not +recognize @samp{foo + bar} as a sexp, even though it @emph{is} a C expression; +it recognizes @samp{foo} as one sexp and @samp{bar} as another, with the +@samp{+} as punctuation between them. This is a fundamental ambiguity: +both @samp{foo + bar} and @samp{foo} are legitimate choices for the sexp to +move over if point is at the @samp{f}. Note that @samp{(foo + bar)} is a +single sexp in C mode. + + Some languages have obscure forms of expression syntax that nobody +has bothered to make Emacs understand properly. + +@node List Commands +@section List And Sexp Commands + +@c doublewidecommands +@table @kbd +@item C-M-f +Move forward over a sexp (@code{forward-sexp}). +@item C-M-b +Move backward over a sexp (@code{backward-sexp}). +@item C-M-k +Kill sexp forward (@code{kill-sexp}). +@item C-M-@key{DEL} +Kill sexp backward (@code{backward-kill-sexp}). +@item C-M-u +Move up and backward in list structure (@code{backward-up-list}). +@item C-M-d +Move down and forward in list structure (@code{down-list}). +@item C-M-n +Move forward over a list (@code{forward-list}). +@item C-M-p +Move backward over a list (@code{backward-list}). +@item C-M-t +Transpose expressions (@code{transpose-sexps}). +@item C-M-@@ +Put mark after following expression (@code{mark-sexp}). +@end table + +@kindex C-M-f +@kindex C-M-b +@findex forward-sexp +@findex backward-sexp + To move forward over a sexp, use @kbd{C-M-f} (@code{forward-sexp}). If +the first significant character after point is an opening delimiter +(@samp{(} in Lisp; @samp{(}, @samp{[} or @samp{@{} in C), @kbd{C-M-f} +moves past the matching closing delimiter. If the character begins a +symbol, string, or number, @kbd{C-M-f} moves over that. + + The command @kbd{C-M-b} (@code{backward-sexp}) moves backward over a +sexp. The detailed rules are like those above for @kbd{C-M-f}, but with +directions reversed. If there are any prefix characters (single-quote, +backquote and comma, in Lisp) preceding the sexp, @kbd{C-M-b} moves back +over them as well. The sexp commands move across comments as if they +were whitespace in most modes. + + @kbd{C-M-f} or @kbd{C-M-b} with an argument repeats that operation the +specified number of times; with a negative argument, it moves in the +opposite direction. + +@kindex C-M-k +@findex kill-sexp +@kindex C-M-DEL +@findex backward-kill-sexp + Killing a whole sexp can be done with @kbd{C-M-k} (@code{kill-sexp}) +or @kbd{C-M-@key{DEL}} (@code{backward-kill-sexp}). @kbd{C-M-k} kills +the characters that @kbd{C-M-f} would move over, and @kbd{C-M-@key{DEL}} +kills the characters that @kbd{C-M-b} would move over. + +@kindex C-M-n +@kindex C-M-p +@findex forward-list +@findex backward-list + The @dfn{list commands} move over lists, as the sexp commands do, but skip +blithely over any number of other kinds of sexps (symbols, strings, etc.). +They are @kbd{C-M-n} (@code{forward-list}) and @kbd{C-M-p} +(@code{backward-list}). The main reason they are useful is that they +usually ignore comments (since the comments usually do not contain any +lists).@refill + +@kindex C-M-u +@kindex C-M-d +@findex backward-up-list +@findex down-list + @kbd{C-M-n} and @kbd{C-M-p} stay at the same level in parentheses, when +that's possible. To move @emph{up} one (or @var{n}) levels, use @kbd{C-M-u} +(@code{backward-up-list}). +@kbd{C-M-u} moves backward up past one unmatched opening delimiter. A +positive argument serves as a repeat count; a negative argument reverses +direction of motion and also requests repetition, so it moves forward and +up one or more levels.@refill + + To move @emph{down} in list structure, use @kbd{C-M-d} +(@code{down-list}). In Lisp mode, where @samp{(} is the only opening +delimiter, this is nearly the same as searching for a @samp{(}. An +argument specifies the number of levels of parentheses to go down. + +@cindex transposition +@kindex C-M-t +@findex transpose-sexps + A somewhat random-sounding command which is nevertheless handy is +@kbd{C-M-t} (@code{transpose-sexps}), which drags the previous sexp +across the next one. An argument serves as a repeat count, and a +negative argument drags backwards (thus canceling out the effect of +@kbd{C-M-t} with a positive argument). An argument of zero, rather than +doing nothing, transposes the sexps ending after point and the mark. + +@kindex C-M-@@ +@findex mark-sexp + To set the region around the next sexp in the buffer, use @kbd{C-M-@@} +(@code{mark-sexp}), which sets mark at the same place that @kbd{C-M-f} +would move to. @kbd{C-M-@@} takes arguments like @kbd{C-M-f}. In +particular, a negative argument is useful for putting the mark at the +beginning of the previous sexp. + + The list and sexp commands' understanding of syntax is completely +controlled by the syntax table. Any character can, for example, be +declared to be an opening delimiter and act like an open parenthesis. +@xref{Syntax}. + +@node Defuns +@section Defuns +@cindex defuns + + In Emacs, a parenthetical grouping at the top level in the buffer is +called a @dfn{defun}. The name derives from the fact that most top-level +lists in a Lisp file are instances of the special form @code{defun}, but +any top-level parenthetical grouping counts as a defun in Emacs parlance +regardless of what its contents are, and regardless of the programming +language in use. For example, in C, the body of a function definition is a +defun. + +@c doublewidecommands +@table @kbd +@item C-M-a +Move to beginning of current or preceding defun +(@code{beginning-of-defun}). +@item C-M-e +Move to end of current or following defun (@code{end-of-defun}). +@item C-M-h +Put region around whole current or following defun (@code{mark-defun}). +@end table + +@kindex C-M-a +@kindex C-M-e +@kindex C-M-h +@findex beginning-of-defun +@findex end-of-defun +@findex mark-defun + The commands to move to the beginning and end of the current defun are +@kbd{C-M-a} (@code{beginning-of-defun}) and @kbd{C-M-e} (@code{end-of-defun}). + +@findex c-mark-function + If you wish to operate on the current defun, use @kbd{C-M-h} +(@code{mark-defun}) which puts point at the beginning and mark at the end +of the current or next defun. For example, this is the easiest way to get +ready to move the defun to a different place in the text. In C mode, +@kbd{C-M-h} runs the function @code{c-mark-function}, which is almost the +same as @code{mark-defun}; the difference is that it backs up over the +argument declarations, function name and returned data type so that the +entire C function is inside the region. @xref{Marking Objects}. + + Emacs assumes that any open-parenthesis found in the leftmost column +is the start of a defun. Therefore, @strong{never put an +open-parenthesis at the left margin in a Lisp file unless it is the +start of a top-level list. Never put an open-brace or other opening +delimiter at the beginning of a line of C code unless it starts the body +of a function.} The most likely problem case is when you want an +opening delimiter at the start of a line inside a string. To avoid +trouble, put an escape character (@samp{\}, in C and Emacs Lisp, +@samp{/} in some other Lisp dialects) before the opening delimiter. It +will not affect the contents of the string. + + In the remotest past, the original Emacs found defuns by moving upward a +level of parentheses until there were no more levels to go up. This always +required scanning all the way back to the beginning of the buffer, even for +a small function. To speed up the operation, Emacs was changed to assume +that any @samp{(} (or other character assigned the syntactic class of +opening-delimiter) at the left margin is the start of a defun. This +heuristic is nearly always right and avoids the costly scan; however, +it mandates the convention described above. + +@node Program Indent +@section Indentation for Programs +@cindex indentation for programs + + The best way to keep a program properly indented is to use Emacs to +reindent it as you change it. Emacs has commands to indent properly +either a single line, a specified number of lines, or all of the lines +inside a single parenthetical grouping. + +@menu +* Basic Indent:: Indenting a single line. +* Multi-line Indent:: Commands to reindent many lines at once. +* Lisp Indent:: Specifying how each Lisp function should be indented. +* C Indent:: Extra features for indenting C and related modes. +* Custom C Indent:: Controlling indentation style for C and related modes. +@end menu + + Emacs also provides a Lisp pretty-printer in the library @code{pp}. +This program reformats a Lisp object with indentation chosen to look nice. + +@node Basic Indent +@subsection Basic Program Indentation Commands + +@c WideCommands +@table @kbd +@item @key{TAB} +Adjust indentation of current line. +@item C-j +Equivalent to @key{RET} followed by @key{TAB} (@code{newline-and-indent}). +@end table + +@kindex TAB @r{(programming modes)} +@findex c-indent-line +@findex lisp-indent-line + The basic indentation command is @key{TAB}, which gives the current line +the correct indentation as determined from the previous lines. The +function that @key{TAB} runs depends on the major mode; it is @code{lisp-indent-line} +in Lisp mode, @code{c-indent-line} in C mode, etc. These functions +understand different syntaxes for different languages, but they all do +about the same thing. @key{TAB} in any programming-language major mode +inserts or deletes whitespace at the beginning of the current line, +independent of where point is in the line. If point is inside the +whitespace at the beginning of the line, @key{TAB} leaves it at the end of +that whitespace; otherwise, @key{TAB} leaves point fixed with respect to +the characters around it. + + Use @kbd{C-q @key{TAB}} to insert a tab at point. + +@kindex C-j +@findex newline-and-indent + When entering lines of new code, use @kbd{C-j} (@code{newline-and-indent}), +which is equivalent to a @key{RET} followed by a @key{TAB}. @kbd{C-j} creates +a blank line and then gives it the appropriate indentation. + + @key{TAB} indents the second and following lines of the body of a +parenthetical grouping each under the preceding one; therefore, if you +alter one line's indentation to be nonstandard, the lines below will +tend to follow it. This behavior is convenient in cases where you have +overridden the standard result of @key{TAB} because you find it +unaesthetic for a particular line. + + Remember that an open-parenthesis, open-brace or other opening delimiter +at the left margin is assumed by Emacs (including the indentation routines) +to be the start of a function. Therefore, you must never have an opening +delimiter in column zero that is not the beginning of a function, not even +inside a string. This restriction is vital for making the indentation +commands fast; you must simply accept it. @xref{Defuns}, for more +information on this. + +@node Multi-line Indent +@subsection Indenting Several Lines + + When you wish to reindent several lines of code which have been altered +or moved to a different level in the list structure, you have several +commands available. + +@table @kbd +@item C-M-q +Reindent all the lines within one list (@code{indent-sexp}). +@item C-u @key{TAB} +Shift an entire list rigidly sideways so that its first line +is properly indented. +@item C-M-\ +Reindent all lines in the region (@code{indent-region}). +@end table + +@kindex C-M-q +@findex indent-sexp + You can reindent the contents of a single list by positioning point +before the beginning of it and typing @kbd{C-M-q} (@code{indent-sexp} in +Lisp mode, @code{c-indent-exp} in C mode; also bound to other suitable +commands in other modes). The indentation of the line the sexp starts on +is not changed; therefore, only the relative indentation within the list, +and not its position, is changed. To correct the position as well, type a +@key{TAB} before the @kbd{C-M-q}. + +@kindex C-u TAB + If the relative indentation within a list is correct but the +indentation of its first line is not, go to that line and type @kbd{C-u +@key{TAB}}. @key{TAB} with a numeric argument reindents the current +line as usual, then reindents by the same amount all the lines in the +grouping starting on the current line. In other words, it reindents the +whole grouping rigidly as a unit. It is clever, though, and does not +alter lines that start inside strings, or C preprocessor lines when in C +mode. + + Another way to specify the range to be reindented is with the region. +The command @kbd{C-M-\} (@code{indent-region}) applies @key{TAB} to +every line whose first character is between point and mark. + +@node Lisp Indent +@subsection Customizing Lisp Indentation +@cindex customizing Lisp indentation + + The indentation pattern for a Lisp expression can depend on the function +called by the expression. For each Lisp function, you can choose among +several predefined patterns of indentation, or define an arbitrary one with +a Lisp program. + + The standard pattern of indentation is as follows: the second line of the +expression is indented under the first argument, if that is on the same +line as the beginning of the expression; otherwise, the second line is +indented underneath the function name. Each following line is indented +under the previous line whose nesting depth is the same. + +@vindex lisp-indent-offset + If the variable @code{lisp-indent-offset} is non-@code{nil}, it overrides +the usual indentation pattern for the second line of an expression, so that +such lines are always indented @code{lisp-indent-offset} more columns than +the containing list. + +@vindex lisp-body-indent + The standard pattern is overridden for certain functions. Functions +whose names start with @code{def} always indent the second line by +@code{lisp-body-indent} extra columns beyond the open-parenthesis +starting the expression. + + The standard pattern can be overridden in various ways for individual +functions, according to the @code{lisp-indent-function} property of the +function name. There are four possibilities for this property: + +@table @asis +@item @code{nil} +This is the same as no property; the standard indentation pattern is used. +@item @code{defun} +The pattern used for function names that start with @code{def} is used for +this function also. +@item a number, @var{number} +The first @var{number} arguments of the function are +@dfn{distinguished} arguments; the rest are considered the @dfn{body} +of the expression. A line in the expression is indented according to +whether the first argument on it is distinguished or not. If the +argument is part of the body, the line is indented @code{lisp-body-indent} +more columns than the open-parenthesis starting the containing +expression. If the argument is distinguished and is either the first +or second argument, it is indented @emph{twice} that many extra columns. +If the argument is distinguished and not the first or second argument, +the standard pattern is followed for that line. +@item a symbol, @var{symbol} +@var{symbol} should be a function name; that function is called to +calculate the indentation of a line within this expression. The +function receives two arguments: +@table @asis +@item @var{state} +The value returned by @code{parse-partial-sexp} (a Lisp primitive for +indentation and nesting computation) when it parses up to the +beginning of this line. +@item @var{pos} +The position at which the line being indented begins. +@end table +@noindent +It should return either a number, which is the number of columns of +indentation for that line, or a list whose car is such a number. The +difference between returning a number and returning a list is that a +number says that all following lines at the same nesting level should +be indented just like this one; a list says that following lines might +call for different indentations. This makes a difference when the +indentation is being computed by @kbd{C-M-q}; if the value is a +number, @kbd{C-M-q} need not recalculate indentation for the following +lines until the end of the list. +@end table + +@node C Indent +@subsection Commands for C Indentation + + Here are the commands for indentation in C mode and related modes: + +@table @code +@item C-c C-q +@kindex C-c C-q @r{(C mode)} +@findex c-indent-defun +Reindent the current top-level function definition or aggregate type +declaration (@code{c-indent-defun}). + +@item C-M-q +@kindex C-M-q @r{(C mode)} +@findex c-indent-exp +Reindent each line in the balanced expression that follows point +(@code{c-indent-exp}). A prefix argument inhibits error checking and +warning messages about invalid syntax. + +@item @key{TAB} +@findex c-indent-command +Reindent the current line, and/or in some cases insert a tab character +(@code{c-indent-command}). + +If @code{c-tab-always-indent} is @code{t}, this command always reindents +the current line and does nothing else. This is the default. + +If that variable is @code{nil}, this command reindents the current line +only if point is at the left margin or in the line's indentation; +otherwise, it inserts a tab (or the equivalent number of spaces, +if @code{indent-tabs-mode} is @code{nil}). + +Any other value (not @code{nil} or @code{t}) means always reindent the +line, and also insert a tab if within a comment, a string, or a +preprocessor directive. + +@item C-u @key{TAB} +Reindent the current line according to its syntax; also rigidly reindent +any other lines of the expression that starts on the current line. +@xref{Multi-line Indent}. +@end table + + To reindent the whole current buffer, type @kbd{C-x h C-M-\}. This +first selects the whole buffer as the region, then reindents that +region. + + To reindent the current block, use @kbd{C-M-u C-M-q}. This moves +to the front of the block and then reindents it all. + +@node Custom C Indent +@subsection Customizing C Indentation + + C mode and related modes use a simple yet flexible mechanism for +customizing indentation. The mechanism works in two steps: first it +classifies the line syntactically according to its contents and context; +second, it associates each kind of syntactic construct with an +indentation offset which you can customize. + +@menu +* Syntactic Analysis:: +* Indentation Calculation:: +* Changing Indent Style:: +* Syntactic Symbols:: +* Variables for C Indent:: +* C Indent Styles:: +@end menu + +@node Syntactic Analysis +@subsubsection Step 1---Syntactic Analysis +@cindex syntactic analysis + + In the first step, the C indentation mechanism looks at the line +before the one you are currently indenting and determines the syntactic +components of the construct on that line. It builds a list of these +syntactic components, each of which contains a @dfn{syntactic symbol} +and sometimes also a buffer position. Some syntactic symbols describe +grammatical elements, for example @code{statement} and +@code{substatement}; others describe locations amidst grammatical +elements, for example @code{class-open} and @code{knr-argdecl}. + + Conceptually, a line of C code is always indented relative to the +indentation of some line higher up in the buffer. This is represented +by the buffer positions in the syntactic component list. + + Here is an example. Suppose we have the following code in a C++ mode +buffer (the line numbers don't actually appear in the buffer): + +@example +1: void swap (int& a, int& b) +2: @{ +3: int tmp = a; +4: a = b; +5: b = tmp; +6: @} +@end example + + If you type @kbd{C-c C-s} (which runs the command +@code{c-show-syntactic-information}) on line 4, it shows the result of +the indentation mechanism for that line: + +@example +((statement . 32)) +@end example + + This indicates that the line is a statement and it is indented +relative to buffer position 32, which happens to be the @samp{i} in +@code{int} on line 3. If you move the cursor to line 3 and type +@kbd{C-c C-s}, it displays this: + +@example +((defun-block-intro . 28)) +@end example + + This indicates that the @code{int} line is the first statement in a +block, and is indented relative to buffer position 28, which is the +brace just after the function header. + +@noindent +Here is another example: + +@example +1: int add (int val, int incr, int doit) +2: @{ +3: if (doit) +4: @{ +5: return (val + incr); +6: @} +7: return (val); +8: @} +@end example + +@noindent +Typing @kbd{C-c C-s} on line 4 displays this: + +@example +((substatement-open . 43)) +@end example + + This says that the brace @emph{opens} a substatement block. By the +way, a @dfn{substatement} indicates the line after an @code{if}, +@code{else}, @code{while}, @code{do}, @code{switch}, @code{for}, +@code{try}, @code{catch}, @code{finally}, or @code{synchronized} +statement. + +@cindex syntactic component +@cindex syntactic symbol +@vindex c-syntactic-context + Within the C indentation commands, after a line has been analyzed +syntactically for indentation, the variable @code{c-syntactic-context} +contains a list that describes the results. Each element in this list +is a @dfn{syntactic component}: a cons cell containing a syntactic +symbol and (optionally) its corresponding buffer position. There may be +several elements in a component list; typically only one element has a +buffer position. + +@node Indentation Calculation +@subsubsection Step 2---Indentation Calculation +@cindex Indentation Calculation + + The C indentation mechanism calculates the indentation for the current +line using the list of syntactic components, @code{c-syntactic-context}, +derived from syntactic analysis. Each component is a cons cell that +contains a syntactic symbol and may also contain a buffer position. + + Each component contributes to the final total indentation of the line +in two ways. First, the syntactic symbol identifies an element of +@code{c-offsets-alist}, which is an association list mapping syntactic +symbols into indentation offsets. Each syntactic symbol's offset adds +to the total indentation. Second, if the component includes a buffer +position, the column number of that position adds to the indentation. +All these offsets and column numbers, added together, give the total +indentation. + + The following examples demonstrate the workings of the C indentation +mechanism: + +@example +1: void swap (int& a, int& b) +2: @{ +3: int tmp = a; +4: a = b; +5: b = tmp; +6: @} +@end example + + Suppose that point is on line 3 and you type @key{TAB} to reindent the +line. As explained above (@pxref{Syntactic Analysis}), the syntactic +component list for that line is: + +@example +((defun-block-intro . 28)) +@end example + + In this case, the indentation calculation first looks up +@code{defun-block-intro} in the @code{c-offsets-alist} alist. Suppose +that it finds the integer 2; it adds this to the running total +(initialized to zero), yielding a updated total indentation of 2 spaces. + + The next step is to find the column number of buffer position 28. +Since the brace at buffer position 28 is in column zero, this adds 0 to +the running total. Since this line has only one syntactic component, +the total indentation for the line is 2 spaces. + +@example +1: int add (int val, int incr, int doit) +2: @{ +3: if (doit) +4: @{ +5: return(val + incr); +6: @} +7: return(val); +8: @} +@end example + + If you type @key{TAB} on line 4, the same process is performed, but +with different data. The syntactic component list for this line is: + +@example +((substatement-open . 43)) +@end example + + Here, the indentation calculation's first job is to look up the +symbol @code{substatement-open} in @code{c-offsets-alist}. Let's assume +that the offset for this symbol is 2. At this point the running total +is 2 (0 + 2 = 2). Then it adds the column number of buffer position 43, +which is the @samp{i} in @code{if} on line 3. This character is in +column 2 on that line. Adding this yields a total indentation of 4 +spaces. + +@vindex c-strict-syntax-p + If a syntactic symbol in the analysis of a line does not appear in +@code{c-offsets-alist}, it is ignored; if in addition the variable +@code{c-strict-syntax-p} is non-@code{nil}, it is an error. + +@node Changing Indent Style +@subsubsection Changing Indentation Style + + There are two ways to customize the indentation style for the C-like +modes. First, you can select one of several predefined styles, each of +which specifies offsets for all the syntactic symbols. For more +flexibility, you can customize the handling of individual syntactic +symbols. @xref{Syntactic Symbols}, for a list of all defined syntactic +symbols. + +@table @kbd +@item M-x c-set-style @key{RET} @var{style} @key{RET} +Select predefined indentation style @var{style}. Type @kbd{?} when +entering @var{style} to see a list of supported styles; to find out what +a style looks like, select it and reindent some C code. + +@item C-c C-o @var{symbol} @key{RET} @var{offset} @key{RET} +Set the indentation offset for syntactic symbol @var{symbol} +(@code{c-set-offset}). The second argument @var{offset} specifies the +new indentation offset. +@end table + + The @code{c-offsets-alist} variable controls the amount of +indentation to give to each syntactic symbol. Its value is an +association list, and each element of the list has the form +@code{(@var{syntactic-symbol} . @var{offset})}. By changing the offsets +for various syntactic symbols, you can customize indentation in fine +detail. To change this alist, use @code{c-set-offset} (see below). + + Each offset value in @code{c-offsets-alist} can be an integer, a +function or variable name, a list, or one of the following symbols: @code{+}, +@code{-}, @code{++}, @code{--}, @code{*}, or @code{/}, indicating positive or negative +multiples of the variable @code{c-basic-offset}. Thus, if you want to +change the levels of indentation to be 3 spaces instead of 2 spaces, set +@code{c-basic-offset} to 3. + + Using a function as the offset value provides the ultimate flexibility +in customizing indentation. The function is called with a single +argument containing the @code{cons} of the syntactic symbol and +the buffer position, if any. The function should return an integer +offset. + + If the offset value is a list, its elements are processed according +to the rules above until a non-@code{nil} value is found. That value is +then added to the total indentation in the normal manner. The primary +use for this is to combine the results of several functions. + +@kindex C-c C-o @r{(C mode)} +@findex c-set-offset + The command @kbd{C-c C-o} (@code{c-set-offset}) is the easiest way to +set offsets, both interactively or in your @file{~/.emacs} file. First +specify the syntactic symbol, then the offset you want. @xref{Syntactic +Symbols}, for a list of valid syntactic symbols and their meanings. + +@node Syntactic Symbols +@subsubsection Syntactic Symbols + + Here is a table of valid syntactic symbols for indentation in C and +related modes, with their syntactic meanings. Normally, most of these +symbols are assigned offsets in @code{c-offsets-alist}. + +@table @code +@item string +Inside a multi-line string. + +@item c +Inside a multi-line C style block comment. + +@item defun-open +On a brace that opens a function definition. + +@item defun-close +On a brace that closes a function definition. + +@item defun-block-intro +In the first line in a top-level defun. + +@item class-open +On a brace that opens a class definition. + +@item class-close +On a brace that closes a class definition. + +@item inline-open +On a brace that opens an in-class inline method. + +@item inline-close +On a brace that closes an in-class inline method. + +@item extern-lang-open +On a brace that opens an external language block. + +@item extern-lang-close +On a brace that closes an external language block. + +@item func-decl-cont +The region between a function definition's argument list and the defun +opening brace (excluding K&R function definitions). In C, you cannot +put anything but whitespace and comments between them; in C++ and Java, +@code{throws} declarations and other things can appear in this context. + +@item knr-argdecl-intro +On the first line of a K&R C argument declaration. + +@item knr-argdecl +In one of the subsequent lines in a K&R C argument declaration. + +@item topmost-intro +On the first line in a topmost construct definition. + +@item topmost-intro-cont +On the topmost definition continuation lines. + +@item member-init-intro +On the first line in a member initialization list. + +@item member-init-cont +On one of the subsequent member initialization list lines. + +@item inher-intro +On the first line of a multiple inheritance list. + +@item inher-cont +On one of the subsequent multiple inheritance lines. + +@item block-open +On a statement block open brace. + +@item block-close +On a statement block close brace. + +@item brace-list-open +On the opening brace of an @code{enum} or @code{static} array list. + +@item brace-list-close +On the closing brace of an @code{enum} or @code{static} array list. + +@item brace-list-intro +On the first line in an @code{enum} or @code{static} array list. + +@item brace-list-entry +On one of the subsequent lines in an @code{enum} or @code{static} array +list. + +@item brace-entry-open +On one of the subsequent lines in an @code{enum} or @code{static} array +list, when the line begins with an open brace. + +@item statement +On an ordinary statement. + +@item statement-cont +On a continuation line of a statement. + +@item statement-block-intro +On the first line in a new statement block. + +@item statement-case-intro +On the first line in a @code{case} ``block.'' + +@item statement-case-open +On the first line in a @code{case} block starting with brace. + +@item inexpr-statement +On a statement block inside an expression. This is used for a GNU +extension to the C language, and for Pike special functions that take a +statement block as an argument. + +@item inexpr-class +On a class definition inside an expression. This is used for anonymous +classes and anonymous array initializers in Java. + +@item substatement +On the first line after an @code{if}, @code{while}, @code{for}, +@code{do}, or @code{else}. + +@item substatement-open +On the brace that opens a substatement block. + +@item case-label +On a @code{case} or @code{default} label. + +@item access-label +On a C++ @code{private}, @code{protected}, or @code{public} access label. + +@item label +On any ordinary label. + +@item do-while-closure +On the @code{while} that ends a @code{do}-@code{while} construct. + +@item else-clause +On the @code{else} of an @code{if}-@code{else} construct. + +@item catch-clause +On the @code{catch} and @code{finally} lines in +@code{try}@dots{}@code{catch} constructs in C++ and Java. + +@item comment-intro +On a line containing only a comment introduction. + +@item arglist-intro +On the first line in an argument list. + +@item arglist-cont +On one of the subsequent argument list lines when no arguments follow on +the same line as the arglist opening parenthesis. + +@item arglist-cont-nonempty +On one of the subsequent argument list lines when at least one argument +follows on the same line as the arglist opening parenthesis. + +@item arglist-close +On the closing parenthesis of an argument list. + +@item stream-op +On one of the lines continuing a stream operator construct. + +@item inclass +On a construct that is nested inside a class definition. The +indentation is relative to the open brace of the class definition. + +@item inextern-lang +On a construct that is nested inside an external language block. + +@item inexpr-statement +On the first line of statement block inside an expression. This is used +for the GCC extension to C that uses the syntax @code{(@{ @dots{} @})}. +It is also used for the special functions that takes a statement block +as an argument in Pike. + +@item inexpr-class +On the first line of a class definition inside an expression. This is +used for anonymous classes and anonymous array initializers in Java. + +@item cpp-macro +On the start of a cpp macro. + +@item friend +On a C++ @code{friend} declaration. + +@item objc-method-intro +On the first line of an Objective-C method definition. + +@item objc-method-args-cont +On one of the lines continuing an Objective-C method definition. + +@item objc-method-call-cont +On one of the lines continuing an Objective-C method call. + +@item inlambda +Like @code{inclass}, but used inside lambda (i.e. anonymous) functions. Only +used in Pike. + +@item lambda-intro-cont +On a line continuing the header of a lambda function, between the +@code{lambda} keyword and the function body. Only used in Pike. +@end table + +@node Variables for C Indent +@subsubsection Variables for C Indentation + + This section describes additional variables which control the +indentation behavior of C mode and related mode. + +@table @code +@item c-offsets-alist +@vindex c-offsets-alist +Association list of syntactic symbols and their indentation offsets. +You should not set this directly, only with @code{c-set-offset}. +@xref{Changing Indent Style}, for details. + +@item c-style-alist +@vindex c-style-alist +Variable for defining indentation styles; see below. + +@item c-basic-offset +@vindex c-basic-offset +Amount of basic offset used by @code{+} and @code{-} symbols in +@code{c-offsets-alist}.@refill + +@item c-special-indent-hook +@vindex c-special-indent-hook +Hook for user-defined special indentation adjustments. This hook is +called after a line is indented by C mode and related modes. +@end table + + The variable @code{c-style-alist} specifies the predefined indentation +styles. Each element has form @code{(@var{name} +@var{variable-setting}@dots{})}, where @var{name} is the name of the +style. Each @var{variable-setting} has the form @code{(@var{variable} +. @var{value})}; @var{variable} is one of the customization variables +used by C mode, and @var{value} is the value for that variable when +using the selected style. + + When @var{variable} is @code{c-offsets-alist}, that is a special case: +@var{value} is appended to the front of the value of @code{c-offsets-alist} +instead of replacing that value outright. Therefore, it is not necessary +for @var{value} to specify each and every syntactic symbol---only those +for which the style differs from the default. + + The indentation of lines containing only comments is also affected by +the variable @code{c-comment-only-line-offset} (@pxref{Comments in C}). + +@node C Indent Styles +@subsubsection C Indentation Styles +@cindex c indentation styles + + A @dfn{C style} is a collection of indentation style customizations. +Emacs comes with several predefined indentation styles for C and related +modes, including @code{gnu}, @code{k&r}, @code{bsd}, @code{stroustrup}, +@code{linux}, @code{python}, @code{java}, @code{whitesmith}, +@code{ellemtel}, and @code{cc-mode}. The default style is @code{gnu}. + +@findex c-set-style +@vindex c-default-style + To choose the style you want, use the command @kbd{M-x c-set-style}. +Specify a style name as an argument (case is not significant in C style +names). The chosen style only affects newly visited buffers, not those +you are already editing. You can also set the variable +@code{c-default-style} to specify the style for various major modes. +Its value should be an alist, in which each element specifies one major +mode and which indentation style to use for it. For example, + +@example +(setq c-default-style + '((java-mode . "java") (other . "gnu"))) +@end example + +@noindent +specifies an explicit choice for Java mode, and the default @samp{gnu} +style for the other C-like modes. + +@findex c-add-style + To define a new C indentation style, call the function +@code{c-add-style}: + +@example +(c-add-style @var{name} @var{values} @var{use-now}) +@end example + +@noindent +Here @var{name} is the name of the new style (a string), and +@var{values} is an alist whose elements have the form +@code{(@var{variable} . @var{value})}. The variables you specify should +be among those documented in @ref{Variables for C Indent}. + +If @var{use-now} is non-@code{nil}, @code{c-add-style} switches to the +new style after defining it. + +@node Matching +@section Automatic Display Of Matching Parentheses +@cindex matching parentheses +@cindex parentheses, displaying matches + + The Emacs parenthesis-matching feature is designed to show +automatically how parentheses match in the text. Whenever you type a +self-inserting character that is a closing delimiter, the cursor moves +momentarily to the location of the matching opening delimiter, provided +that is on the screen. If it is not on the screen, some text near it is +displayed in the echo area. Either way, you can tell what grouping is +being closed off. + + In Lisp, automatic matching applies only to parentheses. In C, it +applies to braces and brackets too. Emacs knows which characters to regard +as matching delimiters based on the syntax table, which is set by the major +mode. @xref{Syntax}. + + If the opening delimiter and closing delimiter are mismatched---such as +in @samp{[x)}---a warning message is displayed in the echo area. The +correct matches are specified in the syntax table. + +@vindex blink-matching-paren +@vindex blink-matching-paren-distance +@vindex blink-matching-delay + Three variables control parenthesis match display. +@code{blink-matching-paren} turns the feature on or off; @code{nil} +turns it off, but the default is @code{t} to turn match display on. +@code{blink-matching-delay} says how many seconds to wait; the default +is 1, but on some systems it is useful to specify a fraction of a +second. @code{blink-matching-paren-distance} specifies how many +characters back to search to find the matching opening delimiter. If +the match is not found in that far, scanning stops, and nothing is +displayed. This is to prevent scanning for the matching delimiter from +wasting lots of time when there is no match. The default is 12,000. + +@cindex Show Paren mode +@findex show-paren-mode + When using X Windows, you can request a more powerful alternative kind +of automatic parenthesis matching by enabling Show Paren mode. This +mode turns off the usual kind of matching parenthesis display and +instead uses highlighting to show what matches. Whenever point is after +a close parenthesis, the close parenthesis and its matching open +parenthesis are both highlighted; otherwise, if point is before an open +parenthesis, the matching close parenthesis is highlighted. (There is +no need to highlight the open parenthesis after point because the cursor +appears on top of that character.) Use the command @kbd{M-x +show-paren-mode} to enable or disable this mode. + +@node Comments +@section Manipulating Comments +@cindex comments + + Because comments are such an important part of programming, Emacs +provides special commands for editing and inserting comments. + +@menu +* Comment Commands:: +* Multi-Line Comments:: +* Options for Comments:: +@end menu + +@node Comment Commands +@subsection Comment Commands + +@kindex M-; +@cindex indentation for comments +@findex indent-for-comment + + The comment commands insert, kill and align comments. + +@c WideCommands +@table @kbd +@item M-; +Insert or align comment (@code{indent-for-comment}). +@item C-x ; +Set comment column (@code{set-comment-column}). +@item C-u - C-x ; +Kill comment on current line (@code{kill-comment}). +@item C-M-j +Like @key{RET} followed by inserting and aligning a comment +(@code{indent-new-comment-line}). +@item M-x comment-region +Add or remove comment delimiters on all the lines in the region. +@end table + + The command that creates a comment is @kbd{M-;} (@code{indent-for-comment}). +If there is no comment already on the line, a new comment is created, +aligned at a specific column called the @dfn{comment column}. The comment +is created by inserting the string Emacs thinks comments should start with +(the value of @code{comment-start}; see below). Point is left after that +string. If the text of the line extends past the comment column, then the +indentation is done to a suitable boundary (usually, at least one space is +inserted). If the major mode has specified a string to terminate comments, +that is inserted after point, to keep the syntax valid. + + @kbd{M-;} can also be used to align an existing comment. If a line +already contains the string that starts comments, then @kbd{M-;} just moves +point after it and reindents it to the conventional place. Exception: +comments starting in column 0 are not moved. + + Some major modes have special rules for indenting certain kinds of +comments in certain contexts. For example, in Lisp code, comments which +start with two semicolons are indented as if they were lines of code, +instead of at the comment column. Comments which start with three +semicolons are supposed to start at the left margin. Emacs understands +these conventions by indenting a double-semicolon comment using @key{TAB}, +and by not changing the indentation of a triple-semicolon comment at all. + +@example +;; This function is just an example +;;; Here either two or three semicolons are appropriate. +(defun foo (x) +;;; And now, the first part of the function: + ;; The following line adds one. + (1+ x)) ; This line adds one. +@end example + + In C code, a comment preceded on its line by nothing but whitespace +is indented like a line of code. + + Even when an existing comment is properly aligned, @kbd{M-;} is still +useful for moving directly to the start of the comment. + +@kindex C-u - C-x ; +@findex kill-comment + @kbd{C-u - C-x ;} (@code{kill-comment}) kills the comment on the current line, +if there is one. The indentation before the start of the comment is killed +as well. If there does not appear to be a comment in the line, nothing is +done. To reinsert the comment on another line, move to the end of that +line, do @kbd{C-y}, and then do @kbd{M-;} to realign it. Note that +@kbd{C-u - C-x ;} is not a distinct key; it is @kbd{C-x ;} (@code{set-comment-column}) +with a negative argument. That command is programmed so that when it +receives a negative argument it calls @code{kill-comment}. However, +@code{kill-comment} is a valid command which you could bind directly to a +key if you wanted to. + +@node Multi-Line Comments +@subsection Multiple Lines of Comments + +@kindex C-M-j +@cindex blank lines in programs +@findex indent-new-comment-line + If you are typing a comment and wish to continue it on another line, +you can use the command @kbd{C-M-j} (@code{indent-new-comment-line}). +This terminates the comment you are typing, creates a new blank line +afterward, and begins a new comment indented under the old one. When +Auto Fill mode is on, going past the fill column while typing a comment +causes the comment to be continued in just this fashion. If point is +not at the end of the line when @kbd{C-M-j} is typed, the text on +the rest of the line becomes part of the new comment line. + +@findex comment-region + To turn existing lines into comment lines, use the @kbd{M-x +comment-region} command. It adds comment delimiters to the lines that start +in the region, thus commenting them out. With a negative argument, it +does the opposite---it deletes comment delimiters from the lines in the +region. + + With a positive argument, @code{comment-region} duplicates the last +character of the comment start sequence it adds; the argument specifies +how many copies of the character to insert. Thus, in Lisp mode, +@kbd{C-u 2 M-x comment-region} adds @samp{;;} to each line. Duplicating +the comment delimiter is a way of calling attention to the comment. It +can also affect how the comment is indented. In Lisp, for proper +indentation, you should use an argument of two, if between defuns, and +three, if within a defun. + +@vindex comment-padding + The variable @code{comment-padding} specifies how many spaces +@code{comment-region} should insert on each line between the +comment delimiter and the line's original text. The default is 1. + +@node Options for Comments +@subsection Options Controlling Comments + +@vindex comment-column +@kindex C-x ; +@findex set-comment-column + The comment column is stored in the variable @code{comment-column}. You +can set it to a number explicitly. Alternatively, the command @kbd{C-x ;} +(@code{set-comment-column}) sets the comment column to the column point is +at. @kbd{C-u C-x ;} sets the comment column to match the last comment +before point in the buffer, and then does a @kbd{M-;} to align the +current line's comment under the previous one. Note that @kbd{C-u - C-x ;} +runs the function @code{kill-comment} as described above. + + The variable @code{comment-column} is per-buffer: setting the variable +in the normal fashion affects only the current buffer, but there is a +default value which you can change with @code{setq-default}. +@xref{Locals}. Many major modes initialize this variable for the +current buffer. + +@vindex comment-start-skip + The comment commands recognize comments based on the regular +expression that is the value of the variable @code{comment-start-skip}. +Make sure this regexp does not match the null string. It may match more +than the comment starting delimiter in the strictest sense of the word; +for example, in C mode the value of the variable is @code{@t{"/\\*+ +*"}}, which matches extra stars and spaces after the @samp{/*} itself. +(Note that @samp{\\} is needed in Lisp syntax to include a @samp{\} in +the string, which is needed to deny the first star its special meaning +in regexp syntax. @xref{Regexps}.) + +@vindex comment-start +@vindex comment-end + When a comment command makes a new comment, it inserts the value of +@code{comment-start} to begin it. The value of @code{comment-end} is +inserted after point, so that it will follow the text that you will insert +into the comment. In C mode, @code{comment-start} has the value +@w{@code{"/* "}} and @code{comment-end} has the value @w{@code{" */"}}. + +@vindex comment-multi-line + The variable @code{comment-multi-line} controls how @kbd{C-M-j} +(@code{indent-new-comment-line}) behaves when used inside a comment. If +@code{comment-multi-line} is @code{nil}, as it normally is, then the +comment on the starting line is terminated and a new comment is started +on the new following line. If @code{comment-multi-line} is not +@code{nil}, then the new following line is set up as part of the same +comment that was found on the starting line. This is done by not +inserting a terminator on the old line, and not inserting a starter on +the new line. In languages where multi-line comments work, the choice +of value for this variable is a matter of taste. + +@vindex comment-indent-function + The variable @code{comment-indent-function} should contain a function +that will be called to compute the indentation for a newly inserted +comment or for aligning an existing comment. It is set differently by +various major modes. The function is called with no arguments, but with +point at the beginning of the comment, or at the end of a line if a new +comment is to be inserted. It should return the column in which the +comment ought to start. For example, in Lisp mode, the indent hook +function bases its decision on how many semicolons begin an existing +comment, and on the code in the preceding lines. + +@node Balanced Editing +@section Editing Without Unbalanced Parentheses + +@table @kbd +@item M-( +Put parentheses around next sexp(s) (@code{insert-parentheses}). +@item M-) +Move past next close parenthesis and reindent +(@code{move-past-close-and-reindent}). +@end table + +@kindex M-( +@kindex M-) +@findex insert-parentheses +@findex move-past-close-and-reindent + The commands @kbd{M-(} (@code{insert-parentheses}) and @kbd{M-)} +(@code{move-past-close-and-reindent}) are designed to facilitate a style +of editing which keeps parentheses balanced at all times. @kbd{M-(} +inserts a pair of parentheses, either together as in @samp{()}, or, if +given an argument, around the next several sexps. It leaves point after +the open parenthesis. The command @kbd{M-)} moves past the close +parenthesis, deleting any indentation preceding it, and indenting with +@kbd{C-j} after it. + + For example, instead of typing @kbd{( F O O )}, you can type @kbd{M-( +F O O}, which has the same effect except for leaving the cursor before +the close parenthesis. + +@vindex parens-require-spaces + @kbd{M-(} may insert a space before the open parenthesis, depending on +the syntax class of the preceding character. Set +@code{parens-require-spaces} to @code{nil} value if you wish to inhibit +this. + +@node Symbol Completion +@section Completion for Symbol Names +@cindex completion (symbol names) + + Usually completion happens in the minibuffer. But one kind of completion +is available in all buffers: completion for symbol names. + +@kindex M-TAB + The character @kbd{M-@key{TAB}} runs a command to complete the partial +symbol before point against the set of meaningful symbol names. Any +additional characters determined by the partial name are inserted at +point. + + If the partial name in the buffer has more than one possible completion +and they have no additional characters in common, a list of all possible +completions is displayed in another window. + +@cindex completion using tags +@cindex tags completion +@cindex Info index completion +@findex complete-symbol + In most programming language major modes, @kbd{M-@key{TAB}} runs the +command @code{complete-symbol}, which provides two kinds of completion. +Normally it does completion based on a tags table (@pxref{Tags}); with a +numeric argument (regardless of the value), it does completion based on +the names listed in the Info file indexes for your language. Thus, to +complete the name of a symbol defined in your own program, use +@kbd{M-@key{TAB}} with no argument; to complete the name of a standard +library function, use @kbd{C-u M-@key{TAB}}. Of course, Info-based +completion works only if there is an Info file for the standard library +functions of your language, and only if it is installed at your site. + +@cindex Lisp symbol completion +@cindex completion in Lisp +@findex lisp-complete-symbol + In Emacs-Lisp mode, the name space for completion normally consists of +nontrivial symbols present in Emacs---those that have function +definitions, values or properties. However, if there is an +open-parenthesis immediately before the beginning of the partial symbol, +only symbols with function definitions are considered as completions. +The command which implements this is @code{lisp-complete-symbol}. + + In Text mode and related modes, @kbd{M-@key{TAB}} completes words +based on the spell-checker's dictionary. @xref{Spelling}. + +@node Which Function +@section Which Function Mode + + Which Function mode is a minor mode that displays the current function +name in the mode line, as you move around in a buffer. + +@findex which-function-mode +@vindex which-func-modes + To enable (or disable) Which Function mode, use the command @kbd{M-x +which-function-mode}. This command is global; it applies to all +buffers, both existing ones and those yet to be created. However, this +only affects certain major modes, those listed in the value of +@code{which-func-modes}. (If the value is @code{t}, then Which Function +mode applies to all major modes that know how to support it---which are +the major modes that support Imenu.) + +@node Documentation +@section Documentation Commands + + As you edit Lisp code to be run in Emacs, the commands @kbd{C-h f} +(@code{describe-function}) and @kbd{C-h v} (@code{describe-variable}) can +be used to print documentation of functions and variables that you want to +call. These commands use the minibuffer to read the name of a function or +variable to document, and display the documentation in a window. + + For extra convenience, these commands provide default arguments based on +the code in the neighborhood of point. @kbd{C-h f} sets the default to the +function called in the innermost list containing point. @kbd{C-h v} uses +the symbol name around or adjacent to point as its default. + +@cindex Eldoc mode +@findex eldoc-mode + For Emacs Lisp code, you can also use Eldoc mode. This minor mode +constantly displays in the echo area the argument list for the function +being called at point. (In other words, it finds the function call that +point is contained in, and displays the argument list of that function.) +Eldoc mode applies in Emacs Lisp and Lisp Interaction modes only. Use +the command @kbd{M-x eldoc-mode} to enable or disable this feature. + +@findex info-lookup-symbol +@findex info-lookup-file +@kindex C-h C-i + For C, Lisp, and other languages, you can use @kbd{C-h C-i} +(@code{info-lookup-symbol}) to view the Info documentation for a symbol. +You specify the symbol with the minibuffer; by default, it uses the +symbol that appears in the buffer at point. The major mode determines +where to look for documentation for the symbol---which Info files and +which indices. You can also use @kbd{M-x info-lookup-file} to look for +documentation for a file name. + +@findex manual-entry + You can read the ``man page'' for an operating system command, library +function, or system call, with the @kbd{M-x manual-entry} command. It +runs the @code{man} program to format the man page, and runs it +asynchronously if your system permits, so that you can keep on editing +while the page is being formatted. (MS-DOS and MS-Windows 3 do not +permit asynchronous subprocesses, so on these systems you cannot edit +while Emacs waits for @code{man} to exit.) The result goes in a buffer +named @samp{*Man @var{topic}*}. These buffers use a special major mode, +Man mode, that facilitates scrolling and examining other manual pages. +For details, type @kbd{C-h m} while in a man page buffer. + +@vindex Man-fontify-manpage-flag + For a long man page, setting the faces properly can take substantial +time. By default, Emacs uses faces in man pages if Emacs can display +different fonts or colors. You can turn off use of faces in man pages +by setting the variable @code{Man-fontify-manpage-flag} to @code{nil}. + +@findex Man-fontify-manpage + If you insert the text of a man page into an Emacs buffer in some +other fashion, you can use the command @kbd{M-x Man-fontify-manpage} to +perform the same conversions that @kbd{M-x manual-entry} does. + + Eventually the GNU project hopes to replace most man pages with +better-organized manuals that you can browse with Info. @xref{Misc +Help}. Since this process is only partially completed, it is still +useful to read manual pages. + +@node Change Log +@section Change Logs + +@cindex change log +@kindex C-x 4 a +@findex add-change-log-entry-other-window + The Emacs command @kbd{C-x 4 a} adds a new entry to the change log +file for the file you are editing +(@code{add-change-log-entry-other-window}). + + A change log file contains a chronological record of when and why you +have changed a program, consisting of a sequence of entries describing +individual changes. Normally it is kept in a file called +@file{ChangeLog} in the same directory as the file you are editing, or +one of its parent directories. A single @file{ChangeLog} file can +record changes for all the files in its directory and all its +subdirectories. + + A change log entry starts with a header line that contains your name, +your email address (taken from the variable @code{user-mail-address}), +and the current date and time. Aside from these header lines, every +line in the change log starts with a space or a tab. The bulk of the +entry consists of @dfn{items}, each of which starts with a line starting +with whitespace and a star. Here are two entries, both dated in May +1993, each with two items: + +@iftex +@medbreak +@end iftex +@smallexample +1993-05-25 Richard Stallman <rms@@gnu.org> + + * man.el: Rename symbols `man-*' to `Man-*'. + (manual-entry): Make prompt string clearer. + + * simple.el (blink-matching-paren-distance): + Change default to 12,000. + +1993-05-24 Richard Stallman <rms@@gnu.org> + + * vc.el (minor-mode-map-alist): Don't use it if it's void. + (vc-cancel-version): Doc fix. +@end smallexample + +@noindent +(Previous Emacs versions used a different format for the date.) + + One entry can describe several changes; each change should have its +own item. Normally there should be a blank line between items. When +items are related (parts of the same change, in different places), group +them by leaving no blank line between them. The second entry above +contains two items grouped in this way. + + @kbd{C-x 4 a} visits the change log file and creates a new entry +unless the most recent entry is for today's date and your name. It also +creates a new item for the current file. For many languages, it can +even guess the name of the function or other object that was changed. + +@cindex Change Log mode +@findex change-log-mode + The change log file is visited in Change Log mode. In this major +mode, each bunch of grouped items counts as one paragraph, and each +entry is considered a page. This facilitates editing the entries. +@kbd{C-j} and auto-fill indent each new line like the previous line; +this is convenient for entering the contents of an entry. + + Version control systems are another way to keep track of changes in your +program and keep a change log. @xref{Log Buffer}. + +@node Tags +@section Tags Tables +@cindex tags table + + A @dfn{tags table} is a description of how a multi-file program is +broken up into files. It lists the names of the component files and the +names and positions of the functions (or other named subunits) in each +file. Grouping the related files makes it possible to search or replace +through all the files with one command. Recording the function names +and positions makes possible the @kbd{M-.} command which finds the +definition of a function by looking up which of the files it is in. + + Tags tables are stored in files called @dfn{tags table files}. The +conventional name for a tags table file is @file{TAGS}. + + Each entry in the tags table records the name of one tag, the name of the +file that the tag is defined in (implicitly), and the position in that file +of the tag's definition. + + Just what names from the described files are recorded in the tags table +depends on the programming language of the described file. They +normally include all functions and subroutines, and may also include +global variables, data types, and anything else convenient. Each name +recorded is called a @dfn{tag}. + +@menu +* Tag Syntax:: Tag syntax for various types of code and text files. +* Create Tags Table:: Creating a tags table with @code{etags}. +* Select Tags Table:: How to visit a tags table. +* Find Tag:: Commands to find the definition of a specific tag. +* Tags Search:: Using a tags table for searching and replacing. +* List Tags:: Listing and finding tags defined in a file. +@end menu + +@node Tag Syntax +@subsection Source File Tag Syntax + + Here is how tag syntax is defined for the most popular languages: + +@itemize @bullet +@item +In C code, any C function or typedef is a tag, and so are definitions of +@code{struct}, @code{union} and @code{enum}. @code{#define} macro +definitions and @code{enum} constants are also tags, unless you specify +@samp{--no-defines} when making the tags table. Similarly, global +variables are tags, unless you specify @samp{--no-globals}. Use of +@samp{--no-globals} and @samp{--no-defines} can make the tags table file +much smaller. + +@item +In C++ code, in addition to all the tag constructs of C code, member +functions are also recognized, and optionally member variables if you +use the @samp{--members} option. Tags for variables and functions in +classes are named @samp{@var{class}::@var{variable}} and +@samp{@var{class}::@var{function}}. + +@item +In Java code, tags include all the constructs recognized in C++, plus +the @code{extends} and @code{implements} constructs. Tags for variables +and functions in classes are named @samp{@var{class}.@var{variable}} and +@samp{@var{class}.@var{function}}. + +@item +In La@TeX{} text, the argument of any of the commands @code{\chapter}, +@code{\section}, @code{\subsection}, @code{\subsubsection}, +@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, +@code{\part}, @code{\appendix}, @code{\entry}, or @code{\index}, is a +tag.@refill + +Other commands can make tags as well, if you specify them in the +environment variable @code{TEXTAGS} before invoking @code{etags}. The +value of this environment variable should be a colon-separated list of +command names. For example, + +@example +TEXTAGS="def:newcommand:newenvironment" +export TEXTAGS +@end example + +@noindent +specifies (using Bourne shell syntax) that the commands @samp{\def}, +@samp{\newcommand} and @samp{\newenvironment} also define tags. + +@item +In Lisp code, any function defined with @code{defun}, any variable +defined with @code{defvar} or @code{defconst}, and in general the first +argument of any expression that starts with @samp{(def} in column zero, is +a tag. + +@item +In Scheme code, tags include anything defined with @code{def} or with a +construct whose name starts with @samp{def}. They also include variables +set with @code{set!} at top level in the file. +@end itemize + + Several other languages are also supported: + +@itemize @bullet +@item +In assembler code, labels appearing at the beginning of a line, +followed by a colon, are tags. + +@item +In Bison or Yacc input files, each rule defines as a tag the nonterminal +it constructs. The portions of the file that contain C code are parsed +as C code. + +@item +In Cobol code, tags are paragraph names; that is, any word starting in +column 8 and followed by a period. + +@item +In Erlang code, the tags are the functions, records, and macros defined +in the file. + +@item +In Fortran code, functions, subroutines and blockdata are tags. + +@item +In Objective C code, tags include Objective C definitions for classes, +class categories, methods, and protocols. + +@item +In Pascal code, the tags are the functions and procedures defined in +the file. + +@item +In Perl code, the tags are the procedures defined by the @code{sub} +keyword. + +@item +In Postscript code, the tags are the functions. + +@item +In Prolog code, a tag name appears at the left margin. +@end itemize + + You can also generate tags based on regexp matching (@pxref{Create +Tags Table}) to handle other formats and languages. + +@node Create Tags Table +@subsection Creating Tags Tables +@cindex @code{etags} program + + The @code{etags} program is used to create a tags table file. It knows +the syntax of several languages, as described in +@iftex +the previous section. +@end iftex +@ifinfo +@ref{Tag Syntax}. +@end ifinfo +Here is how to run @code{etags}: + +@example +etags @var{inputfiles}@dots{} +@end example + +@noindent +The @code{etags} program reads the specified files, and writes a tags table +named @file{TAGS} in the current working directory. @code{etags} +recognizes the language used in an input file based on its file name and +contents. You can specify the language with the +@samp{--language=@var{name}} option, described below. + + If the tags table data become outdated due to changes in the files +described in the table, the way to update the tags table is the same way it +was made in the first place. It is not necessary to do this often. + + If the tags table fails to record a tag, or records it for the wrong +file, then Emacs cannot possibly find its definition. However, if the +position recorded in the tags table becomes a little bit wrong (due to +some editing in the file that the tag definition is in), the only +consequence is a slight delay in finding the tag. Even if the stored +position is very wrong, Emacs will still find the tag, but it must +search the entire file for it. + + So you should update a tags table when you define new tags that you want +to have listed, or when you move tag definitions from one file to another, +or when changes become substantial. Normally there is no need to update +the tags table after each edit, or even every day. + + One tags table can effectively include another. Specify the included +tags file name with the @samp{--include=@var{file}} option when creating +the file that is to include it. The latter file then acts as if it +contained all the files specified in the included file, as well as the +files it directly contains. + + If you specify the source files with relative file names when you run +@code{etags}, the tags file will contain file names relative to the +directory where the tags file was initially written. This way, you can +move an entire directory tree containing both the tags file and the +source files, and the tags file will still refer correctly to the source +files. + + If you specify absolute file names as arguments to @code{etags}, then +the tags file will contain absolute file names. This way, the tags file +will still refer to the same files even if you move it, as long as the +source files remain in the same place. Absolute file names start with +@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows. + + When you want to make a tags table from a great number of files, you +may have problems listing them on the command line, because some systems +have a limit on its length. The simplest way to circumvent this limit +is to tell @code{etags} to read the file names from its standard input, +by typing a dash in place of the file names, like this: + +@example +find . -name "*.[chCH]" -print | etags - +@end example + + Use the option @samp{--language=@var{name}} to specify the language +explicitly. You can intermix these options with file names; each one +applies to the file names that follow it. Specify +@samp{--language=auto} to tell @code{etags} to resume guessing the +language from the file names and file contents. Specify +@samp{--language=none} to turn off language-specific processing +entirely; then @code{etags} recognizes tags by regexp matching alone. +@samp{etags --help} prints the list of the languages @code{etags} knows, +and the file name rules for guessing the language. + + The @samp{--regex} option provides a general way of recognizing tags +based on regexp matching. You can freely intermix it with file names. +Each @samp{--regex} option adds to the preceding ones, and applies only +to the following files. The syntax is: + +@example +--regex=/@var{tagregexp}[/@var{nameregexp}]/ +@end example + +@noindent +where @var{tagregexp} is used to match the lines to tag. It is always +anchored, that is, it behaves as if preceded by @samp{^}. If you want +to account for indentation, just match any initial number of blanks by +beginning your regular expression with @samp{[ \t]*}. In the regular +expressions, @samp{\} quotes the next character, and @samp{\t} stands +for the tab character. Note that @code{etags} does not handle the other +C escape sequences for special characters. + +@cindex interval operator (in regexps) + The syntax of regular expressions in @code{etags} is the same as in +Emacs, augmented with the @dfn{interval operator}, which works as in +@code{grep} and @code{ed}. The syntax of an interval operator is +@samp{\@{@var{m},@var{n}\@}}, and its meaning is to match the preceding +expression at least @var{m} times and up to @var{n} times. + + You should not match more characters with @var{tagregexp} than that +needed to recognize what you want to tag. If the match is such that +more characters than needed are unavoidably matched by @var{tagregexp}, +you may find useful to add a @var{nameregexp}, in order to narrow the tag +scope. You can find some examples below. + + The @samp{-R} option deletes all the regexps defined with +@samp{--regex} options. It applies to the file names following it, as +you can see from the following example: + +@example +etags --regex=/@var{reg1}/ voo.doo --regex=/@var{reg2}/ \ + bar.ber -R --lang=lisp los.er +@end example + +@noindent +Here @code{etags} chooses the parsing language for @file{voo.doo} and +@file{bar.ber} according to their contents. @code{etags} also uses +@var{reg1} to recognize additional tags in @file{voo.doo}, and both +@var{reg1} and @var{reg2} to recognize additional tags in +@file{bar.ber}. @code{etags} uses the Lisp tags rules, and no regexp +matching, to recognize tags in @file{los.er}. + + Here are some more examples. The regexps are quoted to protect them +from shell interpretation. + +@itemize @bullet +@item +Tag the @code{DEFVAR} macros in the emacs source files: + +@smallexample +--regex='/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' +@end smallexample + +@item +Tag VHDL files (this example is a single long line, broken here for +formatting reasons): + +@smallexample +--language=none +--regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' +--regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ +\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' +@end smallexample + +@item +Tag Tcl files (this last example shows the usage of a @var{nameregexp}): + +@smallexample +--lang=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' +@end smallexample +@end itemize + + For a list of the other available @code{etags} options, execute +@code{etags --help}. + +@node Select Tags Table +@subsection Selecting a Tags Table + +@vindex tags-file-name +@findex visit-tags-table + Emacs has at any time one @dfn{selected} tags table, and all the commands +for working with tags tables use the selected one. To select a tags table, +type @kbd{M-x visit-tags-table}, which reads the tags table file name as an +argument. The name @file{TAGS} in the default directory is used as the +default file name. + + All this command does is store the file name in the variable +@code{tags-file-name}. Emacs does not actually read in the tags table +contents until you try to use them. Setting this variable yourself is just +as good as using @code{visit-tags-table}. The variable's initial value is +@code{nil}; that value tells all the commands for working with tags tables +that they must ask for a tags table file name to use. + + Using @code{visit-tags-table} when a tags table is already loaded +gives you a choice: you can add the new tags table to the current list +of tags tables, or start a new list. The tags commands use all the tags +tables in the current list. If you start a new list, the new tags table +is used @emph{instead} of others. If you add the new table to the +current list, it is used @emph{as well as} the others. When the tags +commands scan the list of tags tables, they don't always start at the +beginning of the list; they start with the first tags table (if any) +that describes the current file, proceed from there to the end of the +list, and then scan from the beginning of the list until they have +covered all the tables in the list. + +@vindex tags-table-list + You can specify a precise list of tags tables by setting the variable +@code{tags-table-list} to a list of strings, like this: + +@c keep this on two lines for formatting in smallbook +@example +@group +(setq tags-table-list + '("~/emacs" "/usr/local/lib/emacs/src")) +@end group +@end example + +@noindent +This tells the tags commands to look at the @file{TAGS} files in your +@file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src} +directory. The order depends on which file you are in and which tags +table mentions that file, as explained above. + + Do not set both @code{tags-file-name} and @code{tags-table-list}. + +@node Find Tag +@subsection Finding a Tag + + The most important thing that a tags table enables you to do is to find +the definition of a specific tag. + +@table @kbd +@item M-.@: @var{tag} @key{RET} +Find first definition of @var{tag} (@code{find-tag}). +@item C-u M-. +Find next alternate definition of last tag specified. +@item C-u - M-. +Go back to previous tag found. +@item C-M-. @var{pattern} @key{RET} +Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}). +@item C-u C-M-. +Find the next tag whose name matches the last pattern used. +@item C-x 4 .@: @var{tag} @key{RET} +Find first definition of @var{tag}, but display it in another window +(@code{find-tag-other-window}). +@item C-x 5 .@: @var{tag} @key{RET} +Find first definition of @var{tag}, and create a new frame to select the +buffer (@code{find-tag-other-frame}). +@item M-* +Pop back to where you previously invoked @kbd{M-.} and friends. +@end table + +@kindex M-. +@findex find-tag + @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of +a specified tag. It searches through the tags table for that tag, as a +string, and then uses the tags table info to determine the file that the +definition is in and the approximate character position in the file of +the definition. Then @code{find-tag} visits that file, moves point to +the approximate character position, and searches ever-increasing +distances away to find the tag definition. + + If an empty argument is given (just type @key{RET}), the sexp in the +buffer before or around point is used as the @var{tag} argument. +@xref{Lists}, for info on sexps. + + You don't need to give @kbd{M-.} the full name of the tag; a part +will do. This is because @kbd{M-.} finds tags in the table which +contain @var{tag} as a substring. However, it prefers an exact match +to a substring match. To find other tags that match the same +substring, give @code{find-tag} a numeric argument, as in @kbd{C-u +M-.}; this does not read a tag name, but continues searching the tags +table's text for another tag containing the same substring last used. +If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier +alternative to @kbd{C-u M-.}. + +@kindex C-x 4 . +@findex find-tag-other-window +@kindex C-x 5 . +@findex find-tag-other-frame + Like most commands that can switch buffers, @code{find-tag} has a +variant that displays the new buffer in another window, and one that +makes a new frame for it. The former is @kbd{C-x 4 .}, which invokes +the command @code{find-tag-other-window}. The latter is @kbd{C-x 5 .}, +which invokes @code{find-tag-other-frame}. + + To move back to places you've found tags recently, use @kbd{C-u - +M-.}; more generally, @kbd{M-.} with a negative numeric argument. This +command can take you to another buffer. @kbd{C-x 4 .} with a negative +argument finds the previous tag location in another window. + +@kindex M-* +@findex pop-tag-mark +@vindex find-tag-marker-ring-length + As well as going back to places you've found tags recently, you can go +back to places @emph{from where} you found them. Use @kbd{M-*}, which +invokes the command @code{pop-tag-mark}, for this. Typically you would +find and study the definition of something with @kbd{M-.} and then +return to where you were with @kbd{M-*}. + + Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to +a depth determined by the variable @code{find-tag-marker-ring-length}. + +@findex find-tag-regexp +@kindex C-M-. + The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that +match a specified regular expression. It is just like @kbd{M-.} except +that it does regexp matching instead of substring matching. + +@node Tags Search +@subsection Searching and Replacing with Tags Tables + + The commands in this section visit and search all the files listed in the +selected tags table, one by one. For these commands, the tags table serves +only to specify a sequence of files to search. + +@table @kbd +@item M-x tags-search @key{RET} @var{regexp} @key{RET} +Search for @var{regexp} through the files in the selected tags +table. +@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET} +Perform a @code{query-replace-regexp} on each file in the selected tags table. +@item M-, +Restart one of the commands above, from the current location of point +(@code{tags-loop-continue}). +@end table + +@findex tags-search + @kbd{M-x tags-search} reads a regexp using the minibuffer, then +searches for matches in all the files in the selected tags table, one +file at a time. It displays the name of the file being searched so you +can follow its progress. As soon as it finds an occurrence, +@code{tags-search} returns. + +@kindex M-, +@findex tags-loop-continue + Having found one match, you probably want to find all the rest. To find +one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the +@code{tags-search}. This searches the rest of the current buffer, followed +by the remaining files of the tags table.@refill + +@findex tags-query-replace + @kbd{M-x tags-query-replace} performs a single +@code{query-replace-regexp} through all the files in the tags table. It +reads a regexp to search for and a string to replace with, just like +ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x +tags-search}, but repeatedly, processing matches according to your +input. @xref{Replace}, for more information on query replace. + + It is possible to get through all the files in the tags table with a +single invocation of @kbd{M-x tags-query-replace}. But often it is +useful to exit temporarily, which you can do with any input event that +has no special query replace meaning. You can resume the query replace +subsequently by typing @kbd{M-,}; this command resumes the last tags +search or replace command that you did. + + The commands in this section carry out much broader searches than the +@code{find-tag} family. The @code{find-tag} commands search only for +definitions of tags that match your substring or regexp. The commands +@code{tags-search} and @code{tags-query-replace} find every occurrence +of the regexp, as ordinary search commands and replace commands do in +the current buffer. + + These commands create buffers only temporarily for the files that they +have to search (those which are not already visited in Emacs buffers). +Buffers in which no match is found are quickly killed; the others +continue to exist. + + It may have struck you that @code{tags-search} is a lot like +@code{grep}. You can also run @code{grep} itself as an inferior of +Emacs and have Emacs show you the matching lines one by one. This works +much like running a compilation; finding the source locations of the +@code{grep} matches works like finding the compilation errors. +@xref{Compilation}. + +@node List Tags +@subsection Tags Table Inquiries + +@table @kbd +@item M-x list-tags @key{RET} @var{file} @key{RET} +Display a list of the tags defined in the program file @var{file}. +@item M-x tags-apropos @key{RET} @var{regexp} @key{RET} +Display a list of all tags matching @var{regexp}. +@end table + +@findex list-tags + @kbd{M-x list-tags} reads the name of one of the files described by +the selected tags table, and displays a list of all the tags defined in +that file. The ``file name'' argument is really just a string to +compare against the file names recorded in the tags table; it is read as +a string rather than as a file name. Therefore, completion and +defaulting are not available, and you must enter the file name the same +way it appears in the tags table. Do not include a directory as part of +the file name unless the file name recorded in the tags table includes a +directory. + +@findex tags-apropos + @kbd{M-x tags-apropos} is like @code{apropos} for tags +(@pxref{Apropos}). It reads a regexp, then finds all the tags in the +selected tags table whose entries match that regexp, and displays the +tag names found. + + You can also perform completion in the buffer on the name space of tag +names in the current tags tables. @xref{Symbol Completion}. + +@node Emerge +@section Merging Files with Emerge +@cindex Emerge +@cindex merging files + +It's not unusual for programmers to get their signals crossed and modify +the same program in two different directions. To recover from this +confusion, you need to merge the two versions. Emerge makes this +easier. See also @ref{Comparing Files}, for commands to compare +in a more manual fashion, and @ref{Emerge,,, ediff, The Ediff Manual}. + +@menu +* Overview of Emerge:: How to start Emerge. Basic concepts. +* Submodes of Emerge:: Fast mode vs. Edit mode. + Skip Prefers mode and Auto Advance mode. +* State of Difference:: You do the merge by specifying state A or B + for each difference. +* Merge Commands:: Commands for selecting a difference, + changing states of differences, etc. +* Exiting Emerge:: What to do when you've finished the merge. +* Combining in Emerge:: How to keep both alternatives for a difference. +* Fine Points of Emerge:: Misc. +@end menu + +@node Overview of Emerge +@subsection Overview of Emerge + +To start Emerge, run one of these four commands: + +@table @kbd +@item M-x emerge-files +@findex emerge-files +Merge two specified files. + +@item M-x emerge-files-with-ancestor +@findex emerge-files-with-ancestor +Merge two specified files, with reference to a common ancestor. + +@item M-x emerge-buffers +@findex emerge-buffers +Merge two buffers. + +@item M-x emerge-buffers-with-ancestor +@findex emerge-buffers-with-ancestor +Merge two buffers with reference to a common ancestor in a third +buffer. +@end table + +@cindex merge buffer (Emerge) +@cindex A and B buffers (Emerge) + The Emerge commands compare two files or buffers, and display the +comparison in three buffers: one for each input text (the @dfn{A buffer} +and the @dfn{B buffer}), and one (the @dfn{merge buffer}) where merging +takes place. The merge buffer shows the full merged text, not just the +differences. Wherever the two input texts differ, you can choose which +one of them to include in the merge buffer. + + The Emerge commands that take input from existing buffers use only the +accessible portions of those buffers, if they are narrowed +(@pxref{Narrowing}). + + If a common ancestor version is available, from which the two texts to +be merged were both derived, Emerge can use it to guess which +alternative is right. Wherever one current version agrees with the +ancestor, Emerge presumes that the other current version is a deliberate +change which should be kept in the merged version. Use the +@samp{with-ancestor} commands if you want to specify a common ancestor +text. These commands read three file or buffer names---variant A, +variant B, and the common ancestor. + + After the comparison is done and the buffers are prepared, the +interactive merging starts. You control the merging by typing special +@dfn{merge commands} in the merge buffer. The merge buffer shows you a +full merged text, not just differences. For each run of differences +between the input texts, you can choose which one of them to keep, or +edit them both together. + + The merge buffer uses a special major mode, Emerge mode, with commands +for making these choices. But you can also edit the buffer with +ordinary Emacs commands. + + At any given time, the attention of Emerge is focused on one +particular difference, called the @dfn{selected} difference. This +difference is marked off in the three buffers like this: + +@example +vvvvvvvvvvvvvvvvvvvv +@var{text that differs} +^^^^^^^^^^^^^^^^^^^^ +@end example + +@noindent +Emerge numbers all the differences sequentially and the mode +line always shows the number of the selected difference. + + Normally, the merge buffer starts out with the A version of the text. +But when the A version of a difference agrees with the common ancestor, +then the B version is initially preferred for that difference. + + Emerge leaves the merged text in the merge buffer when you exit. At +that point, you can save it in a file with @kbd{C-x C-w}. If you give a +numeric argument to @code{emerge-files} or +@code{emerge-files-with-ancestor}, it reads the name of the output file +using the minibuffer. (This is the last file name those commands read.) +Then exiting from Emerge saves the merged text in the output file. + + Normally, Emerge commands save the output buffer in its file when you +exit. If you abort Emerge with @kbd{C-]}, the Emerge command does not +save the output buffer, but you can save it yourself if you wish. + +@node Submodes of Emerge +@subsection Submodes of Emerge + + You can choose between two modes for giving merge commands: Fast mode +and Edit mode. In Fast mode, basic merge commands are single +characters, but ordinary Emacs commands are disabled. This is +convenient if you use only merge commands. In Edit mode, all merge +commands start with the prefix key @kbd{C-c C-c}, and the normal Emacs +commands are also available. This allows editing the merge buffer, but +slows down Emerge operations. + + Use @kbd{e} to switch to Edit mode, and @kbd{C-c C-c f} to switch to +Fast mode. The mode line indicates Edit and Fast modes with @samp{E} +and @samp{F}. + + Emerge has two additional submodes that affect how particular merge +commands work: Auto Advance mode and Skip Prefers mode. + + If Auto Advance mode is in effect, the @kbd{a} and @kbd{b} commands +advance to the next difference. This lets you go through the merge +faster as long as you simply choose one of the alternatives from the +input. The mode line indicates Auto Advance mode with @samp{A}. + + If Skip Prefers mode is in effect, the @kbd{n} and @kbd{p} commands +skip over differences in states prefer-A and prefer-B (@pxref{State of +Difference}). Thus you see only differences for which neither version +is presumed ``correct.'' The mode line indicates Skip Prefers mode with +@samp{S}. + +@findex emerge-auto-advance-mode +@findex emerge-skip-prefers-mode + Use the command @kbd{s a} (@code{emerge-auto-advance-mode}) to set or +clear Auto Advance mode. Use @kbd{s s} +(@code{emerge-skip-prefers-mode}) to set or clear Skip Prefers mode. +These commands turn on the mode with a positive argument, turns it off +with a negative or zero argument, and toggle the mode with no argument. + +@node State of Difference +@subsection State of a Difference + + In the merge buffer, a difference is marked with lines of @samp{v} and +@samp{^} characters. Each difference has one of these seven states: + +@table @asis +@item A +The difference is showing the A version. The @kbd{a} command always +produces this state; the mode line indicates it with @samp{A}. + +@item B +The difference is showing the B version. The @kbd{b} command always +produces this state; the mode line indicates it with @samp{B}. + +@item default-A +@itemx default-B +The difference is showing the A or the B state by default, because you +haven't made a choice. All differences start in the default-A state +(and thus the merge buffer is a copy of the A buffer), except those for +which one alternative is ``preferred'' (see below). + +When you select a difference, its state changes from default-A or +default-B to plain A or B. Thus, the selected difference never has +state default-A or default-B, and these states are never displayed in +the mode line. + +The command @kbd{d a} chooses default-A as the default state, and @kbd{d +b} chooses default-B. This chosen default applies to all differences +which you haven't ever selected and for which no alternative is preferred. +If you are moving through the merge sequentially, the differences you +haven't selected are those following the selected one. Thus, while +moving sequentially, you can effectively make the A version the default +for some sections of the merge buffer and the B version the default for +others by using @kbd{d a} and @kbd{d b} between sections. + +@item prefer-A +@itemx prefer-B +The difference is showing the A or B state because it is +@dfn{preferred}. This means that you haven't made an explicit choice, +but one alternative seems likely to be right because the other +alternative agrees with the common ancestor. Thus, where the A buffer +agrees with the common ancestor, the B version is preferred, because +chances are it is the one that was actually changed. + +These two states are displayed in the mode line as @samp{A*} and @samp{B*}. + +@item combined +The difference is showing a combination of the A and B states, as a +result of the @kbd{x c} or @kbd{x C} commands. + +Once a difference is in this state, the @kbd{a} and @kbd{b} commands +don't do anything to it unless you give them a numeric argument. + +The mode line displays this state as @samp{comb}. +@end table + +@node Merge Commands +@subsection Merge Commands + + Here are the Merge commands for Fast mode; in Edit mode, precede them +with @kbd{C-c C-c}: + +@table @kbd +@item p +Select the previous difference. + +@item n +Select the next difference. + +@item a +Choose the A version of this difference. + +@item b +Choose the B version of this difference. + +@item C-u @var{n} j +Select difference number @var{n}. + +@item . +Select the difference containing point. You can use this command in the +merge buffer or in the A or B buffer. + +@item q +Quit---finish the merge. + +@item C-] +Abort---exit merging and do not save the output. + +@item f +Go into Fast mode. (In Edit mode, this is actually @kbd{C-c C-c f}.) + +@item e +Go into Edit mode. + +@item l +Recenter (like @kbd{C-l}) all three windows. + +@item - +Specify part of a prefix numeric argument. + +@item @var{digit} +Also specify part of a prefix numeric argument. + +@item d a +Choose the A version as the default from here down in +the merge buffer. + +@item d b +Choose the B version as the default from here down in +the merge buffer. + +@item c a +Copy the A version of this difference into the kill ring. + +@item c b +Copy the B version of this difference into the kill ring. + +@item i a +Insert the A version of this difference at point. + +@item i b +Insert the B version of this difference at point. + +@item m +Put point and mark around the difference. + +@item ^ +Scroll all three windows down (like @kbd{M-v}). + +@item v +Scroll all three windows up (like @kbd{C-v}). + +@item < +Scroll all three windows left (like @kbd{C-x <}). + +@item > +Scroll all three windows right (like @kbd{C-x >}). + +@item | +Reset horizontal scroll on all three windows. + +@item x 1 +Shrink the merge window to one line. (Use @kbd{C-u l} to restore it +to full size.) + +@item x c +Combine the two versions of this difference (@pxref{Combining in +Emerge}). + +@item x f +Show the names of the files/buffers Emerge is operating on, in a Help +window. (Use @kbd{C-u l} to restore windows.) + +@item x j +Join this difference with the following one. +(@kbd{C-u x j} joins this difference with the previous one.) + +@item x s +Split this difference into two differences. Before you use this +command, position point in each of the three buffers at the place where +you want to split the difference. + +@item x t +Trim identical lines off the top and bottom of the difference. +Such lines occur when the A and B versions are +identical but differ from the ancestor version. +@end table + +@node Exiting Emerge +@subsection Exiting Emerge + + The @kbd{q} command (@code{emerge-quit}) finishes the merge, storing +the results into the output file if you specified one. It restores the +A and B buffers to their proper contents, or kills them if they were +created by Emerge and you haven't changed them. It also disables the +Emerge commands in the merge buffer, since executing them later could +damage the contents of the various buffers. + + @kbd{C-]} aborts the merge. This means exiting without writing the +output file. If you didn't specify an output file, then there is no +real difference between aborting and finishing the merge. + + If the Emerge command was called from another Lisp program, then its +return value is @code{t} for successful completion, or @code{nil} if you +abort. + +@node Combining in Emerge +@subsection Combining the Two Versions + + Sometimes you want to keep @emph{both} alternatives for a particular +difference. To do this, use @kbd{x c}, which edits the merge buffer +like this: + +@example +@group +#ifdef NEW +@var{version from A buffer} +#else /* not NEW */ +@var{version from B buffer} +#endif /* not NEW */ +@end group +@end example + +@noindent +@vindex emerge-combine-versions-template +While this example shows C preprocessor conditionals delimiting the two +alternative versions, you can specify the strings to use by setting +the variable @code{emerge-combine-versions-template} to a string of your +choice. In the string, @samp{%a} says where to put version A, and +@samp{%b} says where to put version B. The default setting, which +produces the results shown above, looks like this: + +@example +@group +"#ifdef NEW\n%a#else /* not NEW */\n%b#endif /* not NEW */\n" +@end group +@end example + +@node Fine Points of Emerge +@subsection Fine Points of Emerge + + During the merge, you mustn't try to edit the A and B buffers yourself. +Emerge modifies them temporarily, but ultimately puts them back the way +they were. + + You can have any number of merges going at once---just don't use any one +buffer as input to more than one merge at once, since the temporary +changes made in these buffers would get in each other's way. + + Starting Emerge can take a long time because it needs to compare the +files fully. Emacs can't do anything else until @code{diff} finishes. +Perhaps in the future someone will change Emerge to do the comparison in +the background when the input files are large---then you could keep on +doing other things with Emacs until Emerge is ready to accept +commands. + +@vindex emerge-startup-hook + After setting up the merge, Emerge runs the hook +@code{emerge-startup-hook} (@pxref{Hooks}). + +@node C Modes +@section C and Related Modes +@cindex C mode +@cindex Java mode +@cindex Pike mode +@cindex IDL mode +@cindex CORBA IDL mode +@cindex Objective C mode +@cindex C++ mode +@cindex mode, Java +@cindex mode, C +@cindex mode, Objective C +@cindex mode, CORBA IDL +@cindex mode, Pike + + This section describes special features available in C, C++, +Objective-C, Java, CORBA IDL, and Pike modes. When we say ``C mode and +related modes,'' those are the modes we mean. + +@menu +* Motion in C:: +* Electric C:: +* Hungry Delete:: +* Other C Commands:: +* Comments in C:: +@end menu + +@node Motion in C +@subsection C Mode Motion Commands + + This section describes commands for moving point, in C mode and +related modes. + +@table @code +@item C-c C-u +@kindex C-c C-u @r{(C mode)} +@findex c-up-conditional +Move point back to the containing preprocessor conditional, leaving the +mark behind. A prefix argument acts as a repeat count. With a negative +argument, move point forward to the end of the containing +preprocessor conditional. When going backwards, @code{#elif} is treated +like @code{#else} followed by @code{#if}. When going forwards, +@code{#elif} is ignored.@refill + +@item C-c C-p +@kindex C-c C-p @r{(C mode)} +@findex c-backward-conditional +Move point back over a preprocessor conditional, leaving the mark +behind. A prefix argument acts as a repeat count. With a negative +argument, move forward. + +@item C-c C-n +@kindex C-c C-n @r{(C mode)} +@findex c-forward-conditional +Move point forward across a preprocessor conditional, leaving the mark +behind. A prefix argument acts as a repeat count. With a negative +argument, move backward. + +@item M-a +@kindex ESC a +@findex c-beginning-of-statement +Move point to the beginning of the innermost C statement +(@code{c-beginning-of-statement}). If point is already at the beginning +of a statement, move to the beginning of the preceding statement. With +prefix argument @var{n}, move back @var{n} @minus{} 1 statements. + +If point is within a string or comment, or next to a comment (only +whitespace between them), this command moves by sentences instead of +statements. + +When called from a program, this function takes three optional +arguments: the numeric prefix argument, a buffer position limit +(don't move back before that place), and a flag that controls whether +to do sentence motion when inside of a comment. + +@item M-e +@kindex ESC e +@findex c-end-of-statement +Move point to the end of the innermost C statement; like @kbd{M-a} +except that it moves in the other direction (@code{c-end-of-statement}). + +@item M-x c-backward-into-nomenclature +@findex c-backward-into-nomenclature +Move point backward to beginning of a C++ nomenclature section or word. +With prefix argument @var{n}, move @var{n} times. If @var{n} is +negative, move forward. C++ nomenclature means a symbol name in the +style of NamingSymbolsWithMixedCaseAndNoUnderlines; each capital letter +begins a section or word. + +In the GNU project, we recommend using underscores to separate words +within an identifier in C or C++, rather than using case distinctions. + +@item M-x c-forward-into-nomenclature +@findex c-forward-into-nomenclature +Move point forward to end of a C++ nomenclature section or word. +With prefix argument @var{n}, move @var{n} times. +@end table + +@node Electric C +@subsection Electric C Characters + + In C mode and related modes, certain printing characters are +``electric''---in addition to inserting themselves, they also reindent +the current line and may insert newlines. This feature is controlled by +the variable @code{c-auto-newline}. The ``electric'' characters are +@kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, @kbd{;}, @kbd{,}, @kbd{<}, +@kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and @kbd{)}. + + Electric characters insert newlines only when the @dfn{auto-newline} +feature is enabled (indicated by @samp{/a} in the mode line after the +mode name). This feature is controlled by the variable +@code{c-auto-newline}. You can turn this feature on or off with the +command @kbd{C-c C-a}: + +@table @kbd +@item C-c C-a +@kindex C-c C-a @r{(C mode)} +@findex c-toggle-auto-state +Toggle the auto-newline feature (@code{c-toggle-auto-state}). With a +prefix argument, this command turns the auto-newline feature on if the +argument is positive, and off if it is negative. +@end table + + The colon character is electric because that is appropriate for a +single colon. But when you want to insert a double colon in C++, the +electric behavior of colon is inconvenient. You can insert a double +colon with no reindentation or newlines by typing @kbd{C-c :}: + +@table @kbd +@item C-c : +@kindex C-c : @r{(C mode)} +@findex c-scope-operator +Insert a double colon scope operator at point, without reindenting the +line or adding any newlines (@code{c-scope-operator}). +@end table + + The electric @kbd{#} key reindents the line if it appears to be the +beginning of a preprocessor directive. This happens when the value of +@code{c-electric-pound-behavior} is @code{(alignleft)}. You can turn +this feature off by setting @code{c-electric-pound-behavior} to +@code{nil}. + + The variable @code{c-hanging-braces-alist} controls the insertion of +newlines before and after inserted braces. It is an association list +with elements of the following form: @code{(@var{syntactic-symbol} +. @var{nl-list})}. Most of the syntactic symbols that appear in +@code{c-offsets-alist} are meaningful here as well. + + The list @var{nl-list} may contain either of the symbols +@code{before} or @code{after}, or both; or it may be @code{nil}. When a +brace is inserted, the syntactic context it defines is looked up in +@code{c-hanging-braces-alist}; if it is found, the @var{nl-list} is used +to determine where newlines are inserted: either before the brace, +after, or both. If not found, the default is to insert a newline both +before and after braces. + + The variable @code{c-hanging-colons-alist} controls the insertion of +newlines before and after inserted colons. It is an association list +with elements of the following form: @code{(@var{syntactic-symbol} +. @var{nl-list})}. The list @var{nl-list} may contain either of the +symbols @code{before} or @code{after}, or both; or it may be @code{nil}. + + When a colon is inserted, the syntactic symbol it defines is looked +up in this list, and if found, the @var{nl-list} is used to determine +where newlines are inserted: either before the brace, after, or both. +If the syntactic symbol is not found in this list, no newlines are +inserted. + + Electric characters can also delete newlines automatically when the +auto-newline feature is enabled. This feature makes auto-newline more +acceptable, by deleting the newlines in the most common cases where you +do not want them. Emacs can recognize several cases in which deleting a +newline might be desirable; by setting the variable +@code{c-cleanup-list}, you can specify @emph{which} of these cases that +should happen. The variable's value is a list of symbols, each +describing one case for possible deletion of a newline. Here are the +meaningful symbols, and their meanings: + +@table @code +@item brace-catch-brace +Clean up @samp{@} catch (@var{condition}) @{} constructs by placing the +entire construct on a single line. The clean-up occurs when you type +the @samp{@{}, if there is nothing between the braces aside from +@code{catch} and @var{condition}. + +@item brace-else-brace +Clean up @samp{@} else @{} constructs by placing the entire construct on +a single line. The clean-up occurs when you type the @samp{@{} after +the @code{else}, but only if there is nothing but white space between +the braces and the @code{else}. + +@item brace-elseif-brace +Clean up @samp{@} else if (@dots{}) @{} constructs by placing the entire +construct on a single line. The clean-up occurs when you type the +@samp{@{}, if there is nothing but white space between the @samp{@}} and +@samp{@{} aside from the keywords and the @code{if}-condition. + +@item empty-defun-braces +Clean up empty defun braces by placing the braces on the same +line. Clean-up occurs when you type the closing brace. + +@item defun-close-semi +Clean up the semicolon after a @code{struct} or similar type +declaration, by placing the semicolon on the same line as the closing +brace. Clean-up occurs when you type the semicolon. + +@item list-close-comma +Clean up commas following braces in array and aggregate +initializers. Clean-up occurs when you type the comma. + +@item scope-operator +Clean up double colons which may designate a C++ scope operator, by +placing the colons together. Clean-up occurs when you type the second +colon, but only when the two colons are separated by nothing but +whitespace. +@end table + +@node Hungry Delete +@subsection Hungry Delete Feature in C + + When the @dfn{hungry-delete} feature is enabled (indicated by +@samp{/h} or @samp{/ah} in the mode line after the mode name), a single +@key{DEL} command deletes all preceding whitespace, not just one space. +To turn this feature on or off, use @kbd{C-c C-d}: + +@table @kbd +@item C-c C-d +@kindex C-c C-d @r{(C mode)} +@findex c-toggle-hungry-state +Toggle the hungry-delete feature (@code{c-toggle-hungry-state}). With a +prefix argument, this command turns the hungry-delete feature on if the +argument is positive, and off if it is negative. + +@item C-c C-t +@kindex C-c C-t @r{(C mode)} +@findex c-toggle-auto-hungry-state +Toggle the auto-newline and hungry-delete features, both at once +(@code{c-toggle-auto-hungry-state}). +@end table + +@vindex c-hungry-delete-key + The variable @code{c-hungry-delete-key} controls whether the +hungry-delete feature is enabled. + +@node Other C Commands +@subsection Other Commands for C Mode + +@table @kbd +@item C-M-h +@findex c-mark-function +@kindex C-M-h @r{(C mode)} +Put mark at the end of a function definition, and put point at the +beginning (@code{c-mark-function}). + +@item M-q +@kindex M-q @r{(C mode)} +@findex c-fill-paragraph +Fill a paragraph, handling C and C++ comments (@code{c-fill-paragraph}). +If any part of the current line is a comment or within a comment, this +command fills the comment or the paragraph of it that point is in, +preserving the comment indentation and comment delimiters. + +@item C-c C-e +@cindex macro expansion in C +@cindex expansion of C macros +@findex c-macro-expand +@kindex C-c C-e @r{(C mode)} +Run the C preprocessor on the text in the region, and show the result, +which includes the expansion of all the macro calls +(@code{c-macro-expand}). The buffer text before the region is also +included in preprocessing, for the sake of macros defined there, but the +output from this part isn't shown. + +When you are debugging C code that uses macros, sometimes it is hard to +figure out precisely how the macros expand. With this command, you +don't have to figure it out; you can see the expansions. + +@item C-c C-\ +@findex c-backslash-region +@kindex C-c C-\ @r{(C mode)} +Insert or align @samp{\} characters at the ends of the lines of the +region (@code{c-backslash-region}). This is useful after writing or +editing a C macro definition. + +If a line already ends in @samp{\}, this command adjusts the amount of +whitespace before it. Otherwise, it inserts a new @samp{\}. However, +the last line in the region is treated specially; no @samp{\} is +inserted on that line, and any @samp{\} there is deleted. + +@item M-x cpp-highlight-buffer +@cindex preprocessor highlighting +@findex cpp-highlight-buffer +Highlight parts of the text according to its preprocessor conditionals. +This command displays another buffer named @samp{*CPP Edit*}, which +serves as a graphic menu for selecting how to display particular kinds +of conditionals and their contents. After changing various settings, +click on @samp{[A]pply these settings} (or go to that buffer and type +@kbd{a}) to rehighlight the C mode buffer accordingly. + +@item C-c C-s +@findex c-show-syntactic-information +@kindex C-c C-s @r{(C mode)} +Display the syntactic information about the current source line +(@code{c-show-syntactic-information}). This is the information that +directs how the line is indented. +@end table + +@node Comments in C +@subsection Comments in C Modes + + C mode and related modes use a number of variables for controlling +comment format. + +@table @code +@item c-comment-only-line-offset +@vindex c-comment-only-line-offset +Extra offset for line which contains only the start of a comment. It +can be either an integer or a cons cell of the form +@code{(@var{non-anchored-offset} . @var{anchored-offset})}, where +@var{non-anchored-offset} is the amount of offset given to +non-column-zero anchored comment-only lines, and @var{anchored-offset} +is the amount of offset to give column-zero anchored comment-only lines. +Just an integer as value is equivalent to @code{(@var{val} . 0)}. + +@item c-comment-start-regexp +@vindex c-comment-start-regexp +This buffer-local variable specifies how to recognize the start of a comment. + +@item c-hanging-comment-ender-p +@vindex c-hanging-comment-ender-p +If this variable is @code{nil}, @code{c-fill-paragraph} leaves the +comment terminator of a block comment on a line by itself. The default +value is @code{t}, which puts the comment-end delimiter @samp{*/} at the +end of the last line of the comment text. + +@item c-hanging-comment-starter-p +@vindex c-hanging-comment-starter-p +If this variable is @code{nil}, @code{c-fill-paragraph} leaves the +starting delimiter of a block comment on a line by itself. The default +value is @code{t}, which puts the comment-start delimiter @samp{/*} at +the beginning of the first line of the comment text. +@end table + +@node Fortran +@section Fortran Mode +@cindex Fortran mode +@cindex mode, Fortran + + Fortran mode provides special motion commands for Fortran statements and +subprograms, and indentation commands that understand Fortran conventions +of nesting, line numbers and continuation statements. Fortran mode has +its own Auto Fill mode that breaks long lines into proper Fortran +continuation lines. + + Special commands for comments are provided because Fortran comments +are unlike those of other languages. Built-in abbrevs optionally save +typing when you insert Fortran keywords. + +@findex fortran-mode + Use @kbd{M-x fortran-mode} to switch to this major mode. This command +runs the hook @code{fortran-mode-hook} (@pxref{Hooks}). + +@menu +* Motion: Fortran Motion. Moving point by statements or subprograms. +* Indent: Fortran Indent. Indentation commands for Fortran. +* Comments: Fortran Comments. Inserting and aligning comments. +* Autofill: Fortran Autofill. Auto fill minor mode for Fortran. +* Columns: Fortran Columns. Measuring columns for valid Fortran. +* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. +* Misc: Fortran Misc. Other Fortran mode features. +@end menu + +@node Fortran Motion +@subsection Motion Commands + + Fortran mode provides special commands to move by subprograms (functions +and subroutines) and by statements. There is also a command to put the +region around one subprogram, convenient for killing it or moving it. + +@kindex C-M-a @r{(Fortran mode)} +@kindex C-M-e @r{(Fortran mode)} +@kindex C-M-h @r{(Fortran mode)} +@kindex C-c C-p @r{(Fortran mode)} +@kindex C-c C-n @r{(Fortran mode)} +@findex beginning-of-fortran-subprogram +@findex end-of-fortran-subprogram +@findex mark-fortran-subprogram +@findex fortran-previous-statement +@findex fortran-next-statement + +@table @kbd +@item C-M-a +Move to beginning of subprogram +(@code{beginning-of-fortran-subprogram}). +@item C-M-e +Move to end of subprogram (@code{end-of-fortran-subprogram}). +@item C-M-h +Put point at beginning of subprogram and mark at end +(@code{mark-fortran-subprogram}). +@item C-c C-n +Move to beginning of current or next statement +(@code{fortran-next-statement}). +@item C-c C-p +Move to beginning of current or previous statement +(@code{fortran-previous-statement}). +@end table + +@node Fortran Indent +@subsection Fortran Indentation + + Special commands and features are needed for indenting Fortran code in +order to make sure various syntactic entities (line numbers, comment line +indicators and continuation line flags) appear in the columns that are +required for standard Fortran. + +@menu +* Commands: ForIndent Commands. Commands for indenting Fortran. +* Contline: ForIndent Cont. How continuation lines indent. +* Numbers: ForIndent Num. How line numbers auto-indent. +* Conv: ForIndent Conv. Conventions you must obey to avoid trouble. +* Vars: ForIndent Vars. Variables controlling Fortran indent style. +@end menu + +@node ForIndent Commands +@subsubsection Fortran Indentation Commands + +@table @kbd +@item @key{TAB} +Indent the current line (@code{fortran-indent-line}). +@item C-j +Indent the current and start a new indented line +(@code{fortran-indent-new-line}). +@item C-M-j +Break the current line and set up a continuation line. +@item M-^ +Join this line to the previous line. +@item C-M-q +Indent all the lines of the subprogram point is in +(@code{fortran-indent-subprogram}). +@end table + +@findex fortran-indent-line + Fortran mode redefines @key{TAB} to reindent the current line for +Fortran (@code{fortran-indent-line}). This command indents line numbers +and continuation markers to their required columns, and independently +indents the body of the statement based on its nesting in the program. + +@kindex C-j @r{(Fortran mode)} +@findex fortran-indent-new-line + The key @kbd{C-j} runs the command @code{fortran-indent-new-line}, +which reindents the current line then makes and indents a new line. +This command is useful to reindent the closing statement of @samp{do} +loops and other blocks before starting a new line. + +@kindex C-M-q @r{(Fortran mode)} +@findex fortran-indent-subprogram + The key @kbd{C-M-q} runs @code{fortran-indent-subprogram}, a command +to reindent all the lines of the Fortran subprogram (function or +subroutine) containing point. + +@kindex C-M-j @r{(Fortran mode)} +@findex fortran-split-line + The key @kbd{C-M-j} runs @code{fortran-split-line}, which splits +a line in the appropriate fashion for Fortran. In a non-comment line, +the second half becomes a continuation line and is indented +accordingly. In a comment line, both halves become separate comment +lines. + +@kindex M-^ @r{(Fortran mode)} +@findex fortran-join-line + @kbd{M-^} runs the command @code{fortran-join-line}, which is more or +less the inverse of @code{fortran-split-line}. It joins the current +line to the previous line in a suitable way for Fortran code. + +@node ForIndent Cont +@subsubsection Continuation Lines +@cindex Fortran continuation lines + +@vindex fortran-continuation-string + Most modern Fortran compilers allow two ways of writing continuation +lines. If the first non-space character on a line is in column 5, then +that line is a continuation of the previous line. We call this +@dfn{fixed format}. (In GNU Emacs we always count columns from 0.) The +variable @code{fortran-continuation-string} specifies what character to +put on column 5. A line that starts with a tab character followed by +any digit except @samp{0} is also a continuation line. We call this +style of continuation @dfn{tab format}. + +@vindex indent-tabs-mode @r{(Fortran mode)} + Fortran mode can make either style of continuation line, but you +must specify which one you prefer. The value of the variable +@code{indent-tabs-mode} controls the choice: @code{nil} for fixed +format, and non-@code{nil} for tab format. You can tell which style +is presently in effect by the presence or absence of the string +@samp{Tab} in the mode line. + + If the text on a line starts with the conventional Fortran +continuation marker @samp{$}, or if it begins with any non-whitespace +character in column 5, Fortran mode treats it as a continuation line. +When you indent a continuation line with @key{TAB}, it converts the line +to the current continuation style. When you split a Fortran statement +with @kbd{C-M-j}, the continuation marker on the newline is created +according to the continuation style. + + The setting of continuation style affects several other aspects of +editing in Fortran mode. In fixed format mode, the minimum column +number for the body of a statement is 6. Lines inside of Fortran +blocks that are indented to larger column numbers always use only the +space character for whitespace. In tab format mode, the minimum +column number for the statement body is 8, and the whitespace before +column 8 must always consist of one tab character. + +@vindex fortran-tab-mode-default +@vindex fortran-analyze-depth + When you enter Fortran mode for an existing file, it tries to deduce the +proper continuation style automatically from the file contents. The first +line that begins with either a tab character or six spaces determines the +choice. The variable @code{fortran-analyze-depth} specifies how many lines +to consider (at the beginning of the file); if none of those lines +indicates a style, then the variable @code{fortran-tab-mode-default} +specifies the style. If it is @code{nil}, that specifies fixed format, and +non-@code{nil} specifies tab format. + +@node ForIndent Num +@subsubsection Line Numbers + + If a number is the first non-whitespace in the line, Fortran +indentation assumes it is a line number and moves it to columns 0 +through 4. (Columns always count from 0 in GNU Emacs.) + +@vindex fortran-line-number-indent + Line numbers of four digits or less are normally indented one space. +The variable @code{fortran-line-number-indent} controls this; it +specifies the maximum indentation a line number can have. Line numbers +are indented to right-justify them to end in column 4 unless that would +require more than this maximum indentation. The default value of the +variable is 1. + +@vindex fortran-electric-line-number + Simply inserting a line number is enough to indent it according to +these rules. As each digit is inserted, the indentation is recomputed. +To turn off this feature, set the variable +@code{fortran-electric-line-number} to @code{nil}. Then inserting line +numbers is like inserting anything else. + +@node ForIndent Conv +@subsubsection Syntactic Conventions + + Fortran mode assumes that you follow certain conventions that simplify +the task of understanding a Fortran program well enough to indent it +properly: + +@itemize @bullet +@item +Two nested @samp{do} loops never share a @samp{continue} statement. + +@item +Fortran keywords such as @samp{if}, @samp{else}, @samp{then}, @samp{do} +and others are written without embedded whitespace or line breaks. + +Fortran compilers generally ignore whitespace outside of string +constants, but Fortran mode does not recognize these keywords if they +are not contiguous. Constructs such as @samp{else if} or @samp{end do} +are acceptable, but the second word should be on the same line as the +first and not on a continuation line. +@end itemize + +@noindent +If you fail to follow these conventions, the indentation commands may +indent some lines unaesthetically. However, a correct Fortran program +retains its meaning when reindented even if the conventions are not +followed. + +@node ForIndent Vars +@subsubsection Variables for Fortran Indentation + +@vindex fortran-do-indent +@vindex fortran-if-indent +@vindex fortran-structure-indent +@vindex fortran-continuation-indent +@vindex fortran-check-all-num@dots{} +@vindex fortran-minimum-statement-indent@dots{} + Several additional variables control how Fortran indentation works: + +@table @code +@item fortran-do-indent +Extra indentation within each level of @samp{do} statement (default 3). + +@item fortran-if-indent +Extra indentation within each level of @samp{if} statement (default 3). +This value is also used for extra indentation within each level of the +Fortran 90 @samp{where} statement. + +@item fortran-structure-indent +Extra indentation within each level of @samp{structure}, @samp{union}, or +@samp{map} statements (default 3). + +@item fortran-continuation-indent +Extra indentation for bodies of continuation lines (default 5). + +@item fortran-check-all-num-for-matching-do +If this is @code{nil}, indentation assumes that each @samp{do} statement +ends on a @samp{continue} statement. Therefore, when computing +indentation for a statement other than @samp{continue}, it can save time +by not checking for a @samp{do} statement ending there. If this is +non-@code{nil}, indenting any numbered statement must check for a +@samp{do} that ends there. The default is @code{nil}. + +@item fortran-blink-matching-if +If this is @code{t}, indenting an @samp{endif} statement moves the +cursor momentarily to the matching @samp{if} statement to show where it +is. The default is @code{nil}. + +@item fortran-minimum-statement-indent-fixed +Minimum indentation for fortran statements when using fixed format +continuation line style. Statement bodies are never indented less than +this much. The default is 6. + +@item fortran-minimum-statement-indent-tab +Minimum indentation for fortran statements for tab format continuation line +style. Statement bodies are never indented less than this much. The +default is 8. +@end table + +@node Fortran Comments +@subsection Fortran Comments + + The usual Emacs comment commands assume that a comment can follow a line +of code. In Fortran, the standard comment syntax requires an entire line +to be just a comment. Therefore, Fortran mode replaces the standard Emacs +comment commands and defines some new variables. + + Fortran mode can also handle a nonstandard comment syntax where comments +start with @samp{!} and can follow other text. Because only some Fortran +compilers accept this syntax, Fortran mode will not insert such comments +unless you have said in advance to do so. To do this, set the variable +@code{comment-start} to @samp{"!"} (@pxref{Variables}). + +@table @kbd +@item M-; +Align comment or insert new comment (@code{fortran-comment-indent}). + +@item C-x ; +Applies to nonstandard @samp{!} comments only. + +@item C-c ; +Turn all lines of the region into comments, or (with argument) turn them back +into real code (@code{fortran-comment-region}). +@end table + + @kbd{M-;} in Fortran mode is redefined as the command +@code{fortran-comment-indent}. Like the usual @kbd{M-;} command, this +recognizes any kind of existing comment and aligns its text appropriately; +if there is no existing comment, a comment is inserted and aligned. But +inserting and aligning comments are not the same in Fortran mode as in +other modes. + + When a new comment must be inserted, if the current line is blank, a +full-line comment is inserted. On a non-blank line, a nonstandard @samp{!} +comment is inserted if you have said you want to use them. Otherwise a +full-line comment is inserted on a new line before the current line. + + Nonstandard @samp{!} comments are aligned like comments in other +languages, but full-line comments are different. In a standard full-line +comment, the comment delimiter itself must always appear in column zero. +What can be aligned is the text within the comment. You can choose from +three styles of alignment by setting the variable +@code{fortran-comment-indent-style} to one of these values: + +@vindex fortran-comment-indent-style +@vindex fortran-comment-line-extra-indent +@table @code +@item fixed +Align the text at a fixed column, which is the sum of +@code{fortran-comment-line-extra-indent} and the minimum statement +indentation. This is the default. + +The minimum statement indentation is +@code{fortran-minimum-statement-indent-fixed} for fixed format +continuation line style and @code{fortran-minimum-statement-indent-tab} +for tab format style. + +@item relative +Align the text as if it were a line of code, but with an additional +@code{fortran-comment-line-extra-indent} columns of indentation. + +@item nil +Don't move text in full-line comments automatically at all. +@end table + +@vindex fortran-comment-indent-char + In addition, you can specify the character to be used to indent within +full-line comments by setting the variable +@code{fortran-comment-indent-char} to the single-character string you want +to use. + +@vindex comment-line-start +@vindex comment-line-start-skip + Fortran mode introduces two variables @code{comment-line-start} and +@code{comment-line-start-skip}, which play for full-line comments the same +roles played by @code{comment-start} and @code{comment-start-skip} for +ordinary text-following comments. Normally these are set properly by +Fortran mode, so you do not need to change them. + + The normal Emacs comment command @kbd{C-x ;} has not been redefined. If +you use @samp{!} comments, this command can be used with them. Otherwise +it is useless in Fortran mode. + +@kindex C-c ; @r{(Fortran mode)} +@findex fortran-comment-region +@vindex fortran-comment-region + The command @kbd{C-c ;} (@code{fortran-comment-region}) turns all the +lines of the region into comments by inserting the string @samp{C$$$} at +the front of each one. With a numeric argument, it turns the region +back into live code by deleting @samp{C$$$} from the front of each line +in it. The string used for these comments can be controlled by setting +the variable @code{fortran-comment-region}. Note that here we have an +example of a command and a variable with the same name; these two uses +of the name never conflict because in Lisp and in Emacs it is always +clear from the context which one is meant. + +@node Fortran Autofill +@subsection Fortran Auto Fill Mode + + Fortran Auto Fill mode is a minor mode which automatically splits +Fortran statements as you insert them when they become too wide. +Splitting a statement involves making continuation lines using +@code{fortran-continuation-string} (@pxref{ForIndent Cont}). This +splitting happens when you type @key{SPC}, @key{RET}, or @key{TAB}, and +also in the Fortran indentation commands. + +@findex fortran-auto-fill-mode + @kbd{M-x fortran-auto-fill-mode} turns Fortran Auto Fill mode on if it +was off, or off if it was on. This command works the same as @kbd{M-x +auto-fill-mode} does for normal Auto Fill mode (@pxref{Filling}). A +positive numeric argument turns Fortran Auto Fill mode on, and a +negative argument turns it off. You can see when Fortran Auto Fill mode +is in effect by the presence of the word @samp{Fill} in the mode line, +inside the parentheses. Fortran Auto Fill mode is a minor mode, turned +on or off for each buffer individually. @xref{Minor Modes}. + +@vindex fortran-break-before-delimiters + Fortran Auto Fill mode breaks lines at spaces or delimiters when the +lines get longer than the desired width (the value of @code{fill-column}). +The delimiters that Fortran Auto Fill mode may break at are @samp{,}, +@samp{'}, @samp{+}, @samp{-}, @samp{/}, @samp{*}, @samp{=}, and @samp{)}. +The line break comes after the delimiter if the variable +@code{fortran-break-before-delimiters} is @code{nil}. Otherwise (and by +default), the break comes before the delimiter. + + By default, Fortran Auto Fill mode is not enabled. If you want this +feature turned on permanently, add a hook function to +@code{fortran-mode-hook} to execute @code{(fortran-auto-fill-mode 1)}. +@xref{Hooks}. + +@node Fortran Columns +@subsection Checking Columns in Fortran + +@table @kbd +@item C-c C-r +Display a ``column ruler'' momentarily above the current line +(@code{fortran-column-ruler}). +@item C-c C-w +Split the current window horizontally temporarily so that it is 72 +columns wide. This may help you avoid making lines longer than the +72-character limit that some Fortran compilers impose +(@code{fortran-window-create-momentarily}). +@end table + +@kindex C-c C-r @r{(Fortran mode)} +@findex fortran-column-ruler +@vindex fortran-column-ruler + The command @kbd{C-c C-r} (@code{fortran-column-ruler}) shows a column +ruler momentarily above the current line. The comment ruler is two lines +of text that show you the locations of columns with special significance in +Fortran programs. Square brackets show the limits of the columns for line +numbers, and curly brackets show the limits of the columns for the +statement body. Column numbers appear above them. + + Note that the column numbers count from zero, as always in GNU Emacs. +As a result, the numbers may be one less than those you are familiar +with; but the positions they indicate in the line are standard for +Fortran. + + The text used to display the column ruler depends on the value of +the variable @code{indent-tabs-mode}. If @code{indent-tabs-mode} is +@code{nil}, then the value of the variable +@code{fortran-column-ruler-fixed} is used as the column ruler. +Otherwise, the variable @code{fortran-column-ruler-tab} is displayed. +By changing these variables, you can change the column ruler display. + +@kindex C-c C-w @r{(Fortran mode)} +@findex fortran-window-create + For even more help, use @kbd{C-c C-w} (@code{fortran-window-create}), a +command which splits the current window horizontally, making a window 72 +columns wide. By editing in this window you can immediately see when you +make a line too wide to be correct Fortran. + +@node Fortran Abbrev +@subsection Fortran Keyword Abbrevs + + Fortran mode provides many built-in abbrevs for common keywords and +declarations. These are the same sort of abbrev that you can define +yourself. To use them, you must turn on Abbrev mode. @xref{Abbrevs}. + + The built-in abbrevs are unusual in one way: they all start with a +semicolon. You cannot normally use semicolon in an abbrev, but Fortran +mode makes this possible by changing the syntax of semicolon to ``word +constituent.'' + + For example, one built-in Fortran abbrev is @samp{;c} for +@samp{continue}. If you insert @samp{;c} and then insert a punctuation +character such as a space or a newline, the @samp{;c} expands automatically +to @samp{continue}, provided Abbrev mode is enabled.@refill + + Type @samp{;?} or @samp{;C-h} to display a list of all the built-in +Fortran abbrevs and what they stand for. + +@node Fortran Misc +@subsection Other Fortran Mode Commands + +@table @kbd +@item C-x n d +Narrow to the current Fortran subprogram. +@end table + +@kindex C-x n d @r{(Fortran mode)} +@findex fortran-narrow-to-subprogram + Fortran mode redefines the key @kbd{C-x n d} to run the command +@code{fortran-narrow-to-subprogram}, which is the Fortran analogue +of the key's usual definition. It narrows the buffer to the subprogram +containing point. + +@node Asm Mode +@section Asm Mode + +@cindex Asm mode +Asm mode is a major mode for editing files of assembler code. It +defines these commands: + +@table @kbd +@item @key{TAB} +@code{tab-to-tab-stop}. +@item C-j +Insert a newline and then indent using @code{tab-to-tab-stop}. +@item : +Insert a colon and then remove the indentation from before the label +preceding colon. Then do @code{tab-to-tab-stop}. +@item ; +Insert or align a comment. +@end table + + The variable @code{asm-comment-char} specifies which character +starts comments in assembler syntax. diff --git a/man/reftex.texi b/man/reftex.texi new file mode 100644 index 00000000000..8afb27d6b0a --- /dev/null +++ b/man/reftex.texi @@ -0,0 +1,4992 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename ../info/reftex +@settitle RefTeX User Manual +@dircategory Editors +@direntry +* RefTeX: (reftex). Emacs support for LaTeX cross-references and citations. +@end direntry +@synindex ky cp +@syncodeindex vr cp +@syncodeindex fn cp +@set VERSION 4.6 +@set EDITION 4.6 +@set DATE September 1999 +@set AUTHOR Carsten Dominik +@set AUTHOR-EMAIL dominik@@strw.leidenuniv.nl +@set MAINTAINER Carsten Dominik +@set MAINTAINER-EMAIL dominik@@strw.leidenuniv.nl +@c %**end of header +@finalout + +@c Macro definitions + +@c Subheadings inside a table. Need a difference between info and the rest. +@macro tablesubheading{text} +@ifinfo +@subsubheading \text\ +@end ifinfo +@ifnotinfo +@item @b{\text\} +@end ifnotinfo +@end macro + +@ifinfo +This file documents @b{Ref@TeX{}}, a package to do labels, references, +citations and indices for LaTeX documents with Emacs.@refill + +This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for +@b{Ref@TeX{}} @value{VERSION}@refill + +Copyright (c) 1997, 1998, 1999 Free Software Foundation, Inc. + +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 a 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 +Permission is granted to copy and distribute modified +versions of this manual under the conditions for +verbatim copying, provided that the entire resulting +derive work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute +translations of this manual into another language, +under the above conditions for modified versions, +except that this permission notice may be stated in a +translation approved by the Free Software Foundation. +@end ifinfo + +@titlepage +@title Ref@TeX{} User Manual +@subtitle Support for LaTeX labels, references, citations and index entries with GNU Emacs +@subtitle Edition @value{EDITION}, @value{DATE} + +@author by Carsten Dominik +@page +Copyright @copyright{} 1997, 1998 Free Software Foundation, Inc. + +@sp 2 +This is edition @value{EDITION} of the @cite{Ref@TeX{} User Manual} for +@b{Ref@TeX{}} version @value{VERSION}, @value{DATE}.@refill + +@sp 2 + +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. + +Permission is granted to copy and distribute modified +versions of this manual under the conditions for +verbatim copying, provided that the entire resulting +derive work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute +translations of this manual into another language, +under the above conditions for modified versions, +except that this permission notice may be stated in a +translation approved by the Free Software Foundation. + +@end titlepage +@page + +@ifinfo +@node Top,,,(dir) + +@b{Ref@TeX{}} is a package for managing Labels, References, +Citations and index entries with GNU Emacs.@refill + +Don't be discouraged by the size of this manual, which covers +@b{Ref@TeX{}} in great depth. All you need to know to use +@b{Ref@TeX{}} can be summarized on two pages (@pxref{RefTeX in a +Nutshell}). You can go back later to other parts of this document when +needed.@refill + +@menu +* Introduction:: Quick-Start information. + +* Table of Contents:: A Tool to move around quickly. +* Labels and References:: Creating and referencing labels. +* Citations:: Creating Citations. +* Index Support:: Creating and Checking Index Entries. +* Viewing Cross-References:: Who references or cites what? + +* RefTeXs Menu:: The Ref menu in the menubar. +* Keybindings:: The default keybindings. +* Faces:: Fontification of RefTeX's buffers. +* Multifile Documents:: Document spread over many files. +* Language Support:: How to support other languages. +* Finding Files:: Included TeX files and BibTeX .bib files. +* AUCTeX:: Cooperation with AUCTeX. +* Optimizations:: When RefTeX is too slow. +* Problems and Work-Arounds:: First Aid. +* Imprint:: Author, Web-site, Thanks + +* Commands:: Which are the available commands. +* Options:: How to extend and configure RefTeX. +* Keymaps and Hooks:: For customization. +* Changes:: A List of recent changes to RefTeX. + +The Index + +* Index:: The full index. + +@detailmenu + +Introduction + +* Installation:: How to install and activate RefTeX. +* RefTeX in a Nutshell:: A brief summary and quick guide. + +Labels and References + +* Creating Labels:: +* Referencing Labels:: +* Builtin Label Environments:: The environments RefTeX knows about. +* Defining Label Environments:: ... and environments it doesn't. +* Reference Info:: View the label corresponding to a \ref. +* xr (LaTeX package):: References to external documents. +* varioref (LaTeX package):: How to create \vref instead of \ref. +* fancyref (LaTeX package):: How to create \fref instead of \ref. + +Defining Label Environments + +* Theorem and Axiom:: Defined with @code{\newenvironment}. +* Quick Equation:: When a macro sets the label type. +* Figure Wrapper:: When a macro argument is a label. +* Adding Magic Words:: Other words for other languages. +* Using \eqref:: How to switch to this AMS-LaTeX macro. +* Non-Standard Environments:: Environments without \begin and \end +* Putting it Together:: How to combine many entries. + +Citations + +* Creating Citations:: How to create them. +* Citation Styles:: Natbib, Harvard, Chicago and Co. +* Citation Info:: View the corresponding database entry. +* Chapterbib and Bibunits:: Multiple bibliographies in a Document. +* Citations Outside LaTeX:: How to make citations in Emails etc. + +Index Support + +* Creating Index Entries:: +* Displaying and Editing the Index:: +* Builtin Index Macros:: The index macros RefTeX knows about. +* Defining Index Macros:: ... and macros it doesn't. + +AUCTeX + +* AUCTeX-RefTeX Interface:: How both packages work together +* Style Files:: AUCTeX's style files can support RefTeX +* Bib-Cite:: Hypertext reading of a document + +Options, Keymaps, Hooks + +* Options (Table of Contents):: +* Options (Defining Label Environments):: +* Options (Creating Labels):: +* Options (Referencing Labels):: +* Options (Creating Citations):: +* Options (Index Support):: +* Options (Viewing Cross-References):: +* Options (Finding Files):: +* Options (Optimizations):: +* Options (Fontification):: +* Options (Misc):: + +@end detailmenu +@end menu + +@end ifinfo + +@node Introduction, Table of Contents, , Top +@chapter Introduction +@cindex Introduction + +@b{Ref@TeX{}} is a specialized package for support of labels, +references, citations, and the index in LaTeX. @b{Ref@TeX{}} wraps +itself round 4 LaTeX macros: @code{\label}, @code{\ref}, @code{\cite}, +and @code{\index}. Using these macros usually requires looking up +different parts of the document and searching through BibTeX database +files. @b{Ref@TeX{}} automates these time--consuming tasks almost +entirely. It also provides functions to display the structure of a +document and to move around in this structure quickly.@refill + +@iftex +Don't be discouraged by the size of this manual, which covers @b{Ref@TeX{}} +in great depth. All you need to know to use @b{Ref@TeX{}} can be +summarized on two pages (@pxref{RefTeX in a Nutshell}). You can go +back later to other parts of this document when needed. +@end iftex + +@xref{Imprint}, for information about who to contact for help, bug +reports or suggestions. + +@menu +* Installation:: How to install and activate RefTeX. +* RefTeX in a Nutshell:: A brief summary and quick guide. +@end menu + +@node Installation, RefTeX in a Nutshell, , Introduction +@section Installation +@cindex Installation + +@b{Ref@TeX{}} is bundled and pre--installed with Emacs since version 20.2. +It was also bundled and pre--installed with XEmacs 19.16--20.x. XEmacs +21.x users want to install the corresponding plug-in package which is +available from the +@uref{ftp://ftp.xemacs.org/pub/xemacs/packages/,XEmacs ftp site}. See +the XEmacs 21.x documentation on package installation for +details.@refill + +Users of earlier Emacs distributions (including Emacs 19) can get a copy +of the @b{Ref@TeX{}} distribution from the maintainers web-page. +@xref{Imprint}, for more information.@refill + +@section Environment +@cindex Finding files +@cindex BibTeX database files, not found +@cindex TeX files, not found +@cindex @code{TEXINPUTS}, environment variable +@cindex @code{BIBINPUTS}, environment variable + +@b{Ref@TeX{}} needs to access all files which are part of a multifile +document, and the BibTeX database files requested by the +@code{\bibliography} command. To find these files, @b{Ref@TeX{}} will +require a search path, i.e. a list of directories to check. Normally +this list is stored in the environment variables @code{TEXINPUTS} and +@code{BIBINPUTS} which are also used by @b{Ref@TeX{}}. However, on some +systems these variables do not contain the full search path. If +@b{Ref@TeX{}} does not work for you because it cannot find some files, +read @ref{Finding Files}. + +@section Entering @b{Ref@TeX{}} Mode + +@findex turn-on-reftex +@findex reftex-mode +@vindex LaTeX-mode-hook +@vindex latex-mode-hook +To turn @b{Ref@TeX{}} Mode on and off in a particular buffer, use +@kbd{M-x reftex-mode}. To turn on @b{Ref@TeX{}} Mode for all LaTeX +files, add the following lines to your @file{.emacs} file:@refill + +@example +(add-hook 'LaTeX-mode-hook 'turn-on-reftex) ; with AUCTeX LaTeX mode +(add-hook 'latex-mode-hook 'turn-on-reftex) ; with Emacs latex mode +@end example + +@page +@node RefTeX in a Nutshell, , Installation, Introduction +@section @b{Ref@TeX{}} in a Nutshell +@cindex Quick-Start +@cindex Getting Started +@cindex RefTeX in a Nutshell +@cindex Nutshell, RefTeX in a + +@enumerate +@item +@b{Table of Contents}@* Typing @kbd{C-c =} (@code{reftex-toc}) will show +a table of contents of the document. This buffer can display sections, +labels and index entries defined in the document. From the buffer, you +can jump quickly to every part of your document. Press @kbd{?} to get +help.@refill + +@item +@b{Labels and References}@* @b{Ref@TeX{}} helps to create unique labels +and to find the correct key for references quickly. It distinguishes +labels for different environments, knows about all standard +environments (and many others), and can be configured to recognize any +additional labeled environments you have defined yourself (variable +@code{reftex-label-alist}).@refill + +@itemize @bullet +@item +@b{Creating Labels}@* +Type @kbd{C-c (} (@code{reftex-label}) to insert a label at point. +@b{Ref@TeX{}} will either +@itemize @minus +@item +derive a label from context (default for section labels) +@item +prompt for a label string (default for figures and tables) or +@item +insert a simple label made of a prefix and a number (all other +environments)@refill +@end itemize +@noindent +Which labels are created how is configurable with the variable +@code{reftex-insert-label-flags}.@refill + +@item +@b{Referencing Labels}@* To make a reference, type @kbd{C-c )} +(@code{reftex-reference}). This shows an outline of the document with +all labels of a certain type (figure, equation,...) and some label +context. Selecting a label inserts a @code{\ref@{@var{label}@}} macro +into the original buffer.@refill +@end itemize + +@item +@b{Citations}@* +Typing @kbd{C-c [} (@code{reftex-citation}) will let you specify a +regular expression to search in current BibTeX database files (as +specified in the @code{\bibliography} command) and pull out a list of +matches for you to choose from. The list is @emph{formatted} and +sorted. The selected article is referenced as @samp{\cite@{@var{key}@}} +(see the variable @code{reftex-cite-format} if you want to insert +different macros).@refill + +@item +@b{Index Support}@* +@b{Ref@TeX{}} helps to enter index entries. It also compiles all +entries into an alphabetically sorted @file{*Index*} buffer which you +can use to check and edit the entries. @b{Ref@TeX{}} knows about the +standard index macros and can be configured to recognize any additional +macros you have defined (@code{reftex-index-macros}). Multiple indices +are supported.@refill + +@itemize @bullet +@item +@b{Creating Index Entries}@* +Type @kbd{C-c /} (@code{reftex-index-selection-or-word}) to index the +current selection or the word at the cursor with the default macro (see +the variable @code{reftex-index-default-macro}).@* +Type @kbd{C-c <} (@code{reftex-index}) to insert a general index macro. +@b{Ref@TeX{}} will offer a list of available macros and provide +completion for the index tag (used to identify one of multiple indices) +and for the entry itself (useful with subentries). + +@refill + +@item +@b{Displaying the Index}@* To display the compiled index in a special +buffer, type @kbd{C-c >} (@code{reftex-display-index}). From that +buffer you can check and edit all entries. The index can be restricted +to those entries defined in a single document section or in a user +defined region.@refill +@end itemize + +@page +@item @b{Viewing Cross-References}@* +When point is on the @var{key} argument of a cross--referencing macro +(@code{\label}, @code{\ref}, @code{\cite}, @code{\bibitem}, +@code{\index}, and variations) or inside a BibTeX database entry, you +can press @kbd{C-c &} (@code{reftex-view-crossref}) to display +corresponding locations in the document and associated BibTeX database +files.@refill @* When the enclosing macro is @code{\cite} or @code{\ref} +and no other message occupies the echo area, information about the +citation or label will automatically be displayed in the echo +area.@refill + +@item +@b{Multifile Documents}@* +Multifile Documents are fully supported. The included files must have a +file variable @code{TeX-master} or @code{tex-main-file} pointing to the +master file. @b{Ref@TeX{}} provides cross-referencing information from +all parts of the document, and across document borders +(@file{xr.sty}).@refill + +@item +@b{Document Parsing}@* @b{Ref@TeX{}} needs to parse the document in +order to find labels and other information. It does it automatically +once and updates its list internally when @code{reftex-label} and +@code{reftex-index} are used. To enforce reparsing, call any of the +commands described above with a raw @kbd{C-u} prefix, or press the +@kbd{r} key in the label selection buffer, the table of contents +buffer, or the index buffer.@refill + +@item +@b{AUCTeX} @* If your major LaTeX mode is AUCTeX, @b{Ref@TeX{}} can +cooperate with it (see variable @code{reftex-plug-into-AUCTeX}). AUCTeX +contains style files which trigger appropriate settings in +@b{Ref@TeX{}}, so that for many of the popular LaTeX packages no +additional customizations will be necessary.@refill + +@item +@b{Useful Settings}@* To make @b{Ref@TeX{}} faster for large documents, +try these:@refill +@lisp +(setq reftex-enable-partial-scans t) +(setq reftex-save-parse-info t) +(setq reftex-use-multiple-selection-buffers t) +@end lisp + +To integrate with AUCTeX, use +@lisp +(setq reftex-plug-into-AUCTeX t) +@end lisp + +To make your own LaTeX macro definitions known to @b{Ref@TeX{}}, +customize the variables@refill +@example +@code{reftex-label-alist} @r{(for label macros/environments)} +@code{reftex-section-levels} @r{(for sectioning commands)} +@code{reftex-cite-format} @r{(for @code{\cite}-like macros)} +@code{reftex-index-macros} @r{(for @code{\index}-like macros)} +@code{reftex-index-default-macro} @r{(to set the default macro)} +@end example +If you have a large number of macros defined, you may want to write +an AUCTeX style file to support them with both AUCTeX and +@b{Ref@TeX{}}.@refill + +@item @b{Where Next?}@* Go ahead and use @b{Ref@TeX{}}. Use its menus +until you have picked up the key bindings. For an overview of what you +can do in each of the different special buffers, press @kbd{?}. Read +the manual if you get stuck. The first part of the manual explains in +a tutorial way how to use and customize @b{Ref@TeX{}}. The second +part is a command and variable reference.@refill +@end enumerate + +@node Table of Contents, Labels and References, Introduction, Top +@chapter Table of Contents +@cindex @file{*toc*} buffer +@cindex Table of contents buffer +@findex reftex-toc +@kindex C-c = + +Pressing the keys @kbd{C-c =} pops up a buffer showing the table of +contents of the document. By default, this @file{*toc*} buffer shows +only the sections of a document. Using the @kbd{l} and @kbd{i} keys you +can display all labels and index entries defined in the document as +well.@refill + +With the cursor in any of the lines denoting a location in the +document, simple key strokes will display the corresponding part in +another window, jump to that location, or perform other actions.@refill + +@kindex ? +Here is a list of special commands in the @file{*toc*} buffer. A +summary of this information is always available by pressing +@kbd{?}.@refill + +@table @kbd + +@tablesubheading{General} +@item ? +Display a summary of commands. + +@item 0-9, - +Prefix argument. + +@tablesubheading{Moving around} +@item n +Goto next entry in the table of context. + +@item p +Goto previous entry in the table of context. + +@item C-c C-n +Goto next section heading. Useful when many labels and index entries +separate section headings.@refill + +@item C-c C-p +Goto previous section heading. + +@tablesubheading{Access to document locations} +@item @key{SPC} +Show the corresponding location in another window. This command does +@emph{not} select that other window.@refill + +@item @key{TAB} +Goto the location in another window. + +@item @key{RET} +Go to the location and hide the @file{*toc*} buffer. This will restore +the window configuration before @code{reftex-toc} (@kbd{C-c =}) was +called.@refill + +@item mouse-2 +@vindex reftex-highlight-selection +Clicking with mouse button 2 on a line has the same effect as @key{RET}. +See also variable @code{reftex-highlight-selection}, @ref{Options +(Fontification)}.@refill + +@item f +@vindex reftex-toc-follow-mode +@vindex reftex-revisit-to-follow +Toggle follow mode. When follow mode is active, the other window will +always show the location corresponding to the line at point in the +@file{*toc*} buffer. This is similar to pressing @key{SPC} after each +cursor motion. The default for this flag can be set with the variable +@code{reftex-toc-follow-mode}. Note that only context in files already +visited is shown. @b{Ref@TeX{}} will not visit a file just for follow +mode. See, however, the variable +@code{reftex-revisit-to-follow}.@refill + +@item . +Show calling point in another window. This is the point from where +@code{reftex-toc} was last called. + +@tablesubheading{Exiting} +@item q +Hide the @file{*toc*} buffer, return to the position where +@code{reftex-toc} was last called.@refill + +@item k +Kill the @file{*toc*} buffer, return to the position where +@code{reftex-toc} was last called.@refill + +@item C-c > +Switch to the @file{*Index*} buffer of this document. With prefix +@samp{2}, restrict the index to the section at point in the @file{*toc*} +buffer. + +@tablesubheading{Controlling what gets displayed} + +@item F +@vindex reftex-toc-include-file-boundaries +Toggle the display of the file borders of a multifile document in the +@file{*toc*} buffer. The default for this flag can be set with the +variable @code{reftex-toc-include-file-boundaries}.@refill + +@item l +@vindex reftex-toc-include-labels +Toggle the display of labels in the @file{*toc*} buffer. The default +for this flag can be set with the variable +@code{reftex-toc-include-labels}. When called with a prefix argument, +@b{Ref@TeX{}} will prompt for a label type and include only labels of +the selected type in the @file{*toc*} buffer. The mode line @samp{L<>} +indicator shows which labels are included.@refill + +@item i +@vindex reftex-toc-include-index-entries +Toggle the display of index entries in the @file{*toc*} buffer. The +default for this flag can be set with the variable +@code{reftex-toc-include-index-entries}. When called with a prefix +argument, @b{Ref@TeX{}} will prompt for a specific index and include +only entries in the selected index in the @file{*toc*} buffer. The mode +line @samp{I<>} indicator shows which index is used.@refill + +@item c +@vindex reftex-toc-include-context +Toggle the display of label and index context in the @file{*toc*} +buffer. The default for this flag can be set with the variable +@code{reftex-toc-include-context}.@refill + +@tablesubheading{Updating the buffer} + +@item g +Rebuild the @file{*toc*} buffer. This does @emph{not} rescan the +document.@refill + +@item r +@vindex reftex-enable-partial-scans +Reparse the LaTeX document and rebuild the @file{*toc*} buffer. When +@code{reftex-enable-partial-scans} is non-nil, rescan only the file this +location is defined in, not the entire document.@refill + +@item C-u r +Reparse the @emph{entire} LaTeX document and rebuild the @file{*toc*} +buffer.@refill + +@item x +Switch to the @file{*toc*} buffer of an external document. When the +current document is using the @code{xr} package (@pxref{xr (LaTeX +package)}), @b{Ref@TeX{}} will switch to one of the external +documents.@refill + +@end table + +@vindex reftex-toc-map +In order to define additional commands for the @file{*toc*} buffer, the +keymap @code{reftex-toc-map} may be used.@refill + +@cindex Sectioning commands +@cindex KOMA-Script, LaTeX classes +@cindex LaTeX classes, KOMA-Script +@vindex reftex-section-levels +The section macros recognized by @b{Ref@TeX{}} are all LaTeX section +macros (from @code{\part} to @code{\subsubparagraph}) and the commands +@code{\addchap} and @code{\addsec} from the KOMA-Script classes. +Additional macros can be configured with the variable +@code{reftex-section-levels}. + +@node Labels and References, Citations, Table of Contents, Top +@chapter Labels and References +@cindex Labels in LaTeX +@cindex References in LaTeX +@cindex Label category +@cindex Label environment +@cindex @code{\label} + +LaTeX provides a powerful mechanism to deal with cross--references in a +document. When writing a document, any part of it can be marked with a +label, like @samp{\label@{mark@}}. LaTeX records the current value of a +certain counter when a label is defined. Later references to this label +(like @samp{\ref@{mark@}}) will produce the recorded value of the +counter.@refill + +Labels can be used to mark sections, figures, tables, equations, +footnotes, items in enumerate lists etc. LaTeX is context sensitive in +doing this: A label defined in a figure environment automatically +records the figure counter, not the section counter.@refill + +Several different environments can share a common counter and therefore +a common label category. E.g. labels in both @code{equation} and +@code{eqnarray} environments record the value of the same counter - the +equation counter.@refill + +@menu +* Creating Labels:: +* Referencing Labels:: +* Builtin Label Environments:: The environments RefTeX knows about. +* Defining Label Environments:: ... and environments it doesn't. +* Reference Info:: View the label corresponding to a \ref. +* xr (LaTeX package):: References to external documents. +* varioref (LaTeX package):: How to create \vref instead of \ref. +* fancyref (LaTeX package):: How to create \fref instead of \ref. +@end menu + +@node Creating Labels, Referencing Labels, , Labels and References +@section Creating Labels +@cindex Creating labels +@cindex Labels, creating +@cindex Labels, deriving from context +@kindex C-c ( +@findex reftex-label + +In order to create a label in a LaTeX document, press @kbd{C-c (} +(@code{reftex-label}). Just like LaTeX, @b{Ref@TeX{}} is context sensitive +and will figure out the environment it currently is in and adapt the +label to that environment. A label usually consists of a short prefix +indicating the type of the label and a unique mark. @b{Ref@TeX{}} has +3 different modes to create this mark.@refill + +@enumerate +@item +@vindex reftex-translate-to-ascii-function +@vindex reftex-derive-label-parameters +@vindex reftex-label-illegal-re +@vindex reftex-abbrev-parameters +A label can be derived from context. This means, @b{Ref@TeX{}} takes +the context of the label definition and constructs a label from +that@footnote{Note that the context may contain constructs which are +illegal in labels. @b{Ref@TeX{}} will therefore strip the accent from +accented Latin-1 characters and remove everything else which is not +legal in labels. This mechanism is safe, but may not be satisfactory +for non-western languages. Check the following variables if you need to +change things: @code{reftex-translate-to-ascii-function}, +@code{reftex-derive-label-parameters}, @code{reftex-label-illegal-re}, +@code{reftex-abbrev-parameters}.}. This works best for section labels, +where the section heading is used to construct a label. In fact, +@b{Ref@TeX{}}'s default settings use this method only for section +labels. You will be asked to confirm the derived label, or edit +it.@refill + +@item +We may also use a simple unique number to identify a label. This is +mostly useful for labels where it is difficult to come up with a very +good descriptive name. @b{Ref@TeX{}}'s default settings use this method +for equations, enumerate items and footnotes. The author of @b{Ref@TeX{}} +tends to write documents with many equations and finds it impossible +to come up with good names for each of them. These simple labels are +inserted without query, and are therefore very fast. Good descriptive +names are not really necessary as @b{Ref@TeX{}} will provide context to +reference a label (@pxref{Referencing Labels}).@refill + +@item +The third method is to ask the user for a label. This is most +useful for things which are easy to describe briefly and do not turn up +too frequently in a document. @b{Ref@TeX{}} uses this for figures and +tables. Of course, one can enter the label directly by typing the full +@samp{\label@{mark@}}. The advantage of using @code{reftex-label} +anyway is that @b{Ref@TeX{}} will know that a new label has been defined. +It will then not be necessary to rescan the document in order to access +this label later.@refill +@end enumerate + +@vindex reftex-insert-label-flags +If you want to change the way certain labels are created, check out the +variable @code{reftex-insert-label-flags} (@pxref{Options (Creating +Labels)}).@refill + +If you are using AUCTeX to write your LaTeX documents, you can +set it up to delegate the creation of labels to +@b{Ref@TeX{}}. @xref{AUCTeX}, for more information. + +@node Referencing Labels, Builtin Label Environments, Creating Labels, Labels and References +@section Referencing Labels +@cindex Referencing labels +@cindex Labels, referencing +@cindex Selection buffer, labels +@cindex Selection process +@cindex @code{\ref} +@kindex C-c ) +@findex reftex-reference + +Referencing Labels is really at the heart of @b{Ref@TeX{}}. Press @kbd{C-c +)} in order to reference a label (reftex-reference). This will start a +selection process and finally insert the complete @samp{\ref@{label@}} +into the buffer.@refill + +First, @b{Ref@TeX{}} will determine the label category which is required. +Often that can be figured out from context. For example, if you +write @samp{As shown in eq.} and the press @kbd{C-c )}, @b{Ref@TeX{}} knows +that an equation label is going to be referenced. If it cannot figure +out what label category is needed, it will query for one.@refill + +You will then be presented with a label selection menu. This is a +special buffer which contains an outline of the document along with all +labels of the given label category. In addition, next to the label +there will be one line of context of the label definition, which is some +text in the buffer near the label definition. Usually this is +sufficient to identify the label. If you are unsure about a certain +label, pressing @key{SPC} will show the label definition point in +another window.@refill + +In order to reference a label, move to cursor to the correct label and +press @key{RET}. You can also reference several labels with a single +call to @code{reftex-reference} by marking entries with the @kbd{m} +key (see below). + +@kindex ? +Here is a list of special commands in the selection buffer. A summary +of this information is always available from the selection process by +pressing @kbd{?}.@refill + + + +@table @kbd +@tablesubheading{General} +@item ? +Show a summary of available commands. + +@item 0-9,- +Prefix argument. + +@tablesubheading{Moving around} +@item n +Go to next label. + +@item p +Go to previous label. + +@item b +Jump back to the position where you last left the selection buffer. +Normally this should get you back to the last referenced label.@refill + +@item C-c C-n +Goto next section heading. + +@item C-c C-p +Goto previous section heading. + +@tablesubheading{Displaying Context} +@item @key{SPC} +Show the surroundings of the definition of the current label in another +window. See also the @kbd{f} key.@refill + +@item f +@vindex reftex-revisit-to-follow +Toggle follow mode. When follow mode is active, the other window will +always display the full context of the current label. This is similar +to pressing @key{SPC} after each cursor motion. Note that only context +in files already visited is shown. @b{RefTeX} will not visit a file +just for follow mode. See, however, the variable +@code{reftex-revisit-to-follow}.@refill + +@item . +Show insertion point in another window. This is the point from where you +called @code{reftex-reference}.@refill + +@tablesubheading{Selecting a label and creating the reference} +@item @key{RET} +Insert a reference to the label at point into the buffer from which the +selection process was started. When entries have been marked, @key{RET} +references all marked labels.@refill + +@item mouse-2 +@vindex reftex-highlight-selection +Clicking with mouse button 2 on a label will accept it like @key{RET} +would. See also variable @code{reftex-highlight-selection}, @ref{Options +(Misc)}.@refill + +@vindex reftex-multiref-punctuation +@item m - + , +Mark the current entry. When several entries have been marked, pressing +@kbd{RET} will accept all of them and place them into several +@code{\ref} macros. The special markers @samp{,-+} also store a +separator to be inserted before the corresponding reference. So marking +six entries with the keys @samp{m , , - , +} will give a reference list +like this (see the variable @code{reftex-multiref-punctuation}) +@example +In eqs. (1), (2), (3)--(4), (5) and (6) +@end example + +@item u +Unmark a marked entry. + +@c FIXME: Do we need `A' as well for consistency? +@cindex LaTeX packages, @code{saferef} +@cindex @code{saferef}, LaTeX package +@item a +Accept the marked entries and put all labels as a comma-separated list +into one @emph{single} @code{\ref} macro. Some packages like +@file{saferef.sty} support multiple references in this way.@refill + +@item l +Use the last referenced label(s) again. This is equivalent to moving to +that label and pressing @key{RET}.@refill + +@item @key{TAB} +Enter a label with completion. This may also be a label which does not +yet exist in the document. + +@item v +@cindex @code{varioref}, LaTeX package +@cindex @code{\vref} +@cindex LaTeX packages, @code{varioref} +Toggle between @code{\ref} and @code{\vref} macro for references. The +@code{\vref} macro is defined in the @code{varioref} LaTeX package. +With this key you can force @b{Ref@TeX{}} to insert a @code{\vref} +macro. The current state of this flag is displayed by the @samp{S<>} +indicator in the mode line of the selection buffer.@refill + +@item V +@cindex @code{fancyref}, LaTeX package +@cindex @code{\fref} +@cindex @code{\Fref} +@cindex LaTeX packages, @code{fancyref} +Cycle between @code{\ref}, @code{\fref} and @code{\Fref}. The +@code{\fref} and @code{\Fref} macros are defined in the @code{fancyref} +LaTeX package. With this key you can force @b{Ref@TeX{}} to insert a +@code{\fref} or @code{\Fref} macro. The current state of this flag is +displayed by the @samp{S<>} indicator in the mode line of the +selection buffer. + +@tablesubheading{Exiting} + +@item q +Exit the selection process without inserting any reference into the +buffer.@refill + +@tablesubheading{Controlling what gets displayed} +@vindex reftex-label-menu-flags +The defaults for the following flags can be configured with the variable +@code{reftex-label-menu-flags} (@pxref{Options (Referencing Labels)}). + +@item c +Toggle the display of the one-line label definition context in the +selection buffer.@refill + +@item F +Toggle the display of the file borders of a multifile document in the +selection buffer.@refill + +@item t +Toggle the display of the table of contents in the selection buffer.@refill + +@item # +Toggle the display of a label counter in the selection buffer.@refill + +@item % +Toggle the display of labels hidden in comments in the selection +buffers. Sometimes, you may have commented out parts of your document. +If these parts contain label definitions, @b{Ref@TeX{}} can still display +and reference these labels.@refill + +@tablesubheading{Updating the buffer} +@item g +Update the menu. This will rebuilt the menu from the internal label +list, but not reparse the document (see @kbd{r}).@refill + +@item r +@vindex reftex-enable-partial-scans +Reparse the document to update the information on all labels and rebuild +the menu. If the variable @code{reftex-enable-partial-scans} is +non-@code{nil} and your document is a multifile document, this will +reparse only a part of the document (the file in which the label at +point was defined).@refill + +@item C-u r +Reparse the @emph{entire} document. + +@item s +Switch the label category. After prompting for another label category, +a menu for that category will be shown.@refill + +@item x +Reference a label from an external document. With the LaTeX package +@code{xr} it is possible to reference labels defined in another +document. This key will switch to the label menu of an external +document and let you select a label from there (@pxref{xr (LaTeX +package),,xr}).@refill + +@end table + +@vindex reftex-select-label-map +In order to define additional commands for the selection process, the +keymap @code{reftex-select-label-map} may be used.@refill + +@node Builtin Label Environments, Defining Label Environments, Referencing Labels, Labels and References +@section Builtin Label Environments +@cindex Builtin label environments +@cindex Label environments, builtin +@cindex Environments, builtin +@vindex reftex-label-alist +@vindex reftex-label-alist-builtin + +@b{Ref@TeX{}} needs to be aware of the environments which can be referenced +with a label (i.e. which carry their own counters). By default, @b{Ref@TeX{}} +recognizes all labeled environments and macros discussed in @cite{The +LaTeX Companion by Goossens, Mittelbach & Samarin, Addison-Wesley +1994.}. These are:@refill + +@itemize @minus +@item +@cindex @code{figure}, LaTeX environment +@cindex @code{figure*}, LaTeX environment +@cindex @code{table}, LaTeX environment +@cindex @code{table*}, LaTeX environment +@cindex @code{equation}, LaTeX environment +@cindex @code{eqnarray}, LaTeX environment +@cindex @code{enumerate}, LaTeX environment +@cindex @code{\footnote}, LaTeX macro +@cindex LaTeX macro @code{footnote} +@cindex LaTeX core +@code{figure}, @code{figure*}, @code{table}, @code{table*}, @code{equation}, +@code{eqnarray}, @code{enumerate}, the @code{\footnote} macro (this is +the LaTeX core stuff)@refill +@item +@cindex AMS-LaTeX +@cindex @code{amsmath}, LaTeX package +@cindex LaTeX packages, @code{amsmath} +@cindex @code{align}, AMS-LaTeX environment +@cindex @code{gather}, AMS-LaTeX environment +@cindex @code{multline}, AMS-LaTeX environment +@cindex @code{flalign}, AMS-LaTeX environment +@cindex @code{alignat}, AMS-LaTeX environment +@cindex @code{xalignat}, AMS-LaTeX environment +@cindex @code{xxalignat}, AMS-LaTeX environment +@cindex @code{subequations}, AMS-LaTeX environment +@code{align}, @code{gather}, @code{multline}, @code{flalign}, +@code{alignat}, @code{xalignat}, @code{xxalignat}, @code{subequations} +(from AMS-LaTeX's @file{amsmath.sty} package)@refill +@item +@cindex @code{endnote}, LaTeX package +@cindex LaTeX packages, @code{endnote} +@cindex @code{\endnote}, LaTeX macro +the @code{\endnote} macro (from @file{endnotes.sty}) +@item +@cindex @code{fancybox}, LaTeX package +@cindex LaTeX packages, @code{fancybox} +@cindex @code{Beqnarray}, LaTeX environment +@code{Beqnarray} (@file{fancybox.sty}) +@item +@cindex @code{floatfig}, LaTeX package +@cindex LaTeX packages, @code{floatfig} +@cindex @code{floatingfig}, LaTeX environment +@code{floatingfig} (@file{floatfig.sty}) +@item +@cindex @code{longtable}, LaTeX package +@cindex LaTeX packages, @code{longtable} +@cindex @code{longtable}, LaTeX environment +@code{longtable} (@file{longtable.sty}) +@item +@cindex @code{picinpar}, LaTeX package +@cindex LaTeX packages, @code{picinpar} +@cindex @code{figwindow}, LaTeX environment +@cindex @code{tabwindow}, LaTeX environment +@code{figwindow}, @code{tabwindow} (@file{picinpar.sty}) +@item +@cindex @code{sidecap}, LaTeX package +@cindex LaTeX packages, @code{sidecap} +@cindex @code{SCfigure}, LaTeX environment +@cindex @code{SCtable}, LaTeX environment +@code{SCfigure}, @code{SCtable} (@file{sidecap.sty}) +@item +@cindex @code{rotating}, LaTeX package +@cindex LaTeX packages, @code{rotating} +@cindex @code{sidewaysfigure}, LaTeX environment +@cindex @code{sidewaystable}, LaTeX environment +@code{sidewaysfigure}, @code{sidewaystable} (@file{rotating.sty}) +@item +@cindex @code{subfig}, LaTeX package +@cindex LaTeX packages, @code{subfigure} +@cindex @code{subfigure}, LaTeX environment +@cindex @code{subfigure*}, LaTeX environment +@code{subfigure}, @code{subfigure*}, the @code{\subfigure} macro +(@file{subfigure.sty})@refill +@item +@cindex @code{supertab}, LaTeX package +@cindex LaTeX packages, @code{supertab} +@cindex @code{supertabular}, LaTeX environment +@code{supertabular} (@file{supertab.sty}) +@item +@cindex @code{wrapfig}, LaTeX package +@cindex LaTeX packages, @code{wrapfig} +@cindex @code{wrapfigure}, LaTeX environment +@code{wrapfigure} (@file{wrapfig.sty}) +@end itemize + +If you want to use other labeled environments, defined with +@code{\newtheorem}, @b{Ref@TeX{}} needs to be configured to recognize +them (@pxref{Defining Label Environments}).@refill + +@node Defining Label Environments, Reference Info, Builtin Label Environments, Labels and References +@section Defining Label Environments +@cindex Label environments, defining + +@vindex reftex-label-alist +@b{Ref@TeX{}} can be configured to recognize additional labeled +environments and macros. This is done with the variable +@code{reftex-label-alist} (@pxref{Options (Defining Label +Environments)}). If you are not familiar with Lisp, you can use the +@code{custom} library to configure this rather complex variable. To do +this, use + +@example +@kbd{M-x customize-variable @key{RET} reftex-label-alist @key{RET}} +@end example + +@vindex reftex-label-alist-builtin +Here we will discuss a few examples, in order to make things clearer. +It can also be instructive to look at the constant +@code{reftex-label-alist-builtin} which contains the entries for +all the builtin environments and macros (@pxref{Builtin Label +Environments}).@refill + +@menu +* Theorem and Axiom:: Defined with @code{\newenvironment}. +* Quick Equation:: When a macro sets the label type. +* Figure Wrapper:: When a macro argument is a label. +* Adding Magic Words:: Other words for other languages. +* Using \eqref:: How to switch to this AMS-LaTeX macro. +* Non-Standard Environments:: Environments without \begin and \end +* Putting it Together:: How to combine many entries. +@end menu + +@node Theorem and Axiom, Quick Equation, , Defining Label Environments +@subsection Theorem and Axiom Environments +@cindex @code{theorem}, newtheorem +@cindex @code{axiom}, newtheorem +@cindex @code{\newtheorem} + +Suppose you are using @code{\newtheorem} in LaTeX in order to define two +new environments, @code{theorem} and @code{axiom}@refill + +@example +\newtheorem@{axiom@}@{Axiom@} +\newtheorem@{theorem@}@{Theorem@} +@end example + +@noindent +to be used like this: + +@example +\begin@{axiom@} +\label@{ax:first@} + .... +\end@{axiom@} +@end example + +So we need to tell @b{Ref@TeX{}} that @code{theorem} and @code{axiom} are new +labeled environments which define their own label categories. We can +either use Lisp to do this (e.g. in @file{.emacs}) or use the custom +library. With Lisp it would look like this + +@lisp +(setq reftex-label-alist + '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.")) + ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th.")))) +@end lisp + +The type indicator characters @code{?a} and @code{?h} are used for +prompts when @b{Ref@TeX{}} queries for a label type. @code{?h} +was chosen for @code{theorem} since @code{?t} is already taken by +@code{table}. Note that also @code{?s}, @code{?f}, @code{?e}, +@code{?i}, @code{?n} are already used for standard environments.@refill + +@noindent +The labels for Axioms and Theorems will have the prefixes @samp{ax:} and +@samp{thr:}, respectively. @xref{AUCTeX}, for information on how +AUCTeX can use @b{Ref@TeX{}} to automatically create labels when a new +environment is inserted into a buffer.@refill + +@noindent +The @samp{~\ref@{%s@}} is a format string indicating how to insert +references to these labels.@refill + +@noindent +The next item indicates how to grab context of the label definition.@refill +@itemize @minus +@item +@code{t} means to get it from a default location (from the beginning of +a @code{\macro} or after the @code{\begin} statement). @code{t} is +@emph{not} a good choice for eqnarray and similar environments.@refill +@item +@code{nil} means to use the text right after the label definition.@refill +@item +For more complex ways of getting context, see the variable +@code{reftex-label-alist} (@ref{Options (Defining Label +Environments)}).@refill +@end itemize + +The strings at the end of each entry are used to guess the correct label +type from the word before point when creating a reference. E.g. if you +write: @samp{As we have shown in Theorem} and then press @kbd{C-c )}, +@b{Ref@TeX{}} will know that you are looking for a theorem label and restrict +the menu to only these labels without even asking.@refill + +To do the same configuration with @code{customize}, you need to click on +the @code{[INS]} button twice to create two templates and fill them in +like this:@refill + +@example +Reftex Label Alist: [Hide] +[INS] [DEL] Package or Detailed : [Value Menu] Detailed: + Environment or \macro : [Value Menu] String: axiom + Type specification : [Value Menu] Char : a + Label prefix string : [Value Menu] String: ax: + Label reference format: [Value Menu] String: ~\ref@{%s@} + Context method : [Value Menu] After label + Magic words: + [INS] [DEL] String: axiom + [INS] [DEL] String: ax. + [INS] +[INS] [DEL] Package or Detailed : [Value Menu] Detailed: + Environment or \macro : [Value Menu] String: theorem + Type specification : [Value Menu] Char : h + Label prefix string : [Value Menu] String: thr: + Label reference format: [Value Menu] String: ~\ref@{%s@} + Context method : [Value Menu] Default position + Magic words: + [INS] [DEL] String: theorem + [INS] [DEL] String: theor. + [INS] [DEL] String: th. + [INS] +@end example + +@vindex reftex-insert-label-flags +@vindex reftex-label-menu-flags +Depending on how you would like the label insertion and selection for +the new environments to work, you might want to add the letters @samp{a} +and @samp{h} to some of the flags in the variables +@code{reftex-insert-label-flags} (@pxref{Options (Creating Labels)}) +and @code{reftex-label-menu-flags} (@pxref{Options (Referencing +Labels)}).@refill + + +@node Quick Equation, Figure Wrapper, Theorem and Axiom , Defining Label Environments +@subsection Quick Equation Macro +@cindex Quick equation macro +@cindex Macros as environment wrappers + +Suppose you would like to have a macro for quick equations. It +could be defined like this: + +@example +\newcommand@{\quickeq@}[1]@{\begin@{equation@} #1 \end@{equation@}@} +@end example + +@noindent +and used like this: + +@example +Einstein's equation is \quickeq@{E=mc^2 \label@{eq:einstein@}@}. +@end example + +We need to tell @b{Ref@TeX{}} that any label defined in the argument of the +@code{\quickeq} is an equation label. Here is how to do this with lisp: + +@lisp +(setq reftex-label-alist '(("\\quickeq@{@}" ?e nil nil 1 nil))) +@end lisp + +The first element in this list is now the macro with empty braces as an +@emph{image} of the macro arguments. @code{?e} indicates that this is +an equation label, the different @code{nil} elements indicate to use the +default values for equations. The @samp{1} as the fifth element +indicates that the context of the label definition should be the 1st +argument of the macro.@refill + +Here is again how this would look in the customization buffer: + +@example +Reftex Label Alist: [Hide] +[INS] [DEL] Package or Detailed : [Value Menu] Detailed: + Environment or \macro : [Value Menu] String: \quickeq@{@} + Type specification : [Value Menu] Char : e + Label prefix string : [Value Menu] Default + Label reference format: [Value Menu] Default + Context method : [Value Menu] Macro arg nr: 1 + Magic words: + [INS] +@end example + +@node Figure Wrapper, Adding Magic Words, Quick Equation, Defining Label Environments +@subsection Figure Wrapping Macro +@cindex Macros as environment wrappers +@cindex Figure wrapping macro + +Suppose you want to make figures not directly with the figure +environment, but with a macro like + +@example +\newcommand@{\myfig@}[5][tbp]@{% + \begin@{figure@}[#1] + \epsimp[#5]@{#2@} + \caption@{#3@} + \label@{#4@} + \end@{figure@}@} +@end example + +@noindent +which would be called like + +@example +\myfig[htp]@{filename@}@{caption text@}@{label@}@{1@} +@end example + +Now we need to tell @b{Ref@TeX{}} that the 4th argument of the +@code{\myfig} macro @emph{is itself} a figure label, and where to find +the context.@refill + +@lisp +(setq reftex-label-alist + '(("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3))) +@end lisp + +The empty pairs of brackets indicate the different arguments of the +@code{\myfig} macro. The @samp{*} marks the label argument. @code{?f} +indicates that this is a figure label which will be listed together with +labels from normal figure environments. The @code{nil} entries for +prefix and reference format mean to use the defaults for figure labels. +The @samp{3} for the context method means to grab the 3rd macro argument +- the caption.@refill + +As a side effect of this configuration, @code{reftex-label} will now +insert the required naked label (without the @code{\label} macro) when +point is directly after the opening parenthesis of a @code{\myfig} macro +argument.@refill + +Again, here the configuration in the customization buffer: + +@example +[INS] [DEL] Package or Detailed : [Value Menu] Detailed: + Environment or \macro : [Value Menu] String: \myfig[]@{@}@{@}@{*@}@{@} + Type specification : [Value Menu] Char : f + Label prefix string : [Value Menu] Default + Label reference format: [Value Menu] Default + Context method : [Value Menu] Macro arg nr: 3 + Magic words: + [INS] +@end example + +@node Adding Magic Words, Using \eqref, Figure Wrapper, Defining Label Environments +@subsection Adding Magic Words +@cindex Magic words +@cindex German magic words +@cindex Label category + +Sometimes you don't want to define a new label environment or macro, but +just change the information associated with a label category. Maybe you +want to add some magic words, for another language. Changing only the +information associated with a label category is done by giving +@code{nil} for the environment name and then specify the items you want +to define. Here is an example which adds German magic words to all +predefined label categories.@refill + +@lisp +(setq reftex-label-alist + '((nil ?s nil nil nil ("Kapitel" "Kap." "Abschnitt" "Teil")) + (nil ?e nil nil nil ("Gleichung" "Gl.")) + (nil ?t nil nil nil ("Tabelle")) + (nil ?f nil nil nil ("Figur" "Abbildung" "Abb.")) + (nil ?n nil nil nil ("Anmerkung" "Anm.")) + (nil ?i nil nil nil ("Punkt")))) +@end lisp + +@node Using \eqref, Non-Standard Environments, Adding Magic Words, Defining Label Environments +@subsection Using @code{\eqref} +@cindex @code{\eqref}, AMS-LaTeX macro +@cindex AMS-LaTeX +@cindex Label category + +Another case where one only wants to change the information associated +with the label category is to change the macro which is used for +referencing the label. When working with the AMS-LaTeX stuff, you might +prefer @code{\eqref} for doing equation references. Here is how to +do this: + +@lisp +(setq reftex-label-alist '((nil ?e nil "~\\eqref@{%s@}" nil nil))) +@end lisp + +@b{Ref@TeX{}} has also a predefined symbol for this special purpose. The +following is equivalent to the line above.@refill + +@lisp +(setq reftex-label-alist '(AMSTeX)) +@end lisp + +Note that this is automatically done by the @file{amsmath.el} style file +of AUCTeX (@pxref{Style Files}) - so if you use AUCTeX, +this configuration will not be necessary.@refill + +@node Non-Standard Environments, Putting it Together, Using \eqref, Defining Label Environments +@subsection Non-standard Environments +@cindex Non-standard environments +@cindex Environments without @code{\begin} +@cindex Special parser functions +@cindex Parser functions, for special environments + +Some LaTeX packages define environment-like structures without using the +standard @samp{\begin..\end} structure. @b{Ref@TeX{}} cannot parse +these directly, but you can write your own special-purpose parser and +use it instead of the name of an environment in an entry for +@code{reftex-label-alist}. The function should check if point is +currently in the special environment it was written to detect. If so, +it must return a buffer position indicating the start of this +environment. The return value must be @code{nil} on failure to detect +the environment. The function is called with one argument @var{bound}. +If non-@code{nil}, @var{bound} is a boundary for backwards searches +which should be observed. We will discuss two examples.@refill + +@cindex LaTeX commands, abbreviated + +Some people define abbreviations for +environments, like @code{\be} for @code{\begin@{equation@}}, and +@code{\ee} for @code{\end@{equation@}}. The parser function would have +to search backward for these macros. When the first match is +@code{\ee}, point is not in this environment. When the first match is +@code{\be}, point is in this environment and the function must return +the beginning of the match. To avoid scanning too far, we can also look +for empty lines which cannot occure inside an equation environment. +Here is the setup:@refill + +@lisp +;; Setup entry in reftex-label-alist, using all defaults for equations +(setq reftex-label-alist '((detect-be-ee ?e nil nil nil nil))) + +(defun detect-be-ee (bound) + ;; Search backward for the macros or an empty line + (if (re-search-backward + "\\(^[ \t]*\n\\|\\\\ee\\>\\)\\|\\(\\\\be\\>\\)" bound t) + (if (match-beginning 2) + (match-beginning 2) ; Return start of environment + nil) ; Return nil because env is closed + nil)) ; Return nil for not found +@end lisp + +@cindex @code{linguex}, LaTeX package +@cindex LaTeX packages, @code{linguex} +A more complex example is the @file{linguex.sty} package which defines +list macros @samp{\ex.}, @samp{\a.}, @samp{\b.} etc. for lists which are +terminated by @samp{\z.} or by an empty line.@refill + +@example +\ex. \label@{ex:12@} Some text in an exotic language ... + \a. \label@{ex:13@} more stuff + \b. \label@{ex:14@} still more stuff + \a. List on a deeper level + \b. Another item + \b. and the third one + \z. + \b. Third item on this level. + +... text after the empty line terminating all lists +@end example + +The difficulty is that the @samp{\a.} lists can nest and that an empty +line terminates all list levels in one go. So we have to count nesting +levels between @samp{\a.} and @samp{\z.}. Here is the implementation +for @b{Ref@TeX{}}. + +@lisp +(setq reftex-label-alist + '((detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex.")))) + +(defun detect-linguex (bound) + (let ((cnt 0)) + (catch 'exit + (while + ;; Search backward for all possible delimiters + (re-search-backward + (concat "\\(^[ \t]*\n\\)\\|\\(\\\\z\\.\\)\\|" + "\\(\\ex[ig]?\\.\\)\\|\\(\\\\a\\.\\)") + nil t) + ;; Check which delimiter was matched. + (cond + ((match-beginning 1) + ;; empty line terminates all - return nil + (throw 'exit nil)) + ((match-beginning 2) + ;; \z. terminates one list level - decrease nesting count + (decf cnt)) + ((match-beginning 3) + ;; \ex. : return match unless there was a \z. on this level + (throw 'exit (if (>= cnt 0) (match-beginning 3) nil))) + ((match-beginning 4) + ;; \a. : return match when on level 0, otherwise + ;; increment nesting count + (if (>= cnt 0) + (throw 'exit (match-beginning 4)) + (incf cnt)))))))) +@end lisp + +@node Putting it Together, , Non-Standard Environments, Defining Label Environments +@subsection Putting it all together + +When you have to put several entries into @code{reftex-label-alist}, just +put them after each other in a list, or create that many templates in +the customization buffer. Here is a lisp example which uses several of +the entries described above: + +@lisp +(setq reftex-label-alist + '(("axiom" ?a "ax:" "~\\ref@{%s@}" nil ("axiom" "ax.")) + ("theorem" ?h "thr:" "~\\ref@{%s@}" t ("theorem" "theor." "th.")) + ("\\quickeq@{@}" ?e nil nil 1 nil) + AMSTeX + ("\\myfig[]@{@}@{@}@{*@}@{@}" ?f nil nil 3) + (detect-linguex ?x "ex:" "~\\ref@{%s@}" nil ("Example" "Ex.")))) +@end lisp + +@node Reference Info, xr (LaTeX package), Defining Label Environments, Labels and References +@section Reference Info +@findex reftex-view-crossref +@findex reftex-mouse-view-crossref +@cindex Cross-references, displaying +@cindex Reference info +@cindex Displaying cross-references +@cindex Viewing cross-references +@kindex C-c & +@kindex S-mouse-2 + +When point is idle on the argument of a @code{\ref} macro, the echo area +will display some information about the label referenced there. Note +that the information is only displayed if the echo area is not occupied +by a different message. + +@b{Ref@TeX{}} can also display the label definition corresponding to a +@code{\ref} macro, or all reference locations corresponding to a +@code{\label} macro. @xref{Viewing Cross-References}, for more +information.@refill + +@node xr (LaTeX package), varioref (LaTeX package), Reference Info, Labels and References +@section @code{xr}: Cross-Document References +@cindex @code{xr}, LaTeX package +@cindex LaTeX packages, @code{xr} +@cindex @code{\externaldocument} +@cindex External documents +@cindex References to external documents +@cindex Cross-document references + +The LaTeX package @code{xr} makes it possible to create references to +labels defined in external documents. The preamble of a document using +@code{xr} will contain something like this:@refill + +@example +\usepackage@{xr@} +\externaldocument[V1-]@{volume1@} +\externaldocument[V3-]@{volume3@} +@end example + +@noindent +and we can make references to any labels defined in these +external documents by using the prefixes @samp{V1-} and @samp{V3-}, +respectively.@refill + +@b{Ref@TeX{}} can be used to create such references as well. Start the +referencing process normally, by pressing @kbd{C-c )}. Select a label +type if necessary. When you see the label selection buffer, pressing +@kbd{x} will switch to the label selection buffer of one of the external +documents. You may then select a label as before and @b{Ref@TeX{}} will +insert it along with the required prefix.@refill + +For this kind of inter-document cross-references, saving of parsing +information and the use of multiple selection buffers can mean a large +speed-up (@pxref{Optimizations}).@refill + +@node varioref (LaTeX package), fancyref (LaTeX package), xr (LaTeX package), Labels and References +@section @code{varioref}: Variable Page References +@cindex @code{varioref}, LaTeX package +@cindex @code{\vref} +@cindex LaTeX packages, @code{varioref} +@vindex reftex-vref-is-default +@code{varioref} is a frequently used LaTeX package to create +cross--references with page information. When you want to make a +reference with the @code{\vref} macro, just press the @kbd{v} key in the +selection buffer to toggle between @code{\ref} and @code{\vref} +(@pxref{Referencing Labels}). The mode line of the selection buffer +shows the current status of this switch. If you find that you almost +always use @code{\vref}, you may want to make it the default by +customizing the variable @code{reftex-vref-is-default}. If this +toggling seems too inconvenient, you can also use the command +@code{reftex-varioref-vref}@footnote{bind it to @kbd{C-c v}.}. +Or use AUCTeX to create your macros (@pxref{AUCTeX}).@refill + +@node fancyref (LaTeX package), , varioref (LaTeX package), Labels and References +@section @code{fancyref}: Fancy Cross References +@cindex @code{fancyref}, LaTeX package +@cindex @code{\fref} +@cindex @code{\Fref} +@cindex LaTeX packages, @code{fancyref} +@vindex reftex-fref-is-default +@code{fancyref} is a LaTeX package where a macro call like +@code{\fref@{@var{fig:map-of-germany}@}} creates not only the number of +the referenced counter but also the complete text around it, like +@samp{Figure 3 on the preceding page}. In order to make it work you +need to use label prefixes like @samp{fig:} consistently - something +@b{Ref@TeX{}} does automatically. When you want to make a reference +with the @code{\fref} macro, just press the @kbd{V} key in the selection +buffer to cycle between @code{\ref}, @code{\fref} and @code{\Fref} +(@pxref{Referencing Labels}). The mode line of the selection buffer +shows the current status of this switch. If this cycling seems +inconvenient, you can also use the commands @code{reftex-fancyref-fref} +and @code{reftex-fancyref-Fref}@footnote{bind them to @kbd{C-c +f} and @kbd{C-c F}.}. Or use AUCTeX to create your macros +(@pxref{AUCTeX}).@refill + +@node Citations, Index Support, Labels and References, Top +@chapter Citations +@cindex Citations +@cindex @code{\cite} + +Citations in LaTeX are done with the @code{\cite} macro or variations of +it. The argument of the macro is a citation key which identifies an +article or book in either a BibTeX database file or in an explicit +@code{thebibliography} environment in the document. @b{Ref@TeX{}}'s +support for citations helps to select the correct key quickly.@refill + +@menu +* Creating Citations:: How to create them. +* Citation Styles:: Natbib, Harvard, Chicago and Co. +* Citation Info:: View the corresponding database entry. +* Chapterbib and Bibunits:: Multiple bibliographies in a Document. +* Citations Outside LaTeX:: How to make citations in Emails etc. +@end menu + +@node Creating Citations, Citation Styles, , Citations +@section Creating Citations +@cindex Creating citations +@cindex Citations, creating +@findex reftex-citation +@kindex C-c [ +@cindex Selection buffer, citations +@cindex Selection process + +In order to create a citation, press @kbd{C-c [}. @b{Ref@TeX{}} then +prompts for a regular expression which will be used to search through +the database and present the list of matches to choose from in a +selection process similar to that for selecting labels +(@pxref{Referencing Labels}).@refill + +The regular expression uses an extended syntax: @samp{&&} defines a +logic @code{and} for regular expressions. For example +@samp{Einstein&&Bose} will match all articles which mention +Bose-Einstein condensation, or which are co-authored by Bose and +Einstein. When entering the regular expression, you can complete on +known citation keys.@refill + +@cindex @code{\bibliography} +@cindex @code{thebibliography}, LaTeX environment +@cindex @code{BIBINPUTS}, environment variable +@cindex @code{TEXBIB}, environment variable +@b{Ref@TeX{}} prefers to use BibTeX database files specified with a +@code{\bibliography} macro to collect its information. Just like +BibTeX, it will search for the specified files in the current directory +and along the path given in the environment variable @code{BIBINPUTS}. +If you do not use BibTeX, but the document contains an explicit +@code{thebibliography} environment, @b{Ref@TeX{}} will collect its +information from there. Note that in this case the information +presented in the selection buffer will just be a copy of relevant +@code{\bibitem} entries, not the structured listing available with +BibTeX database files.@refill + +@kindex ? +In the selection buffer, the following keys provide special commands. A +summary of this information is always available from the selection +process by pressing @kbd{?}.@refill + +@table @kbd +@tablesubheading{General} +@item ? +Show a summary of available commands. + +@item 0-9,- +Prefix argument. + +@tablesubheading{Moving around} +@item n +Go to next article. + +@item p +Go to previous article. + +@tablesubheading{Access to full database entries} +@item @key{SPC} +Show the database entry corresponding to the article at point, in +another window. See also the @kbd{f} key.@refill + +@item f +Toggle follow mode. When follow mode is active, the other window will +always display the full database entry of the current article. This is +equivalent to pressing @key{SPC} after each cursor motion. With BibTeX +entries, follow mode can be rather slow.@refill + +@tablesubheading{Selecting entries and creating the citation} +@item @key{RET} +Insert a citation referencing the article at point into the buffer from +which the selection process was started.@refill + +@item mouse-2 +@vindex reftex-highlight-selection +Clicking with mouse button 2 on a citation will accept it like @key{RET} +would. See also variable @code{reftex-highlight-selection}, @ref{Options +(Misc)}.@refill + +@item m +Mark the current entry. When one or several entries are marked, +pressing @kbd{a} or @kbd{A} accepts all marked entries. Also, +@key{RET} behaves like the @kbd{a} key. + +@item u +Unmark a marked entry. + +@item a +Accept all (marked) entries in the selection buffer and create a single +@code{\cite} macro referring to them.@refill + +@item A +Accept all (marked) entries in the selection buffer and create a +separate @code{\cite} macro for each of it.@refill + +@item @key{TAB} +Enter a citation key with completion. This may also be a key which does +not yet exist. + +@item . +Show insertion point in another window. This is the point from where you +called @code{reftex-citation}.@refill + +@tablesubheading{Exiting} +@item q +Exit the selection process without inserting a citation into the +buffer.@refill + +@tablesubheading{Updating the buffer} + +@item g +Start over with a new regular expression. The full database will be +rescanned with the new expression (see also @kbd{r}).@refill + +@c FIXME: Should we use something else here? r is usually rescan! +@item r +Refine the current selection with another regular expression. This will +@emph{not} rescan the entire database, but just the already selected +entries.@refill + +@end table + +@vindex reftex-select-bib-map +In order to define additional commands for this selection process, the +keymap @code{reftex-select-bib-map} may be used.@refill + +@node Citation Styles, Citation Info, Creating Citations, Citations +@section Citation Styles +@cindex Citation styles +@cindex Citation styles, @code{natbib} +@cindex Citation styles, @code{harvard} +@cindex Citation styles, @code{chicago} +@cindex @code{natbib}, citation style +@cindex @code{harvard}, citation style +@cindex @code{chicago}, citation style + +@vindex reftex-cite-format +The standard LaTeX macro @code{\cite} works well with numeric or simple +key citations. To deal with the more complex task of author-year +citations as used in many natural sciences, a variety of packages has +been developed which define derived forms of the @code{\cite} macro. +@b{Ref@TeX{}} can be configured to produce these citation macros as well by +setting the variable @code{reftex-cite-format}. For the most commonly +used packages (@code{natbib}, @code{harvard}, @code{chicago}) this may +be done from the menu, under @code{Ref->Citation Styles}. Since there +are usually several macros to create the citations, executing +@code{reftex-citation} (@kbd{C-c [}) starts by prompting for the correct +macro. For the Natbib style, this looks like this: + +@example +SELECT A CITATION FORMAT + +[^M] \cite@{%l@} +[t] \citet@{%l@} +[T] \citet*@{%l@} +[p] \citep@{%l@} +[P] \citep*@{%l@} +[e] \citep[e.g.][]@{%l@} +[s] \citep[see][]@{%l@} +[a] \citeauthor@{%l@} +[A] \citeauthor*@{%l@} +[y] \citeyear@{%l@} +@end example + +Following the most generic of these packages, @code{natbib}, the builtin +citation packages always accept the @kbd{t} key for a @emph{textual} +citation (like: @code{Jones et al. (1997) have shown...}) as well as +the @kbd{p} key for a parenthetical citation (like: @code{As shown +earlier (Jones et al, 1997)}).@refill + +To make one of these styles the default, customize the variable +@code{reftex-cite-format} or put into @file{.emacs}: + +@lisp +(setq reftex-cite-format 'natbib) +@end lisp + +You can also use AUCTeX style files to automatically set the +citation style based on the @code{usepackage} commands in a given +document. @xref{Style Files}, for information on how to set up the style +files correctly.@refill + +@node Citation Info, Chapterbib and Bibunits, Citation Styles, Citations, Top +@section Citation Info +@cindex Displaying citations +@cindex Citations, displaying +@cindex Citation info +@cindex Viewing citations +@kindex C-c & +@kindex S-mouse-2 +@findex reftex-view-crossref +@findex reftex-mouse-view-crossref + +When point is idle on the argument of a @code{\cite} macro, the echo area +will display some information about the article cited there. Note +that the information is only displayed if the echo area is not occupied +by a different message. + +@b{Ref@TeX{}} can also display the @code{\bibitem} or BibTeX database +entry corresponding to a @code{\cite} macro, or all citation locations +corresponding to a @code{\bibitem} or BibTeX database entry. +@xref{Viewing Cross-References}.@refill + +@node Chapterbib and Bibunits, Citations Outside LaTeX, Citation Info, Citations +@section Chapterbib and Bibunits +@cindex @code{chapterbib}, LaTeX package +@cindex @code{bibunits}, LaTeX package +@cindex Bibliographies, multiple + +@code{chapterbib} and @code{bibunits} are two LaTeX packages which +produce multiple bibliographies in a document. This is no problem for +@b{Ref@TeX{}} as long as all bibliographies use the same BibTeX database +files. If they do not, it is best to have each document part in a +separate file (as it is required for @code{chapterbib} anyway). Then +@b{Ref@TeX{}} will still scan the locally relevant databases correctly. If +you have multiple bibliographies within a @emph{single file}, this may +or may not be the case. + +@node Citations Outside LaTeX, , Chapterbib and Bibunits, Citations +@section Citations outside LaTeX +@cindex Citations outside LaTeX +@vindex reftex-default-bibliography + +The command @code{reftex-citation} can also be executed outside a LaTeX +buffer. This can be useful to reference articles in the mail buffer and +other documents. You should @emph{not} enter @code{reftex-mode} for +this, just execute the command. The list of BibTeX files will in this +case be taken from the variable @code{reftex-default-bibliography}. +Setting the variable @code{reftex-cite-format} to the symbol +@code{locally} does a decent job of putting all relevant information +about a citation directly into the buffer. Here is the lisp code to add +the @kbd{C-c [} binding to the mail buffer. It also provides a local +binding for @code{reftex-cite-format}.@refill + +@lisp +(add-hook + 'mail-setup-hook + (lambda () + (define-key mail-mode-map "\C-c[" + (lambda () + (interactive) + (require 'reftex) + (let ((reftex-cite-format 'locally)) + (reftex-citation)))))) +@end lisp + +@node Index Support, Viewing Cross-References, Citations, Top +@chapter Index Support +@cindex Index Support +@cindex @code{\index} + +LaTeX has builtin support for creating an Index. The LaTeX core +supports two different indices, the standard index and a glossary. With +the help of special LaTeX packages (@file{multind.sty} or +@file{index.sty}), any number of indices can be supported. + +Index entries are created with the @code{\index@{@var{entry}@}} macro. +All entries defined in a document are written out to the @file{.aux} +file. A separate tool must be used to convert this information into a +nicely formatted index. Tools used with LaTeX include @code{MakeIndex} +and @code{xindy}.@refill + +Indexing is a lot of work and must follow strict conventions, so that +the same word looks the same in all index entries referencing it, and in +order to avoid spurious multiple entries. Therefore, the author of a +document will most likely define special macros to make this easier. To +make @b{Ref@TeX{}} support for indexing possible, these special macros +must be added to @b{Ref@TeX{}}'s configuration (@pxref{Defining Index +Macros}).@refill + +@menu +* Creating Index Entries:: +* Displaying and Editing the Index:: +* Builtin Index Macros:: The index macros RefTeX knows about. +* Defining Index Macros:: ... and macros it doesn't. +@end menu + +@node Creating Index Entries, Displaying and Editing the Index, , Index Support +@section Creating Index Entries +@cindex Creating index entries +@cindex Index entries, creating +@kindex C-c < +@findex reftex-index + +First you need to make sure that @b{Ref@TeX{}} knows about the index +style being used in the current document. @b{Ref@TeX{}} has builtin +support for the default @code{\index} and @code{\glossary} macros. +Other LaTeX packages, like the @file{multind} or @file{index} package, +redefine the @code{\index} macro to have an additional argument, and +@b{Ref@TeX{}} needs to be configured for those. A sufficiently new +version of AUCTeX (9.10c or later) will do this automatically. If you +really don't use AUCTeX (you should!), this configuration needs to be +done by hand with the menu (@code{Ref->Index Style}), or globally for +all your documents with + +@lisp +(setq reftex-index-macros '((multind)) @r{or} +(setq reftex-index-macros '((index)) +@end lisp + +@kindex C-c / +@findex reftex-index-selection-or-word + +In order to index the current selection or the word at the cursor press +@kbd{C-c /} (@code{reftex-index-selection-or-word}). This causes the +selection or word @samp{@var{word}} to be replaced with +@samp{\index@{@var{word}@}@var{word}}. The macro which is used +(@code{\index} by default) can be configured with the variable +@code{reftex-index-default-macro}. When the command is called with a +prefix argument (@kbd{C-u C-c /}), you get a chance to edit the +generated index entry. Use this to change the case of the word or to +make the entry a subentry, for example by entering +@samp{main!sub!@var{word}}. When called with two raw @kbd{C-u} prefixes +(@kbd{C-u C-u C-c /}), you will be asked for the index macro as well. +When there is nothing selected and no word at point, this command will +just call @code{reftex-index}, described below. + +In order to create a general index entry, press @kbd{C-c <} +(@code{reftex-index}). @b{Ref@TeX{}} will prompt for one of the +available index macros and for its arguments. Completion will be +available for the index entry and, if applicable, the index tag. The +index tag is a string identifying one of multiple indices. With the +@file{multind} and @file{index} packages, this tag is the first argument +to the redefined @code{\index} macro.@refill + +@findex reftex-index-globally + +There is also a command @code{reftex-index-globally}@footnote{This +function is still experimentally and may change or go away.} which +copies an index entry near point to other occurrences of the same word +in the document. @b{Ref@TeX{}} assumes that the word you want to index +is in direct contact with the index macro, e.g. +@samp{\index@{@var{word}@}@var{word}} or +@samp{@var{word}\index@{@var{word}@}}. If there is no such word, it +uses the key argument of the index macro. After making you confirm the +precise search and replace strings, a query-replace over the entire +document will be launched. + +@node Displaying and Editing the Index, Builtin Index Macros, Creating Index Entries, Index Support +@section Displaying and Editing the Index +@cindex Displaying the Index +@cindex Editing the Index +@cindex Index entries, creating +@cindex Index, displaying +@cindex Index, editing +@kindex C-c > +@findex reftex-display-index + +In order to compile and display the index, press @kbd{C-c >}. If the +document uses multiple indices, @b{Ref@TeX{}} will ask you to select +one. Then, all index entries will be sorted alphabetically and +displayed in a special buffer, the @file{*Index*} buffer. From that +buffer you can check and edit each entry.@refill + +The index can be restricted to the current section or the region. Then +only entries in that part of the document will go into the compiled +index. To restrict to the current section, use a numeric prefix +@samp{2}, thus press @kbd{C-u 2 C-c >}. To restrict to the current +region, make the region active and use a numeric prefix @samp{3} (press +@kbd{C-u 3 C-c >}). From within the @file{*Index*} buffer the +restriction can be moved from one section to the next with the @kbd{<} +and @kbd{>} keys.@refill + +One caveat: @b{Ref@TeX{}} finds the definition point of an index entry +by searching near the buffer position where it had found to macro during +scanning. If you have several identical index entries in the same +buffer and significant changes have shifted the entries around, you must +rescan the buffer to ensure the correspondence between the +@file{*Index*} buffer and the definition locations. It is therefore +advisable to rescan the document (with @kbd{r} or @kbd{C-u r}) +frequently while editing the index from the @file{*Index*} +buffer.@refill + +@kindex ? +Here is a list of special commands available in the @file{*Index*} buffer. A +summary of this information is always available by pressing +@kbd{?}.@refill + +@table @kbd +@tablesubheading{General} +@item ? +Display a summary of commands. + +@item 0-9, - +Prefix argument. + +@tablesubheading{Moving around} +@item ! A..Z +Pressing any capital letter will jump to the corresponding section in +the @file{*Index*} buffer. The exclamation mark is special and jumps to +the first entries alphabetically sorted below @samp{A}. These are +usually non-alphanumeric characters.@refill +@item n +Go to next entry.@refill +@item p +Go to previous entry.@refill + +@tablesubheading{Access to document locations} +@item @key{SPC} +Show the place in the document where this index entry is defined.@refill + +@item @key{TAB} +Go to the definition of the current index entry in another +window.@refill + +@item @key{RET} +Go to the definition of the current index entry and hide the +@file{*Index*} buffer.@refill + +@item f +@vindex reftex-index-follow-mode +@vindex reftex-revisit-to-follow +Toggle follow mode. When follow mode is active, the other window will +always show the location corresponding to the line in the @file{*Index*} +buffer at point. This is similar to pressing @key{SPC} after each +cursor motion. The default for this flag can be set with the variable +@code{reftex-index-follow-mode}. Note that only context in files +already visited is shown. @b{Ref@TeX{}} will not visit a file just for +follow mode. See, however, the variable +@code{reftex-revisit-to-follow}.@refill + +@tablesubheading{Entry editing} +@item e +Edit the current index entry. In the minibuffer, you can edit the +index macro which defines this entry.@refill + +@item C-k +Kill the index entry. Currently not implemented because I don't know +how to implement an @code{undo} function for this.@refill + +@item * +Edit the @var{key} part of the entry. This is the initial part of the +entry which determines the location of the entry in the index.@refill + +@item | +Edit the @var{attribute} part of the entry. This is the part after the +vertical bar. With @code{MakeIndex}, this part is an encapsulating +macro. With @code{xindy}, it is called @emph{attribute} and is a +property of the index entry that can lead to special formatting. When +called with @kbd{C-u} prefix, kill the entire @var{attribute} +part.@refill + +@item @@ +Edit the @var{visual} part of the entry. This is the part after the +@samp{@@} which is used by @code{MakeIndex} to change the visual +appearance of the entry in the index. When called with @kbd{C-u} +prefix, kill the entire @var{visual} part.@refill + +@item ( +Toggle the beginning of page range property @samp{|(} of the +entry.@refill + +@item ) +Toggle the end of page range property @samp{|)} of the entry.@refill + +@item _ +Make the current entry a subentry. This command will prompt for the +superordinate entry and insert it.@refill + +@item ^ +Remove the highest superordinate entry. If the current entry is a +subitem (@samp{aaa!bbb!ccc}), this function moves it up the hierarchy +(@samp{bbb!ccc}).@refill + +@item & +Globalize the current entry. This runs a search-and-replace through the +entire document in order to index the same word at other places. Rescan +the document in order to get the new entries into the index buffer. For +details, see the command @code{reftex-index-globally}, +@ref{Commands}.@refill + +@tablesubheading{Exiting} +@item q +Hide the @file{*Index*} buffer.@refill + +@item k +Kill the @file{*Index*} buffer.@refill + +@item C-c = +Switch to the Table of Contents buffer of this document.@refill + +@tablesubheading{Controlling what gets displayed} +@item c +@vindex reftex-index-include-context +Toggle the display of short context in the @file{*Index*} buffer. The +default for this flag can be set with the variable +@code{reftex-index-include-context}.@refill + +@item @} +Restrict the index to a single document section. The corresponding +section number will be displayed in the @code{R<>} indication in the +mode line and in the header of the @file{*Index*} buffer.@refill + +@item @{ +Widen the index to contain all entries of the document.@refill + +@item < +When the index is currently restricted, move the restriction to the +previous section.@refill + +@item > +When the index is currently restricted, move the restriction to the +next section.@refill + +@tablesubheading{Updating the buffer} +@item g +Rebuild the @file{*Index*} buffer. This does @emph{not} rescan the +document. However, it sorts the entries again, so that edited entries +will move to the correct position.@refill + +@item r +@vindex reftex-enable-partial-scans +Reparse the LaTeX document and rebuild the @file{*Index*} buffer. When +@code{reftex-enable-partial-scans} is non-nil, rescan only the file this +location is defined in, not the entire document.@refill + +@item C-u r +Reparse the @emph{entire} LaTeX document and rebuild the @file{*Index*} +buffer.@refill + +@item s +Switch to a different index (for documents with multiple +indices).@refill +@end table + + +@node Builtin Index Macros, Defining Index Macros, Displaying and Editing the Index, Index Support +@section Builtin Index Macros +@cindex Builtin index macros +@cindex Index macros, builtin +@vindex reftex-index-macros +@cindex @code{multind}, LaTeX package +@cindex @code{index}, LaTeX package +@cindex LaTeX packages, @code{multind} +@cindex LaTeX packages, @code{index} + +@b{Ref@TeX{}} by default recognizes the @code{\index} and +@code{\glossary} macros which are defined in the LaTeX core. It has +also builtin support for the re-implementations of the @code{\index} +macro of the @file{multind} and @file{index} packages. However, since +the different definitions of the @code{\index} macro are incompatible, +you will have to explicitly specify the index style used. +@xref{Creating Index Entries}, for information on how to do that. + +@node Defining Index Macros, , Builtin Index Macros, Index Support +@section Defining Index Macros +@cindex Defining Index Macros +@cindex Index macros, defining +@vindex reftex-index-macros + +When writing a document with an index you will probably define +additional macros which make entries into the index. +Let's look at an example. + +@example +\newcommand@{\ix@}[1]@{#1\index@{#1@}@} +\newcommand@{\nindex@}[1]@{\textit@{#1@}\index[name]@{#1@}@} +\newcommand@{\astobj@}[1]@{\index@{Astronomical Objects!#1@}@} +@end example + +The first macro @code{\ix} typesets its argument in the text and places +it into the index. The second macro @code{\nindex} typesets its +argument in the text and places it into a separate index with the tag +@samp{name}@footnote{We are using the syntax of the @file{index} package +here.}. The last macro also places its argument into the index, but as +subitems under the main index entry @samp{Astronomical Objects}. Here +is how to make @b{Ref@TeX{}} recognize and correctly interpret these +macros, first with Emacs Lisp. + +@lisp +(setq reftex-index-macros + '(("\\ix@{*@}" "idx" ?x "" nil) + ("\\nindex@{*@}" "name" ?n "" nil) + ("\\astobj@{*@}" "idx" ?o "Astronomical Objects!" nil))) +@end lisp + +Note that the index tag is @samp{idx} for the main index, and +@samp{name} for the name index. @samp{idx} and @samp{glo} are reserved +for the default index and for the glossary. + +The character arguments @code{?x}, @code{?n}, and @code{?o} are for +quick identification of these macros when @b{Ref@TeX{}} inserts new +index entries with @code{reftex-index}. These codes need to be +unique. @code{?i}, @code{?I}, and @code{?g} are reserved for the +@code{\index}, @code{\index*}, and @code{\glossary} macros, +respectively. + +The following string is empty unless your macro adds a superordinate +entry to the index key - this is the case for the @code{\astobj} macro. + +To do the same thing with customize, you need to fill in the templates +like this: + +@example +Repeat: +[INS] [DEL] List: + Macro with args: \ix@{*@} + Index Tag : [Value Menu] String: idx + Access Key : x + Key Prefix : + Exclusion hook : nil +[INS] [DEL] List: + Macro with args: \nindex@{*@} + Index Tag : [Value Menu] String: name + Access Key : n + Key Prefix : + Exclusion hook : nil +[INS] [DEL] List: + Macro with args: \astobj@{*@} + Index Tag : [Value Menu] String: idx + Access Key : o + Key Prefix : Astronomical Objects! + Exclusion hook : nil +[INS] +@end example + +With the macro @code{\ix} defined, you may want to change the default +macro used for indexing a text phrase (@pxref{Creating Index Entries}). +This would be done like this + +@lisp +(setq reftex-index-default-macro '(?x "idx" nil)) +@end lisp + +which specifies that the macro identified with the character @code{?x} (the +@code{\ix} macro) should be used for indexing phrases and words already +in the buffer with @kbd{C-c /} (@code{reftex-index-selection-or-word}). +The index tag is "idx", and the final @code{nil} means that it is not +necessary to repeat the phrase outside the macro, because the macro +indexes @emph{and} typesets is argument. + +@node Viewing Cross-References, RefTeXs Menu, Index Support, Top +@chapter Viewing Cross--References +@findex reftex-view-crossref +@findex reftex-mouse-view-crossref +@kindex C-c & +@kindex S-mouse-2 + +@b{Ref@TeX{}} can display cross--referencing information. This means, +if two document locations are linked, @b{Ref@TeX{}} can display the +matching location(s) in another window. The @code{\label} and @code{\ref} +macros are one way of establishing such a link. Also, a @code{\cite} +macro is linked to the corresponding @code{\bibitem} macro or a BibTeX +database entry.@refill + +The feature is invoked by pressing @kbd{C-c &} +(@code{reftex-view-crossref}) while point is on the @var{key} argument +of a macro involved in cross--referencing. You can also click with +@kbd{S-mouse-2} on the macro argument. Here is what will happen for +individual classes of macros:@refill + +@table @asis + +@item @code{\ref} +@cindex @code{\ref} +Display the corresponding label definition. All usual +variants@footnote{all macros that start with @samp{ref} or end with +@samp{ref} or @samp{refrange}} of the @code{\ref} macro are active for +cross--reference display. This works also for labels defined in an +external document when the current document refers to them through the +@code{xr} interface (@pxref{xr (LaTeX package)}).@refill + +@item @code{\label} +@cindex @code{\label} +@vindex reftex-label-alist +Display a document location which references this label. Pressing +@kbd{C-c &} several times moves through the entire document and finds +all locations. Not only the @code{\label} macro but also other macros +with label arguments (as configured with @code{reftex-label-alist}) are +active for cross--reference display.@refill + +@item @code{\cite} +@cindex @code{\cite} +Display the corresponding BibTeX database entry or @code{\bibitem}. +All usual variants@footnote{all macros that either start or end with +@samp{cite}} of the @code{\cite} macro are active for cross--reference +display.@refill + +@item @code{\bibitem} +@cindex @code{\bibitem} +Display a document location which cites this article. Pressing +@kbd{C-c &} several times moves through the entire document and finds +all locations.@refill + +@item BibTeX +@cindex BibTeX buffer, viewing cite locations from +@cindex Viewing cite locations from BibTeX buffer +@kbd{C-c &} is also active in BibTeX buffers. All locations in a +document where the database entry at point is cited will be displayed. +On first use, @b{Ref@TeX{}} will prompt for a buffer which belongs to +the document you want to search. Subsequent calls will use the same +document, until you break this link with a prefix argument to @kbd{C-c +&}.@refill + +@item @code{\index} +@cindex @code{\index} +Display other locations in the document which are marked by an index +macro with the same key argument. Along with the standard @code{\index} +and @code{\glossary} macros, all macros configured in +@code{reftex-index-macros} will be recognized.@refill +@end table + +@vindex reftex-view-crossref-macros +While the display of cross referencing information for the above +mentioned macros is hard--coded, you can configure additional relations +in the variable @code{reftex-view-crossref-macros}. + +@iftex +@chapter All the Rest +@end iftex + +@node RefTeXs Menu, Keybindings, Viewing Cross-References, Top +@section @b{Ref@TeX{}}'s Menu +@cindex RefTeXs Menu +@cindex Menu, in the menu bar + +@b{Ref@TeX{}} installs a @code{Ref} menu in the menu bar on systems +which support this. From this menu you can access all of +@b{Ref@TeX{}}'s commands and a few of its options. There is also a +@code{Customize} submenu which can be used to access @b{Ref@TeX{}}'s +entire set of options.@refill + +@node Keybindings, Faces, RefTeXs Menu, Top +@section Default Keybindings +@cindex Keybindings, summary + +Here is a summary of the available keybindings. + +@kindex C-c = +@kindex C-c ( +@kindex C-c ) +@kindex C-c [ +@kindex C-c & +@kindex S-mouse-2 +@kindex C-c / +@kindex C-c < +@kindex C-c > +@example +@kbd{C-c =} @code{reftex-toc} +@kbd{C-c (} @code{reftex-label} +@kbd{C-c )} @code{reftex-reference} +@kbd{C-c [} @code{reftex-citation} +@kbd{C-c &} @code{reftex-view-crossref} +@kbd{S-mouse-2} @code{reftex-mouse-view-crossref} +@kbd{C-c /} @code{reftex-index-selection-or-word} +@kbd{C-c <} @code{reftex-index} +@kbd{C-c >} @code{reftex-display-index} +@end example + +Note that the @kbd{S-mouse-2} binding is only provided if this key is +not already used by some other package. @b{Ref@TeX{}} will not override an +existing binding to @kbd{S-mouse-2}.@refill + +Personally, I also bind some functions in the users @kbd{C-c} map for +easier access.@refill + +@c FIXME: Do we need bindings for the Index macros here as well? +@c C-c i C-c I or so???? +@c How about keybindings for reftex-reset-mode and reftex-parse-document? +@kindex C-c t +@kindex C-c l +@kindex C-c r +@kindex C-c c +@kindex C-c v +@kindex C-c s +@kindex C-c g +@example +@kbd{C-c t} @code{reftex-toc} +@kbd{C-c l} @code{reftex-label} +@kbd{C-c r} @code{reftex-reference} +@kbd{C-c c} @code{reftex-citation} +@kbd{C-c v} @code{reftex-view-crossref} +@kbd{C-c s} @code{reftex-search-document} +@kbd{C-c g} @code{reftex-grep-document} +@end example + +@noindent These keys are reserved for the user, so I cannot bind them by +default. If you want to have these keybindings available, set in your +@file{.emacs} file: + +@vindex reftex-extra-bindings +@lisp +(setq reftex-extra-bindings t) +@end lisp + +@vindex reftex-load-hook +Changing and adding to @b{Ref@TeX{}}'s keybindings is best done in the hook +@code{reftex-load-hook}. For information on the keymaps +which should be used to add keys, see @ref{Keymaps and Hooks}. + +@node Faces, AUCTeX, Keybindings, Top +@section Faces +@cindex Faces + +@b{Ref@TeX{}} uses faces when available to structure the selection and +table of contents buffers. It does not create its own faces, but uses +the ones defined in @file{font-lock.el}. Therefore, @b{Ref@TeX{}} will +use faces only when @code{font-lock} is loaded. This seems to be +reasonable because people who like faces will very likely have it +loaded. If you wish to turn off fontification or change the involved +faces, see @ref{Options (Fontification)}.@refill + +@node Multifile Documents, Language Support, AUCTeX, Top +@section Multifile Documents +@cindex Multifile documents +@cindex Documents, spread over files + +The following is relevant when working with documents spread over many +files:@refill + +@itemize @bullet +@item +@b{Ref@TeX{}} has full support for multifile documents. You can edit parts of +several (multifile) documents at the same time without conflicts. +@b{Ref@TeX{}} provides functions to run @code{grep}, @code{search} and +@code{query-replace} on all files which are part of a multifile +document.@refill + +@item +@vindex tex-main-file +@vindex TeX-master +All files belonging to a multifile document should have a File Variable +(@code{TeX-master} for AUCTeX or @code{tex-main-file} for the +standard Emacs LaTeX mode) set to the name of the master file. See the +documentation of your (La)TeX mode and @ref{File Variables,,,emacs, The +GNU Emacs Manual}.@refill + +@item +The context of a label definition must be found in the same file as the +label itself in order to be processed correctly by @b{Ref@TeX{}}. The only +exception is that section labels referring to a section statement +outside the current file can still use that section title as +context.@refill +@end itemize + +@node Language Support, Finding Files, Multifile Documents, Top +@section Language Support +@cindex Language support + +Some parts of @b{Ref@TeX{}} are language dependent. The default +settings work well for English. If you are writing in a different +language, the following hints may be useful: + +@itemize @bullet +@item +@vindex reftex-derive-label-parameters +@vindex reftex-abbrev-parameters +The mechanism to derive a label from context includes the abbreviation +of words and omission of unimportant words. These mechanisms may have +to be changed for other languages. See the variables +@code{reftex-derive-label-parameters} and @code{reftex-abbrev-parameters}. + +@item +@vindex reftex-translate-to-ascii-function +@vindex reftex-label-illegal-re +Also, when a label is derived from context, @b{Ref@TeX{}} clears the +context string from non-ASCII characters in order to make a legal label. +If there should ever be a version of @TeX{} which allows extended +characters @emph{in labels}, then we will have to look at the +variables @code{reftex-translate-to-ascii-function} and +@code{reftex-label-illegal-re}. + +@item +When a label is referenced, @b{Ref@TeX{}} looks at the word before point +to guess which label type is required. These @emph{magic words} are +different in every language. For an example of how to add magic words, +see @ref{Adding Magic Words}. + +@vindex reftex-multiref-punctuation +@vindex reftex-cite-punctuation +@item +@b{Ref@TeX{}} inserts ``punctuation'' for multiple references and +for the author list in citations. Some of this may be language +dependent. See the variables @code{reftex-multiref-punctuation} and +@code{reftex-cite-punctuation}. +@end itemize + +@node Finding Files, Optimizations, Language Support, Top +@section Finding Files +@cindex Finding files + +In order to find files included in a document via @code{\input} or +@code{\include}, @b{Ref@TeX{}} searches all directories specified in the +environment variable @code{TEXINPUTS}. Similarly, it will search the +path specified in the variables @code{BIBINPUTS} and @code{TEXBIB} for +BibTeX database files. + +When searching, @b{Ref@TeX{}} will also expand recursive path +definitions (directories ending in @samp{//} or @samp{!!}). But it will +only search and expand directories @emph{explicitly} given in these +variables. This may cause problems under the following circumstances: + +@itemize @bullet +@item +Most TeX system have a default search path for both TeX files and BibTeX +files which is defined in some setup file. Usually this default path is +for system files which @b{Ref@TeX{}} does not need to see. But if your +document needs TeX files or BibTeX database files in a directory only +given in the default search path, @b{Ref@TeX{}} will fail to find them. +@item +Some TeX systems do not use environment variables at all in order to +specify the search path. Both default and user search path are then +defined in setup files. +@end itemize + +@noindent +There are three ways to solve this problem: + +@itemize @bullet +@item +Specify all relevant directories explicitly in the environment +variables. If for some reason you don't want to mess with the default +variables @code{TEXINPUTS} and @code{BIBINPUTS}, define your own +variables and configure @b{Ref@TeX{}} to use them instead: + +@lisp +(setq reftex-texpath-environment-variables '("MYTEXINPUTS")) +(setq reftex-bibpath-environment-variables '("MYBIBINPUTS")) +@end lisp + +@item +Specify the full search path directly in @b{Ref@TeX{}}'s variables. + +@lisp +(setq reftex-texpath-environment-variables + '("./inp:/home/cd/tex//:/usr/local/tex//")) +(setq reftex-bibpath-environment-variables + '("/home/cd/tex/lit/")) +@end lisp + +@item +Some TeX systems provide stand--alone programs to do the file search just +like TeX and BibTeX. E.g. Thomas Esser's @code{teTeX} uses the +@code{kpathsearch} library which provides the command @code{kpsewhich} +to search for files. @b{Ref@TeX{}} can be configured to use this +program. Note that the exact syntax of the @code{kpsewhich} +command depends upon the version of that program. + +@lisp +(setq reftex-use-external-file-finders t) +(setq reftex-external-file-finders + '(("tex" "kpsewhich -format=.tex %f") + ("bib" "kpsewhich -format=.bib %f"))) +@end lisp +@end itemize + +@node Optimizations, Problems and Work-Arounds, Finding Files, Top +@section Optimizations +@cindex Optimizations + +Implementing the principle of least surprises, the default settings of +@b{Ref@TeX{}} ensure a safe ride for beginners and casual users. However, +when using @b{Ref@TeX{}} for a large project and/or on a small computer, +there are ways to improve speed or memory usage.@refill + +@itemize @bullet +@item +@b{Removing Lookup Buffers}@* +@cindex Removing lookup buffers +@b{Ref@TeX{}} will load other parts of a multifile document as well as BibTeX +database files for lookup purposes. These buffers are kept, so that +subsequent use of the same files is fast. If you can't afford keeping +these buffers around, and if you can live with a speed penalty, try + +@vindex reftex-keep-temporary-buffers +@lisp +(setq reftex-keep-temporary-buffers nil) +@end lisp + +@item +@b{Partial Document Scans}@* +@cindex Partial documents scans +@cindex Document scanning, partial +A @kbd{C-u} prefix on the major @b{Ref@TeX{}} commands @code{reftex-label} +(@kbd{C-u C-c (}), @code{reftex-reference} (@kbd{C-u C-c )}), +@code{reftex-citation} (@kbd{C-u C-c [}), @code{reftex-toc} (@kbd{C-u C-c +=}), and @code{reftex-view-crossref} (@kbd{C-u C-c &}) initiates +re-parsing of the entire document in order to update the parsing +information. For a large document this can be unnecessary, in +particular if only one file has changed. @b{Ref@TeX{}} can be configured +to do partial scans instead of full ones. @kbd{C-u} re-parsing then +does apply only to the current buffer and files included from it. +Likewise, the @kbd{r} key in both the label selection buffer and the +table-of-contents buffer will only prompt scanning of the file in which +the label or section macro near the cursor was defined. Re-parsing of +the entire document is still available by using @kbd{C-u C-u} as a +prefix, or the capital @kbd{R} key in the menus. To use this feature, +try@refill + +@vindex reftex-enable-partial-scans +@lisp +(setq reftex-enable-partial-scans t) +@end lisp + +@item +@b{Saving Parser Information}@* +@cindex Saving parser information +@cindex Parse information, saving to a file +Even with partial scans enabled, @b{Ref@TeX{}} still has to make one full +scan, when you start working with a document. To avoid this, parsing +information can be stored in a file. The file @file{MASTER.rel} is used +for storing information about a document with master file +@file{MASTER.tex}. It is written automatically when you kill a buffer +in @code{reftex-mode} or when you exit Emacs. The information is +restored when you begin working with a document in a new editing +session. To use this feature, put into @file{.emacs}:@refill + +@vindex reftex-save-parse-info +@lisp +(setq reftex-save-parse-info t) +@end lisp + +@item +@b{Automatic Document Scans}@* +@cindex Automatic document scans +@cindex Document scanning, automatic +At rare occasions, @b{Ref@TeX{}} will automatically rescan a part of the +document. If this gets into your way, it can be turned off with + +@vindex reftex-allow-automatic-rescan +@lisp +(setq reftex-allow-automatic-rescan nil) +@end lisp + +@b{Ref@TeX{}} will then occasionally annotate new labels in the selection +buffer, saying that their position in the label list in uncertain. A +manual document scan will fix this.@refill + +@item +@b{Multiple Selection Buffers}@* +@cindex Multiple selection buffers +@cindex Selection buffers, multiple +Normally, the selection buffer @file{*RefTeX Select*} is re-created for +every selection process. In documents with very many labels this can +take several seconds. @b{Ref@TeX{}} provides an option to create a +separate selection buffer for each label type and to keep this buffer +from one selection to the next. These buffers are updated automatically +only when a new label has been added in the buffers category with +@code{reftex-label}. Updating the buffer takes as long as recreating it +- so the time saving is limited to cases where no new labels of that +category have been added. To turn on this feature, use@refill + +@vindex reftex-use-multiple-selection-buffers +@lisp +(setq reftex-use-multiple-selection-buffers t) +@end lisp + +@noindent +@cindex Selection buffers, updating +You can also inhibit the automatic updating entirely. Then the +selection buffer will always pop up very fast, but may not contain the +most recently defined labels. You can always update the buffer by hand, +with the @kbd{g} key. To get this behavior, use instead@refill + +@vindex reftex-auto-update-selection-buffers +@lisp +(setq reftex-use-multiple-selection-buffers t + reftex-auto-update-selection-buffers nil) +@end lisp +@end itemize + +@need 2000 +@noindent +@b{As a summary}, here are the settings I recommend for heavy use of +@b{Ref@TeX{}} with large documents: + +@lisp +@group +(setq reftex-enable-partial-scans t + reftex-save-parse-info t + reftex-use-multiple-selection-buffers t) +@end group +@end lisp + +@page +@node AUCTeX, Multifile Documents, Faces, Top +@section @w{AUC @TeX{}} +@cindex @code{AUCTeX}, Emacs package +@cindex Emacs packages, @code{AUCTeX} + +AUCTeX is without doubt the best major mode for editing TeX and LaTeX +files with Emacs. If AUCTeX is not part of you Emacs distribution, you +can get it@footnote{XEmacs 21.x users may +want to install the corresponding XEmacs package.} by ftp from the +@uref{http://www.sunsite.auc.dk/auctex/,AUCTeX distribution site}. + +@menu +* AUCTeX-RefTeX Interface:: How both packages work together +* Style Files:: AUCTeX's style files can support RefTeX +* Bib-Cite:: Hypertext reading of a document +@end menu + +@node AUCTeX-RefTeX Interface, Style Files, , AUCTeX +@subsection The AUC@TeX{}-@b{Ref@TeX{}} Interface + +@b{Ref@TeX{}} contains code to interface with AUCTeX. When this +interface is turned on, both packages will interact closely. Instead of +using @b{Ref@TeX{}}'s commands directly, you can then also use them +indirectly as part of the AUCTeX +environment@footnote{@b{Ref@TeX{}} 4.0 and AUCTeX 9.10c will be +needed for all of this to work. Parts of it work also with earlier +versions.}. The interface is turned on with@refill + +@lisp +(setq reftex-plug-into-AUCTeX t) +@end lisp + +If you need finer control about which parts of the interface are used +and which not, read the docstring of the variable +@code{reftex-plug-into-AUCTeX} or customize it with @kbd{M-x +customize-variable @key{RET} reftex-plug-into-AUCTeX @key{RET}}. + +The following list describes the individual parts of the interface. + +@itemize @bullet +@item +@findex reftex-label +@vindex LaTeX-label-function, @r{AUCTeX} +@kindex C-c C-e +@kindex C-c C-s +@findex LaTeX-section, @r{AUCTeX} +@findex TeX-insert-macro, @r{AUCTeX} +@b{AUCTeX calls @code{reftex-label} to insert labels}@* +When a new section is created with @kbd{C-c C-s}, or a new environment +is inserted with @kbd{C-c C-e}, AUCTeX normally prompts for a label to +go with it. With the interface, @code{reftex-label} is called instead. +For example, if you type @kbd{C-c C-e equation @key{RET}}, AUCTeX and +@b{Ref@TeX{}} will insert + +@example +\begin@{equation@} +\label@{eq:1@} + +\end@{equation@} +@end example + +@noindent +without further prompts. + +Similarly, when you type @kbd{C-c C-s section @key{RET}}, @b{Ref@TeX{}} +will offer its default label which is derived from the section title. + +@item +@b{AUCTeX tells @b{Ref@TeX{}} about new sections}@* +When creating a new section with @kbd{C-c C-s}, @b{Ref@TeX{}} will not +have to rescan the buffer in order to see it.@refill + +@item +@findex reftex-arg-label +@findex TeX-arg-label, @r{AUCTeX function} +@findex reftex-arg-ref +@findex TeX-arg-ref, @r{AUCTeX function} +@findex reftex-arg-cite +@findex TeX-arg-cite, @r{AUCTeX function} +@findex reftex-arg-index +@findex TeX-arg-index, @r{AUCTeX function} +@findex TeX-insert-macro, @r{AUCTeX function} +@kindex C-c @key{RET} +@b{@b{Ref@TeX{}} supplies macro arguments}@* When you insert a macro +interactively with @kbd{C-c @key{RET}}, AUCTeX normally prompts for +macro arguments. Internally, it uses the functions +@code{TeX-arg-label}, @code{TeX-arg-cite}, and @code{TeX-arg-index} to +prompt for arguments which are labels, citation keys and index entries. +The interface takes over these functions@footnote{@code{fset} is used to +do this, which is not reversible. However, @b{Ref@TeX{}} implements the +old functionality when you later decide to turn off the interface.} and +supplies the macro arguments with @b{Ref@TeX{}'s} mechanisms. For +example, when you type @kbd{C-c @key{RET} ref @key{RET}}, @b{Ref@TeX{}} +will supply its label selection process (@pxref{Referencing +Labels}).@refill + +@item +@b{@b{Ref@TeX{}} tells AUCTeX about new labels, citation-- and index keys}@* +@b{Ref@TeX{}} will add all newly created labels to AUCTeX's completion list. +@end itemize + +@node Style Files, Bib-Cite, AUCTeX-RefTeX Interface, AUCTeX +@subsection Style Files +@cindex Style files, AUCTeX +@findex TeX-add-style-hook, @r{AUCTeX} +Style files are Emacs Lisp files which are evaluated by AUCTeX in +association with the @code{\documentclass} and @code{\usepackage} +commands of a document. Support for @b{Ref@TeX{}} in such a style file +is useful when the LaTeX style defines macros or environments connected +with labels, citations, or the index. Many style files +(e.g. @file{amsmath.el} or @file{natbib.el}) distributed with AUCTeX +already support @b{Ref@TeX{}} in this way.@refill + +Before calling a @b{Ref@TeX{}} function, the style hook should always +test for the availability of the function, so that the style file will +also work for people who do not use @b{Ref@TeX{}}. @refill + +Additions made with style files in the way described below remain local +to the current document. For example, if one package uses AMSTeX, the +style file will make @b{Ref@TeX{}} switch over to @code{\eqref}, but +this will not affect other documents.@refill + +@findex reftex-add-label-environments +@findex reftex-add-to-label-alist +A style hook may contain calls to +@code{reftex-add-label-environments}@footnote{This used to be the +function @code{reftex-add-to-label-alist} which is still available as an +alias for compatibility.} which defines additions to +@code{reftex-label-alist}. The argument taken by this function must have +the same format as @code{reftex-label-alist}. The @file{amsmath.el} +style file of AUCTeX for example contains the following:@refill + +@lisp +@group +(TeX-add-style-hook "amsmath" + (lambda () + (if (fboundp 'reftex-add-label-environments) + (reftex-add-label-environments '(AMSTeX))))) +@end group +@end lisp + +@noindent +@findex LaTeX-add-environments, @r{AUCTeX} +while a package @code{myprop} defining a @code{proposition} environment +with @code{\newtheorem} might use@refill + +@lisp +@group +(TeX-add-style-hook "myprop" + (lambda () + (LaTeX-add-environments '("proposition" LaTeX-env-label)) + (if (fboundp 'reftex-add-label-environments) + (reftex-add-label-environments + '(("proposition" ?p "prop:" "~\\ref@{%s@}" t + ("Proposition" "Prop."))))))) +@end group +@end lisp + +@findex reftex-set-cite-format +Similarly, a style hook may contain a call to +@code{reftex-set-cite-format} to set the citation format. The style +file @file{natbib.el} for the Natbib citation style does switch +@b{Ref@TeX{}}'s citation format like this:@refill + +@lisp +(TeX-add-style-hook "natbib" + (lambda () + (if (fboundp 'reftex-set-cite-format) + (reftex-set-cite-format 'natbib)))) +@end lisp + +@findex reftex-add-index-macros +The hook may contain a call to @code{reftex-add-index-macros} to +define additional @code{\index}-like macros. The argument must have +the same format as @code{reftex-index-macros}. It may be a symbol, to +trigger support for one of the builtin index packages. For example, +the style @file{multind.el} contains + +@lisp +(TeX-add-style-hook "multind" + (lambda () + (and (fboundp 'reftex-add-index-macros) + (reftex-add-index-macros '(multind))))) +@end lisp + +If you have your own package @file{myindex} which defines the +following macros to be used with the LaTeX @file{index.sty} file +@example +\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}@} +\newcommand@{\aindex@}[1]@{#1\index[author]@{#1@} +@end example + +you could write this in the style file @file{myindex.el}: + +@lisp +(TeX-add-style-hook "myindex" + (lambda () + (TeX-add-symbols + '("molec" TeX-arg-index) + '("aindex" TeX-arg-index)) + (if (fboundp 'reftex-add-index-macros) + (reftex-add-index-macros + '(("molec@{*@}" "idx" ?m "Molecules!" nil) + ("aindex@{*@}" "author" ?a "" nil)))))) +@end lisp + +@findex reftex-add-section-levels +Finally the hook may contain a call to @code{reftex-add-section-levels} +to define additional section statements. For example, the FoilTeX class +has just two headers, @code{\foilhead} and @code{\rotatefoilhead}. Here +is a style file @file{foils.el} that will inform @b{Ref@TeX{}} about these: + +@lisp +(TeX-add-style-hook "foils" + (lambda () + (if (fboundp 'reftex-add-section-levels) + (reftex-add-section-levels '(("foilhead" . 3) + ("rotatefoilhead" . 3)))))) +@end lisp + +@node Bib-Cite, , Style Files, AUCTeX +@subsection Bib-Cite +@cindex @code{bib-cite}, Emacs package +@cindex Emacs packages, @code{bib-cite} + +Once you have written a document with labels, references and citations, +it can be nice to read it like a hypertext document. @b{Ref@TeX{}} has +some support for that: @code{reftex-view-crossref} (bound to @kbd{C-c +&}), @code{reftex-mouse-view-crossref} (bound to @kbd{S-mouse-2}), and +@code{reftex-search-document}. A somewhat fancier interface with mouse +highlighting is provided (among other things) by Peter S. Galbraith's +@file{bib-cite.el}. There is some overlap in the functionalities of +Bib-cite and @b{Ref@TeX{}}. Bib-cite.el comes bundled with +AUCTeX.@refill + +Bib-cite version 3.06 and later can be configured so that bib-cite's +mouse functions use @b{Ref@TeX{}} for displaying references and citations. +This can be useful in particular when working with the LaTeX @code{xr} +package or with an explicit @code{thebibliography} environment (rather +than BibTeX). Bib-cite cannot handle those, but @b{Ref@TeX{}} does. To +make use of this feature, try@refill + +@vindex bib-cite-use-reftex-view-crossref +@lisp +(setq bib-cite-use-reftex-view-crossref t) +@end lisp + +@page +@node Problems and Work-Arounds, Imprint, Optimizations, Top +@section Problems and Work-arounds +@cindex Problems and work-arounds + +@itemize @bullet +@item +@b{LaTeX commands}@* +@cindex LaTeX commands, not found +@code{\input}, @code{\include}, @code{\bibliography} and @code{\section} +(etc.) statements have to be first on a line (except for white space).@refill + +@item +@b{Commented regions}@* +@cindex Labels, commented out +@b{Ref@TeX{}} sees also labels in regions commented out and will refuse to +make duplicates of such labels. This is considered to be a feature.@refill + +@item +@b{Wrong section numbers}@* +@cindex Section numbers, wrong +@vindex reftex-enable-partial-scans +When using partial scans (@code{reftex-enable-partial-scans}), the section +numbers in the table of contents may eventually become wrong. A full +scan will fix this.@refill + +@item +@b{Local settings}@* +@cindex Settings, local +@findex reftex-add-label-environments +@findex reftex-set-cite-format +@findex reftex-add-section-levels +The label environment definitions in @code{reftex-label-alist} are +global and apply to all documents. If you need to make definitions +local to a document, because they would interfere with settings in other +documents, you should use AUCTeX and set up style files with calls to +@code{reftex-add-label-environments}, @code{reftex-set-cite-format}, +@code{reftex-add-index-macros}, and @code{reftex-add-section-levels}. +Settings made with these functions remain local to the current +document. @xref{AUCTeX}.@refill + +@item +@b{Funny display in selection buffer}@* +@cindex @code{x-symbol}, Emacs package +@cindex Emacs packages, @code{x-symbol} +@cindex @code{isotex}, Emacs package +@cindex Emacs packages, @code{isotex} +@cindex @code{iso-cvt}, Emacs package +@cindex Emacs packages, @code{iso-cvt} +When using packages which make the buffer representation of a file +different from its disk representation (e.g. x-symbol, isotex, +iso-cvt) you may find that @b{Ref@TeX{}}'s parsing information sometimes +reflects the disk state of a file. This happens only in @emph{unvisited} +parts of a multifile document, because @b{Ref@TeX{}} visits these files +literally for speed reasons. Then both short context and section +headings may look different from what you usually see on your screen. +In rare cases @code{reftex-toc} may have problems to jump to an affected +section heading. There are three possible ways to deal with +this:@refill +@itemize @minus +@item +@vindex reftex-keep-temporary-buffers +@code{(setq reftex-keep-temporary-buffers t)}@* +This implies that @b{Ref@TeX{}} will load all parts of a multifile +document into Emacs (i.e. there won't be any temporary buffers).@refill +@item +@vindex reftex-initialize-temporary-buffers +@code{(setq reftex-initialize-temporary-buffers t)}@* +This means full initialization of temporary buffers. It involves +a penalty when the same unvisited file is used for lookup often.@refill +@item +Set @code{reftex-initialize-temporary-buffers} to a list of hook +functions doing a minimal initialization.@refill +@end itemize +@vindex reftex-refontify-context +See also the variable @code{reftex-refontify-context}. + +@item +@b{Labels as arguments to \begin}@* +@cindex @code{pf}, LaTeX package +@cindex LaTeX packages, @code{pf} +Some packages use an additional argument to a @code{\begin} macro +to specify a label. E.g. Lamport's @file{pf.sty} uses both +@example +\step@{@var{label}@}@{@var{claim}@} and \begin@{step+@}@{@var{label}@} + @var{claim} + \end@{step+@} +@end example + +@noindent +We need to trick @b{Ref@TeX{}} into swallowing this: + +@lisp +@group +;; Configuration for Lamport's pf.sty +(setq reftex-label-alist + '(("\\step@{*@}@{@}" ?p "st:" "~\\stepref@{%s@}" 2 ("Step" "St.")) + ("\\begin@{step+@}@{*@}" ?p "st:" "~\\stepref@{%s@}" 1000))) +@end group +@end lisp + +@noindent +The first line is just a normal configuration for a macro. For the +@code{step+} environment we actually tell @b{Ref@TeX{}} to look for the +@emph{macro} @samp{\begin@{step+@}} and interpret the @emph{first} +argument (which really is a second argument to the macro @code{\begin}) +as a label of type @code{?p}. Argument count for this macro starts only +after the @samp{@{step+@}}, also when specifying how to get +context.@refill + +@item +@b{Idle timers in XEmacs}@* +@cindex Idle timer restart +@vindex reftex-use-itimer-in-xemacs +In XEmacs, idle timer restart does not work reliably after fast +keystrokes. Therefore @b{Ref@TeX{}} currently uses the post command +hook to start the timer used for automatic crossref information. When +this bug gets fixed, a real idle timer can be requested with +@lisp +(setq reftex-use-itimer-in-xemacs t) +@end lisp + +@item +@b{Viper mode}@* +@cindex Viper mode +@cindex Keybindings, problems with Viper mode +@findex viper-harness-minor-mode +With @i{Viper} mode prior to Vipers version 3.01, you need to protect +@b{Ref@TeX{}}'s keymaps with@refill + +@lisp +(viper-harness-minor-mode "reftex") +@end lisp + +@end itemize + +@page +@node Imprint, Commands, Problems and Work-Arounds, Top +@section Imprint +@cindex Imprint +@cindex Maintainer +@cindex Acknowledgments +@cindex Thanks +@cindex Bug reports +@cindex @code{http}, @b{Ref@TeX{}} home page +@cindex @code{ftp}, @b{Ref@TeX{}} site + +@b{Ref@TeX{}} was written by @i{@value{AUTHOR}} +@email{@value{AUTHOR-EMAIL}}, with contributions by @i{Stephen +Eglen}. @b{Ref@TeX{}} is currently maintained by @refill + +@noindent +@value{MAINTAINER} @email{@value{MAINTAINER-EMAIL}} + +If you have questions about @b{Ref@TeX{}}, there are several Usenet +groups which have competent readers: @code{comp.emacs}, +@code{gnu.emacs.help}, @code{comp.emacs.xemacs}, @code{comp.text.tex}. +You can also write directly to the maintainer. + +If you find a bug in @b{Ref@TeX{}} or its documentation, or if you want +to contribute code or ideas, please +@uref{mailto:@value{MAINTAINER-EMAIL},contact the maintainer}. Remember +to provide all necessary information such as version numbers of Emacs +and @b{Ref@TeX{}}, and the relevant part of your configuration in +@file{.emacs}. When reporting a bug which throws an exception, please +include a backtrace if you know how to produce one. + +@b{Ref@TeX{}} is bundled and pre-installed with Emacs since version 20.2. +It was also bundled and pre-installed with XEmacs 19.16--20.x. XEmacs +21.x users want to install the corresponding plugin package which is +available from the XEmacs @code{ftp} site. See the XEmacs 21.x +documentation on package installation for details.@refill + +Users of earlier Emacs distributions (including Emacs 19) can get a +@b{Ref@TeX{}} distribution from the +@uref{http://www.strw.leidenuniv.nl/~dominik/Tools/,maintainers +webpage}. Note that the Emacs 19 version supports many but not all +features described in this manual.@refill + +Thanks to the people on the Net who have used @b{Ref@TeX{}} and helped +developing it with their reports. In particular thanks to +@i{Fran Burstall, Alastair Burt, Soren Dayton, Stephen Eglen, Karl +Eichwalder, Peter Galbraith, Kai Grossjohann, Dieter Kraft, Adrian Lanz, +Rory Molinari, Stefan Monnier, Laurent Mugnier, Sudeep Kumar Palat, +Daniel Polani, Robin Socha, Richard Stanton, Allan Strand, Jan Vroonhof, +Christoph Wedler, Alan Williams}.@refill + +The @code{view-crossref} feature was inspired by @i{Peter Galbraith's} +@file{bib-cite.el}.@refill + +Finally thanks to @i{Uwe Bolick} who first got me (some years ago) into +supporting LaTeX labels and references with an editor (which was +MicroEmacs at the time).@refill + +@node Commands, Options, Imprint, Top +@chapter Commands +@cindex Commands, list of + +Here is a summary of @b{Ref@TeX{}}'s commands. All commands are available +from the @code{Ref} menu. For keybindings, @pxref{Keybindings}. + +@deffn Command reftex-toc +Show the table of contents for the current document. When called with +one ore two @kbd{C-u} prefixes, rescan the document first.@refill +@end deffn + +@deffn Command reftex-label +Insert a unique label. With one or two @kbd{C-u} prefixes, enforce +document rescan first. +@end deffn + +@deffn Command reftex-reference +Start a selection process to select a label, and insert a reference to +it. With one or two @kbd{C-u} prefixes, enforce document rescan first. +@end deffn + +@deffn Command reftex-citation +Make a citation using BibTeX database files. After prompting for a regular +expression, scans the buffers with BibTeX entries (taken from the +@code{\bibliography} command or a @code{thebibliography} environment) +and offers the matching entries for selection. The selected entry is +formated according to @code{reftex-cite-format} and inserted into the +buffer.@refill @* +When called with one or two @kbd{C-u} prefixes, first rescans the +document. When called with a numeric prefix, make that many citations. +When called with point inside the braces of a @code{\cite} command, it +will add another key, ignoring the value of +@code{reftex-cite-format}.@refill @* +The regular expression uses an expanded syntax: @samp{&&} is interpreted +as @code{and}. Thus, @samp{aaaa&&bbb} matches entries which contain +both @samp{aaaa} and @samp{bbb}. While entering the regexp, completion +on knows citation keys is possible. @samp{=} is a good regular +expression to match all entries in all files.@refill +@end deffn + +@deffn Command reftex-index +Query for an index macro and insert it along with its arguments. The +index macros available are those defined in @code{reftex-index-macro} or +by a call to @code{reftex-add-index-macros}, typically from an AUCTeX +style file. @b{Ref@TeX{}} provides completion for the index tag and the +index key, and will prompt for other arguments.@refill +@end deffn + +@deffn Command reftex-index-selection-or-word +Put current selection or the word near point into the default index +macro. This uses the information in @code{reftex-index-default-macro} +to make an index entry. The phrase indexed is the current selection or +the word near point. When called with one @kbd{C-u} prefix, let the +user have a chance to edit the index entry. When called with 2 +@kbd{C-u} as prefix, also ask for the index macro and other stuff. When +called inside TeX math mode as determined by the @file{texmathp.el} +library which is part of AUCTeX, the string is first processed with the +@code{reftex-index-math-format}, which see.@refill +@end deffn + +@deffn Command reftex-display-index +Display a buffer with an index compiled from the current document. +When the document has multiple indices, first prompts for the correct one. +When index support is turned off, offer to turn it on. +With one or two @kbd{C-u} prefixes, rescan document first. +With prefix 2, restrict index to current document section. +With prefix 3, restrict index to active region.@refill +@end deffn + +@deffn Command reftex-index-globally +Index a word with a global search and replace. This works very much +like @code{reftex-query-replace-document}, but the defaults for the +search and replace strings are derived from local context. When there +is an index entry, we try to index similar words. The word to search +for is the word in direct contact with the index macro (like +@samp{\index@{@var{word}@}@var{word}} or +@samp{@var{word}\index@{@var{word}@}}). If there is no such word, we +use the the index key. The replacement text is the index macro with all +its arguments and the attached word. When there is no index entry at +point, we search for the word near point and propose to index it like +this: @samp{\index@{@var{word}@}@var{word}}. You get a chance to edit +the search and replacement strings.@refill +@end deffn + +@deffn Command reftex-view-crossref +View cross reference of macro at point. Point must be on the @var{key} +argument. Works with the macros @code{\label}, @code{\ref}, +@code{\cite}, @code{\bibitem}, @code{\index} and many derivatives of +these. Where it makes sense, subsequent calls show additional +locations. See also the variable @code{reftex-view-crossref-extra} and +the command @code{reftex-view-crossref-from-bibtex}. With one or two +@kbd{C-u} prefixes, enforce rescanning of the document. With argument +2, select the window showing the cross reference. +@end deffn + +@deffn Command reftex-view-crossref-from-bibtex +View location in a LaTeX document which cites the BibTeX entry at point. +Since BibTeX files can be used by many LaTeX documents, this function +prompts upon first use for a buffer in @b{Ref@TeX{}} mode. To reset this +link to a document, call the function with with a prefix arg. Calling +this function several times find successive citation locations. +@end deffn + +@deffn Command reftex-create-tags-file +Create TAGS file by running @code{etags} on the current document. The +TAGS file is also immediately visited with +@code{visit-tags-table}.@refill +@end deffn + +@deffn Command reftex-grep-document +Run grep query through all files related to this document. +With prefix arg, force to rescan document. +No active TAGS table is required.@refill +@end deffn + +@deffn Command reftex-search-document +Regexp search through all files of the current document. +Starts always in the master file. Stops when a match is found. +No active TAGS table is required.@refill +@end deffn + +@deffn Command reftex-query-replace-document +Run a query-replace-regexp of @var{from} with @var{to} over the entire +document. With prefix arg, replace only word-delimited matches. No +active TAGS table is required.@refill +@end deffn + +@deffn Command reftex-change-label +Query replace @var{from} with @var{to} in all @code{\label} and +@code{\ref} commands. Works on the entire multifile document. No +active TAGS table is required.@refill +@end deffn + +@deffn Command reftex-renumber-simple-labels +Renumber all simple labels in the document to make them sequentially. +Simple labels are the ones created by RefTeX, consisting only of the +prefix and a number. After the command completes, all these labels will +have sequential numbers throughout the document. Any references to the +labels will be changed as well. For this, @b{Ref@TeX{}} looks at the +arguments of any macros which either start or end with the string +@samp{ref}. This command should be used with care, in particular in +multifile documents. You should not use it if another document refers +to this one with the @code{xr} package.@refill +@end deffn + +@deffn Command reftex-find-duplicate-labels +Produce a list of all duplicate labels in the document.@refill +@end deffn + +@deffn Command reftex-customize +Run the customize browser on the @b{Ref@TeX{}} group. +@end deffn +@deffn Command reftex-show-commentary +Show the commentary section from @file{reftex.el}. +@end deffn +@deffn Command reftex-info +Run info on the top @b{Ref@TeX{}} node. +@end deffn +@deffn Command reftex-parse-document +Parse the entire document in order to update the parsing information. +@end deffn +@deffn Command reftex-reset-mode +Enforce rebuilding of several internal lists and variables. Also +removes the parse file associated with the current document. +@end deffn + +@node Options, Keymaps and Hooks, Commands, Top +@chapter Options, Keymaps, Hooks +@cindex Options, list of + +Here is a complete list of @b{Ref@TeX{}}'s configuration variables. All +variables have customize support - so if you are not familiar with Emacs +Lisp (and even if you are) you might find it more comfortable to use +@code{customize} to look at and change these variables. @kbd{M-x +reftex-customize} will get you there.@refill + +@menu +* Options (Table of Contents):: +* Options (Defining Label Environments):: +* Options (Creating Labels):: +* Options (Referencing Labels):: +* Options (Creating Citations):: +* Options (Index Support):: +* Options (Viewing Cross-References):: +* Options (Finding Files):: +* Options (Optimizations):: +* Options (Fontification):: +* Options (Misc):: +@end menu + +@node Options (Table of Contents), Options (Defining Label Environments), , Options +@section Table of Contents +@cindex Options, table of contents +@cindex Table of contents, options + +@defopt reftex-toc-keep-other-windows +Non-@code{nil} means, split the selected window to display the +@file{*toc*} buffer. This helps to keep the window configuration, but +makes the @file{*toc*} small. When @code{nil}, all other windows except +the selected one will be deleted, so that the @file{*toc*} window fills +half the frame.@refill +@end defopt + +@defopt reftex-toc-include-file-boundaries +Non-@code{nil} means, include file boundaries in @file{*toc*} buffer. +This flag can be toggled from within the @file{*toc*} buffer with the +@kbd{i} key.@refill +@end defopt + +@defopt reftex-toc-include-labels +Non-@code{nil} means, include labels in @file{*toc*} buffer. This flag +can be toggled from within the @file{*toc*} buffer with the @kbd{l} +key.@refill +@end defopt + +@defopt reftex-toc-include-index-entries +Non-@code{nil} means, include index entries in @file{*toc*} buffer. +This flag can be toggled from within the @file{*toc*} buffer with the +@kbd{i} key. +@end defopt + +@defopt reftex-toc-include-context +Non-@code{nil} means, include context with labels in the @file{*toc*} +buffer. Context will only be shown if the labels are visible as well. +This flag can be toggled from within the @file{*toc*} buffer with the +@kbd{c} key.@refill +@end defopt + +@defopt reftex-toc-follow-mode +Non-@code{nil} means, point in @file{*toc*} buffer (the +table-of-contents buffer) will cause other window to follow. The other +window will show the corresponding part of the document. This flag can +be toggled from within the @file{*toc*} buffer with the @kbd{f} +key.@refill +@end defopt + +@deffn {Normal Hook} reftex-toc-mode-hook +Normal hook which is run when a @file{*toc*} buffer is +created.@refill +@end deffn + +@deffn Keymap reftex-toc-map +The keymap which is active in the @file{*toc*} buffer. +(@pxref{Table of Contents}).@refill +@end deffn + +@node Options (Defining Label Environments), Options (Creating Labels), Options (Table of Contents), Options +@section Defining Label Environments +@cindex Options, defining label environments +@cindex Defining label environments, options + +@defopt reftex-default-label-alist-entries +Default label alist specifications. It is a list of symbols with +associations in the constant @code{reftex-label-alist-builtin}. +@code{LaTeX} should always be the last entry.@refill +@end defopt + +@defopt reftex-label-alist +Set this variable to define additions and changes to the defaults in +@code{reftex-default-label-alist-entries}. The only things you +@emph{must not} change is that @code{?s} is the type indicator for +section labels, and @key{SPC} for the @code{any} label type. These are +hard-coded at other places in the code.@refill + +The value of the variable must be a list of items. Each item is a list +itself and has the following structure: + +@example + (@var{env-or-macro} @var{type-key} @var{label-prefix} @var{reference-format} + @var{context-method} (@var{magic-word} ... )) +@end example + +Each list entry describes either an environment carrying a counter for +use with @code{\label} and @code{\ref}, or a LaTeX macro defining a +label as (or inside) one of its arguments. The elements of each list +entry are:@refill + +@table @asis +@item @var{env-or-macro} +Name of the environment (like @samp{table}) or macro (like +@samp{\myfig}). For macros, indicate the arguments, as in +@samp{\myfig[]@{@}@{@}@{*@}@{@}}. Use square brackets for optional +arguments, a star to mark the label argument, if any. The macro does +not have to have a label argument - you could also use +@samp{\label@{...@}} inside one of its arguments.@refill + +Special names: @code{section} for section labels, @code{any} to define a +group which contains all labels.@refill + +This may also be a function to do local parsing and identify point to be +in a a non-standard label environment. The function must take an +argument @var{bound} and limit backward searches to this value. It +should return either nil or a cons cell @code{(@var{function} +. @var{position})} with the function symbol and the position where the +special environment starts. See the Info documentation for an +example.@refill + +Finally this may also be @code{nil} if the entry is only meant to change +some settings associated with the type indicator character (see +below).@refill + +@item @var{type-key} +Type indicator character, like @code{?t}, must be a printable ASCII +character. The type indicator is a single character which defines a +label type. Any label inside the environment or macro is assumed to +belong to this type. The same character may occur several times in this +list, to cover cases in which different environments carry the same +label type (like @code{equation} and @code{eqnarray}). If the type +indicator is @code{nil} and the macro has a label argument @samp{@{*@}}, +the macro defines neutral labels just like @code{\label}. In this case +the reminder of this entry is ignored.@refill + +@item @var{label-prefix} +Label prefix string, like @samp{tab:}. The prefix is a short string +used as the start of a label. It may be the empty string. The prefix +may contain the following @samp{%} escapes:@refill + +@example +%f Current file name, directory and extension stripped. +%F Current file name relative to master file directory. +%u User login name, on systems which support this. +%S A section prefix derived with variable @code{reftex-section-prefixes}. +@end example + +@noindent +Example: In a file @file{intro.tex}, @samp{eq:%f:} will become +@samp{eq:intro:}.@refill + +@item @var{reference-format} +Format string for reference insert in buffer. @samp{%s} will be +replaced by the label. When the format starts with @samp{~}, this +@samp{~} will only be inserted when the character before point is +@emph{not} a whitespace.@refill + +@item @var{context-method} +Indication on how to find the short context. +@itemize @minus +@item +If @code{nil}, use the text following the @samp{\label@{...@}} macro.@refill +@item +If @code{t}, use +@itemize @minus +@item +the section heading for section labels. +@item +text following the @samp{\begin@{...@}} statement of environments (not +a good choice for environments like eqnarray or enumerate, where one has +several labels in a single environment).@refill +@item +text after the macro name (starting with the first arg) for +macros.@refill +@end itemize +@item +If an integer, use the nth argument of the macro. As a special case, +1000 means to get text after the last macro argument.@refill +@item +If a string, use as regexp to search @emph{backward} from the label. +Context is then the text following the end of the match. E.g. putting +this to @samp{\\caption[[@{]} will use the caption in a figure or table +environment. @samp{\\begin@{eqnarray@}\|\\\\} works for +eqnarrays.@refill +@item +If any of @code{caption}, @code{item}, @code{eqnarray-like}, +@code{alignat-like}, this symbol will internally be translated into an +appropriate regexp (see also the variable +@code{reftex-default-context-regexps}).@refill +@item +If a function, call this function with the name of the environment/macro +as argument. On call, point will be just after the @code{\label} macro. +The function is expected to return a suitable context string. It should +throw an exception (error) when failing to find context. As an example, +here is a function returning the 10 chars following the label macro as +context:@refill + +@example +(defun my-context-function (env-or-mac) + (if (> (point-max) (+ 10 (point))) + (buffer-substring (point) (+ 10 (point))) + (error "Buffer too small"))) +@end example +@end itemize + +Label context is used in two ways by @b{Ref@TeX{}}: For display in the label +menu, and to derive a label string. If you want to use a different +method for each of these, specify them as a dotted pair. +E.g. @code{(nil . t)} uses the text after the label (@code{nil}) for +display, and text from the default position (@code{t}) to derive a label +string. This is actually used for section labels.@refill + +@item @var{magic-word-list} +List of magic words which identify a reference to be of this type. If +the word before point is equal to one of these words when calling +@code{reftex-reference}, the label list offered will be automatically +restricted to labels of the correct type. If the first element of this +word--list is the symbol `regexp', the strings are interpreted as regular +expressions@footnote{Careful: @b{Ref@TeX{}} will add stuff to the +beginning and end of these regular expressions.}.@refill +@end table + +If the type indicator characters of two or more entries are the same, +@b{Ref@TeX{}} will use@refill +@itemize @minus +@item +the first non-@code{nil} format and prefix +@item +the magic words of all involved entries. +@end itemize + +Any list entry may also be a symbol. If that has an association in +@code{reftex-label-alist-builtin}, the @code{cddr} of that association is +spliced into the list. However, builtin defaults should normally be set +with the variable @code{reftex-default-label-alist-entries}.@refill +@end defopt + +@defopt reftex-max-section-depth +Maximum depth of section levels in document structure. +Standard LaTeX needs 7, default is 12. +@end defopt + +@defopt reftex-section-levels +Commands and levels used for defining sections in the document. The +@code{car} of each cons cell is the name of the section macro. The +@code{cdr} is a number indicating its level. A negative level means the +same as the positive value, but the section will never get a +number. The @code{cdr} amy also be a function which then has to return +the level.@refill +@end defopt + +@defopt reftex-section-prefixes +Prefixes for section labels. When the label prefix given in an entry in +@code{reftex-label-alist} contains @samp{%S}, this list is used to +determine the correct prefix string depending on the current section +level. The list is an alist, with each entry of the form +@w{@code{(@var{key} . @var{prefix})}}. Possible keys are sectioning macro +names like @samp{chapter}, integer section levels (as given in +@code{reftex-section-levels}), and @code{t} for the default. +@end defopt + +@defopt reftex-default-context-regexps +Alist with default regular expressions for finding context. The emacs +lisp form @w{@code{(format regexp (regexp-quote environment))}} is used +to calculate the final regular expression - so @samp{%s} will be +replaced with the environment or macro.@refill +@end defopt + +@node Options (Creating Labels), Options (Referencing Labels), Options (Defining Label Environments), Options +@section Creating Labels +@cindex Options, creating labels +@cindex Creating labels, options + +@defopt reftex-insert-label-flags +Flags governing label insertion. The value has the form + +@example +(@var{derive} @var{prompt}) +@end example + +If @var{derive}is @code{t}, @b{Ref@TeX{}} will try to derive a sensible +label from context. A section label for example will be derived from +the section heading. The conversion of the context to a legal label is +governed by the specifications given in +@code{reftex-derive-label-parameters}. If @var{derive} is @code{nil}, +the default label will consist of the prefix and a unique number, like +@samp{eq:23}.@refill + +If @var{prompt} is @code{t}, the user will be prompted for a label +string. When @var{prompt} is @code{nil}, the default label will be +inserted without query.@refill + +So the combination of @var{derive} and @var{prompt} controls label +insertion. Here is a table describing all four possibilities:@refill + +@example +@group +@var{derive} @var{prompt} @var{action} +----------------------------------------------------------- +nil nil @r{Insert simple label, like @samp{eq:22} or @samp{sec:13}. No query.} +nil t @r{Prompt for label.} +t nil @r{Derive a label from context and insert. No query.} +t t @r{Derive a label from context, prompt for confirmation.} +@end group +@end example + +Each flag may be set to @code{t}, @code{nil}, or a string of label type +letters indicating the label types for which it should be true. Thus, +the combination may be set differently for each label type. The default +settings @samp{"s"} and @samp{"sft"} mean: Derive section labels from +headings (with confirmation). Prompt for figure and table labels. Use +simple labels without confirmation for everything else.@refill + +The available label types are: @code{s} (section), @code{f} (figure), +@code{t} (table), @code{i} (item), @code{e} (equation), @code{n} +(footnote), @code{N} (endnote) plus any definitions in +@code{reftex-label-alist}.@refill +@end defopt + +@deffn Hook reftex-format-label-function +If non-@code{nil}, should be a function which produces the string to +insert as a label definition. The function will be called with two +arguments, the @var{label} and the @var{default-format} (usually +@samp{\label@{%s@}}). It should return the string to insert into the +buffer.@refill +@end deffn + +@deffn Hook reftex-string-to-label-function +Function to turn an arbitrary string into a legal label. +@b{Ref@TeX{}}'s default function uses the variable +@code{reftex-derive-label-parameters}.@refill +@end deffn + +@deffn Hook reftex-translate-to-ascii-function +Filter function which will process a context string before it is used to +derive a label from it. The intended application is to convert ISO or +Mule characters into something legal in labels. The default function +@code{reftex-latin1-to-ascii} removes the accents from Latin-1 +characters. X-Symbol (>=2.6) sets this variable to the much more +general @code{x-symbol-translate-to-ascii}.@refill +@end deffn + +@defopt reftex-derive-label-parameters +Parameters for converting a string into a label. This variable is a +list of the following items:@refill +@table @asis +@item @var{nwords} +Number of words to use. +@item @var{maxchar} +Maximum number of characters in a label string. +@item @var{illegal} +@code{nil}: Throw away any words containing characters illegal in labels.@* +@code{t}: Throw away only the illegal characters, not the whole word. +@item @var{abbrev} +@code{nil}: Never abbreviate words.@* +@code{t}: Always abbreviate words (see @code{reftex-abbrev-parameters}).@* +@code{1}: Abbreviate words if necessary to shorten label string. +@item @var{separator} +String separating different words in the label. +@item @var{ignorewords} +List of words which should not be part of labels. +@item @var{downcase} +@code{t}: Downcase words before putting them into the label.@* +@end table +@end defopt + +@defopt reftex-label-illegal-re +Regexp matching characters not legal in labels. +@end defopt + +@defopt reftex-abbrev-parameters +Parameters for abbreviation of words. A list of four parameters.@refill +@table @asis +@item @var{min-chars} +Minimum number of characters remaining after abbreviation. +@item @var{min-kill} +Minimum number of characters to remove when abbreviating words.@refill +@item @var{before} +Character class before abbrev point in word.@refill +@item @var{after} +Character class after abbrev point in word.@refill +@end table +@end defopt + +@node Options (Referencing Labels), Options (Creating Citations), Options (Creating Labels), Options +@section Referencing Labels +@cindex Options, referencing labels +@cindex Referencing labels, options + +@defopt reftex-label-menu-flags +List of flags governing the label menu makeup. The flags are: +@table @asis +@item @var{table-of-contents} +Show the labels embedded in a table of context.@refill +@item @var{section-numbers} +Include section numbers (like 4.1.3) in table of contents.@refill +@item @var{counters} +Show counters. This just numbers the labels in the menu.@refill +@item @var{no-context} +Non-@code{nil} means do @emph{not} show the short context.@refill +@item @var{follow} +Follow full context in other window.@refill +@item @var{show-commented} +Show labels from regions which are commented out.@refill +@item @var{match-everywhere} +Obsolete flag.@refill +@item @var{show-files} +Show begin and end of included files.@refill +@end table + +Each of these flags can be set to @code{t} or @code{nil}, or to a string +of type letters indicating the label types for which it should be true. +These strings work like character classes in regular expressions. Thus, +setting one of the flags to @samp{"sf"} makes the flag true for section +and figure labels, @code{nil} for everything else. Setting it to +@samp{"^sf"} makes it the other way round.@refill + +The available label types are: @code{s} (section), @code{f} (figure), +@code{t} (table), @code{i} (item), @code{e} (equation), @code{n} +(footnote), plus any definitions in @code{reftex-label-alist}.@refill + +Most options can also be switched from the label menu itself - so if you +decide here to not have a table of contents in the label menu, you can +still get one interactively during selection from the label menu.@refill +@end defopt + +@defopt reftex-multiref-punctuation +Punctuation strings for multiple references. When marking is used in +the selection buffer to select several references, this variable +associates the 3 marking characters @samp{,-+} with prefix strings to be +inserted into the buffer before the corresponding @code{\ref} macro. +This is used to string together whole reference sets, like +@samp{eqs. 1,2,3-5,6 and 7} in a single call to +@code{reftex-reference}.@refill +@end defopt + +@defopt reftex-vref-is-default +Non-@code{nil} means, the varioref macro @code{\vref} is used as +default. In the selection buffer, the @kbd{v} key toggles the reference +macro between @code{\ref} and @code{\vref}. The value of this variable +determines the default which is active when entering the selection +process. Instead of @code{nil} or @code{t}, this may also be a string +of type letters indicating the label types for which it should be +true.@refill +@end defopt + +@defopt reftex-fref-is-default +Non-@code{nil} means, the fancyref macro @code{\fref} is used as +default. In the selection buffer, the @kbd{V} key toggles the reference +macro between @code{\ref}, @code{\fref} and @code{\Fref}. The value of +this variable determines the default which is active when entering the +selection process. Instead of @code{nil} or @code{t}, this may also be +a string of type letters indicating the label types for which it should +be true. +@end defopt + +@deffn Hook reftex-format-ref-function +If non-@code{nil}, should be a function which produces the string to +insert as a reference. Note that the insertion format can also be +changed with @code{reftex-label-alist}. This hook also is used by the +special commands to insert @code{\vref} and @code{\fref} references, so +even if you set this, your setting will be ignored by the special +commands. The function will be called with two arguments, the +@var{label} and the @var{default-format} (usually @samp{~\ref@{%s@}}). +It should return the string to insert into the buffer.@refill +@end deffn + +@defopt reftex-level-indent +Number of spaces to be used for indentation per section level.@refill +@end defopt + +@defopt reftex-guess-label-type +Non-@code{nil} means, @code{reftex-reference} will try to guess the +label type. To do that, @b{Ref@TeX{}} will look at the word before the +cursor and compare it with the magic words given in +@code{reftex-label-alist}. When it finds a match, @b{Ref@TeX{}} will +immediately offer the correct label menu - otherwise it will prompt you +for a label type. If you set this variable to @code{nil}, @b{Ref@TeX{}} +will always prompt for a label type.@refill +@end defopt + +@deffn {Normal Hook} reftex-display-copied-context-hook +Normal Hook which is run before context is displayed anywhere. Designed +for @w{@code{X-Symbol}}, but may have other uses as well.@refill +@end deffn + +@deffn Hook reftex-pre-refontification-functions +@code{X-Symbol} specific hook. Probably not useful for other purposes. +The functions get two arguments, the buffer from where the command +started and a symbol indicating in what context the hook is +called.@refill +@end deffn + +@deffn {Normal Hook} reftex-select-label-mode-hook +Normal hook which is run when a selection buffer enters +@code{reftex-select-label-mode}.@refill +@end deffn + +@deffn Keymap reftex-select-label-map +The keymap which is active in the labels selection process +(@pxref{Referencing Labels}).@refill +@end deffn + +@node Options (Creating Citations), Options (Index Support), Options (Referencing Labels), Options +@section Creating Citations +@cindex Options, creating citations +@cindex Creating citations, options + +@defopt reftex-bibfile-ignore-regexps +List of regular expressions to exclude files in +@code{\\bibliography@{..@}}. File names matched by any of these regexps +will not be parsed. Intended for files which contain only +@code{@@string} macro definitions and the like, which are ignored by +@b{Ref@TeX{}} anyway.@refill +@end defopt + +@defopt reftex-default-bibliography +List of BibTeX database files which should be used if none are specified. +When @code{reftex-citation} is called from a document with neither +a @samp{\bibliography@{...@}} statement nor a @code{thebibliography} +environment, @b{Ref@TeX{}} will scan these files instead. Intended for +using @code{reftex-citation} in non-LaTeX files. The files will be +searched along the BIBINPUTS or TEXBIB path.@refill +@end defopt + +@defopt reftex-sort-bibtex-matches +Sorting of the entries found in BibTeX databases by reftex-citation. +Possible values:@refill +@example +nil @r{Do not sort entries.} +author @r{Sort entries by author name.} +year @r{Sort entries by increasing year.} +reverse-year @r{Sort entries by decreasing year.} +@end example +@end defopt + +@defopt reftex-cite-format +The format of citations to be inserted into the buffer. It can be a +string, an alist or a symbol. In the simplest case this is just the string +@samp{\cite@{%l@}}, which is also the default. See the definition of +@code{reftex-cite-format-builtin} for more complex examples.@refill + +If @code{reftex-cite-format} is a string, it will be used as the format. +In the format, the following percent escapes will be expanded.@refill + +@table @code +@item %l +The BibTeX label of the citation. +@item %a +List of author names, see also @code{reftex-cite-punctuation}. +@item %2a +Like %a, but abbreviate more than 2 authors like Jones et al. +@item %A +First author name only. +@item %e +Works like @samp{%a}, but on list of editor names. (@samp{%2e} and +@samp{%E} work a well).@refill +@end table + +It is also possible to access all other BibTeX database fields: + +@example +%b booktitle %c chapter %d edition %h howpublished +%i institution %j journal %k key %m month +%n number %o organization %p pages %P first page +%r address %s school %u publisher %t title +%v volume %y year +%B booktitle, abbreviated %T title, abbreviated +@end example + +@noindent +Usually, only @samp{%l} is needed. The other stuff is mainly for the +echo area display, and for @code{(setq reftex-comment-citations t)}.@refill + +@samp{%<} as a special operator kills punctuation and space around it +after the string has been formatted.@refill + +Beware that all this only works with BibTeX database files. When +citations are made from the @code{\bibitems} in an explicit +@code{thebibliography} environment, only @samp{%l} is available.@refill + +If @code{reftex-cite-format} is an alist of characters and strings, the +user will be prompted for a character to select one of the possible +format strings.@refill + +In order to configure this variable, you can either set +@code{reftex-cite-format} directly yourself or set it to the +@emph{symbol} of one of the predefined styles. The predefined symbols +are those which have an association in the constant +@code{reftex-cite-format-builtin}) E.g.: @code{(setq reftex-cite-format +'natbib)}.@refill +@end defopt + +@deffn Hook reftex-format-cite-function + +If non-@code{nil}, should be a function which produces the string to +insert as a citation. Note that the citation format can also be changed +with the variable @code{reftex-cite-format}. The function will be +called with two arguments, the @var{citation-key} and the +@var{default-format} (taken from @code{reftex-cite-format}). It should +return the string to insert into the buffer.@refill +@end deffn + +@defopt reftex-comment-citations +Non-@code{nil} means add a comment for each citation describing the full +entry. The comment is formatted according to +@code{reftex-cite-comment-format}.@refill +@end defopt + +@defopt reftex-cite-comment-format +Citation format used for commented citations. Must @emph{not} contain +@samp{%l}. See the variable @code{reftex-cite-format} for possible +percent escapes.@refill +@end defopt + +@defopt reftex-cite-punctuation +Punctuation for formatting of name lists in citations. This is a list +of 3 strings.@refill +@enumerate +@item +normal names separator, like @samp{, } in Jones, Brown and Miller +@item +final names separator, like @samp{ and } in Jones, Brown and Miller +@item +The @samp{et al.} string, like @samp{ @{\it et al.@}} in +Jones @{\it et al.@} +@end enumerate +@end defopt + +@deffn {Normal Hook} reftex-select-bib-mode-hook +Normal hook which is run when a selection buffer enters +@code{reftex-select-bib-mode}.@refill +@end deffn + +@deffn Keymap reftex-select-bib-map +The keymap which is active in the citation-key selection process +(@pxref{Creating Citations}).@refill +@end deffn + +@node Options (Index Support), Options (Viewing Cross-References), Options (Creating Citations), Options +@section Index Support +@cindex Options, Index support +@cindex Index support, options + +@defopt reftex-support-index +Non-@code{nil} means, index entries are parsed as well. Index support +is resource intensive and the internal structure holding the parsed +information can become quite big. Therefore it can be turned off. When +this is @code{nil} and you execute a command which requires index +support, you will be asked for confirmation to turn it on and rescan the +document.@refill +@end defopt + +@defopt reftex-index-special-chars +List of special characters in index entries, given as strings. These +correspond to the @code{MakeIndex} keywords +@code{(@var{level} @var{encap} @var{actual} @var{quote} @var{escape})}. +@end defopt + +@defopt reftex-index-macros +List of macros which define index entries. The structure of each entry +is +@lisp +(@var{macro} @var{index-tag} @var{key} @var{prefix} @var{exclude}) +@end lisp + +@var{macro} is the macro. Arguments should be denoted by empty braces, +as for example in @samp{\index[]@{*@}}. Use square brackets to denote +optional arguments. The star marks where the index key is.@refill + +@var{index-tag} is a short name of the index. @samp{idx} and @samp{glo} +are reserved for the default index and the glossary. Other indices can +be defined as well. If this is an integer, the Nth argument of the +macro holds the index tag.@refill + +@var{key} is a character which is used to identify the macro for input +with @code{reftex-index}. @samp{?i}, @samp{?I}, and @samp{?g} are +reserved for default index and glossary.@refill + +@var{prefix} can be a prefix which is added to the @var{key} part of the +index entry. If you have a macro +@code{\newcommand@{\molec@}[1]@{#1\index@{Molecules!#1@}}, this prefix +should be @samp{Molecules!}.@refill + +@var{exclude} can be a function. If this function exists and returns a +non-nil value, the index entry at point is ignored. This was +implemented to support the (deprecated) @samp{^} and @samp{_} shortcuts +in the LaTeX2e @code{index} package.@refill + +The final entry may also be a symbol. It must have an association in +the variable @code{reftex-index-macros-builtin} to specify the main +indexing package you are using. Legal values are currently@refill +@example +default @r{The LaTeX default - unnecessary to specify this one} +multind @r{The multind.sty package} +index @r{The index.sty package} +index-shortcut @r{The index.sty packages with the ^ and _ shortcuts.} + @r{Should not be used - only for old documents} +@end example +Note that AUCTeX sets these things internally for @b{Ref@TeX{}} as well, +so with a sufficiently new version of AUCTeX, you should not set the +package here. +@end defopt + +@defopt reftex-index-default-macro +The default index macro for @code{reftex-index-selection-or-word}. +This is a list with @code{(@var{macro-key} @var{default-tag} @var{repeat-word})}. + +@var{macro-key} is a character identifying an index macro - see +@code{reftex-index-macros}. + +@var{default-tag} is the tag to be used if the macro requires a +@var{tag} argument. When this is @code{nil} and a @var{tag} is needed, +@b{Ref@TeX{}} will ask for it. When this is the empty string and the +TAG argument of the index macro is optional, the TAG argument will be +omitted. + +@var{repeat-word}, when non-@code{nil} means, the index macro does not +typeset the entry in the text, so that the text has to be repeated +outside the index macro. +@end defopt + +@defopt reftex-index-default-tag +Default index tag. When working with multiple indexes, RefTeX queries +for an index tag when creating index entries or displaying a specific +index. This variable controls the default offered for these queries. +The default can be selected with @key{RET} during selection or +completion. Legal values of this variable are:@refill +@example +nil @r{Do not provide a default index} +"tag" @r{The default index tag given as a string, e.g. "idx"} +last @r{The last used index tag will be offered as default} +@end example +@end defopt + +@defopt reftex-index-math-format +Format of index entries when copied from inside math mode. When +@code{reftex-index-selection-or-word} is executed inside TeX math mode, +the index key copied from the buffer is processed with this format +string through the @code{format} function. This can be used to add the +math delimiters (e.g. @samp{$}) to the string. Requires the +@file{texmathp.el} library which is part of AUCTeX.@refill +@end defopt + +@defopt reftex-index-section-letters +The letters which denote sections in the index. Usually these are all +capital letters. Don't use any downcase letters. Order is not +significant, the index will be sorted by whatever the sort function +thinks is correct. In addition to these letters, RefTeX will create a +group @samp{!} which contains all entries sorted below the lowest +specified letter. In the @file{*Index*} buffer, pressing any of these +capital letters or @kbd{!} will jump to that section.@refill +@end defopt + +@defopt reftex-index-include-context +Non-@code{nil} means, display the index definition context in the +@file{*Index*} buffer. This flag may also be toggled from the +@file{*Index*} buffer with the @kbd{c} key. +@end defopt + +@defopt reftex-index-follow-mode +Non-@code{nil} means, point in @file{*Index*} buffer will cause other +window to follow. The other window will show the corresponding part of +the document. This flag can be toggled from within the @file{*Index*} +buffer with the @kbd{f} key. +@end defopt + +@deffn Keymap reftex-index-map +The keymap which is active in the @file{*Index*} buffer +(@pxref{Index Support}).@refill +@end deffn + +@node Options (Viewing Cross-References), Options (Finding Files), Options (Index Support), Options +@section Viewing Cross-References +@cindex Options, viewing cross-references +@cindex Viewing cross-references, options + +@defopt reftex-view-crossref-extra +Macros which can be used for the display of cross references. +This is used when `reftex-view-crossref' is called with point in an +argument of a macro. Note that crossref viewing for citations, +references (both ways) and index entries is hard-coded. This variable +is only to configure additional structures for which crossreference +viewing can be useful. Each entry has the structure +@example +(@var{macro-re} @var{search-re} @var{highlight}). +@end example +@var{macro-re} is matched against the macro. @var{search-re} is the +regexp used to search for cross references. @samp{%s} in this regexp is +replaced with with the macro argument at point. @var{highlight} is an +integer indicating which subgroup of the match should be highlighted. +@end defopt + +@defopt reftex-auto-view-crossref +Non-@code{nil} means, initially turn automatic viewing of crossref info +on. Automatic viewing of crossref info normally uses the echo area. +Whenever point is on the argument of a @code{\ref} or @code{\cite} +macro, and no other message is being displayed, the echo area will +display information about that cross reference. You can also set the +variable to the symbol @code{window}. In this case a small temporary +window is used for the display. This feature can be turned on and of +from the menu (Ref->Options).@refill +@end defopt + +@defopt reftex-idle-time +Time (secs) Emacs has to be idle before automatic crossref display is +done.@refill +@end defopt + +@defopt reftex-cite-view-format +Citation format used to display citation info in the message area. See +the variable @code{reftex-cite-format} for possible percent +escapes.@refill +@end defopt + +@defopt reftex-revisit-to-echo +Non-@code{nil} means, automatic citation display will revisit files if +necessary. When nil, citation display in echo area will only be active +for cached echo strings (see @code{reftex-cache-cite-echo}), or for +BibTeX database files which are already visited by a live associated +buffers.@refill +@end defopt + +@defopt reftex-cache-cite-echo +Non-@code{nil} means, the information displayed in the echo area for +cite macros (see variable @code{reftex-auto-view-crossref}) is cached and +saved along with the parsing information. The cache survives document +scans. In order to clear it, use @kbd{M-x reftex-reset-mode}. +@end defopt + +@node Options (Finding Files), Options (Optimizations), Options (Viewing Cross-References), Options +@section Finding Files +@cindex Options, Finding Files +@cindex Finding files, options + +@defopt reftex-texpath-environment-variables +List of specifications how to retrieve the search path for TeX files. +Several entries are possible.@refill +@itemize @minus +@item +If an element is the name of an environment variable, its content is +used.@refill +@item +If an element starts with an exclamation mark, it is used as a command +to retrieve the path. A typical command with the kpathsearch library +would be @w{@code{"!kpsewhich -show-path=.tex"}}. +@item +Otherwise the element itself is interpreted as a path. +@end itemize +Multiple directories can be separated by the system dependent +@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will +be expanded recursively. See also @code{reftex-use-external-file-finders}. +@end defopt + +@defopt reftex-bibpath-environment-variables +List of specifications how to retrieve the search path for BibTeX +files. Several entries are possible.@refill +@itemize @minus +@item +If an element is the name of an environment variable, its content is +used.@refill +@item +If an element starts with an exclamation mark, it is used as a command +to retrieve the path. A typical command with the kpathsearch library +would be @w{@code{"!kpsewhich -show-path=.bib"}}. +@item +Otherwise the element itself is interpreted as a path. +@end itemize +Multiple directories can be separated by the system dependent +@code{path-separator}. Directories ending in @samp{//} or @samp{!!} will +be expanded recursively. See also @code{reftex-use-external-file-finders}. +@end defopt + +@defopt reftex-file-extensions +Association list with file extensions for different file types. +This is a list of items, each item is like: +@code{(@var{type} . (@var{def-ext} @var{other-ext} ...))} +@example +@var{type}: @r{File type like @code{"bib"} or @code{"tex"}.} +@var{def-ext}: @r{The default extension for that file type, like @code{".tex"} or @code{".bib"}.} +@var{other-ext}: @r{Any number of other legal extensions for this file type.} +@end example +When a files is searched and it does not have any of the legal extensions, +we try the default extension first, and then the naked file name.@refill +@end defopt + +@defopt reftex-search-unrecursed-path-first +Non-@code{nil} means, search all specified directories before trying +recursion. Thus, in a path @samp{.//:/tex/}, search first @samp{./}, +then @samp{/tex/}, and then all subdirectories of @samp{./}. If this +option is @code{nil}, the subdirectories of @samp{./} are searched +before @samp{/tex/}. This is mainly for speed - most of the time the +recursive path is for the system files and not for the user files. Set +this to @code{nil} if the default makes @b{Ref@TeX{}} finding files with +equal names in wrong sequence.@refill +@end defopt + +@defopt reftex-use-external-file-finders +Non-@code{nil} means, use external programs to find files. Normally, +@b{Ref@TeX{}} searches the paths given in the environment variables +@code{TEXINPUTS} and @code{BIBINPUTS} to find TeX files and BibTeX +database files. With this option turned on, it calls an external +program specified in the option @code{reftex-external-file-finders} +instead. As a side effect, the variables +@code{reftex-texpath-environment-variables} and +@code{reftex-bibpath-environment-variables} will be ignored. +@end defopt + +@defopt reftex-external-file-finders +Association list with external programs to call for finding files. Each +entry is a cons cell @w{@code{(@var{type} . @var{program})}}. +@var{type} is either @code{"tex"} or @code{"bib"}. @var{program} is a +string containing the external program to use with any arguments. +@code{%f} will be replaced by the name of the file to be found. Note +that these commands will be executed directly, not via a shell. Only +relevant when @code{reftex-use-external-file-finders} is +non-@code{nil}.@refill +@end defopt + +@page +@node Options (Optimizations), Options (Fontification), Options (Finding Files), Options +@section Optimizations +@cindex Options, optimizations +@cindex Optimizations, options + +@defopt reftex-keep-temporary-buffers +Non-@code{nil} means, keep buffers created for parsing and lookup. +@b{Ref@TeX{}} sometimes needs to visit files related to the current +document. We distinguish files visited for@refill +@table @asis +@item PARSING +Parts of a multifile document loaded when (re)-parsing the +document.@refill +@item LOOKUP +BibTeX database files and TeX files loaded to find a reference, to +display label context, etc.@refill +@end table +The created buffers can be kept for later use, or be thrown away +immediately after use, depending on the value of this variable:@refill + +@table @code +@item nil +Throw away as much as possible. +@item t +Keep everything. +@item 1 +Throw away buffers created for parsing, but keep the ones created for +lookup.@refill +@end table + +If a buffer is to be kept, the file is visited normally (which is +potentially slow but will happen only once). If a buffer is to be thrown +away, the initialization of the buffer depends upon the variable +@code{reftex-initialize-temporary-buffers}.@refill +@end defopt + +@defopt reftex-initialize-temporary-buffers +Non-@code{nil} means do initializations even when visiting file +temporarily. When @code{nil}, @b{Ref@TeX{}} may turn off find-file hooks and +other stuff to briefly visit a file. When @code{t}, the full default +initializations are done (@code{find-file-hook} etc.). Instead of +@code{t} or @code{nil}, this variable may also be a list of hook +functions to do a minimal initialization.@refill +@end defopt + +@defopt reftex-no-include-regexps +List of regular expressions to exclude certain input files from parsing. +If the name of a file included via @code{\include} or @code{\input} is +matched by any of the regular expressions in this list, that file is not +parsed by @b{Ref@TeX{}}. +@end defopt + +@defopt reftex-enable-partial-scans +Non-@code{nil} means, re-parse only 1 file when asked to re-parse. +Re-parsing is normally requested with a @kbd{C-u} prefix to many @b{Ref@TeX{}} +commands, or with the @kbd{r} key in menus. When this option is +@code{t} in a multifile document, we will only parse the current buffer, +or the file associated with the label or section heading near point in a +menu. Requesting re-parsing of an entire multifile document then +requires a @kbd{C-u C-u} prefix or the capital @kbd{R} key in +menus.@refill +@end defopt + +@defopt reftex-save-parse-info +Non-@code{nil} means, save information gathered with parsing in files. +The file @file{MASTER.rel} in the same directory as @file{MASTER.tex} is +used to save the information. When this variable is @code{t}, +@itemize @minus +@item +accessing the parsing information for the first time in an editing +session will read that file (if available) instead of parsing the +document.@refill +@item +exiting Emacs or killing a buffer in reftex-mode will cause a new +version of the file to be written.@refill +@end itemize +@end defopt + +@defopt reftex-allow-automatic-rescan +Non-@code{nil} means, @b{Ref@TeX{}} may rescan the document when this seems +necessary. Applies (currently) only in rare cases, when a new label +cannot be placed with certainty into the internal label list. +@end defopt + +@defopt reftex-use-multiple-selection-buffers +Non-@code{nil} means use a separate selection buffer for each label +type. These buffers are kept from one selection to the next and need +not to be created for each use - so the menu generally comes up faster. +The selection buffers will be erased (and therefore updated) +automatically when new labels in its category are added. See the +variable @code{reftex-auto-update-selection-buffers}.@refill +@end defopt + +@defopt reftex-auto-update-selection-buffers +Non-@code{nil} means, selection buffers will be updated automatically. +When a new label is defined with @code{reftex-label}, all selection +buffers associated with that label category are emptied, in order to +force an update upon next use. When @code{nil}, the buffers are left +alone and have to be updated by hand, with the @kbd{g} key from the +label selection process. The value of this variable will only have any +effect when @code{reftex-use-multiple-selection-buffers} is +non-@code{nil}.@refill +@end defopt + +@node Options (Fontification), Options (Misc), Options (Optimizations), Options +@section Fontification +@cindex Options, fontification +@cindex Fontification, options + +@defopt reftex-use-fonts +Non-@code{nil} means, use fonts in label menu and on-the-fly help. +Font-lock must be loaded as well to actually get fontified +display. After changing this option, a rescan may be necessary to +activate it.@refill +@end defopt + +@defopt reftex-refontify-context +Non-@code{nil} means, re-fontify the context in the label menu with +font-lock. This slightly slows down the creation of the label menu. It +is only necessary when you definitely want the context fontified.@refill + +This option may have 3 different values: +@table @code +@item nil +Never refontify. +@item t +Always refontify. +@item 1 +Refontify when necessary, e.g. with old versions of the x-symbol +package.@refill +@end table +The option is ignored when @code{reftex-use-fonts} is @code{nil}.@refill +@end defopt + +@defopt reftex-highlight-selection +Non-@code{nil} means, highlight selected text in selection and +@file{*toc*} buffers. Normally, the text near the cursor is the +@emph{selected} text, and it is highlighted. This is the entry most +keys in the selection and @file{*toc*} buffers act on. However, if you +mainly use the mouse to select an item, you may find it nice to have +mouse-triggered highlighting @emph{instead} or @emph{as well}. The +variable may have one of these values:@refill + +@example +nil @r{No highlighting.} +cursor @r{Highlighting is cursor driven.} +mouse @r{Highlighting is mouse driven.} +both @r{Both cursor and mouse trigger highlighting.} +@end example + +Changing this variable requires to rebuild the selection and *toc* +buffers to become effective (keys @kbd{g} or @kbd{r}).@refill +@end defopt + +@defopt reftex-cursor-selected-face +Face name to highlight cursor selected item in toc and selection buffers. +See also the variable @code{reftex-highlight-selection}.@refill +@end defopt +@defopt reftex-mouse-selected-face +Face name to highlight mouse selected item in toc and selection buffers. +See also the variable @code{reftex-highlight-selection}.@refill +@end defopt +@defopt reftex-file-boundary-face +Face name for file boundaries in selection buffer. +@end defopt +@defopt reftex-label-face +Face name for labels in selection buffer. +@end defopt +@defopt reftex-section-heading-face +Face name for section headings in toc and selection buffers. +@end defopt +@defopt reftex-toc-header-face +Face name for the header of a toc buffer. +@end defopt +@defopt reftex-bib-author-face +Face name for author names in bib selection buffer. +@end defopt +@defopt reftex-bib-year-face +Face name for year in bib selection buffer. +@end defopt +@defopt reftex-bib-title-face +Face name for article title in bib selection buffer. +@end defopt +@defopt reftex-bib-extra-face +Face name for bibliographic information in bib selection buffer. +@end defopt +@defopt reftex-select-mark-face +Face name for marked entries in the selection buffers. +@end defopt +@defopt reftex-index-header-face +Face name for the header of an index buffer. +@end defopt +@defopt reftex-index-section-face +Face name for the start of a new letter section in the index. +@end defopt +@defopt reftex-index-tag-face +Face name for index names (for multiple indices). +@end defopt +@defopt reftex-index-face +Face name for index entries. +@end defopt + +@node Options (Misc), , Options (Fontification), Options +@section Miscellaneous +@cindex Options, misc + +@defopt reftex-extra-bindings +Non-@code{nil} means, make additional key bindings on startup. These +extra bindings are located in the users @samp{C-c letter} +map. @xref{Keybindings}.@refill +@end defopt + +@defopt reftex-plug-into-AUCTeX +Plug-in flags for AUCTeX interface. This variable is a list of +5 boolean flags. When a flag is non-@code{nil}, @b{Ref@TeX{}} +will@refill + +@example +- supply labels in new sections and environments (flag 1) +- supply arguments for macros like @code{\label} (flag 2) +- supply arguments for macros like @code{\ref} (flag 3) +- supply arguments for macros like @code{\cite} (flag 4) +- supply arguments for macros like @code{\index} (flag 5) +@end example + +You may also set the variable itself to t or nil in order to turn all +options on or off, respectively.@* +Supplying labels in new sections and environments applies when creating +sections with @kbd{C-c C-s} and environments with @kbd{C-c C-e}.@* +Supplying macro arguments applies when you insert such a macro +interactively with @kbd{C-c @key{RET}}.@* +See the AUCTeX documentation for more information. +@end defopt + +@defopt reftex-revisit-to-follow +Non-@code{nil} means, follow-mode will revisit files if necessary. +When nil, follow-mode will be suspended for stuff in unvisited files. +@end defopt + +@defopt reftex-allow-detached-macro-args +Non-@code{nil} means, allow arguments of macros to be detached by +whitespace. When this is @code{t}, the @samp{aaa} in @w{@samp{\bbb +[xxx] @{aaa@}}} will be considered an argument of @code{\bb}. Note that +this will be the case even if @code{\bb} is defined with zero or one +argument.@refill +@end defopt + +@node Keymaps and Hooks, Changes, Options, Top +@section Keymaps and Hooks +@cindex Keymaps + +@b{Ref@TeX{}} has the usual general keymap and load-- and mode-hook. + +@deffn Keymap reftex-mode-map +The keymap for @b{Ref@TeX{}} mode. +@end deffn + +@deffn {Normal Hook} reftex-load-hook +Normal hook which is being run when loading @file{reftex.el}. +@end deffn + +@deffn {Normal Hook} reftex-mode-hook +Normal hook which is being run when turning on @b{Ref@TeX{}} mode.@refill +@end deffn + +Furthermore, the 3 modes used for referencing labels, creating citations +and for the table of contents buffer have their own keymaps and mode +hooks. See the respective sections. There are many more hooks which +are described in the relevant sections about options for a specific part +of @b{Ref@TeX{}}.@refill + +@node Changes, , Keymaps and Hooks, Top +@chapter Changes +@cindex Changes + +Here is a list of recent changes to @b{Ref@TeX{}}. + +@ignore +@noindent @b{Version 1.00} +@itemize @bullet +@item +released on 7 Jan 1997. +@end itemize + +@noindent @b{Version 1.04} +@itemize @bullet +@item +Macros as wrappers, AMSTeX support, delayed context parsing for +new labels.@refill +@end itemize + +@noindent @b{Version 1.05} +@itemize @bullet +@item +XEmacs port. +@end itemize + +@noindent @b{Version 1.07} +@itemize @bullet +@item +@b{Ref@TeX{}} gets its own menu. +@end itemize + +@noindent @b{Version 1.09} +@itemize @bullet +@item +Support for @code{tex-main-file}, an analogue for +@code{TeX-master}.@refill +@item +MS-DOS support. +@end itemize + +@noindent @b{Version 2.00} +@itemize @bullet +@item +Labels can be derived from context (default for sections). +@item +Configuration of label insertion and label referencing revised. +@item +Crossref fields in BibTeX database entries. +@item +@code{reftex-toc} introduced (thanks to Stephen Eglen). +@end itemize + +@noindent @b{Version 2.03} +@itemize @bullet +@item +@code{figure*}, @code{table*}, @code{sidewaysfigure/table} added to +default environments.@refill +@item +@code{reftex-bibfile-ignore-list} introduced (thanks to Rory Molinari). +@item +New functions @code{reftex-arg-label}, @code{reftex-arg-ref}, +@code{reftex-arg-cite}.@refill +@item +Emacs/XEmacs compatibility reworked. XEmacs 19.15 now is +required.@refill +@item +@code{reftex-add-to-label-alist} (to be called from AUCTeX style +files).@refill +@item +Finding context with a hook function. +@item +Sorting BibTeX entries (new variable: +@code{reftex-sort-bibtex-matches}). +@end itemize + +@noindent @b{Version 2.05} +@itemize @bullet +@item +Support for @file{custom.el}. +@item +New function @code{reftex-grep-document} (thanks to Stephen Eglen). +@end itemize + +@noindent @b{Version 2.07} +@itemize @bullet +@item +New functions @code{reftex-search-document}, +@code{reftex-query-replace-document}. +@end itemize + +@noindent @b{Version 2.11} +@itemize @bullet +@item +Submitted for inclusion to Emacs and XEmacs. +@end itemize + +@noindent @b{Version 2.14} +@itemize @bullet +@item +Variable @code{reftex-plug-into-AUCTeX} simplifies cooperation with +AUCTeX.@refill +@end itemize + +@noindent @b{Version 2.17} +@itemize @bullet +@item +Label prefix expands % escapes with current file name and other stuff. +@item +Citation format now with % escapes. This is not backward +compatible!@refill +@item +TEXINPUTS variable recognized when looking for input files. +@item +Context can be the nth argument of a macro.@refill +@item +Searching in the select buffer is now possible (@kbd{C-s} and +@kbd{C-r}).@refill +@item +Display and derive-label can use two different context methods. +@item +AMSmath @code{xalignat} and @code{xxalignat} added. +@end itemize + +@noindent @b{Version 3.00} +@itemize @bullet +@item +@b{Ref@TeX{}} should work better for very large projects: +@item +The new parser works without creating a master buffer. +@item +Rescanning can be limited to a part of a multifile document. +@item +Information from the parser can be stored in a file. +@item +@b{Ref@TeX{}} can deal with macros having a naked label as an argument. +@item +Macros may have white space and newlines between arguments. +@item +Multiple identical section headings no longer confuse +@code{reftex-toc}.@refill +@item +@b{Ref@TeX{}} should work correctly in combination with buffer-altering +packages like outline, folding, x-symbol, iso-cvt, isotex, etc.@refill +@item +All labeled environments discussed in @emph{The LaTeX Companion} by +Goossens, Mittelbach & Samarin, Addison-Wesley 1994) are part of +@b{Ref@TeX{}}'s defaults.@refill +@end itemize + +@noindent @b{Version 3.03} +@itemize @bullet +@item +Support for the LaTeX package @code{xr}, for inter-document +references.@refill +@item +A few (minor) Mule-related changes. +@item +Fixed bug which could cause @emph{huge} @file{.rel} files. +@item +Search for input and @file{.bib} files with recursive path definitions. +@end itemize + +@noindent @b{Version 3.04} +@itemize @bullet +@item +Fixed BUG in the @emph{xr} support. +@end itemize + +@noindent @b{Version 3.05} +@itemize @bullet +@item +Compatibility code now first checks for XEmacs feature. +@end itemize + +@noindent @b{Version 3.07} +@itemize @bullet +@item +@code{Ref} menu improved. +@end itemize + +@noindent @b{Version 3.10} +@itemize @bullet +@item +Fixed a bug which made reftex 3.07 fail on [X]Emacs version 19. +@item +Removed unimportant code which caused OS/2 Emacs to crash. +@item +All customization variables now accessible from menu. +@end itemize + +@noindent @b{Version 3.11} +@itemize @bullet +@item +Fixed bug which led to naked label in (e.g.) footnotes. +@item +Added scroll-other-window functions to RefTeX-Select. +@end itemize + +@noindent @b{Version 3.12} +@itemize @bullet +@item +There are 3 new keymaps for customization: @code{reftex-toc-map}, +@code{reftex-select-label-map}, @code{reftex-select-bib-map}. +@item +Refontification uses more standard font-lock stuff. +@item +When no BibTeX database files are specified, citations can also use +@code{\bibitem} entries from a @code{thebibliography} environment.@refill +@end itemize + +@noindent @b{Version 3.14} +@itemize @bullet +@item +Selection buffers can be kept between selections: this is faster. +See new variable @code{reftex-use-multiple-selection-buffers}.@refill +@item +Prefix interpretation of reftex-view-crossref changed. +@item +Support for the @code{varioref} package (@kbd{v} key in selection +buffer).@refill +@end itemize + +@noindent @b{Version 3.16} +@itemize @bullet +@item +New hooks @code{reftex-format-label-function}, +@code{reftex-format-ref-function}, @code{reftex-format-cite-function}.@refill +@item +TeXInfo documentation completed. +@item +Some restrictions in Label inserting and referencing removed. +@item +New variable @code{reftex-default-bibliography}. +@end itemize + +@noindent @b{Version 3.17} +@itemize @bullet +@item +Additional bindings in selection and @file{*toc*} buffers. @kbd{g} +redefined. +@item +New command @code{reftex-save-all-document-buffers}. +@item +Magic word matching made more intelligent. +@item +Selection process can switch to completion (with @key{TAB}). +@item +@code{\appendix} is now recognized and influences section numbering. +@item +File commentary shortened considerably (use Info documentation). +@item +New option @code{reftex-no-include-regexps} to skip some include files. +@item +New option @code{reftex-revisit-to-follow}. +@end itemize + +@noindent @b{Version 3.18} +@itemize @bullet +@item +The selection now uses a recursive edit, much like minibuffer input. +This removes all restrictions during selection. E.g. you can now +switch buffers at will, use the mouse etc.@refill +@item +New option @code{reftex-highlight-selection}. +@item +@kbd{mouse-2} can be used to select in selection and @file{*toc*} +buffers.@refill +@item +Fixed some problems regarding the interaction with VIPER mode. +@item +Follow-mode is now only used after point motion. +@item +@b{Ref@TeX{}} now finally does not fontify temporary files anymore. +@end itemize + +@noindent @b{Version 3.19} +@itemize @bullet +@item +Fixed bug with AUCTeX @code{TeX-master}. +@end itemize + +@noindent @b{Version 3.21} +@itemize @bullet +@item +New options for all faces used by @b{Ref@TeX{}}. They're in the +customization group @code{reftex-fontification-configurations}.@refill +@end itemize + +@noindent @b{Version 3.22} +@itemize @bullet +@item +Fixed bug with empty context strings. +@item +@code{reftex-mouse-view-crossref} is now bound by default at +@kbd{S-mouse-2}.@refill +@end itemize + +@noindent @b{Version 3.23} +@itemize @bullet +@item +Parse files @file{MASTER.rel} made compatible between Emacs and XEmacs. +@item +@code{kill-emacs-hook} and @code{kill-buffer-hook} now write the parse +file. +@item +The cursor inside a @code{\ref} or @code{\cite} macro can now trigger +automatic display of crossref information in the echo area. See +variable @code{reftex-auto-view-crossref}. +@item +AUCTeX interface updates: +@itemize @minus +@item +AUCTeX 9.9c and later notifies @b{Ref@TeX{}} about new sections. +@item +@b{Ref@TeX{}} notifies AUCTeX about new labels. +@item +@code{TeX-arg-ref} no longer used (introduction was unnecessary). +@item +@code{reftex-arg-label} and @code{reftex-arg-cite} fixed up. +@item +Settings added to @b{Ref@TeX{}} via style files remain local. +@end itemize +@item +Fixed bug with @code{reftex-citation} in non-latex buffers. +@item +Fixed bug with syntax table and context refontification. +@item +Safety-net for name change of @code{font-lock-reference-face}. +@end itemize + +@noindent @b{Version 3.24} +@itemize @bullet +@item +New option @code{reftex-revisit-to-echo}. +@item +Interface with X-Symbol (>=2.6) is now complete and stable. +@item +Adapted to new outline, which uses overlays. +@item +File names in @code{\bibliography} may now have the @code{.bib} +extension.@refill +@item +Fixed Bug with parsing "single file" from master file buffer. +@end itemize + +@noindent @b{Version 3.25} +@itemize @bullet +@item +Echoing of citation info caches the info for displayed entries. +New option @code{reftex-cache-cite-echo}.@refill +@item +@kbd{M-x reftex-reset-mode} now also removes the file with parsing +info.@refill +@item +Default of @code{reftex-revisit-to-follow} changed to nil. +@end itemize + +@noindent @b{Version 3.26} +@itemize @bullet +@item +[X]Emacs 19 no longer supported. Use 3.22 for Emacs 19. +@item +New hooks @code{reftex-translate-to-ascii-function}, +@code{reftex-string-to-label-function}.@refill +@item +Made sure automatic crossref display will not visit/scan files. +@end itemize + +@noindent @b{Version 3.27} +@itemize @bullet +@item +Macros can define @emph{neutral} labels, just like @code{\label} +itself.@refill +@item +New option @code{reftex-allow-detached-macro-args}, default @code{nil}! +@end itemize + +@noindent @b{Version 3.28} +@itemize @bullet +@item +Auto view crossref for XEmacs uses @code{post-command-hook} to restart the +timer, since itimer restart is not reliable.@refill +@item +Option @code{reftex-bibfile-ignore-list} renamed to @code{-regexps}. +@item +Expansion of recursive tex and bib path rewritten. +@item +Fixed problem where @b{Ref@TeX{}} did not scan unsaved buffers. +@item +Fixed bug with section numbering after *-red sections. +@end itemize + +@noindent @b{Version 3.30} +@itemize @bullet +@item +In @code{reftex-citation}, the regular expression used to scan BibTeX +files can be specified using completion on known citation keys. +@item +New keys @kbd{a} and @kbd{A} in BibTeX selection process to cite @emph{all} +entries. +@item +New command @code{reftex-renumber-simple-labels} to renumber simple +labels like @samp{eq:13} sequentially through a document. +@end itemize +@noindent @b{Version 3.33} +@itemize @bullet +@item +Multiple selection buffers are now hidden buffers (they start with a +SPACE). +@item +Fixed bug with file search when TEXINPUTS environment variable is empty. +@end itemize +@noindent @b{Version 3.34} +@itemize @bullet +@item +Additional flag in @code{reftex-derive-label-parameters} do make only +lowercase labels (default @code{t}). +@item +All @file{.rel} files have a final newline to avoid queries. +@item +Single byte representations of accented European letters (ISO-8859-1) +are now legal in labels. +@end itemize +@noindent @b{Version 3.35} +@itemize @bullet +@item +ISO 8859 Latin-1 chars are converted to ASCII to derive better labels. +This takes back the related changes in 3.34 for safety reasons.@refill +@end itemize +@noindent @b{Version 3.36} +@itemize @bullet +@item +New value @code{window} for option @code{reftex-auto-view-crossref}. +@end itemize +@noindent @b{Version 3.38} +@itemize @bullet +@item +@code{reftex-view-crossref} no longer moves to find a macro. Point has +to be on the macro argument. +@end itemize +@noindent @b{Version 3.41} +@itemize @bullet +@item +New options @code{reftex-texpath-environment-variables}, +@code{reftex-use-external-file-finders}, +@code{reftex-external-file-finders}, +@code{reftex-search-unrecursed-path-first}. +@item +@emph{kpathsearch} support. See new options and +@code{reftex-bibpath-environment-variables}. +@end itemize +@end ignore +@noindent @b{Version 3.42} +@itemize @bullet +@item +File search further refined. New option @code{reftex-file-extensions}. +@item +@file{*toc*} buffer can show the file boundaries of a multifile +document, all labels and associated context. New keys @kbd{i}, @kbd{l}, +and @kbd{c}. New options @code{reftex-toc-include-labels}, +@code{reftex-toc-include-context}, +@code{reftex-toc-include-file-boundaries}. @refill +@end itemize +@noindent @b{Version 3.43} +@itemize @bullet +@item +Viewing cross-references generalized. Now works on @code{\label}, +@code{\ref}, @code{\cite}, @code{\bibitem}, @code{\index}, variations of +these, and from BibTeX buffers.@refill +@item +New option @code{reftex-view-crossref-extra}.@refill +@item +Support for the additional sectioning commands @code{\addchap} and +@code{\addsec} which are defined in the LaTeX KOMA-Script classes.@refill +@item +Files in @code{reftex-default-bibliography} will be searched along +@code{BIBINPUTS} path.@refill +@item +Reading a parse file now checks consistency. +@end itemize +@noindent @b{Version 4.00} +@itemize @bullet +@item +RefTeX has been split into several smaller files which are autoloaded on +demand. +@item +Index support, along with many new options. +@item +The selection of keys for @code{\ref} and @code{\cite} now allows to +select multiple items by marking entries with the @kbd{m} key. +@item +Fancyref support. +@end itemize +@noindent @b{Version 4.01} +@itemize @bullet +@item +New command @code{reftex-index-globally} to index a word in many +places in the document. Also available from the index buffer with +@kbd{&}. +@item +The first item in a @code{reftex-label-alist} entry may now also be a parser +function to do non-standard parsing. +@item +@code{reftex-auto-view-crossref} no longer interferes with +@code{pop-up-frames} (patch from Stefan Monnier). +@end itemize +@noindent @b{Version 4.02} +@itemize @bullet +@item +macros ending in @samp{refrange} are considered to contain references. +@item +Index entries made with @code{reftex-index-selection-or-word} in TeX +math mode automatically get enclosing @samp{$} to preserve math mode. See +new option @code{reftex-index-math-format}. Requires AUCTeX. +@end itemize +@noindent @b{Version 4.04} +@itemize @bullet +@item +New option @code{reftex-index-default-tag} implements a default for queries. +@end itemize +@noindent @b{Version 4.06} +@itemize @bullet +@item +@code{reftex-section-levels} can contain a function to compute the level +of a sectioning command. +@item +Multiple @code{thebibliography} environments recognized. +@end itemize + + +@node Index, , , Top +@unnumbered Index +@printindex cp + +@summarycontents +@contents +@bye + diff --git a/man/regs.texi b/man/regs.texi new file mode 100644 index 00000000000..8c51c603595 --- /dev/null +++ b/man/regs.texi @@ -0,0 +1,296 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Registers, Display, Rectangles, Top +@chapter Registers +@cindex registers + + Emacs @dfn{registers} are places you can save text or positions for +later use. Once you save text or a rectangle in a register, you can +copy it into the buffer once or many times; you can move point to a +position saved in a register once or many times. + +@findex view-register + Each register has a name which is a single character. A register can +store a piece of text, a rectangle, a position, a window configuration, +or a file name, but only one thing at any given time. Whatever you +store in a register remains there until you store something else in that +register. To see what a register @var{r} contains, use @kbd{M-x +view-register}. + +@table @kbd +@item M-x view-register @key{RET} @var{r} +Display a description of what register @var{r} contains. +@end table + +@menu +* Position: RegPos. Saving positions in registers. +* Text: RegText. Saving text in registers. +* Rectangle: RegRect. Saving rectangles in registers. +* Configurations: RegConfig. Saving window configurations in registers. +* Files: RegFiles. File names in registers. +* Numbers: RegNumbers. Numbers in registers. +* Bookmarks:: Bookmarks are like registers, but persistent. +@end menu + +@node RegPos +@section Saving Positions in Registers + + Saving a position records a place in a buffer so that you can move +back there later. Moving to a saved position switches to that buffer +and moves point to that place in it. + +@table @kbd +@item C-x r @key{SPC} @var{r} +Save position of point in register @var{r} (@code{point-to-register}). +@item C-x r j @var{r} +Jump to the position saved in register @var{r} (@code{jump-to-register}). +@end table + +@kindex C-x r SPC +@findex point-to-register + To save the current position of point in a register, choose a name +@var{r} and type @kbd{C-x r @key{SPC} @var{r}}. The register @var{r} +retains the position thus saved until you store something else in that +register. + +@kindex C-x r j +@findex jump-to-register + The command @kbd{C-x r j @var{r}} moves point to the position recorded +in register @var{r}. The register is not affected; it continues to +record the same position. You can jump to the saved position any number +of times. + + If you use @kbd{C-x r j} to go to a saved position, but the buffer it +was saved from has been killed, @kbd{C-x r j} tries to create the buffer +again by visiting the same file. Of course, this works only for buffers +that were visiting files. + +@node RegText +@section Saving Text in Registers + + When you want to insert a copy of the same piece of text several +times, it may be inconvenient to yank it from the kill ring, since each +subsequent kill moves that entry further down the ring. An alternative +is to store the text in a register and later retrieve it. + +@table @kbd +@item C-x r s @var{r} +Copy region into register @var{r} (@code{copy-to-register}). +@item C-x r i @var{r} +Insert text from register @var{r} (@code{insert-register}). +@end table + +@kindex C-x r s +@kindex C-x r i +@findex copy-to-register +@findex insert-register + @kbd{C-x r s @var{r}} stores a copy of the text of the region into the +register named @var{r}. Given a numeric argument, @kbd{C-x r s @var{r}} +deletes the text from the buffer as well. + + @kbd{C-x r i @var{r}} inserts in the buffer the text from register +@var{r}. Normally it leaves point before the text and places the mark +after, but with a numeric argument (@kbd{C-u}) it puts point after the +text and the mark before. + +@node RegRect +@section Saving Rectangles in Registers + + A register can contain a rectangle instead of linear text. The +rectangle is represented as a list of strings. @xref{Rectangles}, for +basic information on how to specify a rectangle in the buffer. + +@table @kbd +@findex copy-rectangle-to-register +@kindex C-x r r +@item C-x r r @var{r} +Copy the region-rectangle into register @var{r} +(@code{copy-rectangle-to-register}). With numeric argument, delete it as +well. +@item C-x r i @var{r} +Insert the rectangle stored in register @var{r} (if it contains a +rectangle) (@code{insert-register}). +@end table + + The @kbd{C-x r i @var{r}} command inserts a text string if the +register contains one, and inserts a rectangle if the register contains +one. + + See also the command @code{sort-columns}, which you can think of +as sorting a rectangle. @xref{Sorting}. + +@node RegConfig +@section Saving Window Configurations in Registers + +@findex window-configuration-to-register +@findex frame-configuration-to-register +@kindex C-x r w +@kindex C-x r f + You can save the window configuration of the selected frame in a +register, or even the configuration of all windows in all frames, and +restore the configuration later. + +@table @kbd +@item C-x r w @var{r} +Save the state of the selected frame's windows in register @var{r} +(@code{window-configuration-to-register}). +@item C-x r f @var{r} +Save the state of all frames, including all their windows, in register +@var{r} (@code{frame-configuration-to-register}). +@end table + + Use @kbd{C-x r j @var{r}} to restore a window or frame configuration. +This is the same command used to restore a cursor position. When you +restore a frame configuration, any existing frames not included in the +configuration become invisible. If you wish to delete these frames +instead, use @kbd{C-u C-x r j @var{r}}. + +@node RegNumbers +@section Keeping Numbers in Registers + + There are commands to store a number in a register, to insert +the number in the buffer in decimal, and to increment it. These commands +can be useful in keyboard macros (@pxref{Keyboard Macros}). + +@table @kbd +@item C-u @var{number} C-x r n @var{reg} +@kindex C-x r n +@findex number-to-register +Store @var{number} into register @var{reg} (@code{number-to-register}). +@item C-u @var{number} C-x r + @var{reg} +@kindex C-x r + +@findex increment-register +Increment the number in register @var{reg} by @var{number} +(@code{increment-register}). +@item C-x r g @var{reg} +Insert the number from register @var{reg} into the buffer. +@end table + + @kbd{C-x r g} is the same command used to insert any other +sort of register contents into the buffer. + +@node RegFiles +@section Keeping File Names in Registers + + If you visit certain file names frequently, you can visit them more +conveniently if you put their names in registers. Here's the Lisp code +used to put a file name in a register: + +@smallexample +(set-register ?@var{r} '(file . @var{name})) +@end smallexample + +@need 3000 +@noindent +For example, + +@smallexample +(set-register ?z '(file . "/gd/gnu/emacs/19.0/src/ChangeLog")) +@end smallexample + +@noindent +puts the file name shown in register @samp{z}. + + To visit the file whose name is in register @var{r}, type @kbd{C-x r j +@var{r}}. (This is the same command used to jump to a position or +restore a frame configuration.) + +@node Bookmarks +@section Bookmarks +@cindex bookmarks + + @dfn{Bookmarks} are somewhat like registers in that they record +positions you can jump to. Unlike registers, they have long names, and +they persist automatically from one Emacs session to the next. The +prototypical use of bookmarks is to record ``where you were reading'' in +various files. + +@table @kbd +@item C-x r m @key{RET} +Set the bookmark for the visited file, at point. + +@item C-x r m @var{bookmark} @key{RET} +@findex bookmark-set +Set the bookmark named @var{bookmark} at point (@code{bookmark-set}). + +@item C-x r b @var{bookmark} @key{RET} +@findex bookmark-jump +Jump to the bookmark named @var{bookmark} (@code{bookmark-jump}). + +@item C-x r l +@findex list-bookmarks +List all bookmarks (@code{list-bookmarks}). + +@item M-x bookmark-save +@findex bookmark-save +Save all the current bookmark values in the default bookmark file. +@end table + +@kindex C-x r m +@findex bookmark-set +@kindex C-x r b +@findex bookmark-jump + The prototypical use for bookmarks is to record one current position +in each of several files. So the command @kbd{C-x r m}, which sets a +bookmark, uses the visited file name as the default for the bookmark +name. If you name each bookmark after the file it points to, then you +can conveniently revisit any of those files with @kbd{C-x r b}, and move +to the position of the bookmark at the same time. + +@kindex C-x r l + To display a list of all your bookmarks in a separate buffer, type +@kbd{C-x r l} (@code{list-bookmarks}). If you switch to that buffer, +you can use it to edit your bookmark definitions or annotate the +bookmarks. Type @kbd{C-h m} in that buffer for more information about +its special editing commands. + + When you kill Emacs, Emacs offers to save your bookmark values in your +default bookmark file, @file{~/.emacs.bmk}, if you have changed any +bookmark values. You can also save the bookmarks at any time with the +@kbd{M-x bookmark-save} command. The bookmark commands load your +default bookmark file automatically. This saving and loading is how +bookmarks persist from one Emacs session to the next. + +@vindex bookmark-save-flag + If you set the variable @code{bookmark-save-flag} to 1, then each +command that sets a bookmark will also save your bookmarks; this way, +you don't lose any bookmark values even if Emacs crashes. (The value, +if a number, says how many bookmark modifications should go by between +saving.) + +@vindex bookmark-search-size + Bookmark position values are saved with surrounding context, so that +@code{bookmark-jump} can find the proper position even if the file is +modified slightly. The variable @code{bookmark-search-size} says how +many characters of context to record, on each side of the bookmark's +position. + + Here are some additional commands for working with bookmarks: + +@table @kbd +@item M-x bookmark-load @key{RET} @var{filename} @key{RET} +@findex bookmark-load +Load a file named @var{filename} that contains a list of bookmark +values. You can use this command, as well as @code{bookmark-write}, to +work with other files of bookmark values in addition to your default +bookmark file. + +@item M-x bookmark-write @key{RET} @var{filename} @key{RET} +@findex bookmark-write +Save all the current bookmark values in the file @var{filename}. + +@item M-x bookmark-delete @key{RET} @var{bookmark} @key{RET} +@findex bookmark-delete +Delete the bookmark named @var{bookmark}. + +@item M-x bookmark-insert-location @key{RET} @var{bookmark} @key{RET} +@findex bookmark-insert-location +Insert in the buffer the name of the file that bookmark @var{bookmark} +points to. + +@item M-x bookmark-insert @key{RET} @var{bookmark} @key{RET} +@findex bookmark-insert +Insert in the buffer the @emph{contents} of the file that bookmark +@var{bookmark} points to. +@end table diff --git a/man/rmail.texi b/man/rmail.texi new file mode 100644 index 00000000000..c64623a53ca --- /dev/null +++ b/man/rmail.texi @@ -0,0 +1,1154 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Rmail, Dired, Sending Mail, Top +@chapter Reading Mail with Rmail +@cindex Rmail +@cindex reading mail +@findex rmail +@findex rmail-mode +@vindex rmail-mode-hook + + Rmail is an Emacs subsystem for reading and disposing of mail that you +receive. Rmail stores mail messages in files called Rmail files. +Reading the message in an Rmail file is done in a special major mode, +Rmail mode, which redefines most letters to run commands for managing +mail. The command @code{rmail-mode} is used to switch into Rmail mode, +and it runs the hook @code{rmail-mode-hook} as usual, but don't run this +command by hand; it can't do a reasonable job unless the buffer is +visiting a proper Rmail file. + +@menu +* Basic: Rmail Basics. Basic concepts of Rmail, and simple use. +* Scroll: Rmail Scrolling. Scrolling through a message. +* Motion: Rmail Motion. Moving to another message. +* Deletion: Rmail Deletion. Deleting and expunging messages. +* Inbox: Rmail Inbox. How mail gets into the Rmail file. +* Files: Rmail Files. Using multiple Rmail files. +* Output: Rmail Output. Copying message out to files. +* Labels: Rmail Labels. Classifying messages by labeling them. +* Attrs: Rmail Attributes. Certain standard labels, called attributes. +* Reply: Rmail Reply. Sending replies to messages you are viewing. +* Summary: Rmail Summary. Summaries show brief info on many messages. +* Sort: Rmail Sorting. Sorting messages in Rmail. +* Display: Rmail Display. How Rmail displays a message; customization. +* Editing: Rmail Editing. Editing message text and headers in Rmail. +* Digest: Rmail Digest. Extracting the messages from a digest message. +* Out of Rmail:: Converting an Rmail file to mailbox format. +* Rot13: Rmail Rot13. Reading messages encoded in the rot13 code. +* Movemail: Movemail. More details of fetching new mail. +@end menu + +@node Rmail Basics +@section Basic Concepts of Rmail + +@cindex primary Rmail file +@vindex rmail-file-name + Using Rmail in the simplest fashion, you have one Rmail file +@file{~/RMAIL} in which all of your mail is saved. It is called your +@dfn{primary Rmail file}. The command @kbd{M-x rmail} reads your primary +Rmail file, merges new mail in from your inboxes, displays the first +message you haven't read yet, and lets you begin reading. The variable +@code{rmail-file-name} specifies the name of the primary Rmail file. + + Rmail uses narrowing to hide all but one message in the Rmail file. +The message that is shown is called the @dfn{current message}. Rmail +mode's special commands can do such things as delete the current +message, copy it into another file, send a reply, or move to another +message. You can also create multiple Rmail files and use Rmail to move +messages between them. + +@cindex message number + Within the Rmail file, messages are normally arranged sequentially in +order of receipt; you can specify other ways to sort them. Messages are +assigned consecutive integers as their @dfn{message numbers}. The +number of the current message is displayed in Rmail's mode line, +followed by the total number of messages in the file. You can move to a +message by specifying its message number with the @kbd{j} key +(@pxref{Rmail Motion}). + +@kindex s @r{(Rmail)} +@findex rmail-save + Following the usual conventions of Emacs, changes in an Rmail file +become permanent only when the file is saved. You can save it with +@kbd{s} (@code{rmail-save}), which also expunges deleted messages from +the file first (@pxref{Rmail Deletion}). To save the file without +expunging, use @kbd{C-x C-s}. Rmail also saves the Rmail file after +merging new mail from an inbox file (@pxref{Rmail Inbox}). + +@kindex q @r{(Rmail)} +@findex rmail-quit +@kindex b @r{(Rmail)} +@findex rmail-bury + You can exit Rmail with @kbd{q} (@code{rmail-quit}); this expunges and +saves the Rmail file and then switches to another buffer. But there is +no need to `exit' formally. If you switch from Rmail to editing in +other buffers, and never happen to switch back, you have exited. (The +Rmail command @kbd{b}, @code{rmail-bury}, does this for you.) Just make +sure to save the Rmail file eventually (like any other file you have +changed). @kbd{C-x s} is a good enough way to do this +(@pxref{Saving}). + +@node Rmail Scrolling +@section Scrolling Within a Message + + When Rmail displays a message that does not fit on the screen, you +must scroll through it to read the rest. You could do this with +@kbd{C-v}, @kbd{M-v} and @kbd{M-<}, but in Rmail scrolling is so +frequent that it deserves to be easier to type. + +@table @kbd +@item @key{SPC} +Scroll forward (@code{scroll-up}). +@item @key{DEL} +Scroll backward (@code{scroll-down}). +@item . +Scroll to start of message (@code{rmail-beginning-of-message}). +@end table + +@kindex SPC @r{(Rmail)} +@kindex DEL @r{(Rmail)} + Since the most common thing to do while reading a message is to scroll +through it by screenfuls, Rmail makes @key{SPC} and @key{DEL} synonyms of +@kbd{C-v} (@code{scroll-up}) and @kbd{M-v} (@code{scroll-down}) + +@kindex . @r{(Rmail)} +@findex rmail-beginning-of-message + The command @kbd{.} (@code{rmail-beginning-of-message}) scrolls back to the +beginning of the selected message. This is not quite the same as @kbd{M-<}: +for one thing, it does not set the mark; for another, it resets the buffer +boundaries to the current message if you have changed them. + +@node Rmail Motion +@section Moving Among Messages + + The most basic thing to do with a message is to read it. The way to +do this in Rmail is to make the message current. The usual practice is +to move sequentially through the file, since this is the order of +receipt of messages. When you enter Rmail, you are positioned at the +first message that you have not yet made current (that is, the first one +that has the @samp{unseen} attribute; @pxref{Rmail Attributes}). Move +forward to see the other new messages; move backward to reexamine old +messages. + +@table @kbd +@item n +Move to the next nondeleted message, skipping any intervening deleted +messages (@code{rmail-next-undeleted-message}). +@item p +Move to the previous nondeleted message +(@code{rmail-previous-undeleted-message}). +@item M-n +Move to the next message, including deleted messages +(@code{rmail-next-message}). +@item M-p +Move to the previous message, including deleted messages +(@code{rmail-previous-message}). +@item j +Move to the first message. With argument @var{n}, move to +message number @var{n} (@code{rmail-show-message}). +@item > +Move to the last message (@code{rmail-last-message}). +@item < +Move to the first message (@code{rmail-first-message}). + +@item M-s @var{regexp} @key{RET} +Move to the next message containing a match for @var{regexp} +(@code{rmail-search}). + +@item - M-s @var{regexp} @key{RET} +Move to the previous message containing a match for @var{regexp}. +@end table + +@kindex n @r{(Rmail)} +@kindex p @r{(Rmail)} +@kindex M-n @r{(Rmail)} +@kindex M-p @r{(Rmail)} +@findex rmail-next-undeleted-message +@findex rmail-previous-undeleted-message +@findex rmail-next-message +@findex rmail-previous-message + @kbd{n} and @kbd{p} are the usual way of moving among messages in +Rmail. They move through the messages sequentially, but skip over +deleted messages, which is usually what you want to do. Their command +definitions are named @code{rmail-next-undeleted-message} and +@code{rmail-previous-undeleted-message}. If you do not want to skip +deleted messages---for example, if you want to move to a message to +undelete it---use the variants @kbd{M-n} and @kbd{M-p} +(@code{rmail-next-message} and @code{rmail-previous-message}). A +numeric argument to any of these commands serves as a repeat +count.@refill + + In Rmail, you can specify a numeric argument by typing just the +digits. You don't need to type @kbd{C-u} first. + +@kindex M-s @r{(Rmail)} +@findex rmail-search +@cindex searching in Rmail + The @kbd{M-s} (@code{rmail-search}) command is Rmail's version of +search. The usual incremental search command @kbd{C-s} works in Rmail, +but it searches only within the current message. The purpose of +@kbd{M-s} is to search for another message. It reads a regular +expression (@pxref{Regexps}) nonincrementally, then searches starting at +the beginning of the following message for a match. It then selects +that message. If @var{regexp} is empty, @kbd{M-s} reuses the regexp +used the previous time. + + To search backward in the file for another message, give @kbd{M-s} a +negative argument. In Rmail you can do this with @kbd{- M-s}. + + It is also possible to search for a message based on labels. +@xref{Rmail Labels}. + +@kindex j @r{(Rmail)} +@kindex > @r{(Rmail)} +@kindex < @r{(Rmail)} +@findex rmail-show-message +@findex rmail-last-message +@findex rmail-first-message + To move to a message specified by absolute message number, use @kbd{j} +(@code{rmail-show-message}) with the message number as argument. With +no argument, @kbd{j} selects the first message. @kbd{<} +(@code{rmail-first-message}) also selects the first message. @kbd{>} +(@code{rmail-last-message}) selects the last message. + +@node Rmail Deletion +@section Deleting Messages + +@cindex deletion (Rmail) + When you no longer need to keep a message, you can @dfn{delete} it. This +flags it as ignorable, and some Rmail commands pretend it is no longer +present; but it still has its place in the Rmail file, and still has its +message number. + +@cindex expunging (Rmail) + @dfn{Expunging} the Rmail file actually removes the deleted messages. +The remaining messages are renumbered consecutively. Expunging is the only +action that changes the message number of any message, except for +undigestifying (@pxref{Rmail Digest}). + +@table @kbd +@item d +Delete the current message, and move to the next nondeleted message +(@code{rmail-delete-forward}). +@item C-d +Delete the current message, and move to the previous nondeleted +message (@code{rmail-delete-backward}). +@item u +Undelete the current message, or move back to a deleted message and +undelete it (@code{rmail-undelete-previous-message}). +@item x +Expunge the Rmail file (@code{rmail-expunge}). +@end table + +@kindex d @r{(Rmail)} +@kindex C-d @r{(Rmail)} +@findex rmail-delete-forward +@findex rmail-delete-backward + There are two Rmail commands for deleting messages. Both delete the +current message and select another message. @kbd{d} +(@code{rmail-delete-forward}) moves to the following message, skipping +messages already deleted, while @kbd{C-d} (@code{rmail-delete-backward}) +moves to the previous nondeleted message. If there is no nondeleted +message to move to in the specified direction, the message that was just +deleted remains current. A numeric argument to either command reverses +the direction of motion after deletion. + +@vindex rmail-delete-message-hook + Whenever Rmail deletes a message, it invokes the function(s) listed in +@code{rmail-delete-message-hook}. When the hook functions are invoked, +the message has been marked deleted, but it is still the current message +in the Rmail buffer. + +@cindex undeletion (Rmail) +@kindex x @r{(Rmail)} +@findex rmail-expunge +@kindex u @r{(Rmail)} +@findex rmail-undelete-previous-message + To make all the deleted messages finally vanish from the Rmail file, +type @kbd{x} (@code{rmail-expunge}). Until you do this, you can still +@dfn{undelete} the deleted messages. The undeletion command, @kbd{u} +(@code{rmail-undelete-previous-message}), is designed to cancel the +effect of a @kbd{d} command in most cases. It undeletes the current +message if the current message is deleted. Otherwise it moves backward +to previous messages until a deleted message is found, and undeletes +that message. + + You can usually undo a @kbd{d} with a @kbd{u} because the @kbd{u} +moves back to and undeletes the message that the @kbd{d} deleted. But +this does not work when the @kbd{d} skips a few already-deleted messages +that follow the message being deleted; then the @kbd{u} command +undeletes the last of the messages that were skipped. There is no clean +way to avoid this problem. However, by repeating the @kbd{u} command, +you can eventually get back to the message that you intend to +undelete. You can also select a particular deleted message with +the @kbd{M-p} command, then type @kbd{u} to undelete it. + + A deleted message has the @samp{deleted} attribute, and as a result +@samp{deleted} appears in the mode line when the current message is +deleted. In fact, deleting or undeleting a message is nothing more than +adding or removing this attribute. @xref{Rmail Attributes}. + +@node Rmail Inbox +@section Rmail Files and Inboxes +@cindex inbox file + + The operating system places incoming mail for you in a file that we +call your @dfn{inbox}. When you start up Rmail, it runs a C program +called @code{movemail} to copy the new messages from your inbox into +your primary Rmail file, which also contains other messages saved from +previous Rmail sessions. It is in this file that you actually read the +mail with Rmail. This operation is called @dfn{getting new mail}. You +can get new mail at any time in Rmail by typing @kbd{g}. + +@vindex rmail-primary-inbox-list +@cindex @code{MAIL} environment variable + The variable @code{rmail-primary-inbox-list} contains a list of the +files which are inboxes for your primary Rmail file. If you don't set +this variable explicitly, it is initialized from the @code{MAIL} +environment variable, or, as a last resort, set to @code{nil}, which +means to use the default inbox. The default inbox is +@file{/var/mail/@var{username}}, @file{/usr/spool/mail/@var{username}}, +or @file{/usr/mail/@var{username}}, depending on your operating system. + + To see what the default is on your system, use @kbd{C-h v +rmail-primary-inbox @key{RET}}. You can specify the inbox file(s) for +any Rmail file with the command @code{set-rmail-inbox-list}; see +@ref{Rmail Files}. + + There are two reasons for having separate Rmail files and inboxes. + +@enumerate +@item +The inbox file format varies between operating systems and according to +the other mail software in use. Only one part of Rmail needs to know +about the alternatives, and it need only understand how to convert all +of them to Rmail's own format. + +@item +It is very cumbersome to access an inbox file without danger of losing +mail, because it is necessary to interlock with mail delivery. +Moreover, different operating systems use different interlocking +techniques. The strategy of moving mail out of the inbox once and for +all into a separate Rmail file avoids the need for interlocking in all +the rest of Rmail, since only Rmail operates on the Rmail file. +@end enumerate + + Rmail was written to use Babyl format as its internal format. Since +then, we have recognized that the usual inbox format on Unix and GNU +systems is adequate for the job, and we plan to change Rmail to use that +as its internal format. However, the Rmail file will still be separate +from the inbox file, even on systems where their format is the same. + +@node Rmail Files +@section Multiple Rmail Files + + Rmail operates by default on your @dfn{primary Rmail file}, which is named +@file{~/RMAIL} and receives your incoming mail from your system inbox file. +But you can also have other Rmail files and edit them with Rmail. These +files can receive mail through their own inboxes, or you can move messages +into them with explicit Rmail commands (@pxref{Rmail Output}). + +@table @kbd +@item i @var{file} @key{RET} +Read @var{file} into Emacs and run Rmail on it (@code{rmail-input}). + +@item M-x set-rmail-inbox-list @key{RET} @var{files} @key{RET} +Specify inbox file names for current Rmail file to get mail from. + +@item g +Merge new mail from current Rmail file's inboxes +(@code{rmail-get-new-mail}). + +@item C-u g @var{file} @key{RET} +Merge new mail from inbox file @var{file}. +@end table + +@kindex i @r{(Rmail)} +@findex rmail-input + To run Rmail on a file other than your primary Rmail file, you may use +the @kbd{i} (@code{rmail-input}) command in Rmail. This visits the file +in Rmail mode. You can use @kbd{M-x rmail-input} even when not in +Rmail. + + The file you read with @kbd{i} should normally be a valid Rmail file. +If it is not, Rmail tries to decompose it into a stream of messages in +various known formats. If it succeeds, it converts the whole file to an +Rmail file. If you specify a file name that doesn't exist, @kbd{i} +initializes a new buffer for creating a new Rmail file. + +@vindex rmail-secondary-file-directory +@vindex rmail-secondary-file-regexp + You can also select an Rmail file from a menu. Choose first the menu +bar Classify item, then from the Classify menu choose the Input Rmail +File item; then choose the Rmail file you want. The variables +@code{rmail-secondary-file-directory} and +@code{rmail-secondary-file-regexp} specify which files to offer in the +menu: the first variable says which directory to find them in; the +second says which files in that directory to offer (all those that match +the regular expression). These variables also apply to choosing a file +for output (@pxref{Rmail Output}). + +@findex set-rmail-inbox-list + Each Rmail file can contain a list of inbox file names; you can specify +this list with @kbd{M-x set-rmail-inbox-list @key{RET} @var{files} +@key{RET}}. The argument can contain any number of file names, separated +by commas. It can also be empty, which specifies that this file should +have no inboxes. Once a list of inboxes is specified, the Rmail file +remembers it permanently until you specify a different list. + + As a special exception, if your primary Rmail file does not specify any +inbox files, it uses your standard system inbox. + +@kindex g @r{(Rmail)} +@findex rmail-get-new-mail + The @kbd{g} command (@code{rmail-get-new-mail}) merges mail into the +current Rmail file from its specified inboxes. If the Rmail file +has no inboxes, @kbd{g} does nothing. The command @kbd{M-x rmail} +also merges new mail into your primary Rmail file. + + To merge mail from a file that is not the usual inbox, give the +@kbd{g} key a numeric argument, as in @kbd{C-u g}. Then it reads a file +name and merges mail from that file. The inbox file is not deleted or +changed in any way when @kbd{g} with an argument is used. This is, +therefore, a general way of merging one file of messages into another. + +@node Rmail Output +@section Copying Messages Out to Files + + These commands copy messages from an Rmail file into another file. + +@table @kbd +@item o @var{file} @key{RET} +Append a copy of the current message to the file @var{file}, using Rmail +file format by default (@code{rmail-output-to-rmail-file}). + +@item C-o @var{file} @key{RET} +Append a copy of the current message to the file @var{file}, using +system inbox file format by default (@code{rmail-output}). + +@item w @var{file} @key{RET} +Output just the message body to the file @var{file}, taking the default +file name from the message @samp{Subject} header. +@end table + +@kindex o @r{(Rmail)} +@findex rmail-output-to-rmail-file +@kindex C-o @r{(Rmail)} +@findex rmail-output + The commands @kbd{o} and @kbd{C-o} copy the current message into a +specified file. This file may be an Rmail file or it may be in system +inbox format; the output commands ascertain the file's format and write +the copied message in that format. + + When copying a message to a file in Unix mail file format, these +commands include whichever header fields are currently visible. Use the +@kbd{t} command first, if you wish, to specify which headers to show +(and copy). + + The @kbd{o} and @kbd{C-o} commands differ in two ways: each has its +own separate default file name, and each specifies a choice of format to +use when the file does not already exist. The @kbd{o} command uses +Rmail format when it creates a new file, while @kbd{C-o} uses system +inbox format for a new file. The default file name for @kbd{o} is the +file name used last with @kbd{o}, and the default file name for +@kbd{C-o} is the file name used last with @kbd{C-o}. + + If the output file is an Rmail file currently visited in an Emacs buffer, +the output commands copy the message into that buffer. It is up to you +to save the buffer eventually in its file. + +@kindex w @r{(Rmail)} +@findex rmail-output-body-to-file + Sometimes you may receive a message whose body holds the contents of a +file. You can save the body to a file (excluding the message header) +with the @kbd{w} command (@code{rmail-output-body-to-file}). Often +these messages contain the intended file name in the @samp{Subject} +field, so the @kbd{w} command uses the @samp{Subject} field as the +default for the output file name. However, the file name is read using +the minibuffer, so you can specify a different name if you wish. + + You can also output a message to an Rmail file chosen with a menu. +Choose first the menu bar Classify item, then from the Classify menu +choose the Output Rmail File menu item; then choose the Rmail file you want. +This outputs the current message to that file, like the @kbd{o} command. +The variables @code{rmail-secondary-file-directory} and +@code{rmail-secondary-file-regexp} specify which files to offer in the +menu: the first variable says which directory to find them in; the +second says which files in that directory to offer (all those that match +the regular expression). + +@vindex rmail-delete-after-output + Copying a message gives the original copy of the message the +@samp{filed} attribute, so that @samp{filed} appears in the mode line +when such a message is current. If you like to keep just a single copy +of every mail message, set the variable @code{rmail-delete-after-output} +to @code{t}; then the @kbd{o} and @kbd{C-o} commands delete the original +message after copying it. (You can undelete the original afterward if +you wish.) + + Copying messages into files in system inbox format uses the header +fields that are displayed in Rmail at the time. Thus, if you use the +@kbd{t} command to view the entire header and then copy the message, the +entire header is copied. @xref{Rmail Display}. + +@vindex rmail-output-file-alist + The variable @code{rmail-output-file-alist} lets you specify +intelligent defaults for the output file, based on the contents of the +current message. The value should be a list whose elements have this +form: + +@example +(@var{regexp} . @var{name-exp}) +@end example + +@noindent +If there's a match for @var{regexp} in the current message, then the +default file name for output is @var{name-exp}. If multiple elements +match the message, the first matching element decides the default file +name. The subexpression @var{name-exp} may be a string constant giving +the file name to use, or more generally it may be any Lisp expression +that returns a file name as a string. @code{rmail-output-file-alist} +applies to both @kbd{o} and @kbd{C-o}. + +@node Rmail Labels +@section Labels +@cindex label (Rmail) +@cindex attribute (Rmail) + + Each message can have various @dfn{labels} assigned to it as a means +of classification. Each label has a name; different names are different +labels. Any given label is either present or absent on a particular +message. A few label names have standard meanings and are given to +messages automatically by Rmail when appropriate; these special labels +are called @dfn{attributes}. +@ifinfo +(@xref{Rmail Attributes}.) +@end ifinfo +All other labels are assigned only by users. + +@table @kbd +@item a @var{label} @key{RET} +Assign the label @var{label} to the current message (@code{rmail-add-label}). +@item k @var{label} @key{RET} +Remove the label @var{label} from the current message (@code{rmail-kill-label}). +@item C-M-n @var{labels} @key{RET} +Move to the next message that has one of the labels @var{labels} +(@code{rmail-next-labeled-message}). +@item C-M-p @var{labels} @key{RET} +Move to the previous message that has one of the labels @var{labels} +(@code{rmail-previous-labeled-message}). +@item C-M-l @var{labels} @key{RET} +Make a summary of all messages containing any of the labels @var{labels} +(@code{rmail-summary-by-labels}). +@end table + +@kindex a @r{(Rmail)} +@kindex k @r{(Rmail)} +@findex rmail-add-label +@findex rmail-kill-label + The @kbd{a} (@code{rmail-add-label}) and @kbd{k} +(@code{rmail-kill-label}) commands allow you to assign or remove any +label on the current message. If the @var{label} argument is empty, it +means to assign or remove the same label most recently assigned or +removed. + + Once you have given messages labels to classify them as you wish, there +are two ways to use the labels: in moving and in summaries. + +@kindex C-M-n @r{(Rmail)} +@kindex C-M-p @r{(Rmail)} +@findex rmail-next-labeled-message +@findex rmail-previous-labeled-message + The command @kbd{C-M-n @var{labels} @key{RET}} +(@code{rmail-next-labeled-message}) moves to the next message that has +one of the labels @var{labels}. The argument @var{labels} specifies one +or more label names, separated by commas. @kbd{C-M-p} +(@code{rmail-previous-labeled-message}) is similar, but moves backwards +to previous messages. A numeric argument to either command serves as a +repeat count. + + The command @kbd{C-M-l @var{labels} @key{RET}} +(@code{rmail-summary-by-labels}) displays a summary containing only the +messages that have at least one of a specified set of labels. The +argument @var{labels} is one or more label names, separated by commas. +@xref{Rmail Summary}, for information on summaries.@refill + + If the @var{labels} argument to @kbd{C-M-n}, @kbd{C-M-p} or +@kbd{C-M-l} is empty, it means to use the last set of labels specified +for any of these commands. + +@node Rmail Attributes +@section Rmail Attributes + + Some labels such as @samp{deleted} and @samp{filed} have built-in +meanings and are assigned to or removed from messages automatically at +appropriate times; these labels are called @dfn{attributes}. Here is a +list of Rmail attributes: + +@table @samp +@item unseen +Means the message has never been current. Assigned to messages when +they come from an inbox file, and removed when a message is made +current. When you start Rmail, it initially shows the first message +that has this attribute. +@item deleted +Means the message is deleted. Assigned by deletion commands and +removed by undeletion commands (@pxref{Rmail Deletion}). +@item filed +Means the message has been copied to some other file. Assigned by the +file output commands (@pxref{Rmail Files}). +@item answered +Means you have mailed an answer to the message. Assigned by the @kbd{r} +command (@code{rmail-reply}). @xref{Rmail Reply}. +@item forwarded +Means you have forwarded the message. Assigned by the @kbd{f} command +(@code{rmail-forward}). @xref{Rmail Reply}. +@item edited +Means you have edited the text of the message within Rmail. +@xref{Rmail Editing}. +@item resent +Means you have resent the message. Assigned by the command @kbd{M-x +rmail-resend}. @xref{Rmail Reply}. +@end table + + All other labels are assigned or removed only by the user, and have no +standard meaning. + +@node Rmail Reply +@section Sending Replies + + Rmail has several commands that use Mail mode to send outgoing mail. +@xref{Sending Mail}, for information on using Mail mode, including +certain features meant to work with Rmail. What this section documents +are the special commands of Rmail for entering Mail mode. Note that the +usual keys for sending mail---@kbd{C-x m}, @kbd{C-x 4 m}, and @kbd{C-x 5 +m}---are available in Rmail mode and work just as they usually do. + +@table @kbd +@item m +Send a message (@code{rmail-mail}). +@item c +Continue editing the already started outgoing message (@code{rmail-continue}). +@item r +Send a reply to the current Rmail message (@code{rmail-reply}). +@item f +Forward the current message to other users (@code{rmail-forward}). +@item C-u f +Resend the current message to other users (@code{rmail-resend}). +@item M-m +Try sending a bounced message a second time (@code{rmail-retry-failure}). +@end table + +@kindex r @r{(Rmail)} +@findex rmail-reply +@cindex reply to a message + The most common reason to send a message while in Rmail is to reply to +the message you are reading. To do this, type @kbd{r} +(@code{rmail-reply}). This displays the @samp{*mail*} buffer in another +window, much like @kbd{C-x 4 m}, but preinitializes the @samp{Subject}, +@samp{To}, @samp{CC} and @samp{In-reply-to} header fields based on the +message you are replying to. The @samp{To} field starts out as the +address of the person who sent the message you received, and the +@samp{CC} field starts out with all the other recipients of that +message. + +@vindex rmail-dont-reply-to-names + You can exclude certain recipients from being placed automatically in +the @samp{CC}, using the variable @code{rmail-dont-reply-to-names}. Its +value should be a regular expression (as a string); any recipient that +the regular expression matches, is excluded from the @samp{CC} field. +The default value matches your own name, and any name starting with +@samp{info-}. (Those names are excluded because there is a convention +of using them for large mailing lists to broadcast announcements.) + + To omit the @samp{CC} field completely for a particular reply, enter +the reply command with a numeric argument: @kbd{C-u r} or @kbd{1 r}. + + Once the @samp{*mail*} buffer has been initialized, editing and +sending the mail goes as usual (@pxref{Sending Mail}). You can edit the +presupplied header fields if they are not right for you. You can also +use the commands of Mail mode (@pxref{Mail Mode}), including @kbd{C-c +C-y} which yanks in the message that you are replying to. You can +switch to the Rmail buffer, select a different message there, switch +back, and yank the new current message. + +@kindex M-m @r{(Rmail)} +@findex rmail-retry-failure +@cindex retrying a failed message +@vindex rmail-retry-ignored-headers + Sometimes a message does not reach its destination. Mailers usually +send the failed message back to you, enclosed in a @dfn{failure +message}. The Rmail command @kbd{M-m} (@code{rmail-retry-failure}) +prepares to send the same message a second time: it sets up a +@samp{*mail*} buffer with the same text and header fields as before. If +you type @kbd{C-c C-c} right away, you send the message again exactly +the same as the first time. Alternatively, you can edit the text or +headers and then send it. The variable +@code{rmail-retry-ignored-headers}, in the same format as +@code{rmail-ignored-headers} (@pxref{Rmail Display}), controls which +headers are stripped from the failed message when retrying it; it +defaults to @code{nil}. + +@kindex f @r{(Rmail)} +@findex rmail-forward +@cindex forwarding a message + Another frequent reason to send mail in Rmail is to @dfn{forward} the +current message to other users. @kbd{f} (@code{rmail-forward}) makes +this easy by preinitializing the @samp{*mail*} buffer with the current +message as the text, and a subject designating a forwarded message. All +you have to do is fill in the recipients and send. When you forward a +message, recipients get a message which is ``from'' you, and which has +the original message in its contents. + +@findex unforward-rmail-message + Forwarding a message encloses it between two delimiter lines. It also +modifies every line that starts with a dash, by inserting @w{@samp{- }} +at the start of the line. When you receive a forwarded message, if it +contains something besides ordinary text---for example, program source +code---you might find it useful to undo that transformation. You can do +this by selecting the forwarded message and typing @kbd{M-x +unforward-rmail-message}. This command extracts the original forwarded +message, deleting the inserted @w{@samp{- }} strings, and inserts it +into the Rmail file as a separate message immediately following the +current one. + +@findex rmail-resend + @dfn{Resending} is an alternative similar to forwarding; the +difference is that resending sends a message that is ``from'' the +original sender, just as it reached you---with a few added header fields +@samp{Resent-from} and @samp{Resent-to} to indicate that it came via +you. To resend a message in Rmail, use @kbd{C-u f}. (@kbd{f} runs +@code{rmail-forward}, which is programmed to invoke @code{rmail-resend} +if you provide a numeric argument.) + +@kindex m @r{(Rmail)} +@findex rmail-mail + The @kbd{m} (@code{rmail-mail}) command is used to start editing an +outgoing message that is not a reply. It leaves the header fields empty. +Its only difference from @kbd{C-x 4 m} is that it makes the Rmail buffer +accessible for @kbd{C-c C-y}, just as @kbd{r} does. Thus, @kbd{m} can be +used to reply to or forward a message; it can do anything @kbd{r} or @kbd{f} +can do.@refill + +@kindex c @r{(Rmail)} +@findex rmail-continue + The @kbd{c} (@code{rmail-continue}) command resumes editing the +@samp{*mail*} buffer, to finish editing an outgoing message you were +already composing, or to alter a message you have sent.@refill + +@vindex rmail-mail-new-frame + If you set the variable @code{rmail-mail-new-frame} to a +non-@code{nil} value, then all the Rmail commands to start sending a +message create a new frame to edit it in. This frame is deleted when +you send the message, or when you use the @samp{Don't Send} item in the +@samp{Mail} menu. + + All the Rmail commands to send a message use the mail-composition +method that you have chosen (@pxref{Mail Methods}). + +@node Rmail Summary +@section Summaries +@cindex summary (Rmail) + + A @dfn{summary} is a buffer containing one line per message to give +you an overview of the mail in an Rmail file. Each line shows the +message number, the sender, the labels, and the subject. Almost all +Rmail commands are valid in the summary buffer also; these apply to the +message described by the current line of the summary. Moving point in +the summary buffer selects messages as you move to their summary lines. + + A summary buffer applies to a single Rmail file only; if you are +editing multiple Rmail files, each one can have its own summary buffer. +The summary buffer name is made by appending @samp{-summary} to the +Rmail buffer's name. Normally only one summary buffer is displayed at a +time. + +@menu +* Rmail Make Summary:: Making various sorts of summaries. +* Rmail Summary Edit:: Manipulating messages from the summary. +@end menu + +@node Rmail Make Summary +@subsection Making Summaries + + Here are the commands to create a summary for the current Rmail file. +Once the Rmail file has a summary buffer, changes in the Rmail file +(such as deleting or expunging messages, and getting new mail) +automatically update the summary. + +@table @kbd +@item h +@itemx C-M-h +Summarize all messages (@code{rmail-summary}). +@item l @var{labels} @key{RET} +@itemx C-M-l @var{labels} @key{RET} +Summarize messages that have one or more of the specified labels +(@code{rmail-summary-by-labels}). +@item C-M-r @var{rcpts} @key{RET} +Summarize messages that have one or more of the specified recipients +(@code{rmail-summary-by-recipients}). +@item C-M-t @var{topic} @key{RET} +Summarize messages that have a match for the specified regexp +@var{topic} in their subjects (@code{rmail-summary-by-topic}). +@end table + +@kindex h @r{(Rmail)} +@findex rmail-summary + The @kbd{h} or @kbd{C-M-h} (@code{rmail-summary}) command fills the summary buffer +for the current Rmail file with a summary of all the messages in the file. +It then displays and selects the summary buffer in another window. + +@kindex l @r{(Rmail)} +@kindex C-M-l @r{(Rmail)} +@findex rmail-summary-by-labels + @kbd{C-M-l @var{labels} @key{RET}} (@code{rmail-summary-by-labels}) makes +a partial summary mentioning only the messages that have one or more of the +labels @var{labels}. @var{labels} should contain label names separated by +commas.@refill + +@kindex C-M-r @r{(Rmail)} +@findex rmail-summary-by-recipients + @kbd{C-M-r @var{rcpts} @key{RET}} (@code{rmail-summary-by-recipients}) +makes a partial summary mentioning only the messages that have one or more +of the recipients @var{rcpts}. @var{rcpts} should contain mailing +addresses separated by commas.@refill + +@kindex C-M-t @r{(Rmail)} +@findex rmail-summary-by-topic + @kbd{C-M-t @var{topic} @key{RET}} (@code{rmail-summary-by-topic}) +makes a partial summary mentioning only the messages whose subjects have +a match for the regular expression @var{topic}. + + Note that there is only one summary buffer for any Rmail file; making one +kind of summary discards any previously made summary. + +@vindex rmail-summary-window-size +@vindex rmail-summary-line-count-flag + The variable @code{rmail-summary-window-size} says how many lines to +use for the summary window. The variable +@code{rmail-summary-line-count-flag} controls whether the summary line +for a message should include the line count of the message. + +@node Rmail Summary Edit +@subsection Editing in Summaries + + You can use the Rmail summary buffer to do almost anything you can do +in the Rmail buffer itself. In fact, once you have a summary buffer, +there's no need to switch back to the Rmail buffer. + + You can select and display various messages in the Rmail buffer, from +the summary buffer, just by moving point in the summary buffer to +different lines. It doesn't matter what Emacs command you use to move +point; whichever line point is on at the end of the command, that +message is selected in the Rmail buffer. + + Almost all Rmail commands work in the summary buffer as well as in the +Rmail buffer. Thus, @kbd{d} in the summary buffer deletes the current +message, @kbd{u} undeletes, and @kbd{x} expunges. @kbd{o} and @kbd{C-o} +output the current message to a file; @kbd{r} starts a reply to it. You +can scroll the current message while remaining in the summary buffer +using @key{SPC} and @key{DEL}. + + The Rmail commands to move between messages also work in the summary +buffer, but with a twist: they move through the set of messages included +in the summary. They also ensure the Rmail buffer appears on the screen +(unlike cursor motion commands, which update the contents of the Rmail +buffer but don't display it in a window unless it already appears). +Here is a list of these commands: + +@table @kbd +@item n +Move to next line, skipping lines saying `deleted', and select its +message. +@item p +Move to previous line, skipping lines saying `deleted', and select +its message. +@item M-n +Move to next line and select its message. +@item M-p +Move to previous line and select its message. +@item > +Move to the last line, and select its message. +@item < +Move to the first line, and select its message. +@item M-s @var{pattern} @key{RET} +Search through messages for @var{pattern} starting with the current +message; select the message found, and move point in the summary buffer +to that message's line. +@end table + +@vindex rmail-redisplay-summary + Deletion, undeletion, and getting new mail, and even selection of a +different message all update the summary buffer when you do them in the +Rmail buffer. If the variable @code{rmail-redisplay-summary} is +non-@code{nil}, these actions also bring the summary buffer back onto +the screen. + +@kindex Q @r{(Rmail summary)} +@findex rmail-summary-wipe +@kindex q @r{(Rmail summary)} +@findex rmail-summary-quit + When you are finished using the summary, type @kbd{Q} +(@code{rmail-summary-wipe}) to delete the summary buffer's window. You +can also exit Rmail while in the summary: @kbd{q} +(@code{rmail-summary-quit}) deletes the summary window, then exits from +Rmail by saving the Rmail file and switching to another buffer. + +@node Rmail Sorting +@section Sorting the Rmail File + +@table @kbd +@item M-x rmail-sort-by-date +Sort messages of current Rmail file by date. + +@item M-x rmail-sort-by-subject +Sort messages of current Rmail file by subject. + +@item M-x rmail-sort-by-author +Sort messages of current Rmail file by author's name. + +@item M-x rmail-sort-by-recipient +Sort messages of current Rmail file by recipient's names. + +@item M-x rmail-sort-by-correspondent +Sort messages of current Rmail file by the name of the other +correspondent. + +@item M-x rmail-sort-by-lines +Sort messages of current Rmail file by size (number of lines). + +@item M-x rmail-sort-by-keywords @key{RET} @var{labels} @key{RET} +Sort messages of current Rmail file by labels. The argument +@var{labels} should be a comma-separated list of labels. The order of +these labels specifies the order of messages; messages with the first +label come first, messages with the second label come second, and so on. +Messages which have none of these labels come last. +@end table + + The Rmail sort commands perform a @emph{stable sort}: if there is no +reason to prefer either one of two messages, their order remains +unchanged. You can use this to sort by more than one criterion. For +example, if you use @code{rmail-sort-by-date} and then +@code{rmail-sort-by-author}, messages from the same author appear in +order by date. + + With a numeric argument, all these commands reverse the order of +comparison. This means they sort messages from newest to oldest, from +biggest to smallest, or in reverse alphabetical order. + +@node Rmail Display +@section Display of Messages + + Rmail reformats the header of each message before displaying it for +the first time. Reformatting hides uninteresting header fields to +reduce clutter. You can use the @kbd{t} command to show the entire +header or to repeat the header reformatting operation. + +@table @kbd +@item t +Toggle display of complete header (@code{rmail-toggle-header}). +@end table + +@vindex rmail-ignored-headers + Reformatting the header involves deleting most header fields, on the +grounds that they are not interesting. The variable +@code{rmail-ignored-headers} holds a regular expression that specifies +which header fields to hide in this way---if it matches the beginning of +a header field, that whole field is hidden. + +@kindex t @r{(Rmail)} +@findex rmail-toggle-header + Rmail saves the complete original header before reformatting; to see +it, use the @kbd{t} command (@code{rmail-toggle-header}). This +discards the reformatted headers of the current message and displays it +with the original header. Repeating @kbd{t} reformats the message +again. Selecting the message again also reformats. + + One consequence of this is that if you edit the reformatted header +(using @kbd{e}; @pxref{Rmail Editing}), subsequent use of @kbd{t} will +discard your edits. On the other hand, if you use @kbd{e} after +@kbd{t}, to edit the original (unreformatted) header, those changes are +permanent. + + When the @kbd{t} command has a prefix argument, a positive argument +means to show the reformatted header, and a zero or negative argument +means to show the full header. + +@vindex rmail-highlighted-headers + When used with a window system that supports multiple fonts, Rmail +highlights certain header fields that are especially interesting---by +default, the @samp{From} and @samp{Subject} fields. The variable +@code{rmail-highlighted-headers} holds a regular expression that +specifies the header fields to highlight; if it matches the beginning of +a header field, that whole field is highlighted. + + If you specify unusual colors for your text foreground and background, +the colors used for highlighting may not go well with them. If so, +specify different colors for the @code{highlight} face. That is worth +doing because the @code{highlight} face is used for other kinds of +highlighting as well. @xref{Faces}, for how to do this. + + To turn off highlighting entirely in Rmail, set +@code{rmail-highlighted-headers} to @code{nil}. + +@node Rmail Editing +@section Editing Within a Message + + Most of the usual Emacs commands are available in Rmail mode, though a +few, such as @kbd{C-M-n} and @kbd{C-M-h}, are redefined by Rmail for +other purposes. However, the Rmail buffer is normally read only, and +most of the letters are redefined as Rmail commands. If you want to +edit the text of a message, you must use the Rmail command @kbd{e}. + +@table @kbd +@item e +Edit the current message as ordinary text. +@end table + +@kindex e @r{(Rmail)} +@findex rmail-edit-current-message + The @kbd{e} command (@code{rmail-edit-current-message}) switches from +Rmail mode into Rmail Edit mode, another major mode which is nearly the +same as Text mode. The mode line indicates this change. + + In Rmail Edit mode, letters insert themselves as usual and the Rmail +commands are not available. When you are finished editing the message and +are ready to go back to Rmail, type @kbd{C-c C-c}, which switches back to +Rmail mode. Alternatively, you can return to Rmail mode but cancel all the +editing that you have done, by typing @kbd{C-c C-]}. + +@vindex rmail-edit-mode-hook + Entering Rmail Edit mode runs the hook @code{text-mode-hook}; then it +runs the hook @code{rmail-edit-mode-hook} (@pxref{Hooks}). It adds the +attribute @samp{edited} to the message. It also displays the full +headers of the message, so that you can edit the headers as well as the +body of the message, and your changes in the the headers will be +permanent. + +@node Rmail Digest +@section Digest Messages +@cindex digest message +@cindex undigestify + + A @dfn{digest message} is a message which exists to contain and carry +several other messages. Digests are used on some moderated mailing +lists; all the messages that arrive for the list during a period of time +such as one day are put inside a single digest which is then sent to the +subscribers. Transmitting the single digest uses much less computer +time than transmitting the individual messages even though the total +size is the same, because the per-message overhead in network mail +transmission is considerable. + +@findex undigestify-rmail-message + When you receive a digest message, the most convenient way to read it is +to @dfn{undigestify} it: to turn it back into many individual messages. +Then you can read and delete the individual messages as it suits you. + + To do this, select the digest message and type the command @kbd{M-x +undigestify-rmail-message}. This extracts the submessages as separate +Rmail messages, and inserts them following the digest. The digest +message itself is flagged as deleted. + +@node Out of Rmail +@section Converting an Rmail File to Inbox Format + +@findex unrmail + The command @kbd{M-x unrmail} converts a file in Rmail format to inbox +format (also known as the system mailbox format), so that you can use it +with other mail-editing tools. You must specify two arguments, the name +of the Rmail file and the name to use for the converted file. @kbd{M-x +unrmail} does not alter the Rmail file itself. + +@node Rmail Rot13 +@section Reading Rot13 Messages +@cindex rot13 code + + Mailing list messages that might offend some readers are sometimes +encoded in a simple code called @dfn{rot13}---so named because it +rotates the alphabet by 13 letters. This code is not for secrecy, as it +provides none; rather, it enables those who might be offended to avoid +ever seeing the real text of the message. + +@findex rot13-other-window + To view a buffer using the rot13 code, use the command @kbd{M-x +rot13-other-window}. This displays the current buffer in another window +which applies the code when displaying the text. + +@node Movemail +@section @code{movemail} and POP +@cindex @code{movemail} program + +@vindex rmail-preserve-inbox + When getting new mail, Rmail first copies the new mail from the inbox +file to the Rmail file; then it saves the Rmail file; then it truncates +the inbox file. This way, a system crash may cause duplication of mail +between the inbox and the Rmail file, but cannot lose mail. If +@code{rmail-preserve-inbox} is non-@code{nil}, then Rmail will copy new +mail from the inbox file to the Rmail file without truncating the inbox +file. You may wish to set this, for example, on a portable computer you +use to check your mail via POP while traveling, so that your mail will +remain on the server and you can save it later on your workstation. + + In some cases, Rmail copies the new mail from the inbox file +indirectly. First it runs the @code{movemail} program to move the mail +from the inbox to an intermediate file called +@file{~/.newmail-@var{inboxname}}. Then Rmail merges the new mail from +that file, saves the Rmail file, and only then deletes the intermediate +file. If there is a crash at the wrong time, this file continues to +exist, and Rmail will use it again the next time it gets new mail from +that inbox. + +@pindex movemail + If Rmail is unable to convert the data in +@file{~/.newmail-@var{inboxname}} into Babyl format, it renames the file +to @file{~/RMAILOSE.@var{n}} (@var{n} is an integer chosen to make the +name unique) so that Rmail will not have trouble with the data again. +You should look at the file, find whatever message confuses Rmail +(probably one that includes the control-underscore character, octal code +037), and delete it. Then you can use @kbd{1 g} to get new mail from +the corrected file. + + Some sites use a method called POP for accessing users' inbox data +instead of storing the data in inbox files. @code{movemail} can work +with POP if you compile it with the macro @code{MAIL_USE_POP} defined. +(You can achieve that by specifying @samp{--with-pop} when you run +@code{configure} during the installation of Emacs.) +@code{movemail} only works with POP3, not with older +versions of POP. + +@cindex @code{MAILHOST} environment variable +@cindex POP inboxes + Assuming you have compiled and installed @code{movemail} +appropriately, you can specify a POP inbox by using a ``file name'' of +the form @samp{po:@var{username}}, in the inbox list of an Rmail file. +@code{movemail} handles such a name by opening a connection to the POP +server. The @code{MAILHOST} environment variable specifies the machine +to look for the server on. + +@vindex rmail-pop-password +@vindex rmail-pop-password-required + Accessing mail via POP may require a password. If the variable +@code{rmail-pop-password} is non-@code{nil}, it specifies the password +to use for POP. Alternatively, if @code{rmail-pop-password-required} is +non-@code{nil}, then Rmail asks you for the password to use. + +@vindex rmail-movemail-flags + If you need to pass additional command-line flags to @code{movemail}, +set the variable @code{rmail-movemail-flags} a list of the flags you +wish to use. Do not use this variable to pass the @samp{-p} flag to +preserve your inbox contents; use @code{rmail-preserve-inbox} instead. + +@cindex Kerberos POP authentication + The @code{movemail} program installed at your site may support +Kerberos authentication. If it is +supported, it is used by default whenever you attempt to retrieve +POP mail when @code{rmail-pop-password} and +@code{rmail-pop-password-required} are unset. + +@cindex POP inboxes in reverse order + Some POP servers store messages in reverse order. If your server does +this, and you would rather read your mail in the order in which it was +received, you can tell @code{movemail} to reverse the order of +downloaded messages by adding the @samp{-r} flag to +@code{rmail-movemail-flags}. diff --git a/man/sc.texi b/man/sc.texi new file mode 100644 index 00000000000..6a190701ab3 --- /dev/null +++ b/man/sc.texi @@ -0,0 +1,2535 @@ +\input texinfo @comment -*-texinfo-*- +@comment 3.47 +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename ../info/sc +@settitle Supercite Version 3.1 User's Manual +@iftex +@finalout +@end iftex + +@dircategory Editors +@direntry +* SC: (sc). Supercite lets you cite parts of messages you're + replying to, in flexible ways. +@end direntry + +@c @setchapternewpage odd % For book style double sided manual. +@comment %**end of header (This is for running Texinfo on a region.) +@c @smallbook +@tex +\overfullrule=0pt +%\global\baselineskip 30pt % For printing in double spaces +@end tex +@ifinfo +This document describes the Supercite Version 3.1 package for citing and +attributing the replies for various GNU Emacs mail and news reading +subsystems. + +Copyright @copyright{} 1993 Barry A@. Warsaw + +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{Supercite User's Manual} +@sp 2 +@center @titlefont{Supercite Version 3.1} +@sp 4 +@center Manual Revision: 3.47 +@center August 1993 +@sp 5 +@center Barry A@. Warsaw +@center @t{bwarsaw@@cen.com} +@center @t{@dots{}!uunet!cen.com!bwarsaw} +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1993 Barry A@. Warsaw + +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) +@comment node-name, next, previous, up + +This document describes the Supercite Version 3.1 package for citing and +attributing the replies for various GNU Emacs mail and news reading +subsystems. The manual is divided into the following chapters. + +@menu +* Introduction:: +* Citations:: +* Getting Connected:: +* Replying and Yanking:: +* Selecting an Attribution:: +* Configuring the Citation Engine:: +* Post-yank Formatting Commands:: +* Information Keys and the Info Alist:: +* Reference Headers:: +* Hints to MUA Authors:: +* Version 3 Changes:: +* Thanks and History:: +* The Supercite Mailing List:: + +* Concept Index:: +* Command Index:: +* Key Index:: +* Variable Index:: +@end menu +@end ifinfo + +@node Introduction, Usage Overview, Top, Top +@comment node-name, next, previous, up +@chapter Introduction +@ifinfo + +@end ifinfo +Supercite version 3.1 is a GNU Emacs package written entirely in Emacs +Lisp. It interfaces to most of the commonly used Emacs mail user agents +(@dfn{MUAs}) and news user agents (@dfn{NUAs}), and provides +sophisticated facilities for the citing and attributing of message +replies. Supercite has a very specific and limited role in the process +of composing replies to both USENET network news and electronic mail. + +The preferred way to spell Supercite is with a capital @samp{S}, +lowercase @samp{upercite}. There are a few alternate spellings out there +and I won't be terribly offended if you use them. People often ask +though@dots{} + +@ifinfo +@menu +* Usage Overview:: +* What Supercite Does Not Do:: +* What Supercite Does:: +@end menu +@end ifinfo + +@cindex MUA +@cindex NUA +Supercite is only useful in conjunction with MUAs and NUAs such as VM, +GNUS, RMAIL, etc@. (hereafter referred to collectively as MUAs). +Supercite is typically called by the MUA after a reply buffer has been +setup. Thereafter, Supercite's many commands and formatting styles are +available in that reply buffer until the reply is sent. Supercite is +re-initialized in each new reply buffer. + +Supercite is currently at major revision 3.1, and is known to work in the +following environments: + +@table @asis +@item Emacs versions: + GNU Emacs 18.57 through 18.59, all Emacs 19, + all current Lucid Emacs, and Epoch 4.@refill + +@item MUAs: + VM 4.37 and beyond (including VM version 5), RMAIL, MH-E 3.7 and + beyond, PCMAIL.@refill + +@item NUAs: + RNEWS, GNUS 3.12 and beyond, GNEWS.@refill + +@end table +For systems with version numbers, all known subsequent versions also +work with Supercite. For those systems without version numbers, +Supercite probably works with any recently released version. Note that +only some of these systems will work with Supercite ``out of the box.'' +All others must overload interfacing routines to supply the necessary +glue. @xref{Getting Connected}, for more details.@refill + + +@node Usage Overview, What Supercite Does Not Do, Introduction, Introduction +@comment node-name, next, previous, up +@kindex r +@kindex f +@kindex C-c C-y +@cindex yank +@cindex cite, citing +@cindex attribute, attributing +@comment +@section Usage Overview +@ifinfo + +@end ifinfo +Typical usage is as follows. You want to reply or followup to a message +in your MUA. You will probably hit @kbd{r} (i.e., ``reply'') or @kbd{f} +(i.e., ``forward'') to begin composing the reply. In response, the MUA +will create a reply buffer and initialize the outgoing mail headers +appropriately. The body of the reply will usually be empty at this +point. You now decide that you would like to include part of the +original message in your reply. To do this, you @dfn{yank} the original +message into the reply buffer, typically with a key stroke such as +@kbd{C-c C-y}. This sequence will invoke an MUA-specific function which +fills the body of the reply with the original message and then +@dfn{attributes} this text to its author. This is called @dfn{citing} +and its effect is to prefix every line from the original message with a +special text tag. Most MUAs provide some default style of citing; by +using Supercite you gain a wider flexibility in the look and style of +citations. Supercite's only job is to cite the original message. + +@node What Supercite Does Not Do, What Supercite Does, Usage Overview, Introduction +@comment node-name, next, previous, up +@section What Supercite Doesn't Do +@ifinfo + +@end ifinfo +Because of this clear division of labor, there are useful features which +are the sole responsibility of the MUA, even though it might seem that +Supercite should provide them. For example, many people would like to +be able to yank (and cite) only a portion of the original message. +Since Supercite only modifies the text it finds in the reply buffer as +set up by the MUA, it is the MUA's responsibility to do partial yanking. +@xref{Reply Buffer Initialization}.@refill + +@vindex mail-header-separator +@comment +Another potentially useful thing would be for Supercite to set up the +outgoing mail headers with information it gleans from the reply buffer. +But by previously agreed upon convention, any text above the +@code{mail-header-separator} which separates mail headers from message +bodies cannot be modified by Supercite. Supercite, in fact, doesn't +know anything about the meaning of these headers, and never ventures +outside the designated region. @xref{Hints to MUA Authors}, for more +details.@refill + +@node What Supercite Does, Citations, What Supercite Does Not Do, Introduction +@comment node-name, next, previous, up +@findex sc-cite-original +@section What Supercite Does +@ifinfo + +@end ifinfo +Supercite is invoked for the first time on a reply buffer via your MUA's +reply or forward command. This command will actually perform citations +by calling a hook variable to which Supercite's top-level function +@code{sc-cite-original} has been added. When @code{sc-cite-original} is +executed, the original message must be set up in a very specific way, +but this is handled automatically by the MUA. @xref{Hints to MUA +Authors}.@refill + +@cindex info alist +The first thing Supercite does, via @code{sc-cite-original}, is to parse +through the original message's mail headers. It saves this data in an +@dfn{information association list}, or @dfn{info alist}. The information +in this list is used in a number of places throughout Supercite. +@xref{Information Keys and the Info Alist}.@refill + +@cindex nuking mail headers +@cindex reference header +After the mail header info is extracted, the headers are optionally +removed (@dfn{nuked}) from the reply. Supercite then writes a +@dfn{reference header} into the buffer. This reference header is a +string carrying details about the citation it is about to perform. + +@cindex modeline +Next, Supercite visits each line in the reply, transforming the line +according to a customizable ``script''. Lines which were not previously +cited in the original message are given a citation, while already cited +lines remain untouched, or are coerced to your preferred style. +Finally, Supercite installs a keymap into the reply buffer so that you +have access to Supercite's post-yank formatting and reciting commands as +you subsequently edit your reply. You can tell that Supercite has been +installed into the reply buffer because that buffer's modeline will +display the minor mode string @samp{SC}. + +@cindex filladapt +@cindex gin-mode +@vindex fill-prefix +@findex fill-paragraph +@comment +When the original message is cited by @code{sc-cite-original}, it will +(optionally) be filled by Supercite. However, if you manually edit the +cited text and want to re-fill it, you must use an add-on package such +as @cite{filladapt} or @cite{gin-mode}. These packages can recognize +Supercited text and will fill them appropriately. Emacs' built-in +filling routines, e.g@. @code{fill-paragraph}, do not recognize cited +text and will not re-fill them properly because it cannot guess the +@code{fill-prefix} being used. +@xref{Post-yank Formatting Commands}, for details.@refill + +As mentioned above, Supercite provides commands to recite or uncite +regions of text in the reply buffer, and commands to perform other +beautifications on the cited original text, maintaining consistent and +informative citations throughout. Supercite tries to be as configurable +as possible to allow for a wide range of personalized citation styles, +but it is also immediately useful with the default configuration, once +it has been properly connected to your MUA. @xref{Getting Connected}, +for more details.@refill + +@node Citations, Citation Elements, What Supercite Does, Top +@comment node-name, next, previous, up +@cindex nested citations +@cindex citation +@comment +@chapter Citations +@ifinfo + +@end ifinfo +A @dfn{citation} is the acknowledgement of the original author of a mail +message in the body of the reply. There are two basic citation styles +which Supercite supports. The first, called @dfn{nested citations} is +an anonymous form of citation; in other words, an indication is made +that the cited line was written by someone @emph{other} that the current +message author (i.e., other than you, the person composing the reply), +but no reference is made as to the identity of the original author. +This style should look familiar since its use on the net is widespread. +Here's an example of what a message buffer would look like using nested +citations after multiple replies: + +@example +>> John originally wrote this +>> and this as well +> Jane said that John didn't know +> what he was talking about +And that's what I think too. +@end example + +@ifinfo +@menu +* Citation Elements:: +* Recognizing Citations:: +@end menu +@end ifinfo + +Note that multiple inclusions of the original messages result in a +nesting of the @samp{@code{>}} characters. This can sometimes be quite +confusing when many levels of citations are included since it may be +difficult or impossible to figure out who actually participated in the +thread, and multiple nesting of @samp{@code{>}} characters can sometimes +make the message very difficult for the eye to scan. + +@cindex non-nested citations +In @dfn{non-nested citations}, each cited line begins with an +informative string attributing that line to the original author. Only +the first level of attribution will be shown; subsequent citations don't +nest the citation strings. The above dialog might look like this when +non-nested citations are used: + +@example +John> John originally wrote this +John> and this as well +Jane> Jane said that John didn't know +Jane> what he was talking about +And that's what I think too. +@end example + +Notice here that my inclusion of Jane's inclusion of John's original +message did not result in a line cited with @samp{Jane>John>}. + +@vindex sc-nested-citation-p +@vindex nested-citation-p (sc-) +Supercite supports both styles of citation, and the variable +@code{sc-nested-citation-p} controls which style it will use when citing +previously uncited text. When this variable is @code{nil} (the default), +non-nested citations are used. When non-@code{nil}, nested citations +are used. + + +@node Citation Elements, Recognizing Citations, Citations, Citations +@comment node-name, next, previous, up +@cindex citation string +@comment +@section Citation Elements +@ifinfo + +@end ifinfo +@dfn{Citation strings} are composed of one or more elements. Non-nested +citations are composed of four elements, three of which are directly +user definable. The elements are concatenated together, in this order: + +@cindex citation leader +@vindex citation-leader (sc-) +@vindex sc-citation-leader +@enumerate +@item +The @dfn{citation leader}. The citation leader is contained in the +variable @code{sc-citation-leader}, and has the default value of a +string containing four spaces. + +@cindex attribution string +@item +The @dfn{attribution string}. This element is supplied automatically by +Supercite, based on your preferences and the original message's mail +headers, though you may be asked to confirm Supercite's choice. +@xref{Selecting an Attribution}, for more details.@refill + +@cindex citation delimiter +@vindex sc-citation-delimiter +@vindex citation-delimiter (sc-) +@item +The @dfn{citation delimiter}. This string, contained in the variable +@code{sc-citation-delimiter} visually separates the citation from the +text of the line. This variable has a default value of @code{">"} and +for best results, the string should consist of only a single character. + +@cindex citation separator +@vindex citation-separator (sc-) +@vindex sc-citation-separator +@item +The @dfn{citation separator}. The citation separator is contained in +the variable @code{sc-citation-separator}, and has the default value of +a string containing a single space. +@end enumerate + +For example, suppose you were using the default values for the above +variables, and Supercite provided the attribution string @samp{Jane}. +In this case, the composed, non-nested citation string used might be +something like +@code{@asis{" Jane> "}}. +This citation string will be inserted in front of +every line in the original message that is not already cited.@refill + +Nested citations, being simpler than non-nested citations, are composed +of the same elements, sans the attribution string. Supercite is smart +enough to not put additional spaces between citation delimiters for +multi-level nested citations. + +@node Recognizing Citations, Getting Connected, Citation Elements, Citations +@comment node-name, next, previous, up +@section Recognizing Citations +@ifinfo + +@end ifinfo +Supercite also recognizes citations in the original article, and can +transform these already cited lines in a number of ways. This is how +Supercite suppresses the multiple citing of non-nested citations. +Recognition of cited lines is controlled by variables analogous to those +that make up the citation string as mentioned previously. + +@vindex sc-citation-leader-regexp +@vindex citation-leader-regexp (sc-) +@vindex sc-citation-delimiter-regexp +@vindex citation-delimiter-regexp (sc-) +@vindex sc-citation-separator-regexp +@vindex citation-separator-regexp (sc-) +@vindex sc-citation-root-regexp +@vindex citation-root-regexp (sc-) +@vindex sc-citation-nonnested-root-regexp +@vindex citation-nonnested-root-regexp (sc-) + +The variable @code{sc-citation-leader-regexp} describes how citation +leaders can look, by default it matches any number of spaces or tabs. +Note that since the lisp function @code{looking-at} is used to do the +matching, if you change this variable it need not start with a leading +@code{"^"}. + +Similarly, the variables @code{sc-citation-delimiter-regexp} and +@code{sc-citation-separator-regexp} respectively describe how citation +delimiters and separators can look. They follow the same rule as +@code{sc-citation-leader-regexp} above. + +When Supercite composes a citation string, it provides the attribution +automatically. The analogous variable which handles recognition of the +attribution part of citation strings is @code{sc-citation-root-regexp}. +This variable describes the attribution root for both nested and +non-nested citations. By default it can match zero-to-many alphanumeric +characters (also ``.'', ``-'', and ``_''). But in some situations, +Supercite has to determine whether it is looking at a nested or +non-nested citation. Thus the variable +@code{sc-citation-nonnested-root-regexp} is used to describe only +non-nested citation roots. It is important to remember that if you +change @code{sc-citation-root-regexp} you should always also change +@code{sc-citation-nonnested-root-regexp}.@refill + +Nemacs users:@: For best results, try setting +@code{sc-citation-root-regexp} to:@refill + +@example +"\\([-._a-zA-Z0-9]\\|\\cc\\|\\cC\\|\\ch\\|\\cH\\|\\ck\\|\\cK\\|\\ca\\|\\cg\\|\\cr\\|\\cu\\)*" +@end example + +Mule users:@: For best results, try setting +@code{sc-citation-root-regexp} to:@refill + +@example +"\\([-._a-zA-Z0-9]\\|\\cj\\)*" +@end example + +@node Information Keys and the Info Alist, Reference Headers, Miscellaneous Commands, Top +@comment node-name, next, previous, up +@cindex information keys +@cindex Info Alist +@cindex information extracted from mail fields +@findex sc-mail-field +@findex mail-field (sc-) +@comment +@chapter Information Keys and the Info Alist +@ifinfo + +@end ifinfo +@dfn{Mail header information keys} are nuggets of information that +Supercite extracts from the various mail headers of the original +message, placed in the reply buffer by the MUA. Information is kept in +the @dfn{Info Alist} as key-value pairs, and can be retrieved for use in +various places within Supercite, such as in header rewrite functions and +attribution selection. Other bits of data, composed and created by +Supercite, are also kept as key-value pairs in this alist. In the case +of mail fields, the key is the name of the field, omitting the trailing +colon. Info keys are always case insensitive (as are mail headers), and +the value for a corresponding key can be retrieved from the alist with +the @code{sc-mail-field} function. Thus, if the following fields were +present in the original article:@refill + +@example +Date:@: 08 April 1991, 17:32:09 EST +Subject:@: Better get out your asbestos suit +@end example + +@vindex sc-mumble +@vindex mumble (sc-) +@noindent +then, the following lisp constructs return: + +@example +(sc-mail-field "date") +==> "08 April 1991, 17:32:09 EST" + +(sc-mail-field "subject") +==> "Better get out your asbestos suit" +@end example + +Since the argument to @code{sc-mail-field} can be any string, it is +possible that the mail field will not be present on the info alist +(possibly because the mail header was not present in the original +message). In this case, @code{sc-mail-field} will return the value of +the variable @code{sc-mumble}. + +Supercite always places all mail fields found in the yanked original +article into the info alist. If possible, Supercite will also places +the following keys into the info alist: + +@table @code +@cindex sc-attribution info field +@cindex attribution info field (sc-) +@item "sc-attribution" +the selected attribution string. + +@cindex sc-citation info field +@cindex citation info field (sc-) +@item "sc-citation" +the non-nested citation string. + +@cindex sc-from-address info field +@cindex from-address info field (sc-) +@item "sc-from-address" +email address extracted from the @samp{From:@:} field. + +@cindex sc-reply-address info field +@cindex reply-address info field (sc-) +@item "sc-reply-address" +email address extracted from the @samp{Reply-To:@:} field. + +@cindex sc-sender-address info field +@cindex sender-address info field (sc-) +@item "sc-sender-address" +email address extracted from the @samp{Sender:@:} field. + +@cindex sc-emailname info field +@cindex emailname info field (sc-) +@item "sc-emailname" +email terminus extracted from the @samp{From:@:} field. + +@cindex sc-initials info field +@cindex initials info field (sc-) +@item "sc-initials" +the author's initials. + +@cindex sc-author info field +@cindex author info field (sc-) +@item "sc-author" +the author's full name. + +@cindex sc-firstname info field +@cindex firstname info field (sc-) +@item "sc-firstname" +the author's first name. + +@cindex sc-lastname info field +@cindex lastname info field (sc-) +@item "sc-lastname" +the author's last name. + +@cindex sc-middlename-1 info field +@cindex middlename-1 info field (sc-) +@item "sc-middlename-1" +the author's first middle name. +@end table + +If the author's name has more than one middle name, they will appear as +info keys with the appropriate index (e.g., @code{"sc-middlename-2"}, +@dots{}). @xref{Selecting an Attribution}.@refill + +@node Reference Headers, The Built-in Header Rewrite Functions, Information Keys and the Info Alist, Top +@comment node-name, next, previous, up +@cindex reference headers +@chapter Reference Headers +@ifinfo + +@end ifinfo +Supercite will insert an informative @dfn{reference header} at the +beginning of the cited body of text, which display more detail about the +original article and provides the mapping between the attribution and +the original author in non-nested citations. Whereas the citation +string usually only contains a portion of the original author's name, +the reference header can contain such information as the author's full +name, email address, the original article's subject, etc. In fact any +information contained in the info alist can be inserted into a reference +header. + +@ifinfo +@menu +* The Built-in Header Rewrite Functions:: +* Electric References:: +@end menu +@end ifinfo + +@cindex header rewrite functions +@vindex sc-rewrite-header-list +@vindex rewrite-header-list (sc-) +There are a number of built-in @dfn{header rewrite functions} supplied +by Supercite, but you can write your own custom header rewrite functions +(perhaps using the built-in ones as examples). The variable +@code{sc-rewrite-header-list} contains the list of such header rewrite +functions. This list is consulted both when inserting the initial +reference header, and when displaying @dfn{electric references}. +@xref{Electric References}. + +@vindex sc-preferred-header-style +@vindex preferred-header-style (sc-) +When Supercite is initially run on a reply buffer (via +@code{sc-cite-original}), it will automatically call one of these +functions. The one it uses is defined in the variable +@code{sc-preferred-header-style}. The value of this variable is an +integer which is an index into the @code{sc-rewrite-header-list}, +beginning at zero. + +@node The Built-in Header Rewrite Functions, Electric References, Reference Headers, Reference Headers +@comment node-name, next, previous, up +@cindex header rewrite functions, built-in +@comment +@section The Built-in Header Rewrite Functions +@ifinfo + +@end ifinfo +Below are examples of the various built-in header rewrite functions. +Please note the following:@: first, the text which appears in the +examples below as @var{infokey} indicates that the corresponding value +of the info key from the info alist will be inserted there. +(@pxref{Information Keys and the Info Alist}). For example, in @code{sc-header-on-said} +below, @var{date} and @var{from} correspond to the values of the +@samp{Date:@:} and @samp{From:@:} mail headers respectively.@refill + +@vindex sc-reference-tag-string +@vindex reference-tag-string (sc-) +Also, the string @code{">>>>>"} below is really the value of the +variable @code{sc-reference-tag-string}. This variable is used in all +built-in header rewrite functions, and you can customize its value to +change the tag string globally. + +Finally, the references headers actually written may omit certain parts +of the header if the info key associated with @var{infokey} is not +present in the info alist. In fact, for all built-in headers, if the +@samp{From:@:} field is not present in the mail headers, the entire +reference header will be omitted (but this usually signals a serious +problem either in your MUA or in Supercite's installation). + +@table @code +@findex sc-no-header +@findex no-header (sc-) +@item sc-no-header +This function produces no header. It should be used instead of +@code{nil} to produce a blank header. This header can possibly contain +a blank line after the @code{mail-header-separator} line. + +@item sc-no-blank-line-or-header +@findex sc-no-blank-line-or-header +@findex no-blank-line-or-header (sc-) +This function is similar to @code{sc-no-header} except that any blank +line after the @code{mail-header-separator} line will be removed. + +@item sc-header-on-said +@findex sc-header-on-said +@findex header-on-said (sc-) +@code{>>>>> On @var{date}, @var{from} said:} + +@item sc-header-inarticle-writes +@findex sc-header-inarticle-writes +@findex header-inarticle-writes (sc-) +@code{>>>>> In article @var{message-id}, @var{from} writes:} + +@item sc-header-regarding-adds +@findex sc-header-regarding-adds +@findex header-regarding-adds (sc-) +@code{>>>>> Regarding @var{subject}; @var{from} adds:} + +@item sc-header-attributed-writes +@findex sc-header-attributed-writes +@findex header-attributed-writes (sc-) +@code{>>>>> "@var{sc-attribution}" == @var{sc-author} <@var{sc-reply-address}> writes:} + +@item sc-header-author-writes +@findex sc-header-author-writes +@findex header-author-writes (sc-) +@code{>>>>> @var{sc-author} writes:} + +@item sc-header-verbose +@findex sc-header-verbose +@findex header-verbose (sc-) +@code{>>>>> On @var{date},}@* +@code{>>>>> @var{sc-author}}@* +@code{>>>>> from the organization of @var{organization}}@* +@code{>>>>> who can be reached at:@: @var{sc-reply-address}}@* +@code{>>>>> (whose comments are cited below with:@: "@var{sc-cite}")}@* +@code{>>>>> had this to say in article @var{message-id}}@* +@code{>>>>> in newsgroups @var{newsgroups}}@* +@code{>>>>> concerning the subject of @var{subject}}@* +@code{>>>>> see @var{references} for more details} +@end table + +@node Electric References, Hints to MUA Authors, The Built-in Header Rewrite Functions, Reference Headers +@comment node-name, next, previous, up +@cindex electric references +@section Electric References +@ifinfo + +@end ifinfo +By default, when Supercite cites the original message for the first +time, it just goes ahead and inserts the reference header indexed by +@code{sc-preferred-header-style}. However, you may want to select +different reference headers based on the type of reply or forwarding you +are doing. You may also want to preview the reference header before +deciding whether to insert it into the reply buffer or not. Supercite +provides an optional @dfn{electric reference} mode which you can drop +into to give you this functionality. + +@vindex sc-electric-references-p +@vindex electric-references-p (sc-) +If the variable @code{sc-electric-references-p} is non-@code{nil}, +Supercite will bring up an electric reference mode buffer and place you +into a recursive edit. The electric reference buffer is read-only, so +you cannot directly modify the reference text until you exit electric +references and insert the text into the reply buffer. But you can cycle +through all the reference header rewrite functions in your +@code{sc-rewrite-header-list}. + +You can also set a new preferred header style, jump to any header, or +jump to the preferred header. The header will be shown in the electric +reference buffer and the header index and function name will appear in +the echo area. + +The following commands are available while in electric reference mode +(shown here with their default key bindings): + +@table @asis +@item @code{sc-eref-next} (@kbd{n}) +@findex sc-eref-next +@findex eref-next (sc-) +@kindex n +@vindex sc-electric-circular-p +@vindex electric-circular-p (sc-) +Displays the next reference header in the electric reference buffer. If +the variable @code{sc-electric-circular-p} is non-@code{nil}, invoking +@code{sc-eref-next} while viewing the last reference header in the list +will wrap around to the first header.@refill + +@item @code{sc-eref-prev} (@kbd{p}) +@findex sc-eref-prev +@findex eref-prev (sc-) +@kindex p +Displays the previous reference header in the electric reference buffer. +If the variable @code{sc-electric-circular-p} is non-@code{nil}, +invoking @code{sc-eref-prev} will wrap around to the last header.@refill + +@item @code{sc-eref-goto} (@kbd{g}) +@findex sc-eref-goto +@findex eref-goto (sc-) +@kindex g +Goes to a specified reference header. The index (into the +@code{sc-rewrite-header-list}) can be specified as a numeric argument to +the command. Otherwise, Supercite will query you for the index in the +minibuffer.@refill + +@item @code{sc-eref-jump} (@kbd{j}) +@findex sc-eref-jump +@findex eref-jump (sc-) +@kindex j +Display the preferred reference header, i.e., the one indexed by the current +value of @code{sc-preferred-header-style}. + +@item @code{sc-eref-setn} (@kbd{s}) +@findex sc-eref-setn +@findex eref-setn (sc-) +@kindex s +Set the preferred reference header (i.e., +@code{sc-preferred-header-style}) to the currently displayed header.@refill + +@item @code{sc-eref-exit} (@kbd{C-j}, @key{RET}, and @key{ESC C-c}) +@kindex RET +@kindex C-j +@kindex q +@findex sc-eref-exit +@findex eref-exit (sc-) +Exit from electric reference mode and insert the current header into the +reply buffer.@refill + +@item @code{sc-eref-abort} (@kbd{q}, @kbd{x}) +@findex sc-eref-abort +@findex eref-abort (sc-) +@kindex x +Exit from electric reference mode without inserting the current header. +@end table + +@vindex sc-electric-mode-hook +@vindex electric-mode-hook (sc-) +@noindent +Supercite will execute the hook @code{sc-electric-mode-hook} before +entering electric reference mode. + +@node Getting Connected, Emacs 19 MUAs, Recognizing Citations, Top +@comment node-name, next, previous, up +@cindex citation interface specification +@chapter Getting Connected +@ifinfo + +@end ifinfo +Hitting @kbd{C-c C-y} in your MUA's reply buffer yanks and cites the +original message into the reply buffer. In reality, the citation of the +original message is performed via a call through a configurable hook +variable. The name of this variable has been agreed to in advance as +part of the @dfn{citation interface specification}. By default this +hook variable has a @code{nil} value, which the MUA recognizes to mean, +``use your default citation function''. When you add Supercite's +citation function to the hook, thereby giving the variable a +non-@code{nil} value, it tells the MUA to run the hook via +@code{run-hooks} instead of using the default citation.@refill + +@ifinfo +@menu +* Emacs 19 MUAs:: +* Emacs 18 MUAs:: +* MH-E with any Emacsen:: +* VM with any Emacsen:: +* GNEWS with any Emacsen:: +* Overloading for Non-conforming MUAs:: +@end menu +@end ifinfo + +Early in Supercite's development, the Supercite author, a few MUA +authors, and some early Supercite users got together and agreed upon a +standard interface between MUAs and citation packages (of which +Supercite is currently the only known add-on @t{:-)}. With the recent +release of the Free Software Foundation's GNU Emacs 19, the interface +has undergone some modification and it is possible that not all MUAs +support the new interface yet. Some support only the old interface and +some do not support the interface at all. Still, it is possible for all +known MUAs to use Supercite, and the following sections will outline the +procedures you need to follow. + +To learn exactly how to connect Supercite to the software systems you +are using, read the appropriate following sections. For details on the +interface specifications, or if you are writing or maintaining an MUA, +@pxref{Hints to MUA Authors}. + +@cindex autoload +@cindex .emacs file +@findex sc-cite-original +@findex cite-original (sc-) +@findex sc-submit-bug-report +@findex submit-bug-report (sc-) +The first thing that everyone should do, regardless of the MUA you are +using is to set up Emacs so it will load Supercite at the appropriate +time. You can either dump Supercite into your Emacs binary (ask your +local Emacs guru how to do this if you don't know), or you can set up an +@dfn{autoload} for Supercite. To do the latter, put the following in +your @file{.emacs} file: + +@example +(autoload 'sc-cite-original "supercite" "Supercite 3.1" t) +(autoload 'sc-submit-bug-report "supercite" "Supercite 3.1" t) +@end example + +@cindex point +@cindex mark +The function @code{sc-cite-original} is the top-level Supercite function +designed to be run from the citation hook. It expects +@samp{point} and @samp{mark} to be set around the region to cite, and it +expects the original article's mail headers to be present within this +region. Note that Supercite @emph{never} touches any text outside this +region. Note further that for Emacs 19, the region need not be active +for @code{sc-cite-original} to do its job. +@xref{Hints to MUA Authors}.@refill + +The other step in the getting connected process is to make sure your +MUA calls @code{sc-cite-original} at the right time. As mentioned +above, some MUAs handle this differently. Read the sections that follow +pertaining to the MUAs you are using. + +@vindex sc-load-hook +@vindex load-hook (sc-) +@vindex sc-pre-hook +@vindex pre-hook (sc-) +One final note. After Supercite is loaded into your Emacs session, it +runs the hook @code{sc-load-hook}. You can put any customizations into +this hook since it is only run once. This will not work, however, if +your Emacs maintainer has put Supercite into your dumped Emacs' image. +In that case, you can use the @code{sc-pre-hook} variable, but this will +get executed every time @code{sc-cite-original} is called. @xref{Reply +Buffer Initialization}.@refill + +@node Emacs 19 MUAs, Emacs 18 MUAs, Getting Connected, Getting Connected +@comment node-name, next, previous, up +@vindex mail-citation-hook +@cindex .emacs file +@section GNUS, RMAIL, or RNEWS with any Emacs 19 +@ifinfo + +@end ifinfo +These MUAs, distributed with Emacs and with Lucid Emacs, use Emacs's +built-in yanking facility, which provides the citing hook variable +@code{mail-citation-hook}. By default, this hook's value is @code{nil}, +but by adding the following to your @file{.emacs} file, you can tell +these MUAs to use Supercite to perform the citing of the original +message: + +@example +(add-hook 'mail-citation-hook 'sc-cite-original) +@end example + +GNUS users may also want to add the following bit of lisp as well. This +prevents GNUS from inserting its default attribution header. Otherwise, +both GNUS and Supercite will insert an attribution header: + +@example +(setq news-reply-header-hook nil) +@end example + +@node Emacs 18 MUAs, MH-E with any Emacsen, Emacs 19 MUAs, Getting Connected +@comment node-name, next, previous, up +@vindex mail-citation-hook +@cindex .emacs file +@cindex overloading +@cindex sendmail.el file +@section GNUS, RMAIL, PCMAIL, RNEWS with Emacs 18 or Epoch 4 +@ifinfo + +@end ifinfo +These MUAs use Emacs' built-in yanking and citing routines, contained in +the @file{sendmail.el} file. @file{sendmail.el} for Emacs 18, and its +derivative Epoch 4, do not know anything about the citation interface +required by Supercite. To connect Supercite to any of these MUAs under +Emacs 18 or Epoch 4, you should first +@pxref{Overloading for Non-conforming MUAs}. Then follow the directions +for using these MUAs under Emacs 19. +@xref{Emacs 19 MUAs}.@refill + +@cindex add-hook substitute +@cindex setq as a substitute for add-hook +@findex setq +@findex add-hook +@cindex sc-unsupp.el file +Note that those instructions will tell you to use the function +@code{add-hook}. This function is new with Emacs 19 and you will not +have it by default if you are running Emacs 18 or Epoch 4. You can +either substitute the appropriate call to @code{setq}, or you can use +the @code{add-hook} function that is provided in the @file{sc-unsupp.el} +file of unsupported Supercite hacks and ideas. Or you can upgrade to +some Emacs 19 variant! @t{:-)}@refill + +To use @code{setq} instead of @code{add-hook}, you would, for example, +change this: + +@example +(add-hook 'mail-citation-hook 'sc-cite-original) +@end example + +to: + +@example +(setq mail-citation-hook 'sc-cite-original) +@end example + +Note the lack of of a single quote on the first argument to @code{setq}. + +@node MH-E with any Emacsen, VM with any Emacsen, Emacs 18 MUAs, Getting Connected +@comment node-name, next, previous, up +@cindex .emacs file +@vindex mh-yank-hooks +@findex add-hook +@cindex mail-citation-hook +@section MH-E with any Emacsen +@ifinfo + +@end ifinfo +MH-E 4.x conforms to the @code{mail-citation-hook} interface supported +by other MUAs. At the time of this writing, MH-E 4.0 has not been +released, but if you have it, put this in your @file{.emacs} file to +connect Supercite and MH-E 4.x: + +@example +(add-hook 'mail-citation-hook 'sc-cite-original) +@end example + +Note that if you are using Emacs 18 or Epoch 4, you will not have the +@code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to +proceed without @code{add-hook}. + +MH-E version 3.x uses a slightly different interface than other MUAs. +MH-E provides a hook variable @code{mh-yank-hooks}, but it doesn't act +like a hook, and doing an @code{add-hook} will not work. + +To connect Supercite to MH-E 3.x, you should instead add the following +to your @code{.emacs} file: + +@example +(add-hook 'mh-yank-hooks 'sc-cite-original) +@end example + +@vindex mh-yank-from-start-of-msg +You also need to make sure that MH-E includes all the original mail +headers in the yanked message. The variable that controls this is +@code{mh-yank-from-start-of-msg}. By default, this variable has the +value @code{t}, which tells MH-E to include all the mail headers when +yanking the original message. Before you switched to using Supercite, +you may have set this variable to other values so as not to include the +mail headers in the yanked message. Since Supercite requires these +headers (and cleans them out for you), you need to make sure the value +is @code{t}. This lisp, in your @file{.emacs} file will do the trick: + +@example +(setq mh-yank-from-start-of-msg t) +@end example + +Note that versions of MH-E before 3.7 did not provide the +@code{mh-yank-hooks} variable. Your only option is to upgrade to MH-E +version 3.7 or later. + +@node VM with any Emacsen, GNEWS with any Emacsen, MH-E with any Emacsen, Getting Connected +@comment node-name, next, previous, up +@cindex .emacs file +@vindex mail-citation-hook +@vindex mail-yank-hooks +@section VM with any Emacsen +@ifinfo + +@end ifinfo +Since release 4.40, VM has supported the citation interface required by +Supercite. But since the interface has changed recently the details of +getting connected differ with the version of VM you are using. + +If you are running any release of VM after 4.40, you can add the +following to your @file{.emacs} to connect Supercite with VM: + +@example +(add-hook 'mail-yank-hooks 'sc-cite-original) +@end example + +Note that if you are using Emacs 18 or Epoch 4, you will not have the +@code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to +proceed without @code{add-hook}. + +Since version 5.34, VM has supported the newer @code{mail-citation-hook} +interface, but @code{mail-yank-hooks} is still being supported for +backward compatibility. If you are running a newer version of VM and +you want to maintain consistency with other MUAs, use this bit of code +instead: + +@example +(add-hook 'mail-citation-hook 'sc-cite-original) +@end example + +@node GNEWS with any Emacsen, Overloading for Non-conforming MUAs, VM with any Emacsen, Getting Connected +@comment node-name, next, previous, up@cindex .emacs file +@vindex news-reply-mode-hook +@findex sc-perform-overloads +@findex perform-overloads (sc-) +@vindex gnews-ready-hook +@section GNEWS with any Emacsen +@ifinfo + +@end ifinfo +As far as I know, no version of GNEWS supports the citation interface +required by Supercite. To connect Supercite with GNEWS, please first +@pxref{Overloading for Non-conforming MUAs}. + +After you have followed the directions in that section. You should add +the following lisp code to your @file{.emacs} file: + +@example +(add-hook 'mail-citation-hook 'sc-cite-original) +@end example + +Note that if you are using Emacs 18 or Epoch 4, you will not have the +@code{add-hook} function. @xref{Emacs 18 MUAs}, for details on how to +proceed without @code{add-hook}. + +@node Overloading for Non-conforming MUAs, Replying and Yanking, GNEWS with any Emacsen, Getting Connected +@comment node-name, next, previous, up +@cindex overloading +@cindex sc-oloads.el +@vindex mail-citation-hook +@findex sc-perform-overloads +@cindex .emacs file +@section Overloading for Non-conforming MUAs +@ifinfo + +@end ifinfo +As mentioned elsewhere, some MUAs do not provide the necessary hooks to +connect with Supercite. Supercite version 3.1 provides an unsupported +mechanism, called @dfn{overloading} which redefines certain key +functions in the MUA, so that it will call the @code{mail-citation-hook} +variable instead of the MUA's default hard-coded citing routines. Since +most newer versions of the known MUAs support the +@code{mail-citation-hook} variable, it is recommended that you upgrade +if at all possible. But if you can't upgrade, at least you're not out +of luck! Once you set up overloading properly, you should follow the +directions for connecting Supercite to the Emacs 19 MUAs. +@xref{Emacs 19 MUAs}.@refill + +@cindex Hyperbole +@vindex hyperb:version +Users of Bob Weiner's Hyperbole package take note. Hyperbole provides +the necessary overloads (and a whole lot more!) and you can potentially +clobber it if you were to load Supercite's overloading after +Hyperbole's. For this reason, Supercite will @emph{not} perform any +overloading if it finds the variable @code{hyperb:version} is +@code{boundp} (i.e. it exists because Hyperbole has been loaded into +your Emacs session). If this is the case, Supercite will display a +warning message in the minibuffer. You should consult the Hyperbole +manual for further details. + +Overloading involves the re-definition of the citing function with the +new, @code{mail-citation-hook} savvy version. The function in +@file{sc-oloads.el} that does this is @code{sc-perform-overloads}. This +function is smart enough to only overload the MUA functions when it is +absolutely necessary, based on the version numbers it can figure out. +Also, @code{sc-perform-overloads} will only install the new functions +once. It is also smart enough to do nothing if the MUA is not yet +loaded.@refill + +The tricky part is finding the right time and place to perform the +overloading. It must be done after the MUA has been loaded into your +Emacs session, but before the first time you try to yank in a message. +Fortunately, this has been figured out for you. + +If you must overload, you should put the following lisp code in your +@file{.emacs} file, to make sure the @file{sc-oloads.el} file gets +loaded at the right time: + +@example +(autoload 'sc-perform-overloads "sc-oloads" "Supercite 3.1" t) +@end example + +Then you must make sure that the function @code{sc-perform-overloads} +gets run at the right time. For GNUS, put this in your @file{.emacs} +file: + +@example +(setq news-reply-mode-hook 'sc-perform-overloads) +(setq mail-setup-hook 'sc-perform-overloads) +@end example + +If you are using RNEWS, put this in your @file{.emacs} file: + +@vindex news-reply-mode-hook +@example +(setq news-reply-mode-hook 'sc-perform-overloads) +@end example + +If you are using RMAIL or PCMAIL, put this in your @file{.emacs} file: + +@example +(setq mail-setup-hook 'sc-perform-overloads) +@end example + +If you are using GNEWS, put this in your @file{.emacs} file: + +@example +(setq news-reply-mode-hook 'sc-perform-overloads) +(setq gnews-ready-hook 'sc-perform-overloads) +@end example + +Now go back and follow the directions for getting the Emacs 19 MUAs +connected to Supercite. Be sure to @pxref{Emacs 18 MUAs} on substitutes +for Emacs 19's @code{add-hook} function.@refill + +@node Replying and Yanking, Reply Buffer Initialization, Overloading for Non-conforming MUAs, Top +@comment node-name, next, previous, up +@chapter Replying and Yanking +@ifinfo + +This chapter explains what happens when you reply and yank an original +message from an MUA. + +@menu +* Reply Buffer Initialization:: +* Filling Cited Text:: +@end menu +@end ifinfo +@node Reply Buffer Initialization, Filling Cited Text, Replying and Yanking, Replying and Yanking +@comment node-name, next, previous, up +@findex sc-cite-original +@findex cite-original (sc-) +@comment +@section Reply Buffer Initialization +@ifinfo + +@end ifinfo +Executing @code{sc-cite-original} performs the following steps as it +initializes the reply buffer: + +@enumerate +@item +@vindex sc-pre-hook +@vindex pre-hook (sc-) +@emph{Runs @code{sc-pre-hook}.} +This hook variable is run before @code{sc-cite-original} does any other +work. You could conceivably use this hook to set certain Supercite +variables based on the reply buffer's mode or name (i.e., to do +something different based on whether you are replying or following up to +an article).@refill + +@item +@emph{Inserts Supercite's keymap.} +@vindex sc-mode-map-prefix +@vindex mode-map-prefix (sc-) +@kindex C-c C-p +@cindex keymap prefix +Supercite provides a number of commands for performing post-yank +modifications to the reply buffer. These commands are installed on +Supercite's top-level keymap. Since Supercite has to interface with a +wide variety of MUAs, it does not install all of its commands directly +into the reply buffer's keymap. Instead, it puts its commands on a +keymap prefix, then installs this prefix onto the buffer's keymap. What +this means is that you typically have to type more characters to invoke +a Supercite command, but Supercite's keybindings can be made much more +consistent across MUAs. + +You can control what key Supercite uses as its keymap prefix by changing +the variable @code{sc-mode-map-prefix}. By default, this variable is +set to @code{C-c C-p}; a finger twister perhaps, but unfortunately the +best default due to the scarcity of available keybindings in many MUAs. + +@item +@emph{Turns on Supercite minor mode.} +@cindex modeline +The modeline of the reply buffer should indicate that Supercite is +active in that buffer by displaying the string @samp{SC}. + +@item +@emph{Sets the ``Undo Boundary''.} +@cindex undo boundary +Supercite sets an undo boundary before it begins to modify the original +yanked text. This allows you to easily undo Supercite's changes to +affect alternative citing styles. + +@item +@emph{Processes the mail headers.} +@vindex sc-confirm-always-p +@vindex confirm-always-p (sc-) +@vindex sc-mail-warn-if-non-rfc822-p +@vindex mail-warn-if-non-rfc822-p (sc-) +All previously retrieved info key-value pairs are deleted from the info +alist, then the mail headers in the body of the yanked message are +scanned. Info key-value pairs are created for each header found. Also, +such useful information as the author's name and email address are +extracted. If the variable @code{sc-mail-warn-if-non-rfc822-p} is +non-@code{nil}, then Supercite will warn you if it finds a mail header +that does not conform to RFC822. This is rare and indicates a problem +either with your MUA or the original author's MUA, or some MTA (mail +transport agent) along the way. + +@vindex sc-nuke-mail-headers +@vindex sc-nuke-mail-header-list +@vindex nuke-mail-headers (sc-) +@vindex nuke-mail-header-list (sc-) +Once the info keys have been extracted from the mail headers, the +headers are nuked from the reply buffer. You can control exactly which +headers are removed or kept, but by default, all headers are removed. + +There are two variables which control mail header nuking. The variable +@code{sc-nuke-mail-headers} controls the overall behavior of the header +nuking routines. By setting this variable to @code{'all}, you +automatically nuke all mail headers. Likewise, setting this variable to +@code{'none} inhibits nuking of any mail headers. In between these +extremes, you can tell Supercite to nuke only a specified list of mail +headers by setting this variable to @code{'specified}, or to keep only a +specified list of headers by setting it to @code{'keep}. + +If @code{sc-nuke-mail-headers} is set to @code{'specified} or +@code{'keep}, then the variable @code{sc-nuke-mail-header-list} is +consulted for the list of headers to nuke or keep. This variable +contains a list of regular expressions. If the mail header line matches +a regular expression in this list, the header will be nuked or kept. +The line is matched against the regexp using @code{looking-at} rooted at +the beginning of the line. + +@vindex sc-blank-lines-after-headers +@vindex blank-lines-after-headers (sc-) +If the variable @code{sc-blank-lines-after-headers} is non-@code{nil}, +it contains the number of blank lines remaining in the buffer after mail +headers are nuked. By default, only one blank line is left in the buffer. + +@item +@emph{Selects the attribution and citation strings.} +Once the mail headers have been processed, Supercite selects a +attribution string and a citation string which it will use to cite the +original message. @xref{Selecting an Attribution}, for details. + +@item +@emph{Cites the message body.} +@vindex sc-cite-region-limit +@vindex cite-region-limit (sc-)b +After the selection of the attribution and citation strings, Supercite +cites the original message by inserting the citation string prefix in +front of every uncited line. You may not want Supercite to +automatically cite very long messages however. For example, some email +could contain a smaller header section followed by a huge uuencoded +message. It wouldn't make sense to cite the uuencoded message part when +responding to the original author's short preface. For this reason, +Supercite provides a variable which limits the automatic citation of +long messages to a certain maximum number of lines. The variable is +called @code{sc-cite-region-limit}. If this variable contains an +integer, messages with more lines that this will not be cited at all, +and a warning message will be displayed. Supercite has performed +everything necessary, though, for you to manually cite only the small +portion of the original message that you want to use. + +If @code{sc-cite-region-limit} contains a non-@code{nil} value, the +original message will always be cited, regardless of its size. If the +variable contains the value @code{nil}, the region will never be cited +automatically. Use this if you always want to be able to edit and cite +the message manually. + +@vindex sc-cite-blank-lines-p +@vindex cite-blank-lines-p (sc-) +The variable @code{sc-cite-blank-lines-p} controls whether blank lines +in the original message should be cited or not. If this variable is +non-@code{nil}, blank lines will be cited just like non-blank lines. +Otherwise, blank lines will be treated as paragraph separators. + +Citing of the original message is highly configurable. Supercite's +default setup does a pretty good job of citing many common forms of +previously cited messages. But there are as many citation styles out +there as people on the net, or just about! It would be impossible for +Supercite to anticipate every style in existence, and you probably +wouldn't encounter them all anyway. But you can configure Supercite to +recognize those styles you see often. +@xref{Configuring the Citation Engine}, for details.@refill + +@item +@emph{Runs @code{sc-post-hook}.} +@vindex sc-post-hook +@vindex post-hook (sc-) +This variable is very similar to @code{sc-pre-hook}, except that it runs +after @code{sc-cite-original} is finished. This hook is provided mostly +for completeness and backward compatibility. Perhaps it could be used to +reset certain variables set in @code{sc-pre-hook}.@refill +@end enumerate + +@node Filling Cited Text, Selecting an Attribution, Reply Buffer Initialization, Replying and Yanking +@comment node-name, next, previous, up +@cindex filling paragraphs +@vindex sc-auto-fill-region-p +@vindex auto-fill-region-p (sc-) +@cindex filladapt +@cindex gin-mode +@findex sc-setup-filladapt +@findex setup-filladapt (sc-) +@vindex sc-load-hook +@vindex load-hook (sc-) +@section Filling Cited Text +@ifinfo + +@end ifinfo +Supercite will automatically fill newly cited text from the original +message unless the variable @code{sc-auto-fill-region-p} has a +@code{nil} value. Supercite will also re-fill paragraphs when you +manually cite or re-cite text. + +However, during normal editing, Supercite itself cannot be used to fill +paragraphs. This is a change from version 2. There are other add-on +lisp packages which do filling much better than Supercite ever did. The +two best known are @dfn{filladapt} and @dfn{gin-mode}. Both work well +with Supercite and both are available at the normal Emacs Lisp archive +sites. @dfn{gin-mode} works pretty well out of the box, but if you use +@dfn{filladapt}, you may want to run the function +@code{sc-setup-filladapt} from your @code{sc-load-hook}. This simply +makes @dfn{filladapt} a little more Supercite savvy than its default +setup. + +@vindex sc-fixup-whitespace-p +@vindex fixup-whitespace-p (sc-) +Also, Supercite will collapse leading whitespace between the citation +string and the text on a line when the variable +@code{sc-fixup-whitespace-p} is non-@code{nil}. The default value for +this variable is @code{nil}.@refill + +@vindex fill-prefix +Its important to understand that Supercite's automatic filling (during +the initial citation of the reply) is very fragile. That is because +figuring out the @code{fill-prefix} for a particular paragraph is a +really hard thing to do automatically. This is especially the case when +the original message contains code or some other text where leading +whitespace is important to preserve. For this reason, many Supercite +users typically run with @code{sc-auto-fill-region-p} (and possibly also +@code{sc-fixup-whitespace-p}) set to @code{nil}. They then manually +fill each cited paragraph in the reply buffer. + +I usually run with both these variables containing their default values. +When Supercite's automatic filling breaks on a particular message, I +will use Emacs' undo feature to undo back before the citation was +applied to the original message. Then I'll toggle the variables and +manually cite those paragraphs that I don't want to fill or collapse +whitespace on. @xref{Variable Toggling Shortcuts}.@refill + +@kindex C-c C-p C-p +If you find that Supercite's automatic filling is just too fragile for +your tastes, you might consider one of these alternate approaches. +Also, to make life easier, a shortcut function to toggle the state of +both of these variables is provided on the key binding +@kbd{C-c C-p C-p} (with the default value of @code{sc-mode-map-prefix}; +@pxref{Post-yank Formatting Commands}).@refill + +You will noticed that the minor mode string will +show the state of these variables as qualifier characters. When both +variables are @code{nil}, the Supercite minor mode string will display +@samp{SC}. When just @code{sc-auto-fill-region-p} is non-@code{nil}, the +string will display @samp{SC:f}, and when just +@code{sc-fixup-whitespace-p} is non-@code{nil}, the string will display +@samp{SC:w}. When both variables are non-@code{nil}, the string will +display @samp{SC:fw}. Note that the qualifiers chosen are mnemonics for +the default bindings of the toggling function for each respective +variable. +@xref{Variable Toggling Shortcuts}.@refill + +Why are these variables not set to @code{nil} by default? It is because +many users won't manually fill paragraphs that are Supercited, and there +have been widespread complaints on the net about mail and news messages +containing lines greater than about 72 characters. So the default is to +fill cited text. + +@node Selecting an Attribution, Attribution Preferences, Filling Cited Text, Top +@comment node-name, next, previous, up +@cindex attribution list +@vindex sc-preferred-attribution-list +@vindex preferred-attribution-list (sc-) +@comment +@chapter Selecting an Attribution +@ifinfo + +@end ifinfo +As you know, the attribution string is the part of the author's name +that will be used to composed a non-nested citation string. Supercite +scans the various mail headers present in the original article and uses +a number of heuristics to extract strings which it puts into the +@dfn{attribution association list} or @dfn{attribution alist}. This is +analogous, but different than, the info alist previously mentioned. Each +element in the attribution alist is a key-value pair containing such +information as the author's first name, middle names, and last name, the +author's initials, and the author's email terminus. + +@ifinfo +@menu +* Attribution Preferences:: +* Anonymous Attributions:: +* Author Names:: +@end menu +@end ifinfo + +@node Attribution Preferences, Anonymous Attributions, Selecting an Attribution, Selecting an Attribution +@comment node-name, next, previous, up +@section Attribution Preferences +@ifinfo + +@end ifinfo +When you cite an original message, you can tell Supercite which part of +the author's name you would prefer it to use as the attribution. The +variable @code{sc-preferred-attribution-list} controls this; it contains +keys which are matched against the attribution alist in the given order. +The first value of a key that produces a non-@code{nil}, non-empty +string match is used as the attribution string, and if no keys match, a +secondary mechanism is used to generate the attribution. +@xref{Anonymous Attributions}. + +The following preferences are always available in the attribution alist +(barring error): + +@table @code +@item "emailname" +the author's email terminus. + +@item "initials" +the author's initials. + +@item "firstname" +the author's first name. + +@item "lastname" +the author's last name. + +@item "middlename-1" +the author's first middle name. + +@item "sc-lastchoice" +the last attribution string you have selected. This is useful when you +recite paragraphs in the reply.@refill + +@item "sc-consult" +@vindex sc-attrib-selection-list +@vindex attrib-selection-list (sc-) +consults the customizable list @code{sc-attrib-selection-list} which can +be used to select special attributions based on the value of any info +key. See below for details. + +@item "x-attribution" +the original author's suggestion for attribution string choice. See below +for details.@refill +@end table + +Middle name indexes can be any positive integer greater than zero, +though it is unlikely that many authors will have more than one middle +name, if that many. + +At this point, let me digress into a discussion of etiquette. It is my +belief that while the style of the citations is a reflection of the +personal tastes of the replier (i.e., you), the attribution selection is +ultimately the personal choice of the original author. In a sense it is +his or her ``net nickname'', and therefore the author should have some +say in the selection of attribution string. Imagine how you would feel +if someone gave you a nickname that you didn't like? + +For this reason, Supercite recognizes a special mail header, +@samp{X-Attribution:}, which if present, tells Supercite the attribution +string preferred by the original author. It is the value of this header +that is associated with the @code{"x-attribution"} key in the +attribution alist. Currently, you can override the preference of this +key by changing @code{sc-preferred-attribution-list}, but that isn't +polite, and in the future Supercite may hard-code this. For now, it is +suggested that if you change the order of the keys in this list, that +@code{"x-attribution"} always be first, or possible second behind only +@code{"sc-lastchoice"}. This latter is the default. + +@vindex sc-attrib-selection-list +@vindex attrib-selection-list (sc-) +The value @code{"sc-consult"} in @code{sc-preferred-attribution-list} +has a special meaning during attribution selection. When Supercite +encounters this preference, it begins processing a customizable list of +attributions, contained in the variable @code{sc-attrib-selection-list}. +Each element in this list contains lists of the following form: + +@example +@group +(@var{infokey} ((@var{regexp} @. @var{attribution}) + (@var{regexp} @. @var{attribution}) + (@dots{}))) +@end group +@end example + +@noindent +@findex sc-mail-field +@findex mail-field (sc-) +where @var{infokey} is a key for @code{sc-mail-field} and @var{regexp} +is a regular expression to match against the @var{infokey}'s value. If +@var{regexp} matches the @var{infokey}'s value, the @var{attribution} is +used as the attribution string. Actually, @var{attribution} can be a +string or a list; if it is a list, it is @code{eval}uated and the return +value (which must be a string), is used as the attribution. + +This can be very useful for when you are replying to net acquaintances +who do not use the @samp{X-Attribution:@:} mail header. You may know +what nickname they would prefer to use, and you can set up this list to +match against a specific mail field, e.g., @samp{From:@:}, allowing you +to cite your friend's message with the appropriate attribution. + +@node Anonymous Attributions, Author Names, Attribution Preferences, Selecting an Attribution +@comment node-name, next, previous, up +@vindex sc-default-author-name +@vindex default-author-name (sc-) +@vindex sc-default-attribution +@vindex default-attribution (sc-) +@comment +@section Anonymous Attributions +@ifinfo + +@end ifinfo +When the author's name cannot be found in the @samp{From:@:} mail +header, a fallback author name and attribution string must be supplied. +The fallback author name is contained in the variable +@code{sc-default-author-name} and the fallback attribution string is +contained in the variable @code{sc-default-attribution}. Default values +for these variables are @code{"Anonymous"} and @code{"Anon"}, +respectively. Note that in most circumstances, getting the default +author name or attribution is a sign that something is set up +incorrectly. + +@vindex sc-use-only-preference-p +@vindex use-only-preference-p (sc-) +Also, if the preferred attribution, which you specified in your +@code{sc-preferred-attribution-alist} variable cannot be found, a +secondary method can be employed to find a valid attribution string. The +variable @code{sc-use-only-preference-p} controls what happens in this +case. If the variable's value is non-@code{nil}, then +@code{sc-default-author-name} and @code{sc-default-attribution} are +used, otherwise, the following steps are taken to find a valid +attribution string, and the first step to return a non-@code{nil}, +non-empty string becomes the attribution:@refill + +@enumerate +@item +Use the last selected attribution, if there is one. + +@item +Use the value of the @code{"x-attribution"} key. + +@item +Use the author's first name. + +@item +Use the author's last name. + +@item +Use the author's initials. + +@item +Find the first non-@code{nil}, non-empty attribution string in the +attribution alist. + +@item +@code{sc-default-attribution} is used. +@end enumerate + +@vindex sc-confirm-always-p +@vindex confirm-always-p (sc-) +Once the attribution string has been automatically selected, a number of +things can happen. If the variable @code{sc-confirm-always-p} is +non-@code{nil}, you are queried for confirmation of the chosen +attribution string. The possible values for completion are those strings +in the attribution alist, however you are not limited to these choices. +You can type any arbitrary string at the confirmation prompt. The string +you enter becomes the value associated with the @code{"sc-lastchoice"} +key in the attribution alist. + +@vindex sc-downcase-p +@vindex downcase-p (sc-) +Once an attribution string has been selected, Supercite will force the +string to lower case if the variable @code{sc-downcase-p} is +non-@code{nil}. + +@vindex sc-attribs-preselect-hook +@vindex attribs-preselect-hook (sc-) +@vindex sc-attribs-postselect-hook +@vindex attribs-postselect-hook (sc-) + +Two hook variables provide even greater control of the attribution +selection process. The hook @code{sc-attribs-preselect-hook} is run +before any attribution is selected. Likewise, the hook +@code{sc-attribs-postselect-hook} is run after the attribution is +selected (and the corresponding citation string is built), but before +these values are committed for use by Supercite. During the +post-selection hook, the local variables @code{attribution} and +@code{citation} are bound to the appropriate strings. By changing these +variables in your hook functions, you change the attribution and +citation strings used by Supercite. One possible use of this would be +to override any automatically derived attribution string when it is only +one character long; e.g. you prefer to use @code{"initials"} but the +author only has one name.@refill + +@node Author Names, Configuring the Citation Engine, Anonymous Attributions, Selecting an Attribution +@comment node-name, next, previous, up +@cindex author names +@section Author Names +@ifinfo + +@end ifinfo +Supercite employs a number of heuristics to decipher the author's name +based on value of the @samp{From:@:} mail field of the original message. +Supercite can recognize almost all of the common @samp{From:@:} field +formats in use. If you encounter a @samp{From:@:} field that Supercite +cannot parse, please report this bug. +@xref{The Supercite Mailing List}.@refill + +@vindex sc-titlecue-regexp +@vindex titlecue-regexp (sc-) +There are a number of Supercite variables that control how author names +are extracted from the @samp{From:@:} header. Some headers may contain a +descriptive title as in: + +@example +From:@: computer!speedy!doe (John Xavier-Doe -- Decent Hacker) +@end example + +Supercite knows which part of the @samp{From:@:} header is email address +and which part is author name, but in this case the string @code{"Decent +Hacker"} is not part of the author's name. You can tell Supercite to +ignore the title, while still recognizing hyphenated names through the +use of a regular expression in the variable @code{sc-titlecue-regexp}. +This variable has the default value of @code{"\\\\s +-+\\\\s +"}. Any +text after this regexp is encountered is ignored as noise. + +@vindex sc-name-filter-alist +@vindex name-filter-alist (sc-) +Some @samp{From:@:} headers may contain extra titles in the name fields +not separated by a title cue, but which are nonetheless not part of the +author's name proper. Examples include the titles ``Dr.'', ``Mr.'', +``Ms.'', ``Jr.'', ``Sr.'', and ``III'' (e.g., Thurston Howe, the Third). +Also, some companies prepend or append the name of the division, +organization, or project on the author's name. All of these titles are +noise which should be ignored. The variable @code{sc-name-filter-alist} +is used for this purpose. As implied by its name, this variable is an +association list, where each element is a cons cell of the form: + +@example +(@var{regexp} @. @var{position}) +@end example + +@noindent +where @var{regexp} is a regular expression that is matched (using +@code{string-match}) against each element of the @samp{From:@:} field's +author name. @var{position} is a position indicator, starting at zero. +Thus to strip out all titles of ``Dr.'', ``Mr.'', etc. from the name, +@code{sc-name-filter-alist} would have an entry such as: + +@example +("^\\(Mr\\|Mrs\\|Ms\\|Dr\\)[.]?$" @. 0) +@end example + +@noindent +which only removes them if they appear as the first word in the name. +The position indicator is an integer, or one of the two special symbols +@code{last} or @code{any}. @code{last} always matches against the last +word in the name field, while @code{any} matches against every word in +the name field. + +@node Configuring the Citation Engine, Using Regi, Author Names, Top +@comment node-name, next, previous, up +@cindex Regi +@cindex frames (Regi) +@cindex entries (Regi) +@chapter Configuring the Citation Engine +@ifinfo + +@end ifinfo +At the heart of Supercite is a regular expression interpreting engine +called @dfn{Regi}. Regi operates by interpreting a data structure +called a Regi-frame (or just @dfn{frame}), which is a list of +Regi-entries (or just @dfn{entry}). Each entry contains a predicate, +typically a regular expression, which is matched against a line of text +in the current buffer. If the predicate matches true, an associated +expression is @code{eval}uated. In this way, an entire region of text +can be transformed in an @emph{awk}-like manner. Regi is used +throughout Supercite, from mail header information extraction, to header +nuking, to citing text. + +@ifinfo +@menu +* Using Regi:: +* Frames You Can Customize:: +@end menu +@end ifinfo + +While the details of Regi are discussed below (@pxref{Using Regi}), only +those who wish to customize certain aspects of Supercite need concern +themselves with it. It is important to understand though, that any +conceivable citation style that can be described by a regular expression +can be recognized by Supercite. This leads to some interesting +applications. For example, if you regularly receive email from a +co-worker that uses an uncommon citation style (say one that employs a +@samp{|} or @samp{@}} character at the front of the line), it is +possible for Supercite to recognize this and @emph{coerce} the citation +to your preferred style, for consistency. In theory, it is possible for +Supercite to recognize such things as uuencoded messages or C code and +cite or fill those differently than normal text. None of this is +currently part of Supercite, but contributions are welcome! + +@node Using Regi, Frames You Can Customize, Configuring the Citation Engine, Configuring the Citation Engine +@comment node-name, next, previous, up +@findex regi-interpret +@findex eval +@findex looking-at +@section Using Regi +@ifinfo + +@end ifinfo +Regi works by interpreting frames with the function +@code{regi-interpret}. A frame is a list of arbitrary size where each +element is a entry of the following form: + +@example +(@var{pred} @var{func} [@var{negate-p} [@var{case-fold-search}]]) +@end example + +Regi starts with the first entry in a frame, evaluating the @var{pred} +of that entry against the beginning of the line that @samp{point} is on. +If the @var{pred} evaluates to true (or false if the optional +@var{negate-p} is non-@code{nil}), then the @var{func} for that entry is +@code{eval}uated. How processing continues is determined by the return +value for @var{func}, and is described below. If @var{pred} was false +the next entry in the frame is checked until all entries have been +matched against the current line. If no entry matches, @samp{point} is +moved forward one line and the frame is reset to the first entry. + +@var{pred} can be a string, a variable, a list or one of the following +symbols: @code{t}, @code{begin}, @code{end}, or @code{every}. If +@var{pred} is a string, or a variable or list that @code{eval}uates to a +string, it is interpreted as a regular expression. This regexp is +matched against the current line, from the beginning, using +@code{looking-at}. This match folds case if the optional +@var{case-fold-search} is non-@code{nil}. If @var{pred} is not a +string, or does not @code{eval}uate to a string, it is interpreted as a +binary value (@code{nil} or non-@code{nil}).@refill + +The four special symbol values for @var{pred} are recognized: + +@table @code +@item t +Always produces a true outcome. +@item begin +Always executed before the frame is interpreted. This can be used to +initialize some global variables for example. +@item end +Always executed after frame interpreting is completed. This can be used +to perform any necessary post-processing. +@item every +Executes whenever the frame is reset, usually after the entire frame has +been matched against the current line. +@end table + +Note that @var{negate-p} and @var{case-fold-search} are ignored if +@var{pred} is one of these special symbols. Only the first occurrence of +each symbol in a frame is used; any duplicates are ignored. Also +note that for performance reasons, the entries associated with these +symbols are removed from the frame during the main interpreting loop. + +Your @var{func} can return certain values which control continued Regi +processing. By default, if your @var{func} returns @code{nil} (as it +should be careful to do explicitly), Regi will reset the frame to the +first entry, and advance @samp{point} to the beginning of the next line. +If a list is returned from your function, it can contain any combination +of the following elements:@refill + +@table @asis +@item the symbol @code{continue} +This tells Regi to continue processing entries after a match, instead of +reseting the frame and moving @samp{point}. In this way, lines of text +can have multiple matches, but you have to be careful to avoid entering +infinite loops. + +@item the symbol @code{abort} +This tells Regi to terminate frame processing. However, any @code{end} +entry is still processed. + +@item the list @code{(frame . @var{newframe})} +This tells Regi to substitute @var{newframe} as the frame it is +interpreting. In other words, your @var{func} can modify the Regi frame +on the fly. @var{newframe} can be a variable containing a frame, or it +can be the frame in-lined.@refill + +@item the list @code{(step . @var{step})} +Tells Regi to move @var{step} number of lines forward as it continues +processing. By default, Regi moves forward one line. @var{step} can be +zero or negative of course, but watch out for infinite loops.@refill +@end table + +During execution of your @var{func}, the following variables will be +temporarily bound to some useful information:@refill + +@table @code +@item curline +The current line in the buffer that Regi is @code{looking-at}, as a string. +@item curframe +The current frame being interpreted. +@item curentry +The current frame entry being interpreted. +@end table + +@node Frames You Can Customize, Post-yank Formatting Commands, Using Regi, Configuring the Citation Engine +@comment node-name, next, previous, up +@vindex sc-nuke-mail-header +@section Frames You Can Customize +@ifinfo + +@end ifinfo +As mentioned earlier, Supercite uses various frames to perform +certain jobs such as mail header information extraction and mail header +nuking. However, these frames are not available for you to customize, +except through abstract interfaces such as @code{sc-nuke-mail-header}, +et al. + +@vindex sc-default-cite-frame +However, the citation frames Supercite uses provide a lot of customizing +power and are thus available to you to change to suit your needs. The +workhorse of citation is the frame contained in the variable +@code{sc-default-cite-frame}. This frame recognizes many situations, +such as blank lines, which it interprets as paragraph separators. It +also recognizes previously cited nested and non-nested citations in the +original message. By default it will coerce non-nested citations into +your preferred citation style, and it will add a level of citation to +nested citations. It will also simply cite uncited lines in your +preferred style. + +@cindex unciting +@cindex reciting +@vindex sc-default-uncite-frame +@vindex sc-default-recite-frame +In a similar vein, there are default frames for @dfn{unciting} and +@dfn{reciting}, contained in the variables +@code{sc-default-uncite-frame} and @code{sc-default-recite-frame} +respectively.@refill + +As mentioned earlier (@pxref{Recognizing Citations}), citations are +recognized through the values of the regular expressions +@code{sc-citation-root-regexp}, et al. To recognize odd styles, you +could modify these variables, or you could modify the default citing +frame. Alternatively, you could set up association lists of frames for +recognizing specific alternative forms. + +@vindex sc-cite-frame-alist +@vindex sc-uncite-frame-alist +@vindex sc-recite-frame-alist +For each of the actions -- citing, unciting, and reciting -- an alist is +consulted to find the frame to use (@code{sc-cite-frame-alist}, +@code{sc-uncite-frame-alist}, and @code{sc-recite-frame-alist} +respectively). These frames can contain alists of the form: + +@example +((@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{}) + (@var{infokey} (@var{regexp} @. @var{frame}) (@var{regexp} @. @var{frame}) @dots{}) + (@dots{})) +@end example + +@vindex sc-mail-field +@findex string-match +Where @var{infokey} is a key suitable for @code{sc-mail-field}, +@var{regexp} is a regular expression which is @code{string-match}'d +against the value of the @code{sc-mail-field} key, and @var{frame} is +the frame to use if a match occurred. @var{frame} can be a variable +containing a frame or a frame in-lined.@refill + +When Supercite is about to cite, uncite, or recite a region, it consults +the appropriate alist and attempts to find a frame to use. If one +is not found from the alist, then the appropriate default frame is used. + +@node Post-yank Formatting Commands, Citing Commands, Frames You Can Customize, Top +@comment node-name, next, previous, up +@vindex sc-mode-map-prefix +@vindex mode-map-prefix (sc-) +@kindex C-c C-p +@chapter Post-yank Formatting Commands +@ifinfo + +@end ifinfo +Once the original message has been yanked into the reply buffer, and +@code{sc-cite-original} has had a chance to do its thing, a number of +useful Supercite commands will be available to you. Since there is wide +variety in the keymaps that MUAs set up in their reply buffers, it is +next to impossible for Supercite to properly sprinkle its commands into +the existing keymap. For this reason Supercite places its commands on a +separate keymap, putting this keymap onto a prefix key in the reply +buffer. You can customize the prefix key Supercite uses by changing the +variable @code{sc-mode-map-prefix}. By default, the +@code{sc-mode-map-prefix} is @kbd{C-c C-p}; granted, not a great choice, +but unfortunately the best general solution so far. In the rest of this +chapter, we'll assume you've installed Supercite's keymap on the default +prefix.@refill + +@ifinfo +@menu +* Citing Commands:: +* Insertion Commands:: +* Variable Toggling Shortcuts:: +* Mail Field Commands:: +* Miscellaneous Commands:: +@end menu +@end ifinfo + +@node Citing Commands, Insertion Commands, Post-yank Formatting Commands, Post-yank Formatting Commands +@comment node-name, next, previous, up +@vindex sc-cite-region-limit +@section Commands to Manually Cite, Recite, and Uncite +@ifinfo + +@end ifinfo +Probably the three most common post-yank formatting operations that you +will perform will be the manual citing, reciting, and unciting of +regions of text in the reply buffer. Often you may want to recite a +paragraph to use a nickname, or manually cite a message when setting +@code{sc-cite-region-limit} to @code{nil}. The following commands +perform these functions on the region of text between @samp{point} and +@samp{mark}. Each of them sets the @dfn{undo boundary} before modifying +the region so that the command can be undone in the standard Emacs +way.@refill + +A quick note about Emacs 19. Unlike in Emacs 18, the region delimited +by @samp{point} and @samp{mark} can have two states. It can be +@dfn{active} or @dfn{inactive}. Although Emacs 19 and Lucid Emacs 19 +use different terminology and functions, both employ the same convention +such that when the region is inactive, commands that modify the region +should generate an error. The user needs to explicitly activate the +region before successfully executing the command. All Supercite +commands conform to this convention. + +Here is the list of Supercite citing commands: + +@table @asis +@findex sc-cite-region +@findex cite-region (sc-) +@kindex C-c C-p c +@vindex sc-pre-cite-hook +@vindex pre-cite-hook (sc-) +@vindex sc-confirm-always-p +@vindex confirm-always-p +@kindex C-u +@item @code{sc-cite-region} (@kbd{C-c C-p c}) +@comment +This command cites each line in the region of text by interpreting the +selected frame from @code{sc-cite-frame-alist}, or the default citing +frame @code{sc-default-cite-frame}. It runs the hook +@code{sc-pre-cite-hook} before interpreting the frame. With an optional +universal argument (@kbd{C-u}), it temporarily sets +@code{sc-confirm-always-p} to @code{t} so you can confirm the +attribution string for a single manual citing. +@xref{Configuring the Citation Engine}.@refill + +@findex sc-uncite-region +@findex uncite-region (sc-) +@kindex C-c C-p u +@item @code{sc-uncite-region} (@kbd{C-c C-p u}) +@comment +This command removes any citation strings from the beginning of each +cited line in the region by interpreting the selected frame from +@code{sc-uncite-frame-alist}, or the default unciting frame +@code{sc-default-uncite-frame}. It runs the hook +@code{sc-pre-uncite-hook} before interpreting the frame. +@xref{Configuring the Citation Engine}.@refill + +@findex sc-recite-region +@findex recite-region (sc-) +@kindex C-c C-p r +@item @code{sc-recite-region} (@kbd{C-c C-p r}) +@comment +This command recites each line the region by interpreting the selected +frame from @code{sc-recite-frame-alist}, or the default reciting frame +@code{sc-default-recite-frame}. It runs the hook +@code{sc-pre-recite-hook} before interpreting the frame. +@xref{Configuring the Citation Engine}.@refill + +@vindex sc-confirm-always-p +@vindex confirm-always-p (sc-) +Supercite will always ask you to confirm the attribution when reciting a +region, regardless of the value of @code{sc-confirm-always-p}. +@end table + +@node Insertion Commands, Variable Toggling Shortcuts, Citing Commands, Post-yank Formatting Commands +@comment node-name, next, previous, up +@section Insertion Commands +@ifinfo + +@end ifinfo +These two functions insert various strings into the reply buffer. + +@table @asis +@findex sc-insert-reference +@findex insert-reference (sc-) +@kindex C-c C-p w +@item @code{sc-insert-reference} (@kbd{C-c C-p w}) +@comment +@vindex sc-preferred-header-style +@vindex preferred-header-style (sc-) +Inserts a reference header into the reply buffer at @samp{point}. With +no arguments, the header indexed by @code{sc-preferred-header-style} is +inserted. An optional numeric argument is the index into +@code{sc-rewrite-header-list} indicating which reference header to +write.@refill + +With just the universal argument (@kbd{C-u}), electric reference mode is +entered, regardless of the value of @code{sc-electric-references-p}. + +@findex sc-insert-citation +@findex insert-citation (sc-) +@kindex C-c C-p i +@item @code{sc-insert-citation} (@kbd{C-c C-p i}) +@comment +Inserts the current citation string at the beginning of the line that +@samp{point} is on. If the line is already cited, Supercite will issue +an error and will not cite the line. +@end table + +@node Variable Toggling Shortcuts, Mail Field Commands, Insertion Commands, Post-yank Formatting Commands +@comment node-name, next, previous, up +@cindex toggling variables +@section Variable Toggling Shortcuts +@ifinfo + +@end ifinfo +Supercite defines a number of commands that make it easier for you to +toggle and set various Supercite variables as you are editing the reply +buffer. For example, you may want to turn off filling or whitespace +cleanup, but only temporarily. These toggling shortcut commands make +this easy to do. + +@kindex C-c C-p C-t +Like Supercite commands in general, the toggling commands are placed on +a keymap prefix within the greater Supercite keymap. For the default +value of @code{sc-mode-map-prefix}, this will be +@kbd{C-c C-p C-t}.@refill + +The following commands toggle the value of certain Supercite variables +which take only a binary value: + +@table @kbd +@item C-c C-p C-t b +Toggles the variable @code{sc-mail-nuke-blank-lines-p}. + +@item C-c C-p C-t c +Toggles the variable @code{sc-confirm-always-p}. + +@item C-c C-p C-t d +Toggles the variable @code{sc-downcase-p}. + +@item C-c C-p C-t e +Toggles the variable @code{sc-electric-references-p}. + +@item C-c C-p C-t f +Toggles the variable @code{sc-auto-fill-region-p}. + +@item C-c C-p C-t o +Toggles the variable @code{sc-electric-circular-p}. + +@item C-c C-p C-t s +Toggles the variable @code{sc-nested-citation-p}. + +@item C-c C-p C-t u +Toggles the variable @code{sc-use-only-preferences-p}. + +@item C-c C-p C-t w +Toggles the variable @code{sc-fixup-whitespace-p}. +@end table + +@findex set-variable +The following commands let you set the value of multi-value variables, +in the same way that Emacs' @code{set-variable} does: + +@table @kbd +@item C-c C-p C-t a +Sets the value of the variable @code{sc-preferred-attribution-list}. + +@item C-c C-p C-t l +Sets the value of the variable @code{sc-cite-region-limit}. + +@item C-c C-p C-t n +Sets the value of the variable @code{sc-mail-nuke-mail-headers}. + +@item C-c C-p C-t N +Sets the value of the variable @code{sc-mail-header-nuke-list}. + +@item C-c C-p C-t p +Sets the value of the variable @code{sc-preferred-header-style}. +@end table + +@kindex C-c C-p C-p +One special command is provided to toggle both +@code{sc-auto-fill-region-p} and @code{sc-fixup-whitespace-p} together. +This is because you typically want to run Supercite with either variable +as @code{nil} or non-@code{nil}. The command to toggle these variables +together is bound on @kbd{C-c C-p C-p}.@refill + +Finally, the command @kbd{C-c C-p C-t h} (also @kbd{C-c C-p C-t ?}) +brings up a Help message on the toggling keymap. + + +@node Mail Field Commands, Miscellaneous Commands, Variable Toggling Shortcuts, Post-yank Formatting Commands +@comment node-name, next, previous, up +@section Mail Field Commands +@ifinfo + +@end ifinfo +These commands allow you to view, modify, add, and delete various bits +of information from the info alist. +@xref{Information Keys and the Info Alist}.@refill + +@table @asis +@kindex C-c C-p f +@findex sc-mail-field-query +@findex mail-field-query (sc-) +@kindex C-c C-p f +@item @code{sc-mail-field-query} (@kbd{C-c C-p f}) +@comment +Allows you to interactively view, modify, add, and delete info alist +key-value pairs. With no argument, you are prompted (with completion) +for a info key. The value associated with that key is displayed in the +minibuffer. With an argument, this command will first ask if you want +to view, modify, add, or delete an info key. Viewing is identical to +running the command with no arguments. + +If you want to modify the value of a key, Supercite will first prompt +you (with completion) for the key of the value you want to change. It +will then put you in the minibuffer with the key's current value so you +can edit the value as you wish. When you hit @key{RET}, the key's value +is changed. For those of you running Emacs 19, minibuffer history is +kept for the values. + +If you choose to delete a key-value pair, Supercite will prompt you (with +completion) for the key to delete. + +If you choose to add a new key-value pair, Supercite firsts prompts you +for the key to add. Note that completion is turned on for this prompt, +but you can type any key name here, even one that does not yet exist. +After entering the key, Supercite prompts you for the key's value. It +is not an error to enter a key that already exists, but the new value +will override any old value. It will not replace it though; if you +subsequently delete the key-value pair, the old value will reappear. + +@findex sc-mail-process-headers +@findex mail-process-headers (sc-) +@kindex C-c C-p g +@item @code{sc-mail-process-headers} (@kbd{C-c C-p g}) +@comment +This command lets you re-initialize Supercite's info alist from any set +of mail headers in the region between @samp{point} and @samp{mark}. +This function is especially useful for replying to digest messages where +Supercite will initially set up its information for the digest +originator, but you want to cite each component article with the real +message author. Note that unless an error during processing occurs, any +old information is lost.@refill +@end table + +@node Miscellaneous Commands, Information Keys and the Info Alist, Mail Field Commands, Post-yank Formatting Commands +@comment node-name, next, previous, up +@section Miscellaneous Commands +@ifinfo + +@end ifinfo +@table @asis +@findex sc-open-line +@findex open-line (sc-) +@findex open-line +@kindex C-c C-p o +@item @code{sc-open-line} (@kbd{C-c C-p o}) +@comment +Similar to Emacs' standard @code{open-line} commands, but inserts the +citation string in front of the new line. As with @code{open-line}, +an optional numeric argument inserts that many new lines.@refill + +@findex sc-describe +@findex describe (sc-) +@kindex C-c C-p ? +@kindex C-c C-p h +@item @code{sc-describe} (@kbd{C-c C-p h} and @kbd{C-c C-p ?}) +@comment +This function has been obsoleted by the @TeX{}info manual you are now +reading. It is still provided for compatibility, but it will eventually +go away. + +@findex sc-version +@findex version (sc-) +@kindex C-c C-p v +@item @code{sc-version} (@kbd{C-c C-p v}) +@comment +Echos the version of Supercite you are using. With the optional +universal argument (@kbd{C-u}), this command inserts the version +information into the current buffer. + +@findex sc-submit-bug-report +@findex submit-bug-report (sc-) +@kindex C-c C-p C-b +@item @code{sc-submit-bug-report} (@kbd{C-c C-p C-b}) +@comment +If you encounter a bug, or wish to suggest an enhancement, use this +command to set up an outgoing mail buffer, with the proper address to +the Supercite maintainer automatically inserted in the @samp{To:@:} +field. This command also inserts information that the Supercite +maintainer can use to recreate your exact setup, making it easier to +verify your bug. +@end table + +@node Hints to MUA Authors, Version 3 Changes, Electric References, Top +@comment node-name, next, previous, up +@chapter Hints to MUA Authors +@ifinfo + +@end ifinfo +In June of 1989, some discussion was held between the various MUA +authors, the Supercite author, and other Supercite users. These +discussions centered around the need for a standard interface between +MUAs and Supercite (or any future Supercite-like packages). This +interface was formally proposed by Martin Neitzel on Fri, 23 Jun 89, in +a mail message to the Supercite mailing list: + +@example + Martin> Each news/mail-reader should provide a form of + Martin> mail-yank-original that + + Martin> 1: inserts the original message incl. header into the + Martin> reply buffer; no indentation/prefixing is done, the header + Martin> tends to be a "full blown" version rather than to be + Martin> stripped down. + + Martin> 2: `point' is at the start of the header, `mark' at the + Martin> end of the message body. + + Martin> 3: (run-hooks 'mail-yank-hooks) + + Martin> [Supercite] should be run as such a hook and merely + Martin> rewrite the message. This way it isn't anymore + Martin> [Supercite]'s job to gather the original from obscure + Martin> sources. [@dots{}] +@end example + +@vindex mail-citation-hook +@vindex mail-yank-hooks +@cindex sendmail.el +@findex mail-yank-original +@findex defvar +This specification was adopted, but with the recent release of +Emacs 19, it has undergone a slight modification. Instead of the +variable @code{mail-yank-hooks}, the new preferred hook variable that +the MUA should provide is @code{mail-citation-hook}. +@code{mail-yank-hooks} can be provided for backward compatibility, but +@code{mail-citation-hook} should always take precedence. Richard +Stallman (of the FSF) suggests that the MUAs should @code{defvar} +@code{mail-citation-hook} to @code{nil} and perform some default citing +when that is the case. Take a look at Emacs 19's @file{sendmail.el} +file, specifically the @code{mail-yank-original} defun for +details.@refill + +If you are writing a new MUA package, or maintaining an existing MUA +package, you should make it conform to this interface so that your users +will be able to link Supercite easily and seamlessly. To do this, when +setting up a reply or forward buffer, your MUA should follow these +steps: + +@enumerate +@item +Insert the original message, including the mail headers into the reply +buffer. At this point you should not modify the raw text in any way, and +you should place all the original headers into the body of the reply. +This means that many of the mail headers will be duplicated, one copy +above the @code{mail-header-separator} line and one copy below, +however there will probably be more headers below this line.@refill + +@item +Set @samp{point} to the beginning of the line containing the first mail +header in the body of the reply. Set @samp{mark} at the end of the +message text. It is very important that the region be set around the +text Supercite is to modify and that the mail headers are within this +region. Supercite will not venture outside the region for any reason, +and anything within the region is fair game, so don't put anything that +@strong{must} remain unchanged inside the region. Further note that for +Emacs 19, the region need not be set active. Supercite will work +properly when the region is inactive, as should any other like-minded +package.@refill + +@item +Run the hook @code{mail-citation-hook}. You will probably want to +provide some kind of default citation functions in cases where the user +does not have Supercite installed. By default, your MUA should +@code{defvar} @code{mail-citation-hook} to @code{nil}, and in your +yanking function, check its value. If it finds +@code{mail-citation-hook} to be @code{nil}, it should perform some +default citing behavior. User who want to connect to Supercite then +need only add @code{sc-cite-original} to this list of hooks using +@code{add-hook}.@refill +@end enumerate + +If you do all this, your users will not need to overload your routines +to use Supercite, and your MUA will join the ranks of those that conform +to this interface ``out of the box.'' + +@node Version 3 Changes, Thanks and History, Hints to MUA Authors, Top +@comment node-name, next, previous, up +@chapter Version 3 Changes +@ifinfo + +@end ifinfo +@cindex sc-unsupp.el file +With version 3, Supercite has undergone an almost complete rewrite, and +has hopefully benefited in a number of ways, including vast +improvements in the speed of performance, a big reduction in size of the +code and in the use of Emacs resources, and a much cleaner and flexible +internal architecture. The central construct of the info alist, and its +role in Supercite has been expanded, and the other central concept, the +general package Regi, was developed to provide a theoretically unlimited +flexibility. + +But most of this work is internal and not of very great importance to the +casual user. There have been some changes at the user-visible level, +but for the most part, the Supercite configuration variables from +version 2 should still be relevant to version 3. Below, I briefly +outline those user-visible things that have changed since version 2. For +details, look to other sections of this manual. + +@enumerate +@item +@cindex supercite.el file +@cindex reporter.el file +@cindex regi.el file +@cindex sc.el from version 2 +@cindex sc-elec.el from version 2 +Supercite proper now comes in a single file, @file{supercite.el}, which +contains everything except the unsupported noodlings, overloading (which +should be more or less obsolete with the release of Emacs 19), and the +general lisp packages @file{reporter.el} and @file{regi.el}. Finally, +the @TeX{}info manual comes in its own file as well. In particular, the +file @file{sc.el} from the version 2 distribution is obsolete, as is the +file @file{sc-elec.el}. + +@item +@code{sc-spacify-name-chars} is gone in version 3. + +@item +@vindex sc-attrib-selection-list +@vindex attrib-selection-list +@code{sc-nickname-alist} is gone in version 3. The +@code{sc-attrib-selection-list} is a more general construct supporting +the same basic feature. + +@item +The version 2 variable @code{sc-preferred-attribution} has been changed +to @code{sc-preferred-attribution-list}, and has been expanded upon to +allow you to specify an ordered list of preferred attributions. + +@item +@code{sc-mail-fields-list} has been removed, and header nuking in +general has been greatly improved, giving you wider flexibility in +specifying which headers to keep and remove while presenting a +simplified interface to commonly chosen defaults. + +@item +Post-yank paragraph filling has been completely removed from Supercite, +other packages just do it better than Supercite ever would. Supercite +will still fill newly cited paragraphs. + +@item +@vindex sc-cite-region-limit +@vindex cite-region-limit +The variable @code{sc-all-but-cite-p} has been replaced by +@code{sc-cite-region-limit}. + +@item +Keymap hacking in the reply buffer has been greatly simplified, with, I +believe, little reduction in functionality. + +@item +Hacking of the reply buffer's docstring has been completely eliminated. +@end enumerate + +@node Thanks and History, The Supercite Mailing List, Version 3 Changes, Top +@comment node-name, next, previous, up +@chapter Thanks and History +@ifinfo + +@end ifinfo +The Supercite package was derived from its predecessor Superyank 1.11 +which was inspired by various bits of code and ideas from Martin Neitzel +and Ashwin Ram. They were the folks who came up with the idea of +non-nested citations and implemented some rough code to provide this +style. Superyank and Supercite version 2 evolved to the point where much +of the attribution selection mechanism was automatic, and features have +been continuously added through the comments and suggestions of the +Supercite mailing list participants. Supercite version 3 represents a +nearly complete rewrite with many of the algorithms and coding styles +being vastly improved. Hopefully Supercite version 3 is faster, +smaller, and much more flexible than its predecessors. + +In the version 2 manual I thanked some specific people for their help in +developing Supercite 2. You folks know who you are and your continued +support is greatly appreciated. I wish to thank everyone on the +Supercite mailing list, especially the brave alpha testers, who helped +considerably in testing out the concepts and implementation of Supercite +version 3. Special thanks go out to the MUA and Emacs authors Kyle +Jones, Stephen Gildea, Richard Stallman, and Jamie Zawinski for coming +to a quick agreement on the new @code{mail-citation-hook} interface, and +for adding the magic lisp to their code to support this. + +All who have helped and contributed have been greatly appreciated. + +@node The Supercite Mailing List, Concept Index, Thanks and History, Top +@comment node-name, next, previous, up +@cindex supercite mailing list address +@cindex mailing list address +@chapter The Supercite Mailing List +@ifinfo + +@end ifinfo +The author runs a simple mail expanding mailing list for discussion of +issues related to Supercite. This includes enhancement requests, bug +reports, general help questions, etc. To subscribe or unsubscribe to +the mailing list, send a request to the administrative address: + +@example +supercite-request@@python.org +@end example + +Please be sure to include the most reliable and shortest (preferably +Internet) address back to you. To post articles to the list, send your +message to this address (you do not need to be a member to post, but be +sure to indicate this in your article or replies may not be CC'd to +you): + +@example +supercite@@python.org +@end example + +If you are sending bug reports, they should go to the following address, +but @emph{please}! use the command @code{sc-submit-bug-report} since it +will be much easier for me to duplicate your problem if you do so. It +will set up a mail buffer automatically with this address on the +@samp{To:@:} line: + +@example +supercite-help@@python.org +@end example + +@node Concept Index, Command Index, The Supercite Mailing List, Top +@comment node-name, next, previous, up +@unnumbered Concept Index +@printindex cp + +@node Command Index, Key Index, Concept Index, Top +@comment node-name, next, previous, up +@unnumbered Command Index +@ifinfo + +@end ifinfo +Since all supercite commands are prepended with the string +``@code{sc-}'', each appears under its @code{sc-}@var{command} name and +its @var{command} name. +@iftex +@sp 2 +@end iftex +@printindex fn + +@node Key Index, Variable Index, Command Index, Top +@comment node-name, next, previous, up +@unnumbered Key Index +@printindex ky + +@node Variable Index, , Key Index, Top +@comment node-name, next, previous, up +@unnumbered Variable Index +@ifinfo + +@end ifinfo +Since all supercite variables are prepended with the string +``@code{sc-}'', each appears under its @code{sc-}@var{variable} name and +its @var{variable} name. +@iftex +@sp 2 +@end iftex +@printindex vr +@summarycontents +@contents +@bye diff --git a/man/screen.texi b/man/screen.texi new file mode 100644 index 00000000000..a28d844ddc3 --- /dev/null +++ b/man/screen.texi @@ -0,0 +1,330 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Screen, User Input, Acknowledgments, Top +@chapter The Organization of the Screen +@cindex screen +@cindex parts of the screen +@c + + On a text-only terminal, the Emacs display occupies the whole screen. +On the X Window System, Emacs creates its own X windows to use. We use +the term @dfn{frame} to mean an entire text-only screen or an entire X +window used by Emacs. Emacs uses both kinds of frames in the same way +to display your editing. Emacs normally starts out with just one frame, +but you can create additional frames if you wish. @xref{Frames}. + + When you start Emacs, the entire frame except for the first and last +lines is devoted to the text you are editing. This area is called the +@dfn{window}. The first line is a @dfn{menu bar}, and the last line is +a special @dfn{echo area} or @dfn{minibuffer window} where prompts +appear and where you can enter responses. See below for more +information about these special lines. + + You can subdivide the large text window horizontally or vertically +into multiple text windows, each of which can be used for a different +file (@pxref{Windows}). In this manual, the word ``window'' always +refers to the subdivisions of a frame within Emacs. + + The window that the cursor is in is the @dfn{selected window}, in +which editing takes place. Most Emacs commands implicitly apply to the +text in the selected window (though mouse commands generally operate on +whatever window you click them in, whether selected or not). The other +windows display text for reference only, unless/until you select them. +If you use multiple frames under the X Window System, then giving the +input focus to a particular frame selects a window in that frame. + + Each window's last line is a @dfn{mode line}, which describes what is +going on in that window. It appears in inverse video, if the terminal +supports that, and its contents begin with @w{@samp{--:-- @ *scratch*}} +when Emacs starts. The mode line displays status information such as +what buffer is being displayed above it in the window, what major and +minor modes are in use, and whether the buffer contains unsaved changes. + +@menu +* Point:: The place in the text where editing commands operate. +* Echo Area:: Short messages appear at the bottom of the screen. +* Mode Line:: Interpreting the mode line. +* Menu Bar:: How to use the menu bar. +@end menu + +@node Point +@section Point +@cindex point +@cindex cursor + + Within Emacs, the terminal's cursor shows the location at which +editing commands will take effect. This location is called @dfn{point}. +Many Emacs commands move point through the text, so that you can edit at +different places in it. You can also place point by clicking mouse +button 1. + + While the cursor appears to point @emph{at} a character, you should +think of point as @emph{between} two characters; it points @emph{before} +the character that appears under the cursor. For example, if your text +looks like @samp{frob} with the cursor over the @samp{b}, then point is +between the @samp{o} and the @samp{b}. If you insert the character +@samp{!} at that position, the result is @samp{fro!b}, with point +between the @samp{!} and the @samp{b}. Thus, the cursor remains over +the @samp{b}, as before. + + Sometimes people speak of ``the cursor'' when they mean ``point,'' or +speak of commands that move point as ``cursor motion'' commands. + + Terminals have only one cursor, and when output is in progress it must +appear where the typing is being done. This does not mean that point is +moving. It is only that Emacs has no way to show you the location of point +except when the terminal is idle. + + If you are editing several files in Emacs, each in its own buffer, +each buffer has its own point location. A buffer that is not currently +displayed remembers where point is in case you display it again later. + + When there are multiple windows in a frame, each window has its own +point location. The cursor shows the location of point in the selected +window. This also is how you can tell which window is selected. If the +same buffer appears in more than one window, each window has its own +position for point in that buffer. + + When there are multiple frames, each frame can display one cursor. +The cursor in the selected frame is solid; the cursor in other frames is +a hollow box, and appears in the window that would be selected if you +give the input focus to that frame. + + The term `point' comes from the character @samp{.}, which was the +command in TECO (the language in which the original Emacs was written) +for accessing the value now called `point'. + +@node Echo Area +@section The Echo Area +@cindex echo area +@c + + The line at the bottom of the frame (below the mode line) is the +@dfn{echo area}. It is used to display small amounts of text for +several purposes. + + @dfn{Echoing} means displaying the characters that you type. Outside +Emacs, the operating system normally echoes all your input. Emacs +handles echoing differently. + + Single-character commands do not echo in Emacs, and multi-character +commands echo only if you pause while typing them. As soon as you pause +for more than a second in the middle of a command, Emacs echoes all the +characters of the command so far. This is to @dfn{prompt} you for the +rest of the command. Once echoing has started, the rest of the command +echoes immediately as you type it. This behavior is designed to give +confident users fast response, while giving hesitant users maximum +feedback. You can change this behavior by setting a variable +(@pxref{Display Vars}). + +@cindex error message in the echo area + If a command cannot be executed, it may print an @dfn{error message} in +the echo area. Error messages are accompanied by a beep or by flashing the +screen. Also, any input you have typed ahead is thrown away when an error +happens. + + Some commands print informative messages in the echo area. These +messages look much like error messages, but they are not announced with +a beep and do not throw away input. Sometimes the message tells you +what the command has done, when this is not obvious from looking at the +text being edited. Sometimes the sole purpose of a command is to print +a message giving you specific information---for example, @kbd{C-x =} +prints a message describing the character position of point in the text +and its current column in the window. Commands that take a long time +often display messages ending in @samp{...} while they are working, and +add @samp{done} at the end when they are finished. + +@cindex @samp{*Messages*} buffer +@cindex saved echo area messages +@cindex messages saved from echo area + Echo-area informative messages are saved in an editor buffer named +@samp{*Messages*}. (We have not explained buffers yet; see +@ref{Buffers}, for more information about them.) If you miss a message +that appears briefly on the screen, you can switch to the +@samp{*Messages*} buffer to see it again. (Successive progress messages +are often collapsed into one in that buffer.) + +@vindex message-log-max + The size of @samp{*Messages*} is limited to a certain number of lines. +The variable @code{message-log-max} specifies how many lines. Once the +buffer has that many lines, each line added at the end deletes one line +from the beginning. @xref{Variables}, for how to set variables such as +@code{message-log-max}. + + The echo area is also used to display the @dfn{minibuffer}, a window that +is used for reading arguments to commands, such as the name of a file to be +edited. When the minibuffer is in use, the echo area begins with a prompt +string that usually ends with a colon; also, the cursor appears in that line +because it is the selected window. You can always get out of the +minibuffer by typing @kbd{C-g}. @xref{Minibuffer}. + +@node Mode Line +@section The Mode Line +@cindex mode line +@cindex top level +@c + + Each text window's last line is a @dfn{mode line}, which describes what +is going on in that window. When there is only one text window, the +mode line appears right above the echo area; it is the next-to-last line +on the frame. The mode line is in inverse video if the terminal +supports that, and it starts and ends with dashes. + + Normally, the mode line looks like this: + +@example +-@var{cs}:@var{ch} @var{buf} (@var{major} @var{minor})--@var{line}--@var{pos}------ +@end example + +@noindent +This gives information about the buffer being displayed in the window: the +buffer's name, what major and minor modes are in use, whether the buffer's +text has been changed, and how far down the buffer you are currently +looking. + + @var{ch} contains two stars @samp{**} if the text in the buffer has +been edited (the buffer is ``modified''), or @samp{--} if the buffer has +not been edited. For a read-only buffer, it is @samp{%*} if the buffer +is modified, and @samp{%%} otherwise. + + @var{buf} is the name of the window's @dfn{buffer}. In most cases +this is the same as the name of a file you are editing. @xref{Buffers}. + + The buffer displayed in the selected window (the window that the +cursor is in) is also Emacs's selected buffer, the one that editing +takes place in. When we speak of what some command does to ``the +buffer,'' we are talking about the currently selected buffer. + + @var{line} is @samp{L} followed by the current line number of point. +This is present when Line Number mode is enabled (which it normally is). +You can optionally display the current column number too, by turning on +Column Number mode (which is not enabled by default because it is +somewhat slower). @xref{Optional Mode Line}. + + @var{pos} tells you whether there is additional text above the top of +the window, or below the bottom. If your buffer is small and it is all +visible in the window, @var{pos} is @samp{All}. Otherwise, it is +@samp{Top} if you are looking at the beginning of the buffer, @samp{Bot} +if you are looking at the end of the buffer, or @samp{@var{nn}%}, where +@var{nn} is the percentage of the buffer above the top of the +window.@refill + + @var{major} is the name of the @dfn{major mode} in effect in the +buffer. At any time, each buffer is in one and only one of the possible +major modes. The major modes available include Fundamental mode (the +least specialized), Text mode, Lisp mode, C mode, Texinfo mode, and many +others. @xref{Major Modes}, for details of how the modes differ and how +to select one.@refill + + Some major modes display additional information after the major mode +name. For example, Rmail buffers display the current message number and +the total number of messages. Compilation buffers and Shell buffers +display the status of the subprocess. + + @var{minor} is a list of some of the @dfn{minor modes} that are turned +on at the moment in the window's chosen buffer. For example, +@samp{Fill} means that Auto Fill mode is on. @samp{Abbrev} means that +Word Abbrev mode is on. @samp{Ovwrt} means that Overwrite mode is on. +@xref{Minor Modes}, for more information. @samp{Narrow} means that the +buffer being displayed has editing restricted to only a portion of its +text. This is not really a minor mode, but is like one. +@xref{Narrowing}. @samp{Def} means that a keyboard macro is being +defined. @xref{Keyboard Macros}. + + In addition, if Emacs is currently inside a recursive editing level, +square brackets (@samp{[@dots{}]}) appear around the parentheses that +surround the modes. If Emacs is in one recursive editing level within +another, double square brackets appear, and so on. Since recursive +editing levels affect Emacs globally, not just one buffer, the square +brackets appear in every window's mode line or not in any of them. +@xref{Recursive Edit}.@refill + + Non-windowing terminals can only show a single Emacs frame at a time +(@pxref{Frames}). On such terminals, the mode line displays the name of +the selected frame, after @var{ch}. The initial frame's name is +@samp{F1}. + + @var{cs} states the coding system used for the file you are editing. +A dash indicates the default state of affairs: no code conversion, +except for end-of-line translation if the file contents call for that. +@samp{=} means no conversion whatsoever. Nontrivial code conversions +are represented by various letters---for example, @samp{1} refers to ISO +Latin-1. @xref{Coding Systems}, for more information. If you are using +an input method, a string of the form @samp{@var{i}>} is added to the +beginning of @var{cs}; @var{i} identifies the input method. (Some input +methods show @samp{+} or @samp{@@} instead of @samp{>}.) @xref{Input +Methods}. + + When you are using a character-only terminal (not a window system), +@var{cs} uses three characters to describe, respectively, the coding +system for keyboard input, the coding system for terminal output, and +the coding system used for the file you are editing. + + When multibyte characters are not enabled, @var{cs} does not appear at +all. @xref{Enabling Multibyte}. + +@cindex end-of-line conversion, mode-line indication + The colon after @var{cs} can change to another string in certain +circumstances. Emacs uses newline to separate lines in the buffer. +Some files use different conventions for separating lines: either +carriage-return linefeed (the MS-DOS convention) or just carriage-return +(the Macintosh convention). If the buffer's file uses carriage-return +linefeed, the colon changes to either a backslash (@samp{\}) or +@samp{(DOS)}, depending on the operating system. If the file uses just +carriage-return, the colon indicator changes to either a forward slash +(@samp{/}) or @samp{(Mac)}. On some systems, Emacs displays +@samp{(Unix)} instead of the colon even for files that use newline to +separate lines. + +@vindex eol-mnemonic-unix +@vindex eol-mnemonic-dos +@vindex eol-mnemonic-mac +@vindex eol-mnemonic-undecided + You can customize the mode line display for each of the end-of-line +formats by setting each of the variables @code{eol-mnemonic-unix}, +@code{eol-mnemonic-dos}, @code{eol-mnemonic-mac}, and +@code{eol-mnemonic-undecided} to any string you find appropriate. +@xref{Variables}, for an explanation how to set variables. + + @xref{Optional Mode Line}, for features that add other handy +information to the mode line, such as the current column number of +point, the current time, and whether new mail for you has arrived. + +@node Menu Bar +@section The Menu Bar +@cindex menu bar + + Each Emacs frame normally has a @dfn{menu bar} at the top which you +can use to perform certain common operations. There's no need to list +them here, as you can more easily see for yourself. + +@kindex M-` +@kindex F10 +@findex tmm-menubar + When you are using a window system, you can use the mouse to choose a +command from the menu bar. An arrow pointing right, after the menu +item, indicates that the item leads to a subsidiary menu; @samp{...} at +the end means that the command will read arguments from the keyboard +before it actually does anything. + + To view the full command name and documentation for a menu item, type +@kbd{C-h k}, and then select the menu bar with the mouse in the usual +way (@pxref{Key Help}). + + On text-only terminals with no mouse, you can use the menu bar by +typing @kbd{M-`} or @key{F10} (these run the command +@code{tmm-menubar}). This command enters a mode in which you can select +a menu item from the keyboard. A provisional choice appears in the echo +area. You can use the left and right arrow keys to move through the +menu to different choices. When you have found the choice you want, +type @key{RET} to select it. + + Each menu item also has an assigned letter or digit which designates +that item; it is usually the initial of some word in the item's name. +This letter or digit is separated from the item name by @samp{=>}. You +can type the item's letter or digit to select the item. + + Some of the commands in the menu bar have ordinary key bindings as +well; if so, the menu lists one equivalent key binding in parentheses +after the item itself. diff --git a/man/search.texi b/man/search.texi new file mode 100644 index 00000000000..09c66bca0af --- /dev/null +++ b/man/search.texi @@ -0,0 +1,948 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Search, Fixit, Display, Top +@chapter Searching and Replacement +@cindex searching +@cindex finding strings within text + + Like other editors, Emacs has commands for searching for occurrences of +a string. The principal search command is unusual in that it is +@dfn{incremental}; it begins to search before you have finished typing the +search string. There are also nonincremental search commands more like +those of other editors. + + Besides the usual @code{replace-string} command that finds all +occurrences of one string and replaces them with another, Emacs has a fancy +replacement command called @code{query-replace} which asks interactively +which occurrences to replace. + +@menu +* Incremental Search:: Search happens as you type the string. +* Nonincremental Search:: Specify entire string and then search. +* Word Search:: Search for sequence of words. +* Regexp Search:: Search for match for a regexp. +* Regexps:: Syntax of regular expressions. +* Search Case:: To ignore case while searching, or not. +* Replace:: Search, and replace some or all matches. +* Other Repeating Search:: Operating on all matches for some regexp. +@end menu + +@node Incremental Search, Nonincremental Search, Search, Search +@section Incremental Search + +@cindex incremental search + An incremental search begins searching as soon as you type the first +character of the search string. As you type in the search string, Emacs +shows you where the string (as you have typed it so far) would be +found. When you have typed enough characters to identify the place you +want, you can stop. Depending on what you plan to do next, you may or +may not need to terminate the search explicitly with @key{RET}. + +@c WideCommands +@table @kbd +@item C-s +Incremental search forward (@code{isearch-forward}). +@item C-r +Incremental search backward (@code{isearch-backward}). +@end table + +@kindex C-s +@findex isearch-forward + @kbd{C-s} starts an incremental search. @kbd{C-s} reads characters from +the keyboard and positions the cursor at the first occurrence of the +characters that you have typed. If you type @kbd{C-s} and then @kbd{F}, +the cursor moves right after the first @samp{F}. Type an @kbd{O}, and see +the cursor move to after the first @samp{FO}. After another @kbd{O}, the +cursor is after the first @samp{FOO} after the place where you started the +search. At each step, the buffer text that matches the search string is +highlighted, if the terminal can do that; at each step, the current search +string is updated in the echo area. + + If you make a mistake in typing the search string, you can cancel +characters with @key{DEL}. Each @key{DEL} cancels the last character of +search string. This does not happen until Emacs is ready to read another +input character; first it must either find, or fail to find, the character +you want to erase. If you do not want to wait for this to happen, use +@kbd{C-g} as described below. + + When you are satisfied with the place you have reached, you can type +@key{RET}, which stops searching, leaving the cursor where the search +brought it. Also, any command not specially meaningful in searches +stops the searching and is then executed. Thus, typing @kbd{C-a} would +exit the search and then move to the beginning of the line. @key{RET} +is necessary only if the next command you want to type is a printing +character, @key{DEL}, @key{RET}, or another control character that is +special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, +@kbd{C-y}, @kbd{M-y}, @kbd{M-r}, or @kbd{M-s}). + + Sometimes you search for @samp{FOO} and find it, but not the one you +expected to find. There was a second @samp{FOO} that you forgot about, +before the one you were aiming for. In this event, type another @kbd{C-s} +to move to the next occurrence of the search string. This can be done any +number of times. If you overshoot, you can cancel some @kbd{C-s} +characters with @key{DEL}. + + After you exit a search, you can search for the same string again by +typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes +incremental search, and the second @kbd{C-s} means ``search again.'' + + To reuse earlier search strings, use the @dfn{search ring}. The +commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a search +string to reuse. These commands leave the selected search ring element +in the minibuffer, where you can edit it. Type @kbd{C-s} or @kbd{C-r} +to terminate editing the string and search for it. + + If your string is not found at all, the echo area says @samp{Failing +I-Search}. The cursor is after the place where Emacs found as much of your +string as it could. Thus, if you search for @samp{FOOT}, and there is no +@samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}. +At this point there are several things you can do. If your string was +mistyped, you can rub some of it out and correct it. If you like the place +you have found, you can type @key{RET} or some other Emacs command to +``accept what the search offered.'' Or you can type @kbd{C-g}, which +removes from the search string the characters that could not be found (the +@samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in +@samp{FOOT}). A second @kbd{C-g} at that point cancels the search +entirely, returning point to where it was when the search started. + + An upper-case letter in the search string makes the search +case-sensitive. If you delete the upper-case character from the search +string, it ceases to have this effect. @xref{Search Case}. + + If a search is failing and you ask to repeat it by typing another +@kbd{C-s}, it starts again from the beginning of the buffer. Repeating +a failing reverse search with @kbd{C-r} starts again from the end. This +is called @dfn{wrapping around}. @samp{Wrapped} appears in the search +prompt once this has happened. If you keep on going past the original +starting point of the search, it changes to @samp{Overwrapped}, which +means that you are revisiting matches that you have already seen. + +@cindex quitting (in search) + The @kbd{C-g} ``quit'' character does special things during searches; +just what it does depends on the status of the search. If the search has +found what you specified and is waiting for input, @kbd{C-g} cancels the +entire search. The cursor moves back to where you started the search. If +@kbd{C-g} is typed when there are characters in the search string that have +not been found---because Emacs is still searching for them, or because it +has failed to find them---then the search string characters which have not +been found are discarded from the search string. With them gone, the +search is now successful and waiting for more input, so a second @kbd{C-g} +will cancel the entire search. + + To search for a newline, type @kbd{C-j}. To search for another +control character, such as control-S or carriage return, you must quote +it by typing @kbd{C-q} first. This function of @kbd{C-q} is analogous +to its use for insertion (@pxref{Inserting Text}): it causes the +following character to be treated the way any ``ordinary'' character is +treated in the same context. You can also specify a character by its +octal code: enter @kbd{C-q} followed by a sequence of octal digits. + + You can change to searching backwards with @kbd{C-r}. If a search fails +because the place you started was too late in the file, you should do this. +Repeated @kbd{C-r} keeps looking for more occurrences backwards. A +@kbd{C-s} starts going forwards again. @kbd{C-r} in a search can be canceled +with @key{DEL}. + +@kindex C-r +@findex isearch-backward + If you know initially that you want to search backwards, you can use +@kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r} as +a key runs a command (@code{isearch-backward}) to search backward. A +backward search finds matches that are entirely before the starting +point, just as a forward search finds matches that begin after it. + + The characters @kbd{C-y} and @kbd{C-w} can be used in incremental +search to grab text from the buffer into the search string. This makes +it convenient to search for another occurrence of text at point. +@kbd{C-w} copies the word after point as part of the search string, +advancing point over that word. Another @kbd{C-s} to repeat the search +will then search for a string including that word. @kbd{C-y} is similar +to @kbd{C-w} but copies all the rest of the current line into the search +string. Both @kbd{C-y} and @kbd{C-w} convert the text they copy to +lower case if the search is currently not case-sensitive; this is so the +search remains case-insensitive. + + The character @kbd{M-y} copies text from the kill ring into the search +string. It uses the same text that @kbd{C-y} as a command would yank. +@xref{Yanking}. + + When you exit the incremental search, it sets the mark to where point +@emph{was}, before the search. That is convenient for moving back +there. In Transient Mark mode, incremental search sets the mark without +activating it, and does so only if the mark is not already active. + +@vindex isearch-mode-map + To customize the special characters that incremental search understands, +alter their bindings in the keymap @code{isearch-mode-map}. For a list +of bindings, look at the documentation of @code{isearch-mode} with +@kbd{C-h f isearch-mode @key{RET}}. + +@subsection Slow Terminal Incremental Search + + Incremental search on a slow terminal uses a modified style of display +that is designed to take less time. Instead of redisplaying the buffer at +each place the search gets to, it creates a new single-line window and uses +that to display the line that the search has found. The single-line window +comes into play as soon as point gets outside of the text that is already +on the screen. + + When you terminate the search, the single-line window is removed. +Then Emacs redisplays the window in which the search was done, to show +its new position of point. + +@ignore + The three dots at the end of the search string, normally used to indicate +that searching is going on, are not displayed in slow style display. +@end ignore + +@vindex search-slow-speed + The slow terminal style of display is used when the terminal baud rate is +less than or equal to the value of the variable @code{search-slow-speed}, +initially 1200. + +@vindex search-slow-window-lines + The number of lines to use in slow terminal search display is controlled +by the variable @code{search-slow-window-lines}. Its normal value is 1. + +@node Nonincremental Search, Word Search, Incremental Search, Search +@section Nonincremental Search +@cindex nonincremental search + + Emacs also has conventional nonincremental search commands, which require +you to type the entire search string before searching begins. + +@table @kbd +@item C-s @key{RET} @var{string} @key{RET} +Search for @var{string}. +@item C-r @key{RET} @var{string} @key{RET} +Search backward for @var{string}. +@end table + + To do a nonincremental search, first type @kbd{C-s @key{RET}}. This +enters the minibuffer to read the search string; terminate the string +with @key{RET}, and then the search takes place. If the string is not +found, the search command gets an error. + + The way @kbd{C-s @key{RET}} works is that the @kbd{C-s} invokes +incremental search, which is specially programmed to invoke nonincremental +search if the argument you give it is empty. (Such an empty argument would +otherwise be useless.) @kbd{C-r @key{RET}} also works this way. + + However, nonincremental searches performed using @kbd{C-s @key{RET}} do +not call @code{search-forward} right away. The first thing done is to see +if the next character is @kbd{C-w}, which requests a word search. +@ifinfo +@xref{Word Search}. +@end ifinfo + +@findex search-forward +@findex search-backward + Forward and backward nonincremental searches are implemented by the +commands @code{search-forward} and @code{search-backward}. These +commands may be bound to keys in the usual manner. The feature that you +can get to them via the incremental search commands exists for +historical reasons, and to avoid the need to find suitable key sequences +for them. + +@node Word Search, Regexp Search, Nonincremental Search, Search +@section Word Search +@cindex word search + + Word search searches for a sequence of words without regard to how the +words are separated. More precisely, you type a string of many words, +using single spaces to separate them, and the string can be found even if +there are multiple spaces, newlines or other punctuation between the words. + + Word search is useful for editing a printed document made with a text +formatter. If you edit while looking at the printed, formatted version, +you can't tell where the line breaks are in the source file. With word +search, you can search without having to know them. + +@table @kbd +@item C-s @key{RET} C-w @var{words} @key{RET} +Search for @var{words}, ignoring details of punctuation. +@item C-r @key{RET} C-w @var{words} @key{RET} +Search backward for @var{words}, ignoring details of punctuation. +@end table + + Word search is a special case of nonincremental search and is invoked +with @kbd{C-s @key{RET} C-w}. This is followed by the search string, +which must always be terminated with @key{RET}. Being nonincremental, +this search does not start until the argument is terminated. It works +by constructing a regular expression and searching for that; see +@ref{Regexp Search}. + + Use @kbd{C-r @key{RET} C-w} to do backward word search. + +@findex word-search-forward +@findex word-search-backward + Forward and backward word searches are implemented by the commands +@code{word-search-forward} and @code{word-search-backward}. These +commands may be bound to keys in the usual manner. The feature that you +can get to them via the incremental search commands exists for historical +reasons, and to avoid the need to find suitable key sequences for them. + +@node Regexp Search, Regexps, Word Search, Search +@section Regular Expression Search +@cindex regular expression +@cindex regexp + + A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that +denotes a class of alternative strings to match, possibly infinitely +many. In GNU Emacs, you can search for the next match for a regexp +either incrementally or not. + +@kindex C-M-s +@findex isearch-forward-regexp +@kindex C-M-r +@findex isearch-backward-regexp + Incremental search for a regexp is done by typing @kbd{C-M-s} +(@code{isearch-forward-regexp}). This command reads a search string +incrementally just like @kbd{C-s}, but it treats the search string as a +regexp rather than looking for an exact match against the text in the +buffer. Each time you add text to the search string, you make the +regexp longer, and the new regexp is searched for. Invoking @kbd{C-s} +with a prefix argument (its value does not matter) is another way to do +a forward incremental regexp search. To search backward for a regexp, +use @kbd{C-M-r} (@code{isearch-backward-regexp}), or @kbd{C-r} with a +prefix argument. + + All of the control characters that do special things within an +ordinary incremental search have the same function in incremental regexp +search. Typing @kbd{C-s} or @kbd{C-r} immediately after starting the +search retrieves the last incremental search regexp used; that is to +say, incremental regexp and non-regexp searches have independent +defaults. They also have separate search rings that you can access with +@kbd{M-p} and @kbd{M-n}. + + If you type @key{SPC} in incremental regexp search, it matches any +sequence of whitespace characters, including newlines. If you want +to match just a space, type @kbd{C-q @key{SPC}}. + + Note that adding characters to the regexp in an incremental regexp +search can make the cursor move back and start again. For example, if +you have searched for @samp{foo} and you add @samp{\|bar}, the cursor +backs up in case the first @samp{bar} precedes the first @samp{foo}. + +@findex re-search-forward +@findex re-search-backward + Nonincremental search for a regexp is done by the functions +@code{re-search-forward} and @code{re-search-backward}. You can invoke +these with @kbd{M-x}, or bind them to keys, or invoke them by way of +incremental regexp search with @kbd{C-M-s @key{RET}} and @kbd{C-M-r +@key{RET}}. + + If you use the incremental regexp search commands with a prefix +argument, they perform ordinary string search, like +@code{isearch-forward} and @code{isearch-backward}. @xref{Incremental +Search}. + +@node Regexps, Search Case, Regexp Search, Search +@section Syntax of Regular Expressions +@cindex regexp syntax + + Regular expressions have a syntax in which a few characters are +special constructs and the rest are @dfn{ordinary}. An ordinary +character is a simple regular expression which matches that same +character and nothing else. The special characters are @samp{$}, +@samp{^}, @samp{.}, @samp{*}, @samp{+}, @samp{?}, @samp{[}, @samp{]} and +@samp{\}. Any other character appearing in a regular expression is +ordinary, unless a @samp{\} precedes it. + + For example, @samp{f} is not a special character, so it is ordinary, and +therefore @samp{f} is a regular expression that matches the string +@samp{f} and no other string. (It does @emph{not} match the string +@samp{ff}.) Likewise, @samp{o} is a regular expression that matches +only @samp{o}. (When case distinctions are being ignored, these regexps +also match @samp{F} and @samp{O}, but we consider this a generalization +of ``the same string,'' rather than an exception.) + + Any two regular expressions @var{a} and @var{b} can be concatenated. The +result is a regular expression which matches a string if @var{a} matches +some amount of the beginning of that string and @var{b} matches the rest of +the string.@refill + + As a simple example, we can concatenate the regular expressions @samp{f} +and @samp{o} to get the regular expression @samp{fo}, which matches only +the string @samp{fo}. Still trivial. To do something nontrivial, you +need to use one of the special characters. Here is a list of them. + +@table @kbd +@item .@: @r{(Period)} +is a special character that matches any single character except a newline. +Using concatenation, we can make regular expressions like @samp{a.b}, which +matches any three-character string that begins with @samp{a} and ends with +@samp{b}.@refill + +@item * +is not a construct by itself; it is a postfix operator that means to +match the preceding regular expression repetitively as many times as +possible. Thus, @samp{o*} matches any number of @samp{o}s (including no +@samp{o}s). + +@samp{*} always applies to the @emph{smallest} possible preceding +expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating +@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on. + +The matcher processes a @samp{*} construct by matching, immediately, +as many repetitions as can be found. Then it continues with the rest +of the pattern. If that fails, backtracking occurs, discarding some +of the matches of the @samp{*}-modified construct in case that makes +it possible to match the rest of the pattern. For example, in matching +@samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first +tries to match all three @samp{a}s; but the rest of the pattern is +@samp{ar} and there is only @samp{r} left to match, so this try fails. +The next alternative is for @samp{a*} to match only two @samp{a}s. +With this choice, the rest of the regexp matches successfully.@refill + +@item + +is a postfix operator, similar to @samp{*} except that it must match +the preceding expression at least once. So, for example, @samp{ca+r} +matches the strings @samp{car} and @samp{caaaar} but not the string +@samp{cr}, whereas @samp{ca*r} matches all three strings. + +@item ? +is a postfix operator, similar to @samp{*} except that it can match the +preceding expression either once or not at all. For example, +@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else. + +@item [ @dots{} ] +is a @dfn{character set}, which begins with @samp{[} and is terminated +by @samp{]}. In the simplest case, the characters between the two +brackets are what this set can match. + +Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and +@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s +(including the empty string), from which it follows that @samp{c[ad]*r} +matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc. + +You can also include character ranges in a character set, by writing the +starting and ending characters with a @samp{-} between them. Thus, +@samp{[a-z]} matches any lower-case ASCII letter. Ranges may be +intermixed freely with individual characters, as in @samp{[a-z$%.]}, +which matches any lower-case ASCII letter or @samp{$}, @samp{%} or +period. + +Note that the usual regexp special characters are not special inside a +character set. A completely different set of special characters exists +inside character sets: @samp{]}, @samp{-} and @samp{^}. + +To include a @samp{]} in a character set, you must make it the first +character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To +include a @samp{-}, write @samp{-} as the first or last character of the +set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]} +and @samp{-}. + +To include @samp{^} in a set, put it anywhere but at the beginning of +the set. + +When you use a range in case-insensitive search, you should write both +ends of the range in upper case, or both in lower case, or both should +be non-letters. The behavior of a mixed-case range such as @samp{A-z} +is somewhat ill-defined, and it may change in future Emacs versions. + +@item [^ @dots{} ] +@samp{[^} begins a @dfn{complemented character set}, which matches any +character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches +all characters @emph{except} letters and digits. + +@samp{^} is not special in a character set unless it is the first +character. The character following the @samp{^} is treated as if it +were first (in other words, @samp{-} and @samp{]} are not special there). + +A complemented character set can match a newline, unless newline is +mentioned as one of the characters not to match. This is in contrast to +the handling of regexps in programs such as @code{grep}. + +@item ^ +is a special character that matches the empty string, but only at the +beginning of a line in the text being matched. Otherwise it fails to +match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at +the beginning of a line. + +@item $ +is similar to @samp{^} but matches only at the end of a line. Thus, +@samp{x+$} matches a string of one @samp{x} or more at the end of a line. + +@item \ +has two functions: it quotes the special characters (including +@samp{\}), and it introduces additional special constructs. + +Because @samp{\} quotes special characters, @samp{\$} is a regular +expression that matches only @samp{$}, and @samp{\[} is a regular +expression that matches only @samp{[}, and so on. +@end table + +Note: for historical compatibility, special characters are treated as +ordinary ones if they are in contexts where their special meanings make no +sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is +no preceding expression on which the @samp{*} can act. It is poor practice +to depend on this behavior; it is better to quote the special character anyway, +regardless of where it appears.@refill + +For the most part, @samp{\} followed by any character matches only that +character. However, there are several exceptions: two-character +sequences starting with @samp{\} that have special meanings. The second +character in the sequence is always an ordinary character when used on +its own. Here is a table of @samp{\} constructs. + +@table @kbd +@item \| +specifies an alternative. Two regular expressions @var{a} and @var{b} +with @samp{\|} in between form an expression that matches some text if +either @var{a} matches it or @var{b} matches it. It works by trying to +match @var{a}, and if that fails, by trying to match @var{b}. + +Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} +but no other string.@refill + +@samp{\|} applies to the largest possible surrounding expressions. Only a +surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of +@samp{\|}.@refill + +Full backtracking capability exists to handle multiple uses of @samp{\|}. + +@item \( @dots{} \) +is a grouping construct that serves three purposes: + +@enumerate +@item +To enclose a set of @samp{\|} alternatives for other operations. +Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}. + +@item +To enclose a complicated expression for the postfix operators @samp{*}, +@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches +@samp{bananana}, etc., with any (zero or more) number of @samp{na} +strings.@refill + +@item +To record a matched substring for future reference. +@end enumerate + +This last application is not a consequence of the idea of a +parenthetical grouping; it is a separate feature that is assigned as a +second meaning to the same @samp{\( @dots{} \)} construct. In practice +there is no conflict between the two meanings. + +@item \@var{d} +matches the same text that matched the @var{d}th occurrence of a +@samp{\( @dots{} \)} construct. + +After the end of a @samp{\( @dots{} \)} construct, the matcher remembers +the beginning and end of the text matched by that construct. Then, +later on in the regular expression, you can use @samp{\} followed by the +digit @var{d} to mean ``match the same text matched the @var{d}th time +by the @samp{\( @dots{} \)} construct.'' + +The strings matching the first nine @samp{\( @dots{} \)} constructs +appearing in a regular expression are assigned numbers 1 through 9 in +the order that the open-parentheses appear in the regular expression. +So you can use @samp{\1} through @samp{\9} to refer to the text matched +by the corresponding @samp{\( @dots{} \)} constructs. + +For example, @samp{\(.*\)\1} matches any newline-free string that is +composed of two identical halves. The @samp{\(.*\)} matches the first +half, which may be anything, but the @samp{\1} that follows must match +the same exact text. + +If a particular @samp{\( @dots{} \)} construct matches more than once +(which can easily happen if it is followed by @samp{*}), only the last +match is recorded. + +@item \` +matches the empty string, but only at the beginning +of the buffer or string being matched against. + +@item \' +matches the empty string, but only at the end of +the buffer or string being matched against. + +@item \= +matches the empty string, but only at point. + +@item \b +matches the empty string, but only at the beginning or +end of a word. Thus, @samp{\bfoo\b} matches any occurrence of +@samp{foo} as a separate word. @samp{\bballs?\b} matches +@samp{ball} or @samp{balls} as a separate word.@refill + +@samp{\b} matches at the beginning or end of the buffer +regardless of what text appears next to it. + +@item \B +matches the empty string, but @emph{not} at the beginning or +end of a word. + +@item \< +matches the empty string, but only at the beginning of a word. +@samp{\<} matches at the beginning of the buffer only if a +word-constituent character follows. + +@item \> +matches the empty string, but only at the end of a word. @samp{\>} +matches at the end of the buffer only if the contents end with a +word-constituent character. + +@item \w +matches any word-constituent character. The syntax table +determines which characters these are. @xref{Syntax}. + +@item \W +matches any character that is not a word-constituent. + +@item \s@var{c} +matches any character whose syntax is @var{c}. Here @var{c} is a +character that represents a syntax code: thus, @samp{w} for word +constituent, @samp{-} for whitespace, @samp{(} for open parenthesis, +etc. Represent a character of whitespace (which can be a newline) by +either @samp{-} or a space character. + +@item \S@var{c} +matches any character whose syntax is not @var{c}. +@end table + + The constructs that pertain to words and syntax are controlled by the +setting of the syntax table (@pxref{Syntax}). + + Here is a complicated regexp, used by Emacs to recognize the end of a +sentence together with any whitespace that follows. It is given in Lisp +syntax to enable you to distinguish the spaces from the tab characters. In +Lisp syntax, the string constant begins and ends with a double-quote. +@samp{\"} stands for a double-quote as part of the regexp, @samp{\\} for a +backslash as part of the regexp, @samp{\t} for a tab and @samp{\n} for a +newline. + +@example +"[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*" +@end example + +@noindent +This contains four parts in succession: a character set matching period, +@samp{?}, or @samp{!}; a character set matching close-brackets, quotes, +or parentheses, repeated any number of times; an alternative in +backslash-parentheses that matches end-of-line, a tab, or two spaces; +and a character set matching whitespace characters, repeated any number +of times. + + To enter the same regexp interactively, you would type @key{TAB} to +enter a tab, and @kbd{C-j} to enter a newline. You would also type +single backslashes as themselves, instead of doubling them for Lisp syntax. + +@node Search Case, Replace, Regexps, Search +@section Searching and Case + +@vindex case-fold-search + Incremental searches in Emacs normally ignore the case of the text +they are searching through, if you specify the text in lower case. +Thus, if you specify searching for @samp{foo}, then @samp{Foo} and +@samp{foo} are also considered a match. Regexps, and in particular +character sets, are included: @samp{[ab]} would match @samp{a} or +@samp{A} or @samp{b} or @samp{B}.@refill + + An upper-case letter anywhere in the incremental search string makes +the search case-sensitive. Thus, searching for @samp{Foo} does not find +@samp{foo} or @samp{FOO}. This applies to regular expression search as +well as to string search. The effect ceases if you delete the +upper-case letter from the search string. + + If you set the variable @code{case-fold-search} to @code{nil}, then +all letters must match exactly, including case. This is a per-buffer +variable; altering the variable affects only the current buffer, but +there is a default value which you can change as well. @xref{Locals}. +This variable applies to nonincremental searches also, including those +performed by the replace commands (@pxref{Replace}) and the minibuffer +history matching commands (@pxref{Minibuffer History}). + +@node Replace, Other Repeating Search, Search Case, Search +@section Replacement Commands +@cindex replacement +@cindex search-and-replace commands +@cindex string substitution +@cindex global substitution + + Global search-and-replace operations are not needed as often in Emacs +as they are in other editors@footnote{In some editors, +search-and-replace operations are the only convenient way to make a +single change in the text.}, but they are available. In addition to the +simple @kbd{M-x replace-string} command which is like that found in most +editors, there is a @kbd{M-x query-replace} command which asks you, for +each occurrence of the pattern, whether to replace it. + + The replace commands normally operate on the text from point to the +end of the buffer; however, in Transient Mark mode, when the mark is +active, they operate on the region. The replace commands all replace +one string (or regexp) with one replacement string. It is possible to +perform several replacements in parallel using the command +@code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}). + +@menu +* Unconditional Replace:: Replacing all matches for a string. +* Regexp Replace:: Replacing all matches for a regexp. +* Replacement and Case:: How replacements preserve case of letters. +* Query Replace:: How to use querying. +@end menu + +@node Unconditional Replace, Regexp Replace, Replace, Replace +@subsection Unconditional Replacement +@findex replace-string +@findex replace-regexp + +@table @kbd +@item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} +Replace every occurrence of @var{string} with @var{newstring}. +@item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} +Replace every match for @var{regexp} with @var{newstring}. +@end table + + To replace every instance of @samp{foo} after point with @samp{bar}, +use the command @kbd{M-x replace-string} with the two arguments +@samp{foo} and @samp{bar}. Replacement happens only in the text after +point, so if you want to cover the whole buffer you must go to the +beginning first. All occurrences up to the end of the buffer are +replaced; to limit replacement to part of the buffer, narrow to that +part of the buffer before doing the replacement (@pxref{Narrowing}). +In Transient Mark mode, when the region is active, replacement is +limited to the region (@pxref{Transient Mark}). + + When @code{replace-string} exits, it leaves point at the last +occurrence replaced. It sets the mark to the prior position of point +(where the @code{replace-string} command was issued); use @kbd{C-u +C-@key{SPC}} to move back there. + + A numeric argument restricts replacement to matches that are surrounded +by word boundaries. The argument's value doesn't matter. + +@node Regexp Replace, Replacement and Case, Unconditional Replace, Replace +@subsection Regexp Replacement + + The @kbd{M-x replace-string} command replaces exact matches for a +single string. The similar command @kbd{M-x replace-regexp} replaces +any match for a specified pattern. + + In @code{replace-regexp}, the @var{newstring} need not be constant: it +can refer to all or part of what is matched by the @var{regexp}. +@samp{\&} in @var{newstring} stands for the entire match being replaced. +@samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, stands for +whatever matched the @var{d}th parenthesized grouping in @var{regexp}. +To include a @samp{\} in the text to replace with, you must enter +@samp{\\}. For example, + +@example +M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET} +@end example + +@noindent +replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr} +with @samp{cddr-safe}. + +@example +M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET} +@end example + +@noindent +performs the inverse transformation. + +@node Replacement and Case, Query Replace, Regexp Replace, Replace +@subsection Replace Commands and Case + + If the first argument of a replace command is all lower case, the +commands ignores case while searching for occurrences to +replace---provided @code{case-fold-search} is non-@code{nil}. If +@code{case-fold-search} is set to @code{nil}, case is always significant +in all searches. + +@vindex case-replace + In addition, when the @var{newstring} argument is all or partly lower +case, replacement commands try to preserve the case pattern of each +occurrence. Thus, the command + +@example +M-x replace-string @key{RET} foo @key{RET} bar @key{RET} +@end example + +@noindent +replaces a lower case @samp{foo} with a lower case @samp{bar}, an +all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with +@samp{Bar}. (These three alternatives---lower case, all caps, and +capitalized, are the only ones that @code{replace-string} can +distinguish.) + + If upper-case letters are used in the replacement string, they remain +upper case every time that text is inserted. If upper-case letters are +used in the first argument, the second argument is always substituted +exactly as given, with no case conversion. Likewise, if either +@code{case-replace} or @code{case-fold-search} is set to @code{nil}, +replacement is done without case conversion. + +@node Query Replace,, Replacement and Case, Replace +@subsection Query Replace +@cindex query replace + +@table @kbd +@item M-% @var{string} @key{RET} @var{newstring} @key{RET} +@itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} +Replace some occurrences of @var{string} with @var{newstring}. +@item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET} +@itemx M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} +Replace some matches for @var{regexp} with @var{newstring}. +@end table + +@kindex M-% +@findex query-replace + If you want to change only some of the occurrences of @samp{foo} to +@samp{bar}, not all of them, then you cannot use an ordinary +@code{replace-string}. Instead, use @kbd{M-%} (@code{query-replace}). +This command finds occurrences of @samp{foo} one by one, displays each +occurrence and asks you whether to replace it. A numeric argument to +@code{query-replace} tells it to consider only occurrences that are +bounded by word-delimiter characters. This preserves case, just like +@code{replace-string}, provided @code{case-replace} is non-@code{nil}, +as it normally is. + +@kindex C-M-% +@findex query-replace-regexp + Aside from querying, @code{query-replace} works just like +@code{replace-string}, and @code{query-replace-regexp} works just like +@code{replace-regexp}. This command is run by @kbd{C-M-%}. + + The things you can type when you are shown an occurrence of @var{string} +or a match for @var{regexp} are: + +@ignore @c Not worth it. +@kindex SPC @r{(query-replace)} +@kindex DEL @r{(query-replace)} +@kindex , @r{(query-replace)} +@kindex RET @r{(query-replace)} +@kindex . @r{(query-replace)} +@kindex ! @r{(query-replace)} +@kindex ^ @r{(query-replace)} +@kindex C-r @r{(query-replace)} +@kindex C-w @r{(query-replace)} +@kindex C-l @r{(query-replace)} +@end ignore + +@c WideCommands +@table @kbd +@item @key{SPC} +to replace the occurrence with @var{newstring}. + +@item @key{DEL} +to skip to the next occurrence without replacing this one. + +@item , @r{(Comma)} +to replace this occurrence and display the result. You are then asked +for another input character to say what to do next. Since the +replacement has already been made, @key{DEL} and @key{SPC} are +equivalent in this situation; both move to the next occurrence. + +You can type @kbd{C-r} at this point (see below) to alter the replaced +text. You can also type @kbd{C-x u} to undo the replacement; this exits +the @code{query-replace}, so if you want to do further replacement you +must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart +(@pxref{Repetition}). + +@item @key{RET} +to exit without doing any more replacements. + +@item .@: @r{(Period)} +to replace this occurrence and then exit without searching for more +occurrences. + +@item ! +to replace all remaining occurrences without asking again. + +@item ^ +to go back to the position of the previous occurrence (or what used to +be an occurrence), in case you changed it by mistake. This works by +popping the mark ring. Only one @kbd{^} in a row is meaningful, because +only one previous replacement position is kept during @code{query-replace}. + +@item C-r +to enter a recursive editing level, in case the occurrence needs to be +edited rather than just replaced with @var{newstring}. When you are +done, exit the recursive editing level with @kbd{C-M-c} to proceed to +the next occurrence. @xref{Recursive Edit}. + +@item C-w +to delete the occurrence, and then enter a recursive editing level as in +@kbd{C-r}. Use the recursive edit to insert text to replace the deleted +occurrence of @var{string}. When done, exit the recursive editing level +with @kbd{C-M-c} to proceed to the next occurrence. + +@item C-l +to redisplay the screen. Then you must type another character to +specify what to do with this occurrence. + +@item C-h +to display a message summarizing these options. Then you must type +another character to specify what to do with this occurrence. +@end table + + Some other characters are aliases for the ones listed above: @kbd{y}, +@kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and +@key{RET}. + + Aside from this, any other character exits the @code{query-replace}, +and is then reread as part of a key sequence. Thus, if you type +@kbd{C-k}, it exits the @code{query-replace} and then kills to end of +line. + + To restart a @code{query-replace} once it is exited, use @kbd{C-x +@key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it +used the minibuffer to read its arguments. @xref{Repetition, C-x ESC +ESC}. + + See also @ref{Transforming File Names}, for Dired commands to rename, +copy, or link files by replacing regexp matches in file names. + +@node Other Repeating Search,, Replace, Search +@section Other Search-and-Loop Commands + + Here are some other commands that find matches for a regular +expression. They all operate from point to the end of the buffer, and +all ignore case in matching, if the pattern contains no upper-case +letters and @code{case-fold-search} is non-@code{nil}. + +@findex list-matching-lines +@findex occur +@findex count-matches +@findex delete-non-matching-lines +@findex delete-matching-lines +@findex flush-lines +@findex keep-lines + +@table @kbd +@item M-x occur @key{RET} @var{regexp} @key{RET} +Display a list showing each line in the buffer that contains a match for +@var{regexp}. A numeric argument specifies the number of context lines +to print before and after each matching line; the default is none. +To limit the search to part of the buffer, narrow to that part +(@pxref{Narrowing}). + +@kindex RET @r{(Occur mode)} +The buffer @samp{*Occur*} containing the output serves as a menu for +finding the occurrences in their original context. Click @kbd{Mouse-2} +on an occurrence listed in @samp{*Occur*}, or position point there and +type @key{RET}; this switches to the buffer that was searched and +moves point to the original of the chosen occurrence. + +@item M-x list-matching-lines +Synonym for @kbd{M-x occur}. + +@item M-x count-matches @key{RET} @var{regexp} @key{RET} +Print the number of matches for @var{regexp} after point. + +@item M-x flush-lines @key{RET} @var{regexp} @key{RET} +Delete each line that follows point and contains a match for +@var{regexp}. + +@item M-x keep-lines @key{RET} @var{regexp} @key{RET} +Delete each line that follows point and @emph{does not} contain a match +for @var{regexp}. +@end table + + In addition, you can use @code{grep} from Emacs to search a collection +of files for matches for a regular expression, then visit the matches +either sequentially or in arbitrary order. @xref{Grep Searching}. diff --git a/man/sending.texi b/man/sending.texi new file mode 100644 index 00000000000..3ca862cc1af --- /dev/null +++ b/man/sending.texi @@ -0,0 +1,643 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Sending Mail, Rmail, Picture, Top +@chapter Sending Mail +@cindex sending mail +@cindex mail +@cindex message + + To send a message in Emacs, you start by typing a command (@kbd{C-x m}) +to select and initialize the @samp{*mail*} buffer. Then you edit the text +and headers of the message in this buffer, and type another command +(@kbd{C-c C-s} or @kbd{C-c C-c}) to send the message. + +@table @kbd +@item C-x m +Begin composing a message to send (@code{compose-mail}). +@item C-x 4 m +Likewise, but display the message in another window +(@code{compose-mail-other-window}). +@item C-x 5 m +Likewise, but make a new frame (@code{compose-mail-other-frame}). +@item C-c C-s +In Mail mode, send the message (@code{mail-send}). +@item C-c C-c +Send the message and bury the mail buffer (@code{mail-send-and-exit}). +@end table + +@kindex C-x m +@findex compose-mail +@kindex C-x 4 m +@findex compose-mail-other-window +@kindex C-x 5 m +@findex compose-mail-other-frame + The command @kbd{C-x m} (@code{compose-mail}) selects a buffer named +@samp{*mail*} and initializes it with the skeleton of an outgoing +message. @kbd{C-x 4 m} (@code{compose-mail-other-window}) selects the +@samp{*mail*} buffer in a different window, leaving the previous current +buffer visible. @kbd{C-x 5 m} (@code{compose-mail-other-frame}) creates +a new frame to select the @samp{*mail*} buffer. + + Because the mail-composition buffer is an ordinary Emacs buffer, you can +switch to other buffers while in the middle of composing mail, and switch +back later (or never). If you use the @kbd{C-x m} command again when you +have been composing another message but have not sent it, you are asked to +confirm before the old message is erased. If you answer @kbd{n}, the +@samp{*mail*} buffer is left selected with its old contents, so you can +finish the old message and send it. @kbd{C-u C-x m} is another way to do +this. Sending the message marks the @samp{*mail*} buffer ``unmodified,'' +which avoids the need for confirmation when @kbd{C-x m} is next used. + + If you are composing a message in the @samp{*mail*} buffer and want to +send another message before finishing the first, rename the +@samp{*mail*} buffer using @kbd{M-x rename-uniquely} (@pxref{Misc +Buffer}). Then you can use @kbd{C-x m} or its variants described above +to make a new @samp{*mail*} buffer. Once you've done that, you can work +with each mail buffer independently. + +@menu +* Format: Mail Format. Format of the mail being composed. +* Headers: Mail Headers. Details of permitted mail header fields. +* Aliases: Mail Aliases. Abbreviating and grouping mail addresses. +* Mode: Mail Mode. Special commands for editing mail being composed. +* Spook: Distracting NSA. How to distract the NSA's attention. +* Mail Methods:: Using alternative mail-composition methods. +@end menu + +@node Mail Format +@section The Format of the Mail Buffer + + In addition to the @dfn{text} or @dfn{body}, a message has @dfn{header +fields} which say who sent it, when, to whom, why, and so on. Some +header fields, such as @samp{Date} and @samp{Sender}, are created +automatically when you send the message. Others, such as the recipient +names, must be specified by you in order to send the message properly. + + Mail mode provides a few commands to help you edit some header fields, +and some are preinitialized in the buffer automatically at times. You can +insert and edit header fields using ordinary editing commands. + + The line in the buffer that says + +@example +--text follows this line-- +@end example + +@noindent +is a special delimiter that separates the headers you have specified from +the text. Whatever follows this line is the text of the message; the +headers precede it. The delimiter line itself does not appear in the +message actually sent. The text used for the delimiter line is controlled +by the variable @code{mail-header-separator}. + +Here is an example of what the headers and text in the mail buffer +might look like. + +@example +To: gnu@@gnu.org +CC: lungfish@@spam.org, byob@@spam.org +Subject: The Emacs Manual +--Text follows this line-- +Please ignore this message. +@end example + +@node Mail Headers +@section Mail Header Fields +@cindex headers (of mail message) + + A header field in the mail buffer starts with a field name at the +beginning of a line, terminated by a colon. Upper and lower case are +equivalent in field names (and in mailing addresses also). After the +colon and optional whitespace comes the contents of the field. + + You can use any name you like for a header field, but normally people +use only standard field names with accepted meanings. Here is a table +of fields commonly used in outgoing messages. + +@table @samp +@item To +This field contains the mailing addresses to which the message is +addressed. If you list more than one address, use commas, not spaces, +to separate them. + +@item Subject +The contents of the @samp{Subject} field should be a piece of text +that says what the message is about. The reason @samp{Subject} fields +are useful is that most mail-reading programs can provide a summary of +messages, listing the subject of each message but not its text. + +@item CC +This field contains additional mailing addresses to send the message to, +like @samp{To} except that these readers should not regard the message +as directed at them. + +@item BCC +This field contains additional mailing addresses to send the message to, +which should not appear in the header of the message actually sent. +Copies sent this way are called @dfn{blind carbon copies}. + +@vindex mail-self-blind +To send a blind carbon copy of every outgoing message to yourself, set +the variable @code{mail-self-blind} to @code{t}. + +@item FCC +This field contains the name of one file and directs Emacs to append a +copy of the message to that file when you send the message. If the file +is in Rmail format, Emacs writes the message in Rmail format; otherwise, +Emacs writes the message in system mail file format. + +@vindex mail-archive-file-name +To put a fixed file name in the @samp{FCC} field each time you start +editing an outgoing message, set the variable +@code{mail-archive-file-name} to that file name. Unless you remove the +@samp{FCC} field before sending, the message will be written into that +file when it is sent. + +@item From +Use the @samp{From} field to say who you are, when the account you are +using to send the mail is not your own. The contents of the @samp{From} +field should be a valid mailing address, since replies will normally go +there. If you don't specify the @samp{From} field yourself, Emacs uses +the value of @code{user-mail-address} as the default. + +@item Reply-to +Use this field to direct replies to a different address. Most +mail-reading programs (including Rmail) automatically send replies to +the @samp{Reply-to} address in preference to the @samp{From} address. +By adding a @samp{Reply-to} field to your header, you can work around +any problems your @samp{From} address may cause for replies. + +@cindex @code{REPLYTO} environment variable +@vindex mail-default-reply-to +To put a fixed @samp{Reply-to} address into every outgoing message, set +the variable @code{mail-default-reply-to} to that address (as a string). +Then @code{mail} initializes the message with a @samp{Reply-to} field as +specified. You can delete or alter that header field before you send +the message, if you wish. When Emacs starts up, if the environment +variable @code{REPLYTO} is set, @code{mail-default-reply-to} is +initialized from that environment variable. + +@item In-reply-to +This field contains a piece of text describing a message you are +replying to. Some mail systems can use this information to correlate +related pieces of mail. Normally this field is filled in by Rmail +when you reply to a message in Rmail, and you never need to +think about it (@pxref{Rmail}). + +@item References +This field lists the message IDs of related previous messages. Rmail +sets up this field automatically when you reply to a message. +@end table + + The @samp{To}, @samp{CC}, @samp{BCC} and @samp{FCC} header fields can +appear any number of times, and each such header field can contain +multiple addresses, separated by commas. This way, you can specify any +number of places to send the message. A @samp{To}, @samp{CC}, or +@samp{BCC} field can also have continuation lines: one or more lines +starting with whitespace, following the starting line of the field, are +considered part of the field. Here's an example of a @samp{To} field +with a continuation line:@refill + +@example +@group +To: foo@@here.net, this@@there.net, + me@@gnu.cambridge.mass.usa.earth.spiral3281 +@end group +@end example + +@vindex mail-from-style + When you send the message, if you didn't write a @samp{From} field +yourself, Emacs puts in one for you. The variable +@code{mail-from-style} controls the format: + +@table @code +@item nil +Use just the email address, as in @samp{king@@grassland.com}. +@item parens +Use both email address and full name, as in @samp{king@@grassland.com (Elvis +Parsley)}. +@item angles +Use both email address and full name, as in @samp{Elvis Parsley +<king@@grassland.com>}. +@item system-default +Allow the system to insert the @samp{From} field. +@end table + +@node Mail Aliases +@section Mail Aliases +@cindex mail aliases +@cindex @file{.mailrc} file +@cindex mailrc file + + You can define @dfn{mail aliases} in a file named @file{~/.mailrc}. +These are short mnemonic names which stand for mail addresses or groups of +mail addresses. Like many other mail programs, Emacs expands aliases +when they occur in the @samp{To}, @samp{From}, @samp{CC}, @samp{BCC}, and +@samp{Reply-to} fields, plus their @samp{Resent-} variants. + + To define an alias in @file{~/.mailrc}, write a line in the following +format: + +@example +alias @var{shortaddress} @var{fulladdresses} +@end example + +@noindent +Here @var{fulladdresses} stands for one or more mail addresses for +@var{shortaddress} to expand into. Separate multiple addresses with +spaces; if an address contains a space, quote the whole address with a +pair of double-quotes. + +For instance, to make @code{maingnu} stand for +@code{gnu@@gnu.org} plus a local address of your own, put in +this line:@refill + +@example +alias maingnu gnu@@gnu.org local-gnu +@end example + + Emacs also recognizes include commands in @samp{.mailrc} files. +They look like this: + +@example +source @var{filename} +@end example + +@noindent +The file @file{~/.mailrc} is used primarily by other mail-reading +programs; it can contain various other commands. Emacs ignores +everything in it except for alias definitions and include commands. + +@findex define-mail-alias + Another way to define a mail alias, within Emacs alone, is with the +@code{define-mail-alias} command. It prompts for the alias and then the +full address. You can use it to define aliases in your @file{.emacs} +file, like this: + +@example +(define-mail-alias "maingnu" "gnu@@gnu.org") +@end example + +@vindex mail-aliases + @code{define-mail-alias} records aliases by adding them to a +variable named @code{mail-aliases}. If you are comfortable with +manipulating Lisp lists, you can set @code{mail-aliases} directly. The +initial value of @code{mail-aliases} is @code{t}, which means that +Emacs should read @file{.mailrc} to get the proper value. + +@vindex mail-personal-alias-file + You can specify a different file name to use instead of +@file{~/.mailrc} by setting the variable +@code{mail-personal-alias-file}. + +@findex expand-mail-aliases + Normally, Emacs expands aliases when you send the message. You do not +need to expand mail aliases before sending the message, but you can +expand them if you want to see where the mail will actually go. To do +this, use the command @kbd{M-x expand-mail-aliases}; it expands all mail +aliases currently present in the mail headers that hold addresses. + + If you like, you can have mail aliases expand as abbrevs, as soon as +you type them in (@pxref{Abbrevs}). To enable this feature, execute the +following: + +@example +(add-hook 'mail-setup-hook 'mail-abbrevs-setup) +@end example + +@noindent +@findex define-mail-abbrev +@vindex mail-abbrevs +This can go in your @file{.emacs} file. @xref{Hooks}. If you use this +feature, you must use @code{define-mail-abbrev} instead of +@code{define-mail-alias}; the latter does not work with this package. +Note that the mail abbreviation package uses the variable +@code{mail-abbrevs} instead of @code{mail-aliases}, and that all alias +names are converted to lower case. + +@kindex C-c C-a @r{(Mail mode)} +@findex mail-interactive-insert-alias + The mail abbreviation package also provides the @kbd{C-c C-a} +(@code{mail-interactive-insert-alias}) command, which reads an alias +name (with completion) and inserts its definition at point. This is +useful when editing the message text itself or a header field such as +@samp{Subject} in which Emacs does not normally expand aliases. + + Note that abbrevs expand only if you insert a word-separator character +afterward. However, you can rebind @kbd{C-n} and @kbd{M->} to cause +expansion as well. Here's how to do that: + +@smallexample +(add-hook 'mail-setup-hook + '(lambda () + (substitute-key-definition + 'next-line 'mail-abbrev-next-line + mail-mode-map global-map) + (substitute-key-definition + 'end-of-buffer 'mail-abbrev-end-of-buffer + mail-mode-map global-map))) +@end smallexample + +@node Mail Mode +@section Mail Mode +@cindex Mail mode +@cindex mode, Mail + + The major mode used in the mail buffer is Mail mode, which is much +like Text mode except that various special commands are provided on the +@kbd{C-c} prefix. These commands all have to do specifically with +editing or sending the message. In addition, Mail mode defines the +character @samp{%} as a word separator; this is helpful for using the +word commands to edit mail addresses. + + Mail mode is normally used in buffers set up automatically by the +@code{mail} command and related commands. However, you can also switch +to Mail mode in a file-visiting buffer. That is a useful thing to do if +you have saved draft message text in a file. + +@menu +* Mail Sending:: Commands to send the message. +* Header Editing:: Commands to move to header fields and edit them. +* Citing Mail:: Copying all or part of a message you are replying to. +* Mail Mode Misc:: Spell checking, signatures, etc. +@end menu + +@node Mail Sending +@subsection Mail Sending + + Mail mode has two commands for sending the message you have been +editing: + +@table @kbd +@item C-c C-s +Send the message, and leave the mail buffer selected (@code{mail-send}). +@item C-c C-c +Send the message, and select some other buffer (@code{mail-send-and-exit}). +@end table + +@kindex C-c C-s @r{(Mail mode)} +@kindex C-c C-c @r{(Mail mode)} +@findex mail-send +@findex mail-send-and-exit + @kbd{C-c C-s} (@code{mail-send}) sends the message and marks the mail +buffer unmodified, but leaves that buffer selected so that you can +modify the message (perhaps with new recipients) and send it again. +@kbd{C-c C-c} (@code{mail-send-and-exit}) sends and then deletes the +window or switches to another buffer. It puts the mail buffer at the +lowest priority for reselection by default, since you are finished with +using it. This is the usual way to send the message. + + In a file-visiting buffer, sending the message does not clear the +modified flag, because only saving the file should do that. As a +result, you don't get a warning if you try to send the same message +twice. + +@vindex sendmail-coding-system + When you send a message that contains non-ASCII characters, they need +to be encoded with a coding system (@pxref{Coding Systems}). Usually +the coding system is specified automatically by your chosen language +environment (@pxref{Language Environments}). You can explicitly specify +the coding system for outgoing mail by setting the variable +@code{sendmail-coding-system}. + + If the coding system thus determined does not handle the characters in +a particular message, Emacs asks you to select the coding system to use, +showing a list of possible coding systems. + +@node Header Editing +@subsection Mail Header Editing + + Mail mode provides special commands to move to particular header +fields and to complete addresses in headers. + +@table @kbd +@item C-c C-f C-t +Move to the @samp{To} header field, creating one if there is none +(@code{mail-to}). +@item C-c C-f C-s +Move to the @samp{Subject} header field, creating one if there is +none (@code{mail-subject}). +@item C-c C-f C-c +Move to the @samp{CC} header field, creating one if there is none +(@code{mail-cc}). +@item C-c C-f C-b +Move to the @samp{BCC} header field, creating one if there is none +(@code{mail-bcc}). +@item C-c C-f C-f +Move to the @samp{FCC} header field, creating one if there is none +(@code{mail-fcc}). +@item M-@key{TAB} +Complete a mailing address (@code{mail-complete}). +@end table + +@kindex C-c C-f C-t @r{(Mail mode)} +@findex mail-to +@kindex C-c C-f C-s @r{(Mail mode)} +@findex mail-subject +@kindex C-c C-f C-c @r{(Mail mode)} +@findex mail-cc +@kindex C-c C-f C-b @r{(Mail mode)} +@findex mail-bcc +@kindex C-c C-f C-f @r{(Mail mode)} +@findex mail-fcc + There are five commands to move point to particular header fields, all +based on the prefix @kbd{C-c C-f} (@samp{C-f} is for ``field''). They +are listed in the table above. If the field in question does not exist, +these commands create one. We provide special motion commands for these +particular fields because they are the fields users most often want to +edit. + +@findex mail-complete +@kindex M-TAB @r{(Mail mode)} + While editing a header field that contains mailing addresses, such as +@samp{To:}, @samp{CC:} and @samp{BCC:}, you can complete a mailing +address by typing @kbd{M-@key{TAB}} (@code{mail-complete}). It inserts +the full name corresponding to the address, if it can determine the full +name. The variable @code{mail-complete-style} controls whether to insert +the full name, and what style to use, as in @code{mail-from-style} +(@pxref{Mail Headers}). + + For completion purposes, the valid mailing addresses are taken to be +the local users' names plus your personal mail aliases. You can specify +additional sources of valid addresses; use the customization buffer +to see the options for this. + + If you type @kbd{M-@key{TAB}} in the body of the message, it invokes +@code{ispell-complete-word}, as in Text mode. + +@node Citing Mail +@subsection Citing Mail +@cindex citing mail + + Mail mode also has commands for yanking or @dfn{citing} all or part of +a message that you are replying to. These commands are active only when +you started sending a message using an Rmail command. + +@table @kbd +@item C-c C-y +Yank the selected message from Rmail (@code{mail-yank-original}). +@item C-c C-r +Yank the region from the Rmail buffer (@code{mail-yank-region}). +@item C-c C-q +Fill each paragraph cited from another message +(@code{mail-fill-yanked-message}). +@end table + +@kindex C-c C-y @r{(Mail mode)} +@findex mail-yank-original + When mail sending is invoked from the Rmail mail reader using an Rmail +command, @kbd{C-c C-y} can be used inside the mail buffer to insert +the text of the message you are replying to. Normally it indents each line +of that message three spaces and eliminates most header fields. A numeric +argument specifies the number of spaces to indent. An argument of just +@kbd{C-u} says not to indent at all and not to eliminate anything. +@kbd{C-c C-y} always uses the current message from the Rmail buffer, +so you can insert several old messages by selecting one in Rmail, +switching to @samp{*mail*} and yanking it, then switching back to +Rmail to select another. + +@vindex mail-yank-prefix + You can specify the text for @kbd{C-c C-y} to insert at the beginning +of each line: set @code{mail-yank-prefix} to the desired string. (A +value of @code{nil} means to use indentation; this is the default.) +However, @kbd{C-u C-c C-y} never adds anything at the beginning of the +inserted lines, regardless of the value of @code{mail-yank-prefix}. + +@kindex C-c C-r @r{(Mail mode)} +@findex mail-yank-region + To yank just a part of an incoming message, set the region in Rmail to +the part you want; then go to the @samp{*Mail*} message and type +@kbd{C-c C-r} (@code{mail-yank-region}). Each line that is copied is +indented or prefixed according to @code{mail-yank-prefix}. + +@kindex C-c C-q @r{(Mail mode)} +@findex mail-fill-yanked-message + After using @kbd{C-c C-y} or @kbd{C-c C-r}, you can type @kbd{C-c C-q} +(@code{mail-fill-yanked-message}) to fill the paragraphs of the yanked +old message or messages. One use of @kbd{C-c C-q} fills all such +paragraphs, each one individually. To fill a single paragraph of the +quoted message, use @kbd{M-q}. If filling does not automatically +handle the type of citation prefix you use, try setting the fill prefix +explicitly. @xref{Filling}. + +@node Mail Mode Misc +@subsection Mail Mode Miscellany + +@table @kbd +@item C-c C-t +Move to the beginning of the message body text (@code{mail-text}). +@item C-c C-w +Insert the file @file{~/.signature} at the end of the message text +(@code{mail-signature}). +@item C-c C-i @var{file} @key{RET} +Insert the contents of @var{file} at the end of the outgoing message +(@code{mail-attach-file}). +@item M-x ispell-message +Do spelling correction on the message text, but not on citations from +other messages. +@end table + +@kindex C-c C-t @r{(Mail mode)} +@findex mail-text + @kbd{C-c C-t} (@code{mail-text}) moves point to just after the header +separator line---that is, to the beginning of the message body text. + +@kindex C-c C-w @r{(Mail mode)} +@findex mail-signature +@vindex mail-signature + @kbd{C-c C-w} (@code{mail-signature}) adds a standard piece of text at +the end of the message to say more about who you are. The text comes +from the file @file{~/.signature} in your home directory. To insert +your signature automatically, set the variable @code{mail-signature} to +@code{t}; then starting a mail message automatically inserts the +contents of your @file{~/.signature} file. If you want to omit your +signature from a particular message, delete it from the buffer before +you send the message. + + You can also set @code{mail-signature} to a string; then that string +is inserted automatically as your signature when you start editing a +message to send. If you set it to some other Lisp expression, the +expression is evaluated each time, and its value (which should be a +string) specifies the signature. + +@findex ispell-message + You can do spelling correction on the message text you have written +with the command @kbd{M-x ispell-message}. If you have yanked an +incoming message into the outgoing draft, this command skips what was +yanked, but it checks the text that you yourself inserted. (It looks +for indentation or @code{mail-yank-prefix} to distinguish the cited +lines from your input.) @xref{Spelling}. + +@kindex C-c C-i @r{(Mail mode)} +@findex mail-attach-file + To include a file in the outgoing message, you can use @kbd{C-x i}, +the usual command to insert a file in the current buffer. But it is +often more convenient to use a special command, @kbd{C-c C-i} +(@code{mail-attach-file}). This command inserts the file contents at +the end of the buffer, after your signature if any, with a delimiter +line that includes the file name. + +@vindex mail-mode-hook +@vindex mail-setup-hook + Turning on Mail mode (which @kbd{C-x m} does automatically) runs the +normal hooks @code{text-mode-hook} and @code{mail-mode-hook}. +Initializing a new outgoing message runs the normal hook +@code{mail-setup-hook}; if you want to add special fields to your mail +header or make other changes to the appearance of the mail buffer, use +that hook. @xref{Hooks}. + + The main difference between these hooks is just when they are +invoked. Whenever you type @kbd{M-x mail}, @code{mail-mode-hook} runs +as soon as the @samp{*mail*} buffer is created. Then the +@code{mail-setup} function puts in the default contents of the buffer. +After these default contents are inserted, @code{mail-setup-hook} runs. + +@node Distracting NSA +@section Distracting the NSA + +@findex spook +@cindex NSA + @kbd{M-x spook} adds a line of randomly chosen keywords to an outgoing +mail message. The keywords are chosen from a list of words that suggest +you are discussing something subversive. + + The idea behind this feature is the suspicion that the NSA snoops on +all electronic mail messages that contain keywords suggesting they might +find them interesting. (The NSA says they don't, but that's what they +@emph{would} say.) The idea is that if lots of people add suspicious +words to their messages, the NSA will get so busy with spurious input +that they will have to give up reading it all. + + Here's how to insert spook keywords automatically whenever you start +entering an outgoing message: + +@example +(add-hook 'mail-setup-hook 'spook) +@end example + + Whether or not this confuses the NSA, it at least amuses people. + +@node Mail Methods +@section Mail-Composition Methods +@cindex mail-composition methods + + This chapter describes the usual Emacs mode for editing and sending +mail---Mail mode. Emacs has alternative facilities for editing and +sending mail, including MH-E and Message mode, not documented in this +manual. You can choose any of them as your preferred method. The +commands @code{C-x m}, @code{C-x 4 m} and @code{C-x 5 m} use whichever +agent you have specified. So do various other Emacs commands and +facilities that send mail. + +@vindex mail-user-agent + To specify your mail-composition method, set the variable +@code{mail-user-agent}. Currently legitimate values include +@code{sendmail-user-agent}, @code{mh-e-user-agent}, and +@code{message-user-agent}. + + If you select a different mail-composition method, the information in +this chapter about the @samp{*mail*} buffer and Mail mode does not +apply; other methods may use completely different commands with a +different format in a differently named buffer. + diff --git a/man/text.texi b/man/text.texi new file mode 100644 index 00000000000..273a3d42f3e --- /dev/null +++ b/man/text.texi @@ -0,0 +1,1965 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Text, Programs, Indentation, Top +@chapter Commands for Human Languages +@cindex text +@cindex manipulating text + + The term @dfn{text} has two widespread meanings in our area of the +computer field. One is data that is a sequence of characters. Any file +that you edit with Emacs is text, in this sense of the word. The other +meaning is more restrictive: a sequence of characters in a human language +for humans to read (possibly after processing by a text formatter), as +opposed to a program or commands for a program. + + Human languages have syntactic/stylistic conventions that can be +supported or used to advantage by editor commands: conventions involving +words, sentences, paragraphs, and capital letters. This chapter +describes Emacs commands for all of these things. There are also +commands for @dfn{filling}, which means rearranging the lines of a +paragraph to be approximately equal in length. The commands for moving +over and killing words, sentences and paragraphs, while intended +primarily for editing text, are also often useful for editing programs. + + Emacs has several major modes for editing human-language text. If the +file contains text pure and simple, use Text mode, which customizes +Emacs in small ways for the syntactic conventions of text. Outline mode +provides special commands for operating on text with an outline +structure. +@iftex +@xref{Outline Mode}. +@end iftex + + For text which contains embedded commands for text formatters, Emacs +has other major modes, each for a particular text formatter. Thus, for +input to @TeX{}, you would use @TeX{} +@iftex +mode (@pxref{TeX Mode}). +@end iftex +@ifinfo +mode. +@end ifinfo +For input to nroff, use Nroff mode. + + Instead of using a text formatter, you can edit formatted text in +WYSIWYG style (``what you see is what you get''), with Enriched mode. +Then the formatting appears on the screen in Emacs while you edit. +@iftex +@xref{Formatted Text}. +@end iftex + +@menu +* Words:: Moving over and killing words. +* Sentences:: Moving over and killing sentences. +* Paragraphs:: Moving over paragraphs. +* Pages:: Moving over pages. +* Filling:: Filling or justifying text. +* Case:: Changing the case of text. +* Text Mode:: The major modes for editing text files. +* Outline Mode:: Editing outlines. +* TeX Mode:: Editing input to the formatter TeX. +* Nroff Mode:: Editing input to the formatter nroff. +* Formatted Text:: Editing formatted text directly in WYSIWYG fashion. +@end menu + +@node Words +@section Words +@cindex words +@cindex Meta commands and words + + Emacs has commands for moving over or operating on words. By convention, +the keys for them are all Meta characters. + +@c widecommands +@table @kbd +@item M-f +Move forward over a word (@code{forward-word}). +@item M-b +Move backward over a word (@code{backward-word}). +@item M-d +Kill up to the end of a word (@code{kill-word}). +@item M-@key{DEL} +Kill back to the beginning of a word (@code{backward-kill-word}). +@item M-@@ +Mark the end of the next word (@code{mark-word}). +@item M-t +Transpose two words or drag a word across other words +(@code{transpose-words}). +@end table + + Notice how these keys form a series that parallels the character-based +@kbd{C-f}, @kbd{C-b}, @kbd{C-d}, @key{DEL} and @kbd{C-t}. @kbd{M-@@} is +cognate to @kbd{C-@@}, which is an alias for @kbd{C-@key{SPC}}. + +@kindex M-f +@kindex M-b +@findex forward-word +@findex backward-word + The commands @kbd{M-f} (@code{forward-word}) and @kbd{M-b} +(@code{backward-word}) move forward and backward over words. These +Meta characters are thus analogous to the corresponding control +characters, @kbd{C-f} and @kbd{C-b}, which move over single characters +in the text. The analogy extends to numeric arguments, which serve as +repeat counts. @kbd{M-f} with a negative argument moves backward, and +@kbd{M-b} with a negative argument moves forward. Forward motion +stops right after the last letter of the word, while backward motion +stops right before the first letter.@refill + +@kindex M-d +@findex kill-word + @kbd{M-d} (@code{kill-word}) kills the word after point. To be +precise, it kills everything from point to the place @kbd{M-f} would +move to. Thus, if point is in the middle of a word, @kbd{M-d} kills +just the part after point. If some punctuation comes between point and the +next word, it is killed along with the word. (If you wish to kill only the +next word but not the punctuation before it, simply do @kbd{M-f} to get +the end, and kill the word backwards with @kbd{M-@key{DEL}}.) +@kbd{M-d} takes arguments just like @kbd{M-f}. + +@findex backward-kill-word +@kindex M-DEL + @kbd{M-@key{DEL}} (@code{backward-kill-word}) kills the word before +point. It kills everything from point back to where @kbd{M-b} would +move to. If point is after the space in @w{@samp{FOO, BAR}}, then +@w{@samp{FOO, }} is killed. (If you wish to kill just @samp{FOO}, and +not the comma and the space, use @kbd{M-b M-d} instead of +@kbd{M-@key{DEL}}.) + +@kindex M-t +@findex transpose-words + @kbd{M-t} (@code{transpose-words}) exchanges the word before or +containing point with the following word. The delimiter characters between +the words do not move. For example, @w{@samp{FOO, BAR}} transposes into +@w{@samp{BAR, FOO}} rather than @samp{@w{BAR FOO,}}. @xref{Transpose}, for +more on transposition and on arguments to transposition commands. + +@kindex M-@@ +@findex mark-word + To operate on the next @var{n} words with an operation which applies +between point and mark, you can either set the mark at point and then move +over the words, or you can use the command @kbd{M-@@} (@code{mark-word}) +which does not move point, but sets the mark where @kbd{M-f} would move +to. @kbd{M-@@} accepts a numeric argument that says how many words to +scan for the place to put the mark. In Transient Mark mode, this command +activates the mark. + + The word commands' understanding of syntax is completely controlled by +the syntax table. Any character can, for example, be declared to be a word +delimiter. @xref{Syntax}. + +@node Sentences +@section Sentences +@cindex sentences +@cindex manipulating sentences + + The Emacs commands for manipulating sentences and paragraphs are mostly +on Meta keys, so as to be like the word-handling commands. + +@table @kbd +@item M-a +Move back to the beginning of the sentence (@code{backward-sentence}). +@item M-e +Move forward to the end of the sentence (@code{forward-sentence}). +@item M-k +Kill forward to the end of the sentence (@code{kill-sentence}). +@item C-x @key{DEL} +Kill back to the beginning of the sentence (@code{backward-kill-sentence}). +@end table + +@kindex M-a +@kindex M-e +@findex backward-sentence +@findex forward-sentence + The commands @kbd{M-a} and @kbd{M-e} (@code{backward-sentence} and +@code{forward-sentence}) move to the beginning and end of the current +sentence, respectively. They were chosen to resemble @kbd{C-a} and +@kbd{C-e}, which move to the beginning and end of a line. Unlike them, +@kbd{M-a} and @kbd{M-e} if repeated or given numeric arguments move over +successive sentences. + + Moving backward over a sentence places point just before the first +character of the sentence; moving forward places point right after the +punctuation that ends the sentence. Neither one moves over the +whitespace at the sentence boundary. + +@kindex M-k +@kindex C-x DEL +@findex kill-sentence +@findex backward-kill-sentence + Just as @kbd{C-a} and @kbd{C-e} have a kill command, @kbd{C-k}, to go +with them, so @kbd{M-a} and @kbd{M-e} have a corresponding kill command +@kbd{M-k} (@code{kill-sentence}) which kills from point to the end of +the sentence. With minus one as an argument it kills back to the +beginning of the sentence. Larger arguments serve as a repeat count. +There is also a command, @kbd{C-x @key{DEL}} +(@code{backward-kill-sentence}), for killing back to the beginning of a +sentence. This command is useful when you change your mind in the +middle of composing text.@refill + + The sentence commands assume that you follow the American typist's +convention of putting two spaces at the end of a sentence; they consider +a sentence to end wherever there is a @samp{.}, @samp{?} or @samp{!} +followed by the end of a line or two spaces, with any number of +@samp{)}, @samp{]}, @samp{'}, or @samp{"} characters allowed in between. +A sentence also begins or ends wherever a paragraph begins or ends. + +@vindex sentence-end + The variable @code{sentence-end} controls recognition of the end of a +sentence. It is a regexp that matches the last few characters of a +sentence, together with the whitespace following the sentence. Its +normal value is + +@example +"[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*" +@end example + +@noindent +This example is explained in the section on regexps. @xref{Regexps}. + + If you want to use just one space between sentences, you should +set @code{sentence-end} to this value: + +@example +"[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*" +@end example + +@noindent +You should also set the variable @code{sentence-end-double-space} to +@code{nil} so that the fill commands expect and leave just one space at +the end of a sentence. Note that this makes it impossible to +distinguish between periods that end sentences and those that indicate +abbreviations. + +@node Paragraphs +@section Paragraphs +@cindex paragraphs +@cindex manipulating paragraphs +@kindex M-@{ +@kindex M-@} +@findex backward-paragraph +@findex forward-paragraph + + The Emacs commands for manipulating paragraphs are also Meta keys. + +@table @kbd +@item M-@{ +Move back to previous paragraph beginning (@code{backward-paragraph}). +@item M-@} +Move forward to next paragraph end (@code{forward-paragraph}). +@item M-h +Put point and mark around this or next paragraph (@code{mark-paragraph}). +@end table + + @kbd{M-@{} moves to the beginning of the current or previous +paragraph, while @kbd{M-@}} moves to the end of the current or next +paragraph. Blank lines and text-formatter command lines separate +paragraphs and are not considered part of any paragraph. In Fundamental +mode, but not in Text mode, an indented line also starts a new +paragraph. (If a paragraph is preceded by a blank line, these commands +treat that blank line as the beginning of the paragraph.) + + In major modes for programs, paragraphs begin and end only at blank +lines. This makes the paragraph commands continue to be useful even +though there are no paragraphs per se. + + When there is a fill prefix, then paragraphs are delimited by all lines +which don't start with the fill prefix. @xref{Filling}. + +@kindex M-h +@findex mark-paragraph + When you wish to operate on a paragraph, you can use the command +@kbd{M-h} (@code{mark-paragraph}) to set the region around it. Thus, +for example, @kbd{M-h C-w} kills the paragraph around or after point. +The @kbd{M-h} command puts point at the beginning and mark at the end of +the paragraph point was in. In Transient Mark mode, it activates the +mark. If point is between paragraphs (in a run of blank lines, or at a +boundary), the paragraph following point is surrounded by point and +mark. If there are blank lines preceding the first line of the +paragraph, one of these blank lines is included in the region. + +@vindex paragraph-start +@vindex paragraph-separate + The precise definition of a paragraph boundary is controlled by the +variables @code{paragraph-separate} and @code{paragraph-start}. The +value of @code{paragraph-start} is a regexp that should match any line +that either starts or separates paragraphs. The value of +@code{paragraph-separate} is another regexp that should match only lines +that separate paragraphs without being part of any paragraph (for +example, blank lines). Lines that start a new paragraph and are +contained in it must match only @code{paragraph-start}, not +@code{paragraph-separate}. For example, in Fundamental mode, +@code{paragraph-start} is @code{"[ @t{\}t@t{\}n@t{\}f]"} and +@code{paragraph-separate} is @code{"[ @t{\}t@t{\}f]*$"}.@refill + + Normally it is desirable for page boundaries to separate paragraphs. +The default values of these variables recognize the usual separator for +pages. + +@node Pages +@section Pages + +@cindex pages +@cindex formfeed + Files are often thought of as divided into @dfn{pages} by the +@dfn{formfeed} character (ASCII control-L, octal code 014). When you +print hardcopy for a file, this character forces a page break; thus, +each page of the file goes on a separate page on paper. Most Emacs +commands treat the page-separator character just like any other +character: you can insert it with @kbd{C-q C-l}, and delete it with +@key{DEL}. Thus, you are free to paginate your file or not. However, +since pages are often meaningful divisions of the file, Emacs provides +commands to move over them and operate on them. + +@c WideCommands +@table @kbd +@item C-x [ +Move point to previous page boundary (@code{backward-page}). +@item C-x ] +Move point to next page boundary (@code{forward-page}). +@item C-x C-p +Put point and mark around this page (or another page) (@code{mark-page}). +@item C-x l +Count the lines in this page (@code{count-lines-page}). +@end table + +@kindex C-x [ +@kindex C-x ] +@findex forward-page +@findex backward-page + The @kbd{C-x [} (@code{backward-page}) command moves point to immediately +after the previous page delimiter. If point is already right after a page +delimiter, it skips that one and stops at the previous one. A numeric +argument serves as a repeat count. The @kbd{C-x ]} (@code{forward-page}) +command moves forward past the next page delimiter. + +@kindex C-x C-p +@findex mark-page + The @kbd{C-x C-p} command (@code{mark-page}) puts point at the +beginning of the current page and the mark at the end. The page +delimiter at the end is included (the mark follows it). The page +delimiter at the front is excluded (point follows it). @kbd{C-x C-p +C-w} is a handy way to kill a page to move it elsewhere. If you move to +another page delimiter with @kbd{C-x [} and @kbd{C-x ]}, then yank the +killed page, all the pages will be properly delimited once again. The +reason @kbd{C-x C-p} includes only the following page delimiter in the +region is to ensure that. + + A numeric argument to @kbd{C-x C-p} is used to specify which page to go +to, relative to the current one. Zero means the current page. One means +the next page, and @minus{}1 means the previous one. + +@kindex C-x l +@findex count-lines-page + The @kbd{C-x l} command (@code{count-lines-page}) is good for deciding +where to break a page in two. It prints in the echo area the total number +of lines in the current page, and then divides it up into those preceding +the current line and those following, as in + +@example +Page has 96 (72+25) lines +@end example + +@noindent + Notice that the sum is off by one; this is correct if point is not at the +beginning of a line. + +@vindex page-delimiter + The variable @code{page-delimiter} controls where pages begin. Its +value is a regexp that matches the beginning of a line that separates +pages. The normal value of this variable is @code{"^@t{\}f"}, which +matches a formfeed character at the beginning of a line. + +@node Filling +@section Filling Text +@cindex filling text + + @dfn{Filling} text means breaking it up into lines that fit a +specified width. Emacs does filling in two ways. In Auto Fill mode, +inserting text with self-inserting characters also automatically fills +it. There are also explicit fill commands that you can use when editing +text leaves it unfilled. When you edit formatted text, you can specify +a style of filling for each portion of the text (@pxref{Formatted +Text}). + +@menu +* Auto Fill:: Auto Fill mode breaks long lines automatically. +* Fill Commands:: Commands to refill paragraphs and center lines. +* Fill Prefix:: Filling paragraphs that are indented + or in a comment, etc. +* Adaptive Fill:: How Emacs can determine the fill prefix automatically. +@end menu + +@node Auto Fill +@subsection Auto Fill Mode +@cindex Auto Fill mode +@cindex mode, Auto Fill +@cindex word wrap + + @dfn{Auto Fill} mode is a minor mode in which lines are broken +automatically when they become too wide. Breaking happens only when +you type a @key{SPC} or @key{RET}. + +@table @kbd +@item M-x auto-fill-mode +Enable or disable Auto Fill mode. +@item @key{SPC} +@itemx @key{RET} +In Auto Fill mode, break lines when appropriate. +@end table + +@findex auto-fill-mode + @kbd{M-x auto-fill-mode} turns Auto Fill mode on if it was off, or off +if it was on. With a positive numeric argument it always turns Auto +Fill mode on, and with a negative argument always turns it off. You can +see when Auto Fill mode is in effect by the presence of the word +@samp{Fill} in the mode line, inside the parentheses. Auto Fill mode is +a minor mode which is enabled or disabled for each buffer individually. +@xref{Minor Modes}. + + In Auto Fill mode, lines are broken automatically at spaces when they +get longer than the desired width. Line breaking and rearrangement +takes place only when you type @key{SPC} or @key{RET}. If you wish to +insert a space or newline without permitting line-breaking, type +@kbd{C-q @key{SPC}} or @kbd{C-q C-j} (recall that a newline is really a +control-J). Also, @kbd{C-o} inserts a newline without line breaking. + + Auto Fill mode works well with programming-language modes, because it +indents new lines with @key{TAB}. If a line ending in a comment gets +too long, the text of the comment is split into two comment lines. +Optionally, new comment delimiters are inserted at the end of the first +line and the beginning of the second so that each line is a separate +comment; the variable @code{comment-multi-line} controls the choice +(@pxref{Comments}). + + Adaptive filling (see the following section) works for Auto Filling as +well as for explicit fill commands. It takes a fill prefix +automatically from the second or first line of a paragraph. + + Auto Fill mode does not refill entire paragraphs; it can break lines but +cannot merge lines. So editing in the middle of a paragraph can result in +a paragraph that is not correctly filled. The easiest way to make the +paragraph properly filled again is usually with the explicit fill commands. +@ifinfo +@xref{Fill Commands}. +@end ifinfo + + Many users like Auto Fill mode and want to use it in all text files. +The section on init files says how to arrange this permanently for yourself. +@xref{Init File}. + +@node Fill Commands +@subsection Explicit Fill Commands + +@table @kbd +@item M-q +Fill current paragraph (@code{fill-paragraph}). +@item C-x f +Set the fill column (@code{set-fill-column}). +@item M-x fill-region +Fill each paragraph in the region (@code{fill-region}). +@item M-x fill-region-as-paragraph +Fill the region, considering it as one paragraph. +@item M-s +Center a line. +@end table + +@kindex M-q +@findex fill-paragraph + To refill a paragraph, use the command @kbd{M-q} +(@code{fill-paragraph}). This operates on the paragraph that point is +inside, or the one after point if point is between paragraphs. +Refilling works by removing all the line-breaks, then inserting new ones +where necessary. + +@findex fill-region + To refill many paragraphs, use @kbd{M-x fill-region}, which +divides the region into paragraphs and fills each of them. + +@findex fill-region-as-paragraph + @kbd{M-q} and @code{fill-region} use the same criteria as @kbd{M-h} +for finding paragraph boundaries (@pxref{Paragraphs}). For more +control, you can use @kbd{M-x fill-region-as-paragraph}, which refills +everything between point and mark. This command deletes any blank lines +within the region, so separate blocks of text end up combined into one +block.@refill + +@cindex justification + A numeric argument to @kbd{M-q} causes it to @dfn{justify} the text as +well as filling it. This means that extra spaces are inserted to make +the right margin line up exactly at the fill column. To remove the +extra spaces, use @kbd{M-q} with no argument. (Likewise for +@code{fill-region}.) Another way to control justification, and choose +other styles of filling, is with the @code{justification} text property; +see @ref{Format Justification}. + +@kindex M-s @r{(Text mode)} +@cindex centering +@findex center-line + The command @kbd{M-s} (@code{center-line}) centers the current line +within the current fill column. With an argument @var{n}, it centers +@var{n} lines individually and moves past them. + +@vindex fill-column +@kindex C-x f +@findex set-fill-column + The maximum line width for filling is in the variable +@code{fill-column}. Altering the value of @code{fill-column} makes it +local to the current buffer; until that time, the default value is in +effect. The default is initially 70. @xref{Locals}. The easiest way +to set @code{fill-column} is to use the command @kbd{C-x f} +(@code{set-fill-column}). With a numeric argument, it uses that as the +new fill column. With just @kbd{C-u} as argument, it sets +@code{fill-column} to the current horizontal position of point. + + Emacs commands normally consider a period followed by two spaces or by +a newline as the end of a sentence; a period followed by just one space +indicates an abbreviation and not the end of a sentence. To preserve +the distinction between these two ways of using a period, the fill +commands do not break a line after a period followed by just one space. + +@vindex sentence-end-double-space + If the variable @code{sentence-end-double-space} is @code{nil}, the +fill commands expect and leave just one space at the end of a sentence. +Ordinarily this variable is @code{t}, so the fill commands insist on +two spaces for the end of a sentence, as explained above. @xref{Sentences}. + +@vindex colon-double-space + If the variable @code{colon-double-space} is non-@code{nil}, the +fill commands put two spaces after a colon. + +@node Fill Prefix +@subsection The Fill Prefix + +@cindex fill prefix + To fill a paragraph in which each line starts with a special marker +(which might be a few spaces, giving an indented paragraph), you can use +the @dfn{fill prefix} feature. The fill prefix is a string that Emacs +expects every line to start with, and which is not included in filling. +You can specify a fill prefix explicitly; Emacs can also deduce the +fill prefix automatically (@pxref{Adaptive Fill}). + +@table @kbd +@item C-x . +Set the fill prefix (@code{set-fill-prefix}). +@item M-q +Fill a paragraph using current fill prefix (@code{fill-paragraph}). +@item M-x fill-individual-paragraphs +Fill the region, considering each change of indentation as starting a +new paragraph. +@item M-x fill-nonuniform-paragraphs +Fill the region, considering only paragraph-separator lines as starting +a new paragraph. +@end table + +@kindex C-x . +@findex set-fill-prefix + To specify a fill prefix, move to a line that starts with the desired +prefix, put point at the end of the prefix, and give the command +@w{@kbd{C-x .}}@: (@code{set-fill-prefix}). That's a period after the +@kbd{C-x}. To turn off the fill prefix, specify an empty prefix: type +@w{@kbd{C-x .}}@: with point at the beginning of a line.@refill + + When a fill prefix is in effect, the fill commands remove the fill +prefix from each line before filling and insert it on each line after +filling. Auto Fill mode also inserts the fill prefix automatically when +it makes a new line. The @kbd{C-o} command inserts the fill prefix on +new lines it creates, when you use it at the beginning of a line +(@pxref{Blank Lines}). Conversely, the command @kbd{M-^} deletes the +prefix (if it occurs) after the newline that it deletes +(@pxref{Indentation}). + + For example, if @code{fill-column} is 40 and you set the fill prefix +to @samp{;; }, then @kbd{M-q} in the following text + +@example +;; This is an +;; example of a paragraph +;; inside a Lisp-style comment. +@end example + +@noindent +produces this: + +@example +;; This is an example of a paragraph +;; inside a Lisp-style comment. +@end example + + Lines that do not start with the fill prefix are considered to start +paragraphs, both in @kbd{M-q} and the paragraph commands; this gives +good results for paragraphs with hanging indentation (every line +indented except the first one). Lines which are blank or indented once +the prefix is removed also separate or start paragraphs; this is what +you want if you are writing multi-paragraph comments with a comment +delimiter on each line. + +@findex fill-individual-paragraphs + You can use @kbd{M-x fill-individual-paragraphs} to set the fill +prefix for each paragraph automatically. This command divides the +region into paragraphs, treating every change in the amount of +indentation as the start of a new paragraph, and fills each of these +paragraphs. Thus, all the lines in one ``paragraph'' have the same +amount of indentation. That indentation serves as the fill prefix for +that paragraph. + +@findex fill-nonuniform-paragraphs + @kbd{M-x fill-nonuniform-paragraphs} is a similar command that divides +the region into paragraphs in a different way. It considers only +paragraph-separating lines (as defined by @code{paragraph-separate}) as +starting a new paragraph. Since this means that the lines of one +paragraph may have different amounts of indentation, the fill prefix +used is the smallest amount of indentation of any of the lines of the +paragraph. This gives good results with styles that indent a paragraph's +first line more or less that the rest of the paragraph. + +@vindex fill-prefix + The fill prefix is stored in the variable @code{fill-prefix}. Its value +is a string, or @code{nil} when there is no fill prefix. This is a +per-buffer variable; altering the variable affects only the current buffer, +but there is a default value which you can change as well. @xref{Locals}. + + The @code{indentation} text property provides another way to control +the amount of indentation paragraphs receive. @xref{Format Indentation}. + +@node Adaptive Fill +@subsection Adaptive Filling + +@cindex adaptive filling + The fill commands can deduce the proper fill prefix for a paragraph +automatically in certain cases: either whitespace or certain punctuation +characters at the beginning of a line are propagated to all lines of the +paragraph. + + If the paragraph has two or more lines, the fill prefix is taken from +the paragraph's second line, but only if it appears on the first line as +well. + + If a paragraph has just one line, fill commands @emph{may} take a +prefix from that line. The decision is complicated because there are +three reasonable things to do in such a case: + +@itemize @bullet +@item +Use the first line's prefix on all the lines of the paragraph. + +@item +Indent subsequent lines with whitespace, so that they line up under the +text that follows the prefix on the first line, but don't actually copy +the prefix from the first line. + +@item +Don't do anything special with the second and following lines. +@end itemize + + All three of these styles of formatting are commonly used. So the +fill commands try to determine what you would like, based on the prefix +that appears and on the major mode. Here is how. + +@vindex adaptive-fill-first-line-regexp + If the prefix found on the first line matches +@code{adaptive-fill-first-line-regexp}, or if it appears to be a +comment-starting sequence (this depends on the major mode), then the +prefix found is used for filling the paragraph, provided it would not +act as a paragraph starter on subsequent lines. + + Otherwise, the prefix found is converted to an equivalent number of +spaces, and those spaces are used as the fill prefix for the rest of the +lines, provided they would not act as a paragraph starter on subsequent +lines. + + In Text mode, and other modes where only blank lines and page +delimiters separate paragraphs, the prefix chosen by adaptive filling +never acts as a paragraph starter, so it can always be used for filling. + +@vindex adaptive-fill-mode +@vindex adaptive-fill-regexp + The variable @code{adaptive-fill-regexp} determines what kinds of line +beginnings can serve as a fill prefix: any characters at the start of +the line that match this regular expression are used. If you set the +variable @code{adaptive-fill-mode} to @code{nil}, the fill prefix is +never chosen automatically. + +@vindex adaptive-fill-function + You can specify more complex ways of choosing a fill prefix +automatically by setting the variable @code{adaptive-fill-function} to a +function. This function is called with point after the left margin of a +line, and it should return the appropriate fill prefix based on that +line. If it returns @code{nil}, that means it sees no fill prefix in +that line. + +@node Case +@section Case Conversion Commands +@cindex case conversion + + Emacs has commands for converting either a single word or any arbitrary +range of text to upper case or to lower case. + +@c WideCommands +@table @kbd +@item M-l +Convert following word to lower case (@code{downcase-word}). +@item M-u +Convert following word to upper case (@code{upcase-word}). +@item M-c +Capitalize the following word (@code{capitalize-word}). +@item C-x C-l +Convert region to lower case (@code{downcase-region}). +@item C-x C-u +Convert region to upper case (@code{upcase-region}). +@end table + +@kindex M-l +@kindex M-u +@kindex M-c +@cindex words, case conversion +@cindex converting text to upper or lower case +@cindex capitalizing words +@findex downcase-word +@findex upcase-word +@findex capitalize-word + The word conversion commands are the most useful. @kbd{M-l} +(@code{downcase-word}) converts the word after point to lower case, moving +past it. Thus, repeating @kbd{M-l} converts successive words. +@kbd{M-u} (@code{upcase-word}) converts to all capitals instead, while +@kbd{M-c} (@code{capitalize-word}) puts the first letter of the word +into upper case and the rest into lower case. All these commands convert +several words at once if given an argument. They are especially convenient +for converting a large amount of text from all upper case to mixed case, +because you can move through the text using @kbd{M-l}, @kbd{M-u} or +@kbd{M-c} on each word as appropriate, occasionally using @kbd{M-f} instead +to skip a word. + + When given a negative argument, the word case conversion commands apply +to the appropriate number of words before point, but do not move point. +This is convenient when you have just typed a word in the wrong case: you +can give the case conversion command and continue typing. + + If a word case conversion command is given in the middle of a word, it +applies only to the part of the word which follows point. This is just +like what @kbd{M-d} (@code{kill-word}) does. With a negative argument, +case conversion applies only to the part of the word before point. + +@kindex C-x C-l +@kindex C-x C-u +@findex downcase-region +@findex upcase-region + The other case conversion commands are @kbd{C-x C-u} +(@code{upcase-region}) and @kbd{C-x C-l} (@code{downcase-region}), which +convert everything between point and mark to the specified case. Point and +mark do not move. + + The region case conversion commands @code{upcase-region} and +@code{downcase-region} are normally disabled. This means that they ask +for confirmation if you try to use them. When you confirm, you may +enable the command, which means it will not ask for confirmation again. +@xref{Disabling}. + +@node Text Mode +@section Text Mode +@cindex Text mode +@cindex mode, Text +@findex text-mode + + When you edit files of text in a human language, it's more convenient +to use Text mode rather than Fundamental mode. To enter Text mode, type +@kbd{M-x text-mode}. + + In Text mode, only blank lines and page delimiters separate +paragraphs. As a result, paragraphs can be indented, and adaptive +filling determines what indentation to use when filling a paragraph. +@xref{Adaptive Fill}. + +@kindex TAB @r{(Text mode)} + Text mode defines @key{TAB} to run @code{indent-relative} +(@pxref{Indentation}), so that you can conveniently indent a line like +the previous line. When the previous line is not indented, +@code{indent-relative} runs @code{tab-to-tab-stop}, which uses Emacs tab +stops that you can set (@pxref{Tab Stops}). + + Text mode turns off the features concerned with comments except when +you explicitly invoke them. It changes the syntax table so that periods +are not considered part of a word, while apostrophes, backspaces and +underlines are considered part of words. + +@cindex Paragraph-Indent Text mode +@cindex mode, Paragraph-Indent Text +@findex paragraph-indent-text-mode + If you indent the first lines of paragraphs, then you should use +Paragraph-Indent Text mode rather than Text mode. In this mode, you do +not need to have blank lines between paragraphs, because the first-line +indentation is sufficient to start a paragraph; however paragraphs in +which every line is indented are not supported. Use @kbd{M-x +paragraph-indent-text-mode} to enter this mode. + +@kindex M-TAB @r{(Text mode)} + Text mode, and all the modes based on it, define @kbd{M-@key{TAB}} as +the command @code{ispell-complete-word}, which performs completion of +the partial word in the buffer before point, using the spelling +dictionary as the space of possible words. @xref{Spelling}. + +@vindex text-mode-hook + Entering Text mode runs the hook @code{text-mode-hook}. Other major +modes related to Text mode also run this hook, followed by hooks of +their own; this includes Paragraph-Indent Text mode, Nroff mode, @TeX{} +mode, Outline mode, and Mail mode. Hook functions on +@code{text-mode-hook} can look at the value of @code{major-mode} to see +which of these modes is actually being entered. @xref{Hooks}. + +@ifinfo + Emacs provides two other modes for editing text that is to be passed +through a text formatter to produce fancy formatted printed output. +@xref{Nroff Mode}, for editing input to the formatter nroff. +@xref{TeX Mode}, for editing input to the formatter TeX. + + Another mode is used for editing outlines. It allows you to view the +text at various levels of detail. You can view either the outline +headings alone or both headings and text; you can also hide some of the +headings at lower levels from view to make the high level structure more +visible. @xref{Outline Mode}. +@end ifinfo + +@node Outline Mode +@section Outline Mode +@cindex Outline mode +@cindex mode, Outline +@cindex selective display +@cindex invisible lines + +@findex outline-mode +@findex outline-minor-mode +@vindex outline-minor-mode-prefix + Outline mode is a major mode much like Text mode but intended for +editing outlines. It allows you to make parts of the text temporarily +invisible so that you can see the outline structure. Type @kbd{M-x +outline-mode} to switch to Outline mode as the major mode of the current +buffer. + + When Outline mode makes a line invisible, the line does not appear on +the screen. The screen appears exactly as if the invisible line were +deleted, except that an ellipsis (three periods in a row) appears at the +end of the previous visible line (only one ellipsis no matter how many +invisible lines follow). + + Editing commands that operate on lines, such as @kbd{C-n} and +@kbd{C-p}, treat the text of the invisible line as part of the previous +visible line. Killing an entire visible line, including its terminating +newline, really kills all the following invisible lines along with it. + + Outline minor mode provides the same commands as the major mode, +Outline mode, but you can use it in conjunction with other major modes. +Type @kbd{M-x outline-minor-mode} to enable the Outline minor mode in +the current buffer. You can also specify this in the text of a file, +with a file local variable of the form @samp{mode: outline-minor} +(@pxref{File Variables}). + +@kindex C-c @@ @r{(Outline minor mode)} + The major mode, Outline mode, provides special key bindings on the +@kbd{C-c} prefix. Outline minor mode provides similar bindings with +@kbd{C-c @@} as the prefix; this is to reduce the conflicts with the +major mode's special commands. (The variable +@code{outline-minor-mode-prefix} controls the prefix used.) + +@vindex outline-mode-hook + Entering Outline mode runs the hook @code{text-mode-hook} followed by +the hook @code{outline-mode-hook} (@pxref{Hooks}). + +@menu +* Format: Outline Format. What the text of an outline looks like. +* Motion: Outline Motion. Special commands for moving through + outlines. +* Visibility: Outline Visibility. Commands to control what is visible. +* Views: Outline Views. Outlines and multiple views. +@end menu + +@node Outline Format +@subsection Format of Outlines + +@cindex heading lines (Outline mode) +@cindex body lines (Outline mode) + Outline mode assumes that the lines in the buffer are of two types: +@dfn{heading lines} and @dfn{body lines}. A heading line represents a +topic in the outline. Heading lines start with one or more stars; the +number of stars determines the depth of the heading in the outline +structure. Thus, a heading line with one star is a major topic; all the +heading lines with two stars between it and the next one-star heading +are its subtopics; and so on. Any line that is not a heading line is a +body line. Body lines belong with the preceding heading line. Here is +an example: + +@example +* Food +This is the body, +which says something about the topic of food. + +** Delicious Food +This is the body of the second-level header. + +** Distasteful Food +This could have +a body too, with +several lines. + +*** Dormitory Food + +* Shelter +Another first-level topic with its header line. +@end example + + A heading line together with all following body lines is called +collectively an @dfn{entry}. A heading line together with all following +deeper heading lines and their body lines is called a @dfn{subtree}. + +@vindex outline-regexp + You can customize the criterion for distinguishing heading lines +by setting the variable @code{outline-regexp}. Any line whose +beginning has a match for this regexp is considered a heading line. +Matches that start within a line (not at the left margin) do not count. +The length of the matching text determines the level of the heading; +longer matches make a more deeply nested level. Thus, for example, +if a text formatter has commands @samp{@@chapter}, @samp{@@section} +and @samp{@@subsection} to divide the document into chapters and +sections, you could make those lines count as heading lines by +setting @code{outline-regexp} to @samp{"@@chap\\|@@\\(sub\\)*section"}. +Note the trick: the two words @samp{chapter} and @samp{section} are equally +long, but by defining the regexp to match only @samp{chap} we ensure +that the length of the text matched on a chapter heading is shorter, +so that Outline mode will know that sections are contained in chapters. +This works as long as no other command starts with @samp{@@chap}. + +@vindex outline-level + It is possible to change the rule for calculating the level of a +heading line by setting the variable @code{outline-level}. The value of +@code{outline-level} should be a function that takes no arguments and +returns the level of the current heading. Some major modes such as C, +Nroff, and Emacs Lisp mode set this variable and/or +@code{outline-regexp} in order to work with Outline minor mode. + +@node Outline Motion +@subsection Outline Motion Commands + + Outline mode provides special motion commands that move backward and +forward to heading lines. + +@table @kbd +@item C-c C-n +Move point to the next visible heading line +(@code{outline-next-visible-heading}). +@item C-c C-p +Move point to the previous visible heading line +(@code{outline-previous-visible-heading}). +@item C-c C-f +Move point to the next visible heading line at the same level +as the one point is on (@code{outline-forward-same-level}). +@item C-c C-b +Move point to the previous visible heading line at the same level +(@code{outline-backward-same-level}). +@item C-c C-u +Move point up to a lower-level (more inclusive) visible heading line +(@code{outline-up-heading}). +@end table + +@findex outline-next-visible-heading +@findex outline-previous-visible-heading +@kindex C-c C-n @r{(Outline mode)} +@kindex C-c C-p @r{(Outline mode)} + @kbd{C-c C-n} (@code{outline-next-visible-heading}) moves down to the next +heading line. @kbd{C-c C-p} (@code{outline-previous-visible-heading}) moves +similarly backward. Both accept numeric arguments as repeat counts. The +names emphasize that invisible headings are skipped, but this is not really +a special feature. All editing commands that look for lines ignore the +invisible lines automatically.@refill + +@findex outline-up-heading +@findex outline-forward-same-level +@findex outline-backward-same-level +@kindex C-c C-f @r{(Outline mode)} +@kindex C-c C-b @r{(Outline mode)} +@kindex C-c C-u @r{(Outline mode)} + More powerful motion commands understand the level structure of headings. +@kbd{C-c C-f} (@code{outline-forward-same-level}) and +@kbd{C-c C-b} (@code{outline-backward-same-level}) move from one +heading line to another visible heading at the same depth in +the outline. @kbd{C-c C-u} (@code{outline-up-heading}) moves +backward to another heading that is less deeply nested. + +@node Outline Visibility +@subsection Outline Visibility Commands + + The other special commands of outline mode are used to make lines visible +or invisible. Their names all start with @code{hide} or @code{show}. +Most of them fall into pairs of opposites. They are not undoable; instead, +you can undo right past them. Making lines visible or invisible is simply +not recorded by the undo mechanism. + +@table @kbd +@item C-c C-t +Make all body lines in the buffer invisible (@code{hide-body}). +@item C-c C-a +Make all lines in the buffer visible (@code{show-all}). +@item C-c C-d +Make everything under this heading invisible, not including this +heading itself (@code{hide-subtree}). +@item C-c C-s +Make everything under this heading visible, including body, +subheadings, and their bodies (@code{show-subtree}). +@item C-c C-l +Make the body of this heading line, and of all its subheadings, +invisible (@code{hide-leaves}). +@item C-c C-k +Make all subheadings of this heading line, at all levels, visible +(@code{show-branches}). +@item C-c C-i +Make immediate subheadings (one level down) of this heading line +visible (@code{show-children}). +@item C-c C-c +Make this heading line's body invisible (@code{hide-entry}). +@item C-c C-e +Make this heading line's body visible (@code{show-entry}). +@item C-c C-q +Hide everything except the top @var{n} levels of heading lines +(@code{hide-sublevels}). +@item C-c C-o +Hide everything except for the heading or body that point is in, plus +the headings leading up from there to the top level of the outline +(@code{hide-other}). +@end table + +@findex hide-entry +@findex show-entry +@kindex C-c C-c @r{(Outline mode)} +@kindex C-c C-e @r{(Outline mode)} + Two commands that are exact opposites are @kbd{C-c C-c} +(@code{hide-entry}) and @kbd{C-c C-e} (@code{show-entry}). They are +used with point on a heading line, and apply only to the body lines of +that heading. Subheadings and their bodies are not affected. + +@findex hide-subtree +@findex show-subtree +@kindex C-c C-s @r{(Outline mode)} +@kindex C-c C-d @r{(Outline mode)} +@cindex subtree (Outline mode) + Two more powerful opposites are @kbd{C-c C-d} (@code{hide-subtree}) and +@kbd{C-c C-s} (@code{show-subtree}). Both expect to be used when point is +on a heading line, and both apply to all the lines of that heading's +@dfn{subtree}: its body, all its subheadings, both direct and indirect, and +all of their bodies. In other words, the subtree contains everything +following this heading line, up to and not including the next heading of +the same or higher rank.@refill + +@findex hide-leaves +@findex show-branches +@kindex C-c C-l @r{(Outline mode)} +@kindex C-c C-k @r{(Outline mode)} + Intermediate between a visible subtree and an invisible one is having +all the subheadings visible but none of the body. There are two +commands for doing this, depending on whether you want to hide the +bodies or make the subheadings visible. They are @kbd{C-c C-l} +(@code{hide-leaves}) and @kbd{C-c C-k} (@code{show-branches}). + +@kindex C-c C-i @r{(Outline mode)} +@findex show-children + A little weaker than @code{show-branches} is @kbd{C-c C-i} +(@code{show-children}). It makes just the direct subheadings +visible---those one level down. Deeper subheadings remain invisible, if +they were invisible.@refill + +@findex hide-body +@findex show-all +@kindex C-c C-t @r{(Outline mode)} +@kindex C-c C-a @r{(Outline mode)} + Two commands have a blanket effect on the whole file. @kbd{C-c C-t} +(@code{hide-body}) makes all body lines invisible, so that you see just +the outline structure. @kbd{C-c C-a} (@code{show-all}) makes all lines +visible. These commands can be thought of as a pair of opposites even +though @kbd{C-c C-a} applies to more than just body lines. + +@findex hide-sublevels +@kindex C-c C-q @r{(Outline mode)} + The command @kbd{C-c C-q} (@code{hide-sublevels}) hides all but the +top level headings. With a numeric argument @var{n}, it hides everything +except the top @var{n} levels of heading lines. + +@findex hide-other +@kindex C-c C-o @r{(Outline mode)} + The command @kbd{C-c C-o} (@code{hide-other}) hides everything except +the heading or body text that point is in, plus its parents (the headers +leading up from there to top level in the outline). + + You can turn off the use of ellipses at the ends of visible lines by +setting @code{selective-display-ellipses} to @code{nil}. Then there is +no visible indication of the presence of invisible lines. + + When incremental search finds text that is hidden by Outline mode, +it makes that part of the buffer visible. If you exit the search +at that position, the text remains visible. + +@node Outline Views +@subsection Viewing One Outline in Multiple Views + +@cindex multiple views of outline +@cindex views of an outline +@cindex outline with multiple views +@cindex indirect buffers and outlines + You can display two views of a single outline at the same time, in +different windows. To do this, you must create an indirect buffer using +@kbd{M-x make-indirect-buffer}. The first argument of this command is +the existing outline buffer name, and its second argument is the name to +use for the new indirect buffer. @xref{Indirect Buffers}. + + Once the indirect buffer exists, you can display it in a window in the +normal fashion, with @kbd{C-x 4 b} or other Emacs commands. The Outline +mode commands to show and hide parts of the text operate on each buffer +independently; as a result, each buffer can have its own view. If you +want more than two views on the same outline, create additional indirect +buffers. + +@node TeX Mode +@section @TeX{} Mode +@cindex @TeX{} mode +@cindex La@TeX{} mode +@cindex Sli@TeX{} mode +@cindex mode, @TeX{} +@cindex mode, La@TeX{} +@cindex mode, Sli@TeX{} +@findex tex-mode +@findex plain-tex-mode +@findex latex-mode +@findex slitex-mode + + @TeX{} is a powerful text formatter written by Donald Knuth; it is also +free, like GNU Emacs. La@TeX{} is a simplified input format for @TeX{}, +implemented by @TeX{} macros; it comes with @TeX{}. Sli@TeX{} is a special +form of La@TeX{}.@refill + + Emacs has a special @TeX{} mode for editing @TeX{} input files. +It provides facilities for checking the balance of delimiters and for +invoking @TeX{} on all or part of the file. + +@vindex tex-default-mode + @TeX{} mode has three variants, Plain @TeX{} mode, La@TeX{} mode, and +Sli@TeX{} mode (these three distinct major modes differ only slightly). +They are designed for editing the three different formats. The command +@kbd{M-x tex-mode} looks at the contents of the buffer to determine +whether the contents appear to be either La@TeX{} input or Sli@TeX{} +input; if so, it selects the appropriate mode. If the file contents do +not appear to be La@TeX{} or Sli@TeX{}, it selects Plain @TeX{} mode. +If the contents are insufficient to determine this, the variable +@code{tex-default-mode} controls which mode is used. + + When @kbd{M-x tex-mode} does not guess right, you can use the commands +@kbd{M-x plain-tex-mode}, @kbd{M-x latex-mode}, and @kbd{M-x +slitex-mode} to select explicitly the particular variants of @TeX{} +mode. + +@vindex tex-shell-hook +@vindex tex-mode-hook +@vindex latex-mode-hook +@vindex slitex-mode-hook +@vindex plain-tex-mode-hook + Entering any kind of @TeX{} mode runs the hooks @code{text-mode-hook} +and @code{tex-mode-hook}. Then it runs either +@code{plain-tex-mode-hook} or @code{latex-mode-hook}, whichever is +appropriate. For Sli@TeX{} files, it calls @code{slitex-mode-hook}. +Starting the @TeX{} shell runs the hook @code{tex-shell-hook}. +@xref{Hooks}. + +@menu +* Editing: TeX Editing. Special commands for editing in TeX mode. +* LaTeX: LaTeX Editing. Additional commands for LaTeX input files. +* Printing: TeX Print. Commands for printing part of a file with TeX. +@end menu + +@node TeX Editing +@subsection @TeX{} Editing Commands + + Here are the special commands provided in @TeX{} mode for editing the +text of the file. + +@table @kbd +@item " +Insert, according to context, either @samp{``} or @samp{"} or +@samp{''} (@code{tex-insert-quote}). +@item C-j +Insert a paragraph break (two newlines) and check the previous +paragraph for unbalanced braces or dollar signs +(@code{tex-terminate-paragraph}). +@item M-x tex-validate-region +Check each paragraph in the region for unbalanced braces or dollar signs. +@item C-c @{ +Insert @samp{@{@}} and position point between them (@code{tex-insert-braces}). +@item C-c @} +Move forward past the next unmatched close brace (@code{up-list}). +@end table + +@findex tex-insert-quote +@kindex " @r{(@TeX{} mode)} + In @TeX{}, the character @samp{"} is not normally used; we use +@samp{``} to start a quotation and @samp{''} to end one. To make +editing easier under this formatting convention, @TeX{} mode overrides +the normal meaning of the key @kbd{"} with a command that inserts a pair +of single-quotes or backquotes (@code{tex-insert-quote}). To be +precise, this command inserts @samp{``} after whitespace or an open +brace, @samp{"} after a backslash, and @samp{''} after any other +character. + + If you need the character @samp{"} itself in unusual contexts, use +@kbd{C-q} to insert it. Also, @kbd{"} with a numeric argument always +inserts that number of @samp{"} characters. You can turn off the +feature of @kbd{"} expansion by eliminating that binding in the local +map (@pxref{Key Bindings}). + + In @TeX{} mode, @samp{$} has a special syntax code which attempts to +understand the way @TeX{} math mode delimiters match. When you insert a +@samp{$} that is meant to exit math mode, the position of the matching +@samp{$} that entered math mode is displayed for a second. This is the +same feature that displays the open brace that matches a close brace that +is inserted. However, there is no way to tell whether a @samp{$} enters +math mode or leaves it; so when you insert a @samp{$} that enters math +mode, the previous @samp{$} position is shown as if it were a match, even +though they are actually unrelated. + +@findex tex-insert-braces +@kindex C-c @{ @r{(@TeX{} mode)} +@findex up-list +@kindex C-c @} @r{(@TeX{} mode)} + @TeX{} uses braces as delimiters that must match. Some users prefer +to keep braces balanced at all times, rather than inserting them +singly. Use @kbd{C-c @{} (@code{tex-insert-braces}) to insert a pair of +braces. It leaves point between the two braces so you can insert the +text that belongs inside. Afterward, use the command @kbd{C-c @}} +(@code{up-list}) to move forward past the close brace. + +@findex tex-validate-region +@findex tex-terminate-paragraph +@kindex C-j @r{(@TeX{} mode)} + There are two commands for checking the matching of braces. @kbd{C-j} +(@code{tex-terminate-paragraph}) checks the paragraph before point, and +inserts two newlines to start a new paragraph. It prints a message in +the echo area if any mismatch is found. @kbd{M-x tex-validate-region} +checks a region, paragraph by paragraph. The errors are listed in the +@samp{*Occur*} buffer, and you can use @kbd{C-c C-c} or @kbd{Mouse-2} in +that buffer to go to a particular mismatch. + + Note that Emacs commands count square brackets and parentheses in +@TeX{} mode, not just braces. This is not strictly correct for the +purpose of checking @TeX{} syntax. However, parentheses and square +brackets are likely to be used in text as matching delimiters and it is +useful for the various motion commands and automatic match display to +work with them. + +@node LaTeX Editing +@subsection La@TeX{} Editing Commands + + La@TeX{} mode, and its variant, Sli@TeX{} mode, provide a few extra +features not applicable to plain @TeX{}. + +@table @kbd +@item C-c C-o +Insert @samp{\begin} and @samp{\end} for La@TeX{} block and position +point on a line between them (@code{tex-latex-block}). +@item C-c C-e +Close the innermost La@TeX{} block not yet closed +(@code{tex-close-latex-block}). +@end table + +@findex tex-latex-block +@kindex C-c C-o @r{(La@TeX{} mode)} +@vindex latex-block-names + In La@TeX{} input, @samp{\begin} and @samp{\end} commands are used to +group blocks of text. To insert a @samp{\begin} and a matching +@samp{\end} (on a new line following the @samp{\begin}), use @kbd{C-c +C-o} (@code{tex-latex-block}). A blank line is inserted between the +two, and point is left there. You can use completion when you enter the +block type; to specify additional block type names beyond the standard +list, set the variable @code{latex-block-names}. For example, here's +how to add @samp{theorem}, @samp{corollary}, and @samp{proof}: + +@example +(setq latex-block-names '("theorem" "corollary" "proof")) +@end example + +@findex tex-close-latex-block +@kindex C-c C-e @r{(La@TeX{} mode)} + In La@TeX{} input, @samp{\begin} and @samp{\end} commands must +balance. You can use @kbd{C-c C-e} (@code{tex-close-latex-block}) to +insert automatically a matching @samp{\end} to match the last unmatched +@samp{\begin}. It indents the @samp{\end} to match the corresponding +@samp{\begin}. It inserts a newline after @samp{\end} if point is at +the beginning of a line. + +@node TeX Print +@subsection @TeX{} Printing Commands + + You can invoke @TeX{} as an inferior of Emacs on either the entire +contents of the buffer or just a region at a time. Running @TeX{} in +this way on just one chapter is a good way to see what your changes +look like without taking the time to format the entire file. + +@table @kbd +@item C-c C-r +Invoke @TeX{} on the current region, together with the buffer's header +(@code{tex-region}). +@item C-c C-b +Invoke @TeX{} on the entire current buffer (@code{tex-buffer}). +@item C-c @key{TAB} +Invoke Bib@TeX{} on the current file (@code{tex-bibtex-file}). +@item C-c C-f +Invoke @TeX{} on the current file (@code{tex-file}). +@item C-c C-l +Recenter the window showing output from the inferior @TeX{} so that +the last line can be seen (@code{tex-recenter-output-buffer}). +@item C-c C-k +Kill the @TeX{} subprocess (@code{tex-kill-job}). +@item C-c C-p +Print the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c +C-f} command (@code{tex-print}). +@item C-c C-v +Preview the output from the last @kbd{C-c C-r}, @kbd{C-c C-b}, or @kbd{C-c +C-f} command (@code{tex-view}). +@item C-c C-q +Show the printer queue (@code{tex-show-print-queue}). +@end table + +@findex tex-buffer +@kindex C-c C-b @r{(@TeX{} mode)} +@findex tex-print +@kindex C-c C-p @r{(@TeX{} mode)} +@findex tex-view +@kindex C-c C-v @r{(@TeX{} mode)} +@findex tex-show-print-queue +@kindex C-c C-q @r{(@TeX{} mode)} + You can pass the current buffer through an inferior @TeX{} by means of +@kbd{C-c C-b} (@code{tex-buffer}). The formatted output appears in a +temporary file; to print it, type @kbd{C-c C-p} (@code{tex-print}). +Afterward, you can use @kbd{C-c C-q} (@code{tex-show-print-queue}) to +view the progress of your output towards being printed. If your terminal +has the ability to display @TeX{} output files, you can preview the +output on the terminal with @kbd{C-c C-v} (@code{tex-view}). + +@cindex @code{TEXINPUTS} environment variable +@vindex tex-directory + You can specify the directory to use for running @TeX{} by setting the +variable @code{tex-directory}. @code{"."} is the default value. If +your environment variable @code{TEXINPUTS} contains relative directory +names, or if your files contains @samp{\input} commands with relative +file names, then @code{tex-directory} @emph{must} be @code{"."} or you +will get the wrong results. Otherwise, it is safe to specify some other +directory, such as @code{"/tmp"}. + +@vindex tex-run-command +@vindex latex-run-command +@vindex slitex-run-command +@vindex tex-dvi-print-command +@vindex tex-dvi-view-command +@vindex tex-show-queue-command + If you want to specify which shell commands are used in the inferior @TeX{}, +you can do so by setting the values of the variables @code{tex-run-command}, +@code{latex-run-command}, @code{slitex-run-command}, +@code{tex-dvi-print-command}, @code{tex-dvi-view-command}, and +@code{tex-show-queue-command}. You @emph{must} set the value of +@code{tex-dvi-view-command} for your particular terminal; this variable +has no default value. The other variables have default values that may +(or may not) be appropriate for your system. + + Normally, the file name given to these commands comes at the end of +the command string; for example, @samp{latex @var{filename}}. In some +cases, however, the file name needs to be embedded in the command; an +example is when you need to provide the file name as an argument to one +command whose output is piped to another. You can specify where to put +the file name with @samp{*} in the command string. For example, + +@example +(setq tex-dvi-print-command "dvips -f * | lpr") +@end example + +@findex tex-kill-job +@kindex C-c C-k @r{(@TeX{} mode)} +@findex tex-recenter-output-buffer +@kindex C-c C-l @r{(@TeX{} mode)} + The terminal output from @TeX{}, including any error messages, appears +in a buffer called @samp{*tex-shell*}. If @TeX{} gets an error, you can +switch to this buffer and feed it input (this works as in Shell mode; +@pxref{Interactive Shell}). Without switching to this buffer you can +scroll it so that its last line is visible by typing @kbd{C-c +C-l}. + + Type @kbd{C-c C-k} (@code{tex-kill-job}) to kill the @TeX{} process if +you see that its output is no longer useful. Using @kbd{C-c C-b} or +@kbd{C-c C-r} also kills any @TeX{} process still running.@refill + +@findex tex-region +@kindex C-c C-r @r{(@TeX{} mode)} + You can also pass an arbitrary region through an inferior @TeX{} by typing +@kbd{C-c C-r} (@code{tex-region}). This is tricky, however, because most files +of @TeX{} input contain commands at the beginning to set parameters and +define macros, without which no later part of the file will format +correctly. To solve this problem, @kbd{C-c C-r} allows you to designate a +part of the file as containing essential commands; it is included before +the specified region as part of the input to @TeX{}. The designated part +of the file is called the @dfn{header}. + +@cindex header (@TeX{} mode) + To indicate the bounds of the header in Plain @TeX{} mode, you insert two +special strings in the file. Insert @samp{%**start of header} before the +header, and @samp{%**end of header} after it. Each string must appear +entirely on one line, but there may be other text on the line before or +after. The lines containing the two strings are included in the header. +If @samp{%**start of header} does not appear within the first 100 lines of +the buffer, @kbd{C-c C-r} assumes that there is no header. + + In La@TeX{} mode, the header begins with @samp{\documentclass} or +@samp{\documentstyle} and ends with @samp{\begin@{document@}}. These +are commands that La@TeX{} requires you to use in any case, so nothing +special needs to be done to identify the header. + +@findex tex-file +@kindex C-c C-f @r{(@TeX{} mode)} + The commands (@code{tex-buffer}) and (@code{tex-region}) do all of their +work in a temporary directory, and do not have available any of the auxiliary +files needed by @TeX{} for cross-references; these commands are generally +not suitable for running the final copy in which all of the cross-references +need to be correct. + + When you want the auxiliary files for cross references, use @kbd{C-c +C-f} (@code{tex-file}) which runs @TeX{} on the current buffer's file, +in that file's directory. Before running @TeX{}, it offers to save any +modified buffers. Generally, you need to use (@code{tex-file}) twice to +get the cross-references right. + +@vindex tex-start-options-string + The value of the variable @code{tex-start-options-string} specifies +options for the @TeX{} run. The default value causes @TeX{} to run in +nonstopmode. To run @TeX{} interactively, set the variable to @code{""}. + +@vindex tex-main-file + Large @TeX{} documents are often split into several files---one main +file, plus subfiles. Running @TeX{} on a subfile typically does not +work; you have to run it on the main file. In order to make +@code{tex-file} useful when you are editing a subfile, you can set the +variable @code{tex-main-file} to the name of the main file. Then +@code{tex-file} runs @TeX{} on that file. + + The most convenient way to use @code{tex-main-file} is to specify it +in a local variable list in each of the subfiles. @xref{File +Variables}. + +@findex tex-bibtex-file +@kindex C-c TAB @r{(@TeX{} mode)} +@vindex tex-bibtex-command + For La@TeX{} files, you can use Bib@TeX{} to process the auxiliary +file for the current buffer's file. Bib@TeX{} looks up bibliographic +citations in a data base and prepares the cited references for the +bibliography section. The command @kbd{C-c TAB} +(@code{tex-bibtex-file}) runs the shell command +(@code{tex-bibtex-command}) to produce a @samp{.bbl} file for the +current buffer's file. Generally, you need to do @kbd{C-c C-f} +(@code{tex-file}) once to generate the @samp{.aux} file, then do +@kbd{C-c TAB} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f} +(@code{tex-file}) twice more to get the cross-references correct. + + For managing all kinds of references, you can use Ref@TeX{}. +@xref{Top, , RefTeX, reftex}. + +@node Nroff Mode +@section Nroff Mode + +@cindex nroff +@findex nroff-mode + Nroff mode is a mode like Text mode but modified to handle nroff commands +present in the text. Invoke @kbd{M-x nroff-mode} to enter this mode. It +differs from Text mode in only a few ways. All nroff command lines are +considered paragraph separators, so that filling will never garble the +nroff commands. Pages are separated by @samp{.bp} commands. Comments +start with backslash-doublequote. Also, three special commands are +provided that are not in Text mode: + +@findex forward-text-line +@findex backward-text-line +@findex count-text-lines +@kindex M-n @r{(Nroff mode)} +@kindex M-p @r{(Nroff mode)} +@kindex M-? @r{(Nroff mode)} +@table @kbd +@item M-n +Move to the beginning of the next line that isn't an nroff command +(@code{forward-text-line}). An argument is a repeat count. +@item M-p +Like @kbd{M-n} but move up (@code{backward-text-line}). +@item M-? +Prints in the echo area the number of text lines (lines that are not +nroff commands) in the region (@code{count-text-lines}). +@end table + +@findex electric-nroff-mode + The other feature of Nroff mode is that you can turn on Electric Nroff +mode. This is a minor mode that you can turn on or off with @kbd{M-x +electric-nroff-mode} (@pxref{Minor Modes}). When the mode is on, each +time you use @key{RET} to end a line that contains an nroff command that +opens a kind of grouping, the matching nroff command to close that +grouping is automatically inserted on the following line. For example, +if you are at the beginning of a line and type @kbd{.@: ( b @key{RET}}, +this inserts the matching command @samp{.)b} on a new line following +point. + + If you use Outline minor mode with Nroff mode (@pxref{Outline Mode}), +heading lines are lines of the form @samp{.H} followed by a number (the +header level). + +@vindex nroff-mode-hook + Entering Nroff mode runs the hook @code{text-mode-hook}, followed by +the hook @code{nroff-mode-hook} (@pxref{Hooks}). + +@node Formatted Text +@section Editing Formatted Text + +@cindex Enriched mode +@cindex mode, Enriched +@cindex formatted text +@cindex WYSIWYG +@cindex word processing + @dfn{Enriched mode} is a minor mode for editing files that contain +formatted text in WYSIWYG fashion, as in a word processor. Currently, +formatted text in Enriched mode can specify fonts, colors, underlining, +margins, and types of filling and justification. In the future, we plan +to implement other formatting features as well. + + Enriched mode is a minor mode (@pxref{Minor Modes}). Typically it is +used in conjunction with Text mode (@pxref{Text Mode}). However, you +can also use it with other major modes such as Outline mode and +Paragraph-Indent Text mode. + + Potentially, Emacs can store formatted text files in various file +formats. Currently, only one format is implemented: @dfn{text/enriched} +format, which is defined by the MIME protocol. @xref{Format +Conversion,, Format Conversion, elisp, the Emacs Lisp Reference Manual}, +for details of how Emacs recognizes and converts file formats. + + The Emacs distribution contains a formatted text file that can serve as +an example. Its name is @file{etc/enriched.doc}. It contains samples +illustrating all the features described in this section. It also +contains a list of ideas for future enhancements. + +@menu +* Requesting Formatted Text:: Entering and exiting Enriched mode. +* Hard and Soft Newlines:: There are two different kinds of newlines. +* Editing Format Info:: How to edit text properties. +* Faces: Format Faces. Bold, italic, underline, etc. +* Color: Format Colors. Changing the color of text. +* Indent: Format Indentation. Changing the left and right margins. +* Justification: Format Justification. + Centering, setting text flush with the + left or right margin, etc. +* Other: Format Properties. The "special" text properties submenu. +* Forcing Enriched Mode:: How to force use of Enriched mode. +@end menu + +@node Requesting Formatted Text +@subsection Requesting to Edit Formatted Text + + Whenever you visit a file that Emacs saved in the text/enriched format, +Emacs automatically converts the formatting information in the file into +Emacs's own internal format (text properties), and turns on Enriched +mode. + +@findex enriched-mode + To create a new file of formatted text, first visit the nonexistent +file, then type @kbd{M-x enriched-mode} before you start inserting text. +This command turns on Enriched mode. Do this before you begin inserting +text, to ensure that the text you insert is handled properly. + + More generally, the command @code{enriched-mode} turns Enriched mode +on if it was off, and off if it was on. With a prefix argument, this +command turns Enriched mode on if the argument is positive, and turns +the mode off otherwise. + + When you save a buffer while Enriched mode is enabled in it, Emacs +automatically converts the text to text/enriched format while writing it +into the file. When you visit the file again, Emacs will automatically +recognize the format, reconvert the text, and turn on Enriched mode +again. + +@vindex enriched-fill-after-visiting + Normally, after visiting a file in text/enriched format, Emacs refills +each paragraph to fit the specified right margin. You can turn off this +refilling, to save time, by setting the variable +@code{enriched-fill-after-visiting} to @code{nil} or to @code{ask}. + + However, when visiting a file that was saved from Enriched mode, there +is no need for refilling, because Emacs saves the right margin settings +along with the text. + +@vindex enriched-translations + You can add annotations for saving additional text properties, which +Emacs normally does not save, by adding to @code{enriched-translations}. +Note that the text/enriched standard requires any non-standard +annotations to have names starting with @samp{x-}, as in +@samp{x-read-only}. This ensures that they will not conflict with +standard annotations that may be added later. + +@node Hard and Soft Newlines +@subsection Hard and Soft Newlines +@cindex hard newline +@cindex soft newline +@cindex newlines, hard and soft + + In formatted text, Emacs distinguishes between two different kinds of +newlines, @dfn{hard} newlines and @dfn{soft} newlines. + + Hard newlines are used to separate paragraphs, or items in a list, or +anywhere that there should always be a line break regardless of the +margins. The @key{RET} command (@code{newline}) and @kbd{C-o} +(@code{open-line}) insert hard newlines. + + Soft newlines are used to make text fit between the margins. All the +fill commands, including Auto Fill, insert soft newlines---and they +delete only soft newlines. + + Although hard and soft newlines look the same, it is important to bear +the difference in mind. Do not use @key{RET} to break lines in the +middle of filled paragraphs, or else you will get hard newlines that are +barriers to further filling. Instead, let Auto Fill mode break lines, +so that if the text or the margins change, Emacs can refill the lines +properly. @xref{Auto Fill}. + + On the other hand, in tables and lists, where the lines should always +remain as you type them, you can use @key{RET} to end lines. For these +lines, you may also want to set the justification style to +@code{unfilled}. @xref{Format Justification}. + +@node Editing Format Info +@subsection Editing Format Information + + There are two ways to alter the formatting information for a formatted +text file: with keyboard commands, and with the mouse. + + The easiest way to add properties to your document is by using the Text +Properties menu. You can get to this menu in two ways: from the Edit +menu in the menu bar, or with @kbd{C-mouse-2} (hold the @key{CTRL} key +and press the middle mouse button). + + Most of the items in the Text Properties menu lead to other submenus. +These are described in the sections that follow. Some items run +commands directly: + +@table @code +@findex facemenu-remove-props +@item Remove Properties +Delete from the region all the text properties that the Text Properties +menu works with (@code{facemenu-remove-props}). + +@findex facemenu-remove-all +@item Remove All +Delete @emph{all} text properties from the region +(@code{facemenu-remove-all}). + +@findex list-text-properties-at +@item List Properties +List all the text properties of the character following point +(@code{list-text-properties-at}). + +@item Display Faces +Display a list of all the defined faces. + +@item Display Colors +Display a list of all the defined colors. +@end table + +@node Format Faces +@subsection Faces in Formatted Text + + The Faces submenu lists various Emacs faces including @code{bold}, +@code{italic}, and @code{underline}. Selecting one of these adds the +chosen face to the region. @xref{Faces}. You can also specify a face +with these keyboard commands: + +@table @kbd +@kindex M-g d @r{(Enriched mode)} +@findex facemenu-set-default +@item M-g d +Set the region, or the next inserted character, to the @code{default} face +(@code{facemenu-set-default}). +@kindex M-g b @r{(Enriched mode)} +@findex facemenu-set-bold +@item M-g b +Set the region, or the next inserted character, to the @code{bold} face +(@code{facemenu-set-bold}). +@kindex M-g i @r{(Enriched mode)} +@findex facemenu-set-italic +@item M-g i +Set the region, or the next inserted character, to the @code{italic} face +(@code{facemenu-set-italic}). +@kindex M-g l @r{(Enriched mode)} +@findex facemenu-set-bold-italic +@item M-g l +Set the region, or the next inserted character, to the @code{bold-italic} face +(@code{facemenu-set-bold-italic}). +@kindex M-g u @r{(Enriched mode)} +@findex facemenu-set-underline +@item M-g u +Set the region, or the next inserted character, to the @code{underline} face +(@code{facemenu-set-underline}). +@kindex M-g o @r{(Enriched mode)} +@findex facemenu-set-face +@item M-g o @var{face} @key{RET} +Set the region, or the next inserted character, to the face @var{face} +(@code{facemenu-set-face}). +@end table + + If you use these commands with a prefix argument---or, in Transient Mark +mode, if the region is not active---then these commands specify a face +to use for your next self-inserting input. @xref{Transient Mark}. This +applies to both the keyboard commands and the menu commands. + + Enriched mode defines two additional faces: @code{excerpt} and +@code{fixed}. These correspond to codes used in the text/enriched file +format. + + The @code{excerpt} face is intended for quotations. This face is the +same as @code{italic} unless you customize it (@pxref{Face Customization}). + + The @code{fixed} face is meant to say, ``Use a fixed-width font for this +part of the text.'' Emacs currently supports only fixed-width fonts; +therefore, the @code{fixed} annotation is not necessary now. However, +we plan to support variable width fonts in future Emacs versions, and +other systems that display text/enriched format may not use a +fixed-width font as the default. So if you specifically want a certain +part of the text to use a fixed-width font, you should specify the +@code{fixed} face for that part. + + The @code{fixed} face is normally defined to use a different font from +the default. However, different systems have different fonts installed, +so you may need to customize this. + + If your terminal cannot display different faces, you will not be able +to see them, but you can still edit documents containing faces. You can +even add faces and colors to documents. They will be visible when the +file is viewed on a terminal that can display them. + +@node Format Colors +@subsection Colors in Formatted Text + + You can specify foreground and background colors for portions of the +text. There is a menu for specifying the foreground color and a menu +for specifying the background color. Each color menu lists all the +colors that you have used in Enriched mode in the current Emacs session. + + If you specify a color with a prefix argument---or, in Transient Mark +mode, if the region is not active---then it applies to your next +self-inserting input. @xref{Transient Mark}. Otherwise, the command +applies to the region. + + Each color menu contains one additional item: @samp{Other}. You can use +this item to specify a color that is not listed in the menu; it reads +the color name with the minibuffer. To display list of available colors +and their names, use the @samp{Display Colors} menu item in the Text +Properties menu (@pxref{Editing Format Info}). + + Any color that you specify in this way, or that is mentioned in a +formatted text file that you read in, is added to both color menus for +the duration of the Emacs session. + +@findex facemenu-set-foreground +@findex facemenu-set-background + There are no key bindings for specifying colors, but you can do so +with the extended commands @kbd{M-x facemenu-set-foreground} and +@kbd{M-x facemenu-set-background}. Both of these commands read the name +of the color with the minibuffer. + +@node Format Indentation +@subsection Indentation in Formatted Text + + When editing formatted text, you can specify different amounts of +indentation for the right or left margin of an entire paragraph or a +part of a paragraph. The margins you specify automatically affect the +Emacs fill commands (@pxref{Filling}) and line-breaking commands. + + The Indentation submenu provides a convenient interface for specifying +these properties. The submenu contains four items: + +@table @code +@kindex C-x TAB @r{(Enriched mode)} +@findex increase-left-margin +@item Indent More +Indent the region by 4 columns (@code{increase-left-margin}). In +Enriched mode, this command is also available on @kbd{C-x @key{TAB}}; if +you supply a numeric argument, that says how many columns to add to the +margin (a negative argument reduces the number of columns). + +@item Indent Less +Remove 4 columns of indentation from the region. + +@item Indent Right More +Make the text narrower by indenting 4 columns at the right margin. + +@item Indent Right Less +Remove 4 columns of indentation from the right margin. +@end table + + You can use these commands repeatedly to increase or decrease the +indentation. + + The most common way to use these commands is to change the indentation +of an entire paragraph. However, that is not the only use. You can +change the margins at any point; the new values take effect at the end +of the line (for right margins) or the beginning of the next line (for +left margins). + + This makes it possible to format paragraphs with @dfn{hanging indents}, +which means that the first line is indented less than subsequent lines. +To set up a hanging indent, increase the indentation of the region +starting after the first word of the paragraph and running until the end +of the paragraph. + + Indenting the first line of a paragraph is easier. Set the margin for +the whole paragraph where you want it to be for the body of the +paragraph, then indent the first line by inserting extra spaces or tabs. + + Sometimes, as a result of editing, the filling of a paragraph becomes +messed up---parts of the paragraph may extend past the left or right +margins. When this happens, use @kbd{M-q} (@code{fill-paragraph}) to +refill the paragraph. + +@vindex standard-indent + The variable @code{standard-indent} specifies how many columns these +commands should add to or subtract from the indentation. The default +value is 4. The overall default right margin for Enriched mode is +controlled by the variable @code{fill-column}, as usual. + + The fill prefix, if any, works in addition to the specified paragraph +indentation: @kbd{C-x .} does not include the specified indentation's +whitespace in the new value for the fill prefix, and the fill commands +look for the fill prefix after the indentation on each line. @xref{Fill +Prefix}. + +@node Format Justification +@subsection Justification in Formatted Text + + When editing formatted text, you can specify various styles of +justification for a paragraph. The style you specify automatically +affects the Emacs fill commands. + + The Justification submenu provides a convenient interface for specifying +the style. The submenu contains five items: + +@table @code +@item Flush Left +This is the most common style of justification (at least for English). +Lines are aligned at the left margin but left uneven at the right. + +@item Flush Right +This aligns each line with the right margin. Spaces and tabs are added +on the left, if necessary, to make lines line up on the right. + +@item Full +This justifies the text, aligning both edges of each line. Justified +text looks very nice in a printed book, where the spaces can all be +adjusted equally, but it does not look as nice with a fixed-width font +on the screen. Perhaps a future version of Emacs will be able to adjust +the width of spaces in a line to achieve elegant justification. + +@item Center +This centers every line between the current margins. + +@item None +This turns off filling entirely. Each line will remain as you wrote it; +the fill and auto-fill functions will have no effect on text which has +this setting. You can, however, still indent the left margin. In +unfilled regions, all newlines are treated as hard newlines (@pxref{Hard +and Soft Newlines}) . +@end table + + In Enriched mode, you can also specify justification from the keyboard +using the @kbd{M-j} prefix character: + +@table @kbd +@kindex M-j l @r{(Enriched mode)} +@findex set-justification-left +@item M-j l +Make the region left-filled (@code{set-justification-left}). +@kindex M-j r @r{(Enriched mode)} +@findex set-justification-right +@item M-j r +Make the region right-filled (@code{set-justification-right}). +@kindex M-j f @r{(Enriched mode)} +@findex set-justification-full +@item M-j f +Make the region fully-justified (@code{set-justification-full}). +@kindex M-j c @r{(Enriched mode)} +@kindex M-S @r{(Enriched mode)} +@findex set-justification-center +@item M-j c +@itemx M-S +Make the region centered (@code{set-justification-center}). +@kindex M-j u @r{(Enriched mode)} +@findex set-justification-none +@item M-j u +Make the region unfilled (@code{set-justification-none}). +@end table + + Justification styles apply to entire paragraphs. All the +justification-changing commands operate on the paragraph containing +point, or, if the region is active, on all paragraphs which overlap the +region. + +@vindex default-justification + The default justification style is specified by the variable +@code{default-justification}. Its value should be one of the symbols +@code{left}, @code{right}, @code{full}, @code{center}, or @code{none}. + +@node Format Properties +@subsection Setting Other Text Properties + + The Other Properties menu lets you add or remove three other useful text +properties: @code{read-only}, @code{invisible} and @code{intangible}. +The @code{intangible} property disallows moving point within the text, +the @code{invisible} text property hides text from display, and the +@code{read-only} property disallows alteration of the text. + + Each of these special properties has a menu item to add it to the +region. The last menu item, @samp{Remove Special}, removes all of these +special properties from the text in the region. + + Currently, the @code{invisible} and @code{intangible} properties are +@emph{not} saved in the text/enriched format. The @code{read-only} +property is saved, but it is not a standard part of the text/enriched +format, so other editors may not respect it. + +@node Forcing Enriched Mode +@subsection Forcing Enriched Mode + + Normally, Emacs knows when you are editing formatted text because it +recognizes the special annotations used in the file that you visited. +However, there are situations in which you must take special actions +to convert file contents or turn on Enriched mode: + +@itemize @bullet +@item +When you visit a file that was created with some other editor, Emacs may +not recognize the file as being in the text/enriched format. In this +case, when you visit the file you will see the formatting commands +rather than the formatted text. Type @kbd{M-x format-decode-buffer} to +translate it. + +@item +When you @emph{insert} a file into a buffer, rather than visiting it. +Emacs does the necessary conversions on the text which you insert, but +it does not enable Enriched mode. If you wish to do that, type @kbd{M-x +enriched-mode}. +@end itemize + + The command @code{format-decode-buffer} translates text in various +formats into Emacs's internal format. It asks you to specify the format +to translate from; however, normally you can type just @key{RET}, which +tells Emacs to guess the format. + +@findex format-find-file + If you wish to look at text/enriched file in its raw form, as a +sequence of characters rather than as formatted text, use the @kbd{M-x +find-file-literally} command. This visits a file, like +@code{find-file}, but does not do format conversion. It also inhibits +character code conversion (@pxref{Coding Systems}) and automatic +uncompression (@pxref{Compressed Files}). To disable format conversion +but allow character code conversion and/or automatic uncompression if +appropriate, use @code{format-find-file} with suitable arguments. + diff --git a/man/trouble.texi b/man/trouble.texi new file mode 100644 index 00000000000..e201b6311ab --- /dev/null +++ b/man/trouble.texi @@ -0,0 +1,972 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@iftex +@chapter Dealing with Common Problems + + If you type an Emacs command you did not intend, the results are often +mysterious. This chapter tells what you can do to cancel your mistake or +recover from a mysterious situation. Emacs bugs and system crashes are +also considered. +@end iftex + +@node Quitting, Lossage, Customization, Top +@section Quitting and Aborting +@cindex quitting + +@table @kbd +@item C-g +@itemx C-@key{BREAK} (MS-DOS) +Quit. Cancel running or partially typed command. +@item C-] +Abort innermost recursive editing level and cancel the command which +invoked it (@code{abort-recursive-edit}). +@item @key{ESC} @key{ESC} @key{ESC} +Either quit or abort, whichever makes sense (@code{keyboard-escape-quit}). +@item M-x top-level +Abort all recursive editing levels that are currently executing. +@item C-x u +Cancel a previously made change in the buffer contents (@code{undo}). +@end table + + There are two ways of canceling commands which are not finished +executing: @dfn{quitting} with @kbd{C-g}, and @dfn{aborting} with +@kbd{C-]} or @kbd{M-x top-level}. Quitting cancels a partially typed +command or one which is already running. Aborting exits a recursive +editing level and cancels the command that invoked the recursive edit. +(@xref{Recursive Edit}.) + +@cindex quitting +@kindex C-g + Quitting with @kbd{C-g} is used for getting rid of a partially typed +command, or a numeric argument that you don't want. It also stops a +running command in the middle in a relatively safe way, so you can use +it if you accidentally give a command which takes a long time. In +particular, it is safe to quit out of killing; either your text will +@emph{all} still be in the buffer, or it will @emph{all} be in the kill +ring (or maybe both). Quitting an incremental search does special +things documented under searching; in general, it may take two +successive @kbd{C-g} characters to get out of a search +(@pxref{Incremental Search}). + + On MS-DOS, the character @kbd{C-@key{BREAK}} serves as a quit character +like @kbd{C-g}. The reason is that it is not feasible, on MS-DOS, to +recognize @kbd{C-g} while a command is running, between interactions +with the user. By contrast, it @emph{is} feasible to recognize +@kbd{C-@key{BREAK}} at all times. @xref{MS-DOS Input}. + + @kbd{C-g} works by setting the variable @code{quit-flag} to @code{t} +the instant @kbd{C-g} is typed; Emacs Lisp checks this variable +frequently and quits if it is non-@code{nil}. @kbd{C-g} is only +actually executed as a command if you type it while Emacs is waiting for +input. + + If you quit with @kbd{C-g} a second time before the first @kbd{C-g} is +recognized, you activate the ``emergency escape'' feature and return to +the shell. @xref{Emergency Escape}. + +@cindex NFS and quitting + There may be times when you cannot quit. When Emacs is waiting for +the operating system to do something, quitting is impossible unless +special pains are taken for the particular system call within Emacs +where the waiting occurs. We have done this for the system calls that +users are likely to want to quit from, but it's possible you will find +another. In one very common case---waiting for file input or output +using NFS---Emacs itself knows how to quit, but most NFS implementations +simply do not allow user programs to stop waiting for NFS when the NFS +server is hung. + +@cindex aborting recursive edit +@findex abort-recursive-edit +@kindex C-] + Aborting with @kbd{C-]} (@code{abort-recursive-edit}) is used to get +out of a recursive editing level and cancel the command which invoked +it. Quitting with @kbd{C-g} does not do this, and could not do this, +because it is used to cancel a partially typed command @emph{within} the +recursive editing level. Both operations are useful. For example, if +you are in a recursive edit and type @kbd{C-u 8} to enter a numeric +argument, you can cancel that argument with @kbd{C-g} and remain in the +recursive edit. + +@findex keyboard-escape-quit +@kindex ESC ESC ESC + The command @kbd{@key{ESC} @key{ESC} @key{ESC}} +(@code{keyboard-escape-quit}) can either quit or abort. This key was +defined because @key{ESC} is used to ``get out'' in many PC programs. +It can cancel a prefix argument, clear a selected region, or get out of +a Query Replace, like @kbd{C-g}. It can get out of the minibuffer or a +recursive edit, like @kbd{C-]}. It can also get out of splitting the +frame into multiple windows, like @kbd{C-x 1}. One thing it cannot do, +however, is stop a command that is running. That's because it executes +as an ordinary command, and Emacs doesn't notice it until it is ready +for a command. + +@findex top-level + The command @kbd{M-x top-level} is equivalent to ``enough'' @kbd{C-]} +commands to get you out of all the levels of recursive edits that you +are in. @kbd{C-]} gets you out one level at a time, but @kbd{M-x +top-level} goes out all levels at once. Both @kbd{C-]} and @kbd{M-x +top-level} are like all other commands, and unlike @kbd{C-g}, in that +they take effect only when Emacs is ready for a command. @kbd{C-]} is +an ordinary key and has its meaning only because of its binding in the +keymap. @xref{Recursive Edit}. + + @kbd{C-x u} (@code{undo}) is not strictly speaking a way of canceling +a command, but you can think of it as canceling a command that already +finished executing. @xref{Undo}. + +@node Lossage, Bugs, Quitting, Top +@section Dealing with Emacs Trouble + + This section describes various conditions in which Emacs fails to work +normally, and how to recognize them and correct them. + +@menu +* DEL Gets Help:: What to do if @key{DEL} doesn't delete. +* Stuck Recursive:: `[...]' in mode line around the parentheses. +* Screen Garbled:: Garbage on the screen. +* Text Garbled:: Garbage in the text. +* Unasked-for Search:: Spontaneous entry to incremental search. +* Memory Full:: How to cope when you run out of memory. +* After a Crash:: Recovering editing in an Emacs session that crashed. +* Emergency Escape:: Emergency escape--- + What to do if Emacs stops responding. +* Total Frustration:: When you are at your wits' end. +@end menu + +@node DEL Gets Help +@subsection If @key{DEL} Fails to Delete + + If you find that @key{DEL} enters Help like @kbd{Control-h} instead of +deleting a character, your terminal is sending the wrong code for +@key{DEL}. You can work around this problem by changing the keyboard +translation table (@pxref{Keyboard Translations}). + +@node Stuck Recursive +@subsection Recursive Editing Levels + + Recursive editing levels are important and useful features of Emacs, but +they can seem like malfunctions to the user who does not understand them. + + If the mode line has square brackets @samp{[@dots{}]} around the parentheses +that contain the names of the major and minor modes, you have entered a +recursive editing level. If you did not do this on purpose, or if you +don't understand what that means, you should just get out of the recursive +editing level. To do so, type @kbd{M-x top-level}. This is called getting +back to top level. @xref{Recursive Edit}. + +@node Screen Garbled +@subsection Garbage on the Screen + + If the data on the screen looks wrong, the first thing to do is see +whether the text is really wrong. Type @kbd{C-l}, to redisplay the +entire screen. If the screen appears correct after this, the problem +was entirely in the previous screen update. (Otherwise, see @ref{Text +Garbled}.) + + Display updating problems often result from an incorrect termcap entry +for the terminal you are using. The file @file{etc/TERMS} in the Emacs +distribution gives the fixes for known problems of this sort. +@file{INSTALL} contains general advice for these problems in one of its +sections. Very likely there is simply insufficient padding for certain +display operations. To investigate the possibility that you have this sort +of problem, try Emacs on another terminal made by a different manufacturer. +If problems happen frequently on one kind of terminal but not another kind, +it is likely to be a bad termcap entry, though it could also be due to a +bug in Emacs that appears for terminals that have or that lack specific +features. + +@node Text Garbled +@subsection Garbage in the Text + + If @kbd{C-l} shows that the text is wrong, try undoing the changes to it +using @kbd{C-x u} until it gets back to a state you consider correct. Also +try @kbd{C-h l} to find out what command you typed to produce the observed +results. + + If a large portion of text appears to be missing at the beginning or +end of the buffer, check for the word @samp{Narrow} in the mode line. +If it appears, the text you don't see is probably still present, but +temporarily off-limits. To make it accessible again, type @kbd{C-x n +w}. @xref{Narrowing}. + +@node Unasked-for Search +@subsection Spontaneous Entry to Incremental Search + + If Emacs spontaneously displays @samp{I-search:} at the bottom of the +screen, it means that the terminal is sending @kbd{C-s} and @kbd{C-q} +according to the poorly designed xon/xoff ``flow control'' protocol. + + If this happens to you, your best recourse is to put the terminal in a +mode where it will not use flow control, or give it so much padding that +it will never send a @kbd{C-s}. (One way to increase the amount of +padding is to set the variable @code{baud-rate} to a larger value. Its +value is the terminal output speed, measured in the conventional units +of baud.) + +@cindex flow control +@cindex xon-xoff +@findex enable-flow-control + If you don't succeed in turning off flow control, the next best thing +is to tell Emacs to cope with it. To do this, call the function +@code{enable-flow-control}. + +@findex enable-flow-control-on + Typically there are particular terminal types with which you must use +flow control. You can conveniently ask for flow control on those +terminal types only, using @code{enable-flow-control-on}. For example, +if you find you must use flow control on VT-100 and H19 terminals, put +the following in your @file{.emacs} file: + +@example +(enable-flow-control-on "vt100" "h19") +@end example + + When flow control is enabled, you must type @kbd{C-\} to get the +effect of a @kbd{C-s}, and type @kbd{C-^} to get the effect of a +@kbd{C-q}. (These aliases work by means of keyboard translations; see +@ref{Keyboard Translations}.) + +@node Memory Full +@subsection Running out of Memory +@cindex memory full +@cindex out of memory + + If you get the error message @samp{Virtual memory exceeded}, save your +modified buffers with @kbd{C-x s}. This method of saving them has the +smallest need for additional memory. Emacs keeps a reserve of memory +which it makes available when this error happens; that should be enough +to enable @kbd{C-x s} to complete its work. + + Once you have saved your modified buffers, you can exit this Emacs job +and start another, or you can use @kbd{M-x kill-some-buffers} to free +space in the current Emacs job. If you kill buffers containing a +substantial amount of text, you can safely go on editing. Emacs refills +its memory reserve automatically when it sees sufficient free space +available, in case you run out of memory another time. + + Do not use @kbd{M-x buffer-menu} to save or kill buffers when you run +out of memory, because the buffer menu needs a fair amount memory +itself, and the reserve supply may not be enough. + +@node After a Crash +@subsection Recovery After a Crash + + If Emacs or the computer crashes, you can recover the files you were +editing at the time of the crash from their auto-save files. To do +this, start Emacs again and type the command @kbd{M-x recover-session}. + + This command initially displays a buffer which lists interrupted +session files, each with its date. You must choose which session to +recover from. Typically the one you want is the most recent one. Move +point to the one you choose, and type @kbd{C-c C-c}. + + Then @code{recover-session} asks about each of the files that you were +editing during that session; it asks whether to recover that file. If +you answer @kbd{y} for a file, it shows the dates of that file and its +auto-save file, then asks once again whether to recover that file. For +the second question, you must confirm with @kbd{yes}. If you do, Emacs +visits the file but gets the text from the auto-save file. + + When @code{recover-session} is done, the files you've chosen to +recover are present in Emacs buffers. You should then save them. Only +this---saving them---updates the files themselves. + +@node Emergency Escape +@subsection Emergency Escape + + Because at times there have been bugs causing Emacs to loop without +checking @code{quit-flag}, a special feature causes Emacs to be suspended +immediately if you type a second @kbd{C-g} while the flag is already set, +so you can always get out of GNU Emacs. Normally Emacs recognizes and +clears @code{quit-flag} (and quits!) quickly enough to prevent this from +happening. (On MS-DOS and compatible systems, type @kbd{C-@key{BREAK}} +twice.) + + When you resume Emacs after a suspension caused by multiple @kbd{C-g}, it +asks two questions before going back to what it had been doing: + +@example +Auto-save? (y or n) +Abort (and dump core)? (y or n) +@end example + +@noindent +Answer each one with @kbd{y} or @kbd{n} followed by @key{RET}. + + Saying @kbd{y} to @samp{Auto-save?} causes immediate auto-saving of all +modified buffers in which auto-saving is enabled. + + Saying @kbd{y} to @samp{Abort (and dump core)?} causes an illegal instruction to be +executed, dumping core. This is to enable a wizard to figure out why Emacs +was failing to quit in the first place. Execution does not continue +after a core dump. If you answer @kbd{n}, execution does continue. With +luck, GNU Emacs will ultimately check @code{quit-flag} and quit normally. +If not, and you type another @kbd{C-g}, it is suspended again. + + If Emacs is not really hung, just slow, you may invoke the double +@kbd{C-g} feature without really meaning to. Then just resume and answer +@kbd{n} to both questions, and you will arrive at your former state. +Presumably the quit you requested will happen soon. + + The double-@kbd{C-g} feature is turned off when Emacs is running under +the X Window System, since you can use the window manager to kill Emacs +or to create another window and run another program. + + On MS-DOS and compatible systems, the emergency escape feature is +sometimes unavailable, even if you press @kbd{C-@key{BREAK}} twice, when +some system call (MS-DOS or BIOS) hangs, or when Emacs is stuck in a +very tight endless loop (in C code, @strong{not} in Lisp code). + +@node Total Frustration +@subsection Help for Total Frustration +@cindex Eliza +@cindex doctor + + If using Emacs (or something else) becomes terribly frustrating and none +of the techniques described above solve the problem, Emacs can still help +you. + + First, if the Emacs you are using is not responding to commands, type +@kbd{C-g C-g} to get out of it and then start a new one. + +@findex doctor + Second, type @kbd{M-x doctor @key{RET}}. + + The doctor will help you feel better. Each time you say something to +the doctor, you must end it by typing @key{RET} @key{RET}. This lets +the doctor know you are finished. + +@node Bugs, Contributing, Lossage, Top +@section Reporting Bugs + +@cindex bugs + Sometimes you will encounter a bug in Emacs. Although we cannot +promise we can or will fix the bug, and we might not even agree that it +is a bug, we want to hear about problems you encounter. Often we agree +they are bugs and want to fix them. + + To make it possible for us to fix a bug, you must report it. In order +to do so effectively, you must know when and how to do it. + +@menu +* Criteria: Bug Criteria. Have you really found a bug? +* Understanding Bug Reporting:: How to report a bug effectively. +* Checklist:: Steps to follow for a good bug report. +* Sending Patches:: How to send a patch for GNU Emacs. +@end menu + +@node Bug Criteria +@subsection When Is There a Bug + + If Emacs executes an illegal instruction, or dies with an operating +system error message that indicates a problem in the program (as opposed to +something like ``disk full''), then it is certainly a bug. + + If Emacs updates the display in a way that does not correspond to what is +in the buffer, then it is certainly a bug. If a command seems to do the +wrong thing but the problem corrects itself if you type @kbd{C-l}, it is a +case of incorrect display updating. + + Taking forever to complete a command can be a bug, but you must make +certain that it was really Emacs's fault. Some commands simply take a +long time. Type @kbd{C-g} (@kbd{C-@key{BREAK}} on MS-DOS) and then @kbd{C-h l} +to see whether the input Emacs received was what you intended to type; +if the input was such that you @emph{know} it should have been processed +quickly, report a bug. If you don't know whether the command should +take a long time, find out by looking in the manual or by asking for +assistance. + + If a command you are familiar with causes an Emacs error message in a +case where its usual definition ought to be reasonable, it is probably a +bug. + + If a command does the wrong thing, that is a bug. But be sure you know +for certain what it ought to have done. If you aren't familiar with the +command, or don't know for certain how the command is supposed to work, +then it might actually be working right. Rather than jumping to +conclusions, show the problem to someone who knows for certain. + + Finally, a command's intended definition may not be best for editing +with. This is a very important sort of problem, but it is also a matter of +judgment. Also, it is easy to come to such a conclusion out of ignorance +of some of the existing features. It is probably best not to complain +about such a problem until you have checked the documentation in the usual +ways, feel confident that you understand it, and know for certain that what +you want is not available. If you are not sure what the command is +supposed to do after a careful reading of the manual, check the index and +glossary for any terms that may be unclear. + + If after careful rereading of the manual you still do not understand +what the command should do, that indicates a bug in the manual, which +you should report. The manual's job is to make everything clear to +people who are not Emacs experts---including you. It is just as +important to report documentation bugs as program bugs. + + If the on-line documentation string of a function or variable disagrees +with the manual, one of them must be wrong; that is a bug. + +@node Understanding Bug Reporting +@subsection Understanding Bug Reporting + +@findex emacs-version + When you decide that there is a bug, it is important to report it and to +report it in a way which is useful. What is most useful is an exact +description of what commands you type, starting with the shell command to +run Emacs, until the problem happens. + + The most important principle in reporting a bug is to report +@emph{facts}. Hypotheses and verbal descriptions are no substitute for +the detailed raw data. Reporting the facts is straightforward, but many +people strain to posit explanations and report them instead of the +facts. If the explanations are based on guesses about how Emacs is +implemented, they will be useless; meanwhile, lacking the facts, we will +have no real information about the bug. + + For example, suppose that you type @kbd{C-x C-f /glorp/baz.ugh +@key{RET}}, visiting a file which (you know) happens to be rather large, +and Emacs displayed @samp{I feel pretty today}. The best way to report +the bug is with a sentence like the preceding one, because it gives all +the facts. + + A bad way would be to assume that the problem is due to the size of +the file and say, ``I visited a large file, and Emacs displayed @samp{I +feel pretty today}.'' This is what we mean by ``guessing +explanations.'' The problem is just as likely to be due to the fact +that there is a @samp{z} in the file name. If this is so, then when we +got your report, we would try out the problem with some ``large file,'' +probably with no @samp{z} in its name, and not see any problem. There +is no way in the world that we could guess that we should try visiting a +file with a @samp{z} in its name. + + Alternatively, the problem might be due to the fact that the file starts +with exactly 25 spaces. For this reason, you should make sure that you +inform us of the exact contents of any file that is needed to reproduce the +bug. What if the problem only occurs when you have typed the @kbd{C-x C-a} +command previously? This is why we ask you to give the exact sequence of +characters you typed since starting the Emacs session. + + You should not even say ``visit a file'' instead of @kbd{C-x C-f} unless +you @emph{know} that it makes no difference which visiting command is used. +Similarly, rather than saying ``if I have three characters on the line,'' +say ``after I type @kbd{@key{RET} A B C @key{RET} C-p},'' if that is +the way you entered the text.@refill + + So please don't guess any explanations when you report a bug. If you +want to actually @emph{debug} the problem, and report explanations that +are more than guesses, that is useful---but please include the facts as +well. + +@node Checklist +@subsection Checklist for Bug Reports + +@cindex reporting bugs + The best way to send a bug report is to mail it electronically to the +Emacs maintainers at @samp{bug-gnu-emacs@@gnu.org}. (If you +want to suggest a change as an improvement, use the same address.) + + If you'd like to read the bug reports, you can find them on the +newsgroup @samp{gnu.emacs.bug}; keep in mind, however, that as a +spectator you should not criticize anything about what you see there. +The purpose of bug reports is to give information to the Emacs +maintainers. Spectators are welcome only as long as they do not +interfere with this. In particular, some bug reports contain large +amounts of data; spectators should not complain about this. + + Please do not post bug reports using netnews; mail is more reliable +than netnews about reporting your correct address, which we may need in +order to ask you for more information. + + If you can't send electronic mail, then mail the bug report on paper +or machine-readable media to this address: + +@format +GNU Emacs Bugs +Free Software Foundation +59 Temple Place, Suite 330 +Boston, MA 02111-1307 USA +@end format + + We do not promise to fix the bug; but if the bug is serious, +or ugly, or easy to fix, chances are we will want to. + +@findex report-emacs-bug + A convenient way to send a bug report for Emacs is to use the command +@kbd{M-x report-emacs-bug}. This sets up a mail buffer (@pxref{Sending +Mail}) and automatically inserts @emph{some} of the essential +information. However, it cannot supply all the necessary information; +you should still read and follow the guidelines below, so you can enter +the other crucial information by hand before you send the message. + + To enable maintainers to investigate a bug, your report +should include all these things: + +@itemize @bullet +@item +The version number of Emacs. Without this, we won't know whether there +is any point in looking for the bug in the current version of GNU +Emacs. + +You can get the version number by typing @kbd{M-x emacs-version +@key{RET}}. If that command does not work, you probably have something +other than GNU Emacs, so you will have to report the bug somewhere +else. + +@item +The type of machine you are using, and the operating system name and +version number. @kbd{M-x emacs-version @key{RET}} provides this +information too. Copy its output from the @samp{*Messages*} buffer, so +that you get it all and get it accurately. + +@item +The operands given to the @code{configure} command when Emacs was +installed. + +@item +A complete list of any modifications you have made to the Emacs source. +(We may not have time to investigate the bug unless it happens in an +unmodified Emacs. But if you've made modifications and you don't tell +us, you are sending us on a wild goose chase.) + +Be precise about these changes. A description in English is not +enough---send a context diff for them. + +Adding files of your own, or porting to another machine, is a +modification of the source. + +@item +Details of any other deviations from the standard procedure for installing +GNU Emacs. + +@item +The complete text of any files needed to reproduce the bug. + + If you can tell us a way to cause the problem without visiting any files, +please do so. This makes it much easier to debug. If you do need files, +make sure you arrange for us to see their exact contents. For example, it +can often matter whether there are spaces at the ends of lines, or a +newline after the last line in the buffer (nothing ought to care whether +the last line is terminated, but try telling the bugs that). + +@item +The precise commands we need to type to reproduce the bug. + +@findex open-dribble-file +@cindex dribble file + The easy way to record the input to Emacs precisely is to write a +dribble file. To start the file, execute the Lisp expression + +@example +(open-dribble-file "~/dribble") +@end example + +@noindent +using @kbd{M-:} or from the @samp{*scratch*} buffer just after +starting Emacs. From then on, Emacs copies all your input to the +specified dribble file until the Emacs process is killed. + +@item +@findex open-termscript +@cindex termscript file +@cindex @code{TERM} environment variable +For possible display bugs, the terminal type (the value of environment +variable @code{TERM}), the complete termcap entry for the terminal from +@file{/etc/termcap} (since that file is not identical on all machines), +and the output that Emacs actually sent to the terminal. + +The way to collect the terminal output is to execute the Lisp expression + +@example +(open-termscript "~/termscript") +@end example + +@noindent +using @kbd{M-:} or from the @samp{*scratch*} buffer just after +starting Emacs. From then on, Emacs copies all terminal output to the +specified termscript file as well, until the Emacs process is killed. +If the problem happens when Emacs starts up, put this expression into +your @file{.emacs} file so that the termscript file will be open when +Emacs displays the screen for the first time. + +Be warned: it is often difficult, and sometimes impossible, to fix a +terminal-dependent bug without access to a terminal of the type that +stimulates the bug.@refill + +@item +A description of what behavior you observe that you believe is +incorrect. For example, ``The Emacs process gets a fatal signal,'' or, +``The resulting text is as follows, which I think is wrong.'' + +Of course, if the bug is that Emacs gets a fatal signal, then one can't +miss it. But if the bug is incorrect text, the maintainer might fail to +notice what is wrong. Why leave it to chance? + +Even if the problem you experience is a fatal signal, you should still +say so explicitly. Suppose something strange is going on, such as, your +copy of the source is out of sync, or you have encountered a bug in the +C library on your system. (This has happened!) Your copy might crash +and the copy here might not. If you @emph{said} to expect a crash, then +when Emacs here fails to crash, we would know that the bug was not +happening. If you don't say to expect a crash, then we would not know +whether the bug was happening---we would not be able to draw any +conclusion from our observations. + +@item +If the manifestation of the bug is an Emacs error message, it is +important to report the precise text of the error message, and a +backtrace showing how the Lisp program in Emacs arrived at the error. + +To get the error message text accurately, copy it from the +@samp{*Messages*} buffer into the bug report. Copy all of it, not just +part. + +To make a backtrace for the error, evaluate the Lisp expression +@code{(setq @w{debug-on-error t})} before the error happens (that is to +say, you must execute that expression and then make the bug happen). +This causes the error to run the Lisp debugger, which shows you a +backtrace. Copy the text of the debugger's backtrace into the bug +report. + +This use of the debugger is possible only if you know how to make the +bug happen again. If you can't make it happen again, at least copy +the whole error message. + +@item +Check whether any programs you have loaded into the Lisp world, +including your @file{.emacs} file, set any variables that may affect the +functioning of Emacs. Also, see whether the problem happens in a +freshly started Emacs without loading your @file{.emacs} file (start +Emacs with the @code{-q} switch to prevent loading the init file). If +the problem does @emph{not} occur then, you must report the precise +contents of any programs that you must load into the Lisp world in order +to cause the problem to occur. + +@item +If the problem does depend on an init file or other Lisp programs that +are not part of the standard Emacs system, then you should make sure it +is not a bug in those programs by complaining to their maintainers +first. After they verify that they are using Emacs in a way that is +supposed to work, they should report the bug. + +@item +If you wish to mention something in the GNU Emacs source, show the line +of code with a few lines of context. Don't just give a line number. + +The line numbers in the development sources don't match those in your +sources. It would take extra work for the maintainers to determine what +code is in your version at a given line number, and we could not be +certain. + +@item +Additional information from a C debugger such as GDB might enable +someone to find a problem on a machine which he does not have available. +If you don't know how to use GDB, please read the GDB manual---it is not +very long, and using GDB is easy. You can find the GDB distribution, +including the GDB manual in online form, in most of the same places you +can find the Emacs distribution. To run Emacs under GDB, you should +switch to the @file{src} subdirectory in which Emacs was compiled, then +do @samp{gdb emacs}. It is important for the directory @file{src} to be +current so that GDB will read the @file{.gdbinit} file in this +directory. + +However, you need to think when you collect the additional information +if you want it to show what causes the bug. + +@cindex backtrace for bug reports +For example, many people send just a backtrace, but that is not very +useful by itself. A simple backtrace with arguments often conveys +little about what is happening inside GNU Emacs, because most of the +arguments listed in the backtrace are pointers to Lisp objects. The +numeric values of these pointers have no significance whatever; all that +matters is the contents of the objects they point to (and most of the +contents are themselves pointers). + +@findex debug_print +To provide useful information, you need to show the values of Lisp +objects in Lisp notation. Do this for each variable which is a Lisp +object, in several stack frames near the bottom of the stack. Look at +the source to see which variables are Lisp objects, because the debugger +thinks of them as integers. + +To show a variable's value in Lisp syntax, first print its value, then +use the user-defined GDB command @code{pr} to print the Lisp object in +Lisp syntax. (If you must use another debugger, call the function +@code{debug_print} with the object as an argument.) The @code{pr} +command is defined by the file @file{.gdbinit}, and it works only if you +are debugging a running process (not with a core dump). + +To make Lisp errors stop Emacs and return to GDB, put a breakpoint at +@code{Fsignal}. + +To find out which Lisp functions are running, using GDB, move up the +stack, and each time you get to a frame for the function +@code{Ffuncall}, type these GDB commands: + +@example +p *args +pr +@end example + +@noindent +To print the first argument that the function received, use these +commands: + +@example +p args[1] +pr +@end example + +@noindent +You can print the other arguments likewise. The argument @code{nargs} +of @code{Ffuncall} says how many arguments @code{Ffuncall} received; +these include the Lisp function itself and the arguments for that +function. + +The file @file{.gdbinit} defines several other commands that are useful +for examining the data types and contents of Lisp objects. Their names +begin with @samp{x}. These commands work at a lower level than +@code{pr}, and are less convenient, but they may work even when +@code{pr} does not, such as when debugging a core dump or when Emacs has +had a fatal signal. + +@item +If the symptom of the bug is that Emacs fails to respond, don't assume +Emacs is ``hung''---it may instead be in an infinite loop. To find out +which, make the problem happen under GDB and stop Emacs once it is not +responding. (If Emacs is using X Windows directly, you can stop Emacs +by typing @kbd{C-z} at the GDB job.) Then try stepping with +@samp{step}. If Emacs is hung, the @samp{step} command won't return. +If it is looping, @samp{step} will return. + +If this shows Emacs is hung in a system call, stop it again and examine +the arguments of the call. In your bug report, state exactly where in +the source the system call is, and what the arguments are. + +If Emacs is in an infinite loop, please determine where the loop starts +and ends. The easiest way to do this is to use the GDB command +@samp{finish}. Each time you use it, Emacs resumes execution until it +exits one stack frame. Keep typing @samp{finish} until it doesn't +return---that means the infinite loop is in the stack frame which you +just tried to finish. + +Stop Emacs again, and use @samp{finish} repeatedly again until you get +@emph{back to} that frame. Then use @samp{next} to step through that +frame. By stepping, you will see where the loop starts and ends. Also +please examine the data being used in the loop and try to determine why +the loop does not exit when it should. Include all of this information +in your bug report. +@end itemize + +Here are some things that are not necessary in a bug report: + +@itemize @bullet +@item +A description of the envelope of the bug---this is not necessary for a +reproducible bug. + +Often people who encounter a bug spend a lot of time investigating +which changes to the input file will make the bug go away and which +changes will not affect it. + +This is often time-consuming and not very useful, because the way we +will find the bug is by running a single example under the debugger with +breakpoints, not by pure deduction from a series of examples. You might +as well save time by not searching for additional examples. + +Of course, if you can find a simpler example to report @emph{instead} of +the original one, that is a convenience. Errors in the output will be +easier to spot, running under the debugger will take less time, etc. + +However, simplification is not vital; if you can't do this or don't have +time to try, please report the bug with your original test case. + +@item +A system-call trace of Emacs execution. + +System-call traces are very useful for certain special kinds of +debugging, but in most cases they give little useful information. It is +therefore strange that many people seem to think that @emph{the} way to +report information about a crash is to send a system-call trace. Perhaps +this is a habit formed from experience debugging programs that don't +have source code or debugging symbols. + +In most programs, a backtrace is normally far, far more informative than +a system-call trace. Even in Emacs, a simple backtrace is generally +more informative, though to give full information you should supplement +the backtrace by displaying variable values and printing them as Lisp +objects with @code{pr} (see above). + +@item +A patch for the bug. + +A patch for the bug is useful if it is a good one. But don't omit the +other information that a bug report needs, such as the test case, on the +assumption that a patch is sufficient. We might see problems with your +patch and decide to fix the problem another way, or we might not +understand it at all. And if we can't understand what bug you are +trying to fix, or why your patch should be an improvement, we mustn't +install it. + +@ifinfo +@xref{Sending Patches}, for guidelines on how to make it easy for us to +understand and install your patches. +@end ifinfo + +@item +A guess about what the bug is or what it depends on. + +Such guesses are usually wrong. Even experts can't guess right about +such things without first using the debugger to find the facts. +@end itemize + +@node Sending Patches +@subsection Sending Patches for GNU Emacs + +@cindex sending patches for GNU Emacs +@cindex patches, sending + If you would like to write bug fixes or improvements for GNU Emacs, +that is very helpful. When you send your changes, please follow these +guidelines to make it easy for the maintainers to use them. If you +don't follow these guidelines, your information might still be useful, +but using it will take extra work. Maintaining GNU Emacs is a lot of +work in the best of circumstances, and we can't keep up unless you do +your best to help. + +@itemize @bullet +@item +Send an explanation with your changes of what problem they fix or what +improvement they bring about. For a bug fix, just include a copy of the +bug report, and explain why the change fixes the bug. + +(Referring to a bug report is not as good as including it, because then +we will have to look it up, and we have probably already deleted it if +we've already fixed the bug.) + +@item +Always include a proper bug report for the problem you think you have +fixed. We need to convince ourselves that the change is right before +installing it. Even if it is correct, we might have trouble +understanding it if we don't have a way to reproduce the problem. + +@item +Include all the comments that are appropriate to help people reading the +source in the future understand why this change was needed. + +@item +Don't mix together changes made for different reasons. +Send them @emph{individually}. + +If you make two changes for separate reasons, then we might not want to +install them both. We might want to install just one. If you send them +all jumbled together in a single set of diffs, we have to do extra work +to disentangle them---to figure out which parts of the change serve +which purpose. If we don't have time for this, we might have to ignore +your changes entirely. + +If you send each change as soon as you have written it, with its own +explanation, then two changes never get tangled up, and we can consider +each one properly without any extra work to disentangle them. + +@item +Send each change as soon as that change is finished. Sometimes people +think they are helping us by accumulating many changes to send them all +together. As explained above, this is absolutely the worst thing you +could do. + +Since you should send each change separately, you might as well send it +right away. That gives us the option of installing it immediately if it +is important. + +@item +Use @samp{diff -c} to make your diffs. Diffs without context are hard +to install reliably. More than that, they are hard to study; we must +always study a patch to decide whether we want to install it. Unidiff +format is better than contextless diffs, but not as easy to read as +@samp{-c} format. + +If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when +making diffs of C code. This shows the name of the function that each +change occurs in. + +@item +Avoid any ambiguity as to which is the old version and which is the new. +Please make the old version the first argument to diff, and the new +version the second argument. And please give one version or the other a +name that indicates whether it is the old version or your new changed +one. + +@item +Write the change log entries for your changes. This is both to save us +the extra work of writing them, and to help explain your changes so we +can understand them. + +The purpose of the change log is to show people where to find what was +changed. So you need to be specific about what functions you changed; +in large functions, it's often helpful to indicate where within the +function the change was. + +On the other hand, once you have shown people where to find the change, +you need not explain its purpose in the change log. Thus, if you add a +new function, all you need to say about it is that it is new. If you +feel that the purpose needs explaining, it probably does---but put the +explanation in comments in the code. It will be more useful there. + +Please read the @file{ChangeLog} files in the @file{src} and @file{lisp} +directories to see what sorts of information to put in, and to learn the +style that we use. If you would like your name to appear in the header +line, showing who made the change, send us the header line. +@xref{Change Log}. + +@item +When you write the fix, keep in mind that we can't install a change that +would break other systems. Please think about what effect your change +will have if compiled on another type of system. + +Sometimes people send fixes that @emph{might} be an improvement in +general---but it is hard to be sure of this. It's hard to install +such changes because we have to study them very carefully. Of course, +a good explanation of the reasoning by which you concluded the change +was correct can help convince us. + +The safest changes are changes to the configuration files for a +particular machine. These are safe because they can't create new bugs +on other machines. + +Please help us keep up with the workload by designing the patch in a +form that is clearly safe to install. +@end itemize + +@node Contributing, Service, Bugs, Top +@section Contributing to Emacs Development + +If you would like to help pretest Emacs releases to assure they work +well, or if you would like to work on improving Emacs, please contact +the maintainers at @code{bug-gnu-emacs@@gnu.org}. A pretester +should be prepared to investigate bugs as well as report them. If you'd +like to work on improving Emacs, please ask for suggested projects or +suggest your own ideas. + +If you have already written an improvement, please tell us about it. If +you have not yet started work, it is useful to contact +@code{bug-gnu-emacs@@gnu.org} before you start; it might be +possible to suggest ways to make your extension fit in better with the +rest of Emacs. + +@node Service, Command Arguments, Contributing, Top +@section How To Get Help with GNU Emacs + +If you need help installing, using or changing GNU Emacs, there are two +ways to find it: + +@itemize @bullet +@item +Send a message to the mailing list +@code{help-gnu-emacs@@gnu.org}, or post your request on +newsgroup @code{gnu.emacs.help}. (This mailing list and newsgroup +interconnect, so it does not matter which one you use.) + +@item +Look in the service directory for someone who might help you for a fee. +The service directory is found in the file named @file{etc/SERVICE} in the +Emacs distribution. +@end itemize diff --git a/man/vip.texi b/man/vip.texi new file mode 100644 index 00000000000..967aef2808b --- /dev/null +++ b/man/vip.texi @@ -0,0 +1,1945 @@ +\input texinfo + +@setfilename ../info/vip +@settitle VIP + +@dircategory Editors +@direntry +* VIP: (vip). An older VI-emulation for Emacs. +@end direntry + +@iftex +@finalout +@end iftex + +@titlepage +@sp 10 +@center @titlefont{VIP} +@sp 1 +@center A Vi Package for GNU Emacs +@center (Version 3.5, September 15, 1987) +@sp 2 +@center Masahiko Sato +@sp 2 +@end titlepage + +@unnumbered Distribution + +Copyright @copyright{} 1987 Masahiko Sato. + +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 +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the same conditions as for modified versions. + +@ifinfo +@node Top, Survey,, (DIR) +@top VIP + +VIP is a Vi emulating package written in Emacs Lisp. VIP implements most +Vi commands including Ex commands. It is therefore hoped that this package +will enable you to do Vi style editing under the powerful GNU Emacs +environment. This info file describes the usage of VIP assuming that you +are fairly accustomed to Vi but not so much with Emacs. Also we will +concentrate mainly on differences from Vi, especially features unique to +VIP. + +It is recommended that you read nodes on survey and on customization before +you start using VIP. Other nodes may be visited as needed. + +Comments and bug reports are welcome. Please send messages to +@code{ms@@Sail.Stanford.Edu} if you are outside of Japan and to +@code{masahiko@@sato.riec.tohoku.junet} if you are in Japan.@refill + +@end ifinfo + +@menu +* Survey:: A survey of VIP. +* Vi Commands:: Details of Vi commands. +* Ex Commands:: Details of Ex commands. +* Customization:: How to customize VIP. +@end menu +@iftex +@unnumbered Introduction + +VIP is a Vi emulating package written in Emacs Lisp. VIP implements most +Vi commands including Ex commands. It is therefore hoped that this package +will enable you to do Vi style editing under the powerful GNU Emacs +environment. This manual describes the usage of VIP assuming that you are +fairly accustomed to Vi but not so much with Emacs. Also we will +concentrate mainly on differences from Vi, especially features unique to +VIP. + +It is recommended that you read chapters on survey and on customization +before you start using VIP. Other chapters may be used as future +references. + +Comments and bug reports are welcome. Please send messages to +@code{ms@@Sail.Stanford.Edu} if you are outside of Japan and to +@code{masahiko@@unsun.riec.tohoku.junet} if you are in Japan. +@end iftex + +@node Survey, Basic Concepts, Top, Top +@chapter A Survey of VIP + +In this chapter we describe basics of VIP with emphasis on the features not +found in Vi and on how to use VIP under GNU Emacs. + +@menu +* Basic Concepts:: Basic concepts in Emacs. +* Loading VIP:: How to load VIP automatically. +* Modes in VIP:: VIP has three modes, which are orthogonal to modes + in Emacs. +* Differences from Vi:: Differences of VIP from Vi is explained. +@end menu + +@node Basic Concepts, Loading VIP, Survey, Survey +@section Basic Concepts + +We begin by explaining some basic concepts of Emacs. These concepts are +explained in more detail in the GNU Emacs Manual. + +@cindex buffer +@cindex point +@cindex mark +@cindex text +@cindex looking at +@cindex end (of buffer) +@cindex region + +Conceptually, a @dfn{buffer} is just a string of ASCII characters and two +special characters @key{PNT} (@dfn{point}) and @key{MRK} (@dfn{mark}) such +that the character @key{PNT} occurs exactly once and @key{MRK} occurs at +most once. The @dfn{text} of a buffer is obtained by deleting the +occurrences of @key{PNT} and @key{MRK}. If, in a buffer, there is a +character following @key{PNT} then we say that point is @dfn{looking at} +the character; otherwise we say that point is @dfn{at the end of buffer}. +@key{PNT} and @key{MRK} are used +to indicate positions in a buffer and they are not part of the text of the +buffer. If a buffer contains a @key{MRK} then the text between @key{MRK} +and @key{PNT} is called the @dfn{region} of the buffer.@refill + +@cindex window + +Emacs provides (multiple) @dfn{windows} on the screen, and you can see the +content of a buffer through the window associated with the buffer. The +cursor of the screen is always positioned on the character after @key{PNT}. +@refill + +@cindex mode +@cindex keymap +@cindex local keymap +@cindex global keymap + +A @dfn{keymap} is a table that records the bindings between characters and +command functions. There is the @dfn{global keymap} common to all the +buffers. Each buffer has its @dfn{local keymap} that determines the +@dfn{mode} of the buffer. Local keymap overrides global keymap, so that if +a function is bound to some key in the local keymap then that function will +be executed when you type the key. If no function is bound to a key in the +local map, however, the function bound to the key in the global map becomes +in effect.@refill + +@node Loading VIP, Modes in VIP, Basic Concepts, Survey +@section Loading VIP + +The recommended way to load VIP automatically is to include the line: +@example +(load "vip") +@end example +@noindent +in your @file{.emacs} file. The @file{.emacs} file is placed in your home +directory and it will be executed every time you invoke Emacs. If you wish +to be in vi mode whenever Emacs starts up, you can include the following +line in your @file{.emacs} file instead of the above line: +@example +(setq term-setup-hook 'vip-mode) +@end example +@noindent +(@xref{Vi Mode}, for the explanation of vi mode.) + +Even if your @file{.emacs} file does not contain any of the above lines, +you can load VIP and enter vi mode by typing the following from within +Emacs. +@example +M-x vip-mode +@end example +@noindent + +@node Modes in VIP, Emacs Mode, Loading VIP, Survey +@section Modes in VIP + +@kindex 032 @kbd{C-z} (@code{vip-change-mode-to-vi}) +@kindex 0301 @kbd{C-x C-z} (@code{suspend-emacs}) + +Loading VIP has the effect of globally binding @kbd{C-z} (@kbd{Control-z}) +to the function @code{vip-change-mode-to-vi}. The default binding of @kbd{C-z} +in GNU Emacs is @code{suspend-emacs}, but, you can also call +@code{suspend-emacs} by typing @kbd{C-x C-z}. Other than this, all the +key bindings of Emacs remain the same after loading VIP.@refill + +@cindex vi mode + +Now, if you hit @kbd{C-z}, the function @code{vip-change-mode-to-vi} will be +called and you will be in @dfn{vi mode}. (Some major modes may locally bind +@kbd{C-z} to some special functions. In such cases, you can call +@code{vip-change-mode-to-vi} by @code{execute-extended-command} which is +invoked by @kbd{M-x}. Here @kbd{M-x} means @kbd{Meta-x}, and if your +terminal does not have a @key{META} key you can enter it by typing +@kbd{@key{ESC} x}. The same effect can also be achieve by typing +@kbd{M-x vip-mode}.)@refill + +@cindex mode line + +You can observe the change of mode by looking at the @dfn{mode line}. For +instance, if the mode line is:@refill +@example +-----Emacs: *scratch* (Lisp Interaction)----All------------ +@end example +@noindent +then it will change to: +@example +-----Vi: *scratch* (Lisp Interaction)----All------------ +@end example +@noindent +Thus the word @samp{Emacs} in the mode line will change to @samp{Vi}. + +@cindex insert mode +@cindex emacs mode + +You can go back to the original @dfn{emacs mode} by typing @kbd{C-z} in +vi mode. Thus @kbd{C-z} toggles between these two modes.@refill + +Note that modes in VIP exist orthogonally to modes in Emacs. This means +that you can be in vi mode and at the same time, say, shell mode. + +Vi mode corresponds to Vi's command mode. From vi mode you can enter +@dfn{insert mode} (which corresponds to Vi's insert mode) by usual Vi command +keys like @kbd{i}, @kbd{a}, @kbd{o} @dots{} etc. + +In insert mode, the mode line will look like this: +@example +-----Insert *scratch* (Lisp Interaction)----All------------ +@end example +@noindent +You can exit from insert mode by hitting @key{ESC} key as you do in Vi. + +That VIP has three modes may seem very complicated, but in fact it is not +so. VIP is implemented so that you can do most editing remaining only +in the two modes for Vi (that is vi mode and insert mode). + +@ifinfo +The figure below shows the transition of three modes in VIP. +@display + + + === C-z ==> == i,o ... ==> +emacs mode vi mode insert mode + <== X-z === <=== ESC ==== +@end display +@end ifinfo + +@menu +* Emacs Mode:: This is the mode you should know better. +* Vi Mode:: Vi commands are executed in this mode. +* Insert Mode:: You can enter text, and also can do editing if you + know enough Emacs commands. +@end menu + +@node Emacs Mode, Vi Mode, Modes in VIP, Modes in VIP +@subsection Emacs Mode + +@kindex 032 @kbd{C-z} (@code{vip-change-mode-to-vi}) + +You will be in this mode just after you loaded VIP. You can do all +normal Emacs editing in this mode. Note that the key @kbd{C-z} is globally +bound to @code{vip-change-mode-to-vi}. So, if you type @kbd{C-z} in this mode +then you will be in vi mode.@refill + +@node Vi Mode, Insert Mode, Emacs Mode, Modes in VIP +@subsection Vi Mode + +This mode corresponds to Vi's command mode. Most Vi commands work as they +do in Vi. You can go back to emacs mode by typing @kbd{C-z}. You can +enter insert mode, just as in Vi, by typing @kbd{i}, @kbd{a} etc. + +@node Insert Mode, Differences from Vi, Vi Mode, Modes in VIP +@subsection Insert Mode + +The key bindings in this mode is the same as in the emacs mode except for +the following 4 keys. So, you can move around in the buffer and change +its content while you are in insert mode. + +@table @kbd +@item @key{ESC} +@kindex 033 @kbd{ESC} (@code{vip-change-mode-to-vi}) (insert mode) +This key will take you back to vi mode. +@item C-h +@kindex 010 @kbd{C-h} (@code{vip-delete-backward-char}) (insert mode) +Delete previous character. +@item C-w +@kindex 027 @kbd{C-w} (@code{vip-delete-backward-word}) (insert mode) +Delete previous word. +@item C-z +@kindex 032 @kbd{C-z} (@code{vip-ESC}) (insert mode) +Typing this key has the same effect as typing @key{ESC} in emacs mode. +Thus typing @kbd{C-z x} in insert mode will have the same effect as typing +@kbd{ESC x} in emacs mode. +@end table + +@node Differences from Vi, Undoing, Insert Mode, Survey +@section Differences from Vi + +The major differences from Vi are explained below. + +@menu +* Undoing:: You can undo more in VIP. +* Changing:: Commands for changing the text. +* Searching:: Search commands. +* z Command:: You can now use zH, zM and zL as well as z- etc. +* Counts:: Some Vi commands which do not accept a count now + accept one. +* Marking:: You can now mark the current point, beginning of + the buffer etc. +* Region Commands:: You can now give a region as an argument for delete + commands etc. +* New Commands:: Some new commands not available in Vi are added. +* New Bindings:: Bindings of some keys are changed for the + convenience of editing under Emacs. +* Window Commands:: Commands for moving among windows etc. +* Buffer Commands:: Commands for selecting buffers etc. +* File Commands:: Commands for visiting files etc. +* Misc Commands:: Other useful commands. +@end menu + +@node Undoing, Changing, Differences from Vi, Differences from Vi +@subsection Undoing + +@kindex 165 @kbd{u} (@code{vip-undo}) +@kindex 056 @kbd{.} (@code{vip-repeat}) + +You can repeat undoing by the @kbd{.} key. So, @kbd{u} will undo +a single change, while @kbd{u .@: .@: .@:}, for instance, will undo 4 previous +changes. Undo is undoable as in Vi. So the content of the buffer will +be the same before and after @kbd{u u}.@refill + +@node Changing, Searching, Undoing, Differences from Vi +@subsection Changing + +Some commands which change a small number of characters are executed +slightly differently. Thus, if point is at the beginning of a word +@samp{foo} and you wished to change it to @samp{bar} by typing @w{@kbd{c w}}, +then VIP will prompt you for a new word in the minibuffer by the prompt +@samp{foo => }. You can then enter @samp{bar} followed by @key{RET} or +@key{ESC} to complete the command. Before you enter @key{RET} or +@key{ESC} you can abort the command by typing @kbd{C-g}. In general, +@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) +you can abort a partially formed command by typing @kbd{C-g}.@refill + +@node Searching, z Command, Changing, Differences from Vi +@subsection Searching + +@kindex 057 @kbd{/} (@code{vip-search-forward}) +@kindex 077 @kbd{?} (@code{vip-search-backward}) + +As in Vi, searching is done by @kbd{/} and @kbd{?}. The string will be +searched literally by default. To invoke a regular expression search, +first execute the search command @kbd{/} (or @kbd{?}) with empty search +string. (I.e, type @kbd{/} followed by @key{RET}.) +A search for empty string will toggle the search mode between vanilla +search and regular expression search. You cannot give an offset to the +search string. (It is a limitation.) By default, search will wrap around +the buffer as in Vi. You can change this by rebinding the variable +@code{vip-search-wrap-around}. @xref{Customization}, for how to do this.@refill + +@node z Command, Counts, Searching, Differences from Vi +@subsection z Command + +@kindex 1723 @kbd{z H} (@code{vip-line-to-top}) +@kindex 1721 @kbd{z RET} (@code{vip-line-to-top}) +@kindex 1723 @kbd{z M} (@code{vip-line-to-middle}) +@kindex 1722 @kbd{z .} (@code{vip-line-to-middle}) +@kindex 1723 @kbd{z L} (@code{vip-line-to-bottom}) +@kindex 1722 @kbd{z -} (@code{vip-line-to-bottom}) + +For those of you who cannot remember which of @kbd{z} followed by @key{RET}, +@kbd{.}@: and @kbd{-} do what. You can also use @kbd{z} followed by @kbd{H}, +@kbd{M} and @kbd{L} to place the current line in the Home (Middle, and +Last) line of the window.@refill + +@node Counts, Marking, z Command, Differences from Vi +@subsection Counts + +Some Vi commands which do not accept a count now accept one + +@table @kbd +@item p +@itemx P +@kindex 160 @kbd{p} (@code{vip-put-back}) +@kindex 120 @kbd{P} (@code{vip-Put-back}) +Given counts, text will be yanked (in Vi's sense) that many times. Thus +@kbd{3 p} is the same as @kbd{p p p}. +@item o +@itemx O +@kindex 157 @kbd{o} (@code{vip-open-line}) +@kindex 117 @kbd{O} (@code{vip-Open-line}) +Given counts, that many copies of text will be inserted. Thus +@kbd{o a b c @key{ESC}} will insert 3 lines of @samp{abc} below the current +line. +@item / +@itemx ? +@kindex 057 @kbd{/} (@code{vip-search-forward}) +@kindex 077 @kbd{?} (@code{vip-search-backward}) +Given a count @var{n}, @var{n}-th occurrence will be searched. +@end table + +@node Marking, Region Commands, Counts, Differences from Vi +@subsection Marking + +Typing an @kbd{m} followed by a lower-case character @var{ch} marks the +point to the register named @var{ch} as in Vi. In addition to these, we +have following key bindings for marking. + +@kindex 155 @kbd{m} (@code{vip-mark-point}) + +@table @kbd +@item m < +Set mark at the beginning of buffer. +@item m > +Set mark at the end of buffer. +@item m . +Set mark at point (and push old mark on mark ring). +@item m , +Jump to mark (and pop mark off the mark ring). +@end table + +@node Region Commands, New Commands, Marking, Differences from Vi +@subsection Region Commands + +@cindex region + +Vi operators like @kbd{d}, @kbd{c} etc. are usually used in combination +with motion commands. It is now possible to use current region as the +argument to these operators. (A @dfn{region} is a part of buffer +delimited by point and mark.) The key @kbd{r} is used for this purpose. +Thus @kbd{d r} will delete the current region. If @kbd{R} is used instead +of @kbd{r} the region will first be enlarged so that it will become the +smallest region containing the original region and consisting of whole +lines. Thus @kbd{m .@: d R} will have the same effect as @kbd{d d}.@refill + +@node New Commands, New Bindings, Region Commands, Differences from Vi +@subsection Some New Commands + +Note that the keys below (except for @kbd{R}) are not used in Vi. + +@table @kbd +@item C-a +@kindex 001 @kbd{C-a} (@code{vip-beginning-of-line}) +Move point to the beginning of line. +@item C-n +@kindex 016 @kbd{C-n} (@code{vip-next-window}) +If you have two or more windows in the screen, this key will move point to +the next window. +@item C-o +@kindex 017 @kbd{C-o} (@code{vip-open-line-at-point}) +Insert a newline and leave point before it, and then enter insert mode. +@item C-r +@kindex 022 @kbd{C-r} (@code{isearch-backward}) +Backward incremental search. +@item C-s +@kindex 023 @kbd{C-s} (@code{isearch-forward}) +Forward incremental search. +@item C-c +@itemx C-x +@itemx @key{ESC} +@kindex 003 @kbd{C-c} (@code{vip-ctl-c}) +@kindex 0300 @kbd{C-x} (@code{vip-ctl-x}) +@kindex 033 @kbd{ESC} (@code{vip-ESC}) +These keys will exit from vi mode and return to emacs mode temporarily. If +you hit one of these keys, Emacs will be in emacs mode and will believe +that you hit that key in emacs mode. For example, if you hit @kbd{C-x} +followed by @kbd{2}, then the current window will be split into 2 and you +will be in vi mode again. +@item \ +@kindex 134 @kbd{\} (@code{vip-escape-to-emacs}) +Escape to emacs mode. Hitting @kbd{\} will take you to emacs mode, and you +can execute a single Emacs command. After executing the Emacs command you +will be in vi mode again. You can give a count before typing @kbd{\}. +Thus @kbd{5 \ *}, as well as @kbd{\ C-u 5 *}, will insert @samp{*****} +before point. Similarly @kbd{1 0 \ C-p} will move the point 10 lines above +the current line.@refill +@item K +@kindex 113 @kbd{K} (@code{vip-kill-buffer}) +Kill current buffer if it is not modified. Useful when you selected a +buffer which you did not want. +@item Q +@itemx R +@kindex 121 @kbd{Q} (@code{vip-query-replace}) +@kindex 122 @kbd{R} (@code{vip-replace-string}) +@kbd{Q} is for query replace and @kbd{R} is for replace. By default, +string to be replaced are treated literally. If you wish to do a regular +expression replace, first do replace with empty string as the string to be +replaced. In this way, you can toggle between vanilla and regular +expression replacement. +@item v +@itemx V +@kindex 166 @kbd{v} (@code{vip-find-file}) +@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) +These keys are used to Visit files. @kbd{v} will switch to a buffer +visiting file whose name can be entered in the minibuffer. @kbd{V} is +similar, but will use window different from the current window. +@item # +@kindex 0430 @kbd{#} (@code{vip-command-argument}) +If followed by a certain character @var{ch}, it becomes an operator whose +argument is the region determined by the motion command that follows. +Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q} and +@kbd{s}.@refill +@item # c +@kindex 0432 @kbd{# c} (@code{downcase-region}) +Change upper-case characters in the region to lower case +(@code{downcase-region}). +@item # C +@kindex 0431 @kbd{# C} (@code{upcase-region}) +Change lower-case characters in the region to upper case. For instance, +@kbd{# C 3 w} will capitalize 3 words from the current point +(@code{upcase-region}). +@item # g +@kindex 0432 @kbd{# g} (@code{vip-global-execute}) +Execute last keyboard macro for each line in the region +(@code{vip-global-execute}).@refill +@item # q +@kindex 0432 @kbd{# q} (@code{vip-quote-region}) +Insert specified string at the beginning of each line in the region +(@code{vip-quote-region}). +@item # s +@kindex 0432 @kbd{# s} (@code{spell-region}) +Check spelling of words in the region (@code{spell-region}). +@item * +@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) +Call last keyboard macro. +@end table + +@node New Bindings, Window Commands, New Commands, Differences from Vi +@subsection New Key Bindings + +In VIP the meanings of some keys are entirely different from Vi. These key +bindings are done deliberately in the hope that editing under Emacs will +become easier. It is however possible to rebind these keys to functions +which behave similarly as in Vi. @xref{Customizing Key Bindings}, for +details. + +@table @kbd +@item C-g +@itemx g +@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) +@kindex 147 @kbd{g} (@code{vip-info-on-file}) +In Vi, @kbd{C-g} is used to get information about the file associated to +the current buffer. Here, @kbd{g} will do that, and @kbd{C-g} is +used to abort a command (this is for compatibility with emacs mode.) +@item SPC +@itemx @key{RET} +@kindex 040 @kbd{SPC} (@code{vip-scroll}) +@kindex 015 @kbd{RET} (@code{vip-scroll-back}) +Now these keys will scroll up and down the text of current window. +Convenient for viewing the text. +@item s +@itemx S +@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) +@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) +They are used to switch to a specified buffer. Useful for switching to +already existing buffer since buffer name completion is provided. Also +a default buffer will be given as part of the prompt, to which you can +switch by just typing @key{RET} key. @kbd{s} is used to select buffer +in the current window, while @kbd{S} selects buffer in another window. +@item C +@itemx X +@kindex 103 @kbd{C} (@code{vip-ctl-c-equivalent}) +@kindex 1300 @kbd{X} (@code{vip-ctl-x-equivalent}) +These keys will exit from vi mode and return to emacs mode temporarily. +If you type @kbd{C} (@kbd{X}), Emacs will be in emacs mode and will believe +that you have typed @kbd{C-c} (@kbd{C-x}, resp.) in emacs mode. Moreover, +if the following character you type is an upper-case letter, then Emacs +will believe that you have typed the corresponding control character. +You will be in vi mode again after the command is executed. For example, +typing @kbd{X S} in vi mode is the same as typing @kbd{C-x C-s} in emacs +mode. You get the same effect by typing @kbd{C-x C-s} in vi mode, but +the idea here is that you can execute useful Emacs commands without typing +control characters. For example, if you hit @kbd{X} (or @kbd{C-x}) followed +by @kbd{2}, then the current window will be split into 2 and you will be in +vi mode again.@refill +@end table + +In addition to these, @code{ctl-x-map} is slightly modified: + +@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) + +@table @kbd +@item X 3 +@itemx C-x 3 +This is equivalent to @kbd{C-x 1 C-x 2} (1 + 2 = 3). +@end table + +@node Window Commands, Buffer Commands, New Bindings, Differences from Vi +@subsection Window Commands + +In this and following subsections, we give a summary of key bindings for +basic functions related to windows, buffers and files. + +@table @kbd +@item C-n +@kindex 016 @kbd{C-n} (@code{vip-next-window}) +Switch to next window. +@item X 1 +@itemx C-x 1 +@kindex 1301 @kbd{X 1} (@code{delete-other-windows}) +Delete other windows. +@item X 2 +@itemx C-x 2 +@kindex 1301 @kbd{X 2} (@code{split-window-vertically}) +Split current window into two windows. +@item X 3 +@itemx C-x 3 +@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) +Show current buffer in two windows. +@end table + +@node Buffer Commands, File Commands, Window Commands, Differences from Vi +@subsection Buffer Commands + +@table @kbd +@item s +@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) +Switch to the specified buffer in the current window +(@code{vip-switch-to-buffer}). +@item S +@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) +Switch to the specified buffer in another window +(@code{vip-switch-to-buffer-other-window}). +@item K +@kindex 113 @kbd{K} (@code{vip-kill-buffer}) +Kill the current buffer if it is not modified. +@item X S +@itemx C-x C-s +@kindex 1302 @kbd{X S} (@code{save-buffer}) +Save the current buffer in the file associated to the buffer. +@end table + +@node File Commands, Misc Commands, Buffer Commands, Differences from Vi +@subsection File Commands + +@table @kbd +@item v +@kindex 166 @kbd{v} (@code{vip-find-file}) +Visit specified file in the current window. +@item V +@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) +Visit specified file in another window. +@item X W +@itemx C-x C-w +@kindex 1302 @kbd{X W} (@code{write-file}) +Write current buffer into the specified file. +@item X I +@itemx C-x C-i +@kindex 1302 @kbd{X I} (@code{insert-file}) + +Insert specified file at point. +@end table + +@node Misc Commands, Vi Commands, File Commands, Differences from Vi +@subsection Miscellaneous Commands + +@table @kbd +@item X ( +@itemx C-x ( +@kindex 1301 @kbd{X (} (@code{start-kbd-macro}) +Start remembering keyboard macro. +@item X ) +@itemx C-x ) +@kindex 1301 @kbd{X )} (@code{end-kbd-macro}) +Finish remembering keyboard macro. +@item * +@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) +Call last remembered keyboard macro. +@item X Z +@itemx C-x C-z +@kindex 1302 @kbd{X Z} (@code{suspend-emacs}) +Suspend Emacs. +@item Z Z +Exit Emacs. +@itemx Q +Query replace. +@itemx R +Replace. +@end table + +@node Vi Commands, Numeric Arguments, Misc Commands, Top +@chapter Vi Commands + +This chapter describes Vi commands other than Ex commands implemented in +VIP. Except for the last section which discusses insert mode, all the +commands described in this chapter are to be used in vi mode. + +@menu +* Numeric Arguments:: Many commands accept numeric arguments +* Important Keys:: Some very important keys. +* Buffers and Windows:: Commands for handling buffers and windows. +* Files:: Commands for handling files. +* Viewing the Buffer:: How you can view the current buffer. +* Mark Commands:: Marking positions in a buffer. +* Motion Commands:: Commands for moving point. +* Searching and Replacing:: Commands for searching and replacing. +* Modifying Commands:: Commands for modifying the buffer. +* Other Vi Commands:: Miscellaneous Commands. +* Commands in Insert Mode:: Commands for entering insert mode. +@end menu + +@node Numeric Arguments, Important Keys, Vi Commands, Vi Commands +@section Numeric Arguments + +@cindex numeric arguments +@cindex count +@kindex 061 @kbd{1} (numeric argument) +@kindex 062 @kbd{2} (numeric argument) +@kindex 063 @kbd{3} (numeric argument) +@kindex 064 @kbd{4} (numeric argument) +@kindex 065 @kbd{5} (numeric argument) +@kindex 066 @kbd{6} (numeric argument) +@kindex 067 @kbd{7} (numeric argument) +@kindex 068 @kbd{8} (numeric argument) +@kindex 069 @kbd{9} (numeric argument) + +Most Vi commands accept a @dfn{numeric argument} which can be supplied as +a prefix to the commands. A numeric argument is also called a @dfn{count}. +In many cases, if a count is given, the command is executed that many times. +For instance, @kbd{5 d d} deletes 5 lines while simple @kbd{d d} deletes a +line. In this manual the metavariable @var{n} will denote a count.@refill + +@node Important Keys, Buffers and Windows, Numeric Arguments, Vi Commands +@section Important Keys + +The keys @kbd{C-g} and @kbd{C-l} are unique in that their associated +functions are the same in any of emacs, vi and insert mode. + +@table @kbd +@item C-g +@kindex 007 @kbd{C-g} (@code{vip-keyboard-quit}) +Quit. Cancel running or partially typed command (@code{keyboard-quit}). +@item C-l +@kindex 014 @kbd{C-l} (@code{recenter}) +Clear the screen and reprint everything (@code{recenter}). +@end table + +In Emacs many commands are bound to the key strokes that start with +@kbd{C-x}, @kbd{C-c} and @key{ESC}. These commands can be +accessed from vi mode as easily as from emacs mode.@refill + +@table @kbd +@item C-x +@itemx C-c +@itemx @key{ESC} +@kindex 003 @kbd{C-c} (@code{vip-ctl-c}) +@kindex 0300 @kbd{C-x} (@code{vip-ctl-x}) +@kindex 033 @kbd{ESC} (@code{vip-ESC}) +Typing one of these keys have the same effect as typing it in emacs mode. +Appropriate command will be executed according as the keys you type after +it. You will be in vi mode again after the execution of the command. +For instance, if you type @kbd{@key{ESC} <} (in vi mode) then the cursor will +move to the beginning of the buffer and you will still be in vi mode. +@item C +@itemx X +@kindex 103 @kbd{C} (@code{vip-ctl-c-equivalent}) +@kindex 1300 @kbd{X} (@code{vip-ctl-x-equivalent}) +Typing one of these keys have the effect of typing the corresponding +control character in emacs mode. Moreover, if you type an upper-case +character following it, that character will also be translated to the +corresponding control character. Thus typing @kbd{X W} in vi mode is the +same as typing @kbd{C-x C-w} in emacs mode. You will be in vi mode again +after the execution of a command. +@item \ +@kindex 134 @kbd{\} (@code{vip-escape-to-emacs}) +Escape to emacs mode. Hitting the @kbd{\} key will take you to emacs mode, +and you can execute a single Emacs command. After executing the +Emacs command you will be in vi mode again. You can give a count before +typing @kbd{\}. Thus @kbd{5 \ +}, as well as @kbd{\ C-u 5 +}, will insert +@samp{+++++} before point.@refill +@end table + +@node Buffers and Windows, Files, Important Keys, Vi Commands +@section Buffers and Windows + +@cindex buffer +@cindex selected buffer +@cindex current buffer + +In Emacs the text you edit is stored in a @dfn{buffer}. +See GNU Emacs Manual, for details. There is always one @dfn{selected} +buffer which is called the @dfn{current buffer}.@refill + +@cindex window +@cindex modified (buffer) + +You can see the contents of buffers through @dfn{windows} created by Emacs. +When you have multiple windows on the screen only one of them is selected. +Each buffer has a unique name, and each window has a mode line which shows +the name of the buffer associated with the window and other information +about the status of the buffer. You can change the format of the mode +line, but normally if you see @samp{**} at the beginning of a mode line it +means that the buffer is @dfn{modified}. If you write out the content of +the buffer to a file, then the buffer will become not modified. Also if +you see @samp{%%} at the beginning of the mode line, it means that the file +associated with the buffer is write protected. + +We have the following commands related to windows and buffers. + +@table @kbd +@item C-n +@kindex 016 @kbd{C-n} (@code{vip-next-window}) +Move cursor to the next-window (@code{vip-next-window}). +@item X 1 +@kindex 1301 @kbd{X 1} (@code{delete-other-windows}) +Delete other windows and make the selected window fill the screen +@*(@code{delete-other-windows}). +@item X 2 +@kindex 1301 @kbd{X 2} (@code{split-window-vertically}) +Split current window into two windows (@code{split-window-vertically}). +@item X 3 +@kindex 1301 @kbd{X 3} (@code{vip-buffer-in-two-windows}) +Show current buffer in two windows. +@item s @var{buffer} @key{RET} +@kindex 163 @kbd{s} (@code{vip-switch-to-buffer}) +Select or create a buffer named @var{buffer} (@code{vip-switch-to-buffer}). +@item S @var{buffer} @key{RET} +@kindex 123 @kbd{S} (@code{vip-switch-to-buffer-other-window}) +Similar but select a buffer named @var{buffer} in another window +@*(@code{vip-switch-to-buffer-other-window}). +@item K +@kindex 113 @kbd{K} (@code{vip-kill-buffer}) +Kill the current buffer if it is not modified or if it is not associated +with a file @*(@code{vip-kill-buffer}). +@item X B +@kindex 1302 @kbd{X B} (@code{list-buffers}) +List the existing buffers (@code{list-buffers}). +@end table + +@cindex buffer name completion + +As @dfn{buffer name completion} is provided, you have only to type in +initial substring of the buffer name which is sufficient to identify it +among names of existing buffers. After that, if you hit @key{TAB} the rest +of the buffer name will be supplied by the system, and you can confirm it +by @key{RET}. The default buffer name to switch to will also be prompted, +and you can select it by giving a simple @key{RET}. See GNU Emacs Manual +for details of completion. + +@node Files, Viewing the Buffer, Buffers and Windows, Vi Commands +@section Files + +We have the following commands related to files. They are used to visit, +save and insert files. + +@table @kbd +@item v @var{file} @key{RET} +@kindex 166 @kbd{v} (@code{vip-find-file}) +Visit specified file in the current window (@code{vip-find-file}). +@item V @var{file} @key{RET} +@kindex 126 @kbd{V} (@code{vip-find-file-other-window}) +Visit specified file in another window (@code{vip-find-file-other-window}). +@item X S +@kindex 1302 @kbd{X S} (@code{save-buffer}) +Save current buffer to the file associated with the buffer. If no file is +associated with the buffer, the name of the file to write out the content +of the buffer will be asked in the minibuffer. +@item X W @var{file} @key{RET} +@kindex 1302 @kbd{X W} (@code{write-file}) +Write current buffer into a specified file. +@item X I @var{file} @key{RET} +@kindex 1302 @kbd{X I} (@code{insert-file}) +Insert a specified file at point. +@item g +@kindex 147 @kbd{g} (@code{vip-info-on-file}) +Give information on the file associated with the current buffer. Tell you +the name of the file associated with the buffer, the line number of the +current point and total line numbers in the buffer. If no file is +associated with the buffer, this fact will be indicated by the null file +name @samp{""}. +@end table + +@cindex visiting (a file) +@cindex default directory + +In Emacs, you can edit a file by @dfn{visiting} it. If you wish to visit a +file in the current window, you can just type @kbd{v}. Emacs maintains the +@dfn{default directory} which is specific to each buffer. Suppose, for +instance, that the default directory of the current buffer is +@file{/usr/masahiko/lisp/}. Then you will get the following prompt in the +minibuffer.@refill +@example +visit file: /usr/masahiko/lisp/ +@end example +@noindent +@cindex file name completion +If you wish to visit, say, @file{vip.el} in this directory, then you can +just type @samp{vip.el} followed by @key{RET}. If the file @file{vip.el} +already exists in the directory, Emacs will visit that file, and if not, +the file will be created. Emacs will use the file name (@file{vip.el}, in +this case) as the name of the buffer visiting the file. In order to make +the buffer name unique, Emacs may append @samp{<2>}, @samp{<3>} etc., to +the buffer name. As the @dfn{file name completion} is provided here, you +can sometime save typing. For instance, suppose there is only one file in the +default directory whose name starts with @samp{v}, that is @samp{vip.el}. +Then if you just type @kbd{v @key{TAB}} then it will be completed to +@samp{vip.el}. Thus, in this case, you just have to type @kbd{v v @key{TAB} +@key{RET}} to visit @file{/usr/masahiko/lisp/vip.el}. Continuing the +example, let us now suppose that you wished to visit the file +@file{/usr/masahiko/man/vip.texinfo}. Then to the same prompt which you get +after you typed @kbd{v}, you can enter @samp{/usr/masahiko/man/vip.texinfo} or +@samp{../man/vip.texinfo} followed by @key{RET}. + +Use @kbd{V} instead of @kbd{v}, if you wish to visit a file in another +window. + +You can verify which file you are editing by typing @kbd{g}. (You can also +type @kbd{X B} to get nformation on other buffers too.) If you type +@kbd{g} you will get an information like below in the echo area:@refill +@example +"/usr/masahiko/man/vip.texinfo" line 921 of 1949 +@end example + +After you edited the buffer (@samp{vip.texinfo}, in our example) for a while, +you may wish to save it in a file. If you wish to save it in the file +associated with the buffer (@file{/usr/masahiko/man/vip.texinfo}, in this +case), you can just say @kbd{X S}. If you wish to save it in another file, +you can type @kbd{X W}. You will then get a similar prompt as you get for +@kbd{v}, to which you can enter the file name.@refill + +@node Viewing the Buffer, Mark Commands, Files, Vi Commands +@section Viewing the Buffer + +In this and next section we discuss commands for moving around in the +buffer. These command do not change the content of the buffer. The +following commands are useful for viewing the content of the current +buffer. + +@table @kbd +@item @key{SPC} +@itemx C-f +@kindex 040 @kbd{SPC} (@code{vip-scroll}) +@kindex 006 @kbd{C-f} (@code{vip-scroll-back}) +Scroll text of current window upward almost full screen. You can go +@i{forward} in the buffer by this command (@code{vip-scroll}). +@item @key{RET} +@itemx C-b +@kindex 015 @kbd{RET} (@code{vip-scroll-back}) +@kindex 002 @kbd{C-b} (@code{vip-scroll-back}) +Scroll text of current window downward almost full screen. You can go +@i{backward} in the buffer by this command (@code{vip-scroll-back}). +@itemx C-d +@kindex 004 @kbd{C-d} (@code{vip-scroll-up}) +Scroll text of current window upward half screen. You can go +@i{down} in the buffer by this command (@code{vip-scroll-down}). +@itemx C-u +@kindex 025 @kbd{C-u} (@code{vip-scroll-down}) +Scroll text of current window downward half screen. You can go +@i{up} in the buffer by this command (@code{vip-scroll-up}). +@item C-y +@kindex 031 @kbd{C-y} (@code{vip-scroll-down-one}) +Scroll text of current window upward by one line (@code{vip-scroll-down-one}). +@item C-e +@kindex 005 @kbd{C-e} (@code{vip-scroll-up-one}) +Scroll text of current window downward by one line (@code{vip-scroll-up-one}). +@end table +@noindent +You can repeat these commands by giving a count. Thus, @kbd{2 @key{SPC}} +has the same effect as @kbd{@key{SPC} @key{SPC}}. + +The following commands reposition point in the window. + +@table @kbd +@item z H +@itemx z @key{RET} +@kindex 1723 @kbd{z H} (@code{vip-line-to-top}) +@kindex 1721 @kbd{z RET} (@code{vip-line-to-top}) +Put point on the top (@i{home}) line in the window. So the current line +becomes the top line in the window. Given a count @var{n}, point will be +placed in the @var{n}-th line from top (@code{vip-line-to-top}). +@item z M +@itemx z . +@kindex 1723 @kbd{z M} (@code{vip-line-to-middle}) +@kindex 1722 @kbd{z .} (@code{vip-line-to-middle}) +Put point on the @i{middle} line in the window. Given a count @var{n}, +point will be placed in the @var{n}-th line from the middle line +(@code{vip-line-to-middle}). +@item z L +@itemx z - +@kindex 1723 @kbd{z L} (@code{vip-line-to-bottom}) +@kindex 1722 @kbd{z -} (@code{vip-line-to-bottom}) +Put point on the @i{bottom} line in the window. Given a count @var{n}, +point will be placed in the @var{n}-th line from bottom +(@code{vip-line-to-bottom}). +@item C-l +Center point in window and redisplay screen (@code{recenter}). +@end table + +@node Mark Commands, Motion Commands, Viewing the Buffer, Vi Commands +@section Mark Commands + +The following commands are used to mark positions in the buffer. + +@table @kbd +@item m @var{ch} +@kindex 155 @kbd{m} (@code{vip-mark-point}) +Store current point in the register @var{ch}. @var{ch} must be a +lower-case ASCII letter. +@item m < +Set mark at the beginning of current buffer. +@item m > +Set mark at the end of current buffer. +@item m . +Set mark at point. +@item m , +Jump to mark (and pop mark off the mark ring). +@end table + +@cindex mark ring + +Emacs uses the @dfn{mark ring} to store marked positions. The commands +@kbd{m <}, @kbd{m >} and @kbd{m .}@: not only set mark but also add it as the +latest element of the mark ring (replacing the oldest one). By repeating +the command `@kbd{m ,}' you can visit older and older marked positions. You +will eventually be in a loop as the mark ring is a ring. + +@node Motion Commands, Searching and Replacing, Mark Commands, Vi Commands +@section Motion Commands + +Commands for moving around in the current buffer are collected here. These +commands are used as an `argument' for the delete, change and yank commands +to be described in the next section. + +@table @kbd +@item h +@kindex 150 @kbd{h} (@code{vip-backward-char}) +Move point backward by one character. Signal error if point is at the +beginning of buffer, but (unlike Vi) do not complain otherwise +(@code{vip-backward-char}). +@item l +@kindex 154 @kbd{l} (@code{vip-forward-char}) +Move point backward by one character. Signal error if point is at the +end of buffer, but (unlike Vi) do not complain otherwise +(@code{vip-forward-char}). +@item j +@kindex 152 @kbd{j} (@code{vip-next-line}) +Move point to the next line keeping the current column. If point is on the +last line of the buffer, a new line will be created and point will move to +that line (@code{vip-next-line}). +@item k +@kindex 153 @kbd{k} (@code{vip-previous-line}) +Move point to the previous line keeping the current column +(@code{vip-next-line}). +@item + +@kindex 053 @kbd{+} (@code{vip-next-line-at-bol}) +Move point to the next line at the first non-white character. If point is +on the last line of the buffer, a new line will be created and point will +move to the beginning of that line (@code{vip-next-line-at-bol}). +@item - +@kindex 055 @kbd{-} (@code{vip-previous-line-at-bol}) +Move point to the previous line at the first non-white character +(@code{vip-previous-line-at-bol}). +@end table +@noindent +If a count is given to these commands, the commands will be repeated that +many times. + +@table @kbd +@item 0 +@kindex 060 @kbd{0} (@code{vip-beginning-of-line}) +Move point to the beginning of line (@code{vip-beginning-of-line}). +@item ^ +@kindex 136 @kbd{^} (@code{vip-bol-and-skip-white}) +Move point to the first non-white character on the line +(@code{vip-bol-and-skip-white}). +@item $ +@kindex 044 @kbd{$} (@code{vip-goto-eol}) +Move point to the end of line (@code{vip-goto-eol}). +@item @var{n} | +@kindex 174 @kbd{|} (@code{vip-goto-col}) +Move point to the @var{n}-th column on the line (@code{vip-goto-col}). +@end table +@noindent +Except for the @kbd{|} command, these commands neglect a count. + +@cindex word + +@table @kbd +@item w +@kindex 167 @kbd{w} (@code{vip-forward-word}) +Move point forward to the beginning of the next word +(@code{vip-forward-word}). +@item W +@kindex 127 @kbd{W} (@code{vip-forward-Word}) +Move point forward to the beginning of the next word, where a @dfn{word} is +considered as a sequence of non-white characters (@code{vip-forward-Word}). +@item b +@kindex 142 @kbd{b} (@code{vip-backward-word}) +Move point backward to the beginning of a word (@code{vip-backward-word}). +@item B +@kindex 102 @kbd{B} (@code{vip-backward-Word}) +Move point backward to the beginning of a word, where a @i{word} is +considered as a sequence of non-white characters (@code{vip-forward-Word}). +@item e +@kindex 145 @kbd{e} (@code{vip-end-of-word}) +Move point forward to the end of a word (@code{vip-end-of-word}). +@item E +@kindex 105 @kbd{E} (@code{vip-end-of-Word}) +Move point forward to the end of a word, where a @i{word} is +considered as a sequence of non-white characters (@code{vip-end-of-Word}). +@end table +@noindent +@cindex syntax table +Here the meaning of the word `word' for the @kbd{w}, @kbd{b} and @kbd{e} +commands is determined by the @dfn{syntax table} effective in the current +buffer. Each major mode has its syntax mode, and therefore the meaning of +a word also changes as the major mode changes. See GNU Emacs Manual for +details of syntax table. + +@table @kbd +@item H +@kindex 110 @kbd{H} (@code{vip-window-top}) +Move point to the beginning of the @i{home} (top) line of the window. +Given a count @var{n}, go to the @var{n}-th line from top +(@code{vip-window-top}). +@item M +@kindex 115 @kbd{M} (@code{vip-window-middle}) +Move point to the beginning of the @i{middle} line of the window. Given +a count @var{n}, go to the @var{n}-th line from the middle line +(@code{vip-window-middle}). +@item L +@kindex 114 @kbd{L} (@code{vip-window-bottom}) +Move point to the beginning of the @i{lowest} (bottom) line of the +window. Given count, go to the @var{n}-th line from bottom +(@code{vip-window-bottom}). +@end table +@noindent +These commands can be used to go to the desired line visible on the screen. + +@table @kbd +@item ( +@kindex 050 @kbd{(} (@code{vip-backward-sentence}) +Move point backward to the beginning of the sentence +(@code{vip-backward-sentence}). +@item ) +@kindex 051 @kbd{)} (@code{vip-forward-sentence}) +Move point forward to the end of the sentence +(@code{vip-forward-sentence}). +@item @{ +@kindex 173 @kbd{@{} (@code{vip-backward-paragraph}) +Move point backward to the beginning of the paragraph +(@code{vip-backward-paragraph}). +@item @} +@kindex 175 @kbd{@}} (@code{vip-forward-paragraph}) +Move point forward to the end of the paragraph +(@code{vip-forward-paragraph}). +@end table +@noindent +A count repeats the effect for these commands. + +@table @kbd +@item G +@kindex 107 @kbd{G} (@code{vip-goto-line}) +Given a count @var{n}, move point to the @var{n}-th line in the buffer on +the first non-white character. Without a count, go to the end of the buffer +(@code{vip-goto-line}). +@item ` ` +@kindex 140 @kbd{`} (@code{vip-goto-mark}) +Exchange point and mark (@code{vip-goto-mark}). +@item ` @var{ch} +Move point to the position stored in the register @var{ch}. @var{ch} must +be a lower-case letter. +@item ' ' +@kindex 047 @kbd{'} (@code{vip-goto-mark-and-skip-white}) +Exchange point and mark, and then move point to the first non-white +character on the line (@code{vip-goto-mark-and-skip-white}). +@item ' @var{ch} +Move point to the position stored in the register @var{ch} and skip to the +first non-white character on the line. @var{ch} must be a lower-case letter. +@item % +@kindex 045 @kbd{%} (@code{vip-paren-match}) +Move point to the matching parenthesis if point is looking at @kbd{(}, +@kbd{)}, @kbd{@{}, @kbd{@}}, @kbd{[} or @kbd{]} +@*(@code{vip-paren-match}). +@end table +@noindent +The command @kbd{G} mark point before move, so that you can return to the +original point by @kbd{` `}. The original point will also be stored in +the mark ring. + +The following commands are useful for moving points on the line. A count +will repeat the effect. + +@table @kbd +@item f @var{ch} +@kindex 146 @kbd{f} (@code{vip-find-char-forward}) +Move point forward to the character @var{ch} on the line. Signal error if +@var{ch} could not be found (@code{vip-find-char-forward}). +@item F @var{ch} +@kindex 106 @kbd{F} (@code{vip-find-char-backward}) +Move point backward to the character @var{ch} on the line. Signal error if +@var{ch} could not be found (@code{vip-find-char-backward}). +@item t @var{ch} +@kindex 164 @kbd{t} (@code{vip-goto-char-forward}) +Move point forward upto the character @var{ch} on the line. Signal error if +@var{ch} could not be found (@code{vip-goto-char-forward}). +@item T @var{ch} +@kindex 124 @kbd{T} (@code{vip-goto-char-backward}) +Move point backward upto the character @var{ch} on the line. Signal error if +@var{ch} could not be found (@code{vip-goto-char-backward}). +@item ; +@kindex 073 @kbd{;} (@code{vip-repeat-find}) +Repeat previous @kbd{f}, @kbd{t}, @kbd{F} or @kbd{T} command +(@code{vip-repeat-find}). +@item , +@kindex 054 @kbd{,} (@code{vip-repeat-find-opposite}) +Repeat previous @kbd{f}, @kbd{t}, @kbd{F} or @kbd{T} command, in the +opposite direction (@code{vip-repeat-find-opposite}). +@end table + +@node Searching and Replacing, Modifying Commands, Motion Commands, Vi Commands +@section Searching and Replacing + +Following commands are available for searching and replacing. + +@cindex regular expression (search) + +@table @kbd +@item / @var{string} @key{RET} +@kindex 057 @kbd{/} (@code{vip-search-forward}) +Search the first occurrence of the string @var{string} forward starting +from point. Given a count @var{n}, the @var{n}-th occurrence of +@var{string} will be searched. If the variable @code{vip-re-search} has value +@code{t} then @dfn{regular expression} search is done and the string +matching the regular expression @var{string} is found. If you give an +empty string as @var{string} then the search mode will change from vanilla +search to regular expression search and vice versa +(@code{vip-search-forward}). +@item ? @var{string} @key{RET} +@kindex 077 @kbd{?} (@code{vip-search-backward}) +Same as @kbd{/}, except that search is done backward +(@code{vip-search-backward}). +@item n +@kindex 156 @kbd{n} (@code{vip-search-next}) +Search the previous search pattern in the same direction as before +(@code{vip-search-next}). +@item N +@kindex 116 @kbd{N} (@code{vip-search-Next}) +Search the previous search pattern in the opposite direction +(@code{vip-search-Next}). +@item C-s +@kindex 023 @kbd{C-s} (@code{isearch-forward}) +Search forward incrementally. See GNU Emacs Manual for details +(@code{isearch-forward}). +@item C-r +@kindex 022 @kbd{C-r} (@code{isearch-backward}) +Search backward incrementally (@code{isearch-backward}). +@cindex vanilla (replacement) +@cindex regular expression (replacement) +@item R @var{string} RET @var{newstring} +@kindex 122 @kbd{R} (@code{vip-replace-string}) +There are two modes of replacement, @dfn{vanilla} and @dfn{regular expression}. +If the mode is @i{vanilla} you will get a prompt @samp{Replace string:}, +and if the mode is @i{regular expression} you will ge a prompt +@samp{Replace regexp:}. The mode is initially @i{vanilla}, but you can +toggle these modes by giving a null string as @var{string}. If the mode is +vanilla, this command replaces every occurrence of @var{string} with +@var{newstring}. If the mode is regular expression, @var{string} is +treated as a regular expression and every string matching the regular +expression is replaced with @var{newstring} (@code{vip-replace-string}). +@item Q @var{string} RET @var{newstring} +@kindex 121 @kbd{Q} (@code{vip-query-replace}) +Same as @kbd{R} except that you will be asked form confirmation before each +replacement +@*(@code{vip-query-replace}). +@item r @var{ch} +@kindex 162 @kbd{r} (@code{vip-replace-char}) +Replace the character point is looking at by the character @var{ch}. Give +count, replace that many characters by @var{ch} (@code{vip-replace-char}). +@end table +@noindent +The commands @kbd{/} and @kbd{?} mark point before move, so that you can +return to the original point by @w{@kbd{` `}}. + +@node Modifying Commands, Delete Commands, Searching and Replacing, Vi Commands +@section Modifying Commands + +In this section, commands for modifying the content of a buffer are +described. These commands affect the region determined by a motion command +which is given to the commands as their argument. + +@cindex point commands +@cindex line commands + +We classify motion commands into @dfn{point commands} and +@dfn{line commands}. The point commands are as follows: +@example +@kbd{h}, @kbd{l}, @kbd{0}, @kbd{^}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, @kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, @kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,} +@end example +@noindent +The line commands are as follows: +@example +@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, @kbd{@}}, @kbd{G}, @kbd{'} +@end example +@noindent +@cindex expanding (region) +If a point command is given as an argument to a modifying command, the +region determined by the point command will be affected by the modifying +command. On the other hand, if a line command is given as an argument to a +modifying command, the region determined by the line command will be +enlarged so that it will become the smallest region properly containing the +region and consisting of whole lines (we call this process @dfn{expanding +the region}), and then the enlarged region will be affected by the modifying +command. + +@menu +* Delete Commands:: Commands for deleting text. +* Yank Commands:: Commands for yanking text in Vi's sense. +* Put Back Commands:: Commands for putting back deleted/yanked text. +* Change Commands:: Commands for changing text. +* Repeating and Undoing Modifications:: +@end menu +@node Delete Commands, Yank Commands, Modifying Commands, Modifying Commands +@subsection Delete Commands + +@table @kbd +@item d @var{motion-command} +@kindex 1440 @kbd{d} (@code{vip-command-argument}) +Delete the region determined by the motion command @var{motion-command}. +@end table +@noindent +For example, @kbd{d $} will delete the region between point and end of +current line since @kbd{$} is a point command that moves point to end of line. +@kbd{d G} will delete the region between the beginning of current line and +end of the buffer, since @kbd{G} is a line command. A count given to the +command above will become the count for the associated motion command. +Thus, @kbd{3 d w} will delete three words. + +@kindex 042 @kbd{"} (@code{vip-command-argument}) +It is also possible to save the deleted text into a register you specify. +For example, you can say @kbd{" t 3 d w} to delete three words and save it +to register @kbd{t}. The name of a register is a lower-case letter between +@kbd{a} and @kbd{z}. If you give an upper-case letter as an argument to +a delete command, then the deleted text will be appended to the content of +the register having the corresponding lower-case letter as its name. So, +@kbd{" T d w} will delete a word and append it to register @kbd{t}. Other +modifying commands also accept a register name as their argument, and we +will not repeat similar explanations. + +We have more delete commands as below. + +@table @kbd +@item d d +@kindex 1442 @kbd{d d} +Delete a line. Given a count @var{n}, delete @var{n} lines. +@item d r +@kindex 1442 @kbd{d r} +Delete current region. +@item d R +@kindex 1441 @kbd{d R} +Expand current region and delete it. +@item D +@kindex 104 @kbd{D} (@code{vip-kill-line}) +Delete to the end of a line (@code{vip-kill-line}). +@item x +@kindex 170 @kbd{x} (@code{vip-delete-char}) +Delete a character after point. Given @var{n}, delete @var{n} characters +(@code{vip-delete-char}). +@item @key{DEL} +@kindex 177 @kbd{DEL} (@code{vip-delete-backward-char}) +Delete a character before point. Given @var{n}, delete @var{n} characters +(@code{vip-delete-backward-char}). +@end table + +@node Yank Commands, Put Back Commands, Delete Commands, Modifying Commands +@subsection Yank Commands + +@cindex yank + +Yank commands @dfn{yank} a text of buffer into a (usually anonymous) register. +Here the word `yank' is used in Vi's sense. Thus yank commands do not +alter the content of the buffer, and useful only in combination with +commands that put back the yanked text into the buffer. + +@table @kbd +@item y @var{motion-command} +@kindex 1710 @kbd{y} (@code{vip-command-argument}) +Yank the region determined by the motion command @var{motion-command}. +@end table +@noindent +For example, @kbd{y $} will yank the text between point and the end of line +into an anonymous register, while @kbd{"c y $} will yank the same text into +register @kbd{c}. + +Use the following command to yank consecutive lines of text. + +@table @kbd +@item y y +@itemx Y +@kindex 131 @kbd{Y} (@code{vip-yank-line}) +@kindex 1712 @kbd{y y} (@code{vip-yank-line}) +Yank a line. Given @var{n}, yank @var{n} lines (@code{vip-yank-line}). +@item y r +@kindex 1712 @kbd{y r} +Yank current region. +@item y R +@kindex 1711 @kbd{y R} +Expand current region and yank it. +@end table + +@node Put Back Commands, Change Commands, Yank Commands, Modifying Commands +@subsection Put Back Commands +Deleted or yanked texts can be put back into the buffer by the command +below. + +@table @kbd +@item p +@kindex 160 @kbd{p} (@code{vip-put-back}) +Insert, after the character point is looking at, most recently +deleted/yanked text from anonymous register. Given a register name +argument, the content of the named register will be put back. Given a +count, the command will be repeated that many times. This command also +checks if the text to put back ends with a new line character, and if so +the text will be put below the current line (@code{vip-put-back}). +@item P +@kindex 120 @kbd{P} (@code{vip-Put-back}) +Insert at point most recently deleted/yanked text from anonymous register. +Given a register name argument, the content of the named register will +be put back. Given a count, the command will be repeated that many times. +This command also checks if the text to put back ends with a new line +character, and if so the text will be put above the current line rather +than at point (@code{vip-Put-back}). +@end table +@noindent +@cindex number register +Thus, @kbd{" c p} will put back the content of the register @kbd{c} into the +buffer. It is also possible to specify @dfn{number register} which is a +numeral between @kbd{1} and @kbd{9}. If the number register @var{n} is +specified, @var{n}-th previously deleted/yanked text will be put back. It +is an error to specify a number register for the delete/yank commands. + +@node Change Commands, Repeating and Undoing Modifications, Put Back Commands, Modifying Commands +@subsection Change Commands + +Most commonly used change command takes the following form. + +@table @kbd +@item c @var{motion-command} +@kindex 1430 @kbd{c} (@code{vip-command-argument}) +Replace the content of the region determined by the motion command +@var{motion-command} by the text you type. If the motion command is a +point command then you will type the text into minibuffer, and if the +motion command is a line command then the region will be deleted first and +you can insert the text in @var{insert mode}. +@end table +@noindent +For example, if point is at the beginning of a word @samp{foo} and you +wish to change it to @samp{bar}, you can type @kbd{c w}. Then, as @kbd{w} +is a point command, you will get the prompt @samp{foo =>} in the +minibuffer, for which you can type @kbd{b a r @key{RET}} to complete the change +command.@refill + +@table @kbd +@item c c +@kindex 1432 @kbd{c c} +Change a line. Given a count, that many lines are changed. +@item c r +@kindex 1432 @kbd{c r} +Change current region. +@item c R +@kindex 1431 @kbd{c R} +Expand current region and change it. +@end table + +@node Repeating and Undoing Modifications, Other Vi Commands, Change Commands, Modifying Commands +@subsection Repeating and Undoing Modifications + +VIP records the previous modifying command, so that it is easy to repeat +it. It is also very easy to undo changes made by modifying commands. + +@table @kbd +@item u +@kindex 165 @kbd{u} (@code{vip-undo}) +Undo the last change. You can undo more by repeating undo by the repeat +command @samp{.}. For example, you can undo 5 previous changes by typing +@samp{u....}. If you type @samp{uu}, then the second @samp{u} undoes the +first undo command (@code{vip-undo}). +@item . +@kindex 056 @kbd{.} (@code{vip-repeat}) +Repeat the last modifying command. Given count @var{n} it becomes the new +count for the repeated command. Otherwise, the count for the last +modifying command is used again (@code{vip-repeat}). +@end table + +@node Other Vi Commands, Commands in Insert Mode, Repeating and Undoing Modifications, Vi Commands +@section Other Vi Commands + +Miscellaneous Vi commands are collected here. + +@table @kbd +@item Z Z +@kindex 132 @kbd{Z Z} (@code{save-buffers-kill-emacs}) +Exit Emacs. If modified buffers exist, you will be asked whether you wish +to save them or not (@code{save-buffers-kill-emacs}). +@item !@: @var{motion-command} @var{format-command} +@itemx @var{n} !@: !@: @var{format-command} +@kindex 041 @kbd{!} (@code{vip-command-argument}) +The region determined by the motion command @var{motion-command} will be +given to the shell command @var{format-command} and the region will be +replaced by its output. If a count is given, it will be passed to +@var{motion-command}. For example, @samp{3!Gsort} will sort the region +between point and the 3rd line. If @kbd{!} is used instead of +@var{motion-command} then @var{n} lines will be processed by +@var{format-command} (@code{vip-command-argument}). +@item J +@kindex 112 @kbd{J} (@code{vip-join-lines}) +Join two lines. Given count, join that many lines. A space will be +inserted at each junction (@code{vip-join-lines}). +@item < @var{motion-command} +@itemx @var{n} < < +@kindex 074 @kbd{<} (@code{vip-command-argument}) +Shift region determined by the motion command @var{motion-command} to +left by @var{shift-width} (default is 8). If @kbd{<} is used instead of +@var{motion-command} then shift @var{n} lines +@*(@code{vip-command-argument}). +@item > @var{motion-command} +@itemx @var{n} > > +@kindex 076 @kbd{>} (@code{vip-command-argument}) +Shift region determined by the motion command @var{motion-command} to +right by @var{shift-width} (default is 8). If @kbd{<} is used instead of +@var{motion-command} then shift @var{n} lines +@*(@code{vip-command-argument}). +@item = @var{motion-command} +@kindex 075 @kbd{=} (@code{vip-command-argument}) +Indent region determined by the motion command @var{motion-command}. If +@kbd{=} is used instead of @var{motion-command} then indent @var{n} lines +(@code{vip-command-argument}). +@item * +@kindex 052 @kbd{*} (@code{vip-call-last-kbd-macro}) +Call last remembered keyboard macro. +@item # +A new vi operator. @xref{New Commands}, for more details. +@end table + +The following keys are reserved for future extensions, and currently +assigned to a function that just beeps (@code{vip-nil}). + +@kindex 046 @kbd{&} (@code{vip-nil}) +@kindex 100 @kbd{@@} (@code{vip-nil}) +@kindex 125 @kbd{U} (@code{vip-nil}) +@kindex 133 @kbd{[} (@code{vip-nil}) +@kindex 135 @kbd{]} (@code{vip-nil}) +@kindex 137 @kbd{_} (@code{vip-nil}) +@kindex 161 @kbd{q} (@code{vip-nil}) +@kindex 176 @kbd{~} (@code{vip-nil}) + +@example +&, @@, U, [, ], _, q, ~ +@end example + +VIP uses a special local keymap to interpret key strokes you enter in vi +mode. The following keys are bound to @var{nil} in the keymap. Therefore, +these keys are interpreted by the global keymap of Emacs. We give below a +short description of the functions bound to these keys in the global +keymap. See GNU Emacs Manual for details. + +@table @kbd +@item C-@@ +@kindex 000 @kbd{C-@@} (@code{set-mark-command}) +Set mark and push previous mark on mark ring (@code{set-mark-command}). +@item TAB +@kindex 011 @kbd{TAB} (@code{indent-for-tab-command}) +Indent line for current major mode (@code{indent-for-tab-command}). +@item C-j +@kindex 012 @kbd{C-j} (@code{newline-and-indent}) +Insert a newline, then indent according to mode (@code{newline-and-indent}). +@item C-k +@kindex 013 @kbd{C-k} (@code{kill-line}) +Kill the rest of the current line; before a newline, kill the newline. +With a numeric argument, kill that many lines from point. Negative arguments +kill lines backward (@code{kill-line}). +@item C-l +@kindex 014 @kbd{C-l} (@code{recenter}) +Clear the screen and reprint everything (@code{recenter}). +@item @var{n} C-p +@kindex 020 @kbd{C-p} (@code{previous-line}) +Move cursor vertically up @var{n} lines (@code{previous-line}). +@item C-q +@kindex 021 @kbd{C-q} (@code{quoted-insert}) +Read next input character and insert it. Useful for inserting control +characters +@*(@code{quoted-insert}). +@item C-r +@kindex 022 @kbd{C-r} (@code{isearch-backward}) +Search backward incrementally (@code{isearch-backward}). +@item C-s +@kindex 023 @kbd{C-s} (@code{isearch-forward}) +Search forward incrementally (@code{isearch-forward}). +@item @var{n} C-t +@kindex 024 @kbd{C-t} (@code{transpose-chars}) +Interchange characters around point, moving forward one character. With +count @var{n}, take character before point and drag it forward past @var{n} +other characters. If no argument and at end of line, the previous two +characters are exchanged (@code{transpose-chars}). +@item @var{n} C-v +@kindex 026 @kbd{C-v} (@code{scroll-up}) +Scroll text upward @var{n} lines. If @var{n} is not given, scroll near +full screen (@code{scroll-up}). +@item C-w +@kindex 027 @kbd{C-w} (@code{kill-region}) +Kill between point and mark. The text is save in the kill ring. The +command @kbd{P} or @kbd{p} can retrieve it from kill ring +(@code{kill-region}). +@end table + +@node Commands in Insert Mode, Ex Commands, Other Vi Commands, Vi Commands +@section Insert Mode + +You can enter insert mode by one of the following commands. In addition to +these, you will enter insert mode if you give a change command with a line +command as the motion command. Insert commands are also modifying commands +and you can repeat them by the repeat command @kbd{.} (@code{vip-repeat}). + +@table @kbd +@item i +@kindex 151 @kbd{i} (@code{vip-insert}) +Enter insert mode at point (@code{vip-insert}). +@item I +@kindex 111 @kbd{I} (@code{vip-Insert}) +Enter insert mode at the first non white character on the line +(@code{vip-Insert}). +@item a +@kindex 141 @kbd{a} (@code{vip-append}) +Move point forward by one character and then enter insert mode +(@code{vip-append}). +@item A +@kindex 101 @kbd{A} (@code{vip-Append}) +Enter insert mode at end of line (@code{vip-Append}). +@item o +@kindex 157 @kbd{o} (@code{vip-open-line}) +Open a new line below the current line and enter insert mode +(@code{vip-open-line}). +@item O +@kindex 117 @kbd{O} (@code{vip-Open-line}) +Open a new line above the current line and enter insert mode +(@code{vip-Open-line}). +@item C-o +@kindex 017 @kbd{C-o} (@code{vip-open-line-at-point}) +Insert a newline and leave point before it, and then enter insert mode +@*(@code{vip-open-line-at-point}). +@end table + +Insert mode is almost like emacs mode. Only the following 4 keys behave +differently from emacs mode. + +@table @kbd +@item @key{ESC} +@kindex 033 @kbd{ESC} (@code{vip-change-mode-to-vi}) (insert mode) +This key will take you back to vi mode (@code{vip-change-mode-to-vi}). +@item C-h +@kindex 010 @kbd{C-h} (@code{delete-backward-char}) (insert mode) +Delete previous character (@code{delete-backward-char}). +@item C-w +@kindex 027 @kbd{C-w} (@code{vip-delete-backward-word}) (insert mode) +Delete previous word (@code{vip-delete-backward-word}). +@item C-z +@kindex 032 @kbd{C-z} (@code{vip-ESC}) (insert mode) +This key simulates @key{ESC} key in emacs mode. For instance, typing +@kbd{C-z x} in insert mode iw the same as typing @kbd{ESC x} in emacs mode +(@code{vip-ESC}). +@end table +@noindent +You can also bind @kbd{C-h} to @code{help-command} if you like. +(@xref{Customizing Key Bindings}, for details.) Binding @kbd{C-h} to +@code{help-command} has the effect of making the meaning of @kbd{C-h} +uniform among emacs, vi and insert modes. + +When you enter insert mode, VIP records point as the start point of +insertion, and when you leave insert mode the region between point and +start point is saved for later use by repeat command etc. Therefore, repeat +command will not really repeat insertion if you move point by emacs +commands while in insert mode. + +@node Ex Commands, Ex Command Reference, Commands in Insert Mode, Top +@chapter Ex Commands + +@kindex 072 @kbd{:} (@code{vip-ex}) + +In vi mode, you can execute an Ex command @var{ex-command} by typing: +@example +@kbd{:@: @var{ex-command} @key{RET}} +@end example +Every Ex command follows the following pattern: +@example +@var{address command} @kbd{!}@: @var{parameters count flags} +@end example +@noindent +@cindex address +where all parts are optional. For the syntax of @dfn{address}, the reader +is referred to the reference manual of Ex. + +@cindex magic +@cindex regular expression + +In the current version of VIP, searching by Ex commands is always +@dfn{magic}. That is, search patterns are always treated as @dfn{regular +expressions}. For example, a typical forward search would be invoked by +@kbd{:/@var{pat}/}. If you wish to include @samp{/} as part of +@var{pat} you must preceded it by @samp{\}. VIP strips off these @kbd{\}'s +before @kbd{/} and the resulting @var{pat} becomes the actual search +pattern. Emacs provides a different and richer class or regular +expressions than Vi/Ex, and VIP uses Emacs' regular expressions. See GNU +Emacs Manual for details of regular expressions. + +Several Ex commands can be entered in a line by separating them by a pipe +character @samp{|}. + +@menu +* Ex Command Reference:: Explain all the Ex commands available in VIP. +@end menu +@node Ex Command Reference, Customization, Ex Commands, Ex Commands +@section Ex Command Reference +In this section we briefly explain all the Ex commands supported by VIP. +Most Ex commands expect @var{address} as their argument, and they use +default addresses if they are not explicitly given. In the following, such +default addresses will be shown in parentheses. + +Most command names can and preferably be given in abbreviated forms. In +the following, optional parts of command names will be enclosed in +brackets. For example, @samp{co[py]} will mean that copy command can be +give as @samp{co} or @samp{cop} or @samp{copy}. + +If @var{command} is empty, point will move to the beginning of the line +specified by the @var{address}. If @var{address} is also empty, point will +move to the beginning of the current line. + +@cindex flag + +Some commands accept @dfn{flags} which are one of @kbd{p}, @kbd{l} and +@kbd{#}. If @var{flags} are given, the text affected by the commands will +be displayed on a temporary window, and you will be asked to hit return to +continue. In this way, you can see the text affected by the commands +before the commands will be executed. If you hit @kbd{C-g} instead of +@key{RET} then the commands will be aborted. Note that the meaning of +@var{flags} is different in VIP from that in Vi/Ex. + +@table @kbd +@item (.,.@:) co[py] @var{addr} @var{flags} +@itemx (.,.@:) t @var{addr} @var{flags} +Place a copy of specified lines after @var{addr}. If @var{addr} is +@kbd{0}, it will be placed before the first line. +@item (.,.@:) d[elete] @var{register} @var{count} @var{flags} +Delete specified lines. Text will be saved in a named @var{register} if a +lower-case letter is given, and appended to a register if a capital letter is +given. +@item e[dit] !@: +@var{addr} @var{file} +@itemx e[x] !@: +@var{addr} @var{file} +@itemx vi[sual] !@: +@var{addr} @var{file} +Edit a new file @var{file} in the current window. The command will abort +if current buffer is modified, which you can override by giving @kbd{!}. +If @kbd{+}@var{addr} is given, @var{addr} becomes the current line. +@item file +Give information about the current file. +@item (1,$) g[lobal] !@: /@var{pat}/ @var{cmds} +@itemx (1,$) v /@var{pat}/ @var{cmds} +Among specified lines first mark each line which matches the regular +expression @var{pat}, and then execute @var{cmds} on each marked line. +If @kbd{!}@: is given, @var{cmds} will be executed on each line not matching +@var{pat}. @kbd{v} is same as @kbd{g!}. +@item (.,.+1) j[oin] !@: @var{count} @var{flags} +Join specified lines into a line. Without @kbd{!}, a space character will +be inserted at each junction. +@item (.@:) k @var{ch} +@itemx (.@:) mar[k] @var{ch} +Mark specified line by a lower-case character @var{ch}. Then the +addressing form @kbd{'}@var{ch} will refer to this line. No white space is +required between @kbd{k} and @var{ch}. A white space is necessary between +@kbd{mark} and @var{ch}, however. +@item map @var{ch} @var{rhs} +Define a macro for vi mode. After this command, the character @var{ch} +will be expanded to @var{rhs} in vi mode. +@item (.,.@:) m[ove] @var{addr} +Move specified lines after @var{addr}. +@item (.@:) pu[t] @var{register} +Put back previously deleted or yanked text. If @var{register} is given, +the text saved in the register will be put back; otherwise, last deleted or +yanked text will be put back. +@item q[uit] ! +Quit from Emacs. If modified buffers with associated files exist, you will +be asked whether you wish to save each of them. At this point, you may +choose not to quit, by hitting @kbd{C-g}. If @kbd{!}@: is given, exit from +Emacs without saving modified buffers. +@item (.@:) r[ead] @var{file} +Read in the content of the file @var{file} after the specified line. +@item (.@:) r[ead] !@: @var{command} +Read in the output of the shell command @var{command} after the specified +line. +@item se[t] +Set a variable's value. @xref{Customizing Constants}, for the list of variables +you can set. +@item sh[ell] +Run a subshell in a window. +@item (.,.@:) s[ubstitute] /@var{pat}/@var{repl}/ @var{options} @var{count} @var{flags} +@itemx (.,.@:) & @var{options} @var{count} @var{flags} +On each specified line, the first occurrence of string matching regular +expression @var{pat} is replaced by replacement pattern @var{repl}. Option +characters are @kbd{g} and @kbd{c}. If global option character @kbd{g} +appears as part of @var{options}, all occurrences are substituted. If +confirm option character @kbd{c} appears, you will be asked to give +confirmation before each substitution. If @kbd{/@var{pat}/@var{repl}/} is +missing, the last substitution is repeated. +@item st[op] +Suspend Emacs. +@item ta[g] @var{tag} +@cindex tag +@cindex selected tags table +Find first definition of @var{tag}. If no @var{tag} is given, previously +given @var{tag} is used and next alternate definition is find. By default, +the file @file{TAGS} in the current directory becomes the @dfn{selected tags +table}. You can select another tags table by @kbd{set} command. +@xref{Customizing Constants}, for details. +@item und[o] +Undo the last change. +@item unm[ap] @var{ch} +The macro expansion associated with @var{ch} is removed. +@item ve[rsion] +Tell the version number of VIP. +@item (1,$) w[rite] !@: @var{file} +Write out specified lines into file @var{file}. If no @var{file} is given, +text will be written to the file associated to the current buffer. Unless +@kbd{!}@: is given, if @var{file} is different from the file associated to +the current buffer and if the file @var{file} exists, the command will not +be executed. Unlike Ex, @var{file} becomes the file associated to the +current buffer. +@item (1,$) w[rite]>> @var{file} +Write out specified lines at the end of file @var{file}. @var{file} +becomes the file associated to the current buffer. +@item (1,$) wq !@: @var{file} +Same as @kbd{write} and then @kbd{quit}. If @kbd{!}@: is given, same as +@kbd{write !}@: then @kbd{quit}. +@item (.,.) y[ank] @var{register} @var{count} +Save specified lines into register @var{register}. If no register is +specified, text will be saved in an anonymous register. +@item @var{addr} !@: @var{command} +Execute shell command @var{command}. The output will be shown in a new +window. If @var{addr} is given, specified lines will be used as standard +input to @var{command}. +@item ($) = +Print the line number of the addressed line. +@item (.,.) > @var{count} @var{flags} +Shift specified lines to the right. The variable @code{vip-shift-width} +(default value is 8) determines the amount of shift. +@item (.,.) < @var{count} @var{flags} +Shift specified lines to the left. The variable @code{vip-shift-width} +(default value is 8) determines the amount of shift. +@item (.,.@:) ~ @var{options} @var{count} @var{flags} +Repeat the previous @kbd{substitute} command using previous search pattern +as @var{pat} for matching. +@end table + +The following Ex commands are available in Vi, but not implemented in VIP. +@example +@kbd{abbreviate}, @kbd{list}, @kbd{next}, @kbd{print}, @kbd{preserve}, @kbd{recover}, @kbd{rewind}, @kbd{source}, +@kbd{unabbreviate}, @kbd{xit}, @kbd{z} +@end example + +@node Customization, Customizing Constants, Ex Command Reference, Top +@chapter Customization + +If you have a file called @file{.vip} in your home directory, then it +will also be loaded when VIP is loaded. This file is thus useful for +customizing VIP. + +@menu +* Customizing Constants:: How to change values of constants. +* Customizing Key Bindings:: How to change key bindings. +@end menu + +@node Customizing Constants, Customizing Key Bindings, Customization, Customization +@section Customizing Constants +An easy way to customize VIP is to change the values of constants used +in VIP. Here is the list of the constants used in VIP and their default +values. + +@table @code +@item vip-shift-width 8 +The number of columns shifted by @kbd{>} and @kbd{<} command. +@item vip-re-replace nil +If @code{t} then do regexp replace, if @code{nil} then do string replace. +@item vip-search-wrap-around t +If @code{t}, search wraps around the buffer. +@item vip-re-search nil +If @code{t} then search is reg-exp search, if @code{nil} then vanilla +search. +@item vip-case-fold-search nil +If @code{t} search ignores cases. +@item vip-re-query-replace nil +If @code{t} then do reg-exp replace in query replace. +@item vip-open-with-indent nil +If @code{t} then indent to the previous current line when open a new line +by @kbd{o} or @kbd{O} command. +@item vip-tags-file-name "TAGS" +The name of the file used as the tags table. +@item vip-help-in-insert-mode nil +If @code{t} then @key{C-h} is bound to @code{help-command} in insert mode, +if @code{nil} then it sis bound to @code{delete-backward-char}. +@end table +@noindent +You can reset these constants in VIP by the Ex command @kbd{set}. Or you +can include a line like this in your @file{.vip} file: +@example +(setq vip-case-fold-search t) +@end example + +@node Customizing Key Bindings,, Customizing Constants, Customization +@section Customizing Key Bindings + +@cindex local keymap + +VIP uses @code{vip-command-mode-map} as the @dfn{local keymap} for vi mode. +For example, in vi mode, @key{SPC} is bound to the function +@code{vip-scroll}. But, if you wish to make @key{SPC} and some other keys + behave like Vi, you can include the following lines in your @file{.vip} +file. + +@example +(define-key vip-command-mode-map "\C-g" 'vip-info-on-file) +(define-key vip-command-mode-map "\C-h" 'vip-backward-char) +(define-key vip-command-mode-map "\C-m" 'vip-next-line-at-bol) +(define-key vip-command-mode-map " " 'vip-forward-char) +(define-key vip-command-mode-map "g" 'vip-keyboard-quit) +(define-key vip-command-mode-map "s" 'vip-substitute) +(define-key vip-command-mode-map "C" 'vip-change-to-eol) +(define-key vip-command-mode-map "R" 'vip-change-to-eol) +(define-key vip-command-mode-map "S" 'vip-substitute-line) +(define-key vip-command-mode-map "X" 'vip-delete-backward-char) +@end example + +@unnumbered Key Index + +@printindex ky + +@unnumbered Concept Index +@printindex cp + +@contents +@bye diff --git a/man/viper.texi b/man/viper.texi new file mode 100644 index 00000000000..45cded537ec --- /dev/null +++ b/man/viper.texi @@ -0,0 +1,4459 @@ +% -*-texinfo-*- +\input texinfo + +@comment Using viper.info instead of viper in setfilename breaks DOS. +@comment @setfilename viper +@comment @setfilename viper.info +@setfilename ../info/viper + +@dircategory Editors +@direntry +* VIPER: (viper). The newest Emacs VI-emulation mode. + (also, A VI Plan for Emacs Rescue + or the VI PERil.) +@end direntry + +@iftex +@finalout +@end iftex + +@titlepage +@title Viper Is a Package for Emacs Rebels +@subtitle a Vi emulator for Emacs +@subtitle March 1998, Viper Version 3.02 (Polyglot) + +@author Michael Kifer (Viper) +@author Aamod Sane (VIP 4.4) +@author Masahiko Sato (VIP 3.5) + +@page +@vskip 0pt plus 1fill +@end titlepage + +@unnumbered Distribution + +@noindent +Copyright @copyright{} 1995, 1996, 1997 Free Software Foundation, Inc. + +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 +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the same conditions as for modified versions. + +@ifinfo +@node Top, Overview,, (DIR) + +@unnumbered Viper + +We believe that one or more of the following statements are adequate +descriptions: + +@example +Viper Is a Package for Emacs Rebels; +it is a VI Plan for Emacs Rescue +and/or a venomous VI PERil. +@end example + +Technically speaking, Viper is a Vi emulation package for Emacs. It +implements all Vi and Ex commands, occasionally improving on them and +adding many new features. It gives the user the best of both worlds: Vi +keystrokes for editing combined with the power of the Emacs environment. + +Viper emulates Vi at several levels, from the one that closely follows Vi +conventions to the one that departs from many of them. It has many +customizable options, which can be used to tailor Viper to the work habits +of various users. +This manual describes Viper, concentrating on the differences from Vi and +new features of Viper. + +Viper, formerly known as VIP-19, was written by Michael Kifer. It is based +on VIP version 3.5 by Masahiko Sato and VIP version 4.4 by Aamod Sane. +Viper tries to be compatible with these packages. + +Viper is intended to be usable without reading this manual --- the defaults +are set to make Viper as close to Vi as possible. At startup, Viper will +try to set the most appropriate default environment for you, based on +your familiarity with Emacs. It will also tell you the basic GNU Emacs window +management commands to help you start immediately. + +Although this manual explains how to customize Viper, some basic +familiarity with Emacs Lisp would be a plus. + +It is recommended that you read the Overview node. The other nodes may +be visited as needed. + +Comments and bug reports are welcome. +@code{kifer@@cs.emacs.edu} is the current address for Viper bug reports. +Please use the Ex command @kbd{:submitReport} for this purpose.@refill + +@end ifinfo + +@menu +* Overview:: Must read to get started +* Improvements over Vi:: New features, Improvements +* Customization:: How to customize Viper +* Commands:: Vi and Ex Commands + +* Key Index:: Index of Vi and Ex Commands +* Function Index:: Index of Viper Functions +* Variable Index:: Index of Viper Variables +* Package Index:: Index of Packages Mentioned in this Document +* Concept Index:: Vi, Ex and Emacs concepts + +* Acknowledgments:: +@end menu +@iftex +@unnumbered Introduction + +We believe that one or more of the following statements are adequate +descriptions: + +@example +Viper Is a Package for Emacs Rebels; +it is a VI Plan for Emacs Rescue +and/or a venomous VI PERil. +@end example + +Viper is a Vi emulation package for Emacs. Viper contains virtually all +of Vi and Ex functionality and much more. It gives you the best of both +worlds: Vi keystrokes for editing combined with the GNU Emacs +environment. Viper also fixes some common complaints with Vi commands. +This manual describes Viper, concentrating on the differences from Vi +and on the new features of Viper. + +Viper was written by Michael Kifer. It is based on VIP version 3.5 by +Masahiko Sato and VIP version 4.4 by Aamod Sane. Viper tries to be +compatible with these packages. + +Viper is intended to be usable out of the box, without reading this manual +--- the defaults are set to make Viper as close to Vi as possible. At +startup, Viper will attempt to set the most appropriate default environment +for you, based on your familiarity with Emacs. It will also tell you the +basic GNU Emacs window management commands to help you start immediately. + +Although this manual explains how to customize Viper, some basic +familiarity with Emacs Lisp would be a plus. + +It is recommended that you read the chapter Overview. The other chapters +will be useful for customization and advanced usage. + +You should also learn to use the Info on-line hypertext manual system that +comes with Emacs. This manual can be read as an Info file. Try the command +@kbd{@key{ESC} x info} with vanilla Emacs sometime. + +Comments and bug reports are welcome. +@code{kifer@@cs.sunysb.edu} is the current address for Viper bug reports. +Please use the Ex command @kbd{:submitReport} for this purpose.@refill + +@end iftex + +@node Overview,Improvements over Vi,Top,Top +@chapter Overview of Viper + +Viper is a Vi emulation on top of Emacs. At the same time, Viper provides a +virtually unrestricted access to Emacs facilities. Perfect compatibility +with Vi is possible but not desirable. This chapter tells you about the +Emacs ideas that you should know about, how to use Viper within Emacs and +some incompatibilities. + +Viper was formerly known as VIP-19, which was +a descendant of VIP 3.5 by Masahiko Sato and VIP 4.4 by Aamod Sane. + +@menu +* Emacs Preliminaries:: Basic concepts in Emacs. +* Loading Viper:: Loading and Preliminary Configuration. +* States in Viper:: Viper has four states orthogonal to Emacs + modes. +* The Minibuffer:: Command line in Emacs. +* Multiple Files in Viper:: True multiple file handling. +* Unimplemented Features:: That are unlikely to be implemented. +@end menu + +@node Emacs Preliminaries, Loading Viper, Overview, Overview +@section Emacs Preliminaries + +@cindex buffer +@cindex point +@cindex mark +@cindex text +@cindex looking at +@cindex end (of buffer) +@cindex end (of line) +@cindex region + +Emacs can edit several files at once. A file in Emacs is placed in a +@dfn{buffer} that usually has the same name as the file. Buffers are also used +for other purposes, such as shell interfaces, directory editing, etc. +@xref{Dired,,Directory Editor,emacs,The +Gnu Emacs Manual}, for an example.@refill + +A buffer has a distinguished position called the @dfn{point}. +A @dfn{point} is always between 2 characters, and is @dfn{looking at} +the right hand character. The cursor is positioned on the right hand +character. Thus, when the @dfn{point} is looking at the end-of-line, +the cursor is on the end-of-line character, i.e.@: beyond the last +character on the line. This is the default Emacs behavior.@refill + +The default settings of Viper try to mimic the behavior of Vi, preventing +the cursor from going beyond the last character on the line. By using +Emacs commands directly (such as those bound to arrow keys), it is possible +to get the cursor beyond the end-of-line. However, this won't (or +shouldn't) happen if you restrict yourself to standard Vi keys, unless you +modify the default editing style. @xref{Customization}.@refill + +In addition to the @dfn{point}, there is another distinguished buffer +position called the @dfn{mark}. @xref{Mark,,Mark,emacs,The GNU Emacs +manual}, for more info on the mark. The text between the @dfn{point} and +the @dfn{mark} is called the @dfn{region} of the buffer. For the Viper +user, this simply means that in addition to the Vi textmarkers a--z, there +is another marker called @dfn{mark}. This is similar to the unnamed Vi +marker used by the jump commands @kbd{``} and @kbd{''}, which move the +cursor to the position of the last absolute jump. Viper provides access to +the region in most text manipulation commands as @kbd{r} and @kbd{R} suffix +to commands that operate on text regions, e.g., @kbd{dr} to delete region, +etc. + +Furthermore, Viper lets Ex-style commands to work on the current region. +This is done by typing a digit argument before @kbd{:}. For instance, +typing @kbd{1:} will propmt you with something like @emph{:123,135}, +assuming that the current region starts at line 123 and ends at line +135. There is no need to type the line numbers, since Viper inserts them +automatically in front of the Ex command. + +@xref{Basics}, for more info.@refill + +@cindex window +@cindex mode line +@cindex buffer information +@cindex Minibuffer +@cindex command line +@cindex buffer (modified) + +Emacs divides the screen into tiled @dfn{windows}. You can see the +contents of a buffer through the window associated with the buffer. The +cursor of the screen is positioned on the character after @dfn{point}. +Every window has a @dfn{mode line} that displays information about the buffer. +You can change the format of the mode +line, but normally if you see @samp{**} at the beginning of a mode line it +means that the buffer is @dfn{modified}. If you write out the contents of +a buffer to a file, then the buffer will become not modified. Also if +you see @samp{%%} at the beginning of the mode line, it means that the file +associated with the buffer is write protected. The mode line will also +show the buffer name and current major and minor modes (see below). +A special buffer called @dfn{Minibuffer} is displayed as the last line +in a Minibuffer window. The Minibuffer window is used for command input +output. Viper uses Minibuffer window for @kbd{/} and @kbd{:} +commands.@refill + +@cindex mode +@cindex keymap +@cindex local keymap +@cindex global keymap +@cindex major mode +@cindex minor mode + +An Emacs buffer can have a @dfn{major mode} that customizes Emacs for +editing text of a particular sort by changing the functionality of the keys. +Keys are defined using a @dfn{keymap} that records the bindings between +keystrokes and +functions. The @dfn{global keymap} is common to all the +buffers. Additionally, each buffer has its @dfn{local keymap} that determines the +@dfn{mode} of the buffer. If a function is bound to some key in the local +keymap then that function will be executed when you type the key. +If no function is bound to a key in the +local map, however, the function bound to the key in the global map +will be executed. @xref{Major Modes,Major Modes,Major Modes,emacs,The +GNU Emacs Manual}, for more information.@refill + +A buffer can also have a @dfn{minor mode}. Minor modes are options that +you can use or not. A buffer in @code{text-mode} can have +@code{auto-fill-mode} as minor mode, which can be turned off or on at +any time. In Emacs, a minor mode may have it own keymap, +which overrides the local keymap when the minor mode is turned on. For +more information, @pxref{Minor Modes,Minor Modes,Minor Modes,emacs,The +GNU Emacs Manual} @refill + +@cindex Viper as minor mode +@cindex Control keys +@cindex Meta key + +Viper is implemented as a collection of minor modes. Different minor modes +are involved when Viper emulates Vi command mode, Vi insert mode, etc. +You can also turn Viper on and off at any time while in Vi command mode. +@xref{States in Viper}, for +more information.@refill + +Emacs uses Control and Meta modifiers. These are denoted as C and M, +e.g.@: @kbd{^Z} as @kbd{C-z} and @kbd{Meta-x} as @kbd{M-x}. The Meta key is +usually located on each side of the Space bar; it is used in a manner +similar to the Control key, e.g., @kbd{M-x} means typing @kbd{x} while +holding the Meta key down. For keyboards that do not have a Meta key, +@key{ESC} is used as Meta. Thus @kbd{M-x} is typed as @kbd{@key{ESC} +x}. Viper uses @key{ESC} to switch from Insert state to Vi state. Therefore +Viper defines @kbd{C-\} as its Meta key in Vi state. @xref{Vi State}, for +more info.@refill + +Emacs is structured as a lisp interpreter around a C core. Emacs keys +cause lisp functions to be called. It is possible to call these +functions directly, by typing @kbd{M-x function-name}. + +@node Loading Viper, States in Viper, Emacs Preliminaries, Overview +@section Loading Viper + +The most common way to load it automatically is to include the following +lines (in the given order!): + +@lisp +(setq viper-mode t) +(require 'viper) +@end lisp + +@noindent +in your @file{~/.emacs} file. The @file{.emacs} file is placed in your +home directory and it is be executed every time you invoke Emacs. This is +the place where all general Emacs customization takes place. Beginning with +version 20.0, Emacsen have an interactive interface, which simplifies the +job of customization significantly. + +Viper also uses the file @file{~/.viper} for Viper-specific customization. +If you wish to be in Vi command state whenever this is deemed appropriate +by the author, you can include the following line in your @file{.viper}: +@lisp +(setq viper-always t) +@end lisp +@noindent +(@xref{Vi State}, for the explanation of Vi command state.) + +The location of Viper customization file can be changed by setting the +variable @code{viper-custom-file-name} in @file{.emacs} @emph{prior} to loading +Viper. + +Once invoked, Viper will arrange to bring up Emacs buffers in Vi state +whenever this makes sense. +@xref{Packages that Change Keymaps}, to find out when forcing Vi command state +on a buffer may be counter-productive. + +Even if your @file{.emacs} and @file{.viper} files do not contain any of the +above lines, you can still load Viper and enter Vi command state by typing the +following from within Emacs: + +@lisp +M-x viper-mode +@end lisp + +When Emacs first comes up, if you have not specified a file on the +command line, it will show the @samp{*scratch*} buffer, in the +@samp{Lisp Interaction} mode. After you invoke Viper, you can start +editing files by using @kbd{:e}, @kbd{:vi}, or @kbd{v} commands. +(@xref{File and Buffer Handling}, for more information on @kbd{v} and other +new commands that, in many cases, are more convenient than @kbd{:e}, +@kbd{:vi}, and similar old-style Vi commands.)@refill + +Finally, if at some point you would want to get de-Viperize your running +copy of Emacs after Viper has been loaded, the command @kbd{M-x +viper-go-away} will do it for you. The function @code{toggle-viper-mode} +toggles Viperization of Emacs on and off. + +@node States in Viper, The Minibuffer, Loading Viper,Overview +@section States in Viper + +@kindex @kbd{C-z} +@kindex @key{ESC} +@kindex @kbd{i} +@cindex Emacs state +@cindex Vi state +@cindex Insert state +@cindex Replace state +@cindex Ex commands +@findex @code{viper-go-away} +@findex @code{toggle-viper-mode} + +Viper has four states, Emacs, Vi, Insert, and Replace. + +@table @samp +@item Emacs state +This is the state plain vanilla Emacs is normally in. After you have loaded +Viper, @kbd{C-z} will normally take you to Vi command state. Another +@kbd{C-z} will take you back to Emacs state. This toggle key can be +changed, @pxref{Customization} You can also type @kbd{M-x viper-mode} to +change to Vi state.@refill + + +For users who chose to set their user level to 1 at Viper setup time, +switching to Emacs state is deliberately made harder in order to not +confuse the novice user. In this case, @kbd{C-z} will either iconify Emacs +(if Emacs runs as an application under X Windows) or it will stop Emacs (if +Emacs runs on a dumb terminal or in an Xterm window). + +@item Vi state +This is the Vi command mode. Any of the Vi commands, such as @kbd{i, o, a}, +@dots{}, will take you to Insert state. All Vi commands may +be used in this mode. Most Ex commands can also be used. +For a full list of Ex commands supported by Viper, type +@kbd{:} and then @key{TAB}. To get help on any issue, including the Ex +commands, type @kbd{:help}. This will invoke Viper Info +(if it is installed). Then typing @kbd{i} will prompt you for a topic to +search in the index. Note: to search for Ex commands in the index, you +should start them with a ``@kbd{:}'', e.g., @kbd{:WW}. + +In Viper, Ex commands can be made to work on the current Emacs region. +This is done by typing a digit argument before @kbd{:}. +For instance, typing @kbd{1:} will propmt you with something like +@emph{:123,135}, assuming that the current region starts at line 123 and +ends at line 135. There is no need to type the line numbers, since Viper +inserts them automatically in front of the Ex command. + +@item Insert state +Insert state is the Vi insertion mode. @key{ESC} will take you back to +Vi state. Insert state editing can be done, including auto-indentation. By +default, Viper disables Emacs keybindings in Insert state. + +@item Replace state +Commands like @kbd{cw} invoke the Replace state. When you cross the +boundary of a replacement region (usually designated via a @samp{$} sign), +it will automatically change to Insert state. You do not have to worry +about it. The key bindings remain practically the same as in Insert +state. If you type @key{ESC}, Viper will switch to Vi command mode, terminating the +replacement state.@refill +@end table + +@cindex mode line + +The modes are indicated on the @dfn{mode line} as <E>, <I>, <V>, and <R>, +so that the multiple modes do not confuse you. Most of your editing can be +done in Vi and Insert states. Viper will try to make all new buffers be in Vi +state, but sometimes they may come up in Emacs state. @kbd{C-z} +will take you to Vi state in such a case. In some major modes, like Dired, +Info, Gnus, etc., you should not switch to Vi state (and Viper will not +attempt to do so) because these modes are not intended for text editing and +many of the Vi keys have special meaning there. If you plan to read news, +browse directories, read mail, etc., from Emacs (which you should start +doing soon!), you should learn about the meaning of the various keys in +those special modes (typing @kbd{C-h m} in a buffer provides +help with key bindings for the major mode of that buffer). + +If you switch to Vi in Dired or similar modes---no harm is done. It is just +that the special keybindings provided by those modes will be temporarily +overshadowed by Viper's bindings. Switching back to Viper's Emacs state +will revive the environment provided by the current major mode. + +States in Viper are orthogonal to Emacs major modes, such as C mode or Dired +mode. You can turn Viper on and off for any Emacs state. When Viper is turned +on, Vi state can be used to move around. In Insert state, the bindings for +these modes can be accessed. For beginners (users at Viper levels 1 and 2), +these bindings are suppressed in Insert state, so that new users are not +confused by the Emacs states. Note that unless you allow Emacs bindings in +Insert state, you cannot do many interesting things, like language +sensitive editing. For the novice user (at Viper level 1), all major mode +bindings are turned off in Vi state as well. This includes the bindings for +key sequences that start with @kbd{C-c}, which practically means that all +major mode bindings are supported. @xref{Customization}, to find out how +to allow Emacs keys in Insert state. + +@menu +* Emacs State:: This is the state you should learn more about when + you get up to speed with Viper. +* Vi State:: Vi commands are executed in this state. +* Insert State:: You can enter text, and also can do sophisticated + editing if you know enough Emacs commands. +* Replace State:: Like Insert mode, but it is invoked via the + replacement commands, such as cw, C, R, etc. +@end menu + +@node Emacs State, Vi State, States in Viper, States in Viper +@subsection Emacs State + +@kindex @kbd{C-z} +@cindex Emacs state + + +You will be in this mode only by accident (hopefully). This is the state +Emacs is normally in (imagine!!). Now leave it as soon as possible by +typing @kbd{C-z}. Then you will be in Vi state (sigh of relief) :-). + +Emacs state is actually a Viperism to denote all the major and minor modes +(@pxref{Emacs Preliminaries}) other than Viper that Emacs can be in. Emacs +can have several modes, such as C mode for editing C programs, LaTeX mode +for editing LaTeX documents, Dired for directory editing, etc. These are +major modes, each with a different set of key-bindings. Viper states are +orthogonal to these Emacs major modes. The presence of these language +sensitive and other modes is a major win over Vi. @xref{Improvements over +Vi}, for more.@refill + +The bindings for these modes can be made available in the Viper Insert state +as well as in Emacs state. Unless you specify your user level as 1 (a +novice), all major mode key sequences that start with @kbd{C-x} and +@kbd{C-c} are also available in Vi state. This is important because major +modes designed for editing files, such as cc-mode or latex-mode, use key +sequences that begin with @kbd{C-x} and @kbd{C-c}. + +There is also a key that lets you temporarily escape to Vi command state +from Emacs or Insert states: typing @kbd{C-c \} will let you execute a +single Vi command while staying in Viper's Emacs or Insert state. +In Insert state, the same can also be achieved by typing @kbd{C-z}. + + +@node Vi State, Insert State, Emacs State, States in Viper +@subsection Vi State + +@cindex Vi state + +This is the Vi command mode. When Viper is in Vi state, you will see the sign +<V> in the mode line. Most keys will work as in Vi. The notable +exceptions are: + +@table @kbd +@item C-x +@kindex @kbd{C-x} +@kbd{C-x} is used to invoke Emacs commands, mainly those that do window +management. @kbd{C-x 2} will split a window, @kbd{C-x 0} will close a +window. @kbd{C-x 1} will close all other windows. @kbd{C-xb} is used to +switch buffers in a window, and @kbd{C-xo} to move through windows. +These are about the only necessary keystrokes. +For the rest, see the GNU Emacs Manual. + +@item C-c +@kindex @kbd{C-c} +For user levels 2 and higher, this key serves as a prefix key for the key +sequences used by various major modes. For users at Viper level 1, @kbd{C-c} +simply beeps. + +@item C-g and C-] +@kindex @kbd{C-g} +@kindex @kbd{C-]} + +These are the Emacs @samp{quit} keys. +There will be cases where you will have to +use @kbd{C-g} to quit. Similarly, @kbd{C-]} is used to exit +@samp{Recursive Edits} in Emacs for which there is no comparable Vi +functionality and no key-binding. Recursive edits are indicated by +@samp{[]} brackets framing the modes on the mode line. +@xref{Recursive Edit,Recursive +Edit,Recursive Edit,emacs,The GNU Emacs Manual}. +At user level 1, @kbd{C-g} is bound to @code{viper-info-on-file} +function instead. +@refill +@item C-\ +@kindex @kbd{C-\} +@cindex Meta key + +Viper uses @key{ESC} as a switch between Insert and Vi states. Emacs uses +@key{ESC} for Meta. The Meta key is very important in Emacs since many +finctions are accessible only via that key as @kbd{M-x function-name}. +Therefore, we need to simulate it somehow. In Viper's Vi, Insert, and +Replace states, the meta key is set to be @kbd{C-\}. Thus, to get +@kbd{M-x}, you should type @kbd{C-\ x} (if the keyboard has no Meta key). +This works both in the Vi command state and in the Insert and Replace +states. In Vi command state, you can also use @kbd{\ @key{ESC}} as the +meta key. + +Note: Emacs binds @kbd{C-\} to a function that offers to change the +keyboard input method in the multilingual environment. Viper overrides this +binding. However, it is still possible to switch the input method by typing +@kbd{\ C-\} in the Vi command state and @kbd{C-z \ C-\} in the Insert state. +Or you can use the MULE menu in the menubar. +@end table +@noindent +Other differences are mostly improvements. The ones you should know +about are: + +@table @samp +@item Undo +@kindex @kbd{u} +@kbd{u} will undo. Undo can be repeated by the @kbd{.} key. Undo itself +can be undone. Another @kbd{u} will change the direction. The presence +of repeatable undo means that @kbd{U}, undoing lines, is not very +important. Therefore, @kbd{U} also calls @code{viper-undo}. +@cindex multiple undo +@cindex undo + + +@item Counts +Most commands, @kbd{~}, @kbd{[[}, @kbd{p}, @kbd{/}, @dots{}, etc., take counts. + +@comment ]] Just to balance parens +@item Regexps +Viper uses Emacs Regular Expressions for searches. These are a superset of +Vi regular +expressions, excepting the change-of-case escapes @samp{\u}, @samp{\L}, +@dots{}, etc. @xref{Regular Expressions,,Regular Expressions,emacs,The +GNU Emacs Manual}, for details. +Files specified to @kbd{:e} use @code{csh} regular expressions +(globbing, wildcards, what have you). +However, the function @code{viper-toggle-search-style}, bound to @kbd{C-c /}, +lets the user switch from search with regular expressions to plain vanilla +search and vice versa. It also lets one switch from case-sensitive search +to case-insensitive and back. +@xref{Viper Specials}, for more details. +@cindex regular expressions +@cindex vanilla search +@cindex case-sensitive search +@cindex case-insensitive search +@kindex @kbd{C-c /} + +@item Ex commands +@cindex Ex commands +The current working directory of a buffer is automatically inserted in the +minibuffer if you type @kbd{:e} then space. Absolute filenames are +required less often in Viper. For path names, Emacs uses a convention that +is slightly different from that of Unix. It is designed to minimize the +need for deleting path names that Emacs provides in its prompts. (This is +usually convenient, but occasionally the prompt may suggest a wrong path +name for you.) If you see a prompt @kbd{/usr/foo/} and you wish to edit the +file @kbd{~/.viper}, you don't have to erase the prompt. Instead, simply +continue typing what you need. Emacs will interpret @kbd{/usr/foo/~/.viper} +correctly. Similarly, if the prompt is @kbd{~/foo/} and you need to get to +@kbd{/bar/file}, keep typing. Emacs interprets @kbd{~/foo//bar/} as +@kbd{/bar/file}, since when it sees @samp{//}, it understands that +@kbd{~/foo/} is to be discarded. + +The command @kbd{:cd} will change the default directory for the +current buffer. The command @kbd{:e} will interpret the +filename argument in @code{csh}. @xref{Customization}, if you +want to change the default shell. +The command @kbd{:next} takes counts from +@kbd{:args}, so that @kbd{:rew} is obsolete. Also, @kbd{:args} will show only +the invisible files (i.e., those that are not currently seen in Emacs +windows). + +When applicable, Ex commands support file completion and history. This +means that by typing a partial file name and then @key{TAB}, Emacs will try +to complete the name or it will offer a menu of possible completions. +This works similarly to Tcsh and extends the behavior of Csh. While Emacs +is waiting for a file name, you can type @kbd{M-p} to get the previous file +name you typed. Repeatedly typing @kbd{M-p} and @kbd{M-n} will let you +browse through the file history. + +Like file names, partially typed Ex commands can be completed by typing +@key{TAB}, and Viper keeps the history of Ex commands. After typing +@kbd{:}, you can browse through the previously entered Ex commands by +typing @kbd{M-p} and @kbd{M-n}. Viper tries to rationalize when it puts Ex +commands on the history list. For instance, if you typed @kbd{:w!@: foo}, +only @kbd{:w!} will be placed on the history list. This is because the +last history element is the default that can be invoked simply by typing +@kbd{: @key{RET}}. If @kbd{:w!@: foo} were placed on the list, it would be all to +easy to override valuable data in another file. Reconstructing the full +command, @kbd{:w!@: foo}, from the history is still not that hard, since Viper +has a separate history for file names. By typing @kbd{: M-p}, you will get +@kbd{:w!} in the Minibuffer. Then, repeated @kbd{M-p} will get you through +the file history, inserting one file name after another. + +In contrast to @kbd{:w!@: foo}, if the command were @kbd{:r foo}, the entire +command will appear in the history list. This is because having @kbd{:r} +alone as a default is meaningless, since this command requires a file +argument. +@refill +@end table +@noindent +As Vi, Viper's destructive commands can be re-executed by typing `@kbd{.}'. +However, in addition, Viper keeps track of the history of such commands. This +history can be perused by typing @kbd{C-c M-p} and @kbd{C-c M-n}. +Having found the appropriate command, it can be then executed by typing +`@kbd{.}'. +@xref{Improvements over Vi}, for more information. + +@node Insert State, Replace State, Vi State, States in Viper +@subsection Insert State + +@cindex Insert state + +To avoid confusing the beginner (at Viper level 1 and 2), Viper makes only the +standard Vi keys available in Insert state. The implication is that +Emacs major modes cannot be used Insert state. +It is strongly recommended that as soon as you are comfortable, make the +Emacs state bindings visible (by changing your user level to 3 or higher). +@xref{Customization}, +to see how to do this.@refill + +Once this is done, it is possible to do quite a bit of editing in +Insert state. For instance, Emacs has a @dfn{yank} command, @kbd{C-y}, +which is similar to Vi's @kbd{p}. However, unlike @kbd{p}, @kbd{C-y} can be +used in Insert state of Viper. Emacs also has a kill ring where it keeps +pieces of text you deleted while editing buffers. The command @kbd{M-y} is +used to delete the text previously put back by Emacs' @kbd{C-y} or by Vi's +@kbd{p} command and reinsert text that was placed on the kill-ring earlier. + +This works both in Vi and Insert states. +In Vi state, @kbd{M-y} is a much better alternative to the usual Vi's way +of recovering the 10 previously deleted chunks of text. In Insert state, +you can +use this as follows. Suppose you deleted a piece of text and now you need +to re-insert it while editing in Insert mode. The key @kbd{C-y} will put +back the most recently deleted chunk. If this is not what you want, type +@kbd{M-y} repeatedly and, hopefully, you will find the chunk you want. + +Finally, in Insert and Replace states, Viper provides the history of +pieces of text inserted in previous insert or replace commands. These +strings of text can be recovered by repeatedly typing @kbd{C-c M-p} or +@kbd{C-c M-n} while in Insert or Replace state. (This feature is disabled +in the minibuffer: the above keys are usually bound to other histories, +which are more appropriate in the minibuffer.) + + +@cindex Meta key + +You can call Meta functions from Insert state. As in Vi state, the Meta key +is @kbd{C-\}. Thus @kbd{M-x} is typed as @kbd{C-\ x}. + +Other Emacs commands that are useful in Insert state are @kbd{C-e} +and @kbd{C-a}, which move the cursor to the end and the beginning of the +current line, respectively. You can also use @kbd{M-f} and @kbd{M-b}, +which move the cursor forward (or backward) one word. +If your display has a Meta key, these functions are invoked by holding the +Meta key and then typing @kbd{f} and @kbd{b}, respectively. On displays +without the Meta key, these functions are invoked by typing +@kbd{C-\ f} and @kbd{C-\ b} (@kbd{C-\} simulates the Meta key in Insert +state, as explained above). + +The key @kbd{C-z} is sometimes also useful in Insert state: it allows you +to execute a single command in Vi state without leaving the Insert state! +For instance, @kbd{C-z d2w} will delete the next two words without leaving +the Insert state. + +When Viper is in Insert state, you will see <I> in the mode line. + +@node Replace State,, Insert State, States in Viper +@subsection Replace State + +@cindex Replace state + +This state is entered through Vi replacement commands, such as @kbd{C}, +@kbd{cw}, etc., or by typing @kbd{R}. In Replace state, Viper puts <R> in +the mode line to let you know which state is in effect. If Replace state is +entered through @kbd{R}, Viper stays in that state until the user hits +@key{ESC}. If this state is entered via the other replacement commands, +then Replace state is in effect until you hit @key{ESC} or until you cross +the rightmost boundary of the replacement region. In the latter case, Viper +changes its state from Replace to Insert (which you will notice by the +change in the mode line). + +Since Viper runs under Emacs, it is possible to switch between buffers +while in Replace state. You can also move the cursor using the arrow keys +(even on dumb terminals!)@: and the mouse. Because of this freedom (which is +unattainable in regular Vi), it is possible to take the cursor outside the +replacement region. (This may be necessary for several reasons, including +the need to enable text selection and region-setting with the mouse.) + +The issue then arises as to what to do when the user +hits the @key{ESC} key. In Vi, this would cause the text between cursor and +the end of the replacement region to be deleted. But what if, as is +possible in Viper, the cursor is not inside the replacement region? + +To solve the problem, Viper keeps track of the last cursor position while it +was still inside the replacement region. So, in the above situation, Viper +would delete text between this position and the end of the replacement +region. + +@node The Minibuffer,Multiple Files in Viper, States in Viper, Overview +@section The Minibuffer + +@cindex Minibuffer + +The Minibuffer is where commands are entered in. Editing can be done +by commands from Insert state, namely: + +@table @kbd +@item C-h +Backspace +@item C-w +Delete Word +@item C-u +Erase line +@item C-v +Quote the following character +@item @key{RET} +Execute command +@item C-g and C-] +Emacs quit and abort keys. These may be necessary. @xref{Vi State}, for an +explanation. +@item M-p and M-n +These keys are bound to functions that peruse minibuffer history. The +precise history to be perused depends on the context. It may be the history +of search strings, Ex commands, file names, etc. +@end table + +Most of the Emacs keys are functional in the Minibuffer. While in the +Minibuffer, Viper tries to make editing resemble Vi's behavior when the +latter is waiting for the user to type an Ex command. In particular, you +can use the regular Vi commands to edit the Minibuffer. You can switch +between the Vi state and Insert state at will, and even use the replace mode. +Initially, the Minibuffer comes up in Insert state. + +Some users prefer plain Emacs bindings in the Minibuffer. To this end, set +@code{viper-vi-style-in-minibuffer} to @code{nil} in @file{.viper}. +@xref{Customization}, to learn how to do this. + +When the Minibuffer changes Viper states, you will notice that the appearance +of the text there changes as well. This is useful because the Minibuffer +has no mode line to tell which Vi state it is in. +The appearance of the text in the Minibuffer can be changed. +@xref{Viper Specials}, for more details. + +@node Multiple Files in Viper,Unimplemented Features,The Minibuffer,Overview +@section Multiple Files in Viper + +@cindex multiple files +@cindex managing multiple files + +Viper can edit multiple files. This means, for example that you never need +to suffer through @code{No write since last change} errors. +Some Viper elements are common over all the files. + +@table @samp +@item Textmarkers +@cindex markers +@cindex textmarkers +Textmarkers remember @emph{files and positions}. +If you set marker @samp{a} in +file @file{foo}, start editing file @file{bar} and type @kbd{'a}, then +@emph{YOU WILL SWITCH TO FILE @file{foo}}. You can see the contents of a +textmarker using the Viper command @kbd{[<a-z>} where <a-z> are the +textmarkers, e.g., @kbd{[a} to view marker @samp{a} .@refill +@item Repeated Commands +Command repetitions are common over files. Typing @kbd{!!} will repeat the +last @kbd{!} command whichever file it was issued from. +Typing @kbd{.} will repeat the last command from any file, and +searches will repeat the last search. Ex commands can be repeated by typing +@kbd{: @key{RET}}.@refill +Note: in some rare cases, that @kbd{: @key{RET}} may do something dangerous. +However, usually its effect can be undone by typing @kbd{u}. +@item Registers +@cindex registers +Registers are common to files. Also, text yanked with @kbd{y} can be +put back (@kbd{p}) into any file. The Viper command @kbd{]<a-z>}, where <a-z> are +the registers, can be used to look at the contents of a register, e.g., +type @kbd{]a} to view register @samp{a}. + +There is one difference in text deletion that you should be +aware of. This difference comes from Emacs and was adopted in Viper +because we find it very useful. In Vi, if you delete a line, say, and then +another line, these two deletions are separated and are put back +separately if you use the @samp{p} command. In Emacs (and Viper), successive +series of deletions that are @emph{not interrupted} by other commands are +lumped together, so the deleted text gets accumulated and can be put back +as one chunk. If you want to break a sequence of deletions so that the +newly deleted text could be put back separately from the previously deleted +text, you should perform a non-deleting action, e.g., move the cursor one +character in any direction. +@item Absolute Filenames +@cindex absolute paths +The current directory name for a file is automatically prepended to the +file name in any +@kbd{:e}, @kbd{:r}, @kbd{:w}, etc., command (in Emacs, each buffer has a +current directory). +This directory is inserted in the Minibuffer once you type space after +@kbd{:e, r}, etc. Viper also supports completion of file names and Ex +commands (@key{TAB}), and it keeps track of +command and file history (@kbd{M-p}, @kbd{M-n}). +Absolute filenames are required less +often in Viper. + +You should be aware that Emacs interprets @kbd{/foo/bar//bla} as +@kbd{/bla} and @kbd{/foo/~/bar} as @kbd{~/bar}. This is designed to +minimize the need for erasing path names that Emacs suggests in its +prompts, if a suggested path name is not what you wanted. + +The command @kbd{:cd} will change the default directory for the +current Emacs buffer. The Ex command @kbd{:e} will interpret the +filename argument in @samp{csh}, by default. @xref{Customization}, if you +want to change this. +@end table + +@noindent +Currently undisplayed files can be listed using the @kbd{:ar} command. The +command @kbd{:n} can be given counts from the @kbd{:ar} list to switch to +other files. + +@node Unimplemented Features,,Multiple Files in Viper,Overview +@section Unimplemented Features + +Unimplemented features include: + +@itemize @bullet +@item +@kbd{:ab} and @kbd{:una} are not implemented. +Both @kbd{:map} and @kbd{:ab} are considered obsolete, since Emacs has much +more powerful facilities for defining keyboard macros and abbreviations. +@item +@kbd{:set option?} is not implemented. The current +@kbd{:set} can also be used to set Emacs variables. +@item +@kbd{:se list} requires modification of the display code for Emacs, so +it is not implemented. +A useful alternative is @code{cat -t -e file}. Unfortunately, it cannot +be used directly inside Emacs, since Emacs will obdurately change @samp{^I} +back to normal tabs.@refill +@end itemize + +@comment node-name, next, previous, up +@node Improvements over Vi, Customization, Overview, Top +@chapter Improvements over Vi + +Some common problems with Vi and Ex have been solved in Viper. This +includes better implementation of existing commands, new commands, and +the facilities provided by Emacs. + +@menu +* Basics:: Basic Viper differences, Multi-file effects. +* Undo and Backups:: Multiple undo, auto-save, backups and changes +* History:: History for Ex and Vi commands. +* Macros and Registers:: Keyboard Macros (extended ".")@: @@reg execution. +* Completion:: Filename and Command Completion for Ex. +* Improved Search:: Incremental Search and Buffer Content Search. +* Abbreviation Facilities:: Normal Abbrevs, Templates, and Dynamic Abbrevs. +* Movement and Markers:: Screen Editor movements, viewing textmarkers. +* New Commands:: Commands that do not exist in Vi. +* Useful Packages:: A Sampling of some Emacs packages, and things + you should know about. +@end menu + +@node Basics, Undo and Backups, Improvements over Vi, Improvements over Vi +@section Basics + +The Vi command set is based on the idea of combining motion commands +with other commands. The motion command is used as a text region +specifier for other commands. +We classify motion commands into @dfn{point commands} and +@dfn{line commands}.@refill + +@cindex point commands + +The point commands are: + +@quotation +@kbd{h}, @kbd{l}, @kbd{0}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, +@kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, +@kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}, @kbd{^} +@end quotation + +@cindex line commands + +The line commands are: + +@quotation +@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, +@kbd{@}}, @kbd{G}, @kbd{'}, @kbd{[[}, @kbd{]]}, @kbd{[]} +@end quotation + +@cindex region +@cindex region specification +@cindex expanding (region) +@cindex describing regions +@cindex movement commands + +@noindent +If a point command is given as an argument to a modifying command, the +region determined by the point command will be affected by the modifying +command. On the other hand, if a line command is given as an argument to a +modifying command, the region determined by the line command will be +enlarged so that it will become the smallest region properly containing the +region and consisting of whole lines (we call this process @dfn{expanding +the region}), and then the enlarged region will be affected by the modifying +command. +Text Deletion Commands (@pxref{Deleting Text}), Change commands +(@pxref{Changing Text}), even Shell Commands (@pxref{Shell Commands}) +use these commands to describe a region of text to operate on. +Thus, type @kbd{dw} to delete a word, @kbd{>@}} to shift a paragraph, or +@kbd{!'afmt} to format a region from @samp{point} to textmarker +@samp{a}. + +@cindex r and R region specifiers + +Viper adds the region specifiers @samp{r} and @samp{R}. Emacs has a +special marker called @dfn{mark}. The text-area between the current cursor +position @dfn{point} and the @dfn{mark} is called the @dfn{region}. +@samp{r} specifies the raw region and @samp{R} is the expanded region +(i.e., the minimal contiguous chunk of full lines that contains the raw +region). +@kbd{dr} will now delete the region, @kbd{>r} will shift it, etc. +@kbd{r,R} are not motion commands, however. The special mark is set by +@kbd{m.} and other commands. @xref{Marking}, for more info. + +Viper also adds counts to most commands for which it would make sense. + +In the Overview chapter, some Multiple File issues were discussed +(@pxref{Multiple Files in Viper}). In addition to the files, Emacs has +buffers. These can be seen in the @kbd{:args} list and switched using +@kbd{:next} if you type @kbd{:set ex-cycle-through-non-files t}, or +specify @code{(setq ex-cycle-through-non-files t)} in your @file{.viper} +file. @xref{Customization}, for details. + +@node Undo and Backups, History, Basics, Improvements over Vi +@section Undo and Backups + +@cindex undo + +Viper provides multiple undo. The number of undo's and the size is limited +by the machine. The Viper command @kbd{u} does an undo. Undo can be +repeated by typing @kbd{.} (a period). Another @kbd{u} will undo the undo, +and further +@kbd{.} will repeat it. Typing @kbd{u} does the first undo, and changes the +direction. + +@cindex backup files +@cindex auto save + +Since the undo size is limited, Viper can create backup files and +auto-save files. It will normally do this automatically. It is possible +to have numbered backups, etc. For details, @pxref{Backup,,Backup and +Auto-Save,emacs,The GNU Emacs Manual} @refill + +@comment [ balance parens +@cindex viewing registers and markers +@cindex registers +@cindex markers +@cindex textmarkers + +The results of the 9 previous changes are available in the 9 numeric +registers, as in Vi. The extra goody is the ability to @emph{view} these +registers, in addition to being able to access them through @kbd{p} and +@kbd{M-y} (@xref{Insert State}, for details.) +The Viper command @kbd{] register} will display the contents of any +register, numeric or alphabetical. The related command @kbd{[ textmarker} +will show the text around the textmarker. @samp{register} and @samp{textmarker} +can be any letters from a through z. +@comment ] balance parens + +@node History, Macros and Registers, Undo and Backups,Improvements over Vi +@section History + +@cindex history +@cindex Minibuffer + +History is provided for Ex commands, Vi searches, file names, pieces of +text inserted in earlier commands that use Insert or Replace state, and for +destructive commands in Vi state. These are +useful for fixing those small typos that screw up searches and @kbd{:s}, +and for eliminating routine associated with repeated typing of file names +or pieces of text that need to be inserted frequently. +At the @kbd{:} or @kbd{/} prompts in the Minibuffer, you can do the following: + +@table @kbd +@item M-p and M-n +To move to previous and next history items. This causes the history +items to appear on the command line, where you can edit them, or +simply type Return to execute. +@item M-r and M-s +To search backward and forward through the history. +@item @key{RET} +Type @key{RET} to accept a default (which is displayed in the prompt). +@end table + +The history of insertions can be perused by +typing @kbd{C-c M-p} and @kbd{C-c M-n} while in Insert or Replace state. +The history of destructive Vi commands can be perused via the same keys +when Viper is in Vi state. @xref{Viper Specials}, for details. + +All Ex commands have a file history. For instance, typing @kbd{:e}, space +and then @kbd{M-p} will bring up the name of the previously typed file +name. Repeatedly typing @kbd{M-p}, @kbd{M-n}, etc., will let you browse +through the file history. + +Similarly, commands that have to do with switching buffers +have a buffer history, and commands that expect strings or regular +expressions keep a history on those items. + +@node Macros and Registers,Completion,History,Improvements over Vi +@section Macros and Registers + +@cindex keyboard macros +@cindex macros +@cindex registers +@cindex register execution + +Viper facilitates the use of Emacs-style keyboard macros. @kbd{@@#} will +start a macro definition. As you type, the commands will be executed, and +remembered (This is called ``learn mode'' in some editors.) +@kbd{@@register} will complete the macro, putting it into @samp{register}, +where @samp{register} is any character from @samp{a} through @samp{z}. Then +you can execute this macro using @kbd{@@register}. It is, of course, +possible to yank some text into a register and execute it using +@kbd{@@register}. Typing @kbd{@@@@}, @kbd{@@RET}, or @kbd{@@C-j} will +execute the last macro that was executed using @kbd{@@register}.@refill + +Viper will automatically lowercase the register, so that pressing the +@kbd{SHIFT} key for @kbd{@@} will not create problems. This is for +@kbd{@@} macros and @kbd{"p} @emph{only}. In the case of @kbd{y}, +@kbd{"Ayy} will append to @emph{register a}. For @kbd{[,],',`}, it +is an error to use a Uppercase register name. + +@comment [ balance parens +@cindex viewing registers and markers + +The contents of a register can be seen by @kbd{]register}. (@kbd{[textmarker} +will show the contents of a textmarker). +@comment ] balance parens + +@cindex last keyboard macro + +The last keyboard macro can also be executed using +@kbd{*}, and it can be yanked into a register using @kbd{@@!register}. +This is useful for Emacs style keyboard macros defined using @kbd{C-x(} +and @kbd{C-x)}. Emacs keyboard macros have more capabilities. +@xref{Keyboard Macros,,Keyboard Macros,emacs, The GNU Emacs Manual}, for +details.@refill + +Keyboard Macros allow an interesting form of Query-Replace: +@kbd{/pattern} or @kbd{n} to go to the next pattern (the query), followed by a +Keyboard Macro execution @kbd{@@@@} (the replace). + +Viper also provides Vi-style macros. @xref{Vi Macros}, for details. + + +@node Completion, Improved Search, Macros and Registers, Improvements over Vi +@section Completion + +@cindex completion + +Completion is done when you type @key{TAB}. The Emacs completer does not +grok wildcards in filenames. Once you type a wildcard, the completer will +no longer work for that path. Remember that Emacs interprets a file name +of the form @kbd{/foo//bar} as @kbd{/bar} and @kbd{/foo/~/bar} as +@kbd{~/bar}. + +@node Improved Search, Abbreviation Facilities, Completion, Improvements over Vi +@section Improved Search + +@cindex buffer search +@cindex word search + +Viper provides buffer search, the ability to search the buffer for a region +under the cursor. You have to turn this on in @file{.viper} either by calling + +@example +(viper-buffer-search-enable) +@end example + +@noindent +or by setting @code{viper-buffer-search-char} to, say, @kbd{f3}: +@example +(setq viper-buffer-search-char [f3]) +@end example + +@noindent +If the user calls @code{viper-buffer-search-enable} explicitly (the first +method), then @code{viper-buffer-search-char} will be set to @kbd{g}. +Regardless of how this feature is enabled, the key +@code{viper-buffer-search-char} will take movement commands, like +@kbd{w,/,e}, to find a region and then search for the contents of that +region. This command is very useful for searching for variable names, etc., +in a program. The search can be repeated by @kbd{n} or reversed by @kbd{N}. + +@cindex incremental search + +Emacs provides incremental search. As you type the string in, the +cursor will move to the next match. You can snarf words from the buffer +as you go along. Incremental Search is normally bound to @kbd{C-s} and +@kbd{C-r}. @xref{Customization}, to find out how to change the bindings +of @kbd{C-r or C-s}. +For details, @pxref{Incremental Search,,Incremental +Search,emacs,The GNU Emacs Manual} @refill + +@cindex query replace + +Viper also provides a query replace function that prompts through the +Minibuffer. It is invoked by the @kbd{Q} key in Vi state. + +@cindex mouse search + +On a window display, Viper supports mouse search, i.e., you can search for a +word by clicking on it. @xref{Viper Specials}, for details. + +Finally, on a window display, Viper highlights search patterns as it finds +them. This is done through what is known as @emph{faces} in Emacs. The +variable that controls how search patterns are highlighted is +@code{viper-search-face}. If you don't want any highlighting at all, put +@example +(copy-face 'default 'viper-search-face) +@end example +@vindex @code{viper-search-face} +@noindent +in @file{~/.viper}. If you want to change how patterns are highlighted, you +will have to change @code{viper-search-face} to your liking. The easiest +way to do this is to use Emacs customization widget, which is accessible +from the menubar. Viper customization group is located under the +@emph{Emulations} customization group, which in turn is under the +@emph{Editing} group. All Viper faces are grouped together under Viper's +@emph{Highlighting} group. + +Try it: it is really simple! + +@node Abbreviation Facilities,Movement and Markers,Improved Search,Improvements over Vi +@section Abbreviation Facilities + +@cindex abbrevs + +It is possible in Emacs to define abbrevs based on the contents of the +buffer. +Sophisticated templates can be defined using the Emacs abbreviation +facilities. @xref{Abbrevs,,Abbreviations,emacs,The GNU Emacs Manual}, for +details. + +@cindex dynamic abbrevs + +Emacs also provides Dynamic Abbreviations. Given a partial word, Emacs +will search the buffer to find an extension for this word. For instance, +one can type @samp{Abbreviations} by typing @samp{A}, followed by a keystroke +that completed the @samp{A} to @samp{Abbreviations}. Repeated typing +will search further back in the buffer, so that one could get +@samp{Abbrevs} by repeating the +keystroke, which appears earlier in the text. Emacs binds this to +@kbd{@key{ESC} /}, so you will have to find a key and bind the function +@code{dabbrev-expand} to that key. +Facilities like this make Vi's @kbd{:ab} command obsolete. + +@node Movement and Markers, New Commands, Abbreviation Facilities, Improvements over Vi +@section Movement and Markers + +@cindex Ex style motion +@cindex line editor motion + +Viper can be set free from the line--limited movements in Vi, such as @kbd{l} +refusing to move beyond the line, @key{ESC} moving one character back, +etc. These derive from Ex, which is a line editor. If your @file{.viper} +contains + +@example +@code{(setq viper-ex-style-motion nil)} +@end example + +@noindent +the motion will be a true screen editor motion. One thing you must then +watch out for is that it is possible to be on the end-of-line character. +The keys @kbd{x} and @kbd{%} will still work correctly, i.e., as if they +were on the last character. + +@vindex @code{viper-syntax-preference} +@cindex syntax table + +The word-movement commands @kbd{w}, @kbd{e}, etc., and the associated +deletion/yanking commands, @kbd{dw}, @kbd{yw}, etc., can be made to +understand Emacs syntax tables. If the variable +@code{viper-syntax-preference} is set to @code{strict-vi} then +the meaning of @emph{word} is the same as in +Vi. However, if the value is @code{reformed-vi} (the default) then the +alphanumeric symbols will be those specified by the current Emacs syntax +table (which may be different for different major modes) plus the +underscore symbol @kbd{_}, minus some non-word symbols, like '.;,|, etc. +Both @code{strict-vi} and @code{reformed-vi} work close to Vi in +traditional cases, but @code{reformed-vi} does a better job when editing +text in non-Latin alphabets. + +The user can also specify the value @code{emacs}, which would +make Viper use exactly the Emacs notion of word. In particular, the +underscore may not be part of a word. Finally, if +@code{viper-syntax-preference} is set to @code{extended}, Viper words would +consist of characters that are classified as alphanumeric @emph{or} as +parts of symbols. This is convenient for writing programs and in many other +situations. + +@code{viper-syntax-preference} is a local variable, so it can have different +values for different major modes. For instance, in programming modes it can +have the value @code{extended}. In text modes where words contain special +characters, such as European (non-English) letters, Cyrillic letters, etc., +the value can be @code{reformed-vi} or @code{emacs}. + +Changes to @code{viper-syntax-preference} should be done in the hooks to +various major modes by executing @code{viper-set-syntax-preference} as in +the following example: + +@example +(viper-set-syntax-preference nil "emacs") +@end example + +@findex @code{viper-set-syntax-preference} + +The above discussion of the meaning of Viper's words concerns only Viper's +movement commands. In regular expressions, words remain the same as in +Emacs. That is, the expressions @code{\w}, @code{\>}, @code{\<}, etc., use +Emacs' idea of what is a word, and they don't look into the value of +variable @code{viper-syntax-preference}. This is because Viper doesn't change +syntax tables in fear of upsetting the various major modes that set these +tables. + +@cindex textmarkers + +Textmarkers in Viper remember the file and the position, so that you can +switch files by simply doing @kbd{'a}. If you set up a regimen for using +Textmarkers, this is very useful. Contents of textmarkers can be viewed +by @kbd{[marker}. (Contents of registers can be viewed by @kbd{]register}). + +@node New Commands, Useful Packages, Movement and Markers, Improvements over Vi +@section New Commands + +These commands have no Vi analogs. + +@table @kbd +@item C-x, C-c +@kindex @kbd{C-x} +@kindex @kbd{C-c} +These two keys invoke many important Emacs functions. For example, if you +hit @kbd{C-x} followed by @kbd{2}, then the current window will be split +into 2. Except for novice users, @kbd{C-c} is also set to execute an Emacs +command from the current major mode. @key{ESC} will do the same, if you +configure @key{ESC} as Meta by setting @code{viper-no-multiple-ESC} to nil +in @file{.viper}. @xref{Customization}. @kbd{C-\} in Insert, Replace, or Vi +states will make Emacs think @kbd{Meta} has been hit.@refill +@item \ +@kindex @kbd{\} +Escape to Emacs to execute a single Emacs command. For instance, +@kbd{\ @key{ESC}} will act like a Meta key. +@item Q +@kindex @kbd{Q} +@cindex query replace +@kbd{Q} is for query replace. By default, +each string to be replaced is treated as a regular expression. You can use +@code{(setq viper-re-query-replace nil)} in your @file{.emacs} file to +turn this off. (For normal searches, @kbd{:se nomagic} will work. Note +that @kbd{:se nomagic} turns Regexps off completely, unlike Vi). +@item v +@itemx V +@itemx C-v +@kindex @kbd{v} +@kindex @kbd{V} +@kindex @kbd{C-v} +These keys are used to visit files. @kbd{v} will switch to a buffer +visiting file whose name can be entered in the Minibuffer. @kbd{V} is +similar, but will use a window different from the current window. +@kbd{C-v} is like @kbd{V}, except that a new frame (X window) will be used +instead of a new Emacs window. +@item # +@kindex @kbd{#} +If followed by a certain character @var{ch}, it becomes an operator whose +argument is the region determined by the motion command that follows +(indicated as <move>). +Currently, @var{ch} can be one of @kbd{c}, @kbd{C}, @kbd{g}, @kbd{q}, and +@kbd{s}. For instance, @kbd{#qr} will prompt you for a string and then +prepend this string to each line in the buffer.@refill +@item # c +@kindex @kbd{#c<move>} +@cindex changing case +Change upper-case characters in the region to lower-case +(@code{downcase-region}). +Emacs command @kbd{M-l} does the same for words. +@item # C +@kindex @kbd{#C<move>} +Change lower-case characters in the region to upper-case. For instance, +@kbd{# C 3 w} will capitalize 3 words from the current point +(@code{upcase-region}). +Emacs command @kbd{M-u} does the same for words. +@item # g +@kindex @kbd{#g<move>} +Execute last keyboard macro for each line in the region +(@code{viper-global-execute}).@refill +@item # q +@kindex @kbd{#q<move>} +Insert specified string at the beginning of each line in the region +(@code{viper-quote-region}). The default string is composed of the comment +character(s) appropriate for the current major mode. +@item # s +@kindex @kbd{#s<move>} +Check spelling of words in the region (@code{spell-region}). +The function used for spelling is determined from the variable +@code{viper-spell-function}. +@vindex @code{viper-spell-function} +@item * +@kindex @kbd{*} +Call last keyboard macro. +@item m . +Set mark at point and push old mark off the ring +@item m< +@item m> +Set mark at beginning and end of buffer, respectively. +@item m, +Jump to mark and pop mark off the ring. @xref{Mark,,Mark,emacs,The GNU +Emacs Manual}, for more info. +@item ] register +@kindex @kbd{]<a-z>} +View contents of register +@item [ textmarker +@kindex @kbd{[<a-z>} +View filename and position of textmarker +@item @@# +@item @@register +@item @@! +@kindex @kbd{@@#} +@kindex @kbd{@@<a-z>} +@kindex @kbd{@@!} +@cindex keyboard macros +@cindex register execution + +Begin/end keyboard macro. @@register has a different meaning when used after +a @kbd{@@#}. @xref{Macros and Registers}, for details +@item [] +@kindex @kbd{[]} +Go to end of heading. +@item g <@emph{movement command}> +Search buffer for text delimited by movement command. The canonical +example is @kbd{gw} to search for the word under the cursor. +@xref{Improved Search}, for details.@refill +@item C-g and C-] +@kindex @kbd{C-g} +@kindex @kbd{C-]} +Quit and Abort Recursive edit. These may be necessary on occasion. +@xref{Vi State}, for a reason. +@item C-c g +@kindex @kbd{C-c g} +Hitting @kbd{C-c} followed by @kbd{g} will display the information on the +current buffer. This is the same as hitting @kbd{C-g} in Vi, but, as +explained above, @kbd{C-g} is needed for other purposes in Emacs. +@item C-c / +@kindex @kbd{C-c /} +Without a prefix argument, this command toggles +case-sensitive/case-insensitive search modes and plain vanilla/regular +expression search. With the prefix argument 1, i.e., +@kbd{1 C-c /}, this toggles case-sensitivity; with the prefix argument 2, +toggles plain vanilla search and search using +regular expressions. @xref{Viper Specials}, for alternative ways to invoke +this function. +@cindex vanilla search +@cindex case-sensitive search +@cindex case-insensitive search + +@item M-p and M-n +@kindex @kbd{M-p} +@kindex @kbd{M-n} +In the Minibuffer, these commands navigate through the minibuffer +histories, such as the history of search strings, Ex commands, etc. + +@item C-c M-p and C-c M-n +@kindex @kbd{C-c M-p} +@kindex @kbd{C-c M-n} +@cindex Insertion history +@cindex Insertion ring +@cindex Command history +@cindex Command ring + +In Insert or Replace state, these commands let the user +peruse the history of insertion strings used in previous insert or replace +commands. Try to hit @kbd{C-c M-p} or @kbd{C-c M-n} repeatedly and see what +happens. @xref{Viper Specials}, for more. + +In Vi state, these commands let the user peruse the history of Vi-style +destructive commands, such as @kbd{dw}, @kbd{J}, @kbd{a}, etc. +By repeatedly typing @kbd{C-c M-p} or @kbd{C-c M-n} you will cycle Viper +through the recent history of Vi commands, displaying the commands one by +one. Once +an appropriate command is found, it can be executed by typing `@kbd{.}'. + +Since typing @kbd{C-c M-p} is tedious, it is more convenient to bind an +appropriate function to a function key on the keyboard and use that key. +@xref{Viper Specials}, for details. + +@item Ex commands +@findex @kbd{:args} +@findex @kbd{:n} +@findex @kbd{:pwd} +@findex @kbd{:pre} +The commands @kbd{:args}, @kbd{:next}, @kbd{:pre} behave +differently. @kbd{:pwd} exists to get current directory. +The commands @kbd{:b} and @kbd{:B} switch buffers around. @xref{File and +Buffer Handling}, for details. +There are also the new commands @kbd{:RelatedFile} and +@kbd{PreviousRelatedFile} (which abbreviate to @kbd{R} and @kbd{P}, +respectively. @xref{Viper Specials}, for details. +@findex @kbd{:RelatedFile} +@findex @kbd{:PreviousRelatedFile} +@end table + +Apart from the new commands, many old commands have been enhanced. Most +notably, Vi style macros are much more powerful in Viper than in Vi. @xref{Vi +Macros}, for details. + +@node Useful Packages, ,New Commands, Improvements over Vi +@section Useful Packages + +Some Emacs packages are mentioned here as an aid to the new Viper user, to +indicate what Viper is capable of. +A vast number comes with the standard Emacs distribution, and many more exist +on the net and on the archives. + +This manual also mentions some Emacs features a new user +should know about. The details of these are found in the GNU Emacs +Manual. + +The features first. For details, look up the Emacs Manual. + +@table @samp +@item Make +@cindex make +@cindex compiling + +Makes and Compiles can be done from the editor. Error messages will be +parsed and you can move to the error lines. +@item Shell +@cindex shell +@cindex interactive shell +You can talk to Shells from inside the editor. Your entire shell session +can be treated as a file. +@item Mail +@cindex email +@cindex mail +Mail can be read from and sent within the editor. Several sophisticated +packages exist. +@item Language Sensitive Editing +Editing modes are written for most computer languages in existence. By +controlling indentation, they catch punctuation errors. +@end table + +The packages, below, represents a drop in the sea of special-purpose +packages that come with standard distribution of Emacs. + +@table @samp +@item Transparent FTP +@cindex transparent ftp +@pindex ange-ftp.el +@code{ange-ftp.el} can ftp from the editor to files on other machines +transparent to the user. +@item RCS Interfaces +@cindex version maintenance +@cindex RCS +@pindex vc.el +@code{vc.el} for doing RCS commands from inside the editor +@item Directory Editor +@cindex dired +@pindex dired.el +@code{dired.el} for editing contents of directories and for navigating in +the file system. +@item Syntactic Highlighting +@cindex font-lock +@pindex font-lock.el +@code{font-lock.el} for automatic highlighting various parts of a buffer +using different fonts and colors. +@item Saving Emacs Configuration +@cindex desktop +@pindex desktop.el +@code{desktop.el} for saving/restoring configuration on Emacs exit/startup. +@item Spell Checker +@cindex ispell +@pindex ispell.el +@code{ispell.el} for spell checking the buffer, words, regions, etc. +@item File and Buffer Comparison +@cindex ediff +@pindex ediff.el +@code{ediff.el} for finding differences between files and for applying +patches. +@end table + +@noindent +Emacs Lisp archives exist on +@samp{archive.cis.ohio-state.edu} +and @samp{wuarchive.wustl.edu}@refill + + +@node Customization,Commands,Improvements over Vi,Top +@chapter Customization + +@cindex customization + +Customization can be done in 2 ways. + +@itemize @bullet +@item +@cindex initialization +@cindex .viper +Elisp code in a @file{.viper} file in your home directory. Viper +loads @file{.viper} just before it does the binding for mode +hooks. This is the recommended method. +@item +@cindex .emacs +Elisp code in your @file{.emacs} file before and after the @code{(require +'viper)} line. This method is not recommended, unless you know what you are +doing. Only two variables, @code{viper-mode} and +@code{viper-custom-file-name} are supposed to be customized in @file{.emacs}, +prior to loading Viper.@refill +@end itemize + +@noindent +Most of Viper's behavior can be customized via the interactive Emacs user +interface. Choose "Customize" from the menubar, click on "Editing", then on +"Emulations". The customization widget is self-explanatory. Once you are +satisfied with your changes, save them into a file and then include the +contents of that file in the Viper customization repository, @file{.viper} +(except for @code{viper-mode} and @code{viper-custom-file-name}, which are +supposed to go into @code{.emacs}). + +Some advanced customization cannot be accomplished this way, however, and +has to be done in Emacs Lisp. For the common cases, examples are provided +that you can use directly. + +@menu +* Rudimentary Changes:: Simple constant definitions. +* Keybindings:: Enabling Emacs Keys, Rebinding keys, etc. +* Packages that Change Keymaps:: How to deal with such beasts. +* Viper Specials:: Special Viper commands. +* Vi Macros:: How to do Vi style macros. +@end menu + +@node Rudimentary Changes,Keybindings,Customization,Customization +@section Rudimentary Changes + +@cindex setting variables +@cindex variables for customization +@findex @kbd{:set} + +An easy way to customize Viper is to change the values of constants used in +Viper. Here is the list of the constants used in Viper and their default +values. The corresponding :se command is also indicated. (The symbols +@code{t} and @code{nil} represent ``true'' and ``false'' in Lisp). + +Viper supports both the abbreviated Vi variable names and their full +names. Variable completion is done on full names only. @key{TAB} and +@key{SPC} complete +variable names. Typing `=' will complete the name and then will prompt for +a value, if applicable. For instance, @kbd{:se au @key{SPC}} will complete the +command to @kbd{:set autoindent}; @kbd{:se ta @key{SPC}} will complete the command +and prompt further like this: @kbd{:set tabstop = }. +However, typing @kbd{:se ts @key{SPC}} will produce a ``No match'' message +because @kbd{ts} is an abbreviation for @kbd{tabstop} and Viper supports +completion on full names only. However, you can still hit @key{RET} +or @kbd{=}, which will complete the command like this: @kbd{:set ts = } and +Viper will be waiting for you to type a value for the tabstop variable. +To get the full list of Vi variables, type @kbd{:se @key{SPC} @key{TAB}}. + +@table @code +@item viper-auto-indent nil +@itemx :se ai (:se autoindent) +@itemx :se ai-g (:se autoindent-global) +If @code{t}, enable auto indentation. +by @key{RET}, @kbd{o} or @kbd{O} command. + +@code{viper-auto-indent} is a local variable. To change the value globally, use +@code{setq-default}. It may be useful for certain major modes to have their +own values of @code{viper-auto-indent}. This can be achieved by using +@code{setq} to change the local value of this variable in the hooks to the +appropriate major modes. + +@kbd{:se ai} changes the value of @code{viper-auto-indent} in the current +buffer only; @kbd{:se ai-g} does the same globally. +@item viper-electric-mode t +If not @code{nil}, auto-indentation becomes electric, which means that +@key{RET}, @kbd{O}, and @kbd{o} indent cursor according to the current +major mode. In the future, this variable may control additional electric +features. + +This is a local variable: @code{setq} changes the value of this variable +in the current buffer only. Use @code{setq-default} to change the value in +all buffers. +@item viper-case-fold-search nil +@itemx :se ic (:se ignorecase) +If not @code{nil}, search ignores cases. +This can also be toggled by quickly hitting @kbd{/} twice. +@item viper-re-search nil +@itemx :se magic +If not @code{nil}, search will use regular expressions; if @code{nil} then +use vanilla search. +This behavior can also be toggled by quickly hitting @kbd{/} trice. +@item buffer-read-only +@itemx :se ro (:se readonly) +Set current buffer to read only. To change globally put +@code{(setq-default buffer-read-only t)} in your @file{.emacs} file. +@item blink-matching-paren t +@itemx :se sm (:se showmatch) +Show matching parens by blinking cursor. +@item tab-width t (default setting via @code{setq-default}) +@itemx :se ts=value (:se tabstop=value) +@itemx :se ts-g=value (:se tabstop-global=value) +@code{tab-width} is a local variable that controls the width of the tab stops. +To change the value globally, use @code{setq-default}; for local settings, +use @code{setq}. + +The command @kbd{:se ts} +sets the tab width in the current +buffer only; it has no effect on other buffers. + +The command @kbd{:se ts-g} sets tab width globally, +for all buffers where the tab is not yet set locally, +including the new buffers. + +Note that typing @key{TAB} normally +doesn't insert the tab, since this key is usually bound to +a text-formatting function, @code{indent-for-tab-command} (which facilitates +programming and document writing). Instead, the tab is inserted via the +command @code{viper-insert-tab}, which is bound to @kbd{S-tab} (shift + tab). + +On some non-windowing terminals, Shift doesn't modify the @key{TAB} key, so +@kbd{S-tab} behaves as if it were @key{TAB}. In such a case, you will have +to bind @code{viper-insert-tab} to some other convenient key. + +@item viper-shift-width 8 +@itemx :se sw=value (:se shiftwidth=value) +The number of columns shifted by @kbd{>} and @kbd{<} commands. +@item viper-search-wrap-around t +@itemx :se ws (:se wrapscan) +If not @code{nil}, search wraps around the end/beginning of buffer. +@item viper-search-scroll-threshold 2 +If search lands within this many lines of the window top or bottom, the +window will be scrolled up or down by about 1/7-th of its size, to reveal +the context. If the value is negative---don't scroll. +@item viper-tags-file-name "TAGS" +The name of the file used as the tag table. +@item viper-re-query-replace nil +If not @code{nil}, use reg-exp replace in query replace. +@item viper-want-ctl-h-help nil +If not @code{nil}, @kbd{C-h} is bound to @code{help-command}; +otherwise, @kbd{C-h} is bound as usual in Vi. +@item viper-vi-style-in-minibuffer t +If not @code{nil}, Viper provides a high degree of compatibility with Vi +insert mode when you type text in the Minibuffer; if @code{nil}, typing in +the Minibuffer feels like plain Emacs. +@item viper-no-multiple-ESC t +If you set this to @code{nil}, you can use @key{ESC} as Meta in Vi state. +Normally, this is not necessary, since graphical displays have separate +Meta keys (usually on each side of the space bar). On a dumb terminal, Viper +sets this variable to @code{twice}, which is almost like @code{nil}, except +that double @key{ESC} beeps. This, too, lets @key{ESC} to be used as a Meta. +@item viper-ESC-keyseq-timeout 200 on tty, 0 on windowing display +Escape key sequences separated by this much delay (in milliseconds) are +interpreted as command, ignoring the special meaning of @key{ESC} in +VI. The default is suitable for most terminals. However, if your terminal +is extremely slow, you might want to increase this slightly. You will know +if your terminal is slow if the @key{ESC} key sequences emitted by the +arrow keys are interpreted as separately typed characters (and thus the +arrow keys won't work). Making this value too large will slow you down, so +exercise restraint. +@item viper-fast-keyseq-timeout 200 +Key sequences separated by this many milliseconds are treated as Vi-style +keyboard macros. If the key sequence is defined as such a macro, it will be +executed. Otherwise, it is processed as an ordinary sequence of typed keys. + +Setting this variable too high may slow down your typing. Setting it too +low may make it hard to type macros quickly enough. +@item viper-ex-style-motion t +Set this to @code{nil}, if you want @kbd{l,h} to cross +lines, etc. @xref{Movement and Markers}, for more info. +@item viper-ex-style-editing t +Set this to to @code{nil}, if you want +@kbd{C-h} and @key{DEL} to not stop +at the beginning of a line in Insert state, @key{X} and @key{x} to delete +characters across lines in Vi command state, etc. +@item viper-ESC-moves-cursor-back t +It t, cursor moves back 1 character when switching from insert state to vi +state. If nil, the cursor stays where it was before the switch. +@item viper-always t +@code{t} means: leave it to Viper to decide when a buffer must be brought +up in Vi state, +Insert state, or Emacs state. This heuristics works well in virtually all +cases. @code{nil} means you either has to invoke @code{viper-mode} manually +for each buffer (or you can add @code{viper-mode} to the appropriate major mode +hooks using @code{viper-load-hook}). + +This option must be set in the file @file{~/.viper}. +@item viper-custom-file-name "~/.viper" +File used for Viper-specific customization. +Change this setting, if you want. Must be set in @file{.emacs} (not @file{.viper}!) +before Viper is loaded. Note that you +have to set it as a string inside double quotes. +@item viper-spell-function 'ispell-region +Function used by the command @kbd{#c<move>} to spell. +@item ex-nontrivial-find-file-function +The value of this variable is the function used to find all files that +match a wildcard. This is usually done when the user types @kbd{:e} and +specifies a wildcard in the file name (or if the file name contains unusual +symbols (e.g., a space). Viper provides two functions for this: one for +Unix-like systems (@code{viper-ex-nontrivial-find-file-unix}) and one for +DOS, W95, and NT (@code{viper-ex-nontrivial-find-file-ms}). If the default +function doesn't quite do what you expect or if you prefer to use ``fancy'' +shells, you may have to write your own version of this function and make it +into the value of @code{ex-nontrivial-find-file-function}. Use +@code{viper-ex-nontrivial-find-file-unix} and +@code{viper-ex-nontrivial-find-file-ms} as examples. +@vindex @code{ex-nontrivial-find-file-function}. +@findex @code{viper-ex-nontrivial-find-file-ms} +@findex @code{viper-ex-nontrivial-find-file-unix} +@item ex-cycle-other-window t +If not @code{nil}, @kbd{:n} and @kbd{:b} will cycle through files in another +window, if one exists. +@item ex-cycle-through-non-files nil +@kbd{:n} does not normally cycle through buffers. Set this to get +buffers also. +@item viper-want-emacs-keys-in-insert +This is set to @code{nil} for user levels 1 and 2 and to @code{t} for user +levels 3 and 4. Users who specify level 5 are allowed to set this variable +as they please (the default for this level is @code{t}). If set to +@code{nil}, complete Vi compatibility is provided in Insert state. This is +really not recommended, as this precludes you from using language-specific +features provided by the major modes. +@item viper-want-emacs-keys-in-vi +This is set to @code{nil} for user +level 1 and to @code{t} for user levels 2--4. +At level 5, users are allowed to set this variable as they please (the +default for this level is @code{t}). +If set to @code{nil}, complete Vi compatibility is provided +in Vi command state. Setting this to @code{nil} is really a bad idea, +unless you are a novice, as this precludes the use +of language-specific features provided by the major modes. +@item viper-keep-point-on-repeat t +If not @code{nil}, point is not moved when the user repeats the previous +command by typing `.' This is very useful for doing repeated changes with +the @kbd{.} key. +@item viper-repeat-from-history-key 'f12 +Prefix key used to invoke the macros @kbd{f12 1} and @kbd{f12 2} that repeat +the second-last and the third-last destructive command. +Both these macros are bound (as Viper macros) to +@code{viper-repeat-from-history}, +which checks the second key by which it is invoked to see which of the +previous commands to invoke. Viper binds @kbd{f12 1} and @kbd{f12 2} only, +but the user can bind more in @file{~/.viper}. @xref{Vi Macros}, for how to do +this. +@item viper-keep-point-on-undo nil +If not @code{nil}, Viper tries to not move point when undoing commands. +Instead, it will briefly move the cursor to the place where change has +taken place. However, if the undone piece of text is not seen in window, +then point will be moved to the place where the change took place. +Set it to @code{t} and see if you like it better. +@item viper-delete-backwards-in-replace nil +If not @code{nil}, @key{DEL} key will delete characters while moving the cursor +backwards. If @code{nil}, the cursor will move backwards without deleting +anything. +@item viper-replace-overlay-face 'viper-replace-overlay-face +On a graphical display, Viper highlights replacement regions instead of +putting a @samp{$} at the end. This variable controls the so called +@dfn{face} used to highlight the region. + +By default, @code{viper-replace-overlay-face} underlines the replacement on +monochrome displays and also lays a stipple over them. On color displays, +replacement regions are highlighted with color. + +If you know something about Emacs faces and don't like how Viper highlights +replacement regions, you can change @code{viper-replace-overlay-face} by +specifying a new face. (Emacs faces are described in the Emacs Lisp +reference.) On a color display, the following customization method is +usually most effective: +@example +(set-face-foreground viper-replace-overlay-face "DarkSlateBlue") +(set-face-background viper-replace-overlay-face "yellow") +@end example +For a complete list of colors available to you, evaluate the expression +@code{(x-defined-colors)}. (Type it in the buffer @code{*scratch*} and then +hit the @kbd{C-j} key. + +@item viper-replace-overlay-cursor-color "Red" +@vindex @code{viper-replace-overlay-cursor-color} +Cursor color when it is inside the replacement region. +This has effect only on color displays and only when Emacs runs as an X +application. +@item viper-insert-state-cursor-color nil +@vindex @code{viper-insert-state-cursor-color} +If set to a valid color, this will be the cursor color when Viper is in +insert state. +@item viper-replace-region-end-delimiter "$" +A string used to mark the end of replacement regions. It is used only on +TTYs or if @code{viper-use-replace-region-delimiters} is non-nil. +@item viper-replace-region-start-delimiter "" +A string used to mark the beginning of replacement regions. It is used +only on TTYs or if @code{viper-use-replace-region-delimiters} is non-nil. +@item viper-use-replace-region-delimiters +If non-nil, Viper will always use @code{viper-replace-region-end-delimiter} and +@code{viper-replace-region-start-delimiter} to delimit replacement regions, +even on color displays (where this is unnecessary). By default, this +variable is non-nil only on TTYs or monochrome displays. +@item viper-allow-multiline-replace-regions t +If non-nil, multi-line text replacement regions, such as those produced by +commands @kbd{c55w}, @kbd{3C}, etc., will stay around until the user exits +the replacement mode. In this variable is set to @code{nil}, Viper will +emulate the standard Vi behavior, which supports only intra-line +replacement regions (and multi-line replacement regions are deleted). +@item viper-toggle-key "\C-z" +Specifies the key used to switch from Emacs to Vi and back. +Must be set in @file{.viper}. This variable can't be +changed interactively after Viper is loaded. + +In Insert state, this key acts as a temporary escape to Vi state, i.e., it +will set Viper up so that the very next command will be executed as if it +were typed in Vi state. +@item viper-ESC-key "\e" +Specifies the key used to escape from Insert/Replace states to Vi. +Must be set in @file{.viper}. This variable cannot be +changed interactively after Viper is loaded. +@item viper-buffer-search-char nil +Key used for buffer search. @xref{Viper Specials}, for details. +@item viper-surrounding-word-function 'viper-surrounding-word +The value of this variable is a function name that is used to determine +what constitutes a word clicked upon by the mouse. This is used by mouse +search and insert. +@item viper-search-face 'viper-search-face +Variable that controls how search patterns are highlighted when they are +found. +@item viper-vi-state-hook nil +List of parameterless functions to be run just after entering the Vi +command state. +@item viper-insert-state-hook nil +Same for Insert state. This hook is also run after entering Replace state. +@item viper-replace-state-hook nil +List of (parameterless) functions called just after entering Replace state +(and after all @code{viper-insert-state-hook}). +@item viper-emacs-state-hook nil +List of (parameterless) functions called just after switching from Vi state +to Emacs state. +@item viper-load-hook nil +List of (parameterless) functions called just after loading Viper. This is +the last chance to do customization before Viper is up and running. +@end table +@noindent +You can reset some of these constants in Viper with the Ex command @kbd{:set} +(when so indicated in the table). Or you +can include a line like this in your @file{.viper} file: +@example +(setq viper-case-fold-search t) +@end example +@vindex @code{viper-auto-indent} +@vindex @code{viper-electric-mode} +@vindex @code{viper-case-fold-search} +@vindex @code{viper-re-search} +@vindex @code{viper-shift-width} +@vindex @code{buffer-read-only} +@vindex @code{viper-search-wrap-around} +@vindex @code{viper-search-scroll-threshold} +@vindex @code{viper-search-face} +@vindex @code{viper-tags-file-name} +@vindex @code{viper-re-query-replace} +@vindex @code{viper-want-ctl-h-help} +@vindex @code{viper-vi-style-in-minibuffer} +@vindex @code{viper-no-multiple-ESC} +@vindex @code{viper-always} +@vindex @code{viper-ESC-keyseq-timeout} +@vindex @code{viper-fast-keyseq-timeout} +@vindex @code{viper-ex-style-motion} +@vindex @code{viper-ex-style-editing} +@vindex @code{viper-ESC-moves-cursor-back} +@vindex @code{viper-custom-file-name} +@vindex @code{viper-spell-function} +@vindex @code{ex-cycle-other-window} +@vindex @code{ex-cycle-through-non-files} +@vindex @code{viper-want-emacs-keys-in-insert} +@vindex @code{viper-want-emacs-keys-in-vi} +@vindex @code{viper-keep-point-on-repeat} +@vindex @code{viper-keep-point-on-undo} +@vindex @code{viper-delete-backwards-in-replace} +@vindex @code{viper-replace-overlay-face} +@vindex @code{viper-replace-region-end-symbol} +@vindex @code{viper-replace-region-start-symbol} +@vindex @code{viper-allow-multiline-replace-regions} +@vindex @code{viper-toggle-key} +@vindex @code{viper-ESC-key} +@vindex @code{viper-buffer-search-char} +@vindex @code{viper-surrounding-word-function} +@vindex @code{viper-vi-state-hook} +@vindex @code{viper-insert-state-hook} +@vindex @code{viper-replace-state-hook} +@vindex @code{viper-emacs-state-hook} + +@node Keybindings, Packages that Change Keymaps, Rudimentary Changes,Customization +@section Keybindings + +@cindex keybindings +@cindex keymaps + +Viper lets you define hot keys, i.e., you can associate keyboard keys +such as F1, Help, PgDn, etc., with Emacs Lisp functions (that may already +exist or that you will write). Each key has a "preferred form" in +Emacs. For instance, the Up key's preferred form is [up], the Help key's +preferred form is [help], and the Undo key has the preferred form [f14]. +You can find out the preferred form of a key by typing @kbd{M-x +describe-key-briefly} and then typing the key you want to know about. + +Under X Windows, every keyboard key emits its preferred form, so you can +just type + +@lisp +(global-set-key [f11] 'calendar) ; L1, Stop +(global-set-key [f14] 'undo) ; L4, Undo +@end lisp + +@noindent +to bind L1 so it will invoke the Emacs Calendar and to bind L4 so it will +undo changes. +However, on a dumb terminal or in an Xterm window, even the standard arrow +keys may +not emit the right signals for Emacs to understand. To let Emacs know about +those keys, you will have to find out which key sequences they emit +by typing @kbd{C-q} and then the key (you should switch to Emacs state +first). Then you can bind those sequences to their preferred forms using +@code{function-key-map} as follows: + +@lisp +(cond ((string= (getenv "TERM") "xterm") +(define-key function-key-map "\e[192z" [f11]) ; L1 +(define-key function-key-map "\e[195z" [f14]) ; L4, Undo +@end lisp + +The above illustrates how to do this for Xterm. On VT100, you would have to +replace "xterm" with "vt100" and also change the key sequences (the same +key may emit different sequences on different types of terminals). + +The above keys are global, so they are overwritten by the local maps +defined by the major modes and by Viper itself. Therefore, if you wish to +change a binding set by a major mode or by Viper, read this. + +Viper users who wish to specify their own key bindings should be concerned +only with the following three keymaps: +@code{viper-vi-global-user-map} for Vi state commands, +@code{viper-insert-global-user-map} for Insert state commands, +and @code{viper-emacs-global-user-map} for Emacs state commands (note: +customized bindings for Emacs state made to @code{viper-emacs-global-user-map} +are @emph{not} inherited by Insert state). + +For more information on Viper keymaps, see the header of the file +@file{viper.el}. +If you wish to change a Viper binding, you can use the +@code{define-key} command, to modify @code{viper-vi-global-user-map}, +@code{viper-insert-global-user-map}, and @code{viper-emacs-global-user-map}, as +explained below. Each of these key maps affects the corresponding Viper state. +The keymap @code{viper-vi-global-user-map} also affects Viper's Replace state. + +@noindent +If you want to +bind a key, say @kbd{C-v}, to the function that scrolls +page down and to make @kbd{0} display information on the current buffer, +putting this in @file{.viper} will do the trick in Vi state: +@example +(define-key viper-vi-global-user-map "\C-v" 'scroll-down) +@end example +@noindent +To set a key globally, +@example +(define-key viper-emacs-global-user-map "\C-c m" 'smail) +(define-key viper-vi-global-user-map "0" 'viper-info-on-file) +@end example +@noindent +Note, however, that this binding may be overwritten by other keymaps, since +the global keymap has the lowest priority. +To make sure that nothing will override a binding in Emacs state, you +can write this: +@example +(define-key viper-emacs-global-user-map "\C-c m" 'smail) +@end example +@noindent +To customize the binding for @kbd{C-h} in Insert state: +@example +(define-key viper-insert-global-user-map "\C-h" 'my-del-backwards-function) +@end example +@noindent + +Each Emacs command key calls some lisp function. If you have enabled the +Help, (@pxref{Rudimentary Changes}) @kbd{C-h k} will show you the function +for each specific key; @kbd{C-h b} will show all bindings, and @kbd{C-h m} +will provide information on the major mode in effect. If Help is not +enabled, you can still get help in Vi state by prefixing the above commands +with @kbd{\}, e.g., @kbd{\ C-h k} (or you can use the Help menu in the +menu bar, if Emacs runs under X Windows). + +Viper users can also change bindings on a per major mode basis. As with +global bindings, this can be done separately for each of the three main Viper +states. To this end, Viper provides the function +@code{viper-modify-major-mode}. +@findex @code{viper-modify-major-mode} + +To modify keys in Emacs state for @code{my-favorite-major-mode}, the user +needs to create a sparse keymap, say, @code{my-fancy-map}, bind whatever +keys necessary in that keymap, and put + +@example +(viper-modify-major-mode 'dired-mode 'emacs-state my-fancy-map) +@end example + +@noindent +in @file{~/.viper}. To do the same in Vi and Insert states, you should use +@code{vi-state} and @code{insert-state}. Changes in Insert state are also +in effect in Replace state. For instance, suppose that the user wants to +use @kbd{dd} in Vi state under Dired mode to delete files, @kbd{u} to unmark +files, etc. The following code in @file{~/.viper} will then do the job: + +@example +(setq my-dired-modifier-map (make-sparse-keymap)) +(define-key my-dired-modifier-map "dd" 'dired-flag-file-deletion) +(define-key my-dired-modifier-map "u" 'dired-unmark) +(viper-modify-major-mode 'dired-mode 'vi-state my-dired-modifier-map) +@end example + +A Vi purist may want to modify Emacs state under Dired mode so that +@kbd{k}, @kbd{l}, etc., will move around in directory buffers, as in +Vi. Although this is not recommended, as these keys are bound to useful +Dired functions, the trick can be accomplished via the following code: + +@example +(setq my-dired-vi-purist-map (make-sparse-keymap)) +(define-key my-dired-vi-purist-map "k" 'viper-previous-line) +(define-key my-dired-vi-purist-map "l" 'viper-forward-char) +(viper-modify-major-mode 'dired-mode 'emacs-state my-dired-vi-purist-map) +@end example + +Yet another way to customize key bindings in a major mode is to edit the +list @code{viper-major-mode-modifier-list} using the customization widget. +@vindex @code{viper-major-mode-modifier-list} +(This variable is in the Viper-misc customization group.) +The elements of this list are triples of the form: (major-mode viper-state +keymap), where the keymap contains bindings that are supposed to be active +in the given major mode and the given viper-state. + +Effects similar to key binding changes can be achieved by defining Vi +keyboard macros using the Ex commands @kbd{:map} and @kbd{:map!}. The +difference is that multi-key Vi macros do not override the keys they are +bound to, unless these keys are typed in quick succession. So, with macros, +one can use the normal keys alongside with the macros. If per-mode +modifications are needed, the user can try both ways and see which one is +more convenient. +@findex @kbd{:map} +@xref{Vi Macros}, for details. + +Note: in major modes that come up in @emph{Emacs state} by default, the +aforesaid modifications may not take place immediately (but only after the +buffer switches to some other Viper state and then back to Emacs state). To +avoid this, one should add @code{viper-change-state-to-emacs} to an +appropriate hook of that major mode. (Check the function +@code{viper-set-hooks} in @file{viper.el} for examples.) However, if you +have set @code{viper-always} to @code{t}, chances are that you won't need to +perform the above procedure, because Viper will take care of most useful +defaults. + + +Finally, Viper has a facility that lets the user define per-buffer +bindings, i.e., bindings that are in effect in some specific buffers +only. Unlike per-mode bindings described above, per-buffer bindings can be +defined based on considerations other than the major mode. This is done +via the function @code{viper-add-local-keys}, which lets one specify bindings +that should be in effect in the current buffer only and for a specific Viper +state. For instance, +@lisp +(viper-add-local-keys 'vi-state '(("ZZ" .@: TeX-command-master) + ("ZQ" .@: viper-save-kill-buffer))) +@end lisp +@noindent +redefines @kbd{ZZ} to invoke @code{TeX-command-master} in @code{vi-state} +and @kbd{ZQ} to save-then-kill the current buffer. These bindings take +effect only in the buffer where this command is executed. The typical use +of this function is to execute the above expression from within a function +that is included in a hook to some major mode. For instance, the above +expression +could be called from a function, @code{my-tex-init}, which may be added to +@code{tex-mode-hook} as follows: +@lisp +(add-hook 'tex-mode-hook 'my-tex-init) +@end lisp +@noindent +When TeX mode starts, the hook is executed and the above Lisp expression is +evaluated. Then, the bindings for @kbd{ZZ} and @kbd{ZQ} are changed in Vi +command mode for all buffers in TeX mode. + +Another useful application is to bind @kbd{ZZ} to @code{send-mail} +in the Mail mode buffers (the specifics of this depend on which mail +package you are using, @code{rmail}, @code{mh-e}, @code{vm}, etc. +For instance, here is how to do this for @code{mh-e}, the Emacs interface +to MH: +@lisp +(defun mh-add-vi-keys () + "Set up ZZ for MH-e and XMH." + (viper-add-local-keys 'vi-state '(("ZZ" .@: mh-send-letter)))) +(add-hook 'mh-letter-mode-hook 'mh-add-vi-keys) +@end lisp + +You can also use @code{viper-add-local-keys} to set per buffer +bindings in Insert state and Emacs state by passing as a parameter the +symbols @code{insert-state} and @code{emacs-state}, respectively. +As with global bindings, customized local bindings done to Emacs state +are not inherited by Insert state. + +On rare occasions, local keys may be added by mistake. Usually this is done +indirectly, by invoking a major mode that adds local keys (e.g., +@code{shell-mode} redefines @key{RET}). In such a case, exiting the wrong +major mode won't rid you from unwanted local keys, since these keys are +local to Viper state and the current buffer, not to the major mode. +In such situations, the remedy is to type @kbd{M-x viper-zap-local-keys}. + +So much about Viper-specific bindings. +@xref{Customization,,Customization,emacs,The GNU Emacs +Manual}, and the Emacs quick reference card for the general info on key +bindings in Emacs. + +@vindex @code{function-key-map} +@vindex @code{viper-vi-global-user-map} +@vindex @code{viper-insert-global-user-map} +@vindex @code{viper-emacs-global-user-map} +@findex @code{viper-add-local-keys} +@findex @code{viper-zap-local-keys} + +@node Packages that Change Keymaps,Viper Specials,Keybindings,Customization +@subsection Packages that Change Keymaps +@cindex C-c and Viper +@cindex Viper and C-c + +Viper is designed to coexist with all major and minor modes of Emacs. This +means that bindings set by those modes are generally available with Viper +(unless you explicitly prohibit them by setting +@code{viper-want-emacs-keys-in-vi} and @code{viper-want-emacs-keys-in-insert} to +@code{nil}). +If @code{viper-always} is set to @code{t}, Viper will try to bring each buffer +in the Viper state that is most appropriate for that buffer. +Usually, this would be the Vi state, but sometimes it could be the Insert +state or the Emacs state. + +Some major mode bindings will necessarily be overwritten by Viper. Indeed, in +Vi state, most of the 1-character keys are used for Vi-style editing. This +usually causes no problems because most packages designed for editing files +typically do not bind such keys. Instead, they use key sequences that start +with @kbd{C-x} and @kbd{C-c}. This is why it was so important for us to +free up @kbd{C-x} and @kbd{C-c}. +It is common for language-specific major modes to bind @key{TAB} and +@kbd{C-j} (the line feed) keys to various formatting functions. This is +extremely useful, but may require some getting used to for a Vi user. If you +decide that this feature is not for you, you can re-bind these keys as +explained earlier (@pxref{Customization}). + +Binding for @key{TAB} is one of the most unusual aspects of Viper for many +novice users. In Emacs, @key{TAB} is used to format text and programs, and +is extremely useful. For instance, hitting @key{TAB} causes the current +line to be re-indented in accordance with the context. In programming, +this is very important, since improper automatic indentation would +immediately alert the programmer to a possible error. For instance, if a +@kbd{)} or a @kbd{"} is missing somewhere above the current +line, @key{TAB} is likely to mis-indent the line. + +For this reason, Viper doesn't change the standard Emacs binding of +@key{TAB}, thereby sacrificing Vi compatibility +(except for users at level 1). Instead, in Viper, the key +@kbd{S-tab} (shift+ tab) is chosen to emulate Vi's @key{TAB}. + +We should note that on some non-windowing terminals, Shift doesn't modify +the @key{TAB} key, so @kbd{S-tab} behaves as if it were @key{TAB}. In such +a case, you will have to bind @code{viper-insert-tab} to some other +convenient key. + +Some packages, notably Dired, Gnus, Info, etc., attach special meaning to +common keys like @key{SPC}, @kbd{x}, @kbd{d}, @kbd{v}, and others. This +means that Vi command state is inappropriate for working with these +packages. Fortunately, these modes operate on read-only buffers and are +designed not for editing files, but for special-purpose browsing, reading +news, mail, etc., and Vi commands are meaningless in these situations. For +this reason, Viper doesn't force Vi state on such major modes---it +brings them in Emacs state. You can switch to Vi state by typing @kbd{C-z} +if, for instance, you want to do Vi-style search in a buffer (although, +usually, incremental search, which is bound to @kbd{C-s}, is sufficient in +these situations). But you should then switch back to Emacs state if you +plan to continue using these major modes productively. You can also switch +to Vi temporarily, to execute just one command. This is done by typing +@kbd{C-c \}. (In some of these modes, @kbd{/} and @kbd{:} are bound +Vi-style, unless these keys perform essential duties.) + +If you would like certain major modes to come up in Emacs state rather than +Vi state (but Viper thinks otherwise), you should put these major modes +on the @code{viper-emacs-state-mode-list} list and delete them from +@code{viper-vi-state-mode-list}. +Likewise, you can force Viper's Insert state on a major mode by putting it +in @code{viper-insert-state-mode-list}. +@vindex @code{viper-emacs-state-mode-list} +@vindex @code{viper-insert-state-mode-list} +@vindex @code{viper-vi-state-mode-list} + +It is also possible to impose Vi on some major modes, even though they may +bind common keys to specialized commands. This might make sense for modes +that bind only a small number of common keys. For instance, Viper subverts +the Shell mode by changing the bindings for @kbd{C-m} and @kbd{C-d} using +@code{viper-add-local-keys} described in section on customization +(@pxref{Customization}). + +In some cases, some @emph{minor} modes might override certain essential +bindings in Vi command state. This is not a big priblem because this +can happen only in the beginning, when the minor mode kicks in. Typing +@code{M-x viper-mode} will correct the situation. Viper knows about +several such minor modes and takes care of them, so the above trick +is usually not necessary. If you find that some minor mode, e.g., +@code{nasty-mode.el} interferes with Viper, putting the following in +@file{.viper} should fix the problem: +@lisp +(viper-harness-minor-mode "nasty-mode") +@end lisp +@noindent +The argument to @code{viper-harness-minor-mode} is the name of the file for the +offending minor mode with the suffixes @file{.el} and @file{.elc} removed. + +It may not be always obvious which minor mode is at fault. The only +guidance here is to look into the file that defines the minor mode you are +suspecting, say @code{nasty-mode.el}, and see if it has a variable called +@code{nasty-mode-map}. Then check if there is a statement of the form +@lisp +(define-key nasty-mode-map key function) +@end lisp +@noindent +that binds the misbehaving +keys. If so, use the above line to harness @code{nasty-mode}. If your +suspicion is wrong, no harm is done if you harness a minor mode that +doesn't need to be harnessed. + +@vindex @code{viper-want-emacs-keys-in-vi} +@vindex @code{viper-want-emacs-keys-in-insert} +@vindex @code{viper-always} +@findex @code{viper-set-hooks} +@findex @code{viper-mode} +@findex @code{viper-harness-minor-mode} +@findex @code{remove-hook} +@findex @code{add-hook} + +@node Viper Specials,Vi Macros,Packages that Change Keymaps,Customization +@section Viper Specials + +Viper extends Vi with a number of useful features. This includes various +search functions, histories of search strings, Ex commands, insertions, and +Vi's destructive commands. In addition, Viper supports file name completion +and history, completion of Ex commands and variables, and many other +features. Some of these features are explained in detail elsewhere in this +document. Other features are explained here. + +@table @code +@item (viper-buffer-search-enable) +@item viper-buffer-search-char nil +Enable buffer search. Explicit call to @code{viper-buffer-search-enable} +sets @code{viper-buffer-search-char} to @kbd{g}. Alternatively, the user can +set @code{viper-buffer-search-char} in @file{.viper} to a key sequence +to be used for buffer search. There is no need to call +@code{viper-buffer-search-enable} in that case. +@findex @code{viper-buffer-search-enable} +@vindex @code{viper-buffer-search-char} +@item viper-toggle-search-style +This function, bound to @kbd{C-c /}, lets one toggle case-sensitive and +case-insensitive search, and also switch between plain vanilla search and +search via regular expressions. Without the prefix argument, the user is +asked which mode to toggle. With prefix argument 1, this toggles +case-sensitivity. With prefix argument 2, regular expression/vanilla search +will be toggled. + +However, we found that the most convenient way to toggle +these options is to bind a Vi macro to +bind @kbd{//} to toggles case sensitivity and to @kbd{///} to toggles +vanilla search. Thus, quickly hitting @kbd{/} twice will switch Viper from +case sensitive search to case-insensitive. Repeating this once again will +restore the original state. Likewise, quickly hitting @kbd{/} three times +will switch you from vanilla-style search to search via regular expressions. +If you hit something other than @kbd{/} after the first @kbd{/} or if the +second @kbd{/} doesn't follow quickly enough, then Viper will issue the +usual prompt @kbd{/} and will wait for input, as usual in Vi. +If you don't like this behavior, you can ``unrecord'' these macros in your +@file{~/.viper} file. For instance, if you don't like the above feature, put +this in @file{~/.viper}: +@example +(viper-set-searchstyle-toggling-macros 'undefine) +@end example +@findex @code{viper-set-searchstyle-toggling-macros} + +@item Vi-isms in Emacs state +Some people find it useful to use the Vi-style search key, `/', to invoke +search in modes which Viper leaves in emacs-state. These modes are: +@code{dired-mode}, @code{mh-folder-mode}, @code{gnus-group-mode}, +@code{gnus-summary-mode}, @code{Info-mode}, and @code{Buffer-menu-mode} +(more may be added in the future). So, in the above modes, Viper binds `/' +so that it will behave Vi-style. Furthermore, in those major modes, Viper +binds `:' to invoke ex-style commands, like in vi-state. And, as described +above, `//' and `///' get bound to Vi-style macros that toggle +case-insensitivity and regexp-search. + +If you don't like these features---which I don't really understand---you +can unbind `/' and `:' in @code{viper-dired-modifier-map} (for Dired) or in +@code{viper-slash-and-colon-map}, for other modes. +@vindex @code{viper-slash-and-colon-map} +@vindex @code{viper-dired-modifier-map} + +To unbind the macros `//' and `///' for a major mode where you feel they +are undesirable, execute @code{viper-set-emacs-state-searchstyle-macros} with a +non-nil argument. This can be done either interactively, by supplying a +prefix argument, or by placing +@example +(viper-set-emacs-state-searchstyle-macros 'undefine) +@end example +@findex @code{viper-set-emacs-state-searchstyle-macros} +in the hook to the major mode (e.g., @code{dired-mode-hook}). +@xref{Vi Macros}, for more information on Vi macros. + +@item viper-heading-start +@item viper-heading-end +@cindex headings +@cindex sections +@cindex paragraphs +@cindex sentences +Regular Expressions for @kbd{[[} and @kbd{]]}. Note that Emacs defines +Regexps for paragraphs and sentences. @xref{Paragraphs,,Paragraphs and +Sentences,emacs,The GNU Emacs Manual}, for details. +@item M-x viper-set-expert-level +@findex @code{viper-set-expert-level} +Change your user level interactively. +@item viper-smart-suffix-list '("" "tex" "c" "cc" "el" "p") +@vindex @code{viper-smart-suffix-list} +Viper supports Emacs-style file completion when it prompts the user for a +file name. However, in many cases, the same directory may contain files +with identical prefix but different suffixes, e.g., prog.c, prog.o, +paper.tex, paper.dvi. In such cases, completion will stop at the `.'. +If the above variable is a list of strings representing suffixes, Viper will +try these suffixes +in the order listed and will check if the corresponding file exists. + +For instance, if completion stopped at `paper.'@: and the user typed +@key{RET}, +then Viper will check if the files `paper.', `paper.tex', `paper.c', etc., exist. +It will take the first such file. If no file exists, Viper will give a chance +to complete the file name by typing the appropriate suffix. If `paper.'@: was +the intended file name, hitting return will accept it. + +To turn this feature off, set the above variable to @code{nil}. + +@item viper-insertion-ring-size 14 +@vindex @code{viper-insertion-ring-size} +@cindex Insertion ring +Viper remembers what was previously inserted in Insert and Replace states. +Several such recent insertions are kept in a special ring of strings of size +@code{viper-insertion-ring-size}. +If you enter Insert or Replace state you can reinsert strings from this +ring by typing @kbd{C-c M-p} or @kbd{C-c M-n}. The former will search the +ring in +the direction of older insertions, and the latter will search in +the direction of newer insertions. Hitting @kbd{C-c M-p} or @kbd{C-c M-n} +in succession +will undo the previous insertion from the ring and insert the next item on +the ring. If a larger ring size is needed, change the value of the above +variable in the @file{~/.viper} file. + +Since typing these sequences of keys may be tedious, it is suggested that the +user should bind a function key, such as @kbd{f31}, as follows: +@example +(define-key viper-insert-global-user-map [f31] + 'viper-insert-prev-from-insertion-ring) +@end example +This binds @kbd{f31} (which is usually @kbd{R11} on a Sun workstation) +to the function that inserts the previous string in the insertion history. +To rotate the history in the opposite +direction, you can either bind an unused key to +@code{viper-insert-next-from-insertion-ring} or hit any digit (1 to 9) then +@kbd{f31}. + +One should not bind the above functions to @kbd{M-p} or @kbd{M-n}, since +this will interfere with the Minibuffer histories and, possibly, other +major modes. + +@item viper-command-ring-size 14 +@vindex @code{viper-command-ring-size} +@cindex Destructive command ring +@cindex Destructive command history +Viper keeps track of the recent history of destructive +commands, such as @kbd{dw}, @kbd{i}, etc. +In Vi state, +the most recent command can be re-executed by hitting `@kbd{.}', as in Vi. +However, repeated typing @kbd{C-c M-p} will cause Viper to show the +previous destructive commands in the minibuffer. Subsequent hitting `@kbd{.}' +will execute the command that was displayed last. +The key @kbd{C-c M-n} will cycle through the command history in the +opposite direction. +Since typing @kbd{C-c M-p} may be tedious, it is more convenient to bind an +appropriate function to an unused function key on the keyboard and use that +key. For instance, the following +@example +(define-key viper-vi-global-user-map [f31] + 'viper-prev-destructive-command) +@end example +binds the key @kbd{f31} (which is usually @kbd{R11} on a Sun workstation) +to the function that searches the command history in the direction of older +commands. To search in the opposite +direction, you can either bind an unused key to +@code{viper-next-destructive-command} or hit any digit (1 to 9) then @kbd{f31}. + +One should not bind the above functions to @kbd{M-p} or @kbd{M-n}, since +this will interfere with the Minibuffer histories and, possibly, other +major modes. + +@item viper-minibuffer-vi-face 'viper-minibuffer-vi-face +@item viper-minibuffer-insert-face 'viper-minibuffer-insert-face +@item viper-minibuffer-emacs-face 'viper-minibuffer-emacs-face +These faces control the appearance of the minibuffer text in the +corresponding Viper states. You can change the appearance of these faces +through Emacs' customization widget, which is accessible through the +menubar. + +Viper is located in this widget under the @emph{Emulations} customization +subgroup of the @emph{Editing} group. All Viper faces are grouped together +in Viper's @emph{Highlighting} customization subgroup. + +Note that only the text you type in is affected by the above faces. +Prompts and Minibuffer messages are not affected. + +Purists who do not like adornments in the minibuffer can always zap them by +putting +@example +(copy-face 'default 'viper-minibuffer-vi-face) +(copy-face 'default 'viper-minibuffer-insert-face) +(copy-face 'default 'viper-minibuffer-emacs-face) +@end example +in the @file{~/.viper} file or through the customization widget, as +described above. However, in that case, the user will not have any +indication of the current Viper state in the minibuffer. (This is important +if the user accidentally switches to another Viper state by typing @key{ESC} or +@kbd{C-z}). +@item M-x viper-go-away +@findex @code{viper-go-away} +Make Viper disappear from the face of your running Emacs instance. If your +fingers start aching again, @kbd{M-x viper-mode} might save your day. +@item M-x toggle-viper-mode +@findex @code{toggle-viper-mode} +Toggle Viperization of Emacs on and off. +@end table + +@cindex Multifile documents and programs + +Viper provides some support for multi-file documents and programs. +If a document consists of several files we can designate one of them as a +master and put the following at the end of that file: +@lisp +;;; Local Variables: +;;; eval: (viper-setup-master-buffer "file1" "file2" "file3" "file5" "file5") +;;; End: +@end lisp +@noindent +where @code{file1} to @code{file5} are names of files related to the master +file. Next time, when the master file is visited, the command +@code{viper-setup-master-buffer} will be evaluated and the above files will +be associated with the master file. Then, the new Ex command +@kbd{:RelatedFile} (abbr.@: @kbd{:R}) will display files 1 to 5 one after +another, so you can edit them. If a file is not in any Emacs buffer, it +will be visited. The command @kbd{PreviousRelatedFile} (abbr., @kbd{:P}) +goes through the file list in the opposite direction. +@findex @kbd{:RelatedFile} +@findex @kbd{:PreviousRelatedFile} + +These commands are akin to @kbd{:n} and @kbd{:N}, but they allow the user to +focus on relevant files only. + +Note that only the master file needs to have the aforementioned block of +commands. Also, ";;;" above can be replaced by some other +markers. Semicolon is good for Lisp programs, since it is considered a +comment designator there. For LaTeX, this could be "%%%", and for C the +above block should be commented out. + +Even though these commands are sometimes useful, they are no substitute for +the powerful @emph{tag table} facility of Emacs. Viper's @kbd{:tag} command +in a primitive interface to Emacs tags. @xref{Tags,Tags,Tags,emacs, +The Gnu Emacs Manual}, for more information on tags. + +The following two commands are normally bound to a mouse click and are part +of Viper. They work only if Emacs runs as an application under X +Windows (or under some other window system for which a port of GNU Emacs 20 +is available). Clicking the mouse when Emacs is invoked in an Xterm window +(using @code{emacs -nw}) will do no good. + +@table @code +@cindex mouse +@cindex mouse-search +@item viper-mouse-search-key (meta shift 1) +@vindex @code{viper-mouse-insert-key} +This variable controls the @emph{mouse-search} feature of Viper. The +default value +states that holding Meta and Shift keys while clicking mouse button 1 +should initiate search for a region under the mouse pointer (defined +below). This command can take a prefix argument, which indicates the +occurrence of the pattern to search for. + +Note: while loading initially, Viper binds this mouse action only if it is +not already bound to something else. If you want to use the mouse-search +feature and the Meta-Shift-button-1 mouse action is already bound to +something else you can rebind the mouse-search feature by setting +@code{viper-mouse-search-key} to something else in your @code{~/.viper} +file: +@lisp +(setq viper-mouse-search-key '(meta 1)) +@end lisp +This would bind mouse search to the action invoked by pressing the +Meta key and clicking mouse button 1. The allowed values of +@code{viper-mouse-search-key} are lists that contain a mouse-button number +(1,2, or 3) and any combination of the words `control', `meta', and +`shift'. + +If the requested mouse action (e.g., (meta 1)) is already taken for other +purposes then you have to confirm your intention by placing the following +command in @code{~/.viper} after setting @code{viper-mouse-search-key}: +@lisp +(viper-bind-mouse-search-key 'force) +@end lisp + +You can also change this setting interactively, through the customization +widget of Emacs (choose option "Customize.Customize Group" from the +menubar). + +The region that is chosen as a pattern to search for is determined as +follows. If search is invoked via a single click, Viper chooses the region +that lies between the beginning of the ``word'' under the pointer (``word'' +is understood in Vi sense) and the end of that word. The only difference +with Vi's words is that in Lisp major modes `-' is considered an +alphanumeric symbol. This is done for the convenience of working with Lisp +symbols, which often have an `-' in them. Also, if you click on a +non-alphanumeric character that is not a word separator (in Vi sense) then +this character will also be considered alphanumeric, provided that it is +adjacent (from either side) to an alphanumeric character. This useful +feature gives added control over the patterns selected by the mouse click. + +On a double-click, the region is determined by the beginning of the current +Vi's ``Word'' (i.e., the largest non-separator chunk of text) and the End +of that ``Word'' (as determined by the @kbd{E} command). + +On a triple-click, the region consists of the entire line where the click +occurred with all leading and trailing spaces and tabs removed. + +@cindex mouse-insert +@item viper-mouse-insert-key (meta shift 2) +@vindex @code{viper-mouse-insert-key} +This variable controls the @emph{mouse-insert} feature of Viper. +The above default value states that +holding Meta and Shift keys while clicking mouse button 2 +should insert the region surrounding the +mouse pointer. The rules defining this region are the same as for +mouse-search. This command takes an optional prefix argument, which +indicates how many such regions to snarf from the buffer and insert. (In +case of a triple-click, the prefix argument is ignored.) + +Note: while loading initially, Viper binds this mouse action only if it not +already bound to something else. If you want to use this feature and the +default mouse action is already bound, you can rebind mouse-insert by +placing this command in @code{~/.viper}: +@lisp +(setq viper-mouse-insert-key '(meta 2)) +@end lisp +If you want to bind mouse-insert to an action even if this action is +already taked for other purposes in Emacs, then you should add this command +to @code{~/.viper}, after setting @code{viper-mouse-insert-key}: +@lisp +(viper-bind-mouse-insert-key 'force) +@end lisp + +This value can also be changed via the Emacs customization widget at the +menubar. + +@item viper-multiclick-timeout +This variable controls the rate at which double-clicking must occur for the +purpose of mouse search and mouse insert. By default, this is set to +@code{double-click-time}. +@end table +@kindex @kbd{S-mouse-1} +@kindex @kbd{S-mouse-2} +@kindex @kbd{meta shift button1up} +@kindex @kbd{meta shift button2up} +@vindex @code{viper-multiclick-timeout} +@findex @code{viper-mouse-click-insert-word} +@findex @code{viper-mouse-click-search-word} + +Note: The above functions search and insert in the selected window of +the latest active frame. This means that you can click in another window or +another frame and have search or insertion done in the frame and window you +just left. This lets one use these functions in a multi-frame +configuration. However, this may require some getting used to. For +instance, if you are typing in a frame, A, and then move the mouse to frame +B and click to invoke mouse search, search (or insertion) will be performed +in frame A. To perform search/insertion in frame B, you will first have to +shift focus there, which doesn't happen until you type a character or +perform some other action in frame B---mouse search doesn't shift focus. + +If you decide that you don't like the above feature and always want +search/insertion be performed in the frame where the click occurs, don't +bind (and unbind, if necessary) @code{viper-mouse-catch-frame-switch} from +the mouse event it is bound to. + +Mouse search is integrated with Vi-style search, so you can +repeat it with @kbd{n} and @kbd{N}. It should be also noted that, while +case-sensitivity of search in Viper is controlled by the variable +@code{viper-case-fold-search}, the case of mouse search is +controlled by the Emacs variable @code{case-fold-search}, which may be set +differently from @code{viper-case-fold-search}. Therefore, case-sensitivity +of mouse search may be different from that of the usual Vi-style search. + +Finally, if the way Viper determines the word to be searched for or to be +inserted is not what you want, there is a variable, +@code{viper-surrounding-word-function}, which can be changed to indicate +another function for snarfing words out of the buffer. The catch is that +you will then have to write such a function and make it known to your +Emacs. The function @code{viper-surrounding-word} in @file{viper.el} can be +used as a guiding example. + +@node Vi Macros, ,Viper Specials,Customization +@section Vi Macros + +@cindex Vi macros + +Viper supports much enhanced Vi-style macros and also facilitates the use +of Emacs-style macros. To define a temporary macro, it is generally more +convenient to use Emacs keyboard macro facility. Emacs keyboard macros are +usually defined anonymously, and the latest macro can be executed by typing +@kbd{C-x e} (or @kbd{*}, if Viper is in Vi state). If you need to use several +temporary macros, Viper lets you save them to a +register (a lowercase letter); such macros can then be executed by typing +@kbd{@@a} in Vi state (if a macro was previously saved in register +@kbd{a}). +@xref{Macros and Registers}, for details. + +If, however, you need to use a macro regularly, it must be given a +permanent name and saved. Emacs manual explains how to do this, but +invocation of named Emacs macros is quite different from Vi's. First, +invocation of permanent Emacs macros takes time because of the extra keys. +Second, binding such macros to function keys, for +fast access, hogs valuable real estate on the keyboard. + +Vi-style macros are better in that respect, since Vi lets the user overload +the meaning of key sequences: keys typed in fast succession are treated +specially, if this key sequence is bound to a macro. + +Viper provides keyboard macros through the usual Ex commands, @kbd{:map} and +@kbd{:map!}. Vi-style macros are much more powerful in Viper than +they are in the original Vi and in other emulators. This is because Viper +implements an enhanced vi-style +interface to the powerful Emacs keyboard macro facility. + +First, any Emacs +command can be executed while defining a macro, not just the Vi +commands. In particular, the user can invoke Emacs commands via @kbd{M-x +command-name} or by pressing various function keys on the keyboard. One +can even use the mouse, although this is usually not useful and is not +recommended (and macros defined with the use of the mouse cannot be saved in +command history and in the startup file, for future use). + +Macros defined by mixing Vi and Emacs commands are represented as +vectors. So, don't be confused when you see one (usually through the +history of Ex commands). For instance, if @kbd{gg} is defined by typing +@kbd{l}, the up-arrow key and @kbd{M-x next-line}, its definition will look +as follows in Emacs: + +@example +[l up (meta x) n e x t - l i n e return] +@end example + +Second, Viper macros are defined in a WYSIWYG style. This means that +commands are executed as you type them, so you can see precisely what is +being defined. Third, macros can be bound to arbitrary sequences of keys, +not just to printable keys. For instance, one can define a macro that will +be invoked by hitting @kbd{f3} then @kbd{f2} function keys. (The keys +@kbd{delete} and @kbd{backspace} are excluded; also, a macro invocation +sequence can't start with @key{ESC}. Some other keys, such as @kbd{f1} and +@kbd{help}, can't be bound to macros under Emacs, since they +are bound in @code{key-translation-map}, which overrides any other binding +the user gives to keys. In general, keys that have a binding in +@code{key-translation-map} can't be bound to a macro.) + +Fourth, in Viper, one can define macros that are specific to a given +buffer, a given major mode, or macros that are defined for all buffers. In +fact, the same macro name can have several different definitions: one +global, several definitions for various major modes, and +definitions for various specific buffers. Buffer-specific definitions +override mode-specific definitions, which, in turn, override global +definitions. + +As if all that is not enough, Viper (through its interface to Emacs +macros) lets the user define keyboard macros that ask for confirmation or +even prompt the user for input and then continue. To do this, one should +type @kbd{C-x q} (for confirmation) or @kbd{C-u C-x q} (for prompt). +For details, @pxref{Kbd Macro Query,,Customization,emacs,The GNU Emacs +Manual} @refill + +When the user finishes defining a macro (which is done by typing @kbd{C-x)} --- +a departure from Vi), you will be asked whether you want this +macro to be global, mode-specific, or buffer-specific. You will also be +given a chance to save the macro in your @file{~/.viper} file. +This is the easiest way to save a macro and make +it permanently available. If you work your startup files with bare hands, +here is how Viper saves the above macro so that it will be +available in Viper's Insert state (and Replace state) in buffer @code{my-buf} +only: + +@example +(viper-record-kbd-macro "gg" 'insert-state + [l up (meta x) n e x t - l i n e return] + "my-buf") +@end example + +@noindent +To do the same for Vi state and all buffers with the major mode +@code{cc-mode}, use: + +@example +(viper-record-kbd-macro "gg" 'vi-state + [l up (meta x) n e x t - l i n e return] + 'cc-mode) +@end example + +@noindent +Both macro names and macro definitions are vectors of symbols that denote +keys on the keyboard. Some keys, like @kbd{\}, @kbd{ }, or digit-keys must +be escaped with a backslash. Modified keys are represented as lists. For +instance, holding Meta and Control and pressing @kbd{f4} is represented as +@kbd{(control meta f4)}. +If all members of a vectors are printable characters (or sequences, such as +@kbd{\e}, @kbd{\t}, for @key{ESC} and @key{TAB}), then they can also be represented as +strings: + +@example +(viper-record-kbd-macro "aa" 'vi-state "aaa\e" "my-buffer") +@end example + +@noindent +Thus, typing @kbd{aa} fast in Vi state will switch Viper to Insert state +(due to the first @kbd{a}), insert @kbd{aa}, and then it will switch back to Vi +state. All this will take effect only in the buffer named @code{my-buffer}. + +Note that the last argument to @code{viper-record-kbd-macro} must be either a +string (a buffer name), a symbol representing a major mode, or @code{t}; +the latter says that the macro is to be defined for all buffers +(which is how macros are defined in original Vi). + +For convenience, Viper also lets you define Vi-style macros in its Emacs +state. There is no Ex command, like @kbd{:map} and @kbd{:map!} for doing +this, but the user can include such a macro in the @file{~/.viper} file. The +only thing is that the @code{viper-record-kbd-macro} command should specify +@code{emacs-state} instead of @code{vi-state} or @code{insert-state}. + +The user can get rid of a macro either by using the Ex commands @kbd{:unmap} +and @kbd{:unmap!} or by issuing a call to @code{viper-unrecord-kbd-macro}. +The latter is more powerful, since it can delete macros even in +@code{emacs-state}. However, @code{viper-unrecord-kbd-macro} is usually +needed only when the user needs to get rid of the macros that are already +predefined in Viper. +The syntax is: +@findex @code{viper-unrecord-kbd-macro} +@example +(viper-unrecord-kbd-macro macro state) +@end example +@noindent +The second argument must be @code{vi-state}, @code{insert-state}, or +@code{emacs-state}. The first argument is a name of a macro. To avoid +mistakes in specifying names of existing macros, type @kbd{M-x +viper-describe-kbd-macros} and use a name from the list displayed by this +command. + +If an error occurs during macro definition, Emacs +aborts the process, and it must be repeated. This is analogous to Vi, +except that in Vi the user doesn't know there is an error until the macro is +actually run. All that means that in order for a definition to be +successful, the user must do some simple planning of the process in +advance, to avoid errors. For instance, if you want to map @kbd{gg} to +@kbd{llll} in Vi state, you must make sure that there is enough room on the +current line. Since @kbd{l} moves the cursor forward, it may signal an +error on reaching the end of line, which will abort the definition. + +These precautions are necessary only when defining macros; they will help +avoid the need to redo the job. When macros are actually run, an error +during the execution will simply terminate the current execution +(but the macro will remain mapped). + +A macro name can be a string of characters or a vector of keys. +The latter makes it possible to define macros bound to, say, double-hits +on a function key, such as @kbd{up} or @kbd{f13}. +This is very useful if you run out of function keys on your keyboard; it +makes Viper macro facility a @emph{keyboard doubler}, so to speak. + +Elsewhere (@xref{Keybindings}, for details), we review +the standard Emacs mechanism for binding function keys to commands. +For instance, + +@example +(global-set-key [f13] 'repeat-complex-command) +@end example + +@noindent +binds the key f13 to the Emacs function that repeats the last minibuffer +command. Under Viper, however, you may still use this key for additional +purposes, if you bind, say, a double-hitting action for that key to some +other function. Emacs doesn't allow the user to do that, but Viper does +this through its keyboard macro facility. To do this, type @kbd{:map } +first. When you are asked to enter a macro name, hit f13 twice, followed by +@key{RET} or @key{SPC}. + +Emacs will now start the mapping process by actually executing +Vi and Emacs commands, so that you could see what will happen each time the +macro is executed. Suppose now we wanted to bind the key sequence +@kbd{f13 f13} to the command @code{eval-last-sexp}. To accomplish this, we +can type @kbd{M-x eval-last-sexp} followed by @kbd{C-x )}. +If you answer positively to Viper's offer to save this macro in @file{~/.viper} +for future uses, the following will be inserted in that file: + +@example +(viper-record-kbd-macro [f16 f16] 'vi-state + [(meta x) e v a l - l a s t - s e x p] + 'lisp-interaction-mode) +@end example + +To illustrate the above point, Viper provides two canned macros, which, by +default, are bound to @kbd{[f12 \1]} and @kbd{[f12 \2]} (invoked by typing +@kbd{f12} then @kbd{1} and @kbd{2}, respectively). These macros are useful +shortcuts to Viper's command ring history. The first macro will execute the +second-last destructive command (the last one is executed by @kbd{.}, as +usual). The second macro executes the third-last command. + +If you need to go deeper into the command history, you will have to use +other commands, as described earlier in this section; or you can bind, +say, @kbd{f12 \3} like this: + +@example +(viper-record-kbd-macro [f12 \3] 'vi-state + [(meta x) r e p e a t - f r o m - h i s t o r y] + t) +@end example + + +Note that even though the macro uses the function key @kbd{f12}, the key is +actually free and can still be bound to some Emacs function via +@code{define-key} or @code{global-set-key}. + + +Viper allows the user to define macro names that are prefixes of other macros. +For instance, one can define @kbd{[[} and @kbd{[[[[} to be macros. +If you type the exact sequence of such keys and then pause, Viper will +execute the right macro. However, if you don't pause and, say, type +@kbd{[[[[text} then the conflict is resolved as follows. If only one of the +key sequences, @kbd{[[} or @kbd{[[[[} has a definition applicable to the +current buffer, then, in fact, there is no conflict and the right macro +will be chosen. If both have applicable definitions, then the first one +found will be executed. Usually this is the macro with a shorter name. So, +in our case, @kbd{[[[[text} will cause the macro @kbd{[[} to be executed +twice and then the remaining keys, @kbd{t e x t}, will be processed. + +When defining macros using @kbd{:map} or @kbd{:map!}, the user enters the +actually keys to be used to invoke the macro. For instance, you should hit +the actual key @kbd{f6} if it is to be part of a macro name; you do +@emph{not} write `f 6'. When entering keys, Viper displays them as strings or +vectors (e.g., "abc" or [f6 f7 a]). The same holds for unmapping. Hitting +@key{TAB} while typing a macro name in the @kbd{:unmap} or @kbd{:unmap!} command +will cause name completion. Completions are displayed as strings or vectors. +However, as before, you don't actually type ``"'', ``['', or ``]'' that +appear in the completions. These are meta-symbols that indicate whether +the corresponding macro name is a vector or a string. + +One last difference from Vi: Vi-style keyboard macros cannot be defined in +terms of other Vi-style keyboard macros (but named Emacs macros are OK). +More precisely, while defining or executing a macro, the special meaning +of key sequences (as Vi macros) is ignored. +This is because it is all too easy to create an infinite loop in this way. +Since Viper macros are much more powerful than Vi's it is impossible to +detect such loops. In practice, this is not really a limitation but, +rather, a feature. + +We should also note that Vi macros are disabled in the Minibuffer, which +helps keep some potential troubles away. + +The rate at which the user must type keys in order for them to be +recognized as a timeout macro is controlled by the variable +@code{viper-fast-keyseq-timeout}, which defaults to 200 milliseconds. + +For the most part, Viper macros defined in @file{~/.viper} can be shared +between X and TTY modes. +The problem with TTY may be that the function keys there generate sequences +of events instead of a single event (as under a window system). +Emacs maps some of these sequences back to the logical keys +(e.g., the sequences generated by the arrow keys are mapped to @kbd{up}, +@kbd{left}, etc.). However, not all function keys are mapped in this way. +Macros that are bound to key sequences that contain such unmapped function +keys have to be redefined for TTY's (and possibly for every type of TTY you +may be using). To do this, start Emacs on an appropriate TTY device and +define the macro using @kbd{:map}, as usual. + +@findex @code{viper-describe-kbd-macros} +Finally, Viper provides a function that conveniently displays all macros +currently defined. To see all macros along with their definitions, type +@kbd{M-x viper-describe-kbd-macros}. + +@node Commands,,Customization,Top +@chapter Commands + +This section is a semi-automatically bowdlerized version of the Vi +reference created by @* @samp{maart@@cs.vu.nl} and others. It can be +found on the Vi archives. This reference has been adapted for Viper.@refill + +@menu +* Groundwork:: Textual Conventions and Viper basics +* Text Handling:: Moving, Editing, Undoing. +* Display:: Scrolling. +* File and Buffer Handling:: Editing, Writing and Quitting. +* Mapping:: Mapping Keys, Keyboard Macros +* Shell Commands:: Accessing Shell Commands, Processing Text +* Options:: Ex options, the @kbd{:set} commands +* Emacs Related Commands:: Meta Keys, Windows +* Mouse-bound Commands:: Search and insertion of text +@end menu + +@node Groundwork, Text Handling, Commands, Commands +@comment node-name, next, previous, up +@section Groundwork + +The VI command set is based on the idea of combining motion commands +with other commands. The motion command is used as a text region +specifier for other commands. +We classify motion commands into @dfn{point commands} and +@dfn{line commands}.@refill + +@cindex point commands + +The point commands are: + +@quotation +@kbd{h}, @kbd{l}, @kbd{0}, @kbd{$}, @kbd{w}, @kbd{W}, @kbd{b}, @kbd{B}, +@kbd{e}, @kbd{E}, @kbd{(}, @kbd{)}, @kbd{/}, @kbd{?}, @kbd{`}, @kbd{f}, +@kbd{F}, @kbd{t}, @kbd{T}, @kbd{%}, @kbd{;}, @kbd{,}, @kbd{^} +@end quotation + +@cindex line commands + +The line commands are: + +@quotation +@kbd{j}, @kbd{k}, @kbd{+}, @kbd{-}, @kbd{H}, @kbd{M}, @kbd{L}, @kbd{@{}, +@kbd{@}}, @kbd{G}, @kbd{'}, @kbd{[[}, @kbd{]]}, @kbd{[]} +@end quotation +@noindent + +Text Deletion Commands (@pxref{Deleting Text}), Change commands +(@pxref{Changing Text}), even Shell Commands (@pxref{Shell Commands}) +use these commands to describe a region of text to operate on. + +@cindex r and R region specifiers + +Viper adds two region descriptors, @kbd{r} and @kbd{R}. These describe +the Emacs regions (@pxref{Basics}), but they are not movement commands. + +The command description uses angle brackets @samp{<>} to indicate +metasyntactic variables, since the normal conventions of using simple +text can be confusing with Viper where the commands themselves are +characters. Watch out where @kbd{<} shift commands and @kbd{<count>} are +mentioned together!!! + +@kindex <move> +@kindex <a-z> +@kindex <address> +@cindex <move> +@cindex <a-z> +@cindex <address> +@cindex movements + +@samp{<move>} refers to the above movement commands, and @samp{<a-z>} +refers to registers or textmarkers from @samp{a} to @samp{z}. Note +that the @samp{<move>} is described by full move commands, that is to +say they will take counts, and otherwise behave like normal move commands. +@cindex Ex addresses +@samp{<address>} refers to Ex line addresses, which include + +@table @kbd +@item .@: <No address> +Current line +@item .+n .-n +Add or subtract for current line +@item number +Actual line number, use @kbd{.=} to get the line number +@item '<a-z> +Textmarker +@item $ +Last line +@item x,y +Where x and y are one of the above +@item % +@cindex % (Ex address) +For the whole file, same as (1,$). +@item /<pat>/ +@itemx ?<pat>? +Next or previous line with pattern <pat>. + +Note that the pattern is allowed to contain newline character (inserted as +@kbd{C-qC-j}). Therefore, one can search for patterns that span several +lines. +@end table + +@cindex % (Current file) +Note that @samp{%} is used in Ex commands to mean current file. If you +want a @samp{%} in your command, it must be escaped as @samp{\%}. +@cindex # (Previous file) +Similarly, @samp{#} expands to the previous file. The previous file is +the first file in @kbd{:args} listing. This defaults to previous window +in the VI sense if you have one window only. + +@kindex <args> +@kindex <cmd> +@cindex <args> +@cindex <cmd> +@noindent +Others like @samp{<args> -- arguments}, @samp{<cmd> -- command} etc. +should be fairly obvious. + +@noindent +Common characters referred to include: + +@table @kbd +@item <sp> +Space +@item <ht> +Tab +@item <lf> +Linefeed +@item <esc> +Escape +@item <cr> +Return, Enter +@end table +@cindex <cr> +@cindex <esc> +@cindex <lf> +@cindex <ht> +@cindex <sp> + +@cindex words +@cindex WORDS +@cindex char +@cindex CHAR + +We also use @samp{word} for alphanumeric/non-alphanumeric words, and +@samp{WORD} for whitespace delimited words. @samp{char} refers to any +ASCII character, @samp{CHAR} to non-whitespace character. +Brackets @samp{[]} indicate optional parameters; @samp{<count>} also +optional, usually defaulting to 1. Brackets are elided for +@samp{<count>} to eschew obfuscation. + +Viper's idea of Vi's words is slightly different from Vi. First, Viper +words understand Emacs symbol tables. Therefore, all symbols declared to be +alphanumeric in a symbol table can automatically be made part of the Viper +word. This is useful when, for instance, editing text containing European, +Cyrillic, Japanese, etc., texts. + +Second, Viper lets you depart from Vi's idea of a word by changing the a +syntax preference via the customization widget (the variable +@code{viper-syntax-preference}) or by executing +@code{viper-set-syntax-preference} interactively. + +By default, Viper syntax preference is @code{reformed-vi}, which means that +Viper considers only those symbols to be part of a word that are specified +as word-symbols by the current Emacs syntax table (which may be different +for different major modes) plus the underscore symbol @kbd{_}, minus the +symbols that are not considered words in Vi (e.g., `,',;, etc.), but may be +considered as word-symbols by various Emacs major modes. Reformed-Vi works +very close to Vi, and it also recognizes words in other +alphabets. Therefore, this is the most appropriate mode for editing text +and is likely to fit all your needs. + +You can also set Viper syntax preference to @code{strict-vi}, which would +cause Viper to view all non-English letters as non-word-symbols. + +You can also specify @code{emacs} as your preference, which would +make Viper use exactly the same notion of a word as Emacs does. In +particular, the underscore may not be part of a word in some major modes. + +Finally, if @code{viper-syntax-preference} is set to @code{extended}, Viper +words would consist of characters that are classified as alphanumeric +@emph{or} as parts of symbols. This is convenient for editing programs. + +@code{viper-syntax-preference} is a local variable, so it can have different +values for different major modes. For instance, in programming modes it can +have the value @code{extended}. In text modes where words contain special +characters, such as European (non-English) letters, Cyrillic letters, etc., +the value can be @code{reformed-vi} or @code{emacs}. +If you consider using different syntactic preferences for different major +modes, you should execute, for example, + +@example +(viper-set-syntax-preference nil "extended") +@end example + +in the appropriate major mode hooks. + +@vindex @code{viper-syntax-preference} +@findex @code{viper-set-syntax-preference} +@cindex syntax table + + + +The above discussion concerns only the movement commands. In regular +expressions, words remain the same as in Emacs. That is, the expressions +@code{\w}, @code{\>}, @code{\<}, etc., use Emacs' idea of what is a word, +and they don't look into the value of variable +@code{viper-syntax-preference}. This is because Viper avoids changing +syntax tables in order to not thwart the various major modes that set these +tables. + +The usual Emacs convention is used to indicate Control Characters, i.e +C-h for Control-h. @emph{Do not confuse this to mean the separate +characters C - h!!!} The @kbd{^} is itself, never used to indicate a +Control character. + +Finally, we note that Viper's Ex-style commands can be made to work on the +current Emacs region. This is done by typing a digit argument before +@kbd{:}. For instance, typing @kbd{1:} will propmt you with something like +@emph{:123,135}, assuming that the current region starts at line 123 and +ends at line 135. There is no need to type the line numbers, since Viper +inserts them automatically in front of the Ex command. +@cindex Ex commands + +@node Text Handling, Display, Groundwork, Commands +@section Text Handling + +@menu +* Move Commands:: Moving, Searching +* Marking:: Textmarkers in Viper and the Emacs Mark. +* Appending Text:: Text insertion, Shifting, Putting +* Editing in Insert State:: Autoindent, Quoting etc. +* Deleting Text:: Deleting +* Changing Text:: Changing, Replacement, Joining +* Search and Replace:: Searches, Query Replace, Pattern Commands +* Yanking:: Yanking, Viewing Registers +* Undoing:: Multiple Undo, Backups +@end menu + +@node Move Commands,Marking,,Text Handling +@subsection Move Commands + +@cindex movement commands +@cindex searching +@cindex textmarkers +@cindex markers +@cindex column movement +@cindex paragraphs +@cindex headings +@cindex sections +@cindex sentences +@cindex matching parens +@cindex paren matching + +@table @kbd +@item <count> h C-h +<count> chars to the left. +@item <count> j <lf> C-n +<count> lines downward. +@item <count> l <sp> +<count> chars to the right. +@item <count> k C-p +<count> lines upward. +@item <count> $ +To the end of line <count> from the cursor. +@item <count> ^ +To the first CHAR <count> - 1 lines lower. +@item <count> - +To the first CHAR <count> lines higher. +@item <count> + <cr> +To the first CHAR <count> lines lower. +@item 0 +To the first char of the line. +@item <count> | +To column <count> +@item <count> f<char> +<count> <char>s to the right (find). +@item <count> t<char> +Till before <count> <char>s to the right. +@item <count> F<char> +<count> <char>s to the left. +@item <count> T<char> +Till after <count> <char>s to the left. +@item <count> ; +Repeat latest @kbd{f t F T} <count> times. +@item <count> , +Repeat latest @kbd{f t F T} +<count> times in opposite direction. +@item <count> w +<count> words forward. +@item <count> W +<count> WORDS forward. +@item <count> b +<count> words backward. +@item <count> B +<count> WORDS backward. +@item <count> e +To the end of word <count> forward. +@item <count> E +To the end of WORD <count> forward. +@item <count> G +Go to line <count> (default end-of-file). +@item <count> H +To line <count> from top of the screen (home). +@item <count> L +To line <count> from bottom of the screen (last). +@item M +To the middle line of the screen. +@item <count> ) +<count> sentences forward. +@item <count> ( +<count> sentences backward. +@item <count> @} +<count> paragraphs forward. +@item <count> @{ +<count> paragraphs backward. +@item <count> ]] +To the <count>th heading. +@item <count> [[ +To the <count>th previous heading. +@item <count> [] +To the end of <count>th heading. +@item m<a-z> +Mark the cursor position with a letter. +@item `<a-z> +To the mark. +@item '<a-z> +To the first CHAR of the line with the mark. +@item [<a-z> +Show contents of textmarker. +@item ]<a-z> +Show contents of register. +@item `` +To the cursor position before the latest absolute +jump (of which are examples @kbd{/} and @kbd{G}). +@item '' +To the first CHAR of the line on which the cursor +was placed before the latest absolute jump. +@item <count> /<string> +To the <count>th occurrence of <string>. +@item <count> /<cr> +To the <count>th occurrence of <string> from previous @kbd{/ or ?}. +@item <count> ?<string> +To the <count>th previous occurrence of <string>. +@item <count> ?<cr> +To the <count>th previous occurrence of <string> from previous @kbd{?@: or /}. +@item n +Repeat latest @kbd{/} @kbd{?} (next). +@item N +Repeat latest search in opposite direction. +@item C-c / +Without a prefix argument, this command toggles +case-sensitive/case-insensitive search modes and plain vanilla/regular +expression search. With the prefix argument 1, i.e., +@kbd{1 C-c /}, this toggles case-sensitivity; with the prefix argument 2, +toggles plain vanilla search and search using +regular expressions. @xref{Viper Specials}, for alternative ways to invoke +this function. +@cindex vanilla search +@cindex case-sensitive search +@cindex case-insensitive search +@item % +Find the next bracket/parenthesis/brace and go to its match. +By default, Viper ignores brackets/parentheses/braces that occur inside +parentheses. You can change this by setting +@code{viper-parse-sexp-ignore-comments} to nil in your @file{.viper} file. +This option can also be toggled interactively if you quickly hit @kbd{%%%}. + +This latter feature is implemented as a vi-style keyboard macro. If you +don't want this macro, put + +@example +(viper-set-parsing-style-toggling-macro 'undefine) +@end example +@findex @code{viper-set-parsing-style-toggling-macro} + +in your @file{~/.viper} file. + +@end table +@kindex @kbd{%} +@kindex @kbd{C-c /} +@kindex @kbd{N} +@kindex @kbd{n} +@kindex @kbd{?<cr>} +@kindex @kbd{/<cr>} +@kindex @kbd{?<string>} +@kindex @kbd{/<string>} +@kindex @kbd{''} +@kindex @kbd{``} +@kindex @kbd{]<a-z>} +@kindex @kbd{[<a-z>} +@kindex @kbd{'<a-z>} +@kindex @kbd{`<a-z>} +@kindex @kbd{m<a-z>} +@kindex @kbd{[]} +@kindex @kbd{[[} +@kindex @kbd{]]} +@kindex @kbd{@{} +@kindex @kbd{@}} +@kindex @kbd{(} +@kindex @kbd{)} +@kindex @kbd{M} +@kindex @kbd{L} +@kindex @kbd{H} +@kindex @kbd{G} +@kindex @kbd{E} +@kindex @kbd{e} +@kindex @kbd{B} +@kindex @kbd{b} +@kindex @kbd{W} +@kindex @kbd{w} +@kindex @kbd{,} +@kindex @kbd{;} +@kindex @kbd{T<char>} +@kindex @kbd{F<char>} +@kindex @kbd{t<char>} +@kindex @kbd{f<char>} +@kindex @kbd{|} +@kindex @kbd{0} +@kindex @kbd{<cr>} +@kindex @kbd{+} +@kindex @kbd{-} +@kindex @kbd{^} +@kindex @kbd{$} +@kindex @kbd{C-p} +@kindex @kbd{<lf>} +@kindex @kbd{<sp>} +@kindex @kbd{C-n} +@kindex @kbd{C-h} +@kindex @kbd{h} +@kindex @kbd{j} +@kindex @kbd{k} +@kindex @kbd{l} +@vindex @code{viper-parse-sexp-ignore-comments} + +@node Marking,Appending Text,Move Commands,Text Handling +@subsection Marking + +Emacs mark is referred to in the region specifiers @kbd{r} and @kbd{R}. +@xref{Emacs Preliminaries}, and @xref{Basics}, for explanation. Also +see @ref{Mark,,Mark,emacs,The GNU Emacs manual}, for an explanation of +the Emacs mark ring. + +@cindex marking + +@table @kbd +@item m<a-z> +Mark the current file and position with the specified letter. +@item m . +Set the Emacs mark (@pxref{Emacs Preliminaries}) at point. +@item m < +Set the Emacs mark at beginning of buffer. +@item m > +Set the Emacs mark at end of buffer. +@item m , +Jump to the Emacs mark. +@item :mark <char> +Mark position with text marker named <char>. This is an Ex command. +@item :k <char> +Same as @kbd{:mark}. +@item `` +Exchange point and mark. +@item '' +Exchange point and mark and go to the first CHAR on line. +@item '<a-z> +Go to specified Viper mark. +@item +Go to specified Viper mark and go to the first CHAR on line. +@end table +@kindex @kbd{m<a-z>} +@kindex @kbd{m.} +@kindex @kbd{m>} +@kindex @kbd{m<} +@kindex @kbd{m,} +@findex @kbd{:mark} +@findex @kbd{:k} +@kindex @kbd{''} +@kindex @kbd{``} +@kindex @kbd{`<a-z>} +@kindex @kbd{'<a-z>} + +@node Appending Text, Editing in Insert State, Marking,Text Handling +@subsection Appending Text + +@xref{Options}, to see how to change tab and shiftwidth size. See the GNU +Emacs manual, or try @kbd{C-ha tabs} (If you have turned Emacs help on). +Check out the variable @code{indent-tabs-mode} to put in just spaces. +Also see options for word-wrap. + +@cindex inserting +@cindex appending +@cindex paste +@cindex put + +@table @kbd +@item <count> a +<count> times after the cursor. +@item <count> A +<count> times at the end of line. +@item <count> i +<count> times before the cursor (insert). +@item <count> I +<count> times before the first CHAR of the line +@item <count> o +On a new line below the current (open). +The count is only useful on a slow terminal. +@item <count> O +On a new line above the current. +The count is only useful on a slow terminal. +@item <count> ><move> +Shift the lines described by <count><move> one +shiftwidth to the right (layout!). +@item <count> >> +Shift <count> lines one shiftwidth to the right. +@item <count> ["<a-z1-9>]p +Put the contents of the (default undo) buffer +<count> times after the cursor. The register will +be automatically down-cased. +@item <count> ["<a-z1-9>]P +Put the contents of the (default undo) buffer +<count> times before the cursor. The register will +@item [<a-z> +Show contents of textmarker. +@item ]<a-z> +Show contents of register. +@item <count> . +Repeat previous command <count> times. For destructive +commands as well as undo. +@item f1 1 and f1 2 +While @kbd{.} repeats the last destructive command, +these two macros repeat the second-last and the third-last destructive +commands. @xref{Vi Macros}, for more information on Vi macros. +@item C-c M-p and C-c M-n +In Vi state, +these commands help peruse the history of Vi's destructive commands. +Successive typing of @kbd{C-c M-p} causes Viper to search the history in +the direction +of older commands, while hitting @kbd{C-c M-n} does so in reverse +order. Each command in the history is displayed in the Minibuffer. The +displayed command can +then be executed by typing `@kbd{.}'. + +Since typing the above sequences of keys may be tedious, the +functions doing the perusing can be bound to unused keyboard keys in the +@file{~/.viper} file. @xref{Viper Specials}, for details. +@end table +@kindex @kbd{C-c M-p} +@kindex @kbd{C-c M-n} +@kindex @kbd{.} +@kindex @kbd{]<a-z>} +@kindex @kbd{[<a-z>} +@kindex @kbd{P} +@kindex @kbd{p} +@kindex @kbd{"<a-z1-9>p} +@kindex @kbd{"<a-z1-9>P} +@kindex @kbd{>>} +@kindex @kbd{><move>} +@kindex @kbd{O} +@kindex @kbd{o} +@kindex @kbd{i} +@kindex @kbd{A} +@kindex @kbd{a} + +@node Editing in Insert State, Deleting Text, Appending Text,Text Handling +@subsection Editing in Insert State + +Minibuffer can be edited similarly to Insert state, and you can switch +between Insert/Replace/Vi states at will. +Some users prefer plain Emacs feel in the Minibuffer. To this end, set +@var{viper-vi-style-in-minibuffer} to @code{nil}. + +@cindex Insert state + +@table @kbd +@item C-v +Deprive the next char of its special meaning (quoting). +@item C-h +One char back. +@item C-w +One word back. +@item C-u +Back to the begin of the change on the +current line. + +@end table +@kindex @kbd{C-u} +@kindex @kbd{C-w} +@kindex @kbd{C-v} + +@node Deleting Text, Changing Text, Editing in Insert State, Text Handling +@subsection Deleting Text + + +There is one difference in text deletion that you should be +aware of. This difference comes from Emacs and was adopted in Viper +because we find it very useful. In Vi, if you delete a line, say, and then +another line, these two deletions are separated and are put back +separately if you use the @samp{p} command. In Emacs (and Viper), successive +series of deletions that are @emph{not interrupted} by other commands are +lumped together, so the deleted text gets accumulated and can be put back +as one chunk. If you want to break a sequence of deletions so that the +newly deleted text could be put back separately from the previously deleted +text, you should perform a non-deleting action, e.g., move the cursor one +character in any direction. + +@cindex shifting text + +@table @kbd +@item <count> x +Delete <count> chars under and after the cursor. +@item <count> X +Delete <count> chars before the cursor. +@item <count> d<move> +Delete from point to endpoint of <count><move>. +@item <count> dd +Delete <count> lines. +@item D +The rest of the line. +@item <count> <<move> +Shift the lines described by <count><move> one +shiftwidth to the left (layout!). +@item <count> << +Shift <count> lines one shiftwidth to the left. +@end table +@kindex @kbd{<<} +@kindex @kbd{<<move>} +@kindex @kbd{D} +@kindex @kbd{dd} +@kindex @kbd{d<move>} +@kindex @kbd{X} +@kindex @kbd{x} + +@node Changing Text, Search and Replace, Deleting Text,Text Handling +@subsection Changing Text + +@cindex joining lines +@cindex changing case +@cindex quoting regions +@cindex substitution + +@table @kbd +@item <count> r<char> +Replace <count> chars by <char> - no <esc>. +@item <count> R +Overwrite the rest of the line, +appending change @var{count - 1} times. +@item <count> s +Substitute <count> chars. +@item <count> S +Change <count> lines. +@item <count> c<move> +Change from begin to endpoint of <count><move>. +@item <count> cc +Change <count> lines. +@item <count> C +The rest of the line and <count> - 1 next lines. +@item <count> =<move> +Reindent the region described by move. +@item <count> ~ +Switch lower and upper cases. +@item <count> J +Join <count> lines (default 2). +@item :[x,y]s/<pat>/<repl>/<f> +Substitute (on lines x through y) the pattern +<pat> (default the last pattern) with <repl>. Useful +flags <f> are @samp{g} for @samp{global} (i.e.@: change every +non-overlapping occurrence of <pat>) and @samp{c} for +@samp{confirm} (type @samp{y} to confirm a particular +substitution, else @samp{n} ). Instead of @kbd{/} any +punctuation CHAR unequal to <space> <tab> and <lf> can be used as +delimiter. + +In Emacs, @samp{\&} stands for the last matched expression, so +@kbd{s/[ab]+/\&\&/} will double the string matched by @kbd{[ab]}. +Viper doesn't treat @samp{&} specially, unlike Vi: use @samp{\&} instead. + +Note: @emph{The newline character (inserted as @kbd{C-qC-j}) +can be used in <repl>}. +@item :[x,y]copy [z] +Copy text between @kbd{x} and @kbd{y} to the position after @kbd{z}. +@item :[x,y]t [z] +Same as @kbd{:copy}. +@item :[x,y]move [z] +Move text between @kbd{x} and @kbd{y} to the position after @kbd{z}. +@item & +Repeat latest Ex substitute command, e.g. +@kbd{:s/wrong/right}. +@item C-c / +Toggle case-sensitive search. With prefix argument, toggle vanilla/regular +expression search. +@item #c<move> +Change upper-case characters in the region to lower-case. +@item #C<move> +Change lower-case characters in the region to upper-case. +@item #q<move> +Insert specified string at the beginning of each line in the region +@item C-c M-p and C-c M-n +In Insert and Replace states, these keys are bound to commands that peruse +the history of the text +previously inserted in other insert or replace commands. By repeatedly typing +@kbd{C-c M-p} or @kbd{C-c M-n}, you will cause Viper to +insert these previously used strings one by one. +When a new string is inserted, the previous one is deleted. + +In Vi state, these keys are bound to functions that peruse the history of +destructive Vi commands. +@xref{Viper Specials}, for details. +@end table +@kindex @kbd{C-c M-p} +@kindex @kbd{C-c M-n} +@kindex @kbd{#q<move> } +@kindex @kbd{#C<move>} +@kindex @kbd{#c<move>} +@kindex @kbd{&} +@kindex @kbd{\&} +@findex @kbd{:substitute/<pat>/<repl>/<f>} +@findex @kbd{:s/<pat>/<repl>/<f>} +@findex @kbd{:copy [z]} +@findex @kbd{:t [z]} +@findex @kbd{:move [z]} +@kindex @kbd{J} +@kindex @kbd{~} +@kindex @kbd{=<move>} +@kindex @kbd{C} +@kindex @kbd{cc} +@kindex @kbd{c<move>} +@kindex @kbd{S} +@kindex @kbd{s} +@kindex @kbd{R} +@kindex @kbd{r<char>} + +@node Search and Replace, Yanking, Changing Text,Text Handling +@subsection Search and Replace + +@xref{Groundwork}, for Ex address syntax. @xref{Options}, to see how to +get literal (non-regular-expression) search and how to stop search from +wrapping around. + +@table @kbd +@item <count> /<string> +To the <count>th occurrence of <string>. +@item <count> ?<string> +To the <count>th previous occurrence of <string>. +@item <count> g<move> +Search for the text described by move. (off by default) +@item n +Repeat latest @kbd{/} @kbd{?} (next). +@item N +Idem in opposite direction. +@item % +Find the next bracket and go to its match +@item :[x,y]g/<string>/<cmd> +@cindex text processing +Search globally [from line x to y] for <string> +and execute the Ex <cmd> on each occurrence. +@item :[x,y]v/<string>/<cmd> +Execute <cmd> on the lines that don't match. +@item #g<move> +Execute the last keyboard macro for each line in the region. +@xref{Macros and Registers}, for more info. +@item Q +Query Replace. +@item :ta <name> +Search in the tags file where <name> is defined (file, line), and go to it. +@item :[x,y]s/<pat>/<repl>/<f> +Substitute (on lines x through y) the pattern <pat> (default the last +pattern) with <repl>. Useful +flags <f> are @samp{g} for @samp{global} (i.e.@: change every +non-overlapping occurrence of <pat>) and @samp{c} for +@samp{confirm} (type @samp{y} to confirm a particular +substitution, else @samp{n}). Instead of @kbd{/} any +punctuation character other than <space> <tab> and <lf> can be used as +delimiter. + +Note: @emph{The newline character (inserted as @kbd{C-qC-j}) +can be used in <repl>}. +@item & +Repeat latest Ex substitute command, e.g.@: @kbd{:s/wrong/right}. +@item :global /<pattern>/<ex-command> +@itemx :g /<pattern>/<ex-command> +Execute <ex-command> on all lines that match <pattern>. +@item :vglobal /<pattern>/<ex-command> +@itemx :v /<pattern>/<ex-command> +Execute <ex-command> on all lines that do not match <pattern>. +@end table +@kindex @kbd{&} +@findex @kbd{:substitute/<pat>/<repl>/<f>} +@kindex @kbd{Q} +@kindex @kbd{#g<move>} +@findex @kbd{:v} +@findex @kbd{:g} +@findex @kbd{:global} +@findex @kbd{:vglobal} +@findex @kbd{:tag <name>} +@kindex @kbd{%} +@kindex @kbd{N} +@kindex @kbd{n} +@kindex @kbd{g<move>} +@kindex @kbd{?<string>} +@kindex @kbd{/<string>} + +@node Yanking,Undoing,Search and Replace,Text Handling +@subsection Yanking + +@cindex cut and paste +@cindex paste + +@table @kbd +@item <count> y<move> +Yank from begin to endpoint of <count><move>. +@item <count> "<a-z>y<move> +Yank from begin to endpoint of <count><move> to register. +@item <count> "<A-Z>y<move> +Yank from begin to endpoint of <count><move> and append +to register. +@item <count> yy +<count> lines. +@item <count> Y +Idem (should be equivalent to @kbd{y$} though). +@item m<a-z> +Mark the cursor position with a letter. +@item [<a-z> +Show contents of textmarker. +@item ]<a-z> +Show contents of register. +@item <count> ["<a-z1-9>]p +Put the contents of the (default undo) buffer +<count> times after the cursor. The register will +be automatically down-cased. +@item <count> ["<a-z1-9>]P +Put the contents of the (default undo) buffer +<count> times before the cursor. The register will +@end table +@kindex @kbd{P} +@kindex @kbd{p} +@kindex @kbd{"<a-z1-9>p} +@kindex @kbd{"<a-z1-9>P} +@kindex @kbd{]<a-z>} +@kindex @kbd{[<a-z>} +@kindex @kbd{m<a-z>} +@kindex @kbd{Y} +@kindex @kbd{yy} +@kindex @kbd{"<A-Z>y<move>} +@kindex @kbd{"<a-z>y<move>} +@kindex @kbd{y<move>} +@kindex @kbd{yank} +@findex @kbd{:yank} + +@node Undoing,, Yanking,Text Handling +@subsection Undoing + +@cindex undo +@cindex backup files + +@table @kbd +@item u U +Undo the latest change. +@item . +Repeat undo. +@item :q! +Quit Vi without writing. +@item :e! +Re-edit a messed-up file. +@item :rec +Recover file from autosave. Viper also creates backup files +that have a @samp{~} appended to them. +@end table +@findex @kbd{:rec} +@findex @kbd{:e!} +@findex @kbd{:q!} +@kindex @kbd{.} +@kindex @kbd{U} +@kindex @kbd{u} + +@node Display, File and Buffer Handling, Text Handling, Commands +@section Display + +@cindex scrolling + +@table @kbd +@item C-g +At user level 1, +give file name, status, current line number +and relative position.@* +At user levels 2 and higher, abort the current command. +@item C-c g +Give file name, status, current line number and relative position -- all +user levels. +@item C-l +Refresh the screen. +@item <count> C-e +Expose <count> more lines at bottom, cursor stays put (if possible). +@item <count> C-y +Expose <count> more lines at top, cursor stays put (if possible). +@item <count> C-d +Scroll <count> lines downward (default the number of the previous scroll; +initialization: half a page). +@item <count> C-u +Scroll <count> lines upward (default the number of the previous scroll; +initialization: half a page). +@item <count> C-f +<count> pages forward. +@item <count> C-b +<count> pages backward (in older versions @kbd{C-b} only works without count). +@item <count> z<cr> +@item zH +Put line <count> at the top of the window (default the current line). +@item <count> z- +@item zL +Put line <count> at the bottom of the window +(default the current line). +@item <count> z. +@item zM +Put line <count> in the center of the window +(default the current line). +@end table +@kindex @kbd{zM} +@kindex @kbd{zL} +@kindex @kbd{zH} +@kindex @kbd{z<cr>} +@kindex @kbd{z.} +@kindex @kbd{z-} +@kindex @kbd{z<cr>} +@kindex @kbd{C-b} +@kindex @kbd{C-f} +@kindex @kbd{C-u} +@kindex @kbd{C-d} +@kindex @kbd{C-y} +@kindex @kbd{C-e} +@kindex @kbd{C-l} +@kindex @kbd{C-g} + + +@node File and Buffer Handling, Mapping, Display,Commands +@section File and Buffer Handling + +@cindex multiple files + +In all file handling commands, space should be typed before entering the file +name. If you need to type a modifier, such as @kbd{>>} or @kbd{!}, don't +put any space between the command and the modifier. + +@table @kbd +@item :q +Quit buffer except if modified. +@item :q! +Quit buffer without checking. In Viper, these two commands +are identical. Confirmation is required if exiting modified buffers that +visit files. +@item :suspend +@item :stop +Suspend Viper +@item :[x,y] w +Write the file. Viper makes sure that a final newline is always added to +any file where this newline is missing. This is done by setting Emacs +variable @code{require-final-newline} to @code{t}. If you don't like this +feature, use @code{setq-default} to set @code{require-final-newline} to +@code{nil}. This must be done in @file{.viper} file. +@item :[x,y] w <name> +Write to the file <name>. +@item :[x,y] w>> <name> +Append the buffer to the file <name>. There should be no space between +@kbd{w} and @kbd{>>}. Type space after the @kbd{>>} and see what happens. +@item :w!@: <name> +Overwrite the file <name>. In Viper, @kbd{:w} and @kbd{:w!} are identical. +Confirmation is required for writing to an existing file (if this is not +the file the buffer is visiting) or to a read-only file. +@item :x,y w <name> +Write lines x through y to the file <name>. +@item :wq +Write the file and kill buffer. +@item :r <file> [<file> ...] +Read file into a buffer, inserting its contents after the current line. +@item :xit +Same as @kbd{:wq}. +@item :Write +@itemx :W +Save all unsaved buffers, asking for confirmation. +@item :WWrite +@itemx :WW +Like @kbd{W}, but without asking for confirmation. +@item ZZ +Save current buffer and kill it. If user level is 1, then save all files +and kill Emacs. Killing Emacs is the wrong way to use it, so you should +switch to higher user levels as soon as possible. +@item :x [<file>] +Save and kill buffer. +@item :x!@: [<file>] +@kbd{:w![<file>]} and @kbd{:q}. +@item :pre +Preserve the file -- autosave buffers. +@item :rec +Recover file from autosave. +@item :f +Print file name and lines. +@item :cd [<dir>] +Set the working directory to <dir> (default home directory). +@item :pwd +Print present working directory. +@item :e [+<cmd>] <files> +Edit files. If no filename is given, edit the file visited by the current +buffer. If buffer was modified or the file changed on disk, ask for +confirmation. Unlike Vi, Viper allows @kbd{:e} to take multiple arguments. +The first file is edited the same way as in Vi. The rest are visited +in the usual Emacs way. +@item :e!@: [+<cmd>] <files> +Re-edit file. If no filename, re-edit current file. +In Viper, unlike Vi, @kbd{e!} is identical to @kbd{:e}. In both cases, the +user is asked to confirm if there is a danger of discarding changes to a +buffer. +@item :q! +Quit Vi without writing. +@item C-^ +Edit the alternate (normally the previous) file. +@item :rew +Obsolete +@item :args +List files not shown anywhere with counts for next +@item :n [count] [+<cmd>] [<files>] +Edit <count> file, or edit files. The count comes from @kbd{:args}. +@item :N [count] [+<cmd>] [<files>] +Like @kbd{:n}, but the meaning of the variable +@var{ex-cycle-other-window} is reversed. +@item :b +Switch to another buffer. If @var{ex-cycle-other-window} is @code{t}, +switch in another window. Buffer completion is supported. +@item :B +Like @kbd{:b}, but the meaning of @var{ex-cycle-other-window} is reversed. +@item :<address>r <name> +Read the file <name> into the buffer after the line <address>. +@item v, V, C-v +Edit a file in current or another window, or in another frame. File name +is typed in Minibuffer. File completion and history are supported. +@end table +@kindex @kbd{v} +@kindex @kbd{V} +@findex @kbd{:args} +@findex @kbd{:rew} +@kindex @kbd{C-^} +@findex @kbd{:e!@: [<files>]} +@findex @kbd{:e [<files>]} +@findex @kbd{:edit [<files>]} +@findex @kbd{:edit!@: [<files>]} +@findex @kbd{:q!} +@findex @kbd{:q} +@findex @kbd{:quit} +@findex @kbd{:quit!} +@findex @kbd{:f} +@findex @kbd{:rec} +@findex @kbd{:r} +@findex @kbd{:read} +@findex @kbd{:pre} +@kindex @kbd{ZZ} +@findex @kbd{:wq} +@findex @kbd{:w <file>} +@findex @kbd{:w!@: <file>} +@findex @kbd{:w >> <file>} +@findex @kbd{:write <file>} +@findex @kbd{:write!@: <file>} +@findex @kbd{:write >> <file>} +@findex @kbd{:W} +@findex @kbd{:WW} +@findex @kbd{:Write} +@findex @kbd{:WWrite} +@findex @kbd{:WWrite} +@findex @kbd{:x} +@findex @kbd{:x!} +@findex @kbd{:suspend} +@findex @kbd{:stop} +@findex @kbd{:n [<count> | <file>]} +@findex @kbd{:cd [<dir>]} +@findex @kbd{:pwd} + +@node Mapping, Shell Commands, File and Buffer Handling, Commands +@section Mapping + +@cindex keybindings +@cindex key mapping + +@table @kbd +@item :map <string> +Start defining a Vi-style keyboard macro. +For instance, typing +@kbd{:map www} followed by @kbd{:!wc %} and then typing @kbd{C-x )} +will cause @kbd{www} to run wc on +current file (Vi replaces @samp{%} with the current file name). +@item C-x ) +Finish defining a keyboard macro. +In Viper, this command completes the process of defining all keyboard +macros, whether they are Emacs-style or Vi-style. +This is a departure from Vi, needed to allow WYSIWYG mapping of +keyboard macros and to permit the use of function keys and arbitrary Emacs +functions in the macros. +@item :unmap <string> +Deprive <string> of its mappings in Vi state. +@item :map!@: <string> +Map a macro for Insert state. +@item :unmap!@: <string> +Deprive <string> of its mapping in Insert state (see @kbd{:unmap}). +@item @@<a-z> +In Vi state, +execute the contents of register as a command. +@item @@@@ +In Vi state, +repeat last register command. +@item @@# +In Vi state, +begin keyboard macro. End with @@<a-z>. This will +put the macro in the proper register. Register will +be automatically down-cased. +@xref{Macros and Registers}, for more info. +@item @@!<a-z> +In Vi state, +yank anonymous macro to register +@item * +In Vi state, +execute anonymous macro (defined by C-x( and C-x )). +@item C-x e +Like @kbd{*}, but works in all Viper states. +@item #g<move> +Execute the last keyboard macro for each line in the region. +@xref{Macros and Registers}, for more info. +@item [<a-z> +Show contents of textmarker. +@item ]<a-z> +Show contents of register. +@end table +@kindex @kbd{]<a-z>} +@kindex @kbd{[<a-z>} +@kindex @kbd{#g<move>} +@kindex @kbd{*} +@kindex @kbd{@@!<a-z>} +@kindex @kbd{@@#} +@kindex @kbd{@@@@} +@kindex @kbd{@@<a-z>} +@findex @kbd{:unmap <char>} +@findex @kbd{:map <char> <seq>} +@findex @kbd{:unmap!@: <char>} +@findex @kbd{:map!@: <char> <seq>} + +@node Shell Commands, Options, Mapping, Commands +@section Shell Commands + +@cindex % (Current file) + +Note that % is used in Ex commands to mean current file. If you want a % +in your command, it must be escaped as @samp{\%}. +@cindex % (Ex address) +However if % is the +first character, it stands as the address for the whole file. +@cindex # (Previous file) +Similarly, @samp{#} expands to the previous file. The previous file is +the first file in @kbd{:args} listing. This defaults +to the previous file in the VI sense if you have one window.@refill + +@cindex shell commands + +@table @kbd +@item :sh +Execute a subshell in another window +@item :[x,y]!<cmd> +Execute a shell <cmd> [on lines x through y; +% is replace by current file, \% is changed to % +@item :[x,y]!!@: [<args>] +Repeat last shell command [and append <args>]. +@item :!<cmd> +Just execute command and display result in a buffer. +@item :!!@: <args> +Repeat last shell command and append <args> +@item <count> !<move><cmd> +The shell executes <cmd>, with standard +input the lines described by <count><move>, +next the standard output replaces those lines +(think of @samp{cb}, @samp{sort}, @samp{nroff}, etc.). +@item <count> !!<cmd> +Give <count> lines as standard input to the +shell <cmd>, next let the standard output +replace those lines. +@item :[x,y] w !<cmd> +Let lines x to y be standard input for <cmd> +(notice the <sp> between @kbd{w} and @kbd{!}). +@item :<address>r !<cmd> +Put the output of <cmd> after the line <address> (default current). +@item :<address>r <name> +Read the file <name> into the buffer after the line <address> (default +current). +@end table +@findex @kbd{:<address>r <name>} +@findex @kbd{:<address>r !<cmd>} +@findex @kbd{!<cmd>} +@findex @kbd{!!<cmd>} +@findex @kbd{!<move><cmd>} +@findex @kbd{:w !<cmd>} +@findex @kbd{:x,y w !<cmd>} +@findex @kbd{:!!@: <args>} +@findex @kbd{:!<cmd>} +@findex @kbd{:sh} + +@node Options,Emacs Related Commands,Shell Commands,Commands +@section Options + +@cindex Vi options + +@table @kbd +@item autoindent +@itemx ai +@cindex autoindent +autoindent -- In append mode after a <cr> the +cursor will move directly below the first +character on the previous line. +This setting affects the current buffer only. +@item autoindent-global +@itemx ai-global +Same as `autoindent', but affects all buffers. +@item noautoindent +@itemx noai +Cancel autoindent. +@item noautoindent-global +@itemx noai-g +Cancel autoindent-global. +@item ignorecase +@itemx ic +@cindex case and searching +ignorecase -- No distinction between upper and lower cases when searching. +@item noignorecase +@itemx noic +Cancel ignorecase. +@item magic +@itemx ma +@cindex literal searching +Regular expressions used in searches; nomagic means no regexps. +@item nomagic +@item noma +Cancel magic. +@item readonly +@itemx ro +@cindex readonly files +readonly -- The file is not to be changed. +If the user attempts to write to this file, confirmation will be requested. +@item noreadonly +@itemx noro +Cancel readonly. +@item shell=<string> +@itemx sh=<string> +@cindex shell +shell -- The program to be used for shell escapes +(default @samp{$SHELL} (default @file{/bin/sh})). +@item shiftwidth=<count> +@itemx sw=<count> +@cindex layout +@cindex shifting text +shiftwidth -- Gives the shiftwidth (default 8 positions). +@item showmatch +@itemx sm +@cindex paren matching +@cindex matching parens +showmatch -- Whenever you append a @kbd{)}, Vi shows +its match if it's on the same page; also with +@kbd{@{} and @kbd{@}}. If there's no match, Vi will beep. +@item noshowmatch +@itemx nosm +Cancel showmatch. +@item tabstop=<count> +@itemx ts=<count> +@cindex changing tab width +@cindex tabbing +tabstop -- The length of a <ht>; warning: this is +only IN the editor, outside of it <ht>s have +their normal length (default 8 positions). +This setting affects the current buffer only. +@item tabstop-global +@itemx ts-g +Same as `tabstop', but affects all buffers. +@item wrapmargin=<count> +@itemx wm=<count> +@cindex auto fill +@cindex word wrap +wrapmargin -- In append mode Vi automatically +puts a <lf> whenever there is a <sp> or <ht> +within <wm> columns from the right margin. +@item wrapscan +@itemx ws +@cindex searching +wrapscan -- When searching, the end is +considered @samp{stuck} to the begin of the file. +@item nowrapscan +@itemx nows +Cancel wrapscan. +@item :set <option> +Turn <option> on. +@item :set no<option> +Turn <option> off. +@item :set <option>=<value> +Set <option> to <value>. +@end table +@findex @kbd{:set <option>=<value>} +@findex @kbd{:set no<option>} +@findex @kbd{:set <option>} +@findex @kbd{:set ws} +@findex @kbd{:set wrapscan} +@findex @kbd{:set wm=<count>} +@findex @kbd{:set wrapmargin=<count>} +@findex @kbd{:set ts=<count>} +@findex @kbd{:set tabstop=<count>} +@findex @kbd{:set tab-stop-local=<count>} +@findex @kbd{:set sm} +@findex @kbd{:set showmatch} +@findex @kbd{:set sw=<count>} +@findex @kbd{:set shiftwidth=<count>} +@findex @kbd{:set sh=<string>} +@findex @kbd{:set shell=<string>} +@findex @kbd{:set ro} +@findex @kbd{:set readonly} +@findex @kbd{:set magic} +@findex @kbd{:set ic} +@findex @kbd{:set ignorecase} +@findex @kbd{:set ai} +@findex @kbd{:set autoindent} + +@node Emacs Related Commands,,Options,Commands +@section Emacs Related Commands + +@table @kbd +@item C-\ +Begin Meta command in Vi or Insert states. Most often used as C-\ x (M-x). + +Note: Emacs binds @kbd{C-\} to a function that offers to change the +keyboard input method in the multilingual environment. Viper overrides this +binding. However, it is still possible to switch the input method by typing +@kbd{\ C-\} in the Vi command state and @kbd{C-z \ C-\} in the Insert state. +Or you can use the MULE menu on the menubar. +@item C-z +In Insert and Replace states, prepare Viper to accept the next command and +execute it as if Viper was in Vi state. Then return to Insert state. + +In Vi state, switch to Emacs state; in Emacs state, switch to Vi state. +@item C-c \ +Switches to Vi state for the duration of a single command. Then goes back +to the original Viper state. Works from Vi, Insert, Replace, and Emacs states. +@item C-x0 +Close Window +@item C-x1 +Close Other Windows +@item C-x2 +Split Window +@item C-xo +Move among windows +@item C-xC-f +Emacs find-file, useful in Insert state +@item C-y +Put back the last killed text. Similar to Vi's @kbd{p}, but also works in +Insert and Replace state. This command doesn't work in Vi command state, +since this binding is taken for something else. +@item M-y +Undoes the last @kbd{C-y} and puts another kill from the kill ring. +Using this command, you can try may different kills until you find the one +you need. +@end table +@kindex @kbd{M-y} +@kindex @kbd{C-y} +@kindex @kbd{C-xC-f} +@kindex @kbd{C-xo} +@kindex @kbd{C-x2} +@kindex @kbd{C-x1} +@kindex @kbd{C-x0} +@kindex @kbd{C-z} +@kindex @kbd{C-\} +@kindex @kbd{C-c\} + +@node Mouse-bound Commands,,,Commands +@section Mouse-bound Commands + +The following two mouse actions are normally bound to to special search and +insert commands in of Viper: + +@table @kbd +@item S-mouse-1 +Holding Shift and clicking mouse button 1 will +initiate search for +a region under the mouse pointer. +This command can take a prefix argument. Note: Viper sets this +binding only if this mouse action is not +already bound to something else. +@xref{Viper Specials}, for more information.@refill + +@item S-mouse-2 +Holding Shift and clicking button 2 of the mouse will +insert a region surrounding the mouse pointer. +This command can also take a prefix argument. +Note: Viper sets this binding only if this mouse action is not +already bound to something else. +@xref{Viper Specials}, for more details.@refill +@end table +@kindex @kbd{S-mouse-1} +@kindex @kbd{S-mouse-2} +@kindex @kbd{meta button1up} +@kindex @kbd{meta button2up} + +@node Acknowledgments,,,Top +@comment node-name, next, previous, up +@unnumbered Acknowledgments + +Viper, formerly known as VIP-19, was written by Michael Kifer. Viper is +based on the original VIP package by Masahiko Sato and on its enhancement, +VIP 4.4, by Aamod Sane. This manual is an adaptation of the manual for VIP +4.4, which, in turn, was based on Sato's manual for VIP 3.5. + +Many contributors on the net pointed out bugs and suggested a number of +useful features. Here is a (hopefully) complete list of contributors: + +@example +ahg@@panix.com (Al Gelders), +amade@@diagram.fr (Paul-Bernard Amade), +ascott@@fws214.intel.com (Andy Scott), +cook@@biostat.wisc.edu (Tom Cook), +csdayton@@midway.uchicago.edu (Soren Dayton), +dave@@hellgate.utah.edu, +dominik@@strw.LeidenUniv.nl (Carsten Dominik), +dwallach@@cs.princeton.edu (Dan Wallach), +dwight@@toolucky.llnl.gov (Dwight Shih), +edmonds@@edmonds.home.cs.ubc.ca (Brian Edmonds), +gviswana@@cs.wisc.edu (Guhan Viswanathan), +gvr@@halcyon.com (George V.@: Reilly), +hatazaki@@bach.convex.com (Takao Hatazaki), +hpz@@ibmhpz.aug.ipp-garching.mpg.de (Hans-Peter Zehrfeld), +jackr@@dblues.engr.sgi.com (Jack Repenning), +jamesm@@bga.com (D.J.@: Miller II), +jjm@@hplb.hpl.hp.com (Jean-Jacques Moreau), +jl@@cse.ogi.edu (John Launchbury), +jobrien@@hchp.org (John O'Brien), +johnw@@borland.com (John Wiegley), +kanze@@gabi-soft.fr (James Kanze), +kin@@isi.com (Kin Cho), +kwzh@@gnu.org (Karl Heuer), +lindstro@@biostat.wisc.edu (Mary Lindstrom), +Mark.Bordas@@East.Sun.COM (Mark Bordas), +meyering@@comco.com (Jim Meyering), +mrb@@Eng.Sun.COM (Martin Buchholz), +mveiga@@dit.upm.es (Marcelino Veiga Tuimil), +paulk@@summit.esg.apertus.com (Paul Keusemann), +pfister@@cs.sunysb.edu (Hanspeter Pfister), +phil_brooks@@MENTORG.COM (Phil Brooks), +pogrell@@informatik.hu-berlin.de (Lutz Pogrell), +pradyut@@cs.uchicago.edu (Pradyut Shah), +roderick@@argon.org (Roderick Schertler), +rxga@@ulysses.att.com, +sawdey@@lcse.umn.edu (Aaron Sawdey), +simonb@@prl.philips.co.uk (Simon Blanchard), +stephen@@farrell.org (Stephen Farrell), +sudish@@MindSpring.COM (Sudish Joseph), +schwab@@issan.informatik.uni-dortmund.de (Andreas Schwab) +terra@@diku.dk (Morten Welinder), +thanh@@informatics.muni.cz (Han The Thanh), +toma@@convex.convex.com, +vrenjak@@sun1.racal.com (Milan Vrenjak), +whicken@@dragon.parasoft.com (Wendell Hicken), +zapman@@cc.gatech.edu (Jason Zapman II), +@end example + + +@node Key Index,Function Index,,Top +@comment node-name, next, previous, up +@unnumbered Key Index + +@printindex ky + +@node Function Index,Variable Index,Key Index,Top +@comment node-name, next, previous, up +@unnumbered Function Index + +@printindex fn + +@node Variable Index,Package Index,Function Index,Top +@comment node-name, next, previous, up +@unnumbered Variable Index + +@printindex vr + +@node Package Index,Concept Index,Variable Index,Top +@comment node-name, next, previous, up +@unnumbered Package Index + +@printindex pg + +@node Concept Index,,Package Index,Top +@comment node-name, next, previous, up +@unnumbered Concept Index + +@printindex cp + +@contents +@bye diff --git a/man/widget.texi b/man/widget.texi new file mode 100644 index 00000000000..aa7897395a7 --- /dev/null +++ b/man/widget.texi @@ -0,0 +1,1617 @@ +\input texinfo.tex + +@c %**start of header +@setfilename ../info/widget +@settitle The Emacs Widget Library +@iftex +@afourpaper +@headings double +@end iftex +@c %**end of header + +@dircategory Editors +@direntry +* Widget: (widget). Documenting the "widget" package used by the + Emacs Custom facility. +@end direntry + +@node Top, Introduction, (dir), (dir) +@comment node-name, next, previous, up +@top The Emacs Widget Library + +Version: 1.9914 + +@menu +* Introduction:: +* User Interface:: +* Programming Example:: +* Setting Up the Buffer:: +* Basic Types:: +* Sexp Types:: +* Widget Properties:: +* Defining New Widgets:: +* Widget Browser:: +* Widget Minor Mode:: +* Utilities:: +* Widget Wishlist:: +@end menu + +@node Introduction, User Interface, Top, Top +@comment node-name, next, previous, up +@section Introduction + +Most graphical user interface toolkits, such as Motif and XView, provide +a number of standard user interface controls (sometimes known as +`widgets' or `gadgets'). Emacs doesn't really support anything like +this, except for an incredible powerful text ``widget''. On the other +hand, Emacs does provide the necessary primitives to implement many +other widgets within a text buffer. The @code{widget} package +simplifies this task. + +The basic widgets are: + +@table @code +@item link +Areas of text with an associated action. Intended for hypertext links +embedded in text. +@item push-button +Like link, but intended for stand-alone buttons. +@item editable-field +An editable text field. It can be either variable or fixed length. +@item menu-choice +Allows the user to choose one of multiple options from a menu, each +option is itself a widget. Only the selected option will be visible in +the buffer. +@item radio-button-choice +Allows the user to choose one of multiple options by activating radio +buttons. The options are implemented as widgets. All options will be +visible in the buffer. +@item item +A simple constant widget intended to be used in the @code{menu-choice} and +@code{radio-button-choice} widgets. +@item choice-item +An button item only intended for use in choices. When invoked, the user +will be asked to select another option from the choice widget. +@item toggle +A simple @samp{on}/@samp{off} switch. +@item checkbox +A checkbox (@samp{[ ]}/@samp{[X]}). +@item editable-list +Create an editable list. The user can insert or delete items in the +list. Each list item is itself a widget. +@end table + +Now of what possible use can support for widgets be in a text editor? +I'm glad you asked. The answer is that widgets are useful for +implementing forms. A @dfn{form} in Emacs is a buffer where the user is +supposed to fill out a number of fields, each of which has a specific +meaning. The user is not supposed to change or delete any of the text +between the fields. Examples of forms in Emacs are the @file{forms} +package (of course), the customize buffers, the mail and news compose +modes, and the @sc{html} form support in the @file{w3} browser. + +The advantages for a programmer of using the @code{widget} package to +implement forms are: + +@enumerate +@item +More complex field than just editable text are supported. +@item +You can give the user immediate feedback if he enters invalid data in a +text field, and sometimes prevent entering invalid data. +@item +You can have fixed sized fields, thus allowing multiple field to be +lined up in columns. +@item +It is simple to query or set the value of a field. +@item +Editing happens in buffer, not in the mini-buffer. +@item +Packages using the library get a uniform look, making them easier for +the user to learn. +@item +As support for embedded graphics improve, the widget library will +extended to support it. This means that your code using the widget +library will also use the new graphic features by automatic. +@end enumerate + +In order to minimize the code that is loaded by users who does not +create any widgets, the code has been split in two files: + +@table @file +@item widget.el +This will declare the user variables, define the function +@code{widget-define}, and autoload the function @code{widget-create}. +@item wid-edit.el +Everything else is here, there is no reason to load it explicitly, as +it will be autoloaded when needed. +@end table + +@node User Interface, Programming Example, Introduction, Top +@comment node-name, next, previous, up +@section User Interface + +A form consist of read only text for documentation and some fields, +where each the fields contain two parts, as tag and a value. The tags +are used to identify the fields, so the documentation can refer to the +foo field, meaning the field tagged with @samp{Foo}. Here is an example +form: + +@example +Here is some documentation. + +Name: @i{My Name} @strong{Choose}: This option +Address: @i{Some Place +In some City +Some country.} + +See also @b{_other work_} for more information. + +Numbers: count to three below +@b{[INS]} @b{[DEL]} @i{One} +@b{[INS]} @b{[DEL]} @i{Eh, two?} +@b{[INS]} @b{[DEL]} @i{Five!} +@b{[INS]} + +Select multiple: + +@b{[X]} This +@b{[ ]} That +@b{[X]} Thus + +Select one: + +@b{(*)} One +@b{( )} Another One. +@b{( )} A Final One. + +@b{[Apply Form]} @b{[Reset Form]} +@end example + +The top level widgets in is example are tagged @samp{Name}, +@samp{Choose}, @samp{Address}, @samp{_other work_}, @samp{Numbers}, +@samp{Select multiple}, @samp{Select one}, @samp{[Apply Form]}, and +@samp{[Reset Form]}. There are basically two thing the user can do within +a form, namely editing the editable text fields and activating the +buttons. + +@subsection Editable Text Fields + +In the example, the value for the @samp{Name} is most likely displayed +in an editable text field, and so are values for each of the members of +the @samp{Numbers} list. All the normal Emacs editing operations are +available for editing these fields. The only restriction is that each +change you make must be contained within a single editable text field. +For example, capitalizing all text from the middle of one field to the +middle of another field is prohibited. + +Editing text fields are created by the @code{editable-field} widget. + +The editing text fields are highlighted with the +@code{widget-field-face} face, making them easy to find. + +@deffn Face widget-field-face +Face used for other editing fields. +@end deffn + +@subsection Buttons + +Some portions of the buffer have an associated @dfn{action}, which can +be @dfn{invoked} by a standard key or mouse command. These portions +are called @dfn{buttons}. The default commands for activating a button +are: + +@table @kbd +@item @key{RET} +@deffn Command widget-button-press @var{pos} &optional @var{event} +Invoke the button at @var{pos}, defaulting to point. +If point is not located on a button, invoke the binding in +@code{widget-global-map} (by default the global map). +@end deffn + +@item mouse-2 +@deffn Command widget-button-click @var{event} +Invoke the button at the location of the mouse pointer. If the mouse +pointer is located in an editable text field, invoke the binding in +@code{widget-global-map} (by default the global map). +@end deffn +@end table + +There are several different kind of buttons, all of which are present in +the example: + +@table @emph +@item The Option Field Tags. +When you invoke one of these buttons, you will be asked to choose +between a number of different options. This is how you edit an option +field. Option fields are created by the @code{menu-choice} widget. In +the example, @samp{@b{Choose}} is an option field tag. +@item The @samp{@b{[INS]}} and @samp{@b{[DEL]}} buttons. +Activating these will insert or delete elements from a editable list. +The list is created by the @code{editable-list} widget. +@item Embedded Buttons. +The @samp{@b{_other work_}} is an example of an embedded +button. Embedded buttons are not associated with a fields, but can serve +any purpose, such as implementing hypertext references. They are +usually created by the @code{link} widget. +@item The @samp{@b{[ ]}} and @samp{@b{[X]}} buttons. +Activating one of these will convert it to the other. This is useful +for implementing multiple-choice fields. You can create it wit +@item The @samp{@b{( )}} and @samp{@b{(*)}} buttons. +Only one radio button in a @code{radio-button-choice} widget can be +selected at any time. When you invoke one of the unselected radio +buttons, it will be selected and the previous selected radio button will +become unselected. +@item The @samp{@b{[Apply Form]}} @samp{@b{[Reset Form]}} buttons. +These are explicit buttons made with the @code{push-button} widget. The main +difference from the @code{link} widget is that the buttons are will be +displayed as GUI buttons when possible. +enough. +@end table + +To make them easier to locate, buttons are emphasized in the buffer. + +@deffn Face widget-button-face +Face used for buttons. +@end deffn + +@defopt widget-mouse-face +Face used for buttons when the mouse pointer is above it. +@end defopt + +@subsection Navigation + +You can use all the normal Emacs commands to move around in a form +buffer, plus you will have these additional commands: + +@table @kbd +@item @key{TAB} +@deffn Command widget-forward &optional count +Move point @var{count} buttons or editing fields forward. +@end deffn +@item @key{M-TAB} +@deffn Command widget-backward &optional count +Move point @var{count} buttons or editing fields backward. +@end deffn +@end table + +@node Programming Example, Setting Up the Buffer, User Interface, Top +@comment node-name, next, previous, up +@section Programming Example + +Here is the code to implement the user interface example (@pxref{User +Interface}). + +@lisp +(require 'widget) + +(eval-when-compile + (require 'wid-edit)) + +(defvar widget-example-repeat) + +(defun widget-example () + "Create the widgets from the Widget manual." + (interactive) + (switch-to-buffer "*Widget Example*") + (kill-all-local-variables) + (make-local-variable 'widget-example-repeat) + (let ((inhibit-read-only t)) + (erase-buffer)) + (widget-insert "Here is some documentation.\n\nName: ") + (widget-create 'editable-field + :size 13 + "My Name") + (widget-create 'menu-choice + :tag "Choose" + :value "This" + :help-echo "Choose me, please!" + :notify (lambda (widget &rest ignore) + (message "%s is a good choice!" + (widget-value widget))) + '(item :tag "This option" :value "This") + '(choice-item "That option") + '(editable-field :menu-tag "No option" "Thus option")) + (widget-insert "Address: ") + (widget-create 'editable-field + "Some Place\nIn some City\nSome country.") + (widget-insert "\nSee also ") + (widget-create 'link + :notify (lambda (&rest ignore) + (widget-value-set widget-example-repeat + '("En" "To" "Tre")) + (widget-setup)) + "other work") + (widget-insert " for more information.\n\nNumbers: count to three below\n") + (setq widget-example-repeat + (widget-create 'editable-list + :entry-format "%i %d %v" + :notify (lambda (widget &rest ignore) + (let ((old (widget-get widget + ':example-length)) + (new (length (widget-value widget)))) + (unless (eq old new) + (widget-put widget ':example-length new) + (message "You can count to %d." new)))) + :value '("One" "Eh, two?" "Five!") + '(editable-field :value "three"))) + (widget-insert "\n\nSelect multiple:\n\n") + (widget-create 'checkbox t) + (widget-insert " This\n") + (widget-create 'checkbox nil) + (widget-insert " That\n") + (widget-create 'checkbox + :notify (lambda (&rest ignore) (message "Tickle")) + t) + (widget-insert " Thus\n\nSelect one:\n\n") + (widget-create 'radio-button-choice + :value "One" + :notify (lambda (widget &rest ignore) + (message "You selected %s" + (widget-value widget))) + '(item "One") '(item "Another One.") '(item "A Final One.")) + (widget-insert "\n") + (widget-create 'push-button + :notify (lambda (&rest ignore) + (if (= (length (widget-value widget-example-repeat)) + 3) + (message "Congratulation!") + (error "Three was the count!"))) + "Apply Form") + (widget-insert " ") + (widget-create 'push-button + :notify (lambda (&rest ignore) + (widget-example)) + "Reset Form") + (widget-insert "\n") + (use-local-map widget-keymap) + (widget-setup)) +@end lisp + +@node Setting Up the Buffer, Basic Types, Programming Example, Top +@comment node-name, next, previous, up +@section Setting Up the Buffer + +Widgets are created with @code{widget-create}, which returns a +@dfn{widget} object. This object can be queried and manipulated by +other widget functions, until it is deleted with @code{widget-delete}. +After the widgets have been created, @code{widget-setup} must be called +to enable them. + +@defun widget-create type [ keyword argument ]@dots{} +Create and return a widget of type @var{type}. +The syntax for the @var{type} argument is described in @ref{Basic Types}. + +The keyword arguments can be used to overwrite the keyword arguments +that are part of @var{type}. +@end defun + +@defun widget-delete widget +Delete @var{widget} and remove it from the buffer. +@end defun + +@defun widget-setup +Setup a buffer to support widgets. + +This should be called after creating all the widgets and before allowing +the user to edit them. +@refill +@end defun + +If you want to insert text outside the widgets in the form, the +recommended way to do that is with @code{widget-insert}. + +@defun widget-insert +Insert the arguments, either strings or characters, at point. +The inserted text will be read only. +@end defun + +There is a standard widget keymap which you might find useful. + +@defvr Const widget-keymap +A keymap with the global keymap as its parent.@* +@key{TAB} and @kbd{C-@key{TAB}} are bound to @code{widget-forward} and +@code{widget-backward}, respectively. @kbd{@key{RET}} and @kbd{mouse-2} +are bound to @code{widget-button-press} and +@code{widget-button-}.@refill +@end defvr + +@defvar widget-global-map +Keymap used by @code{widget-button-press} and @code{widget-button-click} +when not on a button. By default this is @code{global-map}. +@end defvar + +@node Basic Types, Sexp Types, Setting Up the Buffer, Top +@comment node-name, next, previous, up +@section Basic Types + +The syntax of a type specification is given below: + +@example +NAME ::= (NAME [KEYWORD ARGUMENT]... ARGS) + | NAME +@end example + +Where, @var{name} is a widget name, @var{keyword} is the name of a +property, @var{argument} is the value of the property, and @var{args} +are interpreted in a widget specific way. + +There following keyword arguments that apply to all widgets: + +@table @code +@item :value +The initial value for widgets of this type. + +@item :format +This string will be inserted in the buffer when you create a widget. +The following @samp{%} escapes are available: + +@table @samp +@item %[ +@itemx %] +The text inside will be marked as a button. + +By default, the text will be shown in @code{widget-button-face}, and +surrounded by brackets. + +@defopt widget-button-prefix +String to prefix buttons. +@end defopt + +@defopt widget-button-suffix +String to suffix buttons. +@end defopt + +@item %@{ +@itemx %@} +The text inside will be displayed with the face specified by +@code{:sample-face}. + +@item %v +This will be replaces with the buffer representation of the widgets +value. What this is depends on the widget type. + +@item %d +Insert the string specified by @code{:doc} here. + +@item %h +Like @samp{%d}, with the following modifications: If the documentation +string is more than one line, it will add a button which will toggle +between showing only the first line, and showing the full text. +Furthermore, if there is no @code{:doc} property in the widget, it will +instead examine the @code{:documentation-property} property. If it is a +lambda expression, it will be called with the widget's value as an +argument, and the result will be used as the documentation text. + +@item %t +Insert the string specified by @code{:tag} here, or the @code{princ} +representation of the value if there is no tag. + +@item %% +Insert a literal @samp{%}. +@end table + +@item :button-face +Face used to highlight text inside %[ %] in the format. + +@item :button-prefix +@itemx :button-suffix + +Text around %[ %] in the format. + +These can be +@table @emph +@item nil +No text is inserted. + +@item a string +The string is inserted literally. + +@item a symbol +The value of the symbol is expanded according to this table. +@end table + +@item :doc +The string inserted by the @samp{%d} escape in the format +string. + +@item :tag +The string inserted by the @samp{%t} escape in the format +string. + +@item :tag-glyph +Name of image to use instead of the string specified by `:tag' on +Emacsen that supports it. + +@item :help-echo +Message displayed whenever you move to the widget with either +@code{widget-forward} or @code{widget-backward}. + +@item :indent +An integer indicating the absolute number of spaces to indent children +of this widget. + +@item :offset +An integer indicating how many extra spaces to add to the widget's +grandchildren compared to this widget. + +@item :extra-offset +An integer indicating how many extra spaces to add to the widget's +children compared to this widget. + +@item :notify +A function called each time the widget or a nested widget is changed. +The function is called with two or three arguments. The first argument +is the widget itself, the second argument is the widget that was +changed, and the third argument is the event leading to the change, if +any. + +@item :menu-tag +Tag used in the menu when the widget is used as an option in a +@code{menu-choice} widget. + +@item :menu-tag-get +Function used for finding the tag when the widget is used as an option +in a @code{menu-choice} widget. By default, the tag used will be either the +@code{:menu-tag} or @code{:tag} property if present, or the @code{princ} +representation of the @code{:value} property if not. + +@item :match +Should be a function called with two arguments, the widget and a value, +and returning non-nil if the widget can represent the specified value. + +@item :validate +A function which takes a widget as an argument, and return nil if the +widgets current value is valid for the widget. Otherwise, it should +return the widget containing the invalid data, and set that widgets +@code{:error} property to a string explaining the error. + +The following predefined function can be used: + +@defun widget-children-validate widget +All the @code{:children} of @var{widget} must be valid. +@end defun + +@item :tab-order +Specify the order in which widgets are traversed with +@code{widget-forward} or @code{widget-backward}. This is only partially +implemented. + +@enumerate a +@item +Widgets with tabbing order @code{-1} are ignored. + +@item +(Unimplemented) When on a widget with tabbing order @var{n}, go to the +next widget in the buffer with tabbing order @var{n+1} or @code{nil}, +whichever comes first. + +@item +When on a widget with no tabbing order specified, go to the next widget +in the buffer with a positive tabbing order, or @code{nil} +@end enumerate + +@item :parent +The parent of a nested widget (e.g. a @code{menu-choice} item or an +element of a @code{editable-list} widget). + +@item :sibling-args +This keyword is only used for members of a @code{radio-button-choice} or +@code{checklist}. The value should be a list of extra keyword +arguments, which will be used when creating the @code{radio-button} or +@code{checkbox} associated with this item. + +@end table + +@deffn {User Option} widget-glyph-directory +Directory where glyphs are found. +Widget will look here for a file with the same name as specified for the +image, with either a @samp{.xpm} (if supported) or @samp{.xbm} extension. +@end deffn + +@deffn{User Option} widget-glyph-enable +If non-nil, allow glyphs to appear on displays where they are supported. +@end deffn + + +@menu +* link:: +* url-link:: +* info-link:: +* push-button:: +* editable-field:: +* text:: +* menu-choice:: +* radio-button-choice:: +* item:: +* choice-item:: +* toggle:: +* checkbox:: +* checklist:: +* editable-list:: +* group:: +@end menu + +@node link, url-link, Basic Types, Basic Types +@comment node-name, next, previous, up +@subsection The @code{link} Widget + +Syntax: + +@example +TYPE ::= (link [KEYWORD ARGUMENT]... [ VALUE ]) +@end example + +The @var{value}, if present, is used to initialize the @code{:value} +property. The value should be a string, which will be inserted in the +buffer. + +By default the link will be shown in brackets. + +@defopt widget-link-prefix +String to prefix links. +@end defopt + +@defopt widget-link-suffix +String to suffix links. +@end defopt + +@node url-link, info-link, link, Basic Types +@comment node-name, next, previous, up +@subsection The @code{url-link} Widget + +Syntax: + +@example +TYPE ::= (url-link [KEYWORD ARGUMENT]... URL) +@end example + +When this link is invoked, the @sc{www} browser specified by +@code{browse-url-browser-function} will be called with @var{url}. + +@node info-link, push-button, url-link, Basic Types +@comment node-name, next, previous, up +@subsection The @code{info-link} Widget + +Syntax: + +@example +TYPE ::= (info-link [KEYWORD ARGUMENT]... ADDRESS) +@end example + +When this link is invoked, the build-in info browser is started on +@var{address}. + +@node push-button, editable-field, info-link, Basic Types +@comment node-name, next, previous, up +@subsection The @code{push-button} Widget + +Syntax: + +@example +TYPE ::= (push-button [KEYWORD ARGUMENT]... [ VALUE ]) +@end example + +The @var{value}, if present, is used to initialize the @code{:value} +property. The value should be a string, which will be inserted in the +buffer. + +By default the tag will be shown in brackets. + +@defopt widget-push-button-prefix +String to prefix push buttons. +@end defopt + +@defopt widget-push-button-suffix +String to suffix push buttons. +@end defopt + +@node editable-field, text, push-button, Basic Types +@comment node-name, next, previous, up +@subsection The @code{editable-field} Widget + +Syntax: + +@example +TYPE ::= (editable-field [KEYWORD ARGUMENT]... [ VALUE ]) +@end example + +The @var{value}, if present, is used to initialize the @code{:value} +property. The value should be a string, which will be inserted in +field. This widget will match all string values. + +The following extra properties are recognized. + +@table @code +@item :size +The width of the editable field.@* +By default the field will reach to the end of the line. + +@item :value-face +Face used for highlighting the editable field. Default is +@code{widget-field-face}. + +@item :secret +Character used to display the value. You can set this to e.g. @code{?*} +if the field contains a password or other secret information. By +default, the value is not secret. + +@item :valid-regexp +By default the @code{:validate} function will match the content of the +field with the value of this attribute. The default value is @code{""} +which matches everything. + +@item :keymap +Keymap used in the editable field. The default value is +@code{widget-field-keymap}, which allows you to use all the normal +editing commands, even if the buffers major mode suppress some of them. +Pressing return invokes the function specified by @code{:action}. +@end table + +@node text, menu-choice, editable-field, Basic Types +@comment node-name, next, previous, up +@subsection The @code{text} Widget + +This is just like @code{editable-field}, but intended for multiline text +fields. The default @code{:keymap} is @code{widget-text-keymap}, which +does not rebind the return key. + +@node menu-choice, radio-button-choice, text, Basic Types +@comment node-name, next, previous, up +@subsection The @code{menu-choice} Widget + +Syntax: + +@example +TYPE ::= (menu-choice [KEYWORD ARGUMENT]... TYPE ... ) +@end example + +The @var{type} arguments represents each possible choice. The widgets +value of will be the value of the chosen @var{type} argument. This +widget will match any value that matches at least one of the specified +@var{type} arguments. + +@table @code +@item :void +Widget type used as a fallback when the value does not match any of the +specified @var{type} arguments. + +@item :case-fold +Set this to nil if you don't want to ignore case when prompting for a +choice through the minibuffer. + +@item :children +A list whose car is the widget representing the currently chosen type in +the buffer. + +@item :choice +The current chosen type + +@item :args +The list of types. +@end table + +@node radio-button-choice, item, menu-choice, Basic Types +@comment node-name, next, previous, up +@subsection The @code{radio-button-choice} Widget + +Syntax: + +@example +TYPE ::= (radio-button-choice [KEYWORD ARGUMENT]... TYPE ... ) +@end example + +The @var{type} arguments represents each possible choice. The widgets +value of will be the value of the chosen @var{type} argument. This +widget will match any value that matches at least one of the specified +@var{type} arguments. + +The following extra properties are recognized. + +@table @code +@item :entry-format +This string will be inserted for each entry in the list. +The following @samp{%} escapes are available: +@table @samp +@item %v +Replaced with the buffer representation of the @var{type} widget. +@item %b +Replace with the radio button. +@item %% +Insert a literal @samp{%}. +@end table + +@item button-args +A list of keywords to pass to the radio buttons. Useful for setting +e.g. the @samp{:help-echo} for each button. + +@item :buttons +The widgets representing the radio buttons. + +@item :children +The widgets representing each type. + +@item :choice +The current chosen type + +@item :args +The list of types. +@end table + +You can add extra radio button items to a @code{radio-button-choice} +widget after it has been created with the function +@code{widget-radio-add-item}. + +@defun widget-radio-add-item widget type +Add to @code{radio-button-choice} widget @var{widget} a new radio button item of type +@var{type}. +@end defun + +Please note that such items added after the @code{radio-button-choice} +widget has been created will @strong{not} be properly destructed when +you call @code{widget-delete}. + +@node item, choice-item, radio-button-choice, Basic Types +@comment node-name, next, previous, up +@subsection The @code{item} Widget + +Syntax: + +@example +ITEM ::= (item [KEYWORD ARGUMENT]... VALUE) +@end example + +The @var{value}, if present, is used to initialize the @code{:value} +property. The value should be a string, which will be inserted in the +buffer. This widget will only match the specified value. + +@node choice-item, toggle, item, Basic Types +@comment node-name, next, previous, up +@subsection The @code{choice-item} Widget + +Syntax: + +@example +ITEM ::= (choice-item [KEYWORD ARGUMENT]... VALUE) +@end example + +The @var{value}, if present, is used to initialize the @code{:value} +property. The value should be a string, which will be inserted in the +buffer as a button. Activating the button of a @code{choice-item} is +equivalent to activating the parent widget. This widget will only match +the specified value. + +@node toggle, checkbox, choice-item, Basic Types +@comment node-name, next, previous, up +@subsection The @code{toggle} Widget + +Syntax: + +@example +TYPE ::= (toggle [KEYWORD ARGUMENT]...) +@end example + +The widget has two possible states, `on' and `off', which corresponds to +a @code{t} or @code{nil} value. + +The following extra properties are recognized. + +@table @code +@item :on +String representing the `on' state. By default the string @samp{on}. +@item :off +String representing the `off' state. By default the string @samp{off}. +@item :on-glyph +Name of a glyph to be used instead of the `:on' text string, on emacsen +that supports it. +@item :off-glyph +Name of a glyph to be used instead of the `:off' text string, on emacsen +that supports it. +@end table + +@node checkbox, checklist, toggle, Basic Types +@comment node-name, next, previous, up +@subsection The @code{checkbox} Widget + +The widget has two possible states, `selected' and `unselected', which +corresponds to a @code{t} or @code{nil} value. + +Syntax: + +@example +TYPE ::= (checkbox [KEYWORD ARGUMENT]...) +@end example + +@node checklist, editable-list, checkbox, Basic Types +@comment node-name, next, previous, up +@subsection The @code{checklist} Widget + +Syntax: + +@example +TYPE ::= (checklist [KEYWORD ARGUMENT]... TYPE ... ) +@end example + +The @var{type} arguments represents each checklist item. The widgets +value of will be a list containing the value of each ticked @var{type} +argument. The checklist widget will match a list whose elements all +matches at least one of the specified @var{type} arguments. + +The following extra properties are recognized. + +@table @code +@item :entry-format +This string will be inserted for each entry in the list. +The following @samp{%} escapes are available: +@table @samp +@item %v +Replaced with the buffer representation of the @var{type} widget. +@item %b +Replace with the checkbox. +@item %% +Insert a literal @samp{%}. +@end table + +@item :greedy +Usually, a checklist will only match if the items are in the exact +sequence given in the specification. By setting @code{:greedy} to +non-nil, it will allow the items to come in any sequence. However, if +you extract the value they will be in the sequence given in the +checklist. I.e. the original sequence is forgotten. + +@item button-args +A list of keywords to pass to the checkboxes. Useful for setting +e.g. the @samp{:help-echo} for each checkbox. + +@item :buttons +The widgets representing the checkboxes. + +@item :children +The widgets representing each type. + +@item :args +The list of types. +@end table + +@node editable-list, group, checklist, Basic Types +@comment node-name, next, previous, up +@subsection The @code{editable-list} Widget + +Syntax: + +@example +TYPE ::= (editable-list [KEYWORD ARGUMENT]... TYPE) +@end example + +The value is a list, where each member represents one widget of type +@var{type}. + +The following extra properties are recognized. + +@table @code +@item :entry-format +This string will be inserted for each entry in the list. +The following @samp{%} escapes are available: +@table @samp +@item %v +This will be replaced with the buffer representation of the @var{type} +widget. +@item %i +Insert the @b{[INS]} button. +@item %d +Insert the @b{[DEL]} button. +@item %% +Insert a literal @samp{%}. +@end table + +@item :insert-button-args +A list of keyword arguments to pass to the insert buttons. + +@item :delete-button-args +A list of keyword arguments to pass to the delete buttons. + +@item :append-button-args +A list of keyword arguments to pass to the trailing insert button. + + +@item :buttons +The widgets representing the insert and delete buttons. + +@item :children +The widgets representing the elements of the list. + +@item :args +List whose car is the type of the list elements. + +@end table + +@node group, , editable-list, Basic Types +@comment node-name, next, previous, up +@subsection The @code{group} Widget + +This widget simply group other widget together. + +Syntax: + +@example +TYPE ::= (group [KEYWORD ARGUMENT]... TYPE...) +@end example + +The value is a list, with one member for each @var{type}. + +@node Sexp Types, Widget Properties, Basic Types, Top +@comment +@section Sexp Types + +A number of widgets for editing s-expressions (lisp types) are also +available. These basically fall in the following categories. + +@menu +* constants:: +* generic:: +* atoms:: +* composite:: +@end menu + +@node constants, generic, Sexp Types, Sexp Types +@comment node-name, next, previous, up +@subsection The Constant Widgets. + +The @code{const} widget can contain any lisp expression, but the user is +prohibited from editing edit it, which is mainly useful as a component +of one of the composite widgets. + +The syntax for the @code{const} widget is + +@example +TYPE ::= (const [KEYWORD ARGUMENT]... [ VALUE ]) +@end example + +The @var{value}, if present, is used to initialize the @code{:value} +property and can be any s-expression. + +@deffn Widget const +This will display any valid s-expression in an immutable part of the +buffer. +@end deffn + +There are two variations of the @code{const} widget, namely +@code{variable-item} and @code{function-item}. These should contain a +symbol with a variable or function binding. The major difference from +the @code{const} widget is that they will allow the user to see the +variable or function documentation for the symbol. + +@deffn Widget variable-item +An immutable symbol that is bound as a variable. +@end deffn + +@deffn Widget function-item +An immutable symbol that is bound as a function. +@end deffn + +@node generic, atoms, constants, Sexp Types +@comment node-name, next, previous, up +@subsection Generic Sexp Widget. + +The @code{sexp} widget can contain any lisp expression, and allows the +user to edit it inline in the buffer. + +The syntax for the @code{sexp} widget is + +@example +TYPE ::= (sexp [KEYWORD ARGUMENT]... [ VALUE ]) +@end example + +@deffn Widget sexp +This will allow you to edit any valid s-expression in an editable buffer +field. + +The @code{sexp} widget takes the same keyword arguments as the +@code{editable-field} widget. +@end deffn + +@node atoms, composite, generic, Sexp Types +@comment node-name, next, previous, up +@subsection Atomic Sexp Widgets. + +The atoms are s-expressions that does not consist of other +s-expressions. A string is an atom, while a list is a composite type. +You can edit the value of an atom with the following widgets. + +The syntax for all the atoms are + +@example +TYPE ::= (NAME [KEYWORD ARGUMENT]... [ VALUE ]) +@end example + +The @var{value}, if present, is used to initialize the @code{:value} +property and must be an expression of the same type as the widget. +I.e. the string widget can only be initialized with a string. + +All the atom widgets take the same keyword arguments as the +@code{editable-field} widget. + +@deffn Widget string +Allows you to edit a string in an editable field. +@end deffn + +@deffn Widget regexp +Allows you to edit a regular expression in an editable field. +@end deffn + +@deffn Widget character +Allows you to enter a character in an editable field. +@end deffn + +@deffn Widget file +Allows you to edit a file name in an editable field. If you invoke +the tag button, you can edit the file name in the mini-buffer with +completion. + +Keywords: +@table @code +@item :must-match +If this is set to non-nil, only existing file names will be allowed in +the minibuffer. +@end table +@end deffn + +@deffn Widget directory +Allows you to edit a directory name in an editable field. +Similar to the @code{file} widget. +@end deffn + +@deffn Widget symbol +Allows you to edit a lisp symbol in an editable field. +@end deffn + +@deffn Widget function +Allows you to edit a lambda expression, or a function name with completion. +@end deffn + +@deffn Widget variable +Allows you to edit a variable name, with completion. +@end deffn + +@deffn Widget integer +Allows you to edit an integer in an editable field. +@end deffn + +@deffn Widget number +Allows you to edit a number in an editable field. +@end deffn + +@deffn Widget boolean +Allows you to edit a boolean. In lisp this means a variable which is +either nil meaning false, or non-nil meaning true. +@end deffn + + +@node composite, , atoms, Sexp Types +@comment node-name, next, previous, up +@subsection Composite Sexp Widgets. + +The syntax for the composite are + +@example +TYPE ::= (NAME [KEYWORD ARGUMENT]... COMPONENT...) +@end example + +Where each @var{component} must be a widget type. Each component widget +will be displayed in the buffer, and be editable to the user. + +@deffn Widget cons +The value of a @code{cons} widget is a cons-cell where the car is the +value of the first component and the cdr is the value of the second +component. There must be exactly two components. +@end deffn + +@deffn Widget list +The value of a @code{list} widget is a list containing the value of +each of its component. +@end deffn + +@deffn Widget vector +The value of a @code{vector} widget is a vector containing the value of +each of its component. +@end deffn + +The above suffice for specifying fixed size lists and vectors. To get +variable length lists and vectors, you can use a @code{choice}, +@code{set} or @code{repeat} widgets together with the @code{:inline} +keywords. If any component of a composite widget has the @code{:inline} +keyword set, its value must be a list which will then be spliced into +the composite. For example, to specify a list whose first element must +be a file name, and whose remaining arguments should either by the +symbol @code{t} or two files, you can use the following widget +specification: + +@example +(list file + (choice (const t) + (list :inline t + :value ("foo" "bar") + string string))) +@end example + +The value of a widget of this type will either have the form +@samp{(file t)} or @code{(file string string)}. + +This concept of inline is probably hard to understand. It was certainly +hard to implement so instead of confuse you more by trying to explain it +here, I'll just suggest you meditate over it for a while. + +@deffn Widget choice +Allows you to edit a sexp which may have one of fixed set of types. It +is currently implemented with the @code{choice-menu} basic widget, and +has a similar syntax. +@end deffn + +@deffn Widget set +Allows you to specify a type which must be a list whose elements all +belong to given set. The elements of the list is not significant. This +is implemented on top of the @code{checklist} basic widget, and has a +similar syntax. +@end deffn + +@deffn Widget repeat +Allows you to specify a variable length list whose members are all of +the same type. Implemented on top of the `editable-list' basic widget, +and has a similar syntax. +@end deffn + +@node Widget Properties, Defining New Widgets, Sexp Types, Top +@comment node-name, next, previous, up +@section Properties + +You can examine or set the value of a widget by using the widget object +that was returned by @code{widget-create}. + +@defun widget-value widget +Return the current value contained in @var{widget}. +It is an error to call this function on an uninitialized widget. +@end defun + +@defun widget-value-set widget value +Set the value contained in @var{widget} to @var{value}. +It is an error to call this function with an invalid @var{value}. +@end defun + +@strong{Important:} You @emph{must} call @code{widget-setup} after +modifying the value of a widget before the user is allowed to edit the +widget again. It is enough to call @code{widget-setup} once if you +modify multiple widgets. This is currently only necessary if the widget +contains an editing field, but may be necessary for other widgets in the +future. + +If your application needs to associate some information with the widget +objects, for example a reference to the item being edited, it can be +done with @code{widget-put} and @code{widget-get}. The property names +must begin with a @samp{:}. + +@defun widget-put widget property value +In @var{widget} set @var{property} to @var{value}. +@var{property} should be a symbol, while @var{value} can be anything. +@end defun + +@defun widget-get widget property +In @var{widget} return the value for @var{property}. +@var{property} should be a symbol, the value is what was last set by +@code{widget-put} for @var{property}. +@end defun + +@defun widget-member widget property +Non-nil if @var{widget} has a value (even nil) for property @var{property}. +@end defun + +Occasionally it can be useful to know which kind of widget you have, +i.e. the name of the widget type you gave when the widget was created. + +@defun widget-type widget +Return the name of @var{widget}, a symbol. +@end defun + +Widgets can be in two states: active, which means they are modifiable by +the user, or inactive, which means they cannot be modified by the user. +You can query or set the state with the following code: + +@lisp +;; Examine if @var{widget} is active or not. +(if (widget-apply @var{widget} :active) + (message "Widget is active.") + (message "Widget is inactive.") + +;; Make @var{widget} inactive. +(widget-apply @var{widget} :deactivate) + +;; Make @var{widget} active. +(widget-apply @var{widget} :activate) +@end lisp + +A widget is inactive if itself, or any of its ancestors (found by +following the @code{:parent} link) have been deactivated. To make sure +a widget is really active, you must therefore activate both itself, and +all its ancestors. + +@lisp +(while widget + (widget-apply widget :activate) + (setq widget (widget-get widget :parent))) +@end lisp + +You can check if a widget has been made inactive by examining the value +of @code{:inactive} keyword. If this is non-nil, the widget itself has +been deactivated. This is different from using the @code{:active} +keyword, in that the later tell you if the widget @strong{or} any of its +ancestors have been deactivated. Do not attempt to set the +@code{:inactive} keyword directly. Use the @code{:activate} +@code{:deactivated} keywords instead. + + +@node Defining New Widgets, Widget Browser, Widget Properties, Top +@comment node-name, next, previous, up +@section Defining New Widgets + +You can define specialized widgets with @code{define-widget}. It allows +you to create a shorthand for more complex widgets, including specifying +component widgets and default new default values for the keyword +arguments. + +@defun widget-define name class doc &rest args +Define a new widget type named @var{name} from @code{class}. + +@var{name} and class should both be symbols, @code{class} should be one +of the existing widget types. + +The third argument @var{DOC} is a documentation string for the widget. + +After the new widget has been defined, the following two calls will +create identical widgets: + +@itemize @bullet +@item +@lisp +(widget-create @var{name}) +@end lisp + +@item +@lisp +(apply widget-create @var{class} @var{args}) +@end lisp +@end itemize + +@end defun + +Using @code{widget-define} does just store the definition of the widget +type in the @code{widget-type} property of @var{name}, which is what +@code{widget-create} uses. + +If you just want to specify defaults for keywords with no complex +conversions, you can use @code{identity} as your conversion function. + +The following additional keyword arguments are useful when defining new +widgets: +@table @code +@item :convert-widget +Function to convert a widget type before creating a widget of that +type. It takes a widget type as an argument, and returns the converted +widget type. When a widget is created, this function is called for the +widget type and all the widgets parent types, most derived first. + +The following predefined functions can be used here: + +@defun widget-types-convert-widget widget +Convert @code{:args} as widget types in @var{widget}. +@end defun + +@defun widget-value-convert-widget widget +Initialize @code{:value} from @code{:args} in @var{widget}. +@end defun + +@item :value-to-internal +Function to convert the value to the internal format. The function +takes two arguments, a widget and an external value, and returns the +internal value. The function is called on the present @code{:value} +when the widget is created, and on any value set later with +@code{widget-value-set}. + +@item :value-to-external +Function to convert the value to the external format. The function +takes two arguments, a widget and an internal value, and returns the +internal value. The function is called on the present @code{:value} +when the widget is created, and on any value set later with +@code{widget-value-set}. + +@item :create +Function to create a widget from scratch. The function takes one +argument, a widget type, and create a widget of that type, insert it in +the buffer, and return a widget object. + +@item :delete +Function to delete a widget. The function takes one argument, a widget, +and should remove all traces of the widget from the buffer. + +@item :value-create +Function to expand the @samp{%v} escape in the format string. It will +be called with the widget as its argument. Should +insert a representation of the widgets value in the buffer. + +@item :value-delete +Should remove the representation of the widgets value from the buffer. +It will be called with the widget as its argument. It doesn't have to +remove the text, but it should release markers and delete nested widgets +if such has been used. + +The following predefined function can be used here: + +@defun widget-children-value-delete widget +Delete all @code{:children} and @code{:buttons} in @var{widget}. +@end defun + +@item :value-get +Function to extract the value of a widget, as it is displayed in the +buffer. + +The following predefined function can be used here: + +@defun widget-value-value-get widget +Return the @code{:value} property of @var{widget}. +@end defun + +@item :format-handler +Function to handle unknown @samp{%} escapes in the format string. It +will be called with the widget and the escape character as arguments. +You can set this to allow your widget to handle non-standard escapes. + +You should end up calling @code{widget-default-format-handler} to handle +unknown escape sequences, which will handle the @samp{%h} and any future +escape sequences, as well as give an error for unknown escapes. + +@item :action +Function to handle user initiated events. By default, @code{:notify} +the parent. + +The following predefined function can be used here: + +@defun widget-parent-action widget &optional event +Tell @code{:parent} of @var{widget} to handle the @code{:action}. +Optional @var{event} is the event that triggered the action. +@end defun + +@item :prompt-value +Function to prompt for a value in the minibuffer. The function should +take four arguments, @var{widget}, @var{prompt}, @var{value}, and +@var{unbound} and should return a value for widget entered by the user. +@var{prompt} is the prompt to use. @var{value} is the default value to +use, unless @var{unbound} is non-nil in which case there are no default +value. The function should read the value using the method most natural +for this widget, and does not have to check that it matches. +@end table + +If you want to define a new widget from scratch, use the @code{default} +widget as its base. + +@deffn Widget default +Widget used as a base for other widgets. + +It provides most of the functionality that is referred to as ``by +default'' in this text. +@end deffn + +@node Widget Browser, Widget Minor Mode, Defining New Widgets, Top +@comment node-name, next, previous, up +@section Widget Browser + +There is a separate package to browse widgets. This is intended to help +programmers who want to examine the content of a widget. The browser +shows the value of each keyword, but uses links for certain keywords +such as `:parent', which avoids printing cyclic structures. + +@deffn Command widget-browse WIDGET +Create a widget browser for WIDGET. +When called interactively, prompt for WIDGET. +@end deffn + +@deffn Command widget-browse-other-window WIDGET +Create a widget browser for WIDGET and show it in another window. +When called interactively, prompt for WIDGET. +@end deffn + +@deffn Command widget-browse-at POS +Create a widget browser for the widget at POS. +When called interactively, use the position of point. +@end deffn + +@node Widget Minor Mode, Utilities, Widget Browser, Top +@comment node-name, next, previous, up +@section Widget Minor Mode + +There is a minor mode for manipulating widgets in major modes that +doesn't provide any support for widgets themselves. This is mostly +intended to be useful for programmers doing experiments. + +@deffn Command widget-minor-mode +Toggle minor mode for traversing widgets. +With arg, turn widget mode on if and only if arg is positive. +@end deffn + +@defvar widget-minor-mode-keymap +Keymap used in @code{widget-minor-mode}. +@end defvar + +@node Utilities, Widget Wishlist, Widget Minor Mode, Top +@comment node-name, next, previous, up +@section Utilities. + +@defun widget-prompt-value widget prompt [ value unbound ] +Prompt for a value matching @var{widget}, using @var{prompt}. +The current value is assumed to be @var{value}, unless @var{unbound} is +non-nil.@refill +@end defun + +@defun widget-get-sibling widget +Get the item @var{widget} is assumed to toggle. +This is only meaningful for radio buttons or checkboxes in a list. +@end defun + +@node Widget Wishlist, , Utilities, Top +@comment node-name, next, previous, up +@section Wishlist + +@itemize @bullet +@item +It should be possible to add or remove items from a list with @kbd{C-k} +and @kbd{C-o} (suggested by @sc{rms}). + +@item +The @samp{[INS]} and @samp{[DEL]} buttons should be replaced by a single +dash (@samp{-}). The dash should be a button that, when invoked, ask +whether you want to add or delete an item (@sc{rms} wanted to git rid of +the ugly buttons, the dash is my idea). + +@item +The @code{menu-choice} tag should be prettier, something like the abbreviated +menus in Open Look. + +@item +Finish @code{:tab-order}. + +@item +Make indentation work with glyphs and proportional fonts. + +@item +Add commands to show overview of object and class hierarchies to the +browser. + +@item +Find a way to disable mouse highlight for inactive widgets. + +@item +Find a way to make glyphs look inactive. + +@item +Add @code{property-list} widget. + +@item +Add @code{association-list} widget. + +@item +Add @code{key-binding} widget. + +@item +Add @code{widget} widget for editing widget specifications. + +@item +Find clean way to implement variable length list. +See @code{TeX-printer-list} for an explanation. + +@item +@kbd{C-h} in @code{widget-prompt-value} should give type specific help. + +@item +A mailto widget. + +@end itemize + +@contents +@bye diff --git a/man/windows.texi b/man/windows.texi new file mode 100644 index 00000000000..a0e72558d35 --- /dev/null +++ b/man/windows.texi @@ -0,0 +1,354 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 86, 87, 93, 94, 95, 1997 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Windows, Frames, Buffers, Top +@chapter Multiple Windows +@cindex windows in Emacs +@cindex multiple windows in Emacs + + Emacs can split a frame into two or many windows. Multiple windows +can display parts of different buffers, or different parts of one +buffer. Multiple frames always imply multiple windows, because each +frame has its own set of windows. Each window belongs to one and only +one frame. + +@menu +* Basic Window:: Introduction to Emacs windows. +* Split Window:: New windows are made by splitting existing windows. +* Other Window:: Moving to another window or doing something to it. +* Pop Up Window:: Finding a file or buffer in another window. +* Force Same Window:: Forcing certain buffers to appear in the selected + window rather than in another window. +* Change Window:: Deleting windows and changing their sizes. +@end menu + +@node Basic Window +@section Concepts of Emacs Windows + + Each Emacs window displays one Emacs buffer at any time. A single +buffer may appear in more than one window; if it does, any changes in +its text are displayed in all the windows where it appears. But the +windows showing the same buffer can show different parts of it, because +each window has its own value of point. + +@cindex selected window + At any time, one of the windows is the @dfn{selected window}; the +buffer this window is displaying is the current buffer. The terminal's +cursor shows the location of point in this window. Each other window +has a location of point as well, but since the terminal has only one +cursor there is no way to show where those locations are. When multiple +frames are visible in X Windows, each frame has a cursor which appears +in the frame's selected window. The cursor in the selected frame is +solid; the cursor in other frames is a hollow box. + + Commands to move point affect the value of point for the selected Emacs +window only. They do not change the value of point in any other Emacs +window, even one showing the same buffer. The same is true for commands +such as @kbd{C-x b} to change the selected buffer in the selected window; +they do not affect other windows at all. However, there are other commands +such as @kbd{C-x 4 b} that select a different window and switch buffers in +it. Also, all commands that display information in a window, including +(for example) @kbd{C-h f} (@code{describe-function}) and @kbd{C-x C-b} +(@code{list-buffers}), work by switching buffers in a nonselected window +without affecting the selected window. + + When multiple windows show the same buffer, they can have different +regions, because they can have different values of point. However, +they all have the same value for the mark, because each buffer has +only one mark position. + + Each window has its own mode line, which displays the buffer name, +modification status and major and minor modes of the buffer that is +displayed in the window. @xref{Mode Line}, for full details on the mode +line. + +@iftex +@break +@end iftex + +@node Split Window +@section Splitting Windows + +@table @kbd +@item C-x 2 +Split the selected window into two windows, one above the other +(@code{split-window-vertically}). +@item C-x 3 +Split the selected window into two windows positioned side by side +(@code{split-window-horizontally}). +@item C-Mouse-2 +In the mode line or scroll bar of a window, split that window. +@end table + +@kindex C-x 2 +@findex split-window-vertically + The command @kbd{C-x 2} (@code{split-window-vertically}) breaks the +selected window into two windows, one above the other. Both windows start +out displaying the same buffer, with the same value of point. By default +the two windows each get half the height of the window that was split; a +numeric argument specifies how many lines to give to the top window. + +@kindex C-x 3 +@findex split-window-horizontally + @kbd{C-x 3} (@code{split-window-horizontally}) breaks the selected +window into two side-by-side windows. A numeric argument specifies how +many columns to give the one on the left. A line of vertical bars +separates the two windows. Windows that are not the full width of the +screen have mode lines, but they are truncated. On terminals where +Emacs does not support highlighting, truncated mode lines sometimes do +not appear in inverse video. + +@kindex C-Mouse-2 @r{(scroll bar)} + You can split a window horizontally or vertically by clicking +@kbd{C-Mouse-2} in the mode line or the scroll bar. The line of +splitting goes through the place where you click: if you click on the +mode line, the new scroll bar goes above the spot; if you click in the +scroll bar, the mode line of the split window is side by side with your +click. + +@vindex truncate-partial-width-windows + When a window is less than the full width, text lines too long to fit are +frequent. Continuing all those lines might be confusing. The variable +@code{truncate-partial-width-windows} can be set non-@code{nil} to force +truncation in all windows less than the full width of the screen, +independent of the buffer being displayed and its value for +@code{truncate-lines}. @xref{Continuation Lines}.@refill + + Horizontal scrolling is often used in side-by-side windows. +@xref{Display}. + +@vindex split-window-keep-point + If @code{split-window-keep-point} is non-@code{nil}, the default, both +of the windows resulting from @kbd{C-x 2} inherit the value of point +from the window that was split. This means that scrolling is +inevitable. If this variable is @code{nil}, then @kbd{C-x 2} tries to +avoid shifting any text the screen, by putting point in each window at a +position already visible in the window. It also selects whichever +window contain the screen line that the cursor was previously on. Some +users prefer the latter mode on slow terminals. + +@node Other Window +@section Using Other Windows + +@table @kbd +@item C-x o +Select another window (@code{other-window}). That is @kbd{o}, not zero. +@item C-M-v +Scroll the next window (@code{scroll-other-window}). +@item M-x compare-windows +Find next place where the text in the selected window does not match +the text in the next window. +@item Mouse-1 +@kbd{Mouse-1}, in a window's mode line, selects that window +but does not move point in it (@code{mouse-select-window}). +@end table + +@kindex C-x o +@findex other-window + To select a different window, click with @kbd{Mouse-1} on its mode +line. With the keyboard, you can switch windows by typing @kbd{C-x o} +(@code{other-window}). That is an @kbd{o}, for `other', not a zero. +When there are more than two windows, this command moves through all the +windows in a cyclic order, generally top to bottom and left to right. +After the rightmost and bottommost window, it goes back to the one at +the upper left corner. A numeric argument means to move several steps +in the cyclic order of windows. A negative argument moves around the +cycle in the opposite order. When the minibuffer is active, the +minibuffer is the last window in the cycle; you can switch from the +minibuffer window to one of the other windows, and later switch back and +finish supplying the minibuffer argument that is requested. +@xref{Minibuffer Edit}. + +@kindex C-M-v +@findex scroll-other-window + The usual scrolling commands (@pxref{Display}) apply to the selected +window only, but there is one command to scroll the next window. +@kbd{C-M-v} (@code{scroll-other-window}) scrolls the window that +@kbd{C-x o} would select. It takes arguments, positive and negative, +like @kbd{C-v}. (In the minibuffer, @kbd{C-M-v} scrolls the window +that contains the minibuffer help display, if any, rather than the +next window in the standard cyclic order.) + + The command @kbd{M-x compare-windows} lets you compare two files or +buffers visible in two windows, by moving through them to the next +mismatch. @xref{Comparing Files}, for details. + +@node Pop Up Window +@section Displaying in Another Window + +@cindex selecting buffers in other windows +@kindex C-x 4 + @kbd{C-x 4} is a prefix key for commands that select another window +(splitting the window if there is only one) and select a buffer in that +window. Different @kbd{C-x 4} commands have different ways of finding the +buffer to select. + +@table @kbd +@item C-x 4 b @var{bufname} @key{RET} +Select buffer @var{bufname} in another window. This runs +@code{switch-to-buffer-other-window}. +@item C-x 4 C-o @var{bufname} @key{RET} +Display buffer @var{bufname} in another window, but +don't select that buffer or that window. This runs +@code{display-buffer}. +@item C-x 4 f @var{filename} @key{RET} +Visit file @var{filename} and select its buffer in another window. This +runs @code{find-file-other-window}. @xref{Visiting}. +@item C-x 4 d @var{directory} @key{RET} +Select a Dired buffer for directory @var{directory} in another window. +This runs @code{dired-other-window}. @xref{Dired}. +@item C-x 4 m +Start composing a mail message in another window. This runs +@code{mail-other-window}; its same-window analogue is @kbd{C-x m} +(@pxref{Sending Mail}). +@item C-x 4 . +Find a tag in the current tags table, in another window. This runs +@code{find-tag-other-window}, the multiple-window variant of @kbd{M-.} +(@pxref{Tags}). +@item C-x 4 r @var{filename} @key{RET} +Visit file @var{filename} read-only, and select its buffer in another +window. This runs @code{find-file-read-only-other-window}. +@xref{Visiting}. +@end table + +@node Force Same Window +@section Forcing Display in the Same Window + + Certain Emacs commands switch to a specific buffer with special +contents. For example, @kbd{M-x shell} switches to a buffer named +@samp{*Shell*}. By convention, all these commands are written to pop up +the buffer in a separate window. But you can specify that certain of +these buffers should appear in the selected window. + +@vindex same-window-buffer-names + If you add a buffer name to the list @code{same-window-buffer-names}, +the effect is that such commands display that particular buffer by +switching to it in the selected window. For example, if you add the +element @code{"*grep*"} to the list, the @code{grep} command will +display its output buffer in the selected window. + + The default value of @code{same-window-buffer-names} is not +@code{nil}: it specifies buffer names @samp{*info*}, @samp{*mail*} and +@samp{*shell*} (as well as others used by more obscure Emacs packages). +This is why @kbd{M-x shell} normally switches to the @samp{*shell*} +buffer in the selected window. If you delete this element from the +value of @code{same-window-buffer-names}, the behavior of @kbd{M-x +shell} will change---it will pop up the buffer in another window +instead. + +@vindex same-window-regexps + You can specify these buffers more generally with the variable +@code{same-window-regexps}. Set it to a list of regular expressions; +then any buffer whose name matches one of those regular expressions is +displayed by switching to it in the selected window. (Once again, this +applies only to buffers that normally get displayed for you in a +separate window.) The default value of this variable specifies Telnet +and rlogin buffers. + + An analogous feature lets you specify buffers which should be +displayed in their own individual frames. @xref{Special Buffer Frames}. + +@node Change Window +@section Deleting and Rearranging Windows + +@table @kbd +@item C-x 0 +Delete the selected window (@code{delete-window}). The last character +in this key sequence is a zero. +@item C-x 1 +Delete all windows in the selected frame except the selected window +(@code{delete-other-windows}). +@item C-x 4 0 +Delete the selected window and kill the buffer that was showing in it +(@code{kill-buffer-and-window}). The last character in this key +sequence is a zero. +@item C-x ^ +Make selected window taller (@code{enlarge-window}). +@item C-x @} +Make selected window wider (@code{enlarge-window-horizontally}). +@item C-x @{ +Make selected window narrower (@code{shrink-window-horizontally}). +@item C-x - +Shrink this window if its buffer doesn't need so many lines +(@code{shrink-window-if-larger-than-buffer}). +@item C-x + +Make all windows the same height (@code{balance-windows}). +@item Drag-Mouse-1 +Dragging a window's mode line up or down with @kbd{Mouse-1} changes +window heights. +@item Mouse-2 +@kbd{Mouse-2} in a window's mode line deletes all other windows in the frame +(@code{mouse-delete-other-windows}). +@item Mouse-3 +@kbd{Mouse-3} in a window's mode line deletes that window +(@code{mouse-delete-window}). +@end table + +@kindex C-x 0 +@findex delete-window + To delete a window, type @kbd{C-x 0} (@code{delete-window}). (That is +a zero.) The space occupied by the deleted window is given to an +adjacent window (but not the minibuffer window, even if that is active +at the time). Once a window is deleted, its attributes are forgotten; +only restoring a window configuration can bring it back. Deleting the +window has no effect on the buffer it used to display; the buffer +continues to exist, and you can select it in any window with @kbd{C-x +b}. + +@findex kill-buffer-and-window +@kindex C-x 4 0 + @kbd{C-x 4 0} (@code{kill-buffer-and-window}) is a stronger command +than @kbd{C-x 0}; it kills the current buffer and then deletes the +selected window. + +@kindex C-x 1 +@findex delete-other-windows + @kbd{C-x 1} (@code{delete-other-windows}) is more powerful in a +different way; it deletes all the windows except the selected one (and +the minibuffer); the selected window expands to use the whole frame +except for the echo area. + + You can also delete a window by clicking on its mode line with +@kbd{Mouse-2}, and delete all the windows in a frame except one window +by clicking on that window's mode line with @kbd{Mouse-3}. + + The easiest way to adjust window heights is with a mouse. If you +press @kbd{Mouse-1} on a mode line, you can drag that mode line up or +down, changing the heights of the windows above and below it. + +@kindex C-x ^ +@findex enlarge-window +@kindex C-x @} +@findex enlarge-window-horizontally +@vindex window-min-height +@vindex window-min-width + To readjust the division of space among vertically adjacent windows, +use @kbd{C-x ^} (@code{enlarge-window}). It makes the currently +selected window get one line bigger, or as many lines as is specified +with a numeric argument. With a negative argument, it makes the +selected window smaller. @kbd{C-x @}} +(@code{enlarge-window-horizontally}) makes the selected window wider by +the specified number of columns. @kbd{C-x @{} +(@code{shrink-window-horizontally}) makes the selected window narrower +by the specified number of columns. + + When you make a window bigger, the space comes from one of its +neighbors. If this makes any window too small, it is deleted and its +space is given to an adjacent window. The minimum size is specified by +the variables @code{window-min-height} and @code{window-min-width}. + +@kindex C-x - +@findex shrink-window-if-larger-than-buffer + The command @kbd{C-x -} (@code{shrink-window-if-larger-than-buffer}) +reduces the height of the selected window, if it is taller than +necessary to show the whole text of the buffer it is displaying. It +gives the extra lines to other windows in the frame. + +@kindex C-x + +@findex balance-windows + You can also use @kbd{C-x +} (@code{balance-windows}) to even out the +heights of all the windows in the selected frame. + + @xref{Minibuffer Edit}, for information about the Resize-Minibuffer +mode, which automatically changes the size of the minibuffer window to +fit the text in the minibuffer. |