diff options
| author | Glenn Morris <rgm@gnu.org> | 2007-09-06 04:50:28 +0000 |
|---|---|---|
| committer | Glenn Morris <rgm@gnu.org> | 2007-09-06 04:50:28 +0000 |
| commit | 8cf51b2c2f18417403f27fdc215f369af887d89b (patch) | |
| tree | 32b8f5cdf35f0c2e674c0f6a3d2e842396080b32 /doc | |
| parent | 19e364e29522a20357a236d8501725db47f7feee (diff) | |
| download | emacs-8cf51b2c2f18417403f27fdc215f369af887d89b.tar.gz | |
Move here from ../../man
Diffstat (limited to 'doc')
59 files changed, 56803 insertions, 0 deletions
diff --git a/doc/emacs/.gitignore b/doc/emacs/.gitignore new file mode 100644 index 00000000000..3ff56b474dd --- /dev/null +++ b/doc/emacs/.gitignore @@ -0,0 +1,23 @@ +*.aux +*.cp +*.cps +*.dvi +*.fn +*.fns +*.ky +*.kys +*.log +*.op +*.ops +*.pdf +*.pg +*.pgs +*.ps +*.tmp +*.toc +*.tp +*.tps +*.vr +*.vrs +Makefile +makefile diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog new file mode 100644 index 00000000000..51803a75727 --- /dev/null +++ b/doc/emacs/ChangeLog @@ -0,0 +1,8267 @@ +2007-09-06 Glenn Morris <rgm@gnu.org> + + * Move manual sources from man/ to subdirectories of doc/. + Split into the Emacs manual in emacs/, and other manuals in misc/. + * Makefile.in (INFO_TARGETS, DVI_TARGETS): Reduce to just the Emacs + manual. + (infodir): New variable. + (info): Use $infodir. + (emacsman): Delete target, not needed any more. + Move all targets that are not the Emacs manual to misc/Makefile.in. + (mostlyclean): Remove `gnustmp'. + * makefile.w32-in (INFO_TARGETS, DVI_TARGETS): Reduce to just the Emacs + manual. + (MULTI_INSTALL_INFO, ENVADD): Go up one more level. + (emacsman): Delete target, not needed any more. + (clean): Remove all info files but Emacs manual. + Move all targets that are not the Emacs manual to misc/Makefile.in. + * emacs-xtra.texi, emacs.texi (setfilename): Go up one more level. + + * Makefile.in (INFOSOURCES): Delete. + (.SUFFIXES): Use $(TEXI2DVI) rather than texi2dvi. + (mostlyclean): Add *.op, *.ops. Move *.aux *.cps *.fns *.kys *.pgs + *.vrs *.toc here... + (maintainer-clean): ...from here. + +2007-09-05 Glenn Morris <rgm@gnu.org> + + * custom.texi (Safe File Variables): Clarify `!' and risky variables. + +2007-09-01 Jay Belanger <jay.p.belanger@gmail.com> + + * calc.texi (Date Conversions): Clarify definition of + Julian day numbering. + (Date Forms): Clarify definition of Julian day numbering; + add some history. + +2007-08-30 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Version 5.07 + +2007-08-29 Glenn Morris <rgm@gnu.org> + + * emacs.texi (EMACSVER): Increase to 23.0.50. + +2007-08-24 IRIE Tetsuya <irie@t.email.ne.jp> (tiny change) + + * message.texi (MIME): Replace mml-attach with mml-attach-file. + +2007-08-22 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Adding hyperlink types): New section. + (Embedded LaTeX): Chapter updated because of LaTeX export. + (LaTeX export): New section. + (Using links out): New section. + +2007-08-22 Glenn Morris <rgm@gnu.org> + + * faq.texi (Learning how to do something): Refcards now in + etc/refcards/ directory. + +2007-08-22 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (Remote Programs): Persistency file must be cleared when + changing `tramp-remote-path'. + (Filename Syntax): Don't use @var{} constructs inside the @trampfn + macro. + +2007-08-17 Eli Zaretskii <eliz@gnu.org> + + * basic.texi (Position Info): Add index entry for face at point. + Mention that character faces are also displayed by "C-u C-x =". + +2007-08-17 Jay Belanger <jay.p.belanger@gmail.com> + + * calc.texi: Move contents to beginning of file. + (Algebraic Entry): Fix the formatting of an example. + +2007-08-15 Jay Belanger <jay.p.belanger@gmail.com> + + * calc.texi (Basic Operations on Units): Mention exact versus + inexact conversions. + +2007-08-14 Jay Belanger <jay.p.belanger@gmail.com> + + * calc.texi (Basic Operations on Units): Mention default + values for new units. + (Quick Calculator Mode): Mention that binary format will + be displayed. + +2007-08-14 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Selecting a Group): Mention gnus-maximum-newsgroup. + +2007-08-10 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (NNTP): Mention nntp-xref-number-is-evil. + +2007-08-08 Glenn Morris <rgm@gnu.org> + + * glossary.texi (Glossary): Deprecate `iff'. + * gnus.texi, sieve.texi: Replace `iff'. + +2007-08-07 Chong Yidong <cyd@stupidchicken.com> + + * files.texi (File Conveniences): Document point motion keys in Image + mode. + +2007-08-03 Jay Belanger <jay.p.belanger@gmail.com> + + * calc.texi (Basic Graphics): Mention the graphing of error + forms. + (Graphics Options): Mention how `g s' handles error forms. + (Curve Fitting): Mention plotting the curves. + (Standard Nonlinear Models): Add additional models. + (Curve Fitting Details): Mention the Levenberg-Marquardt method. + (Linear Fits): Correct result. + +2007-08-01 Alan Mackenzie <acm@muc.de> + + * cc-mode.texi (Mailing Lists and Bug Reports): Correct "-no-site-file" + to "--no-site-file". + +2007-07-29 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (Frequently Asked Questions): Point to mode line + extension in Emacs 23.1. + + * trampver.texi: Update release number. + +2007-07-27 Glenn Morris <rgm@gnu.org> + + * calc.texi (Copying) + * emacs.texi (Copying): Include license text from gpl.texi, rather than + in-line. + + * gpl.texi: New file with text of GPL. + * Makefile.in (EMACSSOURCES): Add gpl.texi. + +2007-07-26 Dan Nicolaescu <dann@ics.uci.edu> + + * vc2-xtra.texi (Customizing VC): Add GIT and HG. + + * dired.texi (Wdired): Mention C-x C-q key binding. + +2007-07-28 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (GDB Graphical Interface): Qualify use of "M-x gdba". + +2007-07-25 Glenn Morris <rgm@gnu.org> + + * calc.texi (Copying) + * emacs.texi (Copying): Replace license with GPLv3. + + * Relicense all FSF files to GPLv3 or later. + +2007-07-24 Glenn Morris <rgm@gnu.org> + + * calendar.texi (Writing Calendar Files): cal-tex-diary etc only work + for some calendars. + +2007-07-23 Nick Roberts <nickrob@snap.net.nz> + + * screen.texi (Mode Line): Describe new mode-line flag that shows if + default-directory for the current buffer is on a remote machine. + +2007-07-22 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.1.10. + + * tramp.texi (trampfn): Expand macro implementation in order to handle + empty arguments. + (trampfnmhl, trampfnuhl, trampfnhl): Remove macros. Replace all + occurencies by trampfn. + (Frequently Asked Questions): Extend example code for host + identification in the modeline. Add bbdb to approaches shortening Tramp + file names to be typed. + + * trampver.texi: Update release number. + +2007-07-21 Eli Zaretskii <eliz@gnu.org> + + * vc2-xtra.texi (Customizing VC) <vc-handled-backends>: Update the + default value. + +2007-07-21 Richard Stallman <rms@gnu.org> + + * files.texi (Why Version Control?): Improve previous change. + +2007-07-18 Eric S. Raymond <esr@snark.thyrsus.com> + + * files.texi (Why Version Control?): New node. + +2007-07-17 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi: Move @setfilename ../info/tramp up, outside the header + section. Reported by <poti@potis.org>. + (Remote processes): Arguments of the program to be debugged are taken + literally. + (Frequently Asked Questions): Simplify recentf example. + +2007-07-14 Karl Berry <karl@gnu.org> + + * info.texi (@copying): New Back-Cover Text. + + * info.texi (Quitting Info): Move to proper place in source. + (Reported by Benno Schulenberg.) + +2007-07-13 Eli Zaretskii <eliz@gnu.org> + + * Makefile.in (../info/emacs-mime): Use --enable-encoding. + + * makefile.w32-in ($(infodir)/emacs-mime): Ditto. + + * emacs-mime.texi: Add @documentencoding directive. + +2007-07-12 Nick Roberts <nickrob@snap.net.nz> + + * tramp.texi (Remote processes): Add an anchor to the subsection + "Running a debugger on a remote host". + + * building.texi (Starting GUD): Add xref to this anchor. + +2007-07-12 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (Remote processes): Don't call it "experimental" any + longer. Add subsection about running a debugger on a remote host. + +2007-07-10 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Properties and columns): Chapter rewritten. + +2007-07-08 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi: + * trampver.texi: Migrate to Tramp 2.1. + +2007-07-02 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Properties): New chapter. + +2007-07-02 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus-faq.texi ([3.2]): Fix locating of environment variables in the + Control Panel. + + * gnus.texi (Misc Article): Add index entry for + gnus-single-article-buffer. + +2007-06-27 Andreas Seltenreich <andreas@gate450.dyndns.org> + + * gnus.texi (Starting Up): Fix typo. + +2007-06-25 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Asynchronous Fetching): Fix typo. + +2007-06-24 Karl Berry <karl@gnu.org> + + * emacs.texi: new Back-Cover Text. + +2007-06-20 Jay Belanger <jay.p.belanger@gmail.com> + + * calc.texi:Change ifinfo to ifnottex (as appropriate) throughout. + (About This Manual): Remove redundant information. + (Getting Started): Mention author. + (Basic Arithmetic, Customizing Calc): Make description of the + variable `calc-multiplication-has-precedence' match its new effect. + +2007-06-19 Jay Belanger <jay.p.belanger@gmail.com> + + * calc.texi (Basic Arithmetic, Customizing Calc): Mention + the variable `calc-multiplication-has-precedence'. + +2007-06-19 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Tag): Section swapped with node Timestamps. + (Formula syntax for Lisp): Document new `L' flag. + +2007-06-06 Andreas Seltenreich <andreas@gate450.dyndns.org> + + * gnus.texi (Misc Group Stuff, Summary Buffer) + (Server Commands, Article Keymap): Fix typo. s/function/command/. + +2007-06-07 Alan Mackenzie <acm@muc.de> + + * display.texi (Optional Mode Line): Document the new form of + line+column numbers, "(561,2)". + +2007-06-06 Juanma Barranquero <lekktu@gmail.com> + + * cc-mode.texi (Comment Commands, Getting Started, Style Variables): + * gnus.texi (Article Buttons, Mail Source Customization) + (Sending or Not Sending, Customizing NNDiary): + * maintaining.texi (Create Tags Table): + * message.texi (Message Headers): + * mh-e.texi (HTML): Fix typos. + +2007-06-07 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.0.56. + + * tramp.texi (Frequently Asked Questions): Improve ~/.zshrc + settings. Reported by Ted Zlatanov <tzz@lifelogs.com>. + +2007-06-02 Chong Yidong <cyd@stupidchicken.com> + + * Version 22.1 released. + +2007-05-26 Michael Olson <mwolson@gnu.org> + + * erc.texi (Modules): Fix references to completion modules. + +2007-05-09 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Running NNDiary): Use ~/.gnus.el instead of gnusrc. + +2007-05-09 Didier Verna <didier@xemacs.org> + + * gnus.texi (Email Based Diary): New. Proper documentation for the + nndiary back end and the gnus-diary library. + +2007-05-07 Karl Berry <karl@gnu.org> + + * emacs.texi (EMACSVER): Back to 22. + +2007-05-06 Richard Stallman <rms@gnu.org> + + * maintaining.texi (Create Tags Table): Clean up previous change. + +2007-05-05 Francesco Potort,Al(B <pot@gnu.org> + + * maintaining.texi (Create Tags Table): Add text about the dangers of + making symbolic links to tags files. + +2007-05-04 Karl Berry <karl@gnu.org> + + * emacs.texi (EMACSVER) [smallbook]: 22.1 for printed version, not 22. + +2007-05-03 Karl Berry <karl@gnu.org> + + * emacs.texi (EMACSVER) [smallbook]: 22 for printed version. + + * .cvsignore (*.pdf): New entry. + + * texinfo.tex: Update from current version for better pdf generation. + + * emacs.texi (\urlcolor, \linkcolor) [smallbook]: \let to \Black + for printing. + +2007-05-01 Richard Stallman <rms@gnu.org> + + * cmdargs.texi (Initial Options): Under --batch, mention --eval. + +2007-04-30 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Article Highlighting): Clarify gnus-cite-parse-max-size. + +2007-04-28 Glenn Morris <rgm@gnu.org> + + * ack.texi (Acknowledgments): + * anti.texi (Antinews): + * faq.texi (New in Emacs 22): + * programs.texi (Program Modes): Restore mention of python.el pending + consideration of legal status. + +2007-04-28 Richard Stallman <rms@gnu.org> + + * files.texi (File Names): Fixes to ~ description on MS systems. + +2007-04-27 J.D. Smith <jdsmith@as.arizona.edu> + + * idlwave.texi: Minor updates for IDLWAVE 6.1. + +2007-04-26 Glenn Morris <rgm@gnu.org> + + * emacs.texi (EMACSVER): Increase to 22.1.50. + +2007-04-25 Karl Berry <karl@gnu.org> + + * emacs.texi: Improve line breaks on copyright page, + similar layout to lispref, 8.5x11 by default. + + * dired.texi (Image-Dired): Improve line break, fix typo. + +2007-04-24 Chong Yidong <cyd@stupidchicken.com> + + * programs.texi (Program Modes): + * faq.texi (New in Emacs 22): + * anti.texi (Antinews): + * ack.texi (Acknowledgments): python.el removed. + +2007-04-23 Jay Belanger <jay.p.belanger@gmail.com> + + * calc.texi (Reporting bugs): Update maintainer's address. + +2007-04-23 Chong Yidong <cyd@stupidchicken.com> + + * display.texi (Highlight Interactively): Correct description of + hi-lock-file-patterns-policy. + + * files.texi (File Archives): Mention self-extracting executables. + +2007-04-23 Eli Zaretskii <eliz@gnu.org> + + * search.texi (Unconditional Replace, Query Replace): Add xref to + "Replacement and Case". + +2007-04-22 Chong Yidong <cyd@stupidchicken.com> + + * dired.texi (Image-Dired): Move from Thumbnails node. + * misc.texi (Thumbnails): Node deleted. + * emacs.texi (Top): Update node listing. + + * files.texi (File Conveniences): + * ack.texi (Acknowledgments): + * faq.texi (New in Emacs 22): Rename "tumme" to "image-dired". + +2007-04-21 Richard Stallman <rms@gnu.org> + + * display.texi (Highlight Interactively): Correct previous change. + Clarify doc of hi-lock-find-patterns, and move new features into it. + +2007-04-20 David Koppelman <koppel@ece.lsu.edu> + + * display.texi (Highlight Interactively): Document + hi-lock-file-patterns-policy. + +2007-04-20 Martin Rudalics <rudalics@gmx.at> + + * display.texi (Scrolling): Fix typo. + +2007-04-15 Jay Belanger <belanger@truman.edu> + + * calc.texi (Title page): Remove the date. + (Basic Arithmetic): Emphasize that / binds less strongly than *. + (The Standard Calc Interface): Change trail title. + (Floats): Mention that when non-decimal floats are entered, only + approximations are stored. + (Copying): Move to the appendices. + (GNU Free Documentation License): Add as an appendix. + +2007-04-15 Chong Yidong <cyd@stupidchicken.com> + + * ada-mode.texi, autotype.texi, cc-mode.texi, cl.texi: + * dired-x.texi, ebrowse.texi, ediff.texi: + * emacs-mime.texi, erc.texi, eshell.texi: + * eudc.texi, flymake.texi, forms.texi, gnus.texi: + * idlwave.texi, message.texi, newsticker.texi, org.texi: + * pcl-cvs.texi, pgg.texi, rcirc.texi, reftex.texi, sc.texi: + * ses.texi, sieve.texi, smtpmail.texi, speedbar.texi: + * tramp.texi, url.texi, vip.texi, viper.texi, widget.texi: + * woman.texi: Include GFDL. + + * doclicense.texi: Remove node heading, so that it can be included by + other files. + + * emacs.texi: Insert node heading for GFDL. + + * dired-x.texi: Relicence under GFDL. Remove date from title page. + + * calc.texi (Algebraic Tutorial): Emphasize that / binds less strongly + than *. + +2007-04-14 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Formula syntax for Calc): Emphasize the operator precedence + in Calc. + +2007-04-14 Eli Zaretskii <eliz@gnu.org> + + * cmdargs.texi (Colors): Qualify "color of window" index entry by + "command line". + + * display.texi (Faces): Refer to "Creating Frames" for face + and other frame customizations in .emacs. + + * frames.texi (Creating Frames): Mention that face customizations can + be put in .emacs. Add index entries. + +2007-04-12 Richard Stallman <rms@gnu.org> + + * glossary.texi (Glossary): Explain `iff'. + +2007-04-11 Karl Berry <karl@gnu.org> + + * gnu.texi (Top), + * macos.texi (Mac Font Specs), + * anti.texi (Antinews), + * xresources.texi (Resources), + * misc.texi (Emulation), + * calendar.texi (Daylight Saving), + * dired.texi (Dired and Find), + * rmail.texi (Remote Mailboxes), + * sending.texi (Mail Headers), + * programs.texi (Which Function), + * files.texi (Recover), + * buffers.texi (Uniquify), + * frames.texi (Wheeled Mice), + * killing.texi (Rectangles): Wording to improve breaks in + 8.5x11 format. + * mule.texi (Language Environments): \hbadness=10000 since there's + no way to reword. + * emacs.texi (smallbook): New @set to more easily switch between + smallbook and 8.5x11. + +2007-04-11 Richard Stallman <rms@gnu.org> + + * files.texi (File Conveniences): Add xref to Tumme. + Delete text about Thumbnail mode. + +2007-04-09 Romain Francoise <romain@orebokech.com> + + * faq.texi (New in Emacs 22): Mention improvements to the Windows and + Mac OS ports. Make it clear that mouse-1 complements and doesn't + replace mouse-2. + +2007-04-09 Alan Mackenzie <acm@muc.de> + + * cmdargs.texi (Initial Options): Call "inhibit-splash-screen" by its + new name. Insert concept index entries. + +2007-04-08 Richard Stallman <rms@gnu.org> + + * url.texi: Fix some indexing. + (Disk Caching): Drop discussion of old/other Emacs versions. + +2007-04-08 Chong Yidong <cyd@stupidchicken.com> + + * display.texi (Standard Faces): Document prefix arg for + list-faces-display. + + * rmail.texi (Rmail Scrolling): Document rmail-end-of-message. + + * woman.texi (Word at point, Interface Options): woman-topic-at-point + renamed to woman-use-topic-at-point. Document new behavior. + +2007-04-07 Chong Yidong <cyd@stupidchicken.com> + + * url.texi (Disk Caching): Say Emacs 21 "and later". + + * cc-mode.texi (Font Locking Preliminaries): Link to Emacs manual node + on Font locking which now mentions JIT lock. + + * killing.texi (Deletion): Rewrite description of M-\ prefix argument. + + * files.texi (Misc File Ops): Rewrite description of + insert-file-literally. + +2007-04-01 Michael Olson <mwolson@gnu.org> + + * erc.texi: Update for the ERC 5.2 release. + +2007-03-31 David Kastrup <dak@gnu.org> + + * woman.texi (Topic, Interface Options): Explain changes semantics of + woman-manpath in order to consider MANPATH_MAP entries. + +2007-03-31 Eli Zaretskii <eliz@gnu.org> + + * misc.texi (Printing): Postscript -> PostScript. + + * emacs-mime.texi (Non-MIME): Postscript -> PostScript. + + * ack.texi (Acknowledgments): Postscript -> PostScript. + + * custom.texi (Init File, Init Non-ASCII): Fix last change. + + * emacs.texi (Top): Fix the menu due to the change in custom.texi + below. + +2007-03-30 Chong Yidong <cyd@stupidchicken.com> + + * custom.texi (Non-ASCII Rebinding): Node deleted. Material moved to + Init Non-ASCII. + (Init Rebinding, Init Syntax): Link to Init Non-ASCII instead. + (Init Non-ASCII): New node. + +2007-03-28 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp> + + * macos.texi (Mac Font Specs): Mention AppleAntiAliasingThreshold. + +2007-03-26 Richard Stallman <rms@gnu.org> + + * pgg.texi (Caching passphrase): Clean up previous change. + +2007-03-25 Thien-Thi Nguyen <ttn@gnu.org> + + * gnus.texi (Setting Process Marks): Fix typo. + +2007-03-25 Romain Francoise <romain@orebokech.com> + + * faq.texi (New in Emacs 22): Reorganize using an itemized list for + readability, and include various fixes by Daniel Brockman, Nick Roberts + and Dieter Wilhelm. + +2007-03-24 Thien-Thi Nguyen <ttn@gnu.org> + + * gnus.texi (Splitting Mail): Reword "splitting"-as-adj to be -as-noun. + + * gnus.texi (Mail Source Specifiers): Fix typo. + +2007-03-22 Ralf Angeli <angeli@caeruleus.net> + + * reftex.texi (Imprint): Update maintainer information. + +2007-03-15 Katsumi Yamaoka <yamaoka@jpl.org> + + * message.texi (Message Buffers): Update documentation for + message-generate-new-buffers. + +2007-03-15 Daiki Ueno <ueno@unixuser.org> + + * pgg.texi (Caching passphrase): Describe pgg-passphrase-coding-system. + +2007-03-21 Glenn Morris <rgm@gnu.org> + + * eshell.texi (Known problems): Emacs 22 comes with eshell 2.4.2. + +2007-03-19 Chong Yidong <cyd@stupidchicken.com> + + * eshell.texi (Known problems): Emacs 21 -> 22. + + * cc-mode.texi (Performance Issues): Update note about 21.3 to 22.1. + +2007-03-18 Jay Belanger <belanger@truman.edu> + + * calc.texi (Time Zones): Mention that the DST rules changed in 2007. + +2007-03-12 Glenn Morris <rgm@gnu.org> + + * calc.texi (Time Zones): Switch to new North America DST rule. + + * calendar.texi, emacs.texi (Daylight Saving): Rename node from + "Daylight Savings". + + * calc.texi, calendar.texi: Replace "daylight savings" with "daylight + saving" in text throughout. + +2007-03-11 Andreas Seltenreich <uwi7@rz.uni-karlsruhe.de> + + * gnus.texi (Mail and Post): Update documentation for gnus-user-agent. + The variable now uses a list of symbols instead of just a symbol. + Reported by Christoph Conrad <christoph.conrad@gmx.de>. + +2007-03-06 Romain Francoise <romain@orebokech.com> + + * faq.texi (New in Emacs 22): Don't say "now" too much. Add MH-E to + new packages, and mention Gnus update. + +2007-03-04 Richard Stallman <rms@gnu.org> + + * custom.texi (Safe File Variables): Minor correction. + +2007-02-27 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (NNTP): Mention nntp-never-echoes-commands and + nntp-open-connection-functions-never-echo-commands. + +2007-02-28 Thien-Thi Nguyen <ttn@gnu.org> + + * rmail.texi (Movemail): Add internal ref. + Don't indent the intro for the PROTO table. + Format PROTO table items with @code. + +2007-02-27 Chong Yidong <cyd@stupidchicken.com> + + * pgg.texi (Caching passphrase): Document gpg-agent usage, gpg-agent + problems on the console, and security risk in not using gpg-agent. + +2007-02-26 Nick Roberts <nickrob@snap.net.nz> + + * building.texi: Remove references to bashdb. + +2007-02-25 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (The spreadsheet): Renamed from "Table calculations". + Completely reorganized and rewritten. + (CamelCase links): Section removed. + (Repeating items): New section. + (Tracking TODO state changes): New section. + (Agenda views): Chapter reorganized and rewritten. + (HTML export): Section rewritten. + (Tables in arbitrary syntax): New section. + (Summary): Better feature summary. + (Activation): Document problem with cut-and-paste of Lisp code + from PDF files. + (Visibility cycling): Document indirect buffer use. + (Structure editing): Document sorting. + (Remember): Section rewritten. + (Time stamps): Better description of time stamp types. + (Tag searches): Document regular expression search for tags. + (Stuck projects): New section. + (In-buffer settings): New keywords. + (History and Acknowledgments): Updated description. + +2007-02-24 Alan Mackenzie <acm@muc.de> + + * cc-mode.texi (Movement Commands): Insert two missing command names. + (Getting Started): Slight wording correction (use conditional). + +2007-02-22 Kim F. Storm <storm@cua.dk> + + * widget.texi (User Interface, Basic Types): Document need to put some + text before the %v escape in :format string in editable-field widget. + +2007-02-19 Juanma Barranquero <lekktu@gmail.com> + + * mule.texi (Language Environments): Update list of supported language + environments. + +2007-02-18 Romain Francoise <romain@orebokech.com> + + * pcl-cvs.texi (Miscellaneous commands): q runs `cvs-bury-buffer', not + `cvs-mode-quit'. + +2007-02-14 Kim F. Storm <storm@cua.dk> + + * building.texi (Grep Searching): Fix lgrep doc. + +2007-02-12 Chong Yidong <cyd@stupidchicken.com> + + * back.texi: Remove unused file. + +2007-02-10 Markus Triska <markus.triska@gmx.at> + + * widget.texi (Programming Example): Put constant strings in :format. + +2007-02-07 Juanma Barranquero <lekktu@gmail.com> + + * faq.texi (Fullscreen mode on MS-Windows): New node. + +2007-02-05 Francesco Potort,Al(B <pot@gnu.org> + + * maintaining.texi (Tag Syntax): Now --members is the default for + etags, not for ctags yet. + +2007-02-04 David Kastrup <dak@gnu.org> + + * faq.texi (AUCTeX): Update version number. Should probably be done + for other packages as well. + +2007-02-03 Eli Zaretskii <eliz@gnu.org> + + * emacs.texi (Top): Update the top-level menus. Make the detailed menu + headers compliant with Texinfo guidelines and with what texnfo-upd.el + expects. Add comments to prevent people from inadvertently modifying + the key parts needed by `texinfo-multiple-files-update'. + +2007-01-29 Chong Yidong <cyd@stupidchicken.com> + + * frames.texi (Secondary Selection): Window clicked does not matter + when mouse-yank-at-point is non-nil. + +2007-01-28 Andreas Seltenreich <uwi7@rz.uni-karlsruhe.de> + + * gnus.texi (Batching Agents): Fix example. Reported by Tassilo Horn + <tassilo@member.fsf.org>. + +2007-01-27 Eli Zaretskii <eliz@gnu.org> + + * msdog.texi (ls in Lisp): Document ls-lisp-format-time-list and + ls-lisp-use-localized-time-format. + +2007-01-20 Markus Triska <markus.triska@gmx.at> + + * flymake.texi (Flymake mode): find-file-hook instead of ...-hooks. + +2007-01-13 Michael Olson <mwolson@gnu.org> + + * erc.texi (Modules): Mention capab-identify module. + +2007-01-16 Glenn Morris <rgm@gnu.org> + + * abbrevs.texi (Editing Abbrevs): Describe how to disable a + system abbrev. + +2007-01-11 Richard Stallman <rms@gnu.org> + + * msdog.texi (Windows Keyboard): Another small cleanup. + +2007-01-10 Richard Stallman <rms@gnu.org> + + * msdog.texi (Windows Keyboard): Yet another try to make + everyone happy with that passage. + +2007-01-05 Richard Stallman <rms@gnu.org> + + * anti.texi (Antinews): Mention M-x shell scrolling. + +2007-01-05 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Watch Expressions): Describe gdb-max-children. + +2007-01-05 Michael Olson <mwolson@gnu.org> + + * erc.texi (Getting Started): Update for /RECONNECT command. + +2007-01-04 Richard Stallman <rms@gnu.org> + + * ebrowse.texi: Change C-c b to C-c C-m. + + * msdog.texi (Windows Keyboard): Clarify previous change. + +2007-01-03 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Customizing Articles): Use index entries for gnus-treat-* + variables only in info to avoid redundant entries in the printed + manual. + +2007-01-02 Richard Stallman <rms@gnu.org> + + * custom.texi (Changing a Variable): Minor clarification. + (Specific Customization): customize-customized => customize-unsaved. + + * entering.texi (Entering Emacs): Clean up text about restarting + Emacs for each file. + + * misc.texi (Shell Options): Minor cleanup. + + * msdog.texi (Windows Keyboard): Explain that Windows was incompatible + with Emacs, not vice versa. + + * programs.texi (Symbol Completion): Recommend customizing + window manager. + + * xresources.texi (Resources): Minor fix. + +2007-01-02 Daiki Ueno <ueno@unixuser.org> + + * message.texi (Using PGP/MIME): Document gpg-agent usage. + +2007-01-02 Reiner Steib <Reiner.Steib@gmx.de> + + * message.texi (Security): Split into sub-nodes. + +2007-01-01 Alan Mackenzie <acm@muc.de> + + * cc-mode.texi ("Limitations and Known Bugs"): Document problems with + eval-after-load in Emacs <=21 and a workaround. Document that + trigraphs are not supported. + +2007-01-01 Alan Mackenzie <acm@muc.de> + + * cc-mode.texi ("Filling and Breaking"): Amend the doc for + c-context-line-break. When invoked within a string, preserve + whitespace. Add a backslash only when also in a macro. + +2007-01-01 Alan Mackenzie <acm@muc.de> + + * cc-mode.texi ("Choosing a Style"): Mention c-file-style. + +2007-01-01 Alan Mackenzie <acm@muc.de> + + * cc-mode.texi ("Movement Commands", "Sample .emacs File"): C-M-[ae] + are now bound by default to c-\(beginning\|end\)-of-defun by default. + +2007-01-01 Alan Mackenzie <acm@muc.de> + + * cc-mode.texi ("Other Commands"): Move c-set-style (C-c .) here from + "Choosing a Style". + + * cc-mode.texi ("Styles"): Add @dfn{style}. + +2007-01-01 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * xresources.texi (Table of Resources): Add scrollBarWidth resource. + +2007-01-01 Richard Stallman <rms@gnu.org> + + * commands.texi (User Input): Document keys stolen by window mangers. + +2006-12-31 Richard Stallman <rms@gnu.org> + + * custom.texi (Specific Customization): Document customize-option + instead of customize-variable. + +2006-12-31 Kim F. Storm <storm@cua.dk> + + * major.texi (Choosing Modes): Document auto-mode-case-fold. + +2006-12-30 Kim F. Storm <storm@cua.dk> + + * killing.texi (CUA Bindings): Fix typo. + + * xresources.texi (Table of Resources): Mention grow-only value for + auto-resize-tool-bars. + +2006-12-30 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.0.55. + + * trampver.texi: Update release number. + +2006-12-29 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Customizing Articles): Add index entries for all + gnus-treat-* variables. + +2006-12-29 Jouni K. Sepp,Ad(Bnen <jks@iki.fi> + + * gnus.texi (IMAP): Fix incorrect explanation of + nnimap-search-uids-not-since-is-evil in documentation for + nnimap-expunge-search-string. + +2006-12-27 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (ifile spam filtering): Rename spam-ifile-database-path to + spam-ifile-database. + +2006-12-26 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Spam Package Configuration Examples): Don't encourage to + rebind C-s. + +2006-12-26 Jouni K. Sepp,Ad(Bnen <jks@iki.fi> + + * gnus.texi (Group Parameters, Group Maintenance, Topic Commands) + (Mail Group Commands, Expiring Mail, IMAP): Add index entries for + "expiring mail". + (IMAP): Document nnimap-search-uids-not-since-is-evil and + nnimap-nov-is-evil. + +2006-12-27 Eli Zaretskii <eliz@gnu.org> + + * msdog.texi (Windows Keyboard): Mention widespread Windows bindings, + and how to get them back. + +2006-12-26 Richard Stallman <rms@gnu.org> + + * calendar.texi (Holidays): Holiday listing is based on current + practice, but DST is not. + +2006-12-25 Richard Stallman <rms@gnu.org> + + * emacs.texi (Top): Update subnode menus. + + * mark.texi (Transient Mark): Fix xref. + + * killing.texi (Graphical Kill): Node deleted. + (Killing): Add xref to Cut and Paste. + (CUA Bindings): Update xref. + + * frames.texi (Cut and Paste): New section to hold other nodes. + (Mouse Commands): Node demoted. + (Cut/Paste Other App): Split out from Mouse Commands. + (Word and Line Mouse): Likewise. + (Secondary Selection, Clipboard): Nodes demoted. + +2006-12-25 Kevin Ryde <user42@zip.com.au> + + * cl.texi (Sorting Sequences): In sort*, add a little cautionary note + about the key procedure being used heavily. + +2006-12-24 Chong Yidong <cyd@stupidchicken.com> + + * pgg.texi (Caching passphrase): Default for pgg-gpg-use-agent changed + to t. + (Prerequisites): Add explanation about gpg-agent. + +2006-12-24 Kevin Ryde <user42@zip.com.au> + + * calendar.texi (Holidays): US daylight saving begins second Sunday + in March for 2007 onwards. + (Daylight Savings): Show new US default daylight saving rules, 2nd + Sun in Mar to 1st Sun in Nov, now in cal-dst.el. + +2006-12-23 Chong Yidong <cyd@stupidchicken.com> + + * calendar.texi (Scroll Calendar): < and > are switched. + +2006-12-23 Kevin Rodgers <ihs_4664@yahoo.com> + + * killing.texi (Deletion): Describe M-\ prefix argument. + +2006-12-23 Richard Stallman <rms@gnu.org> + + * search.texi (Regexp Search): Explain why forward and reverse regexp + search are not mirror images. + +2006-12-22 Kevin Ryde <user42@zip.com.au> + + * cl.texi (Sorting Sequences): Typo in sort*, example showed plain + "sort" instead of "sort*". + +2006-12-19 Richard Stallman <rms@gnu.org> + + * calc.texi (History and Acknowledgements): Recognize that Emacs + now does have floating point. + +2006-12-19 Kim F. Storm <storm@cua.dk> + + * major.texi (Choosing Modes): Describe match-function elements for + magic-mode-alist. + +2006-12-19 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (External transfer methods): Describe new method `scpc'. + +2006-12-18 Eli Zaretskii <eliz@gnu.org> + + * msdog.texi (Windows Keyboard): Add a footnote about "Windows" keys + peculiarities. + +2006-12-18 Richard Stallman <rms@gnu.org> + + * abbrevs.texi (Editing Abbrevs): Fix previous change. + +2006-12-17 Sascha Wilde <wilde@sha-bang.de> + + * pgg.texi: Added short note on gpg-agent to the introduction. + +2006-12-17 Alan Mackenzie <acm@muc.de> + + * programs.texi (Left Margin Paren): Remove the bit which says + that CC Mode sets open-paren-in-column-0-is-defun-start to nil. + Discuss some of the issues of setting this option to nil. + +2006-12-17 Glenn Morris <rgm@gnu.org> + + * abbrevs.texi (Editing Abbrevs): Mention system abbrevs. + +2006-12-16 Eli Zaretskii <eliz@gnu.org> + + * msdog.texi (Windows Keyboard): Clarify `w32-recognize-altgr' effect. + (Windows Files): `w32-get-true-file-attributes' is only relevant for + NTFS volumes. + (ls in Lisp): `links' in `ls-lisp-verbosity' is only relevant to NTFS + volumes. + +2006-12-15 Eli Zaretskii <eliz@gnu.org> + + * text.texi (HTML Mode): Fix "C-c TAB". + +2006-12-13 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Hiding Headers): Document that `long-to' and `many-to' + also applies to Cc. + +2006-12-12 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (X-Face): Clarify. Say which programs are required + on Windows. + +2006-12-09 Richard Stallman <rms@gnu.org> + + * misc.texi (Invoking emacsclient): Simplify TCP file text. + +2006-12-08 Kevin Rodgers <ihs_4664@yahoo.com> + + * files.texi (Misc File Ops): Document insert-file-literally. + +2006-12-08 Eli Zaretskii <eliz@gnu.org> + + * cmdargs.texi (Colors): Note that --color is intended for overriding + the terminal defaults, not for normal invocation. + + * misc.texi (Emacs Server): Improve wording. Don't mention the + ``server program''. Add a cross-reference to "Init File" node. + (Invoking emacsclient): Add index entries. Document both short and + long versions of command-line options. Document the -f option. + +2006-12-08 Michael Olson <mwolson@gnu.org> + + * erc.texi (Modules): Remove documentation for list module. + +2006-12-06 Richard Stallman <rms@gnu.org> + + * text.texi (Outline Format): Say to set outline-regexp + and outline-level with major modes and file local variables. + +2006-12-05 Micha,Ak(Bl Cadilhac <michael.cadilhac@lrde.org> + + * anti.texi (Antinews): Mention the alternative to + `~/.emacs_SHELLNAME', which is `~/.emacs.d/init_SHELLNAME.sh'. + + * faq.texi (^M in the shell buffer): Ditto. + + * misc.texi (Interactive Shell): Ditto. + +2006-12-04 Eli Zaretskii <eliz@gnu.org> + + * emacs.texi (Acknowledgments): Fix Arne J@o{}rgensen's name. + + * ack.texi (Acknowledgments): Fix Arne J@o{}rgensen's name. + +2006-12-01 Eli Zaretskii <eliz@gnu.org> + + * mule.texi (Enabling Multibyte): Rephrase the confusing reference to a + colon in the mode line. + + * msdog.texi (Windows Processes) [@ifnottex]: Mention w32-shell-execute. + +2006-11-26 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Watch Expressions): Mention SPC for expanding/ + contracting watch expressions. + +2006-11-26 Kim F. Storm <storm@cua.dk> + + * kmacro.texi (Basic Keyboard Macro): Mention F3/F4 more. + +2006-11-26 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Debugger Operation): Define text command mode. + Clarify how tooltips work. + (GDB Graphical Interface): Explain how to run in text command mode + more clearly. + +2006-11-25 Juanma Barranquero <lekktu@gmail.com> + + * mule.texi (Defining Fontsets): Fix use of `charset' and `font'. + +2006-11-22 Juanma Barranquero <lekktu@gmail.com> + + * anti.texi (Antinews): Mention --server-file and TCP sockets. + +2006-11-20 Michael Olson <mwolson@gnu.org> + + * erc.texi: Call this the 5.2 stable pre-release of ERC. + +2006-11-18 Chong Yidong <cyd@stupidchicken.com> + + * misc.texi (Interactive Shell): INSIDE_EMACS is set to t, + and EMACS is deprecated. + +2006-11-18 Juanma Barranquero <lekktu@gmail.com> + + * makefile.w32-in (emacs.dvi): Remove xresmini.texi. + +2006-11-18 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * Makefile.in (emacs.dvi): Remove xresmini.texi. + + * emacs.texi: Include xresources.texi both for info and dvi. + + * xresources.texi: Merge text from xresmini.texi. + +2006-11-17 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Fix typos. + (Agenda commands): Document `C-k'. + +2006-11-16 Eli Zaretskii <eliz@gnu.org> + + * url.texi (http/https): Fix a typo in the HTTP URL. + +2006-11-14 Stephen Leake <stephen_leake@stephe-leake.org> + + * ada-mode.texi: Total rewrite. + +2006-11-13 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Minor typo fixes. + +2006-11-13 Bill Wohler <wohler@newt.com> + + Release MH-E manual version 8.0.3. + + * mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for + release 8.0.3. + + * mh-e.texi (Incorporating Mail): Use output of "mhparam Path" + to set MAILDIR. + (Reading Mail): Document the customization of read-mail-command + for MH-E. + (Viewing Attachments): Document mm-discouraged-alternatives. + (Tool Bar): Fix Texinfo for mh-xemacs-use-tool-bar-flag. + (Junk): Add more information about the settings of mh-junk-background + in a program. Add /usr/bin/mh to PATH in examples. + +2006-11-12 Richard Stallman <rms@gnu.org> + + * woman.texi: Update author address but say he no longer maintains it. + +2006-11-12 Roberto Rodr,Am(Bguez <lanubeblanca@googlemail.com> (tiny change) + + * glossary.texi: Fix typos. + +2006-11-10 Carsten Dominik <carsten.dominik@gmail.com> + + * org.texi (ARCHIVE tag): Document C-TAB for forcing cycling of + archived trees. + (Checkboxes): Section moved to chapter 5, and extended. + (The date/time prompt): New section. + (Link abbreviations): New section. + (Presentation and sorting): New section. + (Custom agenda views): Section completely rewritten. + (Summary): Compare with Planner. + (Feedback): More info about creating backtraces. + (Plain lists): Modified example. + (Breaking down tasks): New section. + (Custom time format): New section. + (Time stamps): Document inactive timestamps. + (Setting tags): More details about fast tag selection. + (Block agenda): New section. + (Custom agenda views): Section rewritten. + (Block agenda): New section. + +2006-11-07 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (Configuration): scp is the default method. + (Default Method): Use ssh as example for another method. + +2006-11-06 Richard Stallman <rms@gnu.org> + + * emacs.texi (Acknowledgments): Fix name spelling, add Anna Bigatti. + + * ack.texi (Acknowledgments): Fix name spelling. + +2006-11-01 Juri Linkov <juri@jurta.org> + + * search.texi (Word Search): Document incremental word search. + +2006-10-28 Glenn Morris <rgm@gnu.org> + + * ack.texi (Acknowledgments): Add cal-html author. + + * calendar.texi (Writing Calendar Files): Rename section (was "LaTeX + Calendar"). Describe new package cal-html. + * emacs.texi (Top): Rename old node "LaTeX Calendar" to "Writing + Calendar Files." + +2006-10-27 Richard Stallman <rms@gnu.org> + + * woman.texi: Downcase nroff/troff/roff. + (Installation): Chapter deleted. Some xrefs deleted. + (Background): woman doesn't advise man ;-). + +2006-10-26 Roberto Rodr,Am(Bguez <lanubeblanca@googlemail.com> (tiny change) + + * ada-mode.texi (Project files, Identifier completion) + (Automatic Casing, Debugging, Using non-standard file names) + (Working Remotely): Fix typos. + +2006-10-23 Richard Stallman <rms@gnu.org> + + * abbrevs.texi (Expanding Abbrevs): Expansion happens only when + Abbrev mode is enabled. + +2006-10-20 Masatake YAMATO <jet@gyve.org> + + * cc-mode.texi (Sample .emacs File): Added missing `)' in + sample code `my-c-initialization-hook'. + +2006-10-19 Stuart D. Herring <herring@lanl.gov> + + * widget.texi: Fix typos. + +2006-10-19 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (Frequently Asked Questions): Remove questions marked with + "???". There have been no complaints for years, so the information + must be appropriate. + +2006-10-16 Richard Stallman <rms@gnu.org> + + * widget.texi: Use @var instead of capitalization. + Clarify many widget type descriptions. + + * emacs.texi: Update ISBN. + +2006-10-13 Andreas Seltenreich <uwi7@rz.uni-karlsruhe.de> + + * gnus.texi (Other modes): Fix typo. Add alternative index entry for + gnus-dired-attach. + (Selecting a Group): Fix typo. + +2006-10-12 Roberto Rodr,Am(Bguez <lanubeblanca@googlemail.com> (tiny change) + + * widget.texi: Fix typos. + +2006-10-11 Kim F. Storm <storm@cua.dk> + + * emacs.texi (Acknowledgments): Use @dotless{i}. + +2006-10-08 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Breakpoints Buffer): Mention catchpoints. + +2006-10-08 Kim F. Storm <storm@cua.dk> + + * ack.texi (Acknowledgments): Update. + + * emacs.texi (Acknowledgments): Fix bad @/ form. + +2006-10-06 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Image Enhancements): Update for Emacs 22. + + * gnus-faq.texi ([1.3]): Update. + +2006-10-06 Richard Stallman <rms@gnu.org> + + * faq.texi (Displaying the current line or column): + Delete "As of Emacs 20". + +2006-10-06 Romain Francoise <romain@orebokech.com> + + * faq.texi (VM): VM works with Emacs 22 too. + +2006-10-06 Richard Stallman <rms@gnu.org> + + * ebrowse.texi: Remove Emacs version "21" from title. + +2006-10-05 Kim F. Storm <storm@cua.dk> + + * emacs.texi (Acknowledgments): Add more contributors. + +2006-10-03 Richard Stallman <rms@gnu.org> + + * emacs.texi (Acknowledgments): Update version and edition. + +2006-10-02 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Foreign Groups): Say where change of editing commands are + stored. Add reference to `gnus-parameters'. + +2006-10-01 Karl Berry <karl@gnu.org> + + * custom.texi (Customization Groups): Page break to keep example buffer + on one page. + +2006-09-30 Karl Berry <karl@gnu.org> + + * programs.texi (Basic Indent): @need to improve page break. + * text.texi: Rewording to improve page breaks, and use @LaTeX{}. + +2006-09-29 Glenn Morris <rgm@gnu.org> + + * calendar.texi (Date Formats): Doc fix for european-calendar-style. + +2006-09-29 Karl Berry <karl@gnu.org> + + * windows.texi (Basic Window): Remove forced @break, no longer + desirable. + * frames.texi (Frame Commands), + * mark.texi (Marking Objects): Reword to avoid bad page break. + * display.texi (Auto Scrolling): Use @tie{} to avoid bad line break. + +2006-09-19 Richard Stallman <rms@gnu.org> + + * frames.texi (Dialog Boxes): Clean up wording: avoid passive, + stick to present tense. + +2006-09-18 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * frames.texi (Dialog Boxes): Rename x-use-old-gtk-file-dialog + to x-gtk-use-old-file-dialog. + (Dialog Boxes): Document x-gtk-file-dialog-help-text. + +2006-09-15 Jay Belanger <belanger@truman.edu> + + * calc.texi, emacs.texi, mh-e.texi (GNU GENERAL PUBLIC LICENSE): + Change "Library Public License" to "Lesser Public License" + throughout. Use "yyyy" to represent year. + +2006-09-15 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Setting tags): Typo fix. + +2006-09-14 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Oort Gnus): Add @xref for `mm-fill-flowed'. + +2006-09-12 Reiner Steib <Reiner.Steib@gmx.de> + + * files.texi (Visiting): Add index entry "open file". + + * reftex.texi (Citations Outside LaTeX): Simplify lisp example. + +2006-09-12 Paul Eggert <eggert@cs.ucla.edu> + + * faq.texi (Escape sequences in shell output): EMACS is now set + to Emacs's absolute file name, not to "t". + (^M in the shell buffer): Likewise. + * misc.texi (Interactive Shell): Likewise. + +2006-09-11 Richard Stallman <rms@gnu.org> + + * building.texi (Compilation Mode): Clarification. + (Grep Searching): Add xref to Compilation Mode. + +2006-09-11 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Mail Source Specifiers): Mention problem of duplicate + mails with pop3-leave-mail-on-server. Fix wording. + (Limiting): Improve gnus-summary-limit-to-articles. + (X-Face): Fix typo. + +2006-09-11 Simon Josefsson <jas@extundo.com> + + * smtpmail.texi (Authentication): Explain TLS and SSL better, based on + suggested by Phillip Lord <phillip.lord@newcastle.ac.uk>. + +2006-09-08 Richard Stallman <rms@gnu.org> + + * search.texi (Search): Ref multi-file search commands here. + (Other Repeating Search): Not here. + +2006-09-06 Simon Josefsson <jas@extundo.com> + + * smtpmail.texi (Authentication): Mention SSL. + +2006-09-01 Eli Zaretskii <eliz@gnu.org> + + * rcirc.texi (Internet Relay Chat, Useful IRC commands): + Don't use @indicateurl. + + * cc-mode.texi (Subword Movement): Don't use @headitem. + (Custom Braces, Clean-ups): Don't use @tie. + +2006-08-29 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.0.54. + + * tramp.texi (Bug Reports): The Tramp mailing list is moderated now. + Suggested by Adrian Phillips <a.phillips@met.no>. + +2006-08-28 Richard Stallman <rms@gnu.org> + + * windows.texi (Split Window): Update xref. + + * basic.texi (Continuation Lines): Update xref. + + * indent.texi (Tab Stops): Update xref. + + * emacs.texi (Top): Update subnode menu. + + * display.texi (Line Truncation, Displaying Boundaries): New nodes, + split out of Display Custom. + +2006-08-25 Kim F. Storm <storm@cua.dk> + + * display.texi (Display Custom): Add variables overline-margin + and x-underline-at-descent-line. + +2006-08-25 Richard Stallman <rms@gnu.org> + + * entering.texi (Exiting): Rewrite to give graphical displays + priority over text terminals. + + * search.texi (Incremental Search): Move index entries. + +2006-08-23 Chong Yidong <cyd@stupidchicken.com> + + * custom.texi (Init File): Reference Find Init to avoid "home + directory" confusion. + +2006-08-22 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Other GDB-UI Buffers): Describe how to edit + a value in the locals buffer. + +2006-08-21 Richard Stallman <rms@gnu.org> + + * search.texi (Basic Isearch): Add `isearch' index entry. + +2006-08-16 Richard Stallman <rms@gnu.org> + + * misc.texi (Saving Emacs Sessions): Clean up wording. + + * mark.texi (Marking Objects): Mention term "select all". + + * emacs.texi (Top): Update subnode menu. + + * help.texi (Help Mode): Move node up in file. + +2006-08-15 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Installation, Activation): Split from Installation and + Activation. + (Clocking work time): Documented new features. + +2006-08-15 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Stack Buffer): Explain fringe arrow. + +2006-08-13 Alex Schroeder <alex@gnu.org> + + * rcirc.texi (Configuration): Use correct variable in rcirc-authinfo + example. + +2006-08-12 Eli Zaretskii <eliz@gnu.org> + + * faq.texi (How to add fonts): New node. + + * misc.texi (Saving Emacs Sessions): Clarify when desktop is restored + on startup. + +2006-08-11 Romain Francoise <romain@orebokech.com> + + * ack.texi (Acknowledgments): Delete mention to zone-mode.el. + +2006-08-10 Sven Joachim <svenjoac@gmx.de> (tiny change) + + * mule.texi (Recognize Coding, Text Coding): Fix typos. + +2006-08-10 Richard Stallman <rms@gnu.org> + + * text.texi (Format Faces): Substantial rewrites to deal + with face merging. Empty regions don't count. Clarify + face property inheritance. + +2006-08-08 Romain Francoise <romain@orebokech.com> + + * dired.texi (Marks vs Flags): Fix typo reported by Ari Roponen + <arjuropo@cc.jyu.fi>. + +2006-08-05 Romain Francoise <romain@orebokech.com> + + * faq.texi (New in Emacs 22): Expand. + +2006-08-04 Eli Zaretskii <eliz@gnu.org> + + * cmdargs.texi (Window Size X) <--geometry>: Only width and height + apply to all frames. + +2006-08-03 Michael Olson <mwolson@gnu.org> + + * erc.texi: Update for ERC 5.1.4. + +2006-08-01 Richard Stallman <rms@gnu.org> + + * help.texi (Name Help): Add index entries for describe-variable. + +2006-08-01 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (GDB Graphical Interface): Shorten node names. + (GDB-UI Layout): Use GDB-related. + (Other GDB-UI Buffers): Simplify English. + +2006-07-31 Richard Stallman <rms@gnu.org> + + * search.texi (Query Replace): Add xref for Dired's Q command. + +2006-07-28 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Oort Gnus): Mention that the Lisp files are now installed + in .../site-lisp/gnus/ by default. + [ From gnus-news.texi in the trunk. ] + +2006-07-27 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (MIME Commands): Additions for yEnc. + +2006-07-31 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (GDB commands in Fringe): Rename to... + (Source Buffers): ..this and move forward. Describe hollow arrow and + new option gdb-find-source-frame. + +2006-07-29 Richard Stallman <rms@gnu.org> + + * dired.texi (Operating on Files): Simplify previous change + and fix Texinfo usage. + +2006-07-29 Eli Zaretskii <eliz@gnu.org> + + * dired.texi (Operating on Files): Add cross-references. State the + Unix commands that do similar things. + +2006-07-28 Richard Stallman <rms@gnu.org> + + * mark.texi (Transient Mark): Clarify that region never disappears + when Transient Mark mode is off, and not when it is on. + +2006-07-27 Richard Stallman <rms@gnu.org> + + * search.texi (Non-ASCII Isearch): Clarify. Mention C-q. + +2006-07-24 Richard Stallman <rms@gnu.org> + + * xresources.texi (GTK styles): Fix texinfo usage. + + * pgg.texi, org.texi, info.texi, forms.texi, flymake.texi: + * faq.texi: Move periods and commas inside quotes. + + * commands.texi (User Input): Explain why we teach keyboard cmds. + + * xresources.texi, xresmini.texi, search.texi, programs.texi: + * misc.texi, kmacro.texi, killing.texi, glossary.texi: + * fortran-xtra.texi, files.texi, emacs.texi, emacs-xtra.texi: + * doclicense.texi, display.texi, dired.texi, basic.texi: + * anti.texi, ack.texi: Move periods and commas inside quotes. + +2006-07-22 Eli Zaretskii <eliz@gnu.org> + + * cmdargs.texi (General Variables): Document EMAIL. + +2006-07-21 Eli Zaretskii <eliz@gnu.org> + + * frames.texi (Frame Commands): Mention that focus-follows-mouse + doesn't have effect on MS-Windows. + +2006-07-20 Jay Belanger <belanger@truman.edu> + + * calc.texi (Error forms): Mention M-+ keybinding for `calc-plus-minus'. + +2006-07-18 Chong Yidong <cyd@stupidchicken.com> + + * faq.texi (Security risks with Emacs): Document Emacs 22 + file-local-variable mechanism. + +2006-07-17 Richard Stallman <rms@gnu.org> + + * building.texi (Grep Searching): Explain about chaining grep commands. + +2006-07-12 Michael Olson <mwolson@gnu.org> + + * erc.texi: Update for ERC 5.1.3. + +2006-07-12 Alex Schroeder <alex@gnu.org> + + * rcirc.texi: Fix typos. + (Getting started with rcirc): New calling convention for M-x irc. + Mention #rcirc. Removed channel tracking. + (Configuration): Changed the names of all variables that got changed + recently, eg. rcirc-server to rcirc-default-server. Added + documentation for rcirc-authinfo, some background for Bitlbee, and + rcirc-track-minor-mode. + (Scrolling conservatively): Fixed the xref from Auto Scrolling to just + Scrolling. + (Reconnecting after you have lost the connection): Fixed example code + to match code changes. + +2006-07-10 Nick Roberts <nickrob@snap.net.nz> + + * killing.texi, gnus.texi, message.texi, mini.texi: Fix typos. + +2006-07-09 Chong Yidong <cyd@stupidchicken.com> + + * misc.texi (Invoking emacsclient): Document behavior when emacsclient + is invoked for multiple files. + +2006-07-08 Eli Zaretskii <eliz@gnu.org> + + * msdog.texi (Windows Keyboard) [@iftex]: Add an @inforef to the + on-line manual for the rest of this node. + (Windows Mouse) <w32-pass-extra-mouse-buttons-to-system>: Include + unconditionally. + (Windows Processes) <w32-quote-process-args>: Include unconditionally. + Improve wording. + (Windows Printing): Improve wording. + (Windows Misc) [@iftex]: Add an @inforef to the on-line manual for the + rest of this node. + +2006-07-07 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Exporting): Document `C-c C-e' as the prefix for exporting + commands. + (Global TODO list): Document the use of the variables + `org-agenda-todo-ignore-scheduled' and + `org-agenda-todo-list-sublevels'. + +2006-07-05 Richard Stallman <rms@gnu.org> + + * faq.texi (Scrolling only one line): Fix xref. + +2006-07-05 Thien-Thi Nguyen <ttn@gnu.org> + + * building.texi (Lisp Eval): + * faq.texi (Evaluating Emacs Lisp code): + Throughout, replace eval-current-buffer with eval-buffer. + +2006-07-05 Nick Roberts <nickrob@snap.net.nz> + + * mule.texi (Coding Systems, Specify Coding): Link descriptions + of character translation. + +2006-07-04 Nick Roberts <nickrob@snap.net.nz> + + * rmail.texi (Remote Mailboxes): Add missing @code keyword. + +2006-07-03 Karl Berry <karl@gnu.org> + + * emacs.texi (\hbadness): Set to 6000 so we aren't bothered by + not-too-underfull hboxes in the TeX output. + * abbrevs.texi, buffers.texi, building.texi, calendar.texi, + * cmdargs.texi, custom.texi, dired.texi, macos.texi, + * maintaining.texi, misc.texi, mule.texi, programs.texi, rmail.texi, + * sending.texi, text.texi: Fix overfull/underfull boxes. + +2006-07-03 Romain Francoise <romain@orebokech.com> + + * m-x.texi (M-x): Fix. + +2006-07-03 Richard Stallman <rms@gnu.org> + + * rcirc.texi (Scrolling conservatively): Fix xref. + + * pcl-cvs.texi (Viewing differences): Usage fix. + + * search.texi (Other Repeating Search): filename -> file name. + + * misc.texi (Narrowing): Minor cleanups. + + * files.texi (Visiting): filename -> file name. + + * emacs.texi (Top): Update subnode menus. + + * mule.texi (Coding Systems): Move char translation stuff here. + (Specify Coding, Output Coding): New nodes, out of Recognize Coding. + (Recognize Coding): Substantial local rewrites. + (International): Update menu. + + * display.texi (Auto Scrolling): New node, broken out of Scrolling. + (Scrolling): Substantial local rewrites. + (Display): Update menu and intro. + + * dired.texi: filename -> file name. + + * custom.texi (Safe File Variables): Texinfo usage fix. + +2006-07-03 Ted Zlatanov <tzz@lifelogs.com> + + * help.texi, m-x.texi: Lots of cleanups. + +2006-07-03 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Agenda commands): Document `s' key to save all org-mode + buffers. + +2006-06-30 Eli Zaretskii <eliz@gnu.org> + + * msdog.texi (ls in Lisp, Windows Keyboard, Windows Mouse) + (Windows Processes, Windows Misc): Shorten the printed version by + selectively conditioning less important portions by @ifnottex. + +2006-06-30 Ralf Angeli <angeli@caeruleus.net> + + * pcl-cvs.texi (Customizing Faces): Remove -face suffix from face + names. Mention `cvs-msg' face. + +2006-06-29 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Checkboxes): New section. + +2006-06-28 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Embedded LaTeX): Fix typos and implement small improvements + throughout this chapter. + +2006-06-27 Chong Yidong <cyd@stupidchicken.com> + + * info.texi (Help-Small-Screen): Clarify placement of "All" and "Top" + text for standalone vs Emacs info. + (Help): Clarify header line description. Use mouse-1 for clicks. + (Help-P): Use mouse-1 for clicks. + (Help-^L): "Top" and "All" not displayed with dashes in Emacs. + (Help-^L, Help-M, Help-Int, Search Index, Go to node) + (Choose menu subtopic): Remove gratuitous Emacs command names. + (Help-FOO): Put usual behavior first. + (Help-Xref): Clicking on xrefs works in Emacs. + (Search Text): Clarify what the default behavior is. + (Create Info buffer): Fix Emacs window/X window confusion. + (Emacs Info Variables): Fix for new Emacs init file behavior. + +2006-06-27 Richard Stallman <rms@gnu.org> + + * mini.texi (Minibuffer File): Minor cleanup. + +2006-06-25 Nick Roberts <nickrob@snap.net.nz> + + * frames.texi (XTerm Mouse): Rename to... + (Text-Only Mouse): ...this. Mention t-mouse-mode. + + * emacs.texi (Top): Use new node name. + +2006-06-24 Eli Zaretskii <eliz@gnu.org> + + * emacs.texi (Top): Update the detailed menu according to changes in + msdog.texi. + + * msdog.texi (Windows Keyboard): New section. + (Windows Mouse): New section. + (Windows System Menu): Remove section (text merged with "Windows + Keyboard"). + (Windows Misc): New section. + + * dired.texi (Dired Enter): Refer to msdog.texi for ls-lisp emulation. + + * msdog.texi (ls in Lisp): New section. + + * files.texi (Visiting): Document case-insensitive wildcard matching + under find-file-wildcards. + +2006-06-24 Andreas Seltenreich <uwi7@rz.uni-karlsruhe.de> + + * gnus.texi (Summary Buffer Lines): Fix typo. + +2006-06-23 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Embedded LaTeX): New chapter. + (Archiving): Section rewritten. + (Enhancing text): Some parts moved to the new chapter about LaTeX. + +2006-06-20 Bill Wohler <wohler@newt.com> + + Release MH-E manual version 8.0.1. + + * mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for + release 8.0.1. + (Preface): Depend on GNU mailutils 1.0 and higher. + +2006-06-19 Katsumi Yamaoka <yamaoka@jpl.org> + + * message.texi (News Headers): Update message-syntax-checks section. + +2006-06-19 Karl Berry <karl@gnu.org> + + * info.texi (Advanced): Mention C-q, especially with ?. + +2006-06-19 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Publishing links): Document the `:link-validation-function' + property. + (Extensions and Hacking): New chapter, includes some sections of the + "Miscellaneous" chapter. + +2006-06-16 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp> + + * macos.texi (Mac Input): Add description of mac-function-modifier. + Now Unicode keyboard layouts work. + +2006-06-10 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Progress logging): New section. + +2006-06-10 Richard Stallman <rms@gnu.org> + + * mule.texi (Recognize Coding): Clarify previous change. + +2006-06-09 Kenichi Handa <handa@m17n.org> + + * mule.texi (Recognize Coding): Describe the convention of "CODING!" + notation. + +2006-06-07 Kevin Ryde <user42@zip.com.au> + + * mule.texi (Coding Systems): Footnote xref "MS-DOS and MULE" in main + manual for @ifnottex, but in emacs-extra for @iftex. + + * cmdargs.texi (General Variables): Fix smtpmail xref. + +2006-05-29 Stefan Monnier <monnier@iro.umontreal.ca> + + * viper.texi (Viper Specials): + * programs.texi (Comment Commands): + * gnus.texi (Example Setup): + * faq.texi (Backspace invokes help): + * dired-x.texi (Optional Installation Dired Jump): + * custom.texi (Specifying File Variables): + * calc.texi (Defining Simple Commands): Use ;; instead of ;;; to better + follow coding conventions. + +2006-05-18 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Saving Articles): Clarify gnus-summary-save-article-mail. + +2006-06-07 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Watch Expressions): Move node to end. + (GDB Graphical Interface): Move description of clicks in fringe... + (GDB commands in the Fringe): ...to here. New node. + +2006-06-06 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (ASCII export): Document indentation adaptation. + (Setting tags): Document mutually-exclusive tags. + +2006-06-05 Romain Francoise <romain@orebokech.com> + + * url.texi (irc): Mention new funs `url-irc-rcirc' and `url-irc-erc'. + Fix typo. + + * gnus-faq.texi (Question 8.6): Update reference to the Gnus + channel (#gnus@irc.freenode.net). + Fix typos. Update copyright notice. + + * cc-mode.texi (Getting Started, Indentation Commands, Config Basics) + (Custom Filling and Breaking, Custom Braces, Syntactic Symbols) + (Line-Up Functions, Custom Macros): + * ediff.texi (Window and Frame Configuration) + (Highlighting Difference Regions, Highlighting Difference Regions): + * emacs-mime.texi (Display Customization): + * erc.texi (History): + * eshell.texi (Known problems): + * eudc.texi (Overview, BBDB): + * gnus.texi (NNTP, IMAP, Advanced Scoring Examples) + (The problem of spam, SpamOracle, Extending the Spam package) + (Conformity, Terminology): + * idlwave.texi (Routine Info, Routine Info) + (Class and Keyword Inheritance, Padding Operators) + (Breakpoints and Stepping, Electric Debug Mode) + (Examining Variables, Troubleshooting): + * org.texi (Creating timestamps): + * reftex.texi (Commands, Options, Changes): + * tramp.texi (Inline methods, Password caching) + (Auto-save and Backup, Issues): + * vip.texi (Files, Commands in Insert Mode): + * viper.texi (Emacs Preliminaries, States in Viper) + (Packages that Change Keymaps, Viper Specials, Groundwork): + * xresmini.texi (GTK resources): + Fix various typos. + +2006-06-05 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (GDB Graphical Interface): Update bindings. + (Commands of GUD): Add gud-print. Remove gud-run. + Restate availability more generally. + +2006-06-03 Ted Zlatanov <tzz@lifelogs.com> + + * mini.texi: Lots of cleanups. + +2006-06-01 Luc Teirlinck <teirllm@auburn.edu> + + * misc.texi (Shell History Copying): Update descriptions of `C-c RET' + and Mouse-2. + +2006-06-01 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * screen.texi (Menu Bar): Change menu-bar-start to menu-bar-open. + +2006-05-31 Michael Ernst <mernst@alum.mit.edu> + + * ediff.texi: Fix typos. + +2006-05-31 Richard Stallman <rms@gnu.org> + + * basic.texi (Moving Point): Fix previous change. + +2006-05-30 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Small typo fixes. + +2006-05-29 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (Frequently Asked Questions): Disable zsh zle. + +2006-05-29 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * screen.texi (Menu Bar): F10 for Gtk+/Lesstif/Lucid menus. + +2006-05-28 Ted Zlatanov <tzz@lifelogs.com> + + * basic.texi: Many simplifications and improvements in wording. + +2006-05-27 Thien-Thi Nguyen <ttn@gnu.org> + + * pcl-cvs.texi: Fix typos. + (Customization): Say "us". + +2006-05-26 Eli Zaretskii <eliz@gnu.org> + + * org.texi: Remove bogus @setfilename. + +2006-05-26 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (ASCII export): Omit command name. + (HTML export): Add prefix to all lines in Local Variable example. + (Acknowledgments): Typeset names in italics. + +2006-05-26 Nick Roberts <nickrob@snap.net.nz> + + * anti.texi (Antinews): Create a node for gdb-ui. + +2006-05-24 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Plain lists): Add new item navigation commands. + (External links): Document elisp and info links. + (Custom searches): New section. + (Publishing): New chapter. + (HTML export): Include a list of supported CSS classes. + (Setting tags): Describe the fast-tag-setting interface. + +2006-05-22 Reiner Steib <Reiner.Steib@gmx.de> + + * frames.texi (Menu Bars, Tool Bars): Add index entries. + +2006-05-20 Richard Stallman <rms@gnu.org> + + * dired.texi (Dired Navigation): dired-goto-file is now j. + +2006-05-20 Luc Teirlinck <teirllm@auburn.edu> + + * dired-x.texi: ifinfo -> ifnottex. + +2006-05-20 Eli Zaretskii <eliz@gnu.org> + + * mule.texi (Coding Systems): Mention the undecided-* coding systems + and their aliases. + + * msdog.texi (Windows Printing): Mention non-support of plain text + printing with some el-cheapo printers, and suggest a workaround. + +2006-05-20 Kevin Ryde <user42@zip.com.au> + + * text.texi (TeX Print): tex-dvi-view-command has a default value, + remove the bit saying you must set it. + +2006-05-19 Luc Teirlinck <teirllm@auburn.edu> + + * trouble.texi (Checklist): + * text.texi (Text, Auto Fill, Text Mode): + * search.texi (Nonincremental Search): + * rmail.texi (Rmail Labels): + * mule.texi (Input Methods, Multibyte Conversion): + * misc.texi (Gnus, Where to Look, PostScript): + * maintaining.texi (Create Tags Table): + * indent.texi (Indentation Commands): + * fixit.texi (Spelling): + * emacs.texi (Copying): + * custom.texi (Init File): ifinfo -> ifnottex. + +2006-05-18 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Saving Articles): Clarify gnus-summary-save-article-mail. + +2006-05-17 Richard Stallman <rms@gnu.org> + + * files.texi (Diff Mode): Mention C-x `. + +2006-05-08 Richard Stallman <rms@gnu.org> + + * custom.texi (Disabling): Textual cleanups. + +2006-05-12 Reiner Steib <Reiner.Steib@gmx.de> + + * message.texi (Interface): Add tool bar customization. + (MIME): Index and text additions for mml-attach. + (MIME): Describe mml-dnd-protocol-alist and + mml-dnd-attach-options. + + * gnus.texi (Oort Gnus): Reorder entries in sections. + Fix some entries. + (Starting Up): Add references to "Emacs for Heathens" and to + "Finding the News". Add user-full-name and user-mail-address. + (Group Buffer Format): Add tool bar customization and update. + (Summary Buffer): Add tool bar customization. + (Posting Styles): Add message-alternative-emails. + +2006-05-12 Glenn Morris <rgm@gnu.org> + + * calendar.texi (Displaying the Diary, Format of Diary File): + Refer to diary-view-entries, diary-list-entries, + diary-show-all-entries rather than obsolete aliases. + +2006-05-12 Eli Zaretskii <eliz@gnu.org> + + * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary) + (Displaying the Diary, Special Diary Entries, Importing Diary): + * building.texi (Compilation Shell): + * buffers.texi (Several Buffers) [iftex]: Replace @xref's to + emacs-xtra with @inforef's. + + * files.texi (Visiting): Fix wording. + + * mule.texi (Coding Systems, Text Coding): More indexing. + Mention that C-x RET f can set eol conversion. + +2006-05-09 Michael Albinus <michael.albinus@gmx.de> + + * tramp.texi (Filename completion): Improve wording. + +2006-05-07 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * xresmini.texi (GTK resources): Insert GTK description. + + * xresources.texi (GTK resources): metafont should be menufont. + +2006-05-07 Romain Francoise <romain@orebokech.com> + + * faq.texi (Using regular expressions): Fix typo. + (Packages that do not come with Emacs): Fix capitalization. + (Replacing text across multiple files): Expand node to explain how + to use `dired-do-query-replace-regexp' in more detail, based on + suggestion by Eric Hanchrow <offby1@blarg.net>. + +2006-05-06 Michael Albinus <michael.albinus@gmx.de> + + * mini.texi (Completion Options): + * tramp.texi (Filename completion): Completion of remote files' + method, user name and host name is active only in partial + completion mode. + +2006-05-06 Bill Wohler <wohler@newt.com> + + Release MH-E manual version 8.0. + + * mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for + release 8.0. + +2006-05-06 Bill Wohler <wohler@newt.com> + + * mh-e.texi (MH-BOOK-HOME): Change from + http://www.ics.uci.edu/~mh/book/mh to + http://rand-mh.sourceforge.net/book/mh. + Replace .htm suffix with .html for MH book files. + (Using This Manual): Update key binding for getting relevant + chapter in Info from command key. + (Ranges): Fix itemx. + +2006-05-06 Eli Zaretskii <eliz@gnu.org> + + * makefile.w32-in (emacs.dvi): + * Makefile.in (emacs.dvi): Add xresmini.texi. + + * xresmini.texi (Table of Resources): Remove xref to non-existent + node "LessTif Resources". + + * msdog.texi (Microsoft Windows): + * calendar.texi (Calendar/Diary, Displaying the Diary) + (Special Diary Entries, Importing Diary, Holidays): + * programs.texi (Program Modes): + * text.texi (Text): + * buffers.texi (Several Buffers): + * files.texi (Comparing Files): Fix cross-references to emacs-xtra. + +2006-05-06 Eli Zaretskii <eliz@gnu.org> + + The following changes merge the emacs-xtra manual into the main + manual, but only for on-line version of the manual. + + * vc2-xtra.texi (Version Backups, Local Version Control) + (Making Snapshots, Change Logs and VC, Version Headers) + (Customizing VC, CVS Options) [ifnottex]: Conditional xref's for + on-line manual. + + * vc1-xtra.texi (VC Dired Mode) [ifnottex]: Conditional xref's + for on-line manual. + + * msdog-xtra.texi (MS-DOS, MS-DOS Keyboard, MS-DOS Mouse) + (MS-DOS Display, MS-DOS File Names, MS-DOS Printing) + (MS-DOS and MULE, MS-DOS Processes) [ifnottex]: Conditional xref's + for on-line manual. + + * fortran-xtra.texi (Fortran, Fortran Autofill) + (Fortran Autofill, Fortran Abbrev) [ifnottex]: Conditional xref's + for on-line manual. + + * picture-xtra.texi (Basic Picture, Rectangles in Picture) [ifnottex]: + Conditional xref's for on-line manual. + + * emerge-xtra.texi (Emerge, Overview of Emerge) + (Fine Points of Emerge) [ifnottex]: Conditional xref's for on-line + manual. + + * Makefile.in (INFO_TARGETS): Remove ../info/emacs-xtra. + (EMACS_XTRA): New variable, lists the new *-xtra.texi files. + (EMACSSOURCES): Use EMACS_XTRA. + (../info/emacs-xtra): Remove. + (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites. + + * makefile.w32-in (INFO_TARGETS): Remove $(infodir)/emacs-xtra. + (EMACS_XTRA): New variable, lists the new *-xtra.texi files. + (EMACSSOURCES): Use EMACS_XTRA. + ($(infodir)/emacs-xtra): Remove. + (emacs-xtra.dvi): Add EMACS_XTRA to prerequisites. + + * trouble.texi (Quitting): + * text.texi (Text): + * programs.texi (Program Modes): + * msdog.texi (Microsoft Windows): + * frames.texi (Frames): + * files.texi (Backup, Version Control, VC Concepts) + (Types of Log File, Advanced C-x v v, Log Buffer, Old Versions) + (Registering, VC Status, VC Undo, Multi-User Branching) + (Comparing Files): + * calendar.texi (Calendar/Diary, Holidays, Displaying the Diary) + (Displaying the Diary, Special Diary Entries, Importing Diary): + * buffers.texi (Several Buffers): Replace inforef to emacs-xtra by + conditional xref's, depending on @iftex/@ifnottex. + + * msdog.texi (Microsoft Windows) [ifnottex]: Add menu entry for + "MS-DOS". @include msdog-xtra.texi. + + * programs.texi (Programs) [ifnottex]: Add menu entry for "Fortran". + <Top Level> [ifnottex]: @include fortran-xtra.texi. + + * files.texi (Secondary VC Commands) [ifnottex]: Add menu entries + for vc-xtra.texi subsections. + (VC Undo) [ifnottex]: @include vc1-xtra.texi and @lowersections it. + (Multi-User Branching) [ifnottex]: @include vc2-xtra.texi. + + * sending.texi (Sending Mail): A @node line without explicit Prev, + Next, and Up links. + + * abbrevs.texi (Abbrevs): A @node line without explicit Prev, + Next, and Up links. + + * emacs.texi (Top) [ifnottex]: Add menu entries for "Picture Mode" + and its sections. @include picture-xtra.texi. + + * maintaining.texi (Maintaining) [ifnottex]: Add menu entry for + "Emerge". + (List Tags) [ifnottex]: @include emerge-xtra.texi. + + * cal-xtra.texi (Daylight Savings): Remove this node: it is an + exact duplicate of its name-sake in calendar.texi. + + * calendar.texi (Calendar/Diary) [ifnottex]: Add menu item for + "Advanced Calendar/Diary Usage". + (Time Intervals) [ifnottex]: @include cal-xtra.texi. + + * dired.texi (Subdirectories in Dired) [ifnottex]: @include + dired-xtra.texi. + (Dired) [ifnottex]: Add menu entry for "Subdir Switches". + + * files.texi (Reverting) [ifnottex]: @include arevert-xtra.texi. + (Files) [ifnottex]: Add menu entry for Autorevert. + + * emacs-xtra.texi (Introduction): Reword to make consistent with + printed version only. + <Top level>: Remove the body of all chapters and move them to the + new *-xtra.texi files. Use @raisesections and @lowersections to + convert sections to chapters etc. + + * msdog-xtra.texi: + * fortran-xtra.texi: + * vc-xtra.texi: + * vc1-xtra.texi: + * vc2-xtra.texi: + * emerge-xtra.texi: + * cal-xtra.texi: + * dired-xtra.texi: + * arevert-xtra.texi: New files, with text from respective chapters + of emacs-xtra.texi. Convert each @chapter into @section, @section + into @subsection, etc. + + * emacs-xtra.texi (MS-DOS): Renamed from "MS-DOG". All references + updated. + + * msdog.texi (Microsoft Windows): Rename from "Emacs and Microsoft + Windows". All references updated. + +2006-05-06 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp> + + * macos.texi (Mac Input): Mention input from Character Palette. + (Mac Font Specs): Fix typo. + +2006-05-05 Richard Stallman <rms@gnu.org> + + * files.texi (Diff Mode): Minor cleanup. + +2006-05-05 Karl Berry <karl@gnu.org> + + * texinfo.tex (\definetextfonsizexi, \definetextfonsizex): New cmds. + (\fonttextsize): New user-level command to change text font size. + * emacs.texi: Call @fonttextsize 10, inside @tex to avoid + errors from the current release of makeinfo (4.8). + * help.texi (Library Keywords): Change widest word in multitable + template from `emulations' to `convenience'. (Not sure if this is + related to the font change.) + +2006-05-05 Eli Zaretskii <eliz@gnu.org> + + * files.texi (File Names): Add a footnote about limited support of + ~USER on MS-Windows. + + * cmdargs.texi (Initial Options): Add a footnote about limited + support of ~USER on MS-Windows. + +2006-05-03 Richard Stallman <rms@gnu.org> + + * files.texi (Diff Mode): Node moved here. + (Comparing Files): Delete what duplicates new node. + (Files): Put Diff Mode in menu. + + * misc.texi (Diff Mode): Moved to files.texi. + + * emacs.texi (Top): Update menu for Diff Mode. + + * trouble.texi (Emergency Escape): Simplify. + + * emacs.texi (Top): Minor clarification. + +2006-05-03 Teodor Zlatanov <tzz@lifelogs.com> + + * commands.texi, entering.texi, screen.texi: Many simplifications. + +2006-05-03 Richard Stallman <rms@gnu.org> + + * commands.texi (Text Characters): Delete paragraph about unibyte + non-ASCII printing chars. + + * killing.texi (Killing): Say "graphical displays". + * display.texi: Say "graphical displays". + + * cmdargs.texi (Misc X): Say "graphical displays". + +2006-05-01 Richard Stallman <rms@gnu.org> + + * emacs.texi (Top): Add Diff Mode to menu. + +2006-05-01 Aaron S. Hawley <Aaron.Hawley@uvm.edu> + + * misc.texi (Diff Mode): New node. + +2006-05-01 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp> + + * macos.texi (Mac International): Now Carbon Emacs has ATSUI support. + (Mac Environment Variables): Shorten example line. + (Mac Font Specs): Shorten lisp lines. Add descriptions for ATSUI. + +2006-05-01 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (GUD Customization): Describe cases %d and %c. + Update description for %e. + +2006-04-30 Glenn Morris <rgm@gnu.org> + + * calendar.texi (LaTeX Calendar): Mention cal-tex-preamble-extra. + +2006-04-29 Dan Nicolaescu <dann@ics.uci.edu> + + * custom.texi (Examining): Update C-h v output example. + +2006-04-29 Kim F. Storm <storm@cua.dk> + + * building.texi (Grep Searching): Add lgrep and rgrep. + +2006-04-26 Reiner Steib <Reiner.Steib@gmx.de> + + * pgg.texi (Caching passphrase): Fix markup and typos. Simplify. + +2006-04-26 Sascha Wilde <wilde@sha-bang.de> (tiny change) + + * pgg.texi (Caching passphrase): Add pgg-gpg-use-agent. + +2006-04-24 Bill Wohler <wohler@newt.com> + + * mh-e.texi (Getting Started): Make it more explicit that you need + to install MH. Add pointers to current MH implementations. + +2006-04-23 Richard Stallman <rms@gnu.org> + + * emacs.texi [TeX]: Use xresmini.texi instead of xresources.texi. + + * xresmini.texi: New file. + + * xresources.texi (Face Resources): Split table into font resources + and the rest. Combine similar attributes for brevity. + +2006-04-21 Bill Wohler <wohler@newt.com> + + Release MH-E manual version 7.94. + + * mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for + release 7.94. + +2006-04-21 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Many small fixes. + (Handling links): Rename from "Managing links". + +2006-04-21 Eli Zaretskii <eliz@gnu.org> + + * emacs-xtra.texi (MS-DOS File Names): Remove section about + backslashes and case-insensitivity in file names (moved to the + main manual). + (MS-DOS Printing): Move most of the text to the main manual. + + * msdog.texi (Windows Files, Windows HOME, MS-Windows Printing): + New nodes. + (Windows Processes, Windows System Menu): Add index entries and + fix wording. + +2006-04-20 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Spam Statistics Package): Fix typo in @pxref. + (Splitting mail using spam-stat): Fix @xref. + +2006-04-20 Chong Yidong <cyd@stupidchicken.com> + + * gnus.texi (Spam Package): Major revision of the text. + Previouly this node was "Filtering Spam Using The Spam ELisp Package". + +2006-04-20 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Time stamps): Better explanation of the purpose of + different time stamps. + (Structure editing, Plain lists): More details on how new items + and headings are inserted. + +2006-04-18 J.D. Smith <jdsmith@as.arizona.edu> + + * misc.texi (Shell Ring): Add notes on saved input when + navigating off the end of the history list. + +2006-04-18 Chong Yidong <cyd@mit.edu> + + * misc.texi (Shell Options): Correct default value of + comint-scroll-show-maximum-output. + +2006-04-18 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Formula syntax): Fix link to Calc Manual. + +2006-04-17 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Emacsen): Don't support Emacs 20.7 and XEmacs 21.1. + +2006-04-17 Bill Wohler <wohler@newt.com> + + * mh-e.texi (Folders): Update mh-before-quit-hook and + mh-quit-hook example with code that removes the buffers rather + than just bury them. + +2006-04-18 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Watch Expressions): Update. + +2006-04-17 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.0.53. + +2006-04-13 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Updating settings): New section. + (Visibility cycling): Better names for the startup folding + options. + (Exporting): Completely restructured. + (The very busy C-c C-c key): New section. + (Summary of in-buffer settings): New section. + +2006-04-12 Richard Stallman <rms@gnu.org> + + * search.texi: Clean up previous change. + +2006-04-12 Eli Zaretskii <eliz@gnu.org> + + * search.texi (Regexp Backslash, Regexp Replace): Add index + entries for ``back reference'' and mention the term itself in the + text. + +2006-04-11 Richard Stallman <rms@gnu.org> + + * custom.texi (Safe File Variables): + Document enable-local-variables = :safe. + +2006-04-11 Karl Berry <karl@gnu.org> + + * emacs-xtra.texi, emacs.texi (Dired under VC, VC Dired Commands) + (Remote Repositories, Version Backups, Local Version Control) + (Snapshots, Making and Using Snapshots, Snapshot Caveats) + (Miscellaneous Commands and Features of VC, Change Logs and VC) + (Renaming VC Work Files and Master Files) + (Inserting Version Control Headers, Customizing VC, General Options) + (Options for RCS and SCCS, Options specific for CVS): Move all + these nodes to emacs-xtra.texi, for brevity. + * cmdargs.texi, files.texi: Change cross-references. + +2006-04-11 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi, gnus-faq.texi, message.texi: Gnus v5.10.8 is released. + +2006-04-10 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Misc Group Stuff, Summary Buffer, Article Keymap) + (Server Commands): Key `v' is reserved for users. + +2006-04-11 J.D. Smith <jdsmith@as.arizona.edu> + + * files.texi (Old Versions): Update description of vc-annotate's + use of color to indicate date ranges. + +2006-04-11 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Link format): New section, emphasis on bracket links. + (External links): Document bracket links. + (FAQ): Expand to cover shell links and the new link format. + +2006-04-09 Kevin Ryde <user42@zip.com.au> + + * org.texi (Formula syntax): Typo in node name of calc-eval xref. + + * sending.texi (Mail Sending): In send-mail-function @pxref smtpmail, + put info and printed manual names the right way around. + +2006-04-09 Karl Berry <karl@gnu.org> + + * msdog.texi, emacs-xtra.texi: Move all the MS-DOS material to + emacs-xtra.texi, leaving only MS Windows information. + * building.texi, emacs.texi, frames.texi, gnu.texi, macos.texi, + * msdog.texi, mule.texi, trouble.texi: Change cross-references and + node names. + + * emacs.texi: Move @summarycontents and @contents to the beginning + of the file. + +2006-04-07 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Summary Buffer Lines): Add `*'. + +2006-04-07 Jochen K,A|(Bpper <jochen@fhi-berlin.mpg.de> + + * gnus.texi (Group Parameters): + Mention gnus-permanently-visible-groups. + +2006-04-06 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Face): Fix typo. + +2006-04-05 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (X-Face): Clarify. + (Face): Need Emacs with PNG support. + +2006-04-08 Kevin Ryde <user42@zip.com.au> + + * text.texi (Fill Commands): fill-nobreak-predicate is now a hook. + +2006-04-07 Richard Stallman <rms@gnu.org> + + * programs.texi (Comments, Comment Commands, Options for Comments) + (Multi-Line Comments): "Align", not "indent". + (Basic Indent): C-j deletes trailing whitespace before the newline. + +2006-04-06 Richard Stallman <rms@gnu.org> + + * idlwave.texi: Delete the blocks "not suitable for inclusion with + Emacs". + + * programs.texi (Basic Indent): Clarify relationship of C-j to TAB. + +2006-04-06 Eli Zaretskii <eliz@gnu.org> + + * killing.texi (Rectangles): Add index entry for marking a rectangle. + +2006-04-06 J.D. Smith <jdsmith@as.arizona.edu> + + * idlwave.texi: Updated for IDLWAVE version 6.0, factoring out + blocks not suitable for inclusion with Emacs using variable + PARTOFEMACS. + +2006-04-05 Richard Stallman <rms@gnu.org> + + * emacs.texi (Top): Update subnode menu. + + * trouble.texi (Unasked-for Search): Node deleted. + (Lossage): Delete from menu. + +2006-04-04 Richard Stallman <rms@gnu.org> + + * trouble.texi: Various cleanups. + (Checklist): Don't bother saying how to snail a bug report. + (Emergency Escape): Much rewriting. + (After a Crash): Rename the core dump immediately. + (Total Frustration): Call it a psychotherapist. + (Bug Criteria): Avoid "illegal instruction". + (Sending Patches): We always put the contributor's name in. + + * misc.texi (Thumbnails): Minor correction. + +2006-04-04 Simon Josefsson <jas@extundo.com> + + * gnus.texi (Security): Improve. + +2006-04-03 Richard Stallman <rms@gnu.org> + + * misc.texi (Thumbnails): Minor cleanup. + +2006-04-02 Karl Berry <karl@gnu.org> + + * sending.texi (Mail Sending): pxref to Top needs five args. + + * texinfo.tex: Update to current version (2006-03-21.13). + +2006-04-02 Bill Wohler <wohler@newt.com> + + * mh-e.texi (Getting Started, Junk, Bug Reports) + (MH FAQ and Support): Fix URLs. + +2006-03-31 Romain Francoise <romain@orebokech.com> + + * gnus.texi (Virtual Groups): `nnvirtual-always-rescan' defaults + to t, not nil (and has for the past eight years). + +2006-03-31 Richard Stallman <rms@gnu.org> + + * emacs.texi (Top): Update subnode menu. + + * help.texi (Help Mode): Cleanup. + + * dired.texi: Many cleanups. + (Dired Deletion): Describe dired-recursive-deletes. + (Operating on Files): dired-create-directory moved. + (Misc Dired Features): Move to here. + (Tumme): Node moved to misc.texi. + + * custom.texi: Many cleanups. + (Minor Modes): Don't mention ISO Accents Mode. + (Examining): Update C-h v output example. + (Hooks): Add index and xref for add-hook. + (Locals): Delete list of vars that are always per-buffer. Rearrange. + (Local Keymaps): Don't mention lisp-mode-map, c-mode-map. + + * misc.texi: Many cleanups. + (beginning): Add to summary of topics. + (Shell): Put eshell xref at the end. Remove eshell from table. + (Thumbnails): New node. + +2006-03-31 Reiner Steib <Reiner.Steib@gmx.de> + + * message.texi, gnus.texi: Bump version to 5.11. + +2006-03-29 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Top): Add comment about version line. + + * message.texi (Top): Ditto. Change to take named versions into + account. + +2006-03-28 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Posting Styles): Add x-face-file to example. + (X-Face): Refer to posting styles. + + * gnus-faq.texi ([5.8]): Add x-face-file. + ([8.4]): Add links to gmane.emacs.gnus.user and + gmane.emacs.gnus.general. + +2006-03-28 Eli Zaretskii <eliz@gnu.org> + + * files.texi (File Name Cache): Make it clear that the cache is + not persistent. + +2006-03-27 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus-faq.texi: Use .invalid. + ([5.4]): Fix gnus-posting-styles example. + +2006-03-27 Romain Francoise <romain@orebokech.com> + + * faq.texi (Emacs/W3): Rename from `w3-mode'. Mention that + Emacs/W3 needs a new maintainer. + (Ispell): Update author and version info. + (Mailcrypt): Mention PGG. + (New in Emacs 22): Add PGG to the list of new packages. + Include minor changes from "Ramprasad B" <ramprasad_i82@yahoo.com> + updating dead URLs. + +2006-03-25 Karl Berry <karl@gnu.org> + + * ada-mode.texi, autotype.texi, calc.texi, cc-mode.texi, cl.texi, + * dired-x.texi, ebrowse.texi, ediff.texi, emacs-mime.texi, + * emacs-xtra.texi, emacs.texi, erc.texi, eshell.texi, eudc.texi, + * faq.texi, forms.texi, gnu.texi, gnus.texi, idlwave.texi, + * info.texi, message.texi, mh-e.texi, pcl-cvs.texi, pgg.texi, + * rcirc.texi, reftex.texi, sc.texi, ses.texi, sieve.texi, + * speedbar.texi, url.texi, vip.texi, viper.texi, widget.texi, + * woman.texi: (1) use @copyright{} instead of (C) in typeset text; + (2) do not indent copyright year list (or anything else). + +2006-03-21 Bill Wohler <wohler@newt.com> + + * mh-e.texi (Folders): Various edits. + +2006-03-20 Romain Francoise <romain@orebokech.com> + + * gnus.texi (Mail Folders): Grammar fix. + +2006-03-21 Juanma Barranquero <lekktu@gmail.com> + + * files.texi (VC Dired Mode): Remove misplaced brackets. + +2006-03-21 Andre Spiegel <spiegel@gnu.org> + + * files.texi: Various updates and clarifications in the VC chapter. + +2006-03-19 Luc Teirlinck <teirllm@auburn.edu> + + * help.texi (Help Mode): Document "C-c C-c". + +2006-03-19 Bill Wohler <wohler@newt.com> + + * mh-e.texi (Replying): Document Mail-Followup-To. + Change manually-formatted table to multitable. Add debugging info. + Move description of mh-reply-default-reply-to into paragraph + that describes its values. + +2006-03-17 Bill Wohler <wohler@newt.com> + + * mh-e.texi: Use smallexample and smalllisp consistenly. + (Sending Mail Tour): Update method of entering + addresses and subject. + (Sending Mail Tour, Reading Mail Tour, Processing Mail Tour) + (Adding Attachments, Searching): Update screenshots for Emacs 22. + +2006-03-16 Luc Teirlinck <teirllm@auburn.edu> + + * emacs-xtra.texi (Top): Avoid ugly continuation line in + menu in the standalone Info reader. + +2006-03-15 Chong Yidong <cyd@stupidchicken.com> + + * emacs-xtra.texi (Emerge, Picture Mode, Fortran): New chapters, + moved here from Emacs manual. + + * programs.texi (Fortran): Section moved to emacs-xtra. + (Program Modes): Xref to Fortran in emacs-xtra. + + * maintaining.texi (Emerge): Move to emacs-xtra. + * files.texi (Comparing Files): Xref to Emerge in emacs-xtra. + + * picture.texi: File deleted. + * Makefile.in: + * makefile.w32-in: Remove picture.texi. + + * text.texi (Text): Xref to Picture Mode in emacs-xtra. + * abbrevs.texi (Abbrevs): + * sending.texi (Sending Mail): Picture node removed. + + * emacs.texi (Top): Update node listings. + +2006-03-15 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Version number change only. + +2006-03-14 Bill Wohler <wohler@newt.com> + + * mh-e.texi: Add index entries around each paragraph rather than + depend on entries from beginning of node. Doing so ensures that + index entries are less likely to be forgotten if text is cut and + pasted, and are necessary anyway if the references are on a + separate page. It seems that makeinfo is now (v. 4.8) only + producing one index entry per node, so there is no longer any + excuse not to. Use subheading instead of heading. The incorrect + use of heading produced very large fonts in Info--as large as the + main heading. + (From Bill Wohler): MH-E never did appear in Emacs 21--MH-E + versions 6 and 7 appeared *around* the time of these Emacs releases. + +2006-03-13 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Clean view): Document new startup options. + +2006-03-12 Richard Stallman <rms@gnu.org> + + * calendar.texi: Various cleanups. + +2006-03-11 Bill Wohler <wohler@newt.com> + + * mh-e.texi (Preface, More About MH-E, Options, HTML, Folders) + (Composing, Scan Line Formats): Fix @refs. + (Getting Started): Define MH profile and MH profile components. + (Incorporating Mail, Reading Mail, Viewing, Printing) + (Sending Mail, Forwarding, Editing Drafts, Inserting Letter) + (Signature, Aliases, Scan Line Formats): Use @code instead of @samp + for string constants. + (Tool Bar): Remove spurious quote. + (Junk): Use ``...'' instead of "...". + (Scan Line Formats): Replace @samp with @kbd. + +2006-03-11 Luc Teirlinck <teirllm@auburn.edu> + + * search.texi (Regexps): Use @samp for regexp that is not in Lisp + syntax. + +2006-03-10 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (NoCeM): Mention gnus-use-nocem can also be a number. + +2006-03-10 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Fancy Mail Splitting): Improve sentences so as to be + easy to understand. + +2006-03-09 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi: Markup fix. + (Fancy Mail Splitting): Specify new feature. + +2006-03-08 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Fancy Mail Splitting): Improve descriptions about + partial-words matching. + +2006-03-07 Reiner Steib <Reiner.Steib@gmx.de> + + * emacs-mime.texi (Display Customization): Reword image/.* stuff. + + * gnus.texi (Oort Gnus): Add note about `gnus-load'. + (MIME Commands): Fix mm-discouraged-alternatives. + +2006-03-08 Luc Teirlinck <teirllm@auburn.edu> + + * search.texi (Regexps): More accurately describe which characters + are special in which situations. Recommend _not_ to quote `]' or + `-' when they are not special. + +2006-03-07 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Version number change only. + +2006-03-06 Bill Wohler <wohler@newt.com> + + * mh-e.texi: Move from SourceForge repository to Savannah. + This is version 7.93, which is a total rewrite from the previous + edition 1.3 for MH-E version 5.0.2, and corresponds to MH-E + version 7.93. + +2006-03-03 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Oort Gnus): Add `mm-fill-flowed'. + +2006-03-01 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Interaction): Add item about `org-mouse.el' by + Piotr Zielinski. + (Managing links): Document that also mouse-1 can be used to + activate a link. + (Headlines, FAQ): Add entry about hiding leading stars. + (Miscellaneous): Resort the sections in this chapter to a more + logical sequence. + +2006-02-28 Andre Spiegel <spiegel@gnu.org> + + * files.texi (Old Versions): Clarify operation of C-x v =. + +2006-02-27 Simon Josefsson <jas@extundo.com> + + * emacs-mime.texi (Flowed text): Add mm-fill-flowed. (Sync + 2004-01-27 from the trunk). + +2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org> + + * cc-mode.texi: Rename c-hungry-backspace to + c-hungry-delete-backwards, at the request of RMS. Leave the old + name as an alias. + +2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org> + + * cc-mode.texi: Correct the definition of c-beginning-of-defun, to + include the function header within the defun. + +2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org> + + * cc-mode.texi: Correct two typos. + +2006-02-24 Alan Mackenzie <bug-cc-mode@gnu.org> + + * cc-mode.texi (Comment Commands): State that C-u M-; kills any + existing comment. + (Electric Keys): Add a justification for electric indentation. + (Hungry WS Deletion): Clear up the names and complications of the + BACKSPACE and DELETE keys. + +2006-02-23 Juri Linkov <juri@jurta.org> + + * faq.texi (Common requests): Move `Turning on auto-fill by + default' after `Wrapping words automatically'. Move `Working with + unprintable characters' before `Searching for/replacing newlines'. + Move `Replacing highlighted text' after `Highlighting a region'. + Merge `Repeating commands' and `Repeating a command as many times + as possible' into the former. + (Packages that do not come with Emacs): Add refs to Gmane and + etc/MORE.STUFF. + +2006-02-23 Juri Linkov <juri@jurta.org> + + * faq.texi (Newsgroup archives): Update URLs of GNU mail archives. + (Reporting bugs): Suggest using `M-x report-emacs-bug'. + Add xref to `(emacs)Reporting Bugs'. + (Getting a printed manual): Add URL to other formats of the manual. + (Common requests): Fix menu. + (Highlighting a region): Remove ref to `Turning on syntax highlighting'. + (Horizontal scrolling): Mention `truncate-partial-width-windows'. + (Inserting text at the beginning of each line): Add pxref to + `Changing the included text prefix'. + (Forcing the cursor to remain in the same column): Mention `track-eol' + and `set-goal-column'. Add pxref to `(emacs)Moving Point'. + (Replacing text across multiple files): Add keybinding `Q' for + `dired-do-query-replace'. + +2006-02-22 Carsten Dominik <dominik@science.uva.nl> + + * reftex.texi: Version number and date change only. + + * org.texi (Internal Links): Rewrite to cover the modified + linking system. + +2006-02-21 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Watch Expressions): Update and describe + gdb-speedbar-auto-raise. + +2006-02-19 Richard M. Stallman <rms@gnu.org> + + * emacs.texi: Use @smallbook. + (Top): Update ref to Emacs paper, delete ref to Cookbook. + Update subnode menu. + + * building.texi (Lisp Interaction): Minor addition. + +2006-02-18 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Watch Expressions): Update and be more precise. + +2006-02-17 Eli Zaretskii <eliz@gnu.org> + + * faq.texi: Remove the coding cookie, it's not needed anymore. + +2006-02-15 Francesco Potort,Al(B <pot@gnu.org> + + * maintaining.texi (Create Tags Table): Explain why the + exception when etags writes to files under the /dev tree. + +2006-02-14 Richard M. Stallman <rms@gnu.org> + + * custom.texi (Safe File Variables): Lots of clarification. + Renamed from Unsafe File Variables. + +2006-02-14 Chong Yidong <cyd@stupidchicken.com> + + * custom.texi (Unsafe File Variables): File variable confirmation + assumed denied in batch mode. + +2006-02-14 Richard M. Stallman <rms@gnu.org> + + * building.texi (GDB User Interface Layout): Don't say `inferior' + for program being debugged. + +2006-02-15 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (GDB Graphical Interface): + Replace gdb-use-inferior-io-buffer with gdb-use-separate-io-buffer. + +2006-02-13 Chong Yidong <cyd@stupidchicken.com> + + * custom.texi (Specifying File Variables, Unsafe File Variables): + New nodes, split from File Variables. Document new file local + variable behavior. + +2006-02-13 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp> + + * display.texi (Standard Faces): + * faq.texi (Colors on a TTY): + * files.texi (Visiting): + * frames.texi (Clipboard): + * glossary.texi (Glossary) <Clipboard>: + * xresources.texi (X Resources): Mention Mac OS port. + +2006-02-12 Karl Berry <karl@gnu.org> + + * faq.texi (Emacs for Atari ST): Use Sch@"auble instead of the + 8-bit accented a. + +2006-02-12 Richard M. Stallman <rms@gnu.org> + + * building.texi (Building): Clarify topic in intro. + + * maintaining.texi (Maintaining): Change title; clarify topic. + Delete duplicate index entries. + + * building.texi (Other GDB User Interface Buffers): Clarifications. + + * text.texi (Cell Commands): Clarifications. + + * programs.texi (Defuns): Delete duplicate explanation of + left-margin paren convention. + (Hungry Delete): Minor cleanup. + +2006-02-11 Mathias Dahl <mathias.dahl@gmail.com> + + * dired.texi (Tumme): More tumme documentation. + +2006-02-11 Alan Mackenzie <acm@muc.de> + + * programs.texi ("Hungry Delete"): Correct the appellation of the + backspace and delete keys to @kbd{DEL} and @kbd{DELETE}. + +2006-02-11 Mathias Dahl <mathias.dahl@gmail.com> + + * dired.texi (Tumme): Fix small bug. + +2006-02-10 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp> + + * macos.texi (Mac International): Rename "fontset-mac" to + "fontset-standard". + +2006-02-09 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Gnus Versions): Add history beyond start of Oort. + +2006-02-09 Mathias Dahl <mathias.dah@gmail.com> + + * dired.texi (Tumme): Basic documentation for Tumme added. + +2006-02-08 Romain Francoise <romain@orebokech.com> + + * faq.texi (Top): Remove paragraph about the FAQ being a + transitional document, etc. + (Searching for/replacing newlines): New node. + (Yanking text in isearch): New node. + (Inserting text at the beginning of each line): Rename and make + more general, mention `M-;' in Message mode. + +2006-02-07 Luc Teirlinck <teirllm@auburn.edu> + + * mule.texi (International): + * programs.texi (Basic Indent): Fix typos. + + * faq.texi (Meta key does not work in xterm) + (Emacs does not display 8-bit characters) + (Inputting eight-bit characters): + * custom.texi (Minor Modes): + * display.texi (Text Display): + * commands.texi (Text Characters): Update xrefs. + +2006-02-07 Richard M. Stallman <rms@gnu.org> + + * emacs.texi (Top): Update subnode menu. + Update info on old Emacs papers. + (Intro): "Graphical display", not window system. + + * xresources.texi (GTK styles): Minor clarifications. + + * trouble.texi: "Graphical display", not window system. + (Stuck Recursive): Minor clarification. + + * text.texi: Minor clarifications. + (Sentences): Explain why two-space convention is better. + Explain sentence-end-without-period here. + (Fill Commands): Not here. + (Refill): Node moved down. + (Filling): Update menu. + (Table Creation, Cell Justification, Column Commands): Clarify. + + * sending.texi: Minor clarifications. + + * search.texi (Regexp Backslash): Clarification. + + * rmail.texi: Minor cleanups. + (Rmail): Delete digression about `rmail-mode'. + (Rmail Inbox): Delete false advice wrt rmail-primary-inbox-list. + (Rmail Files): Mention C-u M-x rmail. + (Rmail Reply): Mention References. + (Rmail Display): Mention rmail-nonignored-headers. + + * programs.texi: Minor cleanups. + (Comment Commands): Mention momentary Transient Mark mode. + (Matching): Be more specific about customizing show-paren-mode. + (Info Lookup): Don't list the modes that support C-h S. + Just say what it does in an unsupported mode. + (Man Page): Delete excessive info on customizing woman. + (Motion in C): Don't mention c-for/backward-into-nomenclature. + + * abbrevs.texi: Minor clarifications. + (Dabbrev Customization): Talk about "dynamic abbrev expansion", + not "dynamic abbrevs" as if they were a kind of abbrev. + + * picture.texi (Picture): Minor cleanup. + + * mule.texi (Communication Coding): Say "other applications". + (Fontsets): Not specific to X. Add xref to X Resources. + (Unibyte Mode): Rename from Single-Byte Character Support. + "Graphical display", not window system. + (International): Update menu. + + * maintaining.texi (Format of ChangeLog): + New node, split out from ChangeLog. + (ChangeLog): Clarifications in the remaining text. + (Create Tags Table, Etags Regexps, Select Tags Table): Cleanups. + (Find Tag): Add @w. + (Tags Search): Explain tag table order here. Simplify grep ref. + (List Tags): tags-tag-face is a variable, not a face. + (Emerge): Cleanups. + + * kmacro.texi (Keyboard Macro Counter): Rewrite for clarity. + (Keyboard Macros): Avoid "the user". + + * killing.texi: "Graphical display", not window system. + + * help.texi (Help Echo): "Graphical display", not window system. + + * glossary.texi: Say "you", not "the user". Say "graphical display". + + * frames.texi: Minor cleanups. "Graphical display", not window system. + + * files.texi (Visiting): Make drag-and-drop not X-specific. + + * custom.texi: Minor cleanups. "Graphical display", not window system. + + * cmdargs.texi: Minor cleanups. + + * building.texi (Compilation): Move and split kill-compilation para. + Add para about multiple compilers. + (Compilation Mode): Commands also available in grep mode and others. + Mention C-u C-x ` more tutorially. Clarify C-x `. + (Compilation Shell): Clarify. Put Bash example first. + (Grep Searching): Minor cleanups; add @w. + (Debuggers): Minor cleanups. + (Starting GUD): Make GDB xgraphical mode issue clearer. + (Debugger Operation): Lots of clarifications including + GDB tooltip side-effect issue. + (Commands of GUD): Clarify. + (GUD Customization): Add bashdb-mode-hook. + (GDB Graphical Interface): Rewrite for clarity. + (GDB User Interface Layout): Rewrite for clarity. + (Stack Buffer, Watch Expressions): Likewise. + (Other GDB User Interface Buffers): Cleanups. + (Lisp Libraries, External Lisp): Cleanup. + + * basic.texi (Position Info): "Graphical displays", rather than + window systems. + + * anti.texi: Minor cleanup. + +2006-02-06 Romain Francoise <romain@orebokech.com> + + * faq.texi (VM): VM now at version 7.19. + Set myself as maintainer of this file. + +2006-02-04 Michael Olson <mwolson@gnu.org> + + * erc.texi (History): Note that ERC is now included with Emacs. + +2006-02-03 Eli Zaretskii <eliz@gnu.org> + + * custom.texi (Init File, Find Init): Add cross-references to + where $HOME is described. + +2006-02-01 Luc Teirlinck <teirllm@auburn.edu> + + * frames.texi (Frame Parameters): Remove @item for S-Mouse-1; it + is not inside the @table. + + * emacs.texi (Top): Correct node name. + + * files.texi (File Names): Fix @xref. + (Reverting): Fix typo. + + * mule.texi (International): Correct node name. + + * kmacro.texi (Save Keyboard Macro): Add missing @kbd to @table. + +2006-02-01 Richard M. Stallman <rms@gnu.org> + + * emacs.texi (Top): Update subnode menu. + + * mule.texi: Minor clarifications. + Reduce the specific references to X Windows. + Refer to "graphical" terminals, rather than window systems. + (Text Coding): Rename from Specify Coding. + (Communication Coding, File Name Coding, Terminal Coding): + New nodes split out from Text Coding. + + * kmacro.texi: Minor clarifications. + (Keyboard Macro Ring): Comment out some excessive commands. + (Basic Keyboard Macro): Split up the table, putting part in each node. + + * major.texi: Minor clarifications. + + * misc.texi (Single Shell, Interactive Shell): Fix xrefs. + + * windows.texi: Minor clarifications. + (Change Window): Don't describe mode-line mouse cmds here. + Add xref to Mode Line Mouse. + + * msdog.texi (Text and Binary, MS-DOS and MULE): Fix xrefs. + + * macos.texi (Mac International): Fix xref. + + * indent.texi: Minor clarifications. + + * frames.texi: Minor clarifications. + Reduce the specific references to X Windows. + Refer to "graphical" terminals, rather than window systems. + (Frame Parameters): Don't mention commands like + set-foreground-color. Just say to customize a face. + (Drag and Drop): Lisp-level stuff moved to Emacs Lisp manual. + + * files.texi: Minor clarifications. + (Numbered Backups): New node, split out from Backup Names. + + * display.texi (Font Lock): C mode no longer depends on (-in-col-0. + + * cmdargs.texi (General Variables): Fix xref. + + * buffers.texi: Minor clarifications. + +2006-01-31 Romain Francoise <romain@orebokech.com> + + * message.texi (Message Headers): Explain what + `message-alternative-emails' does in more detail. + Update copyright year. + +2006-01-31 Richard M. Stallman <rms@gnu.org> + + * display.texi (Scrolling, Horizontal Scrolling, Follow Mode): + Nodes moved to top. + + * display.texi: Minor clarifications. + (Display): Rearrange menu. + (Standard Faces): Mention query-replace face. + (Faces): Simplify. + (Font Lock): Simplify face customization info. + (Highlight Changes): Node merged into Highlight Interactively. + (Highlight Interactively): Much rewriting and cleanup. + (Optional Mode Line): Narrowed line number not good for goto-line. + Simplify face customization advice. + (Text Display): Mention use of escape-glyph face. + Move ctl-arrow and tab-width here. + (Display Custom): Move no-redraw-on-reenter to end of node. + + * search.texi: Minor clarifications. + (Isearch Scroll): Simplify. + (Other Repeating Search): Document multi-occur-in-matching-buffers. + + * regs.texi (Registers): Mention bookmarks here. + + * mark.texi: Minor clarifications. + (Selective Undo): Node deleted. + + * m-x.texi: Minor clarifications. + + * killing.texi: Minor clarifications. + Refer to "graphical" terminals, rather than window systems. + + * help.texi: Clarifications. + (Help): Don't describe C-h F and C-h K here. + (Key Help): Describe C-h K here. + (Name Help): Mention Emacs Lisp Intro. + Describe C-h F here. + (Misc Help): Mention C-h F and C-h K only briefly. + + * fixit.texi (Undo): New node, mostly copied from basic.texi. + Selective undo text merged in. + (Spelling): Mention Aspell along with Ispell. + + * emacs.texi (Top): Update subnode menus. + + * basic.texi (Basic Undo): Rename from Undo. Most of text + moved to new Undo node. + +2006-01-30 Juanma Barranquero <lekktu@gmail.com> + + * makefile.w32-in (clean): Add newsticker, sieve, pgg, erc and rcirc. + +2006-01-29 Chong Yidong <cyd@stupidchicken.com> + + * basic.texi (Continuation Lines, Inserting Text): + Mention longlines mode. + +2006-01-29 Richard M. Stallman <rms@gnu.org> + + * screen.texi: Minor cleaups. + (Screen): Clean up the intro paragraphs. + (Mode Line): Lots of rewriting. Handle frame-name better. + eol-mnemonic-... vars moved out. + + * emacs.texi (Top): Change menu item for MS-DOS node. + Update subnode menu. + + * msdog.texi (MS-DOS): Rewrite intro to explain how this + chapter relates to Windows. Title changed. + + * mini.texi: Minor cleanups. + + * mark.texi (Selective Undo): New node, text moved from basic.texi. + (Mark): Put it in the menu. + + * entering.texi: Minor cleanups. + + * emacs.texi (Top): Add xref to Mac chapter; explain Windows better. + (Intro): Refer to "graphical" terminals, rather than X. + + * display.texi (Display Custom): Add xref to Variables. + (Optional Mode Line): eol-mnemonic-... vars moved here. + + * commands.texi: Minor cleanups. Refer to "graphical" terminals, + rather than X. + + * cc-mode.texi (Indentation Commands): Inserts newline, not "linefeed". + + * basic.texi: Minor cleanups. + (Undo): selective-undo moved. + +2006-01-29 Michael Olson <mwolson@gnu.org> + + * makefile.w32-in ($(infodir)/erc, erc.dvi): New targets. + + * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add ERC. + + * faq.texi (New in Emacs 22): Mention ERC. + +2006-01-28 Luc Teirlinck <teirllm@auburn.edu> + + * rcirc.texi: Capitalize dir entry for consistency with the entry + in info/dir and other entries in the Emacs category. + Fix typos. Delete trailing whitespace. + +2006-01-28 Bj,Av(Brn Lindstr,Av(Bm <bkhl@elektrubadur.se> + + * rcirc.texi: Some @cindex changes, some changes from @kbd to @key. + +2006-01-27 Eli Zaretskii <eliz@gnu.org> + + * makefile.w32-in ($(infodir)/rcirc, rcirc.dvi): New targets. + (INFO_TARGETS, DVI_TARGETS): Add rcirc. + + * Makefile.in (../info/rcirc, rcirc.dvi): New targets. + (INFO_TARGETS, DVI_TARGETS): Add rcirc. + +2006-01-27 Alex Schroeder <alex@gnu.org> + + * rcirc.texi: New file. + +2006-01-25 Luc Teirlinck <teirllm@auburn.edu> + + * anti.texi (Antinews): Various corrections and additions. + +2006-01-23 Juri Linkov <juri@jurta.org> + + * custom.texi (Easy Customization, Customization Groups) + (Browsing Custom): Mention links along with buttons. + + * widget.texi (User Interface): Add S-TAB for widget-backward. + +2006-01-22 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.0.52. + + * tramp.texi (Frequently Asked Questions): Remove Ange-FTP item. + Add Tramp disabling item. New item for common connection problems. + (various): Apply "ftp" as method for the download URL. + (Bug Reports): Refer to FAQ for common problems. + +2006-01-21 Eli Zaretskii <eliz@gnu.org> + + * widget.texi (User Interface): Use @key for TAB. + + * text.texi (TeX Print): Use @key for TAB. + + * ses.texi (Formulas, Printer functions): Use @key for TAB. + + * kmacro.texi (Keyboard Macro Step-Edit): Use @key for TAB. + + * ebrowse.texi (Switching to Tree, Symbol Completion): Use @key + for TAB. + + * cc-mode.texi (Indentation Calculation): Use @key for TAB. + +2006-01-15 Sven Joachim <svenjoac@gmx.de> (tiny change) + + * files.texi (File Aliases): Don't claim that usually separate + buffers are created for two file names that name the same data. + Mention additional situations where different names mean the same + file on disk. + +2006-01-19 Richard M. Stallman <rms@gnu.org> + + * killing.texi (Deletion): Upcase @key argument. + + * custom.texi (Custom Themes): Minor cleanup. + + * programs.texi (Hungry Delete): Upcase @key argument. + +2006-01-16 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi: Update copyright. + +2006-01-16 Juri Linkov <juri@jurta.org> + + * display.texi (Standard Faces): Add `mode-line-buffer-id'. + Move `mode-line-highlight' before `mode-line-buffer-id'. + +2006-01-13 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Article Washing): Additions. + +2006-01-08 Alex Schroeder <alex@gnu.org> + + * pgg.texi (Caching passphrase): Rewording. + +2006-01-14 Richard M. Stallman <rms@gnu.org> + + * basic.texi (Inserting Text): Minor cleanup. + +2006-01-13 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Agenda commands): Document tags command. + +2006-01-11 Luc Teirlinck <teirllm@auburn.edu> + + * custom.texi (Changing a Variable, Face Customization): + Update for changes in Custom menus. + +2006-01-10 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (RSS): Document nnrss-wash-html-in-text-plain-parts. + +2006-01-06 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (RSS): Addition. + +2005-12-22 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Summary Post Commands): Fix function bound to `S O p'. + +2005-12-19 Katsumi Yamaoka <yamaoka@jpl.org> + + * emacs-mime.texi (Display Customization): Add setting example to + mm-discouraged-alternatives. + +2006-01-09 Stefan Monnier <monnier@iro.umontreal.ca> + + * flymake.texi (Obtaining Flymake): Remove chapter since Emacs's + version is the canonical version. + +2006-01-08 Alex Schroeder <alex@gnu.org> + + * pgg.texi (Caching passphrase): Rewording. + +2006-01-06 Eli Zaretskii <eliz@gnu.org> + + * flymake.texi (Obtaining Flymake): Update Flymake's CVS + repository URL. + +2006-01-06 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Removed the accidentally re-added empty line in the + direntry. + +2006-01-05 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp> + + * macos.texi (Mac International): Undo last change. + +2006-01-05 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Agenda Views): Chapter reorganized. + +2006-01-02 Chong Yidong <cyd@stupidchicken.com> + + * custom.texi (Custom Themes): Describe the new + customize-create-theme interface. + +2005-12-30 Juri Linkov <juri@jurta.org> + + * basic.texi (Position Info): Update example. + +2005-12-29 Romain Francoise <romain@orebokech.com> + + * faq.texi (Using Customize): New node. + +2005-12-28 Luc Teirlinck <teirllm@auburn.edu> + + * org.texi: Remove blank line in @direntry. It is non-standard + and recursively produces blank lines all over the dir file (when + using Texinfo 4.8). + +2005-12-27 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * frames.texi (Dialog Boxes): Add x-gtk-show-hidden-files. + +2005-12-24 Chong Yidong <cyd@stupidchicken.com> + + * custom.texi (Custom Themes): `load-theme' always loads. + +2005-12-23 Juri Linkov <juri@jurta.org> + + * display.texi (Highlight Interactively): Use double space to + separate sentences. Replace C-p with M-p, and C-n with M-n. + +2005-12-22 Richard M. Stallman <rms@gnu.org> + + * custom.texi (Easy Customization and subnodes): + Replace "active field" with "button". + Use "user option" only for variables. + Use "setting" for variable-or-face. + +2005-12-22 Luc Teirlinck <teirllm@auburn.edu> + + * buffers.texi (Select Buffer): Change order in table to make + "Similar" refer to the correct item. + (Indirect Buffers): Minor rewording. + +2005-12-21 Luc Teirlinck <teirllm@auburn.edu> + + * widget.texi (atoms): Delete obsolete remark about `file' widget. + +2005-12-20 Juri Linkov <juri@jurta.org> + + * files.texi (VC Status): Put P and N near p and n. + +2005-12-20 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Tags): Boolean logic documented. + (Agenda Views): Document custom commands. + +2005-12-20 David Kastrup <dak@gnu.org> + + * faq.texi (AUCTeX): Update version and mailing list info. + +2005-12-19 Richard M. Stallman <rms@gnu.org> + + * programs.texi (Electric C): Delete the info about newline control. + (Other C Commands): Minor cleanup. + (Left Margin Paren): Minor cleanup. + +2005-12-19 Luc Teirlinck <teirllm@auburn.edu> + + * custom.texi (Easy Customization): Add "Browsing Custom" to menu. + (Customization Groups): Delete text moved to "Browsing Custom". + (Browsing Custom): New node. + (Specific Customization): Clarify which commands only work for + loaded options. + +2005-12-18 Bill Wohler <wohler@newt.com> + + * frames.texi (Tool Bars): Shorten text of previous change. + +2005-12-18 Aaron S. Hawley <Aaron.Hawley@uvm.edu> + + * files.texi (VC Status): Document log-view mode. + +2005-12-18 Bill Wohler <wohler@newt.com> + + * frames.texi (Tool Bars): Mention that you can turn off tool bars + permanently via the customize interface. + +2005-12-17 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (MIME Commands): Mention addition of + multipart/alternative to gnus-buttonized-mime-types and add xref + to mm-discouraged-alternatives. + + * emacs-mime.texi (Display Customization): Mention addition of + "image/.*" and add xref to gnus-buttonized-mime-types in the + mm-discouraged-alternatives section. + +2005-12-16 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Tags): New section. + (Agenda Views): Chapter reorganized. + +2005-12-16 Ralf Angeli <angeli@iwi.uni-sb.de> + + * killing.texi (Killing by Lines): Document `kill-whole-line' + function. + +2005-12-16 Eli Zaretskii <eliz@gnu.org> + + * org.texi (Internal Links): Add a missing comma after an @xref. + +2005-12-16 L$,1 q(Brentey K,Aa(Broly <lorentey@elte.hu> + + * buffers.texi (Select Buffer): Change `prev-buffer' to + `previous-buffer'. Indicate that these functions use a frame + local buffer list. + +2005-12-14 Chong Yidong <cyd@stupidchicken.com> + + * faq.texi (Filling paragraphs with a single space): No need to + change sentence-end now. + +2005-12-13 Romain Francoise <romain@orebokech.com> + + * faq.texi (Scrolling only one line): Use `scroll-conservatively'. + +2005-12-12 Jay Belanger <belanger@truman.edu> + + * faq.texi (Calc): Update version number. + +2005-12-12 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Progress Logging): New section. + +2005-12-12 Richard M. Stallman <rms@gnu.org> + + * custom.texi (Easy Customization): Change menu comment. + (Prefix Keymaps): Fix spelling of Control-X-prefix. + + * help.texi (Apropos): Rewrite. Talk about "apropos patterns". + (Help): Among the Apropos commands, describe only C-h a here. + +2005-12-11 Richard M. Stallman <rms@gnu.org> + + * programs.texi (Options for Comments): Comment-end starts with space. + + * glossary.texi (Glossary): Minor cleanup. + + * files.texi (Old Versions): Use @table. + +2005-12-10 Romain Francoise <romain@orebokech.com> + + Update the Emacs FAQ for the 22.1 release. + + * faq.texi: Set VER to `22.1'. + (Basic editing): Explain how to use localized versions of the + Tutorial. Mention that `C-h r' displays the manual. Delete + obsolete WWW link to an Emacs 18 tutorial. + (Getting a printed manual): Point to the new locations of the + manuals on the GNU Web site. + (Emacs Lisp documentation): Explain that the Emacs Lisp manual is + available via Info (it was previously distributed separately). + (Installing Texinfo documentation): The latest version of Texinfo + is 4.8, not 4.0. + (Informational files for Emacs): COPYING is the GNU General Public + License, not the Emacs General Public License. + (Informational files for Emacs): Delete obsolete link to the + GNUinfo pages as they have been removed from the GNU Web site. + (New in Emacs 22): New node. + (Setting up a customization file): Say that most packages support + Customize nowadays. + (Colors on a TTY): Delete reference to instructions on how to + enable syntax highlighting, it is now enabled by default. + (Turning on abbrevs by default): Emacs now reads the abbrevs file + at startup automatically. + (Controlling case sensitivity): Mention `M-c' in isearch. + (Using an already running Emacs process): Emacs now creates the + socket in `/tmp/emacsUID'. Fix typos. Change default location of + gnuserv. As emacsclient can now run Lisp code as well, delete a + sentence praising gnuserv for that. Simplify description of how + the client/server operation works. + (Compiler error messages): Delete obsolete text (compile.el has + been rewritten). + (Indenting switch statements): Fix typo. + (Matching parentheses): Simplify setup instructions, mention the + menu bar item in the Options menu. + (Repeating a command as many times as possible): Mention `C-x e'. + (Going to a line by number): Mention new keymap and bindings + `M-g M-g', `M-g M-p' and `M-g M-n'. + (Turning on syntax highlighting): Now on by default. Simplify. + (Replacing highlighted text): Use `1', not `t'. + (Problems with very large files): The maximum size is now 256MB on + 32-bit machines. + (^M in the shell buffer): Mention `comint-process-echoes'. + (Emacs for Apple computers): Emacs 22 has native support for Mac + OS X. + (Translating names to IP addresses): Delete node. + (Binding keys to commands): Fix typo. + (SPC no longer completes file names): New node. + (MIME with Emacs mail packages): Delete section about the Emacs + MIME FAQ (it's not reachable anymore). + +2005-12-10 David Koppelman <koppel@ece.lsu.edu> + + * display.texi (Highlight Interactively): Include + global-hi-lock-mode. Add miscellaneous details and elaborations. + +2005-12-09 Richard M. Stallman <rms@gnu.org> + + * display.texi (Font Lock): Delete the Global FL menu item. + +2005-12-09 Luc Teirlinck <teirllm@auburn.edu> + + * custom.texi (Minibuffer Maps): Mention the maps for file name + completion. + +2005-12-09 Kim F. Storm <storm@cua.dk> + + * killing.texi (CUA Bindings): Describe how to use C-x and C-c as + prefix keys even when mark is active. Decribe that RET moves + cursor to next corner in rectangle; clarify insert around rectangle. + +2005-12-08 Alan Mackenzie <bug-cc-mode@gnu.org> + + * cc-mode.texi: The manual has been extensively revised: the + information about using CC Mode has been separated from the larger + and more difficult chapters about configuration. It has been + updated for CC Mode 5.31. + +2005-12-05 Katsumi Yamaoka <yamaoka@jpl.org> + + * pgg.texi (User Commands): Fix description of pgg-verify-region. + (Selecting an implementation): Fix descriptions. + +2005-11-30 Katsumi Yamaoka <yamaoka@jpl.org> + + * message.texi (Various Message Variables): Addition. + +2005-11-29 Katsumi Yamaoka <yamaoka@jpl.org> + + * message.texi: Fix default values. + +2005-11-25 Katsumi Yamaoka <yamaoka@jpl.org> + + * message.texi (Header Commands): Clarify descriptions of + message-cross-post-followup-to, message-reduce-to-to-cc, and + message-insert-wide-reply. + (Various Commands): Fix kindex for message-kill-to-signature; + clarify description of message-tab. + +2005-11-22 Katsumi Yamaoka <yamaoka@jpl.org> + + * message.texi (Mailing Lists): Fix description about MFT. + + * gnus.texi (Emacs Lisp): Use ~/.gnus.el instead of ~/.emacs. + +2005-11-17 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Slow Terminal Connection): Replace old description + with new one. + +2005-11-16 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Oort Gnus): Use ~/.gnus.el instead of ~/.emacs; + replace X-Draft-Headers with X-Draft-From. + +2005-11-14 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Various Various): Fix the default value of + nnheader-max-head-length. + (Gnus Versions): Fix typo. + +2005-12-08 Luc Teirlinck <teirllm@auburn.edu> + + * custom.texi (Customization): Use xref to elisp manual for + non-TeX output. + (Minor Modes): Update. + (Customization Groups, Changing a Variable, Face Customization): + Update for new appearance of Custom buffers. + (Changing a Variable): `custom-buffer-done-function' has been + replaced by `custom-buffer-done-kill'. + (Specific Customization): In the `customize-group' buffer, a + subgroup's contents are not "hidden". They are not included at + all. They have no [Show] button. + (Mouse Buttons): Add pxref to description of mouse event lists in + Elisp manual. Add `menu-bar' and `header-line' dummy prefix keys. + (Find Init): Emacs now looks for ~/.emacs.d/init.el instead of + ~/.emacs.d/.emacs, if it can not find ~/.emacs(.el). + +2005-12-08 Richard M. Stallman <rms@gnu.org> + + * mini.texi (Completion Commands, Completion): + In file name input, SPC does not do completion. + +2005-12-08 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Structure editing): Document new functionality of + M-RET. + +2005-12-08 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (GDB Graphical Interface): Explain screen size + setting. + (Other GDB User Interface Buffers): Describe features specific to + GDB 6.4. + +2005-12-06 Luc Teirlinck <teirllm@auburn.edu> + + * org.texi (Internal Links): Fix Texinfo usage. + +2005-12-06 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (TODO basics): Document the global todo list. + (TODO items): Documents sparse tree for specific TODO + keywords. + +2005-12-01 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (GDB User Interface Layout): Describe how to + kill associated buffers. + (Breakpoints Buffer): Use D instead of d for gdb-delete-breakpoint. + (Watch Expressions): Be more precise. + (Other GDB User Interface Buffers): Describe how to change a + register value. + +2005-11-30 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Plain Lists): Typos fixed. + +2005-11-28 Jay Belanger <belanger@truman.edu> + + * calc.texi: Change references of `M-#' to `C-x *' prefix. + +2005-11-24 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Structure editing): New item moving commands added. + (Plain Lists): New section. + +2005-11-24 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp> + + * macos.texi (Mac Input): Remove description of + mac-command-key-is-meta. Add descriptions of + mac-control-modifier, mac-command-modifier, and + mac-option-modifier. + (Mac International): Fix description of conversion of clipboard data. + (Mac Font Specs): Add example of font customization by face attributes. + +2005-11-22 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Watch Expressions): Expand description. + (Other GDB User Interface Buffers): Describe local map for + gud-watch. + +2005-11-21 Chong Yidong <cyd@stupidchicken.com> + + * display.texi (Font Lock): Font lock is enabled by default now. + +2005-11-20 Juri Linkov <juri@jurta.org> + + * basic.texi (Position Info): Update examples of the output. + Remove the fact that examples are produced in the TeXinfo buffer, + because in the Info reader users will get a different output from + `C-x ='. + + * building.texi (Compilation Mode): Remove paragraph duplicated + from the node `Compilation'. Add `compilation-skip-threshold'. + + * display.texi (Font Lock): Suggest more user-friendly method of + finding all Font Lock faces (M-x customize-group RET font-lock-faces). + +2005-11-18 Richard M. Stallman <rms@gnu.org> + + * files.texi (Registering): Mention @@ in mode line. + + * mini.texi (Minibuffer File): Clarify previous change. Add @findex. + +2005-11-08 Aaron S. Hawley <Aaron.Hawley@uvm.edu> + + * files.texi (Renaming and VC): Some back-ends don't + handle renaming. + +2005-11-18 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (FAQ): Document `org-table-tab-jumps-over-hlines'. + (Agenda): Document commands `org-cycle-agenda-files' and + `org-agenda-file-to-front' + (Built-in table editor): Document `org-table-sort-lines'. + (HTML formatting): Export of hand-formatted lists. + +2005-11-17 Juri Linkov <juri@jurta.org> + + * emacs.texi (Top): + * display.texi (Highlight Interactively): Put this font-lock based + mode near Font Lock node. + +2005-11-16 Chong Yidong <cyd@stupidchicken.com> + + * ack.texi (Acknowledgments): Acknowledge Andrew Zhilin for Emacs + icons. + +2005-11-12 Kim F. Storm <storm@cua.dk> + + * help.texi (Help): Fix C-h a entry. Add C-h d entry. + (Help Summary): Add C-h d and C-h e. + (Apropos): Clarify that all apropos commands may search for either + list of words or a regexp. Add C-h d for apropos-documentation. + Describe apropos-documentation-sort-by-scores user option. + +2005-11-10 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (XVarious): Fix description of gnus-use-toolbar; add + new variable gnus-toolbar-thickness. + +2005-11-08 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (XVarious): Revert description of gnus-use-toolbar. + +2005-11-07 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (X-Face): Fix description. + (XVarious): Remove gnus-xmas-logo-color-alist and + gnus-xmas-logo-color-style; fix description of gnus-use-toolbar. + +2005-11-01 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Group Parameters): Mention new variable + gnus-parameters-case-fold-search. + (Home Score File): Addition. + +2005-11-09 Luc Teirlinck <teirllm@auburn.edu> + + * killing.texi (CUA Bindings): Add @section. + +2005-11-10 Kim F. Storm <storm@cua.dk> + + * emacs.texi (Top): Add CUA Bindings entry to menu. + + * killing.texi (CUA Bindings): New node. Moved here from + misc.texi and extended with info on rectangle commands and + rectangle highlighting, interface to registers, and the global + mark feature. + + * misc.texi (Emulation): Move CUA bindings item to killing.texi. + + * regs.texi: Prev link points to CUA Bindings node. + +2005-11-07 Luc Teirlinck <teirllm@auburn.edu> + + * help.texi (Help Echo): By default, help echos are only shown on + mouse-over, not on point-over. + +2005-11-04 J,Ai(Br,At(Bme Marant <jerome@marant.org> + + * misc.texi (Shell Mode): Describe how to activate password echoing. + +2005-11-04 Ulf Jasper <ulf.jasper@web.de> + + * newsticker.texi: VERSION changed to 1.9. Updated UPDATED. + (Overview): List supported feed types. + (Installation): No installation necessary when using autoload. + (Configuration): Rename "RSS" to "news". + +2005-11-04 Ken Manheimer <ken.manheimer@gmail.com> + + * pgg.texi (User Commands): Document additional passphrase + argument for pgg-encrypt-*, pgg-decrypt-*, and pgg-sign-* functions. + (Backend methods): Likewise for corresponding pgg-scheme-* functions. + +2005-11-04 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Version number changed to 3.19. + +2005-11-04 Romain Francoise <romain@orebokech.com> + + * mark.texi (Mark Ring): Fix typo. + +2005-11-03 Richard M. Stallman <rms@gnu.org> + + * mark.texi (Mark Ring): Mention set-mark-command-repeat-pop. + +2005-11-01 Bill Wohler <wohler@newt.com> + + * help.texi (Help Mode): Fix typo. + +2005-11-01 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Other GDB User Interface Buffers): Describe + the command gdb-use-inferior-io-buffer. + +2005-10-31 Romain Francoise <romain@orebokech.com> + + * files.texi (Compressed Files): Fix typo. + + * buffers.texi (Misc Buffer): Downcase `*shell*'. + + * windows.texi (Force Same Window): Likewise. + +2005-10-30 Bill Wohler <wohler@newt.com> + + * help.texi (Help Mode): URLs viewed with browse-url. + +2005-10-31 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (GDB Graphical Interface): Don't reference + gdb-mouse-set-clear-breakpoint. Explain gdb-mouse-until + must stay in same frame. + +2005-10-29 Chong Yidong <cyd@stupidchicken.com> + + * custom.texi (Init File): Document ~/.emacs.d/init.el. + + * anti.texi (Antinews): Likewise. + +2005-10-29 Sascha Wilde <wilde@sha-bang.de> + + * pgg.texi (How to use): Update the example to add autoload of + pgg-encrypt-symmetric-region. + (User Commands): Document pgg-encrypt-symmetric-region. + (Backend methods): Document pgg-scheme-encrypt-symmetric-region. + +2005-10-28 Bill Wohler <wohler@newt.com> + + * help.texi (Help): Help mode now creates hyperlinks for URLs. + +2005-10-28 Richard M. Stallman <rms@gnu.org> + + * files.texi (Visiting): Explain how to enter ? in a file name. + + * trouble.texi (Memory Full): Mention !MEM FULL! in mode line. + +2005-10-27 Jay Belanger <belanger@truman.edu> + + * calc.texi (Predefined Units): Fix the symbol for a TeX points, + mention other TeX-related units. + +2005-10-25 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (GDB Graphical Interface): Describe + gdb-mouse-until. + +2005-10-23 Richard M. Stallman <rms@gnu.org> + + * custom.texi (Init File): Recommend when to use site-start.el. + +2005-10-23 Lars Hansen <larsh@soem.dk> + + * dired-x.texi (Miscellaneous Commands): Replace + dired-do-relative-symlink by dired-do-relsymlink and + dired-do-relative-symlink-regexp by dired-do-relsymlink-regexp. + +2005-10-23 Jay Belanger <belanger@truman.edu> + + * calc.texi (Predefined Units): Use `alpha' for the fine structure + constant. + +2005-10-23 Michael Albinus <michael.albinus@gmx.de> + + * faq.texi (Bugs and problems): Replace + `dired-move-to-filename-regexp' by + `directory-listing-before-filename-regexp'. + +2005-10-22 Eli Zaretskii <eliz@gnu.org> + + * newsticker.texi (UPDATED): Set value. + +2005-10-17 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Document Groups): Remove duplicate item. + +2005-10-21 Juri Linkov <juri@jurta.org> + + * custom.texi (Examining): Mention accessing the old variable + value via M-n in set-variable. + +2005-10-21 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Summary): Mention iCalendar support. + (Exporting): Document iCalendar support. + +2005-10-18 Romain Francoise <romain@orebokech.com> + + * files.texi (Version Systems): Capitalize GNU. + + * viper.texi (Viper Specials): Likewise. + +2005-10-18 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Compilation Mode): Remove redundant paragraph. + (Watch Expressions): Remove paragraph to reflect code change. + +2005-10-17 Juri Linkov <juri@jurta.org> + + * info.texi (Getting Started, Search Index, Expert Info): + Fix wording. + (Search Text): Replace `echo area' with `mode line'. + (Search Index): Both `i' and `,' find all index entries. + Replace example `C-f' with `C-l' (which exists in index of Info + manual) and delete spaces in its keyboard input sequence. + Delete unnecessary explanations about literal characters. + +2005-10-16 Richard M. Stallman <rms@gnu.org> + + * building.texi (Compilation Mode, Compilation): Clarified. + +2005-10-15 Richard M. Stallman <rms@gnu.org> + + * misc.texi (Saving Emacs Sessions): Mention savehist library. + +2005-10-14 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Document Server Internals): Addition. + +2005-10-13 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (A note on namespaces): Fix RFC reference. + +2005-10-12 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (RSS): Fix key description. + +2005-10-11 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi: Emacs/w3 -> Emacs/W3. + (Browsing the Web): Fix description. + (Web Searches): Ditto. + (Customizing W3): Ditto. + +2005-10-07 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Maildir): Clarify expire-age and expire-group. + +2005-10-13 Kenichi Handa <handa@m17n.org> + + * basic.texi (Position Info): Fix previous change. + +2005-10-12 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * cmdargs.texi (Icons X): Fix typo. + +2005-10-12 Kenichi Handa <handa@m17n.org> + + * basic.texi (Position Info): Describe the case that Emacs shows + "part of display ...". + +2005-10-11 Jay Belanger <belanger@truman.edu> + + * calc.texi (Integration): Mention using `a i' to compute definite + integrals. + +2005-10-11 Juri Linkov <juri@jurta.org> + + * info.texi: Rearrange nodes. + (Top): Update menu. Change ref `Info for Experts' to + `Advanced Info Commands'. + (Getting Started): Fix description of manual's parts. + (Help-Int): Change xref `Info Search' to `Search Index', and + `Expert Info' to `Advanced'. + (Advanced): Move node one level up. + (Search Text, Search Index): New nodes split out from `Info Search'. + (Go to node, Choose menu subtopic, Create Info buffer): New nodes + split out from `Advanced'. + (Advanced, Emacs Info Variables): De-document editing an Info file + in Info. + (Emacs Info Variables): Move node from `Expert Info' to `Advanced'. + (Creating an Info File): Delete node and move its text to + `Expert Info'. + +2005-10-10 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * cmdargs.texi (Icons X): -nb => -nbi. + +2005-10-10 Chong Yidong <cyd@stupidchicken.com> + + * frames.texi (Speedbar): A couple more clarifications. + +2005-10-11 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (GDB User Interface Layout): Improve diagram. + (Watch Expressions): Explain how to make speedbar global. + (Other GDB User Interface Buffers): Make references more precise. + +2005-10-10 Carsten Dominik <dominik@science.uva.nl> + + * org.texi (Workflow states): Documented that change in keywords + becomes active only after restart of Emacs. + +2005-10-09 Richard M. Stallman <rms@gnu.org> + + * frames.texi (Speedbar): Clarify the text. + +2005-10-09 Chong Yidong <cyd@stupidchicken.com> + + * frames.texi (Speedbar): Add information on keybindings, + dismissing the speedbar, and buffer display mode. Link to + speedbar manual. + +2005-10-09 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * cmdargs.texi (Icons X): Removed options -i, -itype, --icon-type, + added -nb, --no-bitmap-icon. + +2005-10-08 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.0.51. + +2005-10-08 Nick Roberts <nickrob@snap.net.nz> + + * speedbar.texi (Introduction): Describe new location of speedbar + on menubar. + (Basic Key Bindings): Remove descriptions of bindings that have + been removed. + +2005-10-07 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (GDB Graphical Interface): Add variables and + functions to indices. Be more precise. + +2005-10-05 Nick Roberts <nickrob@snap.net.nz> + + * speedbar.texi (GDB): Describe use of watch expressions. + +2005-10-03 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * frames.texi (Drag and Drop): Remove the x- from + x-dnd-open-file-other-window and xdnd-protocol-alist. + +2005-09-30 Romain Francoise <romain@orebokech.com> + + * mini.texi (Minibuffer): The default value now appears before the + colon in minibuffer prompts. + +2005-09-28 Simon Josefsson <jas@extundo.com> + + * message.texi (IDNA): Fix. + +2005-09-28 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (NNTP): Remove nntp-buggy-select, nntp-read-timeout, + nntp-server-hook, and nntp-warn-about-losing-connection; fix + description of nntp-open-connection-function. + (Common Variables): Fix descriptions. + +2005-09-26 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Server Buffer Format): Document the %a format spec. + +2005-09-25 Richard M. Stallman <rms@gnu.org> + + * search.texi (Regexp Search): Doc search-whitespace-regexp. + +2005-09-22 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Mail): Fix gnus-confirm-mail-reply-to-news entry. + +2005-09-20 Emanuele Giaquinta <emanuele.giaquinta@gmail.com> (tiny change) + + * text.texi (Paragraphs): Correction about Paragraph-Indent Text mode. + +2005-09-23 Carsten Dominik <dominik@science.uva.nl> + + * org.texi Version 3.16. + +2005-09-21 YAMAMOTO Mitsuharu <mituharu@math.s.chiba-u.ac.jp> + + * emacs.texi (Top): Update submenus from macos.texi. + + * macos.texi: Change `Mac OS 8 or 9' to `Mac OS Classic'. + (Mac OS): Update feature support status. + (Mac Input): List supported input scripts. Remove description + about `mac-keyboard-text-encoding'. Mention mouse button + emulation and related variables. + (Mac International): Mention Central European and Cyrillic + support. Now `keyboard-coding-system' is dynamically changed. + Add description about coding system for selection. Add + description about language environment. + (Mac Environment Variables): Mention + `~/.MacOSX/environment.plist'. Give example of command line + arguments. Add Preferences support. + (Mac Directories): Explicitly state that this node is for Mac OS + Classic only. + (Mac Font Specs): Mention specification for scalable fonts. List + supported charsets. Add preferred way of creating fontsets. Add + description about `mac-allow-anti-aliasing'. + (Mac Functions): Add descriptions about `mac-set-file-creator', + `mac-get-file-creator', `mac-set-file-type', `mac-get-file-type', + and `mac-get-preference'. + +2005-09-19 Miles Bader <miles@gnu.org> + + * newsticker.texi: Get rid of CVS keywords. + +2005-09-15 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Finding the Parent): Fix description of how Gnus + finds article. + +2005-09-14 Jari Aalto <jari.aalto@cante.net> + + * gnus.texi (Advanced Scoring Examples): New examples to teach how + to drop off non-answered articles. + +2005-09-19 Juanma Barranquero <lekktu@gmail.com> + + * makefile.w32-in (newsticker.dvi): Use parentheses instead of curly + braces (which are unsupported by NMAKE) for macro `srcdir'. + +2005-09-17 Eli Zaretskii <eliz@gnu.org> + + * makefile.w32-in (INFO_TARGETS, DVI_TARGETS): Add newsticker targets. + (../info/newsticker, newsticker.dvi): New targets. + +2005-09-17 Ulf Jasper <ulf.jasper@web.de> + + * newsticker.texi: Replace @command with @code. Replace @example + with @lisp. + (Top): Added explanations to menu items. + (GNU Free Documentation License): Removed. + +2005-09-16 Romain Francoise <romain@orebokech.com> + + Update all files to specify GFDL version 1.2. + + * doclicense.texi (GNU Free Documentation License): Update to + version 1.2. + +2005-09-15 Richard M. Stallman <rms@gnu.org> + + * buffers.texi (List Buffers): Fix xref. + + * rmail.texi (Rmail Basics): Fix xref. + + * emacs.texi (Top): Update subnode menus. + + * files.texi (Saving Commands): New node, broken out of Saving. + (Customize Save): New node, broken out of Saving. + Clarify effect of write-region-inhibit-fsync. + (Misc File Ops): Say write-region-inhibit-fsync affects write-region. + + * newsticker.texi: Fix @setfilename. + + * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add newsticker targets. + (../info/newsticker, newsticker.dvi): New targets. + +2005-09-14 Romain Francoise <romain@orebokech.com> + + * files.texi (Saving): Mention write-region-inhibit-fsync. + +2005-09-05 Chong Yidong <cyd@stupidchicken.com> + + * custom.texi (Custom Themes): New node. + +2005-09-03 Richard M. Stallman <rms@gnu.org> + + * search.texi (Search Case): Mention vars that control + case-fold-search for various operations. + +2005-08-30 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Version 3.15. + +2005-08-29 Luc Teirlinck <teirllm@auburn.edu> + + * ses.texi: Combine all three indices into one. + Correct a few typos. + +2005-08-19 Katsumi Yamaoka <yamaoka@jpl.org> + + * emacs-mime.texi (time-date): Fix description of safe-date-to-time. + +2005-08-18 Katsumi Yamaoka <yamaoka@jpl.org> + + * emacs-mime.texi (Handles): Remove duplicate item. + (Encoding Customization): Fix the default value for + mm-coding-system-priorities. + (Charset Translation): Emacs doesn't use mm-mime-mule-charset-alist. + (Basic Functions): Fix reference. + +2005-08-09 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (Charsets): Fj hierarchy uses iso-2022-jp. + +2005-08-22 Juri Linkov <juri@jurta.org> + + * display.texi (Standard Faces): Merge the text from + `(elisp)Standard Faces' into this node. + +2005-08-18 Luc Teirlinck <teirllm@auburn.edu> + + * emacs.texi (Top): Delete menu item for deleted node + Keyboard Translations. + +2005-08-18 Richard M. Stallman <rms@gnu.org> + + * faq.texi (Obtaining the FAQ): Delete refs to Lerner's email + and web site. + + * trouble.texi (Unasked-for Search): + Delete xref to Keyboard Translations. + + * glossary.texi (Glossary): Delete xref. + + * faq.texi (Swapping keys): Xref for normal-erase-is-backspace-mode, + not keyboard-translate. + + * custom.texi (Minor Modes): Say that the list here is not complete. + (Keyboard Translations): Node deleted. + (Disabling): Delete xref to it. + (Customization Groups): Fix Custom buffer example. + (Hooks): Mention remove-hooks. + +2005-08-17 Luc Teirlinck <teirllm@auburn.edu> + + * building.texi (GDB Graphical Interface): Improve filling of menu + item. + +2005-08-18 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (GDB Graphical Interface): Use better node names. + +2005-08-14 Richard M. Stallman <rms@gnu.org> + + * text.texi (Sentences): Fix xref. + +2005-08-14 Juri Linkov <juri@jurta.org> + + * building.texi (Compilation, Grep Searching): Move grep command + headings from `Compilation' to `Grep Searching'. + + * dired.texi (Dired and Find): + * maintaining.texi (Tags Search): Replace grep xref to + `Compilation' node with `Grep Searching'. + + * files.texi (Comparing Files): Replace xref to `Compilation' with + `Compilation Mode'. + +2005-08-13 Alan Mackenzie <acm@muc.de> + + * search.texi (Non-ASCII Isearch): Correct a typo. + (Replacement Commands): Mention query-replace key binding. + +2005-08-11 Richard M. Stallman <rms@gnu.org> + + * programs.texi (Options for Comments): Fix xref. + + * search.texi (Regexp Backslash, Regexp Example): New nodes split + out of Regexps. + + * faq.texi (Using regular expressions): Fix xref. + +2005-08-09 Juri Linkov <juri@jurta.org> + + * building.texi (Compilation): Use `itemx' instead of `item'. + (Grep Searching): Simplify phrase. + + * display.texi (Standard Faces): Describe vertical-border on + window systems. + + * windows.texi (Split Window): Simplify phrase and mention + vertical-border face. + +2005-08-09 Richard M. Stallman <rms@gnu.org> + + * files.texi (Comparing Files): Clarify compare-windows. + + * calendar.texi (Scroll Calendar): Document < and > in calendar. + +2005-08-09 Juri Linkov <juri@jurta.org> + + * info.texi (Help-P): Replace `Prev' with `Previous'. + (Help-M, Help-Xref): Add S-TAB. + (Help-FOO): Update `u' command. + (Help-Xref): Move info about Mouse-2 from `Help-Int'. + Update info about visibility of xref parts. + (Help-Int): Fix `m' command. Rename `Info-last' to + `Info-history-back'. Add `Info-history-forward'. + (Advanced): Fix `g*' and `M-n' commands. + (Info Search): Add `index-apropos' in stand-alone browser. + Add isearch commands. + (Emacs Info Variables): Remove `Info-fontify'. + Add `Info-mode-hook'. Update face names. + Add `Info-fontify-maximum-menu-size', + `Info-fontify-visited-nodes', `Info-isearch-search'. + +2005-08-07 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.0.50. + + * tramp.texi: Use @option{} consequently for method names. + (Inline methods, External transfer methods): Remove references to + Cygwin. + (Issues with Cygwin ssh): Explain trouble with Cygwin's ssh + implementation. + +2005-08-06 Eli Zaretskii <eliz@gnu.org> + + * mule.texi (Coding Systems): Rephrase the paragraph about + codepages: no need for "M-x codepage-setup" anymore, except on + MS-DOS. + + * msdog.texi (MS-DOS and MULE): Clarify that this section is for + the MS-DOS port only. + +2005-07-30 Eli Zaretskii <eliz@gnu.org> + + * makefile.w32-in (info): Don't run multi-install-info.bat. + ($(infodir)/dir): New target, produced by running + multi-install-info.bat. + +2005-07-27 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Startup Files): Fix name of gnus-site-init-file. + Mention that gnus-init-file is not read when Emacs is invoked with + --no-init-file or -q. + +2005-07-22 Eli Zaretskii <eliz@gnu.org> + + * files.texi (Quoted File Names): Add index entry. + +2005-07-19 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Version 3.14. + +2005-07-04 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Version 3.13. + +2005-07-19 Juri Linkov <juri@jurta.org> + + * files.texi (Comparing Files): Mention resync for `compare-windows'. + +2005-07-18 Juri Linkov <juri@jurta.org> + + * calc.texi (Time Zones, Logical Operations): + * cl.texi (Overview): + * custom.texi (Easy Customization): + * files.texi (Old Versions): + * frames.texi (Wheeled Mice): + * mule.texi (Specify Coding): + * org.texi (TODO types): + * sc.texi (Emacs 18 MUAs): + * speedbar.texi (Top): + * text.texi (Cell Justification): + * trouble.texi (After a Crash): + * url.texi (History): + * xresources.texi (GTK styles): + Delete duplicate duplicate words. + +2005-07-17 Richard M. Stallman <rms@gnu.org> + + * frames.texi (Creating Frames): Fix foreground color example. + + * custom.texi (Init Examples): Clean up text about conditionals. + +2005-07-16 Richard M. Stallman <rms@gnu.org> + + * mini.texi (Completion Commands): Fix command name for ?. + +2005-07-16 Johan Bockgard <bojohan@users.sourceforge.net> (tiny change) + + * cl.texi (Type Predicates): Document `atom' type. + +2005-07-16 Eli Zaretskii <eliz@gnu.org> + + * display.texi (Standard Faces): Explain that customization of + `menu' face has no effect on w32 and with GTK. Add + cross-references. + + * cmdargs.texi (General Variables): Clarify the default location + of $HOME on w32 systems. + +2005-07-15 Jason Rumney <jasonr@gnu.org> + + * cmdargs.texi (General Variables): Default HOME on MS Windows has + changed. + +2005-07-08 Kenichi Handa <handa@m17n.org> + + * mule.texi (Recognize Coding): Recommend + revert-buffer-with-coding-system instead of revert-buffer. + +2005-07-07 Richard M. Stallman <rms@gnu.org> + + * anti.texi (Antinews): Mention mode-line-inverse-video. + + * files.texi (Saving): Minor correction about C-x C-w. + + * display.texi (Display Custom): Don't mention mode-line-inverse-video. + +2005-07-07 Luc Teirlinck <teirllm@auburn.edu> + + * search.texi (Isearch Scroll): Add example of using the + `isearch-scroll' property. + (Slow Isearch): Reference anchor for `baud-rate' instead of entire + `Display Custom' node. + (Regexp Replace): Put text that requires Emacs Lisp knowledge last + and de-emphasize it. + (Other Repeating Search): `occur' currently can not correctly + handle multiline matches. Correct, clarify and update description + of `flush-lines' and `keep-lines'. + + * display.texi (Display Custom): Add anchor for `baud-rate'. + +2005-07-07 Richard M. Stallman <rms@gnu.org> + + * gnu.texi: Update where to get GNU status; add refs for how to help. + Add footnotes 6 and 7. + +2005-07-04 Lute Kamstra <lute@gnu.org> + + Update FSF's address in GPL notices. + + * calc.texi (Copying): + * doclicense.texi (GNU Free Documentation License): + * faq.texi (Contacting the FSF): + * mh-e.texi (Copying): + * trouble.texi (Checklist): Update FSF's address. + +2005-07-03 Richard M. Stallman <rms@gnu.org> + + * flymake.texi (Example -- Configuring a tool called directly): + Update name of flymake-build-relative-filename. + +2005-06-29 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (NoCeM): gnus-nocem-verifyer defaults to pgg-verify. + +2005-06-29 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Version 3.12. + +2005-06-24 Richard M. Stallman <rms@gnu.org> + + * display.texi (Text Display): Change index entries. + +2005-06-24 Eli Zaretskii <eliz@gnu.org> + + * makefile.w32-in (MAKEINFO): Use --force. + (INFO_TARGETS, DVI_TARGETS): Make identical to the lists in + Makefile.in. + (gnus.dvi): Use "..." to quote Sed args, so that it works with + more shells. + +2005-06-23 Richard M. Stallman <rms@gnu.org> + + * anti.texi (Antinews): Renamed show-nonbreak-escape to + nobreak-char-display. + + * emacs.texi (Top): Update detailed node listing. + + * display.texi (Text Display): Renamed show-nonbreak-escape + to nobreak-char-display and no-break-space to nobreak-space. + (Standard Faces): Split up the list of standard faces + and put it in a separate node. Add nobreak-space and + escape-glyph. + + * speedbar.texi (Creating a display): Texinfo usage fixes. + + * tramp.texi (Customizing Completion, Auto-save and Backup): + Texinfo usage fixes. + +2005-06-23 Lute Kamstra <lute@gnu.org> + + * mule.texi (Select Input Method): Fix typo. + +2005-06-23 Kenichi Handa <handa@m17n.org> + + * mule.texi (International): List all supported scripts. Adjust + text for that leim is now included in the normal Emacs + distribution. + (Language Environments): List all language environments. + Intlfonts contains fonts for most supported scripts, not all.. + (Select Input Method): Refer to C-u C-x = to see how to type to + input a specifc character. + (Recognize Coding): Fix typo, china-iso-8bit -> chinese-iso-8bit. + +2005-06-23 Juanma Barranquero <lekktu@gmail.com> + + * building.texi (Grep Searching): + * dired-x.texi (Miscellaneous Commands): + * ediff.texi (Miscellaneous): + * gnus.texi (MIME Commands, Fancy Mail Splitting, Agent Visuals) + (Agent Variables): + * info.texi (Help-Xref): + * message.texi (Message Headers): + * org.texi (Remember): + * reftex.texi (Options (Defining Label Environments)): + (Options (Index Support)): + (Options (Viewing Cross-References)): + (Options (Misc)): + (Changes): + * speedbar.texi (Creating a display): + * tramp.texi (Customizing Completion, Auto-save and Backup): + Texinfo usage fix. + +2005-06-22 Miles Bader <miles@gnu.org> + + * display.texi (Faces): Change `vertical-divider' to `vertical-border'. + +2005-06-20 Miles Bader <miles@gnu.org> + + * display.texi (Faces): Add `vertical-divider'. + +2005-06-17 Richard M. Stallman <rms@gnu.org> + + * text.texi (Adaptive Fill): Minor clarification. + +2005-06-13 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Version 3.11. + +2005-06-12 Jay Belanger <belanger@truman.edu> + + * calc.texi (Getting Started): Remove extra menu item. + +2005-06-10 Lute Kamstra <lute@gnu.org> + + * emacs.texi (Top): Correct version number. + * anti.texi (Antinews): Correct version number. Use EMACSVER to + refer to the current version of Emacs. + +2005-06-08 Luc Teirlinck <teirllm@auburn.edu> + + * files.texi (Log Buffer): Document when there can be more than + one file to be committed. + +2005-06-08 Juri Linkov <juri@jurta.org> + + * display.texi (Faces): Add `shadow' face. + +2005-06-07 Masatake YAMATO <jet@gyve.org> + + * display.texi (Faces): Write about mode-line-highlight. + +2005-06-06 Richard M. Stallman <rms@gnu.org> + + * misc.texi (Printing Package): Explain how to initialize + printing package. + + * cmdargs.texi (Action Arguments): Clarify directory default for -l. + +2005-06-05 Chong Yidong <cyd@stupidchicken.com> + + * emacs.texi: Rename Hardcopy to Printing. + Make PostScript and PostScript Variables subnodes of it. + + * misc.texi (Printing): Rename node from Hardcopy. + Mention menu bar options. + Move PostScript and PostScript Variables to submenu. + (Printing package): New node. + + * mark.texi (Using Region): Change Hardcopy xref to Printing. + + * dired.texi (Operating on Files): Likewise. + + * calendar.texi (Displaying the Diary): Likewise. + + * msdog.texi (MS-DOS Printing, MS-DOS Processes): Likewise. + + * glossary.texi (Glossary): Likewise. + + * frames.texi (Mode Line Mouse): Mention mode-line-highlight + effect. + +2005-06-04 Richard M. Stallman <rms@gnu.org> + + * trouble.texi (After a Crash): Polish previous change. + +2005-05-31 Jay Belanger <belanger@truman.edu> + + * calc.texi (Notations Used in This Manual): Use @kbd for key + sequence. + (Demonstration of Calc): Mention another way of starting Calc. + (Starting Calc): Mention long name of M-#. + (Embedded Mode Overview): Remove unnecessary instruction. + (Other M-# commands): Rephrase `M-# 0' explanation. + (Basic Embedded Mode): Rewrite discussion of prefix arguments to + reflect current behavior. + +2005-05-30 Jay Belanger <belanger@truman.edu> + + * calc.texi (Hooks): Change description of calc-window-hook and + calc-trail-window-hook to match usage. + (Computational Functions): Add more constant-generating functions. + (Customizable Variables): Use defvar. + +2005-05-30 Noah Friedman <friedman@splode.com> + + * trouble.texi (After a Crash): Mention emacs-buffer.gdb as a + recovery mechanism. + +2005-05-28 Jay Belanger <belanger@truman.edu> + + * calc.texi (Assignments in Embedded Mode): Fix variable name. + (Basic Embedded Mode): Explain behavior of arguments to + calc-embedded-mode. + +2005-05-28 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Other Buffers): SPC toggles display of + floating point registers. + +2005-05-27 Jay Belanger <belanger@truman.edu> + + * calc.texi (Queries in Keyboard Macros): Rewrite to reflect + current behavior. + +2005-05-27 Nick Roberts <nickrob@snap.net.nz> + + * files.texi (Log Buffer): Merge in description of Log Edit + mode from pcl-cvs.texi. + +2005-05-26 Richard M. Stallman <rms@gnu.org> + + * building.texi (Lisp Eval): C-M-x with arg runs Edebug. + +2005-05-25 Jay Belanger <belanger@truman.edu> + + * calc.texi: Change Calc version number throughout. + (Keypad Mode): Change location in info output. + (Keypad mode overview): Move picture of keypad. + +2005-05-24 Luc Teirlinck <teirllm@auburn.edu> + + * fixit.texi (Spelling): Delete confusing sentence; flyspell is + not enabled by default. + When not on a word, `ispell-word' by default checks the word + before point. + +2005-05-24 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Debugger Operation): Simplify last sentence. + +2005-05-23 Lute Kamstra <lute@gnu.org> + + * emacs.texi: Update FSF's address throughout. + (Preface): Use @cite. + (Distrib): Add cross reference to the node "Copying". Mention the + FDL. Don't refer to etc/{FTP,ORDERS}. Mention the sale of + printed manuals. + (Intro): Use @xref for the Emacs Lisp Intro. + +2005-05-21 Jay Belanger <belanger@truman.edu> + + * calc.texi (Storing variables): Mention that only most variables + are void to begin with. + +2005-05-21 Kevin Ryde <user42@zip.com.au> + + * widget.texi (Basic Types): Update cross ref from "Enabling + Mouse-1 to Follow Links" to "Links and Mouse-1" per recent + lispref/text.texi change. + +2005-05-20 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Version 3.09. + +2005-05-18 Carsten Dominik <dominik@science.uva.nl> + + * reftex.texi: Version 4.28. + +2005-05-18 Luc Teirlinck <teirllm@auburn.edu> + + * buffers.texi (Select Buffer): Document `C-u M-g M-g'. + + * basic.texi (Moving Point): Mention default for `goto-line'. + + * programs.texi (Lisp Doc): Eldoc mode shows only the first line + of a variable's docstring. + +2005-05-18 Lute Kamstra <lute@gnu.org> + + * maintaining.texi (Overview of Emerge): Add cross reference. + Remove duplication. + + * emacs.texi (Top): Update to the current structure of the manual. + * misc.texi (Emacs Server): Add menu description. + * files.texi (Saving): Fix menu. + * custom.texi (Customization): Fix menu. + * mule.texi (International): Fix menu. + * kmacro.texi (Keyboard Macros): Fix menu. + +2005-05-16 Luc Teirlinck <teirllm@auburn.edu> + + * display.texi: Various minor changes. + (Faces): Delete text that is repeated in the next section. + +2005-05-16 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Debugger Operation): Mention GUD tooltips are + disabled with GDB in text command mode. + +2005-05-16 Jay Belanger <belanger@truman.edu> + + * calc.texi (Storing Variables): Mention `calc-copy-special-constant'. + +2005-05-16 Nick Roberts <nickrob@snap.net.nz> + + * building.texi: Replace toolbar with "tool bar" for consistency. + (Compilation Mode): Describe compilation-context-lines + and use of arrow in compilation buffer. + (Debugger Operation): Replace help text with variable's value. + + * frames.texi (Tooltips): Replace toolbar with "tool bar" for + consistency. + +2005-05-15 Luc Teirlinck <teirllm@auburn.edu> + + * major.texi (Choosing Modes): normal-mode processes the -*- line. + Add xref. + +2005-05-14 Jay Belanger <belanger@truman.edu> + + * calc.texi (Default Simplifications): Insert missing ! (logical + not operator). + +2005-05-14 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.0.49. + +2005-05-14 Luc Teirlinck <teirllm@auburn.edu> + + * basic.texi (Moving Point): Mention `M-g g' binding for `goto-line'. + (Position Info): Delete discussion of `goto-line'. It is already + described in `Moving point'. + + * mini.texi (Completion Commands): Correct reference. + (Completion Options): Fix typo. + + * killing.texi (Deletion): Complete description of `C-x C-o'. + +2005-05-10 Jay Belanger <belanger@truman.edu> + + * calc.texi (Default Simplifications): Mention that 0^0 simplifies + to 1. + +2005-05-10 Richard M. Stallman <rms@gnu.org> + + * building.texi (Compilation): Clarify recompile's directory choice. + + * frames.texi (Tooltips): Cleanups. + + * basic.texi (Arguments): Fix punctuation. + +2005-05-09 Luc Teirlinck <teirllm@auburn.edu> + + * screen.texi (Menu Bar): The up and down (not left and right) + arrow keys move through a keyboard menu. + +2005-05-08 Luc Teirlinck <teirllm@auburn.edu> + + * basic.texi: Various typo and grammar fixes. + (Moving Point): C-a now runs move-beginning-of-line. + +2005-05-08 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Debugger Operation): Describe gud-tooltip-echo-area. + + * frames.texi (Tooltips): Describe help tooltips and GUD tooltips + as different animals. + +2005-05-07 Luc Teirlinck <teirllm@auburn.edu> + + * frames.texi (Mouse References): Clarify `mouse-1-click-follows-link'. + Correct index entry. + +2005-05-07 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Debugger Operation): Update to reflect changes + in GUD tooltips. + +2005-04-30 Richard M. Stallman <rms@gnu.org> + + * files.texi (Compressed Files): Auto Compression normally enabled. + + * building.texi (Debugger Operation): Clarify previous change. + +2005-04-29 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Version 3.08, structure reorganized. + +2005-04-28 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Debugger Operation): Add description for + GUD tooltips when program is not running. + +2005-04-26 Luc Teirlinck <teirllm@auburn.edu> + + * misc.texi (Shell): Add `Shell Prompts' to menu. + (Shell Mode): Add xref to `Shell Prompts'. Clarify `C-c C-u' + description. Delete remarks moved to new node. + (Shell Prompts): New node. + (History References): Replace remarks moved to `Shell Prompts' + with xref to that node. + (Remote Host): Clarify how to specify the terminal type when + logging in to a different machine. + +2005-04-26 Richard M. Stallman <rms@gnu.org> + + * emacs.texi (Top): Update submenus from files.texi. + + * files.texi (Filesets): Clarify previous change. + + * dired.texi (Misc Dired Features): Clarify previous change. + +2005-04-25 Chong Yidong <cyd@stupidchicken.com> + + * ack.texi (Acknowledgments): Delete info about iso-acc.el. + + * dired.texi (Misc Dired Features): Document + dired-compare-directories. + + * files.texi (Filesets): New node. + (File Conveniences): Document Image mode. + + * text.texi (TeX Print): Document tex-compile. + +2005-04-25 Luc Teirlinck <teirllm@auburn.edu> + + * frames.texi (Tooltips): Tooltip mode is enabled by default. + Delete redundant reference to tooltip Custom group. It is + referred too again in the next paragraph. + +2005-04-24 Richard M. Stallman <rms@gnu.org> + + * ack.texi: Delete info about lazy-lock.el and fast-lock.el. + + * faq.texi: Delete info about lazy-lock.el and fast-lock.el. + +2005-04-19 Kim F. Storm <storm@cua.dk> + + * building.texi (Compilation Mode): Add M-g M-n and M-g M-p bindings. + +2005-04-18 Lars Hansen <larsh@math.ku.dk> + + * misc.texi (Saving Emacs Sessions): Add that "--no-desktop" now + turns off desktop-save-mode. + +2005-04-17 Luc Teirlinck <teirllm@auburn.edu> + + * frames.texi (XTerm Mouse): Xterm Mouse mode is no longer enabled + by default in terminals compatible with xterm. Mention that + xterm-mouse-mode is a minor mode and put in pxref to Minor Modes + node. + +2005-04-15 Carsten Dominik <dominik@science.uva.nl> + + * org.texi: Update to version 3.06. + +2005-04-13 Lute Kamstra <lute@gnu.org> + + * cc-mode.texi: Prevent creating an unnecessary empty cc-mode.ss file. + +2005-04-12 Luc Teirlinck <teirllm@auburn.edu> + + * frames.texi (XTerm Mouse): Xterm Mouse mode is now enabled by default. + +2005-04-12 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * xresources.texi (Table of Resources): Add cursorBlink. + +2005-04-11 Luc Teirlinck <teirllm@auburn.edu> + + * rmail.texi (Rmail Summary Edit): Explain numeric arguments to + `d', `C-d' and `u'. + +2005-04-11 Richard M. Stallman <rms@gnu.org> + + * cmdargs.texi (Initial Options): -Q is now --quick, and does less. + (Misc X): Add -D, --basic-display. + + * maintaining.texi (Change Log): Correct the description of + the example. + + * major.texi (Choosing Modes): Document magic-mode-alist. + +2005-04-10 Thien-Thi Nguyen <ttn@gnu.org> + + * cl.texi (Porting Common Lisp): Fix typo. + +2005-04-10 Luc Teirlinck <teirllm@auburn.edu> + + * rmail.texi (Rmail Basics): Clarify description of `q' and `b'. + (Rmail Deletion): `C-d' in RMAIL buffer does not accept a numeric arg. + (Rmail Inbox): Give full name of `rmail-primary-inbox-list'. + (Rmail Output): Clarify which statements apply to `o', `C-o' and + `w', respectively. + (Rmail Labels): Mention `l'. + (Rmail Attributes): Correct pxref. Mention `stored' attribute. + (Rmail Summary Edit): Describe `j' and RET. + +2005-04-10 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * xresources.texi (Lucid Resources): Add fontSet resource. + +2005-04-06 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (RSS): Addition. + +2005-04-09 Luc Teirlinck <teirllm@auburn.edu> + + * display.texi (Useless Whitespace): `indicate-unused-lines' is + now called `indicate-empty-lines'. + +2005-04-06 Kim F. Storm <storm@cua.dk> + + * cmdargs.texi (Initial Options): Add --bare-bones alias for -Q. + +2005-04-04 Luc Teirlinck <teirllm@auburn.edu> + + * dired.texi (Dired Visiting): `dired-view-command-alist' has been + deleted. + (Marks vs Flags): Add some convenient key bindings. + (Hiding Subdirectories): Delete redundant and inaccurate sentence. + (Misc Dired Features): Correct and expand description of `w' command. + + * frames.texi (XTerm Mouse): Delete apparently false info. + The GNU/Linux console currently does not appear to support + `xterm-mouse-mode'. + +2005-04-04 Jay Belanger <belanger@truman.edu> + + * calc.texi: Change Calc version number. + (Customizable variables): Fix description of calc-language-alist. + (Copying): Put in version 2 of GPL. + +2005-04-03 Glenn Morris <gmorris@ast.cam.ac.uk> + + * calendar.texi (Diary): Mention shell utility `calendar'. + +2005-04-01 Richard M. Stallman <rms@gnu.org> + + * cmdargs.texi (Misc X): Explain horizontal scroll bars don't exist. + +2005-04-01 Jay Belanger <belanger@truman.edu> + + * calc.texi (Troubleshooting Commands): Remove comment about + installation. + (Installation): Remove section. + (Customizable Variables): New section. + (Basic Embedded Mode, Customizing Embedded Mode, Graphics) + (Graphical Devices): Add references to Customizable Variables. + +2005-04-01 Lute Kamstra <lute@gnu.org> + + * maintaining.texi (Change Log): add-change-log-entry uses + add-log-mailing-address. + +2005-03-31 Luc Teirlinck <teirllm@auburn.edu> + + * files.texi (Reverting): Move `auto-revert-check-vc-info' to + `VC Mode Line' and put in an xref to that node. + (VC Mode Line): Move `auto-revert-check-vc-info' here and clarify + its description. + +2005-03-31 Paul Eggert <eggert@cs.ucla.edu> + + * calendar.texi (Calendar Systems): Say that the Persian calendar + implemented here is the arithmetical one championed by Birashk. + +2005-03-30 Glenn Morris <gmorris@ast.cam.ac.uk> + + * programs.texi (Fortran Motion): Fix previous change. + +2005-03-25 Katsumi Yamaoka <yamaoka@jpl.org> + + * emacs-mime.texi (Display Customization): Markup fixes. + (rfc2047): Update. + +2005-03-23 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus-faq.texi: Replaced with auto-generated version. + +2005-03-29 Richard M. Stallman <rms@gnu.org> + + * mule.texi (Single-Byte Character Support): Reinstall the C-x 8 info. + +2005-03-29 Chong Yidong <cyd@stupidchicken.com> + + * text.texi (Refill): Refer to Long Lines Mode. + (Longlines): New node. + (Auto Fill): Don't index "word wrap" here. + (Filling): Add Longlines to menu. + +2005-03-29 Richard M. Stallman <rms@gnu.org> + + * xresources.texi: Minor fixes. + + * misc.texi (Emacs Server): Fix Texinfo usage. + + * emacs.texi (Top): Don't use a real section heading for + "Detailed Node Listing". Fake it instead. + + * basic.texi (Position Info): Minor cleanup. + + * mule.texi (Input Methods): Minor cleanup. + +2005-03-29 Glenn Morris <gmorris@ast.cam.ac.uk> + + * programs.texi (ForIndent Vars): `fortran-if-indent' does other + constructs as well. + (Fortran Motion): Add fortran-end-of-block, fortran-beginning-of-block. + +2005-03-29 Kenichi Handa <handa@m17n.org> + + * mule.texi (Input Methods): Refer to the command C-u C-x =. + + * basic.texi (Position Info): Update the description about the + command C-u C-x =. + +2005-03-28 Richard M. Stallman <rms@gnu.org> + + * emacs.texi (Top): Use @section for the detailed node listing. + + * calendar.texi: Minor fixes to previous change. + + * programs.texi (Fortran): Small fixes to previous changes. + + * emacs.texi (Top): Update list of subnodes of Dired. + Likewise for building.texi. + + * files.texi (File Conveniences): Delete Auto Image File mode. + +2005-03-28 Chong Yidong <cyd@stupidchicken.com> + + * building.texi (Flymake): New node. + + * custom.texi (Function Keys): Document kp- event types and + keypad-setup package. + + * dired.texi (Wdired): New node. + + * files.texi (File Conveniences): Reorder entries. + Explain how to turn on Auto-image-file mode. + Document Thumbs mode. + + * mule.texi (Specify Coding): Document recode-region and + recode-file-name. + + * programs.texi (Program Modes): Add Conf mode and DNS mode. + +2005-03-27 Luc Teirlinck <teirllm@auburn.edu> + + * commands.texi (Keys): M-o is now a prefix key. + +2005-03-27 Glenn Morris <gmorris@ast.cam.ac.uk> + + * programs.texi: Reformat and update copyright years. + (Fortran): Update section. + +2005-03-26 Luc Teirlinck <teirllm@auburn.edu> + + * files.texi: Several small changes in addition to: + (Visiting): Change xref for Dialog Boxes to ref. + (Version Headers): Replace references to obsolete var + `vc-header-alist' with `vc-BACKEND-header'. + (Customizing VC): Update value of `vc-handled-backends'. + +2005-03-26 Glenn Morris <gmorris@ast.cam.ac.uk> + + * emacs-xtra.texi (Advanced Calendar/Diary Usage): New section; + move here from Emacs Lisp Reference Manual. + * calendar.texi (Calendar/Diary, Diary Commands) + (Special Diary Entries, Importing Diary): Change some xrefs to + point to emacs-xtra rather than elisp. + + * emacs-xtra.texi (Calendar Customizing): + Move view-diary-entries-initially, view-calendar-holidays-initially, + mark-diary-entries-in-calendar, mark-holidays-in-calendar to main + Emacs Manual. + (Appt Customizing): Merge entire section into main Emacs Manual. + * calendar.texi (Holidays): Move view-calendar-holidays-initially, + mark-holidays-in-calendar here from emacs-xtra. + (Displaying the Diary): Move view-diary-entries-initially, + mark-diary-entries-in-calendar here from emacs-xtra. + (Appointments): Move appt-display-mode-line, + appt-display-duration, appt-disp-window-function, + appt-delete-window-function here from emacs-xtra. + + * calendar.texi: Update and reformat copyright. + Change all @xrefs to the non-printing emacs-xtra to @inforefs. + (Calendar/Diary): Menu now only on Mouse-3, not C-Mouse-3. + (Diary): Refer to `diary-file' rather than ~/diary. + (Diary Commands): Rename node to "Displaying the Diary". + * emacs.texi (Top): Rename "Diary Commands" section. + * misc.texi (Hardcopy): Rename "Diary Commands" xref. + +2005-03-26 Eli Zaretskii <eliz@gnu.org> + + * misc.texi (Emacs Server): Fix the command for setting + server-name. Add an xref to Invoking emacsclient. + + * help.texi (Help Summary): Clarify when "C-h ." will do something + nontrivial. + (Apropos): Add cindex entry for apropos-sort-by-scores. + + * display.texi (Text Display): Add index entries for how no-break + characters are displayed. + +2005-03-26 Stephan Stahl <stahl@eos.franken.de> (tiny change) + + * dired-x.texi (Multiple Dired Directories): default-directory was + renamed to dired-default-directory. + +2005-03-26 Eli Zaretskii <eliz@gnu.org> + + * files.texi (Visiting): Fix cross-references introduced with the + last change. + + * xresources.texi (GTK resources): Fix last change. + +2005-03-26 Jay Belanger <belanger@truman.edu> + + * calc.texi (Simplifying Formulas, Rewrite Rules): + Change description of top and bottom of fraction. + (Modulo Forms): Move description of how to create modulo forms to + earlier in the section. + (Fraction Mode): Suggest using : to get a fraction by dividing. + (Basic Arithmetic): Adjust placement of command name. + (Truncating the Stack): Emphasize that "hidden" entries are still + visible. + (Installation): Move discussion of printing manual to "About This + Manual". + (About This Manual): Mention how to print the manual. + (Reporting Bugs): Remove first person. + (Building Vectors): Add algebraic version of append. + (Manipulating Vectors): Fix algebraic version of calc-reverse-vector. + (Grouping Digits): Fix typo. + +2005-03-25 Chong Yidong <cyd@stupidchicken.com> + + * xresources.texi (X Resources): GTK options documented too. + (Resources): Clarify meaning of program name. + (Table of Resources): Add visualClass. + (GTK resources): Rewrite. + (GTK widget names, GTK Names in Emacs, GTK styles): Cleanups. + + * display.texi (Text Display): Mention non-breaking spaces. + + * files.texi (Reverting): Document auto-revert-check-vc-info. + + * frames.texi (Mouse Commands): Document + x-mouse-click-focus-ignore-position and mouse-drag-copy-region. + + * help.texi (Help Summary): Add `C-h .'. + (Apropos): Apropos accepts a list of search terms. + Document apropos-sort-by-scores. + (Help Echo): Document display-local-help. + + * misc.texi (Emacs Server): Document server-name. + (Invoking emacsclient): Document -s option for server names. + + * text.texi (Outline Visibility): Introduce "current heading + line" (commands can be called with point on a body line). + Re-order table to follow the sequence of discussion. + hide-body won't hide lines before first header line. + (TeX Mode): Add DocTeX mode. + +2005-03-25 Werner Lemberg <wl@gnu.org> + + * calc.texi, cl.texi, gnus.texi, idlwave.texi, reftex.texi: + Replace `legal' with `valid'. + +2005-03-25 Werner Lemberg <wl@gnu.org> + + * calc.texi, reftex.texi: Replace `illegal' with `invalid'. + +2005-03-24 Jay Belanger <belanger@truman.edu> + + * calc.texi (General Mode Commands) + (Mode Settings in Embedded Mode): Add some explanation of + recording mode settings. + +2005-03-24 Richard M. Stallman <rms@gnu.org> + + * mule.texi (Single-Byte Character Support): Delete mention + of iso-acc.el and iso-transl.el. + + * calc.texi: Remove praise of non-free software. + + * idlwave.texi: Don't say where to get IDL or its non-free manual. + (Installation): Node deleted. + +2005-03-23 Lute Kamstra <lute@gnu.org> + + * search.texi (Non-ASCII Isearch): Rename from Non-Ascii Isearch. + +2005-03-23 Richard M. Stallman <rms@gnu.org> + + * url.texi (HTTP language/coding): Improve last change. + + * search.texi: Delete explicit node pointers. + (Incremental Search): New menu. + (Basic Isearch, Repeat Isearch, Error in Isearch) + (Non-Ascii Isearch, Isearch Yank, Highlight Isearch, Isearch Scroll) + (Slow Isearch): New subnodes. + (Configuring Scrolling): Node deleted. + (Search Case): Doc default-case-fold-search. + (Regexp Replace): Move replace-regexp doc here. + + * rmail.texi (Movemail): Put commas inside closequotes. + + * picture.texi (Insert in Picture): Document C-c arrow combos. + (Basic Picture): Clarify erasure. + + * display.texi (Font Lock): Put commas inside closequotes. + + * cmdargs.texi (General Variables): Put commas inside closequotes. + +2005-03-23 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Stack Buffer): Mention reverse contrast for + *selected* frame (might not be current frame). + +2005-03-22 Jay Belanger <belanger@truman.edu> + + * calc.texi (Embedded Mode): Add new information on changing + modes. + +2005-03-21 Richard M. Stallman <rms@gnu.org> + + * building.texi (Starting GUD): Add bashdb. + +2005-03-20 Chong Yidong <cyd@stupidchicken.com> + + * basic.texi (Moving Point): Add M-g M-g binding. + (Undo): Document undo-only. + (Position Info): Document M-g M-g and C-u M-g M-g. + + * building.texi (Building): Put Grep Searching after Compilation + Shell. + (Compilation Mode): Document M-n, M-p, M-}, M-{, and C-c C-f bindings. + Document next-error-highlight. + (Grep Searching): Document grep-highlight-matches. + (Lisp Eval): Typing C-x C-e twice prints integers specially. + + * calendar.texi (Importing Diary): Rename node from iCalendar. + Document diary-from-outlook. + + * dired.texi (Misc Dired Features): Rename node from Misc Dired + Commands. + Mention effect of X drag and drop on Dired buffers. + + * files.texi (Visiting): Document large-file-warning-threshold. + Move paragraph on file-selection dialog. + Mention visiting files using X drag and drop. + (Reverting): Mention using Auto-Revert mode to tail files. + Document auto-revert-tail-mode. + (Version Systems): Minor correction. + (Comparing Files): Diff-mode is no longer based on Compilation + mode. + Document compare-ignore-whitespace. + (Misc File Ops): Explain passing a directory to rename-file. + Likewise for copy-file and make-symbolic-link. + + * frames.texi (Wheeled Mice): Mouse wheel support on by default. + Document mouse-wheel-progressive speed. + + * help.texi (Misc Help): Document numeric argument for C-h i. + Correctly explain the effect of just C-u as argument. + + * killing.texi (Deletion): Document numeric argument for + just-one-space. + + * mini.texi (Completion): Completion acts on text before point. + + * misc.texi (Saving Emacs Sessions): Document desktop-restore-eager. + (Emulation): CUA mode replaces pc-bindings-mode, + pc-selection-mode, and s-region. + + * mule.texi (Input Methods): Leim is now built-in. + (Select Input Method): Document quail-show-key. + (Specify Coding): Document revert-buffer-with-coding-system. + + * programs.texi (Fortran Motion): Document f90-next-statement, + f90-previous-statement, f90-next-block, f90-previous-block, + f90-end-of-block, and f90-beginning-of-block. + + * text.texi (Format Faces): Replace old M-g key prefix with M-o. + + * emacs.texi (Acknowledgments): Updated. + + * anti.texi: Total rewrite. + +2005-03-20 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.0.48. + + * trampver.texi.in: Replace "Emacs" by "GNU Emacs". + + * tramp.texi: Replace "Emacs" by "GNU Emacs". Replace "Linux" by + "GNU/Linux". Change all addresses to .gnu.org. + (Default Method): Offer shortened syntax for "su" and "sudo" + methods. + +2005-03-19 Chong Yidong <cyd@stupidchicken.com> + + * ack.texi (Acknowledgments): Update. + +2005-03-19 Eli Zaretskii <eliz@gnu.org> + + * anti.texi (Antinews): Refer to Emacs 21.4, not 21.3. Update + copyright years. + +2005-03-14 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Commands of GUD): Move paragraph on setting + breakpoints with mouse to the GDB Graphical Interface node. + +2005-03-07 Richard M. Stallman <rms@gnu.org> + + * url.texi: Fix usage of "e.g.". + (HTTP language/coding): Explain the rules for these strings. + + * misc.texi (Single Shell, Shell Options): Fix previous change. + + * building.texi (Debugger Operation): Update GUD tooltip enable info. + +2005-03-06 Richard M. Stallman <rms@gnu.org> + + * building.texi (Starting GUD): Don't explain text vs graphical + GDB here. Just mention it and xref. + Delete "just one debugger process". + (Debugger Operation): Move GUD tooltip info here. + (GUD Tooltips): Node deleted. + (GDB Graphical Interface): Explain the two GDB modes here. + + * woman.texi (Introduction): Minor cleanups. + + * url.texi (HTTP language/coding): Get rid of "Emacs 21". + + * sending.texi (Sending Mail): Minor cleanup. + (Mail Aliases): Explain quoting conventions. + Update key rebinding example. + (Header Editing): C-M-i is like M-TAB. + (Mail Mode Misc): mail-attach-file does not do MIME. + + * rmail.texi (Rmail Inbox): Move text from Remote Mailboxes + that really belongs here. + (Remote Mailboxes): Text moved to Rmail Inbox. + (Rmail Display): Mention Mouse-1. + (Movemail): Clarify two movemail versions. + Clarify rmail-movemail-program. + + * pcl-cvs.texi (About PCL-CVS): Get rid of "Emacs 21". + (Installation): Node deleted. + + * misc.texi (Single Shell): Replace uudecode example with gpg example. + Document async shell commands. + (Shell History): Clarify. + (Shell Ring): Mention C-UP an C-DOWN. + (Shell Options): Add comint-prompt-read-only. + (Invoking emacsclient): Set EDITOR to run Emacs. + (Sorting): No need to explain what region is. + (Saving Emacs Sessions): Fix typo. + (Recursive Edit): Fix punctuation. + (Emulation): Don't mention "PC bindings" which are standard. + (Hyperlinking): Explain Mouse-1 convention here. + (Find Func): Node deleted. + + * mh-e.texi (Preface): Get rid of "Emacs 21". + + * help.texi (Name Help): Xref to Hyperlinking. + + * glossary.texi (Glossary): + Rename "Balance Parentheses" to "Balancing...". + Add "Byte Compilation". Correct "Copyleft". + New xref in "Customization". + Clarify "Current Line", "Echoing", "Fringe", "Frame", "Speedbar". + Add "Graphical Terminal" "Keybinding", "Margin", "Window System". + Rename "Registers" to "Register". + Replace "Selecting" with "Selected Frame", + "Selected Window", and "Selecting a Buffer". + + * files.texi (Types of Log File): Explain how projects' + methods can vary. + + * eshell.texi (Installation): Delete node (for Emacs 20). + + * display.texi (Faces): Delete "Emacs 21". + + * custom.texi (Changing a Variable): C-M-i like M-TAB. + * fixit.texi (Spelling): C-M-i like M-TAB. + * mini.texi (Completion Options): C-M-i like M-TAB. + * programs.texi (Symbol Completion): C-M-i like M-TAB. + * text.texi (Text Mode): C-M-i like M-TAB. + + * commands.texi (Keys): Mention F1 and F2 in list of prefixes. + + * calendar.texi (Specified Dates): Mention `g w'. + (Appointments): appt-activate toggles with no arg. + +2005-03-05 Thien-Thi Nguyen <ttn@gnu.org> + + * flymake.texi: Refill and tweak style in @lisp blocks. + +2005-03-05 Juri Linkov <juri@jurta.org> + + * cmdargs.texi (Emacs Invocation): Add cindex + "invocation (command line arguments)" + (Misc X): Add -nbc, --no-blinking-cursor. + +2005-03-04 Ulf Jasper <ulf.jasper@web.de> + + * calendar.texi (iCalendar): No need to require it now. + +2005-03-03 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Slow/Expensive Connection): Don't abbreviate "very". + +2005-03-03 Nick Roberts <nickrob@snap.net.nz> + + * trouble.texi (Contributing): Mention Savannah. Direct users to + emacs-devel. + +2005-03-01 Glenn Morris <gmorris@ast.cam.ac.uk> + + * calendar.texi (Adding to Diary): Mention redrawing of calendar + window. + +2005-03-01 Jay Belanger <belanger@truman.edu> + + * calc.texi (Trigonometric and Hyperbolic Functions): + Mention additional functions. + (Algebraic Simplifications): Mention additional simplifications. + +2005-02-27 Richard M. Stallman <rms@gnu.org> + + * building.texi (Compilation): Update mode line status info. + +2005-02-27 Matt Hodges <MPHodges@member.fsf.org> + + * calendar.texi (General Calendar): Document binding of + scroll-other-window-down. + (Mayan Calendar): Fix earliest date. + (Time Intervals): Document timeclock-change. + Fix timeclock-ask-before-exiting documentation. + +2005-02-26 Kim F. Storm <storm@cua.dk> + + * frames.texi (Mouse References): + Add mouse-1-click-in-non-selected-windows. + +2005-02-25 Richard M. Stallman <rms@gnu.org> + + * screen.texi (Screen): Explain better about cursors and mode lines; + don't presuppose text terminals. + (Point): Don't assume just one cursor. + Clarify explanation of cursors. + (Echo Area, Menu Bar): Cleanups. + + * mini.texi (Minibuffer): Prompts are highlighted. + (Minibuffer Edit): Newline = C-j only on text terminals. + Clarify resize-mini-windows values. + Mention M-PAGEUP and M-PAGEDOWN. + (Completion Commands): Mouse-1 like Mouse-2. + (Minibuffer History): Explain history commands better. + (Repetition): Add xref to Incremental Search. + + * mark.texi (Setting Mark): Clarify info about displaying mark. + Clarify explanation of C-@ and C-SPC. + (Transient Mark): Mention Delete Selection mode. + (Marking Objects): Clean up text about extending the region. + + * m-x.texi (M-x): One C-g doesn't always go to top level. + No delay before suggest-key-bindings output. + + * fixit.texi (Fixit): Mention C-/ for undo. + (Spelling): Mention ESC TAB like M-TAB. + Replacement words with r and R are rechecked. + Say where C-g leaves point. Mention ? as input. + +2005-02-23 Lute Kamstra <lute@gnu.org> + + * cmdargs.texi (Initial Options): Add cross reference. + +2005-02-18 Jonathan Yavner <jyavner@member.fsf.org> + + * ses.texi: Add concept/function/variable indices (this work was + donated by Brad Collins <brad@chenla.org>, copyright-assignment + papers on file at FSF). + +2005-02-16 Luc Teirlinck <teirllm@auburn.edu> + + * emacs.texi (Top): Update menu for splitting of node in + msdog.texi. + * frames.texi (Frames): Update xref for splitting of node in + msdog.texi. + * trouble.texi (Quitting): Ditto. + +2005-02-16 Richard M. Stallman <rms@gnu.org> + + * windows.texi (Split Window): Simplify line truncation info + and xref to Display Custom. + + * trouble.texi (Quitting): Emergency escape only for text terminal. + (Screen Garbled): C-l for ungarbling is only for text terminal. + + * text.texi (Text Mode): ESC TAB alternative for M-TAB. + + * sending.texi (Header Editing): ESC TAB alternative for M-TAB. + + * programs.texi (Program Modes): Mention Python mode. + (Moving by Defuns): Repeating C-M-h extends region. + (Basic Indent): Clarify. + (Custom C Indent): Clarify. + (Expressions): Repeating C-M-@ extends region. + (Info Lookup): Clarify for C-h S. + (Symbol Completion): ESC TAB alternative for M-TAB. + (Electric C): Clarify. + + * emacs.texi (Top): Update display.texi and frames.texi submenu data. + + * msdog.texi (MS-DOS Keyboard, MS-DOS Mouse): Split from + MS-DOS Input node. + (MS-DOS Keyboard): Start with explaining DEL and BREAK. + (MS-DOS and MULE): Clarify. + (MS-DOS Processes, Windows Processes): Fix typos. + + * major.texi (Choosing Modes): Clarify. + + * kmacro.texi (Basic Keyboard Macro): Doc F3, F4. + (Keyboard Macro Step-Edit): Clarify. + + * indent.texi (Indentation): Clarifications. + + * help.texi (Help): Correct error about C-h in query-replace. + Clarify apropos vs C-h a. Fix how to search in FAQ. + (Key Help): Describe C-h w here. + (Name Help): Minor cleanup. C-h w moved to Key Help. + Clarify the "object" joke. + (Apropos): Clarify. Mouse-1 like Mouse-2. + (Help Mode): Mouse-1 like Mouse-2. + + * fixit.texi (Spelling): Mention ESC TAB as alt. for M-TAB. + + * display.texi (Display): Reorder menu. + (Faces): Cleanup. + (Font Lock): Cleanup. Mention Options menu. + Delete obsolete text. + (Scrolling): For C-l, don't presume text terminal. + (Horizontal Scrolling): Simplify intro. + (Follow Mode): Clarify. + (Cursor Display): Moved before Display Custom. + (Display Custom): Explain no-redraw-on-reenter is for text terminals. + Doc default-tab-width. Doc line truncation more thoroughly. + + * dired.texi (Dired Enter): C-x C-f can run Dired. + (Dired Visiting): Comment out `a' command. + Mouse-1 is like Mouse-2. + (Shell Commands in Dired): ? can be used more than once. + + * basic.texi (Continuation Lines): Simplify description of truncation, + and refer to Display Custom for the rest of it. + +2005-02-10 Jay Belanger <belanger@truman.edu> + + * calc.texi: Change @LaTeX to La@TeX throughout. + Redefine @expr as @math for TeX output. + Redefine @texline as a no-op for TeX output. + Define @tfn, replace @t by @tfn throughout. + +2005-02-09 Jay Belanger <belanger@truman.edu> + + * calc.texi: Add macro for LaTeX for info output. + +2005-02-08 Kim F. Storm <storm@cua.dk> + + * texinfo.tex (LaTex): Add def. + +2005-02-06 Jay Belanger <belanger@truman.edu> + + * calc.texi (TeX Language Mode): Add mention of LaTeX mode, and + change name to "TeX and LaTeX Language Modes." Mention LaTeX mode + throughout manual. + +2005-02-06 Lute Kamstra <lute@gnu.org> + + * basic.texi (Undo): Fix typo. + + * cmdargs.texi (Emacs Invocation): Fix typo. + + * custom.texi (Init Examples): Fix typo. + + * abbrevs.texi (Expanding Abbrevs): Fix typo. + +2005-02-06 Richard M. Stallman <rms@gnu.org> + + * regs.texi (Registers): Registers can hold numbers, too. + + * killing.texi (Other Kill Commands): Cleanup. + Delete redundant explanation of kill in read-only buffer. + (Yanking): Mention term "copying". + (Accumulating Text): Fix typo. + + * entering.texi (Entering Emacs): Update rationale at start. + (Exiting): Treat iconifying on a par with suspension. + + * custom.texi (Minor Modes): Fix typo. + (Easy Customization): Fix menu style. + (Variables): Add xref. + (Examining): Setting for future sessions works through .emacs. + (Keymaps): "Text terminals", not "Many". + (Init Rebinding): Explain \C-. Show example of \M-. + Fix minor wording errors. + (Function Keys): Explain vector syntax just once. + (Named ASCII Chars): Clarify history of TAB/C-i connection. + (Init File): Mention .emacs.d directory. + (Init Examples): Add xref. + (Find Init): Mention .emacs.d directory. + + * cmdargs.texi (Emacs Invocation): +LINENUM is also an option. + (Action Arguments): Explain which kinds of -l args are found how. + (Initial Options): --batch does not inhibit site-start. + Add xrefs. + (Command Example): Use --batch, not -batch. + + * basic.texi (Inserting Text): Cleanup wording. + (Moving Point): Doc PRIOR, PAGEUP, NEXT, PAGEDOWN more systematically. + C-n is not error at end of buffer. + (Undo): Doc C-/ like C-_. Add xrefs. + (Arguments): META key may be labeled ALT. + Peculiar arg meanings are explained in doc strings. + + * abbrevs.texi (Expanding Abbrevs): Clarify. + +2005-02-05 Eli Zaretskii <eliz@gnu.org> + + * frames.texi (Frame Parameters): Add an xref to the description + of list-colors-display. Add a pointer to the X docs about colors. + + * cmdargs.texi (Colors): Mention 16-, 88- and 256-color modes. + Impove docs of list-colors-display. + +2005-02-03 Lute Kamstra <lute@gnu.org> + + * frames.texi (Frames, Drag and Drop): Fix typos. + +2005-02-03 Richard M. Stallman <rms@gnu.org> + + * windows.texi (Basic Window): Mention color-change in mode line. + (Change Window): Explain dragging vertical boundaries. + + * text.texi (Sentences): Clarify. + (Paragraphs): Explain M-a and blank lines. + (Outline Mode): Clarify text and menu. + (Hard and Soft Newlines): Mention use-hard-newlines. + + * frames.texi (Frames): Delete unnecessary mention of Windows. + (Mouse Commands): Likewise. Mention xterm mouse support. + (Clipboard): Clarify. + (Mouse References): Mention use of Mouse-1 for following links. + (Menu Mouse Clicks): Clarify. + (Mode Line Mouse): Clarify. + (Drag and Drop): Rewrite. + + * fixit.texi (Spelling): Fix typo. + + * files.texi (File Names): Clarify. + (Visiting): Update conditions for use of file dialog. Clarify. + (Saving): Doc d as answer in save-some-buffers. + (Remote Files): Clean up the text. + + * dired.texi (Misc Dired Commands): Delete dired-marked-files. + + * buffers.texi (Select Buffer): Doc next-buffer and prev-buffer. + (List Buffers): Clarify. + (Several Buffers): Doc T command. + (Buffer Convenience): Clarify menu. + + * basic.texi (Undo): Clarify last change. + +2005-02-02 Matt Hodges <MPHodges@member.fsf.org> + + * fixit.texi (Spelling): Fix typo. + +2005-02-01 Luc Teirlinck <teirllm@auburn.edu> + + * basic.texi (Undo): Update description of `undo-outer-limit'. + +2005-02-01 Nick Roberts <nickrob@snap.net.nz> + + * building.texi: Update documentation relating to GDB Graphical + Interface. + +2005-01-30 Luc Teirlinck <teirllm@auburn.edu> + + * custom.texi (Easy Customization): Adapt menu to node name change. + +2005-01-30 Richard M. Stallman <rms@gnu.org> + + * custom.texi (Easy Customization): Defn of "User Option" now + includes faces. Don't say just "option" when talking about variables. + Do say just "options" to mean "anything customizable". + (Specific Customization): Describe `customize-variable', + not `customize-option'. + + * glossary.texi (Glossary) <Faces>: Add xref. + <User Option>: Change definition--include faces. Change xref. + + * picture.texi (Picture): Mention artist.el. + + * sending.texi, screen.texi, programs.texi, misc.texi: + * mini.texi, major.texi, maintaining.texi, macos.texi: + * help.texi, frames.texi, files.texi: + Don't say just "option" when talking about variables. + + * display.texi, mule.texi: Don't say just "option" when talking + about variables. Other minor cleanups. + +2005-01-28 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * gnus.texi: Some edits based on comments from David Abrahams. + +2005-01-24 Katsumi Yamaoka <yamaoka@jpl.org> + + * gnus.texi (RSS): Fix the keystroke. + +2005-01-26 Lute Kamstra <lute@gnu.org> + + * cmdargs.texi (Initial Options): Add a cross reference to `Init + File'. Mention the `-Q' option at the `--no-site-file' option. + +2005-01-24 David Kastrup <dak@gnu.org> + + * faq.texi: Update AUCTeX version info. + +2005-01-16 Xavier Maillard <zedek@gnu-rox.org> (tiny change) + + * gnus-faq.texi ([4.1]): Typo. + +2005-01-22 David Kastrup <dak@gnu.org> + + * building.texi (Grep Searching): Mention alias `find-grep' for + `grep-find'. + +2005-01-20 Richard M. Stallman <rms@gnu.org> + + * calendar.texi (Time Intervals): Delete special stuff for MS-DOS. + +2005-01-19 Jay Belanger <belanger@truman.edu> + + * calc.texi (Keep Arguments): Mention that keeping arguments + doesn't work with keyboard macros. + +2005-01-16 Richard M. Stallman <rms@gnu.org> + + * autotype.texi (Autoinserting): Fix small error. + +2005-01-16 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.0.47. + + * tramp.texi (Compilation): New section, describing compilation of + remote files. + +2005-01-15 Sergey Poznyakoff <gray@Mirddin.farlep.net> + + * rmail.texi (Movemail): Explain differences + between standard and mailutils versions of movemail. + Describe command line and configuration options introduced + with the latter. + Explain the notion of mailbox URL, provide examples and + cross-references to mailutils documentation. + Describe various methods of specifying mailbox names, + user names and user passwords for rmail. + (Remote Mailboxes): New section. Describe + how movemail handles remote mailboxes. Describe configuration + options used to control its behavior. + (Other Mailbox Formats): Explain handling of various mailbox + formats. + +2005-01-13 Richard M. Stallman <rms@gnu.org> + + * commands.texi (Commands): Clarification. + +2005-01-11 Richard M. Stallman <rms@gnu.org> + + * programs.texi (Multi-line Indent): Fix previous change. + (Fortran Autofill): Simplify description of fortran-auto-fill-mode. + +2005-01-11 Kim F. Storm <storm@cua.dk> + + * widget.texi (Basic Types): Add :follow-link keyword. + +2005-01-09 Jay Belanger <belanger@truman.edu> + + * calc.texi (Basic Commands): Describe new behavior of calc-reset. + +2005-01-08 Richard M. Stallman <rms@gnu.org> + + * display.texi (Faces): isearch-lazy-highlight-face renamed to + lazy-highlight. + + * search.texi (Query Replace): Mention faces query-replace + and lazy-highlight. + (Incremental Search): Update isearch highlighting info. + +2005-01-08 Jay Belanger <belanger@truman.edu> + + * calc.texi: Change throughout to reflect new default value of + calc-settings-file. + +2005-01-06 Katsumi Yamaoka <yamaoka@jpl.org> + + * message.texi (Reply): `message-reply-to-function' should return + a list. Suggested by ARISAWA Akihiro <ari@mbf.ocn.co.jp>. + +2005-01-06 Hiroshi Fujishima <pooh@nature.tsukuba.ac.jp> (tiny change) + + * faq.texi (Changing load-path): Fix typo. + +2005-01-05 Jay Belanger <belanger@truman.edu> + + * calc.texi (Programming Tutorial): Replace kbd command by + appropriate characters for a keyboard macro. + +2005-01-04 Jay Belanger <belanger@truman.edu> + + * calc.texi (Basic Tutorial, Programming Tutorial): Remove caveats + for Lucid Emacs. + (Programming Tutorial): Mention that the user needs to be in the + right mode to compute some functions. + +2005-01-04 Richard M. Stallman <rms@gnu.org> + + * custom.texi (Saving Customizations): Minor improvement. + +2005-01-04 Jay Belanger <belanger@truman.edu> + + * calc.texi (Rewrite rules): Remove an exercise (on 0^0) which is + no longer applicable. + +2005-01-03 Luc Teirlinck <teirllm@auburn.edu> + + * custom.texi (Saving Customizations): Emacs no longer loads + `custom-file' after .emacs. No longer mention customizing through + Custom. + +2005-01-01 Jay Belanger <belanger@truman.edu> + + * calc.texi (Programming Tutorial): Changed description of how to + edit keyboard macros to match current behavior. + +2005-01-01 Andreas Schwab <schwab@suse.de> + + * killing.texi (Graphical Kill): Move up under node Killing, + change @section to @subsection. + +2005-01-01 Richard M. Stallman <rms@gnu.org> + + * custom.texi (Face Customization): Mention hex color specs. + + * emacs.texi (Top): Update Killing submenu. + + * killing.texi (Killing): Reorganize section. + No more TeX-only text; put the node command at start of chapter. + But the first section heading is used only in TeX. + Rewrite the text to read better in this mode. + (Graphical Kill): New subnode gets some of the text that + used to be in the first section. + +2004-12-31 Richard M. Stallman <rms@gnu.org> + + * dired.texi (Shell Commands in Dired): Delete the ? example. + + * display.texi (Scrolling): Correct scroll-preserve-screen-position. + + * files.texi (Saving): Describe new require-final-newline features + and mode-require-final-newline. + +2004-12-31 Jay Belanger <belanger@truman.edu> + + * calc.texi: Mention C-cC-c as the way to finish editing throughout. + +2004-12-29 Richard M. Stallman <rms@gnu.org> + + * custom.texi (File Variables): Clarify previous change. + +2004-12-27 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * frames.texi (Dialog Boxes): Mention Gtk+ 2.6 also, as that version is + out now. + +2004-12-27 Richard M. Stallman <rms@gnu.org> + + * Makefile.in (MAKEINFO): Specify --force. + + * basic.texi (Moving Point): C-e now runs move-end-of-line. + (Undo): Doc undo-outer-limit. + +2004-12-20 Jay Belanger <belanger@truman.edu> + + * calc.texi (Types Tutorial): Emphasize that you can't divide by + zero. + +2004-12-17 Luc Teirlinck <teirllm@auburn.edu> + + * cc-mode.texi (Text Filling and Line Breaking): Put period after + @xref. + (Font Locking): Avoid @strong{Note:}. + +2004-12-17 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.0.46. + + * tramp.texi (bottom): Add arch-tag. It was lost, somehow. + +2004-12-16 Luc Teirlinck <teirllm@auburn.edu> + + * url.texi: Correct typos. + (Retrieving URLs): @var{nil}->@code{nil}. + (HTTP language/coding, mailto): Replace "GNU Emacs Manual" with + the standard "The GNU Emacs Manual" in fifth argument of @xref's. + (Dealing with HTTP documents): @inforef->@xref. + +2004-12-15 Juri Linkov <juri@jurta.org> + + * mark.texi (Transient Mark, Mark Ring): M-< and other + movement commands don't set mark in Transient Mark mode + if mark is active. + +2004-12-15 Jay Belanger <belanger@truman.edu> + + * calc.texi: Consistently capitalized all mode names. + (Answers to Exercises): Mention that an answer can be a fraction + when in Fraction mode. + +2004-12-13 Jay Belanger <belanger@truman.edu> + + * calc.texi: Fix some TeX definitions. + +2004-12-12 Juri Linkov <juri@jurta.org> + + * misc.texi (FFAP): Add C-x C-r, C-x C-v, C-x C-d, + C-x 4 r, C-x 4 d, C-x 5 r, C-x 5 d. + + * dired.texi (Dired Navigation): Add @r{(Dired)} to M-g. + (Misc Dired Commands): Add @r{(Dired)} to w. + +2004-12-12 Juri Linkov <juri@jurta.org> + + * mark.texi (Marking Objects): Marking commands also extend the + region when mark is active in Transient Mark mode. + +2004-12-09 Luc Teirlinck <teirllm@auburn.edu> + + * reftex.texi (Imprint): Remove erroneous @value's. + +2004-12-08 Luc Teirlinck <teirllm@auburn.edu> + + * custom.texi (Saving Customizations): Emacs only loads the custom + file automatically after the init file in version 22.1 or later. + Adapt text and examples to this fact. + + * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, $(infodir)/org) + (org.dvi, $(infodir)/url, url.dvi, clean): Add org and url manuals. + +2004-12-08 Jay Belanger <belanger@truman.edu> + + * calc.texi (Starting Calc): Remove comment about installation. + (Keypad Mode Overview): Remove comment about Emacs 19 support. + +2004-12-08 Luc Teirlinck <teirllm@auburn.edu> + + * url.texi: Update @setfilename. + (Getting Started): No need to worry about Gnus versions. + (Dealing with HTTP documents): Use @inforef. + + * org.texi: Fix @direntry file name. + +2004-12-07 Luc Teirlinck <teirllm@auburn.edu> + + * frames.texi (Scroll Bars): The option `scroll-bar-mode' has to + be set through Custom. Otherwise, it has no effect. + +2004-12-07 Stefan <monnier@iro.umontreal.ca> + + * url.texi: New file. + + * Makefile.in (INFO_TARGETS, DVI_TARGETS, ../info/url, url.dvi): Add it. + +2004-12-06 Jay Belanger <belanger@truman.edu> + + * calc.texi (Using Calc): Remove paragraph about installation. + +2004-12-06 Jay Belanger <belanger@truman.edu> + + * calc.texi: Use more Texinfo macros and less TeX defs. + Remove @refill's. + +2004-12-06 Richard M. Stallman <rms@gnu.org> + + * org.texi: New file. + +2004-12-05 Richard M. Stallman <rms@gnu.org> + + * cmdargs.texi, doclicense.texi, xresources.texi, emacs.texi: + * entering.texi: Rename Command Line to Emacs Invocation. + + * Makefile.in (org.dvi, ../info/org): New targets. + (INFO_TARGETS): Add ../info/org. + (DVI_TARGETS): Add org.dvi. + (maintainer-clean): Remove the info files in the info dir. + + * misc.texi (Term Mode): Correcty describe C-c. + + * custom.texi (Easy Customization): Move up to section level, + before Variables. Avoid using the term "variable"; say "option". + New initial explanation. + (Variables): In initial explanation, connect "variable" to the + already-explained "user option". + + * emacs.texi (Top): Fix ref to Command Line. + Move reference to Easy Customization. + + * xresources.texi (X Resources): Fix From link. + + * doclicense.texi (GNU Free Documentation License): Fix To link. + + * entering.texi (Entering Emacs): Fix xref, now to Command Line. + + * cmdargs.texi (Command Line): Node renamed from Command Arguments. + +2004-12-03 Richard M. Stallman <rms@gnu.org> + + * cmdargs.texi (Initial Options): Clarify batch mode i/o. + +2004-12-01 Luc Teirlinck <teirllm@auburn.edu> + + * kmacro.texi: Several small changes in addition to the following. + (Keyboard Macro Ring): Describe behavior of `C-x C-k C-k' when + defining a keyboard macro. + Mention `kmacro-ring-max'. + (Keyboard Macro Counter): Clarify description of + `kmacro-insert-counter', `kmacro-set-counter', + `kmacro-add-counter' and `kmacro-set-format'. + +2004-11-29 Reiner Steib <Reiner.Steib@gmx.de> + + * custom.texi (File Variables): Add `unibyte' and make it more + clear that `unibyte' and `coding' are special. Suggested by Simon + Krahnke <overlord@gmx.li>. + + * mule.texi (Enabling Multibyte): Refer to File Variables. + Suggested by Simon Krahnke <overlord@gmx.li>. + +2004-11-26 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * frames.texi (Dialog Boxes): Rename use-old-gtk-file-dialog to + x-use-old-gtk-file-dialog. + +2004-11-26 Eli Zaretskii <eliz@gnu.org> + + * idlwave.texi: Fix the setfilename directive to put the produced + file in ../info. + (Continued Statement Indentation): Resurrect Jan D.'s change from + 2004-11-03 that was lost when a newer version of idlwave.texi was + imported. + +2004-11-20 Richard M. Stallman <rms@gnu.org> + + * text.texi (Fill Prefix): M-q doesn't apply fill prefix to first line. + +2004-11-09 Lars Brinkhoff <lars@nocrew.org> + + * building.texi (Lisp Eval): Delete hyphen in section name. + +2004-11-19 Thien-Thi Nguyen <ttn@gnu.org> + + * files.texi (Old Versions): + No longer document annotation as "CVS only". + +2004-11-10 Andre Spiegel <spiegel@gnu.org> + + * files.texi (Version Control): Rewrite the introduction about + version systems, mentioning the new ones that we support. Thanks + to Alex Ott, Karl Fogel, Stefan Monnier, and David Kastrup for + suggestions. + +2004-12-08 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus-faq.texi ([5.1]): Added missing bracket. + + * gnus.texi (Filtering Spam Using The Spam ELisp Package): Index + `spam-initialize'. + +2004-11-22 Reiner Steib <Reiner.Steib@gmx.de> + + * message.texi (Various Message Variables): Mention that all mail + file variables are derived from `message-directory'. + + * gnus.texi (Splitting Mail): Clarify bogus group. + +2004-11-02 Katsumi Yamaoka <yamaoka@jpl.org> + + * emacs-mime.texi (Encoding Customization): Fix + mm-coding-system-priorities entry. + +2004-11-03 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * frames.texi (Dialog Boxes): + * idlwave.texi (Continued Statement Indentation): + * reftex.texi (Options (Index Support)): + (Displaying and Editing the Index, Table of Contents): + * speedbar.texi (Creating a display, Major Display Modes): Replace + non-nil with non-@code{nil}. + +2004-11-02 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * frames.texi (Dialog Boxes): Document use-old-gtk-file-dialog. + +2004-10-23 Eli Zaretskii <eliz@gnu.org> + + * text.texi (Text Based Tables, Table Definition) + (Table Creation, Table Recognition, Cell Commands) + (Cell Justification, Row Commands, Column Commands) + (Fixed Width Mode, Table Conversion, Measuring Tables) + (Table Misc): New nodes, documenting the Table Mode. + +2004-10-21 Jay Belanger <belanger@truman.edu> + + * calc.texi (Algebraic-Style Calculations): Removed a comment. + +2004-10-19 Jason Rumney <jasonr@gnu.org> + + * makefile.w32-in (info): Change order of arguments to makeinfo. + +2004-10-19 Ulf Jasper <ulf.jasper@web.de> + + * calendar.texi (iCalendar): Update for package changes. + +2004-10-18 Luc Teirlinck <teirllm@auburn.edu> + + * calc.texi (Reporting Bugs): Double up `@'. + +2004-10-18 Jay Belanger <belanger@truman.edu> + + * calc.texi (Reporting Bugs): Changed the address that bugs + should be sent to. + +2004-10-15 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (New Features): Add 5.11. + + * message.texi (Resending): Remove wrong default value. + + * gnus.texi (Mail Source Specifiers): Describe possible problems + of `pop3-leave-mail-on-server'. Add `pop3-movemail' and + `pop3-leave-mail-on-server' to the index. + +2004-10-15 Katsumi Yamaoka <yamaoka@jpl.org> + + * message.texi (Canceling News): Add how to set a password. + +2004-10-12 Jay Belanger <belanger@truman.edu> + + * calc.texi (Help Commands): Changed the descriptions of + calc-describe-function and calc-describe-variable to match their + current behavior. + +2004-10-12 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus-faq.texi ([5.9]): Improve code for reply-in-news. + +2004-10-12 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.0.45. + + * tramp.texi (Frequently Asked Questions): Comment paragraph about + plink link. The URL is outdated. Originator contacted for + clarification. + +2004-10-10 Juri Linkov <juri@jurta.org> + + * gnus.texi (Top, Marking Articles): Join two menus in one node + because a node can have only one menu. + +2004-10-09 Luc Teirlinck <teirllm@auburn.edu> + + * files.texi (Misc File Ops): View mode is a minor mode. + +2004-10-09 Juri Linkov <juri@jurta.org> + + * gnus.texi (Fancy Mail Splitting): Remove backslash in the + example of nnmail-split-fancy. + +2004-10-08 Glenn Morris <gmorris@ast.cam.ac.uk> + + * calendar.texi (iCalendar): Style changes. + +2004-10-07 Luc Teirlinck <teirllm@auburn.edu> + + * search.texi (Regexps): The regexp described in the example is no + longer stored in the variable `sentence-end'. + +2004-10-06 Karl Berry <karl@gnu.org> + + * info.texi (@kbd{1}--@kbd{9}): No space around --, for + consistency with other uses of dashes. + +2004-10-06 Nick Roberts <nickrob@snap.net.nz> + + * building.texi (Starting GUD): Note that multiple debugging + sessions requires `gdb --fullname'. + +2004-10-05 Ulf Jasper <ulf.jasper@web.de> + + * calendar.texi (iCalendar): New section for a new package. + +2004-10-05 Karl Berry <karl@gnu.org> + + * info.texi: Consistently use --- throughout, periods at end of + menu descriptions, and a couple typos. + +2004-10-05 Luc Teirlinck <teirllm@auburn.edu> + + * text.texi: Various small changes in addition to the following. + (Text): Replace xref for autotype with inforef. + (Sentences): Explain nil value for `sentence-end'. + (Paragraphs): Update default values for `paragraph-start' and + `paragraph-separate'. + (Text Mode): Correct description of Text mode's effect on the + syntax table. + (Outline Visibility): `hide-other' does not hide top level headings. + `selective-display-ellipses' no longer has an effect on Outline mode. + (TeX Misc): Add missing @cindex. + Replace xref for RefTeX with inforef. + (Requesting Formatted Text): The variable + `enriched-fill-after-visiting' no longer exists. + (Editing Format Info): Update names of menu items and commands. + (Format Faces): Mention special effect of specifying the default face. + Describe inheritance of text properties. + Correct description of `fixed' face. + (Format Indentation): Correct description of effect of setting + margins. Mention `set-left-margin' and `set-right-margin'. + (Format Justification): Update names of menu items. + `set-justification-full' is now bound to `M-j b'. + Mention that `default-justification' is a per buffer variable. + (Format Properties): Update name of menu item. + (Forcing Enriched Mode): `format-decode-buffer' automatically + turns on Enriched mode if the buffer is in text/enriched format. + +2004-10-05 Emilio C. Lopes <eclig@gmx.net> + + * calendar.texi (From Other Calendar): Add calendar-goto-iso-week. + +2004-09-28 Kim F. Storm <storm@cua.dk> + + * display.texi (Display Custom) <indicate-buffer-boundaries>: + Align with new functionality. + +2004-09-26 Jesper Harder <harder@ifa.au.dk> + + * sieve.texi (Manage Sieve API): nil -> @code{nil}. + * pgg.texi (User Commands, Backend methods): Do. + * gnus.texi: Markup fixes. + (Setting Process Marks): Fix `M P a' entry. + * emacs-mime.texi: Fixes. + +2004-09-23 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus-faq.texi ([5.12]): Fix code example for FQDN in Message-Ids + again. + Use 5.10 instead of 5.10.0. + +2004-09-20 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * gnus.texi (Summary Mail Commands): S D e. + +2004-09-20 Raymond Scholz <ray-2004@zonix.de> (tiny change) + + * gnus.texi (Misc Article): Refer to `Summary Buffer Mode Line' in + the gnus-article-mode-line-format section. + +2004-09-20 Helmut Waitzmann <Helmut.Waitzmann@web.de> (tiny change) + + * gnus.texi (Various Summary Stuff): Fix the documentation for + gnus-newsgroup-variables. + +2004-09-20 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (MIME Commands): Added + gnus-mime-display-multipart-as-mixed, + gnus-mime-display-multipart-alternative-as-mixed, + gnus-mime-display-multipart-related-as-mixed. + (Mail Source Customization): Clarify `mail-source-directory'. + (Splitting Mail): Mention gnus-group-find-new-groups. + (SpamOracle): Fixed typo. + + * gnus-faq.texi: Untabify. + ([6.3]): nnir.el is in contrib directory. + + * message.texi (News Headers): Clarify how a unique ID is created. + + * gnus.texi (Batching Agents): Fixed typo in example. Reported + by Hiroshi Fujishima <pooh@nature.tsukuba.ac.jp>. + +2004-09-20 Andre Srinivasan <andre@e2open.com> + + * gnus.texi (Group Parameters): Added more on hooks. (Small + change.) + +2004-09-20 Florian Weimer <fw@deneb.enyo.de> + + * gnus.texi (Charsets): Point to relevant section in emacs-mime. + +2004-09-22 Luc Teirlinck <teirllm@auburn.edu> + + * display.texi (Display Custom): Remove stray `@end defvar'. + +2004-09-23 Kim F. Storm <storm@cua.dk> + + * display.texi (Display Custom): Add `overflow-newline-into-fringe', + `indicate-buffer-boundaries' and `default-indicate-buffer-boundaries'. + +2004-09-22 Jay Belanger <belanger@truman.edu> + + * calc.texi (Vectors as Lists): Added a warning that the tutorial + might be hidden during part of the session. + +2004-09-20 Jay Belanger <belanger@truman.edu> + + * calc.texi (Notations Used in This Manual): Put in an earlier + mention that DEL could be called Backspace. + +2004-09-20 Richard M. Stallman <rms@gnu.org> + + * custom.texi (Hooks): Explain using setq to clear out a hook. + (File Variables): Explain multiline string constants. + (Non-ASCII Rebinding): Explain when you need to update + non-ASCII char codes in .emacs. + + * building.texi (Compilation): Explain how to make a silent + subprocess that won't be terminated. Explain compilation-environment. + +2004-09-13 Kim F. Storm <storm@cua.dk> + + * mini.texi (Repetition): Rename isearch-resume-enabled to + isearch-resume-in-command-history and change default to disabled. + +2004-09-10 Simon Josefsson <jas@extundo.com> + + * gnus.texi (IMAP): Add example. Suggested and partially written + by Steinar Bang <sb@dod.no>. + +2004-09-10 Teodor Zlatanov <tzz@lifelogs.com> + + * gnus.texi (IMAP): Add comments about imaps synonym to imap in + netrc syntax. + +2004-09-10 Teodor Zlatanov <tzz@lifelogs.com> + + * gnus.texi (Spam ELisp Package Sequence of Events): Some clarifications. + (Spam ELisp Package Global Variables): More clarifications. + +2004-09-10 Teodor Zlatanov <tzz@lifelogs.com> + + * gnus.texi (Spam ELisp Package Filtering of Incoming Mail): + Mention spam-split does not modify incoming mail. + +2004-09-10 Teodor Zlatanov <tzz@lifelogs.com> + + * gnus.texi (Spam ELisp Package Sequence of Events): Fix typo. + +2004-09-10 Eli Zaretskii <eliz@gnu.org> + + * Makefile.in (../info/gnus, gnus.dvi): Depend on gnus-faq.texi. + +2004-09-09 Kim F. Storm <storm@cua.dk> + + * kmacro.texi (Save Keyboard Macro): Replace `name-last-kbd-macro' + with new `kmacro-name-last-macro'. + +2004-09-09 Reiner Steib <Reiner.Steib@gmx.de> + + * makefile.w32-in (sieve, pgg): Use $(infodir). + +2004-09-08 Juri Linkov <juri@jurta.org> + + * mini.texi (Minibuffer History): Add `history-delete-duplicates'. + +2004-09-08 Dhruva Krishnamurthy <dhruva.krishnamurthy@gmail.com> (tiny change) + + * makefile.w32-in: Fix PGG and Sieve entries. + +2004-09-03 Juri Linkov <juri@jurta.org> + + * search.texi (Incremental Search): Update wording for M-%. + +2004-09-02 Luc Teirlinck <teirllm@auburn.edu> + + * killing.texi (Killing): Correct description of kill commands in + read-only buffer. + +2004-09-02 Teodor Zlatanov <tzz@lifelogs.com> + + * building.texi (Compilation Mode): Add a paragraph about rules + for finding the compilation buffer for `next-error'. + + * search.texi (Other Repeating Search): Mention that Occur mode + supports the next-error functionality. + +2004-09-02 Juri Linkov <juri@jurta.org> + + * search.texi (Regexp Replace): Add missing backslash to \footnote. + +2004-08-31 Luc Teirlinck <teirllm@auburn.edu> + + * kmacro.texi (Basic Keyboard Macro): + `apply-macro-to-region-lines' now operates on all lines that begin + in the region, rather than on all complete lines in the region. + +2004-08-31 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * frames.texi (Drag and drop): Add documentation about + x-dnd-test-function and x-dnd-known-types. + +2004-08-30 Luc Teirlinck <teirllm@auburn.edu> + + * indent.texi: Various minor changes in addition to: + (Indentation Commands): Correct description of `indent-relative'. + (Tab Stops): <TAB> is no longer bound to `tab-to-tab-stop' in Text + mode. The *Tab Stops* buffer uses Overwrite Mode. + (Just Spaces): `tabify' converts sequences of at least two spaces + to tabs. + +2004-08-28 Eli Zaretskii <eliz@gnu.org> + + * faq.texi (Emacs for MS-DOS): Update URLs for the MS-DOS port of + Emacs and related programs. + +2004-08-27 Luc Teirlinck <teirllm@auburn.edu> + + * frames.texi (Secondary Selection): Setting the secondary + selection with M-Drag-Mouse-1 does not alter the kill ring, + setting it with M-Mouse-1 and M-Mouse-3 does. + (Mode Line Mouse): C-Mouse-2 on scroll bar now also works for + toolkit scroll bars. + (Scroll Bars): Ditto. + + * windows.texi (Basic Window): When using a window system, the value + of point in a non-selected window is indicated by a hollow box. + (Split Window): Side by side windows are separated by a scroll bar, + if scroll bars are used. + C-Mouse-2 on scroll bar now also works for toolkit scroll bars. + (Change Window): Correct Mouse-2 vs Mouse-3 mess-up. + (Window Convenience): Update bindings for `winner-undo' and + `winner-redo'. + + * ack.texi (Acknowledgments): Use `@unnumbered'. + * misc.texi : Adapt sectioning in Info to the node structure. + (Invoking emacsclient): Make "Invoking emacsclient" a subsection + of "Using Emacs as a Server". + * building.texi (Building): Interchange nodes (for correct numbering). + * programs.texi (Programs): Interchange nodes (for correct numbering). + * killing.texi, entering.texi, commands.texi: Adapt sectioning in + Info to the node structure. + * emacs.texi: Make "GNU GENERAL PUBLIC LICENSE" an appendix. + Rearrange order of nodes and sections such that both "GNU GENERAL + PUBLIC LICENSE" and "GNU Free Documentation License" appear at the + end, as appropriate for appendices. + (Acknowledgments): Put inside @iftex instead of @ifnotinfo. + Use `@unnumberedsec'. + * trouble.texi: Adapt sectioning in Info to the node structure. + Adapt node pointers to change in emacs.texi. + * cmdargs.texi, doclicense.texi: Adapt node pointers. + +2004-08-27 Richard M. Stallman <rms@gnu.org> + + * faq.texi: Fix texinfo usage, esp. doublequotes. + (Difference between Emacs and XEmacs): Some clarification. + + * faq.texi (Difference between Emacs and XEmacs): + Explain not to contrast XEmacs with GNU Emacs. + +2004-08-26 Richard M. Stallman <rms@gnu.org> + + * faq.texi (Difference between Emacs and XEmacs): Rewrite. + +2004-08-25 Kenichi Handa <handa@m17n.org> + + * custom.texi (Non-ASCII Rebinding): Fix and simplify the + description for unibyte mode. + +2004-08-23 Luc Teirlinck <teirllm@auburn.edu> + + * display.texi (Font Lock): Correct invalid (for hardcopy) @xref. + + * search.texi (Regexps): Correct cryptic (in hardcopy) @ref. + (Configuring Scrolling): Correct invalid (for hardcopy) @xref. + (Regexp Replace): Standardize reference to hardcopy Elisp Manual + in @pxref. + +2004-08-22 Luc Teirlinck <teirllm@auburn.edu> + + * kmacro.texi (Keyboard Macro Counter, Keyboard Macro Step-Edit): + Change section names. + +2004-08-22 David Kastrup <dak@gnu.org> + + * reftex.texi (AUCTeX): Update links, section name. + + * faq.texi (Calc): Update availability (included in 22.1). + (AUCTeX): Update availability, information, versions, description. + +2004-08-21 Luc Teirlinck <teirllm@auburn.edu> + + * kmacro.texi (Keyboard Macro Ring): Rename section. + Emacs treats the head of the macro ring as the `last keyboard macro'. + (Keyboard Macro Counter): Minor change. + (Save Keyboard Macro): Some clarifications. + (Edit Keyboard Macro): Rename section. + + * buffers.texi (Buffers): Maximum buffer size is now 256M on + 32-bit machines. + (Several Buffers): Clarify which buffer is selected if `2' is + pressed in the Buffer Menu. + Auto Revert mode can be used to update the Buffer Menu + automatically. + +2004-08-21 Eli Zaretskii <eliz@gnu.org> + + * help.texi (Misc Help): Add an index entry for finding an Info + manual by its file name. + +2004-08-20 Luc Teirlinck <teirllm@auburn.edu> + + * files.texi (Backup Deletion): Correct description of + `delete-old-versions'. + (Time Stamps): `time-stamp' needs to be added to `before-save-hook'. + (Auto Save Files): Recommend `auto-save-mode' to reenable + auto-saving, rather than the abbreviation `auto-save'. + +2004-08-17 Luc Teirlinck <teirllm@auburn.edu> + + * emacs.texi (Top): Mention "cutting" and "pasting" as synonyms + for "killing" and "yanking" in main menu. + +2004-08-16 Richard M. Stallman <rms@gnu.org> + + * killing.texi (Yanking, Killing): Minor cleanups. + + * mark.texi (Momentary Mark): Minor cleanups. + +2004-08-15 Kenichi Handa <handa@etl.go.jp> + + * custom.texi (Non-ASCII Rebinding): + C-q always inserts the right code to pass to global-set-key. + +2004-08-14 Eli Zaretskii <eliz@gnu.org> + + * Makefile.in (../info/tramp, tramp.dvi): Depend on trampver.texi. + +2004-08-13 Luc Teirlinck <teirllm@auburn.edu> + + * regs.texi (RegNumbers): Mention `C-x r i' binding for + `insert-register', instead of `C-x r g' binding, for consistency. + +2004-08-12 Luc Teirlinck <teirllm@auburn.edu> + + * fixit.texi (Spelling): Fix typo. + +2004-08-11 Luc Teirlinck <teirllm@auburn.edu> + + * help.texi (Help): Fix Texinfo usage. + +2004-08-11 Martin Stjernholm <bug-cc-mode@gnu.org> + + * cc-mode.texi: Various updates for CC Mode 5.30.9. + +2004-08-10 Michael Albinus <michael.albinus@gmx.de> + + Sync with Tramp 2.0.44. + +2004-08-05 Lars Hansen <larsh@math.ku.dk> + + * widget.texi (User Interface): Update how to separate the + editable field of an editable-field widget from other widgets. + (Programming Example): Add text after field. + +2004-07-24 Richard M. Stallman <rms@gnu.org> + + * text.texi (Paragraphs): Update how paragraphs are separated + and the default for paragraph-separate. + + * search.texi (Regexp Replace): Further update text for new + replacement operators. + +2004-08-31 Katsumi Yamaoka <yamaoka@jpl.org> + + * emacs-mime.texi (Encoding Customization): Add a note to the + mm-content-transfer-encoding-defaults entry. + (rfc2047): Update. + + * gnus.texi (Article Highlighting): Add + gnus-cite-ignore-quoted-from. + (POP before SMTP): New node. + (Posting Styles): Addition. + (Splitting Mail): Add nnmail-split-lowercase-expanded. + (Fancy Mail Splitting): Ditto. + (X-Face): Add gnus-x-face. + +2004-08-30 Reiner Steib <Reiner.Steib@gmx.de> + + * emacs-mime.texi, gnus-faq.texi, gnus.texi, message.texi, + * pgg.texi, sieve.texi: Use @copying and @insertcopying. + +2004-08-22 Reiner Steib <Reiner.Steib@gmx.de> + + * gnus.texi (Mail Source Specifiers): Describe + `pop3-leave-mail-on-server'. + +2004-08-02 Reiner Steib <Reiner.Steib@gmx.de> + + * Makefile.in, makefile.w32-in: Added PGG and Sieve files. + + * pgg.texi, sieve.texi: Import from the v5_10 branch of the Gnus + repository. Change setfilename. + + * emacs-mime.texi, gnus-faq.texi, gnus.texi, message.texi: Ditto. + +2004-07-18 Luc Teirlinck <teirllm@auburn.edu> + + * emacs-xtra.texi (Subdir switches): Dired does not remember the + `R' switch. + + * dired.texi (Dired Updating): `k' only deletes inserted + subdirectories from the Dired buffer if a prefix argument was given. + + * search.texi (Regexps): Delete redundant definition of `symbol' in + description of `\_>'. It already occurs in the description of `\_<'. + +2004-07-02 Juri Linkov <juri@jurta.org> + + * pcl-cvs.texi (Viewing differences): Add `d r'. + +2004-07-01 Juri Linkov <juri@jurta.org> + + * search.texi (Incremental Search): Add C-M-w, C-M-y, M-%, C-M-%, M-e. + (Regexp Search): Add M-r. + +2004-06-30 Luc Teirlinck <teirllm@auburn.edu> + + * makefile.w32-in (EMACSSOURCES): Remove emacs-xtra. + +2004-06-29 Jesper Harder <harder@ifa.au.dk> + + * ses.texi, viper.texi, search.texi, flymake.texi, faq.texi: + * eshell.texi, ediff.texi, calendar.texi: Markup fixes. + +2004-06-25 Richard M. Stallman <rms@gnu.org> + + * search.texi (Regexp Replace): Rewrite description of \# \, and \?. + +2004-06-25 David Kastrup <dak@gnu.org> + + * search.texi (Regexp Replace): Some typo corrections and + rearrangement. + +2004-06-24 David Kastrup <dak@gnu.org> + + * search.texi (Unconditional Replace): Use replace-string instead + of query-replace in example. + (Regexp Replace): Add explanations for `\,', `\#' and `\?' + sequences. + (Query Replace): Correct explanation of `^' which does not use + the mark stack. + +2004-06-21 Nick Roberts <nickrob@gnu.org> + + * misc.texi (Shell History Copying): Document comint-insert-input. + (Shell Ring): Describe comint-dynamic-list-input-ring here. + +2004-06-21 Karl Berry <karl@gnu.org> + + * info.texi (Top): Mention that only Emacs has mouse support. + (Getting Started): Mention this in a few other places. + +2004-06-20 Jesper Harder <harder@ifa.au.dk> + + * msdog.texi (Text and Binary, MS-DOS Printing): Use m-dash. + * custom.texi (Customization): Do. + * anti.texi (Antinews): Do. + * abbrevs.texi (Defining Abbrevs): Do. + + * programs.texi (Info Lookup): Fix keybinding for + info-lookup-symbol. + +2004-06-16 Juanma Barranquero <lektu@terra.es> + + * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, EMACSSOURCES): + Add emacs-xtra. + ($(infodir)/emacs-xtra, emacs-xtra.dvi): New dependencies. + (clean): Add emacs-xtra and flymake. Remove redundancies. + +2004-06-15 Luc Teirlinck <teirllm@auburn.edu> + + * Makefile.in (INFO_TARGETS, DVI_TARGETS, ../info/emacs-xtra): + Add emacs-xtra. + * emacs-xtra.texi: New file. + +2004-06-14 Luc Teirlinck <teirllm@auburn.edu> + + * dired.texi (Dired Enter): Mention conditions on `ls' switches. + (Dired and Find): Mention differences with ordinary Dired buffers. + +2004-06-13 Luc Teirlinck <teirllm@auburn.edu> + + * autotype.texi (Copyrights, Timestamps): Recommend + `before-save-hook' instead of `write-file-functions'. + +2004-06-13 Richard M. Stallman <rms@gnu.org> + + * custom.texi (Init Syntax): Explain about vars that do special + things when set with setq or with Custom. + (Init Examples): Add line-number-mode example. + +2004-06-13 Lars Hansen <larsh@math.ku.dk> + + * dired-x.texi (dired-mark-omitted): Update keybinding. + +2004-06-12 Juri Linkov <juri@jurta.org> + + * dired.texi (Operating on Files): Add dired-do-touch. + +2004-06-10 Kim F. Storm <storm@cua.dk> + + * pcl-cvs.texi (Viewing differences): Add 'd y'. + +2004-06-10 Juri Linkov <juri@jurta.org> + + * building.texi (Lisp Eval): Add C-M-x on defface. + +2004-06-08 Luc Teirlinck <teirllm@auburn.edu> + + * files.texi (Reverting): Auto-Revert mode and + Global Auto-Revert mode no longer revert remote files. + +2004-06-05 Lars Hansen <larsh@math.ku.dk> + + * dired-x.texi (variable dired-omit-mode): Rename from + dired-omit-files-p. + (function dired-omit-mode): Rename from dired-omit-toggle. + Call dired-omit-mode rather than set dired-omit-files-p. + (dired-mark-omitted): Describe command. + +2004-05-29 Michael Albinus <michael.albinus@gmx.de> + + Version 2.0.41 of Tramp released. + +2004-05-29 Juanma Barranquero <lektu@terra.es> + + * makefile.w32-in (../info/flymake, flymake.dvi): New targets. + (INFO_TARGETS, DVI_TARGETS): Add Flymake. + +2004-05-29 Richard M. Stallman <rms@gnu.org> + + * custom.texi (Init File): Two dashes start --no-site-file. + + * cl.texi (Top): Call this chapter `Introduction'. + (Overview): In TeX, no section heading here. + + * cc-mode.texi: Put commas after i.e. and e.g. Minor cleanups. + +2004-05-29 Alan Mackenzie <acm@muc.de> + + * programs.texi: Update for CC Mode 5.30 and incidental amendments. + ("AWK"): Is consistently thus spelt throughout. + (AWK, Pike): Document as "C-like modes". + (@kbd{M-j}): Document as alternative to @kbd{C-M-j}. + (M-x man): Supersedes M-x manual-entry. + Add numerous index entries. Correct "ESC a/e" to "M-a/e". + + ("Comments in C"): Delete node; the info is in CC Mode manual. + (c-comment-only-line-offset): Remove description. + + (C-c ., C-c C-c): Describe new C Mode bindings. + + (C-u TAB, indent-code-rigidly, c-indent-exp, c-tab-always-indent) + (@dfn{Style}, c-default-style, comment-column, comment-padding) + (c-up-conditional, c-beginning-of-statement, c-end-of-statement): + Amend definitions. + + (c-beginning-of-defun, c-end-of-defun, c-context-line-break): + Describe functions. + + (c-comment-start-regexp, c-hanging-comment-ender-p) + (c-hanging-comment-starter-p): Remove obsolete definitions. + + * emacs.texi: Remove the menu entry "Comments in C". + +2004-05-29 Eli Zaretskii <eliz@gnu.org> + + * Makefile.in (../info/flymake, flymake.dvi): New targets. + (INFO_TARGETS, DVI_TARGETS): Add Flymake. + +2004-05-29 Pavel Kobiakov <pk_at_work@yahoo.com> + + * flymake.texi: New file. + +2004-05-28 Simon Josefsson <jas@extundo.com> + + * smtpmail.texi (Authentication): Improve STARTTLS discussion. + +2004-05-27 Luc Teirlinck <teirllm@auburn.edu> + + * dired.texi (Dired and Find): `find-ls-option' does not apply to + `M-x locate'. + +2004-05-16 Karl Berry <karl@gnu.org> + + * emacs.texi (ack.texi) [@ifnottex]: Change condition; with @ifinfo, + makeinfo --html fails. + * help.texi (Help Summary) [@ifnottex]: Likewise. + +2004-05-13 Nick Roberts <nickrob@gnu.org> + + * building.texi (GDB Graphical Interface): Update and describe + layout first. + +2004-05-07 Kai Grossjohann <kai@emptydomain.de> + + Version 2.0.40 of Tramp released. + +2004-04-25 Michael Albinus <Michael.Albinus@alcatel.de> + + Complete rework, based on review by Karl Berry <karl@gnu.org>. + + * tramp.texi (Auto-save and Backup): Explain exploitation of new + variables `tramp-backup-directory-alist' and + `tramp-bkup-backup-directory-info'. + (Overview, Connection types) + (External transfer methods, Default Method) + (Windows setup hints): Remove restriction of password entering + with external methods. + (Auto-save and Backup): Make file name example + (X)Emacs neutral. In case of XEmacs, `bkup-backup-directory-info' + and `auto-save-directory' must be used. + (Frequently Asked Questions): Use "MS Windows NT/2000/XP" (not + only "NT"). Remove doubled entry "What kinds of systems does + @tramp{} work on". + (tramp): Macro removed. + (Obtaining Tramp): Flag removed from title. + (all): "tramp-" and "-" removed from flag names. Flags `tramp' + and `trampver' used properly. Flag `tramp-inst' replaced by + `installchapter'. Installation related text adapted. + +2004-05-04 Jason Rumney <jasonr@gnu.org> + + * makefile.w32-in: Revert last change. + +2004-05-03 Jason Rumney <jasonr@gnu.org> + + * makefile.w32-in (MULTI_INSTALL_INFO, ENVADD): Use forward slashes. + +2004-04-28 Masatake YAMATO <jet@gyve.org> + + * widget.texi (Programming Example): Remove overlays. + +2004-04-27 Jesper Harder <harder@ifa.au.dk> + + * faq.texi, viper.texi, dired-x.texi, autotype.texi: lisp -> Lisp. + +2004-04-23 Juanma Barranquero <lektu@terra.es> + + * makefile.w32-in: Add "-*- makefile -*-" mode tag. + +2004-04-18 Juri Linkov <juri@jurta.org> + + * fixit.texi (Spelling): Remove file extension from ispell xref. + +2004-04-15 Kim F. Storm <storm@cua.dk> + + * cmdargs.texi (Initial Options): Add -Q. + +2004-04-05 Kim F. Storm <storm@cua.dk> + + * custom.texi (File Variables): Add safe-local-eval-forms. + +2004-04-05 Jesper Harder <harder@ifa.au.dk> + + * info.texi (Info Search): Add info-apropos. + +2004-04-02 Luc Teirlinck <teirllm@auburn.edu> + + * files.texi (Reverting): Correct description of revert-buffer's + handling of point. + +2004-03-22 Juri Linkov <juri@jurta.org> + + * emacs.texi (Top): Add `Misc X'. + + * faq.texi, trouble.texi: Fix help key bindings. + + * glossary.texi: Improve references. + + * help.texi: Sync keywords with finder.el. + + * mini.texi (Completion): Add description for menu items. + + * misc.texi (Browse-URL, FFAP): Add information about keywords. + + * sending.texi (Mail Methods): Fix xref to Message manual. + +2004-03-17 Luc Teirlinck <teirllm@auburn.edu> + + * info.texi (Advanced): Replace @unnumberedsubsec by @subheading + (as suggested by Karl Berry). Update information about colored + stars in menus. Add new subheading describing M-n. + +2004-03-12 Richard M. Stallman <rms@gnu.org> + + * cl.texi (Top): Rename top node's title. + + * buffers.texi (Misc Buffer): Add index entry for rename-uniquely. + +2004-03-08 Karl Berry <karl@gnu.org> + + * info.texi: \input texinfo.tex instead of just texinfo, to avoid + problems making the texinfo distribution. + +2004-03-04 Richard M. Stallman <rms@gnu.org> + + * search.texi (Regexps): Explain that ^ and $ have their + special meanings only in certain contexts. + + * programs.texi (Expressions): Doc C-M-SPC as alias for C-M-@. + + * mule.texi (Specify Coding): Doc C-x RET F. + + * buffers.texi (Misc Buffer): Explain use of M-x rename-uniquely + for multiple compile and grep buffers. + (Indirect Buffers): Don't recommand clone-indirect-buffer + for multiple compile and grep buffers. + +2004-02-29 Simon Josefsson <jas@extundo.com> + + * smtpmail.texi (Authentication): Changed the list of supported + authentication mechanisms from CRAM-MD5, PLAIN and LOGIN-MD5 to + CRAM-MD5 and LOGIN, tiny patch from Andreas Voegele + <voegelas@gmx.net>. + +2004-02-29 Juanma Barranquero <lektu@terra.es> + + * makefile.w32-in (mostlyclean, clean, maintainer-clean): + Use $(DEL) instead of rm, and ignore exit code. + +2004-02-29 Kai Grossjohann <kgrossjo@eu.uu.net> + + Tramp version 2.0.39 released. + +2004-02-29 Michael Albinus <Michael.Albinus@alcatel.de> + + * tramp.texi (Customizing Completion): Explain new functions + `tramp-parse-shostkeys' and `tramp-parse-sknownhosts'. + (all): Savannah URLs unified to "http://savannah.nongnu.org". + (Top): Refer to Savannah mailing list as the major one. Mention + older mailing lists in HTML mode only. + (Auto-save and Backup): Add auto-save. Based on wording of Kai. + (Frequently Asked Questions): Remote hosts must not be Unix-like + for "smb" method. + (Password caching): New node. + (External transfer methods): Refer to password caching for "smb" + method. + +2004-02-23 Nick Roberts <nick@nick.uklinux.net> + + * building.texi (Watch Expressions): Update. + +2004-02-21 Juri Linkov <juri@jurta.org> + + * cmdargs.texi (Action Arguments): Add alias --find-file. Add + --directory, --help, --version. Move text about command-line-args + to Command Arguments. + (Initial Options): Add @cindex for --script. Fix @cindex for -q. + Add --no-desktop. Add alias --no-multibyte, --no-unibyte. + (Window Size X): Join -g and --geometry. Add @cindex. + (Borders X): Fix @cindex for -ib. Add @cindex for -bw. + (Title X): Remove alias -title. + (Misc X): New node. + +2004-02-17 Karl Berry <karl@gnu.org> + + * info.texi (Help-Int): Mention the new line number feature. + +2004-02-15 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * frames.texi (Drag and drop): Add Motif to list of supported + protocols. + +2004-02-14 Jonathan Yavner <jyavner@member.fsf.org> + + * ses.texi (Advanced Features): New functionality for + ses-set-header-row (defaults to current row unless C-u used). + (Acknowledgements): Add Stefan Monnier. + +2004-02-03 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * frames.texi (Drag and drop): New section. + +2004-01-24 Richard M. Stallman <rms@gnu.org> + + * emacs.texi (Acknowledgments): Renamed from Acknowledgements. + Include it only @ifnotinfo. Patch the preceding and following + node headers to point to each other. + +2004-01-11 Glenn Morris <gmorris@ast.cam.ac.uk> + + * calendar.texi (Appointments): Update section. + +2003-12-29 Kevin Ryde <user42@zip.com.au> + + * viper.texi (Vi Macros): Fix reference to the Emacs manual. + + * programs.texi (C Modes): Fix the xref. + +2003-12-23 Nick Roberts <nick@nick.uklinux.net> + + * building.texi (Watch Expressions): Update. + (Commands of GUD): Include use of toolbar + breakpoints set from + fringe/margin. + +2003-12-03 Andre Spiegel <spiegel@gnu.org> + + * files.texi: Say how to disable VC. Suggested by Alan Mackenzie + <acm@muc.de>. + +2003-11-30 Kai Grossjohann <kai.grossjohann@gmx.net> + + Tramp version 2.0.38 released. + + * tramp.texi (Remote shell setup): Warn of environment variables + FRUMPLE if user frumple exists. Suggested by Sven Gabriel + <sven.gabriel@imk.fzk.de>. + (Configuration): Tramp now chooses base64/uuencode + automatically. Update wording accordingly. + (Top): More description for the `Default Method' menu entry. + (Default Method): Use @code, not @var, for Lisp variables. + (Default Method): New subsection `Which method is the right one + for me?' Suggested by Christian Kirsch. + (Configuration): Pointer to new subsection added. + (Default Method): Too many "use" in one sentence. + Rephrase. Reported by Christian Kirsch. + (Filename Syntax): Old `su' example is probably a left-over from + the sm/su method naming. Replace with `ssh', instead. + (External transfer methods, Auto-save and Backup): + Typo fixes. + +2003-11-02 Michael Albinus <Michael.Albinus@alcatel.de> + + * tramp.texi (all): Harmonize all occurences of @tramp{}. + (Top): Mention japanese manual only if flag `jamanual' is set. + Insert section `Japanese manual' in menu. + +2003-11-29 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * frames.texi (Dialog Boxes): Add use-file-dialog. + +2003-11-26 Thien-Thi Nguyen <ttn@gnu.org> + + * eshell.texi (Known Problems): Add doc item. + +2003-11-22 Martin Stjernholm <bug-cc-mode@gnu.org> + + * ack.texi: Note that Alan Mackenzie contributed the AWK support + in CC Mode. + +2003-11-22 Martin Stjernholm <bug-cc-mode@gnu.org> + + * cc-mode.texi: Update for CC Mode 5.30. + + Note: Please refrain from doing purely cosmetic changes like + removing trailing whitespace in this manual; it clobbers cvs + merging for no good reason. + +2003-11-02 Jesper Harder <harder@ifa.au.dk> (tiny change) + + * man/ack.texi, man/basic.texi, man/cmdargs.texi: + * man/commands.texi, man/custom.texi, man/display.texi: + * man/ediff.texi, man/emacs.texi, man/faq.texi, man/files.texi: + * man/frames.texi, man/glossary.texi, man/killing.texi: + * man/macos.texi, man/mark.texi, man/misc.texi, man/msdog.texi: + * man/mule.texi, man/rmail.texi, man/search.texi: + * man/sending.texi, man/text.texi, man/tramp.texi: + * man/trouble.texi, man/vip.texi, man/viper.texi, man/widget.texi: + * man/woman.texi: Replace @sc{ascii} and ASCII with @acronym{ASCII}. + +2003-11-01 Alan Mackenzie <acm@muc.de> + + * search.texi (Scrolling During Incremental Search): Document a + new scrolling facility in isearch mode. + +2003-10-26 Karl Berry <karl@gnu.org> + + * info.texi (Info Search): Echo area, not echo are. From Debian + diff. + +2003-10-26 Per Abrahamsen <abraham@dina.kvl.dk> + + * widget.texi (Defining New Widgets): Document new beavior of + :buttons and :children keywords. + +2003-10-22 Miles Bader <miles@gnu.org> + + * Makefile.in (info): Move before $(top_srcdir)/info. + +2003-10-22 Nick Roberts <nick@nick.uklinux.net> + + * building.texi (Watch Expressions): Update section on data display + to reflect code changes (GDB Graphical Interface). + +2003-10-17 Thien-Thi Nguyen <ttn@gnu.org> + + * tramp.texi (Inline methods): Small grammar fix. + (External transfer methods): Likewise. + +2003-10-13 Richard M. Stallman <rms@gnu.org> + + * xresources.texi (GTK resources): Clean up previous change. + +2003-10-12 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * xresources.texi (GTK resources): Add a note that some themes + disallow customizations. Add scroll theme example. + +2003-10-08 Nick Roberts <nick@nick.uklinux.net> + + * speedbar.texi: Remove paragraph for GUD that is no longer true. + +2003-10-06 Luc Teirlinck <teirllm@auburn.edu> + + * texinfo.tex: Replace `%' in arch tagline by @ignore. + +2003-09-30 Richard M. Stallman <rms@gnu.org> + + * dired-x.texi (Miscellaneous Commands): Delete M-g, w, T. + + * widget.texi (User Interface): Fix typos. + + * pcl-cvs.texi, cl.texi, woman.texi, ediff.texi: Fix @strong{Note:}. + + * cmdargs.texi (General Variables): Remove MAILRC envvar. + + * misc.texi (Saving Emacs Sessions): Shorten the section, + collapsing back into one node. + +2003-09-30 Lars Hansen <larsh@math.ku.dk> + + * misc.texi: Section "Saving Emacs Sessions" rewritten. + +2003-09-29 Jan Dj,Ad(Brv. <jan.h.d@swipnet.se> + + * xresources.texi (GTK names in Emacs): Correct typo. + +2003-09-29 Thien-Thi Nguyen <ttn@gnu.org> + + * pcl-cvs.texi (Selected Files): Fix typo. + +2003-09-24 Luc Teirlinck <teirllm@mail.auburn.edu> + + * cmdargs.texi (Font X): Mention new default font. More + fully describe long font names, wildcard patterns and the + problems involved. (Result of discussion on emacs-devel.) + +2003-09-22 Luc Teirlinck <teirllm@mail.auburn.edu> + + * emacs.texi (Acknowledgements): Correct typo. + +2003-09-22 Richard M. Stallman <rms@gnu.org> + + * dired.texi (Misc Dired Commands): New node. + (Dired Navigation): Add dired-goto-file. + + * files.texi (File Aliases, Misc File Ops): Add @cindex entries. + + * emacs.texi (Acknowledgements): New node, split from Distribution. + + * cmdargs.texi (Action Arguments): -f reads interactive args. + +2003-09-21 Karl Berry <karl@gnu.org> + + * info.texi (] and [ commands): No period at end of section title. + +2003-09-08 Lute Kamstra <lute@gnu.org> + + * screen.texi (Mode Line): Say that POS comes before LINE. + Mention `size-indication-mode'. + * display.texi (Optional Mode Line): Document + `size-indication-mode'. + * basic.texi (Position Info): Mention `size-indication-mode'. + +2003-09-07 Luc Teirlinck <teirllm@mail.auburn.edu> + + * xresources.texi (Resources): Refer to `editres' man page. + (Lucid Resources): Update defaults. Expand description of + `shadowThickness'. + +2003-09-04 Miles Bader <miles@gnu.org> + + * Makefile.in (top_srcdir): New variable. + ($(top_srcdir)/info): New rule. + (info): Depend on it. + +2003-09-03 Peter Runestig <peter@runestig.com> + + * makefile.w32-in: New file. + +2003-08-29 Richard M. Stallman <rms@gnu.org> + + * misc.texi (Saving Emacs Sessions): Correct previous change. + +2003-08-26 Per Abrahamsen <abraham@dina.kvl.dk> + + * widget.texi (User Interface): Explain the need of static text + around an editable field. + +2003-08-19 Luc Teirlinck <teirllm@mail.auburn.edu> + + * widget.texi (Basic Types): The argument to `:help-echo' can now + be a form that evaluates to a string. + + * emacs.texi (Top): Update menu to reflect new Keyboard Macros chapter. + (Intro): Include kmacro.texi after fixit.texi instead of after + custom.texi. (As suggested by Kim Storm.) + +2003-08-18 Luc Teirlinck <teirllm@mail.auburn.edu> + + * fixit.texi (Fixit): Update `Next' pointer. + * files.texi (Files): Update `Previous' pointer. + * kmacro.texi (Keyboard Macros): Remove redundant node and section. + * emacs.texi (Intro): Include kmacro.texi after custom.texi. + (Suggested by Kim Storm.) + * Makefile (EMACSSOURCES): Add kmacro.texi. (Suggested by Kim Storm.) + +2003-08-18 Kim F. Storm <storm@cua.dk> + + * kmacro.texi: New file describing enhanced keyboard macro + functionality. Replaces old description in custom.texi. + + * custom.texi (Customization): Add xref to Keyboard Macros chapter. + (Keyboard Macros): Move to new kmacro.texi file. + + * emacs.texi (Keyboard Macros): Reference new keyboard macro topics. + + * calc.texi (Queries in Macros): Update xref to keyboard macro query. + +2003-08-17 Edward M. Reingold <reingold@emr.cs.iit.edu> + + * calendar.texi (Specified Dates): Add `calendar-goto-day-of-year'. + +2003-08-17 Alex Schroeder <alex@gnu.org> + + * misc.texi (Saving Emacs Sessions): Manual M-x desktop-save not + required. + +2003-08-16 Richard M. Stallman <rms@gnu.org> + + * dired-x.texi (Shell Command Guessing): Explain *. + +2003-08-16 Chunyu Wang <spr@db.cs.hit.edu.cn> (tiny change) + + * pcl-cvs.texi (Log Edit Mode): Fix key binding for + log-edit-insert-changelog. + +2003-08-05 Richard M. Stallman <rms@gnu.org> + + * programs.texi (Lisp Indent): Don't describe + lisp-indent-function property here. Use xref to Lisp Manual. + +2003-08-03 Karl Berry <karl@gnu.org> + + * info.texi: Need @contents. + +2003-08-03 Glenn Morris <gmorris@ast.cam.ac.uk> + + * calendar.texi (Date Formats): Document changed behaviour of + abbreviations. + +2003-07-24 Markus Rost <rost@math.ohio-state.edu> + + * buffers.texi (List Buffers): Fix previous change. + +2003-07-20 Kai Gro,A_(Bjohann <kai.grossjohann@gmx.net> + + Tramp version 2.0.36 released. + + * tramp.texi (Remote shell setup): Explain about problems with + non-Bourne commands in ~/.profile and ~/.shrc. + +2003-07-13 Markus Rost <rost@math.ohio-state.edu> + + * buffers.texi (List Buffers): Adjust to new format of *Buffer + List*. + +2003-07-07 Luc Teirlinck <teirllm@mail.auburn.edu> + + * info.texi (Help-Inv, Help-M, Help-Xref): Update following + renaming of `vis-mode' to `visible-mode'. + + * display.texi (Font Lock): Fix typo. + +2003-07-07 Richard M. Stallman <rms@gnu.org> + + * display.texi (Font Lock): Add xref for format info on + font-lock-remove-keywords. + + * building.texi (Compilation): Document what happens with asynch + children of compiler process. + + * help.texi (Library Keywords): Use @multitable. + +2003-07-04 Luc Teirlinck <teirllm@mail.auburn.edu> + + * info.texi (Top, Help-Small-Screen): Remove accidentally added + next, prev and up pointers. + +2003-07-02 Luc Teirlinck <teirllm@mail.auburn.edu> + + * info.texi (Help): Mention existence of Emacs and stand-alone + Info at the very beginning of the tutorial. + (Help-Inv): New node. + (Help-]): New node. + (Help-M): Systematically point out the differences between default + Emacs and stand-alone versions. Delete second menu. + (Help-Xref): Systematically point out the differences between + default Emacs and stand-alone versions. + (Help-Int): Change `l' example. + (Expert Info): Fix typos. + (Emacs Info Variables): Mention `Info-hide-note-references' and + new default for `Info-scroll-prefer-subnodes'. + +2003-06-17 Kai Gro,A_(Bjohann <kai.grossjohann@gmx.net> + + Version 2.0.35 of Tramp released. + + * tramp.texi: From Michael Albinus <Michael.Albinus@alcatel.de>: + (Inline methods): Add methods `remsh' and `plink1'. + (External transfer methods): Add method `remcp'. + (Multi-hop Methods): Add method `remsh'. + Small patch from Adrian Aichner <adrian@xemacs.org>: + Fix minor typos. + (Concept Index): Added to make manual searchable via + `Info-index'. + (Version Control): Add cindex entry. + +2003-06-04 Richard M. Stallman <rms@gnu.org> + + * programs.texi (Expressions): Delete C-M-DEL. + + * misc.texi (Shell Options): Clarify comint-scroll-show-maximum-output. + comint-move-point-for-output renamed from + comint-scroll-to-bottom-on-output. + + * custom.texi (Init Rebinding): Replace previous change with xref. + (Non-ASCII Rebinding): Explain that issue more briefly here. + +2003-05-28 Richard M. Stallman <rms@gnu.org> + + * indent.texi (Indentation): Condense, simplify, clarify prev change. + +2003-05-28 Nick Roberts <nick@nick.uklinux.net> + + * building.texi (GDB Graphical Interface): New node. + (Rewritten somewhat by RMS.) + +2003-05-28 Kai Gro,A_(Bjohann <kai.grossjohann@gmx.net> + + * custom.texi (Init Rebinding): Xref Non-ASCII Rebinding, for + non-English letters. Explain how to set coding systems correctly + and how to include the right coding cookie in the file. + +2003-05-24 Kai Gro,A_(Bjohann <kai.grossjohann@gmx.net> + + * trampver.texi: Version 2.0.34 released. + +2003-05-22 Kai Gro,A_(Bjohann <kai.grossjohann@gmx.net> + + * indent.texi (Indentation): Explain the concepts. + (Just Spaces): Explain why preventing tabs for indentation might + be useful. + +2003-05-03 Glenn Morris <gmorris@ast.cam.ac.uk> + + * faq.texi: Improve previous changes. + +2003-05-02 Glenn Morris <gmorris@ast.cam.ac.uk> + + * faq.texi: Update copyright and maintenance details. + Update some package URLs, versions, and maintainers. + Remove many references to the Emacs Lisp Archive. + +2003-04-23 Simon Josefsson <jas@extundo.com> + + * smtpmail.texi: Fix license (the invariant sections mentioned has + never been part of the smtp manual). Align info dir entry with + other emacs packages. + +2003-04-16 Richard M. Stallman <rms@gnu.org> + + * search.texi (Regexps): Ref to Lisp manual for more regexp features. + +2003-04-08 Michael Albinus <Michael.Albinus@alcatel.de> + + * tramp.texi: Version 2.0.33 released. + Remove installation chapter. Remove XEmacs specifics. + +2003-03-29 Richard M. Stallman <rms@gnu.org> + + * tramp.texi (Top): Undo the previous renaming. + (emacs-other-name, emacs-other-dir, emacs-other-file-name): Delete. + +2003-03-29 Kai Gro,A_(Bjohann <kai.grossjohann@gmx.net> + + * Makefile.in (../info/tramp): Compile Emacs, instead of XEmacs, + version of manual. + + * tramp.texi (Auto-save and Backup): New node. + +2003-03-29 Michael Albinus <Michael.Albinus@alcatel.de> + + * tramp.texi (Top): Include trampver.texi. Rename "Emacs" to "GNU + Emacs" in order to have better differentiation to "XEmacs". + `emacs-other-name', `emacs-other-dir' and `emacs-other-file-name' + are new macros in order to point to the other Emacs flavor where + appropriate. In info case, point to node `Installation' in order + to explain how to generate the other way. In html case, make a + link to the other html file. + (Obtaining TRAMP): Added a paragraph saying to perform `autoconf' + after CVS checkout/update. + (Installation): Completely rewritten. + (Installation parameters, Load paths): New sections under + `Installation'. + +2003-02-28 Kai Gro,A_(Bjohann <kai.grossjohann@uni-duisburg.de> + + * tramp.texi: Version 2.0.30 released. + Replace word "path" with "localname" where used as a component of + a Tramp file name. + +2003-02-28 Michael Albinus <Michael.Albinus@alcatel.de> + + * tramp.texi (Frequently Asked Questions): `tramp-chunksize' + introduced. + (Installation): Explain what to do if files from the tramp/contrib + directory are needed. + +2003-02-23 Alex Schroeder <alex@emacswiki.org> + + * smtpmail.texi (How Mail Works): New. + +2003-02-22 Alex Schroeder <alex@emacswiki.org> + + * cmdargs.texi (General Variables): Document SMTPSERVER. + + * smtpmail.texi: New file. + + * sending.texi: Remove SMTP node. + (Mail Sending): Describe `send-mail-function'. Link to SMTP + library. + + * Makefile.in: Build SMTP manual. + +2003-02-22 Alex Schroeder <alex@emacswiki.org> + + * sending.texi (Sending via SMTP): Explain MTA/MUA. + +2003-02-22 Simon Josefsson <jas@extundo.com> + + * sending.texi (Mail Methods): Add node about SMTP. + +2003-02-17 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * xresources.texi (GTK names in Emacs): Add emacs-toolbar - GtkToolbar. + +2003-02-05 Kai Gro,A_(Bjohann <kai.grossjohann@uni-duisburg.de> + + * tramp.texi: Version 2.0.29 released. + (Installation): In Emacs, use M-x texinfo-format-buffer RET, not + M-x makeinfo-buffer RET. Reported by gebser@ameritech.net. + +2003-02-01 Michael Albinus <Michael.Albinus@alcatel.de> + + * tramp.texi (Frequently Asked Questions): Explain a workaround if + another package loads accidently Ange-FTP. + +2003-01-24 Michael Albinus <Michael.Albinus@alcatel.de> + + * tramp.texi (Customizing Completion): Add function + `tramp-parse-sconfig'. Change example of + `tramp-set-completion-function', because parsing of ssh config + files looks more natural. + +2003-02-01 Kevin Ryde <user42@zip.com.au> + + * glossary.texi (Glossary): Correction to cl cross reference. + +2003-01-20 Richard M. Stallman <rms@gnu.org> + + * killing.texi (Rectangles): Document C-x c r. + +2003-01-19 Jan Dj,Ad(Brv <jan.h.d@swipnet.se> + + * xresources.texi (GTK resources): New node. + (GTK widget names): New node. + (GTK names in Emacs): New node. + (GTK styles): New node. + +2003-01-15 ShengHuo ZHU <zsh@cs.rochester.edu> + + * gnus.texi: Do not use `path' in several locations. + +2003-01-09 Francesco Potort,Al(B <pot@gnu.org> + + * maintaining.texi (Create Tags Table): Add reference to the new + `etags --help --lang=LANG' option. + +2002-12-26 Kai Gro,A_(Bjohann <kai.grossjohann@uni-duisburg.de> + + * tramp.texi (External transfer methods): New method `smb'. From + Michael Albinus. + +2002-11-05 Karl Berry <karl@gnu.org> + + * info.texi (Info-fontify): Reorder face list to avoid bad line + breaks. + +2002-10-06 Kai Gro,A_(Bjohann <Kai.Grossjohann@CS.Uni-Dortmund.DE> + + * tramp.texi: Move @copying to standard place. Use + @insertcopying. + +2002-10-02 Karl Berry <karl@gnu.org> + + * (ada-mode.texi autotype.texi calc.texi cc-mode.texi cl.texi + dired-x.texi ebrowse.texi ediff.texi emacs-mime.texi emacs.texi + eshell.texi eudc.texi faq.texi forms.texi idlwave.texi info.texi + message.texi mh-e.texi pcl-cvs.texi reftex.texi sc.texi ses.texi + speedbar.texi vip.texi viper.texi widget.texi woman.texi): + Per rms, update all manuals to use @copying instead of @ifinfo. + Also use @ifnottex instead of @ifinfo around the top node, where + needed for the sake of the HTML output. + (The Gnus manual is not fixed since it's not clear to me how it + works; and the Tramp manual already uses @copying, although in an + unusual way. All others were changed.) + +2002-09-10 Jonathan Yavner <jyavner@engineer.com> + + * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add SES. + (../info/ses, ses.dvi): New targets. + * ses.texi: New file. + +2002-09-06 Pavel Jan,Am(Bk <Pavel@Janik.cz> + + * texinfo.tex: Update to texinfo 4.2. + +2002-08-27 Carsten Dominik <dominik@sand.science.uva.nl> + + * reftex.texi: Update to RefTeX 4.19. + +2002-06-17 Kai Gro,A_(Bjohann <Kai.Grossjohann@CS.Uni-Dortmund.DE> + + * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add Tramp. + (../info/tramp, tramp.dvi): New targets. + +2002-01-04 Eli Zaretskii <eliz@is.elta.co.il> + + * Makefile.in (DVI_TARGETS): Add calc.dvi. + (calc.dvi): Uncomment. + +2001-12-20 Eli Zaretskii <eliz@is.elta.co.il> + + * Makefile.in (EMACSSOURCES): Update the list of Emacs manual + source files. + +2001-11-16 Eli Zaretskii <eliz@is.elta.co.il> + + * Makefile.in (emacsman): New target. + +2001-11-07 Eli Zaretskii <eliz@is.elta.co.il> + + * Makefile.in (INFO_TARGETS): Add ../info/calc. + (../info/calc): New target. + +2001-10-20 Gerd Moellmann <gerd@gnu.org> + + * (Version 21.1 released.) + +2001-10-05 Gerd Moellmann <gerd@gnu.org> + + * Branch for 21.1. + +2001-04-14 Eli Zaretskii <eliz@is.elta.co.il> + + * Makefile.in (../info/info): Use an explicit -o switch to + makeinfo. + +2001-03-05 Gerd Moellmann <gerd@gnu.org> + + * Makefile.in (mostlyclean, maintainer-clean): Delete more files. + +2000-12-20 Eli Zaretskii <eliz@is.elta.co.il> + + * Makefile.in (../info/idlwave): Use --no-split. + +2000-12-14 Dave Love <fx@gnu.org> + + * Makefile.in (mostlyclean): Remove gnustmp.* + (gnus.dvi): Change rule to remove @latex stuff. + +2000-10-19 Eric M. Ludlam <zappo@ultranet.com> + + * Makefile.in (Speedbar): Add build targets for speedbar.texi. + +2000-10-13 John Wiegley <johnw@gnu.org> + + * Makefile.in: Add build targets for eshell.texi. + +2000-09-25 Gerd Moellmann <gerd@gnu.org> + + * Makefile.in: Remove/comment speedbar stuff. + +2000-09-22 Dave Love <fx@gnu.org> + + * Makefile.in: Add emacs-mime. + +2000-08-08 Eli Zaretskii <eliz@is.elta.co.il> + + * Makefile.in (INFO_TARGETS): Add ../info/woman. + (DVI_TARGETS): Add woman.dvi. + (../info/woman, woman.dvi): New targets. + +2000-05-31 Stefan Monnier <monnier@cs.yale.edu> + + * .cvsignore (*.tmp): New entry. Seems to be used for @macro. + + * pcl-cvs.texi: New file. + * Makefile.in (INFO_TARGETS, DVI_TARGETS: Add pcl-cvs. + (../info/pcl-cvs, pcl-cvs.dvi): New targets. + +2000-05-11 Gerd Moellmann <gerd@gnu.org> + + * Makefile.in (INFO_TARGETS): Add info/ebrowse. + (../info/ebrowse, ebrowse.dvi): New targets. + +2000-01-13 Gerd Moellmann <gerd@gnu.org> + + * Makefile.in (INFO_TARGETS): Add eudc. + (DVI_TARGETS): Add eudc.dvi. + (../info/eudc, eudc.dvi): New targets. + +2000-01-05 Eli Zaretskii <eliz@is.elta.co.il> + + * Makefile.in (INFO_TARGETS): Rename emacs-faq to efaq (for + compatibility with 8+3 filesystems). + (../info/efaq): Rename from emacs-faq. + +2000-01-03 Eli Zaretskii <eliz@is.elta.co.il> + + * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add idlwave. + (../info/idlwave, idlwave.dvi): New targets. + +1999-10-23 Dave Love <fx@gnu.org> + + * Makefile.in: Use autotype.texi. + +1999-10-12 Stefan Monnier <monnier@cs.yale.edu> + + * Makefile.in (faq): Use ../info/emacs-faq.info (as specified in the + faq.texi file) rather than ../info/faq. + +1999-10-07 Gerd Moellmann <gerd@gnu.org> + + * Makefile.in (INFO_TARGETS, DVI_TARGETS): Add ada-mode. + (../info/ada-mode, ada-mode.dvi): New targets. + +1999-09-01 Dave Love <fx@gnu.org> + + * Makefile.in: Add faq. + +1999-07-12 Richard Stallman <rms@gnu.org> + + * Version 20.4 released. + +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-08-19 Richard Stallman <rms@psilocin.ai.mit.edu> + + * Version 20.3 released. + +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: Update 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): Rename 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): Rename 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@stop.mail-abuse.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): Rename 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): Rename 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): Rename 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): Rename 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. + Add missing `@end iftex', fix 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: Update 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): Add gnus and sc. + (dvi): Add 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: Document next-line-add-lines variable used to + implement down-arrow. + + * killing.texi: Document kill-whole-line. + +1993-04-18 Noah Friedman (friedman@nutrimat.gnu.ai.mit.edu) + + * text.texi: Update unix TeX ordering information. + +1993-03-26 Eric S. Raymond (eric@geech.gnu.ai.mit.edu) + + * news.texi: Mention fill-rectangle in keybinding list. + + * killing.texi: Document fill-rectangle. + +1993-03-17 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) + + * vc.texi: Bring the docs up to date with VC 5.2. + +1992-01-10 Eric S. Raymond (eric@mole.gnu.ai.mit.edu) + + * emacs.tex: Mention blackbox and gomoku under Amusements. + Assembler mode is now mentioned and appropriately indexed + under Programming Modes. + +1991-02-15 Robert J. Chassell (bob@wookumz.ai.mit.edu) + + * emacs.tex: Update TeX ordering information. + +1990-08-30 David Lawrence (tale@pogo.ai.mit.edu) + + * gnus.texinfo: New file. Removed installation instructions. + +1990-06-26 David Lawrence (tale@geech) + + * emacs.tex: Note that completion-ignored-extensions is not used + to filter out names when all completions are displayed in + *Completions*. + +1990-05-25 Richard Stallman (rms@sugar-bombs.ai.mit.edu) + + * texindex.tex: If USG, include sys/types.h and sys/fcntl.h. + +1990-03-21 Jim Kingdon (kingdon@pogo.ai.mit.edu) + + * emacs.tex: Add @findex grep. + +1989-01-17 Robert J. Chassell (bob@rice-chex.ai.mit.edu) + + * texinfo.tex: Change spelling of `\sc' font to `\smallcaps' and + then define `\sc' as the command for smallcaps in Texinfo. This + means 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@frosted-flakes.ai.mit.edu) + + * emacs.tex: Correct two typos. No other changes before + Version 19 will be made. + + * vip.texinfo: Remove menu entry Adding Lisp Code in node + Customization since the menu entry did not point to anything. + Also add an @finalout command to remove overfull hboxes from the + printed output. + + * cl.texinfo: Add @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@frosted-flakes.ai.mit.edu) + + * texinfo.texinfo: Three typos corrected. + +1988-05-23 Robert J. Chassell (bob@frosted-flakes.ai.mit.edu) + + * emacs.tex: Update information for obtaining TeX distribution from the + University of Washington. + +;; Local Variables: +;; coding: iso-2022-7bit +;; fill-column: 79 +;; add-log-time-zone-rule: t +;; End: + + Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002, + 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. + + This file is part of GNU Emacs. + + GNU Emacs 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 3, or (at your option) + any later version. + + GNU Emacs 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 GNU Emacs; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. + +;;; arch-tag: f1d62776-3ed5-4811-9d96-267252577dbd diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in new file mode 100644 index 00000000000..00088b74b51 --- /dev/null +++ b/doc/emacs/Makefile.in @@ -0,0 +1,368 @@ +#### Makefile for the Emacs Manual and other documentation. + +# Copyright (C) 1994, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, +# 2004, 2005, 2006, 2007 Free Software Foundation, Inc. + +# This file is part of GNU Emacs. + +# GNU Emacs 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 3, or (at your option) +# any later version. + +# GNU Emacs 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 GNU Emacs; see the file COPYING. If not, write to +# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +# Boston, MA 02110-1301, USA. + +# Where to find the source code. $(srcdir) will be the man +# subdirectory of the source tree. This is +# set by the configure script's `--srcdir' option. +srcdir=@srcdir@ +top_srcdir=@top_srcdir@ + +# Tell make where to find source files; this is needed for the makefiles. +VPATH=@srcdir@ + + +# The makeinfo program is part of the Texinfo distribution. +# Use --force so that it generates output even if there are errors. +MAKEINFO = makeinfo --force +INFO_TARGETS = ../info/emacs ../info/ccmode ../info/cl \ + ../info/dired-x ../info/ediff ../info/forms ../info/gnus \ + ../info/message ../info/sieve ../info/pgg ../info/emacs-mime \ + ../info/info ../info/mh-e ../info/reftex \ + ../info/sc ../info/vip ../info/viper ../info/widget \ + ../info/efaq ../info/ada-mode ../info/autotype ../info/calc \ + ../info/idlwave ../info/eudc ../info/ebrowse ../info/pcl-cvs \ + ../info/woman ../info/eshell ../info/org ../info/url \ + ../info/speedbar ../info/tramp ../info/ses ../info/smtpmail \ + ../info/flymake ../info/newsticker ../info/rcirc ../info/erc +DVI_TARGETS = emacs.dvi calc.dvi cc-mode.dvi cl.dvi dired-x.dvi \ + ediff.dvi forms.dvi gnus.dvi message.dvi emacs-mime.dvi \ + gnus.dvi message.dvi sieve.dvi pgg.dvi mh-e.dvi \ + reftex.dvi sc.dvi vip.dvi viper.dvi widget.dvi faq.dvi \ + ada-mode.dvi autotype.dvi idlwave.dvi eudc.dvi ebrowse.dvi \ + pcl-cvs.dvi woman.dvi eshell.dvi org.dvi url.dvi \ + speedbar.dvi tramp.dvi ses.dvi smtpmail.dvi flymake.dvi \ + newsticker.dvi emacs-xtra.dvi rcirc.dvi erc.dvi +INFOSOURCES = info.texi + +# The following rule does not work with all versions of `make'. +.SUFFIXES: .texi .dvi +.texi.dvi: + texi2dvi $< + +TEXI2DVI = texi2dvi +ENVADD = TEXINPUTS="$(srcdir):$(TEXINPUTS)" MAKEINFO="$(MAKEINFO) -I$(srcdir)" + +EMACS_XTRA=\ + $(srcdir)/arevert-xtra.texi \ + $(srcdir)/cal-xtra.texi \ + $(srcdir)/dired-xtra.texi \ + $(srcdir)/picture-xtra.texi \ + $(srcdir)/emerge-xtra.texi \ + $(srcdir)/vc-xtra.texi \ + $(srcdir)/vc1-xtra.texi \ + $(srcdir)/vc2-xtra.texi \ + $(srcdir)/fortran-xtra.texi \ + $(srcdir)/msdog-xtra.texi + +EMACSSOURCES= \ + ${srcdir}/emacs.texi \ + ${srcdir}/doclicense.texi \ + ${srcdir}/gpl.texi \ + ${srcdir}/screen.texi \ + ${srcdir}/commands.texi \ + ${srcdir}/entering.texi \ + ${srcdir}/basic.texi \ + ${srcdir}/mini.texi \ + ${srcdir}/m-x.texi \ + ${srcdir}/help.texi \ + ${srcdir}/mark.texi \ + ${srcdir}/killing.texi \ + ${srcdir}/regs.texi \ + ${srcdir}/display.texi \ + ${srcdir}/search.texi \ + ${srcdir}/fixit.texi \ + ${srcdir}/files.texi \ + ${srcdir}/buffers.texi \ + ${srcdir}/windows.texi \ + ${srcdir}/frames.texi \ + ${srcdir}/mule.texi \ + ${srcdir}/major.texi \ + ${srcdir}/indent.texi \ + ${srcdir}/text.texi \ + ${srcdir}/programs.texi \ + ${srcdir}/building.texi \ + ${srcdir}/maintaining.texi \ + ${srcdir}/abbrevs.texi \ + ${srcdir}/sending.texi \ + ${srcdir}/rmail.texi \ + ${srcdir}/dired.texi \ + ${srcdir}/calendar.texi \ + ${srcdir}/misc.texi \ + ${srcdir}/custom.texi \ + ${srcdir}/trouble.texi \ + ${srcdir}/cmdargs.texi \ + ${srcdir}/xresources.texi \ + ${srcdir}/anti.texi \ + ${srcdir}/macos.texi \ + ${srcdir}/msdog.texi \ + ${srcdir}/gnu.texi \ + ${srcdir}/glossary.texi \ + ${srcdir}/ack.texi \ + ${srcdir}/kmacro.texi \ + $(EMACS_XTRA) + +info: $(top_srcdir)/info $(INFO_TARGETS) + +$(top_srcdir)/info: + mkdir $@ + +dvi: $(DVI_TARGETS) + +# Note that all the Info targets build the Info files +# in srcdir. There is no provision for Info files +# to exist in the build directory. +# In a distribution of Emacs, the Info files should be up to date. + +# The following target uses an explicit -o switch to work around +# the @setfilename directive in info.texi, which is required for +# the Texinfo distribution. + +../info/info: ${INFOSOURCES} + cd $(srcdir); $(MAKEINFO) --no-split info.texi -o $@ + +info.dvi: ${INFOSOURCES} + $(ENVADD) $(TEXI2DVI) ${srcdir}/info.texi + +../info/emacs: ${EMACSSOURCES} + cd $(srcdir); $(MAKEINFO) emacs.texi + +emacs.dvi: ${EMACSSOURCES} + $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs.texi + +# This target is here so you could easily get the list of the *.texi +# files which belong to the Emacs manual (as opposed to the separate +# manuals for CL, CC Mode, Ebrowse, etc.). With this target, you can +# say things like "grep foo `make emacsman`". +emacsman: + @echo $(EMACSSOURCES) + +../info/ccmode: cc-mode.texi + cd $(srcdir); $(MAKEINFO) cc-mode.texi +cc-mode.dvi: cc-mode.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/cc-mode.texi + +../info/ada-mode: ada-mode.texi + cd $(srcdir); $(MAKEINFO) ada-mode.texi +ada-mode.dvi: ada-mode.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/ada-mode.texi + +../info/pcl-cvs: pcl-cvs.texi + cd $(srcdir); $(MAKEINFO) pcl-cvs.texi +pcl-cvs.dvi: pcl-cvs.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/pcl-cvs.texi + +../info/eshell: eshell.texi + cd $(srcdir); $(MAKEINFO) eshell.texi +eshell.dvi: eshell.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/eshell.texi + +../info/cl: cl.texi + cd $(srcdir); $(MAKEINFO) cl.texi +cl.dvi: cl.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/cl.texi + +../info/dired-x: dired-x.texi + cd $(srcdir); $(MAKEINFO) dired-x.texi +dired-x.dvi: dired-x.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/dired-x.texi + +../info/ediff: ediff.texi + cd $(srcdir); $(MAKEINFO) ediff.texi +ediff.dvi: ediff.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/ediff.texi + +emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA) + $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-xtra.texi + +../info/forms: forms.texi + cd $(srcdir); $(MAKEINFO) forms.texi +forms.dvi: forms.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/forms.texi + +# gnus/message/emacs-mime/sieve/pgg are part of Gnus: +../info/gnus: gnus.texi gnus-faq.texi + cd $(srcdir); $(MAKEINFO) gnus.texi +gnus.dvi: gnus.texi gnus-faq.texi + sed -e '/@iflatex/,/@end iflatex/d' ${srcdir}/gnus.texi > gnustmp.texi + $(ENVADD) $(TEXI2DVI) gnustmp.texi + cp gnustmp.dvi $*.dvi + rm gnustmp.* + +../info/message: message.texi + cd $(srcdir); $(MAKEINFO) message.texi +message.dvi: message.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/message.texi + +../info/sieve: sieve.texi + cd $(srcdir); $(MAKEINFO) sieve.texi +sieve.dvi: sieve.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/sieve.texi + +../info/emacs-mime: emacs-mime.texi + cd $(srcdir); $(MAKEINFO) --enable-encoding emacs-mime.texi +emacs-mime.dvi: emacs-mime.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/emacs-mime.texi + +../info/pgg: pgg.texi + cd $(srcdir); $(MAKEINFO) pgg.texi +pgg.dvi: pgg.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/pgg.texi + +../info/mh-e: mh-e.texi + cd $(srcdir); $(MAKEINFO) mh-e.texi +mh-e.dvi: mh-e.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/mh-e.texi + +../info/reftex: reftex.texi + cd $(srcdir); $(MAKEINFO) reftex.texi +reftex.dvi: reftex.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/reftex.texi + +../info/sc: sc.texi + cd $(srcdir); $(MAKEINFO) sc.texi +sc.dvi: sc.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/sc.texi + +../info/vip: vip.texi + cd $(srcdir); $(MAKEINFO) vip.texi +vip.dvi: vip.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/vip.texi + +../info/viper: viper.texi + cd $(srcdir); $(MAKEINFO) viper.texi +viper.dvi: viper.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/viper.texi + +../info/widget: widget.texi + cd $(srcdir); $(MAKEINFO) widget.texi +widget.dvi: widget.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/widget.texi + +../info/efaq: faq.texi + cd $(srcdir); $(MAKEINFO) faq.texi +faq.dvi: faq.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/faq.texi + +../etc/GNU: gnu1.texi gnu.texi + cd $(srcdir) && makeinfo --no-headers -o ../etc/GNU gnu1.texi + +../info/autotype: autotype.texi + cd $(srcdir); $(MAKEINFO) autotype.texi +autotype.dvi: autotype.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/autotype.texi + +../info/calc: calc.texi + cd $(srcdir); $(MAKEINFO) calc.texi + +calc.dvi: calc.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/calc.texi + +# This is produced with --no-split to avoid making files whose +# names clash on DOS 8+3 filesystems +../info/idlwave: idlwave.texi + cd $(srcdir); $(MAKEINFO) --no-split idlwave.texi +idlwave.dvi: idlwave.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/idlwave.texi + +../info/eudc: eudc.texi + cd $(srcdir); $(MAKEINFO) eudc.texi +eudc.dvi: eudc.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/eudc.texi + +../info/ebrowse: ebrowse.texi + cd $(srcdir); $(MAKEINFO) ebrowse.texi +ebrowse.dvi: ebrowse.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/ebrowse.texi + +../info/woman: woman.texi + cd $(srcdir); $(MAKEINFO) woman.texi +woman.dvi: woman.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/woman.texi + +../info/org: org.texi + cd $(srcdir); $(MAKEINFO) org.texi +org.dvi: org.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/org.texi + +../info/url: url.texi + cd $(srcdir); $(MAKEINFO) url.texi +url.dvi: url.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/url.texi + +../info/speedbar: speedbar.texi + cd $(srcdir); $(MAKEINFO) speedbar.texi +speedbar.dvi: speedbar.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/speedbar.texi + +../info/tramp: tramp.texi trampver.texi + cd $(srcdir); $(MAKEINFO) -D emacs tramp.texi +tramp.dvi: tramp.texi trampver.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/tramp.texi + +../info/ses: ses.texi + cd $(srcdir); $(MAKEINFO) ses.texi +ses.dvi: ses.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/ses.texi + +../info/smtpmail: smtpmail.texi + cd $(srcdir); $(MAKEINFO) smtpmail.texi +smtpmail.dvi: smtpmail.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/smtpmail.texi + +../info/flymake: flymake.texi + cd $(srcdir); $(MAKEINFO) flymake.texi +flymake.dvi: flymake.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/flymake.texi + +../info/newsticker: newsticker.texi + cd $(srcdir); $(MAKEINFO) newsticker.texi +newsticker.dvi: newsticker.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/newsticker.texi + +../info/rcirc: rcirc.texi + cd $(srcdir); $(MAKEINFO) rcirc.texi +rcirc.dvi: rcirc.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/rcirc.texi + +../info/erc: erc.texi + cd $(srcdir); $(MAKEINFO) erc.texi +erc.dvi: erc.texi + $(ENVADD) $(TEXI2DVI) ${srcdir}/erc.texi + +mostlyclean: + rm -f *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.* + +clean: mostlyclean + rm -f *.dvi + +distclean: clean + +maintainer-clean: distclean + rm -f *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc + for file in $(INFO_TARGETS); do rm -f $${file}*; done + + +# Formerly this directory had texindex.c and getopt.c in it +# and this makefile built them to make texindex. +# That caused trouble because this is run entirely in the source directory. +# Since we expect to get texi2dvi from elsewhere, +# it is ok to expect texindex from elsewhere also. diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi new file mode 100644 index 00000000000..585e28318e7 --- /dev/null +++ b/doc/emacs/abbrevs.texi @@ -0,0 +1,457 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, 2003, +@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Abbrevs +@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 could 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}. + + ``Hippie'' expansion generalizes abbreviation expansion. +@xref{Hippie Expand, , Hippie Expansion, autotype, Features for +Automatic Typing}. + +@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. + + Abbrevs can have @dfn{mode-specific} definitions, 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. + + You can define abbrevs interactively during the editing session. You +can also save lists of abbrev definitions in files for use 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 define-global-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET} +Define @var{abbrev} as an abbrev expanding into @var{exp}. +@item M-x define-mode-abbrev @key{RET} @var{abbrev} @key{RET} @var{exp} @key{RET} +Define @var{abbrev} as a mode-specific abbrev expanding into @var{exp}. +@item M-x kill-all-abbrevs +Discard all abbrev definitions, 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 abbrev text itself is already in the buffer, you can use the +commands @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and +@kbd{C-x a i l} (@code{inverse-add-mode-abbrev}) to define it as an +abbrev by specify the expansion in the minibuffer. 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). + +@findex define-mode-abbrev +@findex define-global-abbrev + You can define an abbrev without inserting either the abbrev or its +expansion in the buffer using the command @code{define-global-abbrev}. +It reads two arguments---the abbrev, and its expansion. The command +@code{define-mode-abbrev} does likewise for a mode-specific abbrev. + + 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 before replacing it. + +@findex kill-all-abbrevs + 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. @kbd{M-x kill-all-abbrevs} removes all +abbrev definitions, both global and local. + +@node Expanding Abbrevs +@section Controlling Abbrev Expansion + + When Abbrev mode is enabled, 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 or whitespace 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} (setting it non-@code{nil} specifies +@samp{FIND OUTER OTTER}). + + 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 and attach a prefix to the expansion; +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, not expanding it. + +@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 any abbrev first 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. With a numeric argument, list +only local abbrevs. +@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 +@var{various other tables@dots{}} +(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. + + Some abbrevs are marked with @samp{(sys)}. These ``system'' abbrevs +(@pxref{Abbrevs,,, elisp, The Emacs Lisp Reference Manual}) are +pre-defined by various modes, and are not saved to your abbrev file. +To disable a ``system'' abbrev, define an abbrev of the same name that +expands to itself, and save it to your abbrev file. + +@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. The function @code{quietly-read-abbrev-file} is similar +except that it does not display a message in the echo area; you cannot +invoke it interactively, and it is used primarily in the @file{.emacs} +file. If either of these functions is called with @code{nil} as the +argument, it uses the file name specified in the variable +@code{abbrev-file-name}, which is by default @code{"~/.abbrev_defs"}. +That file is your standard abbrev definition file, and Emacs loads +abbrevs from it automatically when it starts up. + +@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}). It saves them in the file specified by +@code{abbrev-file-name}. 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 after point, +describing all current abbrev definitions; @kbd{M-x define-abbrevs} parses +the entire current buffer and defines abbrevs accordingly. + +@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 abbreviations 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 +away 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}. + +@vindex dabbrev-ignored-buffer-regexps + For finer control over which buffers to scan, customize the variable +@code{dabbrev-ignored-buffer-regexps}. Its value is a list of regular +expressions. If a buffer's name matches any of these regular +expressions, dynamic abbrev expansion skips that buffer. + + A negative argument to @kbd{M-/}, as in @kbd{C-u - M-/}, says to +search first for expansions after point, then other buffers, and +consider expansions before point only as a last resort. If you repeat +the @kbd{M-/} to look for another expansion, do not specify an +argument. Repeating @kbd{M-/} cycles through 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 additional 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 abbrev. 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 it is @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 dynamic abbrev you are expanding}, 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 dynamic abbrev. If it is @code{t}, +the dynamic abbrev's case pattern is preserved in most cases; if it is +@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 dynamic 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: dynamic abbrevs 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 abbrev expansion 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 abbrev expression should ignore. + +@ignore + arch-tag: 638e0079-9540-48ec-9166-414083e16445 +@end ignore diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi new file mode 100644 index 00000000000..d5dbf1ae8ca --- /dev/null +++ b/doc/emacs/ack.texi @@ -0,0 +1,1574 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1994, 1995, 1996, 1997, 1999, 2000, 2001, 2002, 2003, +@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@c +@node Acknowledgments, Screen, Concept Index, Top +@unnumbered 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 in alphabetical order those who have +written substantial portions. + +@c We should list here anyone who has contributed a new package, +@c and anyone who has made major enhancements in Emacs +@c that many users would notice and consider important. + +@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, @file{gnus-cus.el} which implements customization +commands for Gnus, @file{gnus-cite.el}, a citation-parsing facility +for news articles and @file{cpp.el} which hides or highlights parts of +C programs according to preprocessor conditionals. + +@item +Tomas Abrahamsson wrote @file{artist.el}, a package for producing @acronym{ASCII} +art with a mouse or with keyboard keys. + +@item +Jay K.@: Adams wrote @file{jka-compr.el}, providing automatic +decompression and recompression for compressed files. + +@item +Ralf Angeli wrote @file{scroll-lock.el}, a minor mode which keeps the +point vertically fixed by scrolling the window when moving up and down +in the buffer. + +@item +Joe Arceneaux wrote the original text property implementation, and +implemented support for X11. + +@item +Miles Bader wrote @file{image-file.el}, support code for visiting +image files, @file{minibuf-eldef.el}, a minor mode whereby the default +value is shown in the minibuffer prompt only when appropriate, and +@file{button.el}, the library that implements clickable buttons. + +@item +David Bakhash wrote @file{strokes.el}, a mode for controlling Emacs by +moving the mouse in particular patterns. + +@item +Eli Barzilay wrote @file{calculator.el}, a desktop calculator for +Emacs. + +@item +Steven L.@: Baur wrote +@c If earcon.el actually works with Emacs 21, it isn't useful for lack +@c of sound files. -- fx +@c @file{earcon.el}, a facility for sound effects +@c for email and news messages, +@file{footnote.el} which lets you include +footnotes in email messages, and @file{gnus-audio.el} which provides +sound effects for Gnus. + +@item +Alexander L. Belikoff, Sergey Berezin, David Edmondson, Andreas +Fuchs, Mario Lang, Gergely Nagy, Michael Olson, and Alex Schroeder +contributed ERC, an advanced Internet Relay Chat client. + +@item +Boaz Ben-Zvi wrote @file{profile.el}, to time Emacs Lisp functions. + +@item +Anna M. Bigatti wrote @file{cal-html.el}, which produces HTML calendars. + +@item +Ray Blaak wrote @file{delphi.el}, a major mode for editing Delphi +(Object Pascal) source code. + +@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. Jim also wrote @file{tvi970.el}, +terminal support for the TeleVideo 970 terminals. + +@item +Per Bothner wrote @file{term.el}, a terminal emulator in an Emacs +buffer. + +@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: + +@itemize @minus +@item +@file{dirtrack} which does better tracking of directory changes in shell +buffers, +@item +@file{filecache.el} which records which directories your files are in, +@item +@file{locate.el} which interfaces to the @code{locate} command, +@item +@file{find-lisp.el}, an Emacs Lisp emulation of the @code{find} program, +@item +@file{net-utils.el}, and +@item +the ``generic mode'' feature. +@end itemize + +@item +Emmanuel Briot wrote @file{xml.el}, an XML parser for Emacs. + +@item +Kevin Broadey wrote @file{foldout.el}, providing folding extensions to +Emacs's outline modes. + +@c @item +@c Vincent Broman wrote @file{ada.el}, a mode for editing Ada code +@c (since replaced by @file{ada-mode.el}). + +@item +David M.@: Brown wrote @file{array.el}, for editing arrays and other +tabular data. + +@item +W@l{}odek Bzyl and Ryszard Kubiak wrote @file{ogonek.el}, a package for +changing the encoding of Polish characters. + +@item +Bill Carpenter provided @file{feedmail.el}, a package for massaging +outgoing mail messages and sending them through various popular mailers. + +@item +Per Cederqvist and Inge Wallin wrote @file{ewoc.el}, an Emacs widget for +manipulating object collections. + +@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 +Chris Chase and Carsten Dominik wrote @file{idlwave.el}, an editing mode +for IDL and WAVE CL. + +@item +Bob Chassell wrote @file{texnfo-upd.el} and @file{makeinfo.el}, modes +and utilities for working with Texinfo files; and @file{page-ext.el}, +commands for extended page handling. + +@item +Andrew Choi wrote the Macintosh support code, and contributed +@file{mac-win.el}, support for the Mac window system. + +@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 +Georges Brun-Cottan and Stefan Monnier wrote @file{easy-mmode.el}, a +package for easy definition of major and minor modes. + +@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 +Mathias Dahl wrote @file{image-dired.el}, a package for viewing image +files as ``thumbnails.'' + +@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 +Jan Dj@"{a}rv added support for the GTK+ toolkit and X drag-and-drop. + +@item +Carsten Dominik wrote @file{reftex.el}, a package for setting up +labels and cross-references in La@TeX{} documents, and @file{org.el}, +a mode for maintaining notes, todo lists, and project planning. + +@item +Scott Draves wrote @file{tq.el}, help functions for maintaining +transaction queues between Emacs and its subprocesses. + +@item +Benjamin Drieu wrote @file{pong.el}, an implementation of the classical +pong game. + +@item +Viktor Dukhovni wrote support for dumping under SunOS version 4. + +@item +John Eaton co-wrote Octave mode. + +@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 +Torbj@"orn +Einarsson contributed the Fortran 90 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 Farnbach implemented @file{morse.el}, which converts text to +Morse code. + +@item +Oscar Figueiredo wrote EUDC, the Emacs Unified Directory Client, which +is an interface to directory servers via LDAP, CCSO PH/QI, or BBDB; and +@file{ldap.el}, the LDAP client interface. + +@item +Fred Fish wrote the support for dumping COFF executable files. + +@item +Karl Fogel wrote: + +@itemize @minus +@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 @file{crisp.el}, the emulation for CRiSP and Brief +editors, and @file{scroll-lock.el} (now @file{scroll-all.el}) a mode +for scrolling several buffers together. + +@item +Noah Friedman wrote @file{rlogin.el}, an interface to Rlogin, +@file{type-break.el}, which reminds you to take periodic breaks from +typing, and @code{eldoc-mode}, a mode to show the defined parameters or +the doc string for the Lisp function near point. 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 and wrote +@file{w32-win.el}, support functions for the MS-Windows window system. + +@item +Juan Le@'{o}n Lahoz Garc@'{i}a wrote @file{wdired.el}, a package for +performing file operations by directly editing Dired buffers. + +@item +Howard Gayle wrote: + +@itemize @minus +@item +the C and lisp code for display tables and case tables, +@item +@file{rot13.el}, a command to display the plain-text form of a buffer +encoded with the Caesar cipher, +@item +@file{case-table.el}, code to extend the character set and support case +tables, +@item +much of the support for the ISO-8859 European character sets (which +includes @file{iso-ascii.el}, @file{iso-insert.el}, @file{iso-swed.el}, +@file{latin-1.el}, @file{iso-syntax.el}, @file{iso-transl.el}, +@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, and made many +contributions for @file{time-stamp.el}, a package for maintaining +last-change time stamps in files. + +@item +Julien Gilles wrote @file{gnus-ml.el}, a mailing list minor mode for +Gnus. + +@item +David Gillespie wrote: + +@itemize @minus +@item +The Common Lisp compatibility packages, +@item +@code{Calc}, an advanced calculator and mathematical tool, +@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, a facility for +writing regexps using a Lisp-like syntax. + +@item +Boris Goldowsky wrote: + +@itemize @minus +@item +@file{avoid.el}, a package to keep the mouse cursor out of the way of +the text cursor, +@item +@file{shadowfile.el}, a package for keeping identical copies of files in +more than one place, +@item +@file{format.el}, a package for reading and writing files in various +formats, +@item +@file{enriched.el}, a package for saving text properties in files, and +@item +@file{facemenu.el}, a package for specifying faces. +@end itemize + +@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} for editing DCL command files. + +@item +Kai Gro@ss{}johann and Michael Albinus wrote the Tramp package, which +provides transparent remote file editing using rcp, ssh, ftp, and other +network protocols. + +@item +Michael Gschwind wrote @file{iso-cvt.el}, a package to convert between +the ISO 8859-1 character set and the notations for non-@acronym{ASCII} +characters used by @TeX{} and net tradition, and @file{latin-2.el}, code +which sets up case-conversion and syntax tables for the ISO Latin-2 +character set. + +@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, and wrote @file{isearch-x.el}, a facility for searching +non-@acronym{ASCII} text. Together with Naoto Takahashi, he wrote +@file{quail.el}, a simple input facility for typing non-@acronym{ASCII} text from +an @acronym{ASCII} keyboard. Ken'ichi also wrote @file{ps-bdf.el}, a BDF font +support for printing non-@acronym{ASCII} text on a PostScript printer. + +@item +Chris Hanson wrote @file{netuname.el}, a package to use HP-UX's Remote +File Access facility from Emacs. + +@item +Jesper Harder wrote @file{yenc.el}, for decoding yenc encoded messages. + +@item +K. Shane Hartman wrote: + +@itemize @minus +@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 @acronym{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 +Jon K Hellan wrote @file{utf7.el}, support for mail-safe transformation +format of Unicode. + +@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 MS-DOS. + +@item +Anders Holst wrote @file{hippie-exp.el}, a versatile completion and +expansion package. + +@item +Kurt Hornik co-wrote Octave mode. + +@item +Tom Houlder wrote @file{mantemp.el}, which generates manual C@t{++} +template instantiations. + +@item +Joakim Hove wrote @file{html2text.el}, a html to plain text converter. +@item +Denis Howe wrote @file{browse-url.el}, a package for invoking a WWW +browser to display a URL. + +@item +Lars Magne Ingebrigtsen did a major redesign of the Gnus news-reader and +wrote many of its parts. + +@item +Andrew Innes contributed extensively to the MS-Windows support. + +@item +Seiichiro Inoue improved Emacs's XIM support. + +@item +Ulf Jasper wrote @file{icalendar.el}, a package for converting Emacs +diary entries to and from the iCalendar format, and +@file{newsticker.el}, an RSS and Atom based Newsticker. + +@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 +Terry Jones wrote @file{shadow.el}, a package for finding potential +load-path problems when some Lisp file ``shadows'' another. + +@item +Simon Josefsson wrote: + +@itemize @minus +@item +@file{dns-mode.el}, an editing mode for Domain Name System master files, +@item +@file{flow-fill.el}, a package for interpreting RFC2646 formatted text +in messages, +@item +@file{fringe.el}, a package for customizing the fringe, +@item +@file{imap.el}, an Emacs Lisp library for talking to IMAP servers, +@item +@file{nnimap}, the IMAP back-end for Gnus, and +@item +@file{rfc2104.el}, a hashed message authentication facility. +@end itemize + +@item +Arne J@o{}rgensen wrote @file{latexenc.el}, a package to +automatically guess the correct coding system in LaTeX files. + +@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 +Taichi Kawabata added support for Devanagari script and the Indian +languages. + +@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 +@command{diff}, @command{patch}, and @command{merge} 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. He also wrote the initial version of +@file{uniquify.el}, a facility to make buffer names unique by adding +parts of the file's name to the buffer name. +@c We're not using his backquote.el any more. + +@item +Peter Kleiweg wrote @file{ps-mode.el}, a major mode for editing +PostScript files and running a PostScript interpreter interactively from +within Emacs. + +@item +Pavel Kobiakov wrote @file{flymake.el}, a minor mode for performing +on-the-fly syntax checking. + +@item +Larry K.@: Kolodney wrote @file{cvtmail.c}, a program to convert the mail +directories used by Gosling Emacs into RMAIL format. + +@item +David M.@: Koppelman wrote @file{hi-lock.el}, a minor mode for +interactive automatic highlighting of parts of the buffer text. + +@item +Koseki Yoshinori wrote @file{iimage.el}, a minor mode for displaying +inline images. + +@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. He also wrote @file{ls-lisp.el}, a Lisp emulation +of the @code{ls} command for platforms which don't have @code{ls} as a +standard program. + +@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 @minus +@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's incremental search minor mode. +@end itemize + +@item +James R.@: Larus wrote @file{mh-e.el}, an interface to the MH mail system. + +@item +Vinicius Jose Latorre wrote the Emacs printing facilities, as well as: + +@itemize @minus +@item +@code{ps-print}, a package for pretty-printing Emacs buffers to +PostScript printers, +@item +@file{delim-col.el}, a package to arrange text into columns, +@item +@file{ebnf2ps.el}, a package that translates EBNF grammar to a syntactic +chart that can be printed to a PostScript printer. +@end itemize + +@item +Frederic Lepied contributed @file{expand.el}, which uses the abbrev +mechanism for inserting programming constructs. + +@item +Peter Liljenberg wrote @file{elint.el}, a Lint-style code checker for +Emacs Lisp programs. + +@item +Lars Lindberg wrote @file{msb.el}, which provides more flexible menus +for buffer selection, and rewrote @file{dabbrev.el}. + +@item +Anders Lindgren wrote @file{autorevert.el}, a package for automatically +reverting files visited by Emacs that were changed on disk; +@file{cwarn.el}, a package to highlight suspicious C and C@t{++} +constructs; and @file{follow.el}, a minor mode to synchronize windows +that show the same buffer. + +@item +Thomas Link wrote @file{filesets.el}, a package for handling sets of +files. + +@item +Dave Love wrote much of the code dealing with Unicode support and +Latin-N unification. He added support for many coding systems, +including those in @file{code-pages.el} and the various UTF-7 and +UTF-16 coding systems. He also wrote: + +@itemize @minus +@item +@code{autoarg-mode}, a global minor mode whereby digit keys supply +prefix arguments, and @code{autoarg-kp-mode} which redefines the keypad +numeric keys to digit arguments, +@item +@file{autoconf.el}, a mode for editing Autoconf @file{configure.in} +files, +@item +@file{cfengine.el}, a mode for editing Cfengine files, +@item +@file{elide-head.el}, a package for eliding boilerplate text, such as +copyright notices, from file headers, +@item +@file{hl-line.el}, a package that provides a minor mode for highlighting +the line in the current window on which point is, +@item +@file{latin-8.el} and @file{latin-9.el}, code which sets up +case-conversion and syntax tables for the ISO Latin-8 and Latin-9 +character sets, +@item +@file{latin1-disp.el}, a package that lets you display ISO 8859 +characters on Latin-1 terminals by setting up appropriate display +tables, +@item +@file{python.el}, a major mode for the Python programming language. +@item +@file{refill.el}, a mode for automatic paragraph refilling, akin to +typical word processors, +@item +@file{smiley-ems.el}, a facility for displaying smiley faces, and +@item +@file{tool-bar.el}, a mode to control the display of the Emacs tool bar. +@end itemize + +@item +Eric Ludlam wrote the Speedbar package and the following packages: + +@itemize @minus +@item +@file{checkdoc.el}, for checking doc strings in Emacs Lisp programs, +@item +@file{dframe.el}, providing dedicatd frame support modes, and +@item +@file{ezimage.el}, a generalized way to place images over text. +@end itemize + +@item +Alan Mackenzie wrote the integrated AWK support in CC Mode. + +@item +Christopher J.@: Madsen wrote @file{decipher.el}, a package for cracking +simple substitution ciphers. + +@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 @file{regexp-opt.el}, which generates a regular +expression from a list of strings. He also extended @file{comint.el}, +originally written by Olin Shivers. + +@item +Bengt Martensson, Marc 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 @minus +@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 +Will Mengarini wrote @file{repeat.el}, a command to repeat the preceding +command with its arguments. + +@item +Wayne Mesard wrote @file{hscroll.el} which does horizontal scrolling +automatically. + +@item +Brad Miller wrote @file{gnus-gl.el}, a Gnus interface for GroupLens. + +@item +Richard Mlynarik wrote: + +@itemize @minus +@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 +Gerd Moellmann was the Emacs maintainer from the beginning of Emacs 21 +development until the release of 21.1. He wrote: + +@itemize @minus +@item +the new display engine for Emacs 21, +@item +the asynchronous timers facility (@file{atimer.c}), +@item +the @code{ebrowse} C@t{++} browser, +@item +@file{jit-lock.el}, the Just-In-Time font-lock support mode, +@item +@file{tooltip.el}, a package for displaying tooltips, and +@item +@file{authors.el} package for maintaining the @file{AUTHORS} files. +@end itemize + +@item +Stefan Monnier added support for Arch, Subversion, and Meta-CVS to VC, +and re-wrote much of the Emacs server to use the built-in networking +primitives. He also wrote: + +@itemize @minus +@item +@code{PCL-CVS}, a directory-level front end to the CVS version control +system, +@item +@file{reveal.el}, a minor mode for automatically revealing invisible +text, +@item +@file{smerge-mode.el}, a minor mode for resolving @code{diff3} +conflicts, and +@item +@file{diff-mode.el}, a mode for viewing and editing context diffs. +@end itemize + +@item +Morioka Tomohiko wrote several packages for MIME support in Gnus and +elsewhere. + +@item +Sen Nagata wrote @file{crm.el}, a package for reading multiple strings +with completion, and @file{rfc2368.el}, support for @code{mailto:} +URLs. + +@item +Erik Naggum wrote the time-conversion functions. He also wrote +@file{disp-table.el}, a package for dealing with display tables, +@file{latin-4.el} and @file{latin-5.el}, code which sets up +case-conversion and syntax tables for the ISO Latin-4 and Latin-5 +character sets, @file{mailheader.el}, a package for parsing email +headers, and @file{parse-time.el}, a package for parsing time strings. + +@item +Thomas Neumann and Eric Raymond wrote @file{makefile.el} (now +@file{make-mode.el}), a mode for editing makefiles. + +@item +Thien-Thi Nguyen and Dan Nicolaescu wrote @file{hideshow.el}, a minor +mode for selectively displaying blocks of text. + +@item +Dan Nicolaescu wrote @file{romanian.el}, support for editing Romanian +text, and @file{iris-ansi.el}, support for running Emacs on SGI's +@code{xwsh} and @code{winterm} terminal emulators. + +@item +Jurgen Nickelsen wrote @file{ws-mode.el}, providing WordStar emulation. + +@item +Hrvoje Niksic wrote @file{savehist.el}, for saving the minibuffer +history between Emacs sessions. + +@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 +Alexandre Oliva wrote @file{gnus-mlspl.el}, a group params-based mail +splitting mechanism. + +@item +Takaaki Ota wrote @file{table.el}, a package for creating and editing +embedded text-based tables. + +@item +Pieter E.@: J.@: Pareit wrote @file{mixal-mode.el}, an editing mode for +the MIX assembly language. + +@item +David Pearson contributed @file{quickurl.el}, a simple method of +inserting a URL into the current buffer based on text at point; +@file{5x5.el}, a game to fill all squares on the field. + +@item +Jeff Peck wrote: + +@itemize @minus +@item +@file{emacstool.c}, support for running Emacs under SunView/Sun Windows, +@item +@file{sun.el}, key bindings for sunterm keys, +@item +@file{sun-curs.el}, cursor definitions for Sun Windows, and +@item +@file{sun-fns.el} and @file{sun-mouse.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 +William M.@: Perry wrote @file{mailcap.el}, a MIME media types +configuration facility, @file{mwheel.el}, a package for supporting +mouse wheels, and the URL package. + +@item +Per Persson wrote @file{gnus-vm.el}, the VM interface for Gnus. + +@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 @minus +@item +@file{conf-mode.el}, a major mode for editing configuration files, +@item +@file{copyright.el}, a package for updating copyright notices in files, +@item +@file{executable.el}, a package for executing interpreter scripts, +@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 + +Daniel also rewrote @file{apropos.el}, originally written by Joe Wells, +and, together with Jim Blandy, co-authored @file{wyse50.el}, support for +Wyse 50 terminals. + +@item +Richard L.@: Pieri wrote @file{pop3.el}, a Post Office Protocol (RFC +1460) interface for Emacs. + +@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 +David Ponce wrote: + +@itemize @minus +@item +@file{recentf.el}, a package that puts a menu of recently visited +files in the Emacs menu bar, +@item +@file{ruler-mode.el}, a minor mode for displaying a ruler in the +header line, and +@item +@file{tree-widget.el}, a package to display hierarchical data structures. +@end itemize + +@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. +He also expanded and redesigned the @code{etags} program. + +@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 +Mukesh Prasad contributed @file{vmsproc.el}, a facility for running +asynchronous subprocesses on VMS. + +@item +Marko Rahamaa wrote @file{latin-3.el}, code which sets up +case-conversion and syntax tables for the ISO Latin-3 character set. + +@item +Ashwin Ram wrote @file{refer.el}, commands to look up references in +bibliography files by keyword. + +@item +Eric S.@: Raymond wrote: + +@itemize @minus +@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{AT386.el}, terminal support package for IBM's AT keyboards, +@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{keyswap.el}, code to swap the @key{BS} and @key{DEL} keys, +@item +@file{loadhist.el}, functions for loading and unloading Emacs features, +@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, Nachum +Dershowitz, Paul Eggert, Steve Fisk, Michael Kifer, 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 +David Reitter wrote @file{mailclient.el} which can send mail via the +system's designated mail client. + +@item +Alex Rezinsky contributed @file{which-func.el}, a mode that shows the +name of the current function in the mode line. + +@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 +Nick Roberts wrote @file{gdb-ui.el}, the graphical user interface to +GDB. + +@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 and +DSSSL 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 +Jason Rumney has ported the Emacs 21 display engine to MS-Windows, and +contributed extensively to the MS-Windows port of Emacs. + +@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 +Kevin Ryde wrote @file{info-xref.el}, a library for checking +references in Info files. + +@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 +Holger Schauer wrote @file{fortune.el}, a package for using fortune in +message signatures. + +@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 +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 +Jan Schormann wrote @file{solitaire.el}, an Emacs Lisp implementation of +the Solitaire game. + +@item +Alex Schroeder wrote @file{ansi-color.el}, a package for translating +ANSI color escape sequences to Emacs faces, and @file{sql.el}, a package +for interactively running an SQL interpreter in an Emacs buffer. + +@item +Randal Schwartz wrote @file{pp.el}, a pretty-printer for lisp objects. + +@item +Oliver Seidel wrote @file{todo-mode.el}, a package for maintaining +@file{TODO} list files. + +@item +Manuel Serrano contributed the Flyspell package that does spell checking +as you type. + +@item +Hovav Shacham wrote @file{windmove.el}, a set of commands for selecting +windows based on their geometrical position on the frame. + +@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 show recent editing changes. + +@item +Olin Shivers wrote: + +@itemize @minus +@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 +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 +Andre Spiegel made many contributions to the Emacs Version Control +package, and in particular made it support multiple back ends. + +@item +Michael Staats wrote @file{pc-select.el}, which rebinds keys for +selecting regions to follow many other systems. + +@item +Richard Stallman invented Emacs, and then wrote: + +@itemize @minus +@item +@file{easymenu.el}, a facility for defining Emacs menus, +@item +@file{menu-bar.el}, the Emacs menu bar support code, +@item +@file{paren.el}, a package to make matching parentheses stand out in +color, and +@item +most of the rest of Emacs code. +@end itemize + +@item +Sam Steingold wrote @file{gulp.el}, a facility for asking package +maintainers for updated versions of their packages via e-mail, and +@file{midnight.el}, a package for running a command every midnight. + +@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 +Ken Stevens wrote the initial version of @file{ispell.el} and maintains +that package since Ispell 3.1 release. + +@item +Jonathan Stigelman wrote @file{hilit19.el}, a package providing +automatic highlighting in source code buffers, mail readers, and other +contexts. + +@item +Kim F.@: Storm made many improvements to the Emacs display engine, +process support, and networking support. He also wrote: + +@itemize @minus +@item +@file{bindat.el}, a package for encoding and decoding binary data. +@item +@file{cua.el}, which allows Emacs to emulate the standard CUA key +bindings. +@item +@file{ido.el}, a package for selecting buffers and files quickly. +@item +@file{kmacro.el}, the keyboard macro facility. +@end itemize + +@item +Martin Stjernholm co-authored CC Mode, a major editing mode for C, +C@t{++}, Objective-C, Java, Pike, CORBA IDL, and AWK code. + +@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 +Olaf Sylvester wrote @file{bs.el}, a package for manipulating Emacs +buffers. + +@item +Tibor @v{S}imko and Milan Zamazal wrote @file{slovak.el}, support for +editing text in Slovak language. + +@item +Naoto Takahashi wrote @file{utf-8.el}, support for encoding and +decoding UTF-8 data. + +@item +Luc Teirlinck wrote @file{help-at-pt.el}, providing local help through +the keyboard. + +@item +Jean-Philippe Theberge wrote @file{thumbs.el}, a package for viewing +image files as ``thumbnails.'' + +@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 +Tom Tromey and Chris Lindblad wrote @file{tcl.el}, a major mode for +editing Tcl/Tk source files and running a Tcl interpreter as an Emacs +subprocess. + +@item +Eli Tziperman wrote @file{rmail-spam-filter.el}, a spam filter for RMAIL. +@item +Daiki Ueno wrote @file{starttls.el}, support for Transport Layer +Security protocol, and the PGG package adding GnuPG and PGP support. + +@item +Masanobu Umeda wrote: + +@itemize @minus +@item +GNUS, a feature-full 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{gnus-kill.el}, the Kill File mode for Gnus, +@item +@file{gnus-mh.el}, an mh-e interface for Gnus, +@item +@file{gnus-msg.el}, a mail and post interface for Gnus, +@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 +Rajesh Vaidheeswarran wrote @file{whitespace.el}, a package that +detects and cleans up excess whitespace in a file. + +@item +Neil W.@: Van Dyke wrote @file{webjump.el}, a ``hot links'' package. + +@item +Didier Verna contributed @file{rect.el}, a package of functions for +operations on rectangle regions of text. + +@item +Ulrik Vieth implemented @file{meta-mode.el}, for editing MetaFont code. + +@item +Geoffrey Voelker wrote the Windows NT support. He also wrote +@file{dos-w32.el}, functions shared by the MS-DOS and MS-Windows ports +of Emacs, and @file{w32-fns.el}, MS-Windows specific support functions. + +@item +Johan Vromans wrote @file{forms.el} and its associated files, a +mode for filling in forms. + +@item +Colin Walters wrote @file{ibuffer.el}, a Dired-like major mode for +operating on buffers. + +@item +Barry Warsaw wrote: + +@itemize @minus +@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, C@t{++}, and Java 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 functionality for use in lisp +programs, +@item +@file{reporter.el}, providing customizable bug reporting for lisp +packages, and +@item +@file{supercite.el}, a minor mode for quoting sections of mail messages +and news articles. +@end itemize + +@item +Morten Welinder introduced face support into the MS-DOS port of Emacs, +and also wrote: + +@itemize @minus +@item +@file{desktop.el}, facilities for saving some of Emacs's state between +sessions, +@item +@file{timer.el}, the Emacs facility to run commands at a given time or +frequency, or when Emacs is idle, and its C-level support code, +@item +@file{pc-win.el}, the MS-DOS ``window-system'' support, +@item +@file{internal.el}, an ``internal terminal'' emulator for the MS-DOS +port of Emacs, +@item +@file{arc-mode.el}, the mode for editing compressed archives, +@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 @minus +@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}, a major +mode for editing VHDL source code. + +@item +John Wiegley wrote @file{align.el}, a set of commands for aligning text +according to regular-expression based rules; @file{timeclock.el}, a +package for keeping track of time spent on projects; +@file{pcomplete.el}, a programmable completion facility; and +@code{eshell}, a command shell implemented entirely in Emacs Lisp. + +@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 +Bill Wohler wrote the Emacs interface to the MH mail system. + +@item +Dale R.@: Worley wrote @file{emerge.el}, a package for interactively +merging two versions of a file. + +@item +Francis J.@: Wright wrote @code{WoMan}, a package for browsing +manual pages without the @code{man} command. + +@item +Tom Wurgler wrote @file{emacs-lock.el}, which makes it harder +to exit with valuable buffers unsaved. + +@item +Masatake Yamato wrote @file{ld-script.el}, an editing mode for GNU +linker scripts, and contributed subword handling in CC mode. + +@item +Jonathan Yavner wrote @file{testcover.el}, a package for keeping track +of the testing status of Emacs Lisp code, and the SES spreadsheet +package. + +@item +Ryan Yeske wrote @file{rcirc.el} a simple Internet Relay Chat client. +@item +Ilya Zakharevich and Bob Olson contributed @file{cperl-mode.el}, a major +mode for editing Perl code. Ilya Zakharevich also wrote @file{tmm.el}, +a mode for accessing the Emacs menu bar on a text-mode terminal. + +@item +Milan Zamazal wrote @file{czech.el}, support for editing Czech text, +@file{glasses.el}, a package for easier reading of source code which +uses illegible identifier names such as @code{cantReadThisVariable}, and +@file{tildify.el}, commands for adding hard spaces to text, @TeX{}, and +SGML/HTML files. + +@item +Victor Zandy contributed @file{zone.el}, a package for people who like +to zone out in front of Emacs. + +@item +Eli Zaretskii made many standard Emacs features work on MS-DOS. He also +wrote @file{tty-colors.el}, which implements transparent mapping of X +colors to tty colors, and (together with Kenichi Handa) +@file{codepage.el}, a package for editing text encoded in DOS/Windows +code pages. + +@item +Jamie Zawinski wrote: + +@itemize @minus +@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 +Andrew Zhilin created the Emacs icons used beginning with Emacs 22. + +@item +Shenghuo Zhu wrote: + +@itemize @minus +@item +@file{binhex.el}, a package for reading and writing binhex files, +@item +@file{mm-partial.el}, message/partial support for MIME messages, +@item +@file{rfc1843.el}, an HZ decoding package, +@item +@file{uudecode.el}, an Emacs Lisp decoder for uuencoded data, +@item +@file{webmail.el}, an interface to Web mail. +@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. + +@item +Detlev Zundel wrote @file{re-builder.el}, a package for building regexps +with visual feedback. + +@end itemize + +Others too numerous to mention have reported and fixed bugs, and added +features to many parts of Emacs. (Many are mentioned in the +@file{ChangeLog} files which are summarized in the file @file{AUTHORS} +in the distribution.) 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. + +@ignore + arch-tag: bb1d0fa4-0240-4992-b5d4-8602d1e3d4ba +@end ignore diff --git a/doc/emacs/anti.texi b/doc/emacs/anti.texi new file mode 100644 index 00000000000..ebff1c7677f --- /dev/null +++ b/doc/emacs/anti.texi @@ -0,0 +1,306 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. + +@node Antinews, Mac OS, X Resources, Top +@appendix Emacs 21 Antinews + + For those users who live backwards in time, here is information about +downgrading to Emacs version 21.4. We hope you will enjoy the greater +simplicity that results from the absence of many Emacs @value{EMACSVER} +features. + +@itemize @bullet + +@item +The buffer position and line number are now displayed at the end of +the mode line, where they can be more easily seen. + +@item +The mode line of the selected window is no longer displayed with a +special face. All mode lines are created equal. Meanwhile, you can +use the variable @code{mode-line-inverse-video} to control whether +mode lines are highlighted at all---@code{nil} means don't highlight +them. + +@item +Clicking on a link with the left mouse button (@kbd{mouse-1}) will +always set point at the position clicked, instead of following the +link. If you want to follow the link, use the middle mouse button +(@kbd{mouse-2}). + +@item +Emacs is tired of X droppings. If you drop a file or a piece of text +onto an Emacs window, nothing will happen. + +@item +On an xterm, even if you enable Xterm Mouse mode, Emacs provides a +more convincing simulation of a text terminal by not responding to +mouse clicks on the mode line, header line, or display margin. + +@item +For simplicity, windows always have fringes. We wouldn't want to +in-fringe anyone's windows. Likewise, horizontal scrolling always +works in the same automatic way. + +@item +The horizontal-bar cursor shape has been removed. + +@item +If command line arguments are given, Emacs will not display a splash +screen, so that you can immediately get on with your editing. The +command-line option @samp{--no-splash} is therefore obsolete, and has +been removed. + +@item +These command line options have also been removed: @samp{--color}, +@samp{--fullwidth}, @samp{--fullheight}, @samp{--fullscreen}, +@samp{--no-blinking-cursor}, @samp{--no-desktop}, and @samp{-Q}. + +@item +The @samp{--geometry} option applies only to the initial frame, and +the @samp{-f} option will not read arguments for interactive +functions. + +@item +We have standardized on one location for the user init file: the file +named @file{.emacs} in your home directory. Emacs will not look for +the init file in @file{~/.emacs.d/init.el}. Similarly, don't try +putting @file{.emacs_SHELL} as @file{init_SHELL.sh} in +@file{~/.emacs.d}; Emacs won't find it. + +@item +Emacs will not read @file{~/.abbrev_defs} automatically. If you want +to load abbrev definitions from a file, you must always do so +explicitly. + +@item +When you are logged in as root, all files now give you writable +buffers, reflecting the fact that you can write any files. + +@item +The maximum size of buffers and integer variables has been halved. On +32-bit machines, the maximum buffer size is now 128 megabytes. + +@item +An unquoted @samp{$} in a file name is now an error, if the following +name is not recognized as an environment variable. Thus, +the file name @file{foo$bar} would probably be an error. Meanwhile, +the @code{setenv} command does not expand @samp{$} at all. + +@item +If a single command accumulates too much undo information, Emacs never +discards it. If Emacs runs out of memory as a result, it will handle +this by crashing. + +@item +Many commands have been removed from the menus or rearranged. + +@item +The @kbd{C-h} (help) subcommands have been rearranged---especially +those that display specific files. Type @kbd{C-h C-h} to see a list +of these commands; that will show you what is different. + +@item +The @kbd{C-h v} and @kbd{C-h f} commands no longer show a hyperlink to +the C source code, even if it is available. If you want to find the +source code, grep for it. + +@item +The apropos commands will not accept a list of words to match, in +order to encourage you to be more specific. Also, the user option +@code{apropos-sort-by-scores} has been removed. + +@item +The minibuffer prompt is now displayed using the default face. +The colon is enough to show you what part is the prompt. + +@item +Minibuffer completion commands always complete the entire minibuffer +contents, just as if you had typed them at the end of the minibuffer, +no matter where point is actually located. + +@item +The command @code{backward-kill-sexp} is now bound to @kbd{C-M-delete} +and @kbd{C-M-backspace}. Be careful when using these key sequences! +It may shut down your X server, or reboot your operating system. + +@item +Commands to set the mark at a place away from point, including +@kbd{M-@@}, @kbd{M-h}, etc., don't do anything special when you repeat +them. In most cases, typing these commands multiple times is +equivalent to typing them once. @kbd{M-h} ignores numeric arguments. + +@item +The user option @code{set-mark-command-repeat-pop} has been removed. + +@item +@kbd{C-@key{SPC} C-@key{SPC}} has no special meaning--it just sets the +mark twice. Neither does @kbd{C-u C-x C-x}, which simply exchanges +point and mark like @kbd{C-x C-x}. + +@item +The function @code{sentence-end} has been eliminated in favor of a +more straightforward approach: directly setting the variable +@code{sentence-end}. For example, to end each sentence with a single +space, use + +@lisp +(setq sentence-end "[.?!][]\"')@}]*\\($\\|[ \t]\\)[ \t\n]*") +@end lisp + +@item +The variable @code{fill-nobreak-predicate} is no longer customizable, +and it can only hold a single function. + +@item +Nobreak spaces and hyphens are displayed just like normal characters, +and the user option @code{nobreak-char-display} has been removed. + +@item +@kbd{C-w} in an incremental search always grabs an entire word +into the search string. More precisely, it grabs text through +the next end of a word. + +@item +Yanking now preserves all text properties that were in the killed +text. The variable @code{yank-excluded-properties} has been removed. + +@item +Occur mode, Info mode, and Comint-derived modes now control +fontification in their own way, and @kbd{M-x font-lock-mode} has +nothing to do with it. To control fontification in Info mode, use the +variable @code{Info-fontify}. + +@item +@samp{M-x shell} is now completely standard in regard to scrolling +behavior. It no longer has the option of scrolling the input line to +the bottom of the window the way a text terminal running a shell does. + +@item +The Grep package has been merged with Compilation mode. Many +grep-specific commands and user options have thus been eliminated. +Also, @kbd{M-x grep} never tries the GNU grep @samp{-H} option, +and instead silently appends @file{/dev/null} to the command line. + +@item +In Dired's @kbd{!} command, @samp{*} and @samp{?} now +cause substitution of the file names wherever they appear---not +only when they are surrounded by whitespace. + +@item +When a file is managed with version control, the command @kbd{C-x C-q} +(whose general meaning is to make a buffer read-only or writable) now +does so by checking the file in or out. Checking the file out makes +the buffer writable; checking it in makes the buffer read-only. + +You can still use @kbd{C-x v v} to do these operations if you wish; +its meaning is unchanged. If you want to control the buffer's +read-only flag without performing any version control operation, +use @kbd{M-x toggle-read-only}. + +@item +SGML mode does not handle XML syntax, and does not have indentation +support. + +@item +Many Info mode commands have been removed. Incremental search in Info +searches only the current node. + +@item +Many @code{etags} features for customizing parsing using regexps +have been removed. + +@item +The Emacs server now runs a small C program called @file{emacsserver}, +rather than trying to handle everything in Emacs Lisp. Now there can +only be one Emacs server running at a time. The @code{server-mode} +command and @code{server-name} user option have been eliminated. + +@item +The @file{emacsclient} program no longer accepts the @samp{--eval}, +@samp{--display} and @samp{--server-file} command line options, and +can only establish local connections using Unix domain sockets. + +@item +The command @code{quail-show-key}, for showing how to input a +character, has been removed. + +@item +The default value of @code{keyboard-coding-system} is always +@code{nil}, regardless of your locale settings. If you want some +other value, set it yourself. + +@item +Unicode support and unification between Latin-@var{n} character sets +have been removed. Cutting and pasting X selections does not support +``extended segments'', so there are certain coding systems it cannot +handle. + +@item +The input methods for Emacs are included in a separate distribution +called ``Leim.'' To use this, you must extract the Leim tar file on +top of the Emacs distribution, into the same directory, before you +build Emacs. + +@item +The following input methods have been eliminated: belarusian, +bulgarian-bds, bulgarian-phonetic, chinese-sisheng, croatian, dutch, +georgian, latin-alt-postfix, latin-postfix, latin-prefix, +latvian-keyboard, lithuanian-numeric, lithuanian-keyboard, +malayalam-inscript, rfc1345, russian-computer, sgml, slovenian, +tamil-inscript ucs, ukrainian-computer, vietnamese-telex, and welsh. + +@item +The following language environments have been eliminated: Belarusian, +Bulgarian, Chinese-EUC-TW, Croatian, French, Georgian, Italian, +Latin-6, Latin-7, Latvian, Lithuanian, Malayalam, Russian, Russian, +Slovenian, Swedish, Tajik, Tamil, UTF-8, Ukrainian, Ukrainian, Welsh, +and Windows-1255. + +@item +The @code{code-pages} library, which contained various 8-bit coding +systems, has been removed. + +@item +The Kmacro package has been replaced with a simple and elegant +keyboard macro system. Use @kbd{C-x (} to start a new keyboard macro, +@kbd{C-x )} to end the macro, and @kbd{C-x e} to execute the last +macro. Use @kbd{M-x name-last-kbd-macro} to name the most recently +defined macro. + +@item +Emacs no longer displays your breakpoints in the source buffer, so you +have to remember where you left them. It can be difficult to inspect +the state of your debugged program from the command line, so Emacs +tries to demonstrate this in the GUD buffer. + +@item +The Calc, CUA, Ibuffer, Ido, Password, Printing, Reveal, +Ruler-mode, SES, Table, Tramp, and URL packages have been removed. +The Benchmark, Cfengine, Conf, Dns, Flymake, Python, Thumbs, and +Wdired modes have also been removed. + +@item +The Emacs Lisp Reference Manual and the Introduction to Programming in +Emacs Lisp are now distributed separately, not in the Emacs +distribution. + +@item +On MS Windows, there is no longer any support for tooltips, images, +sound, different mouse pointer shapes, or pointing devices with more +than 3 buttons. If you want these features, consider switching to +another operating system. But even if you don't want these features, +you should still switch---for freedom's sake. + +@item +Emacs will not use Unicode for clipboard operations on MS Windows. + +@item +To keep up with decreasing computer memory capacity and disk space, many +other functions and files have been eliminated in Emacs 21.4. +@end itemize + +@ignore + arch-tag: 32932bd9-46f5-41b2-8a0e-fb0cc4caeb29 +@end ignore diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi new file mode 100644 index 00000000000..c2b1ddc2ffe --- /dev/null +++ b/doc/emacs/arevert-xtra.texi @@ -0,0 +1,191 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@c +@c This file is included either in emacs-xtra.texi (when producing the +@c printed version) or in the main Emacs manual (for the on-line version). +@node Autorevert +@section Auto Reverting non-file Buffers + +Normally Global Auto Revert Mode only reverts file buffers. There are +two ways to auto-revert certain non-file buffers: enabling Auto Revert +Mode in those buffers (using @kbd{M-x auto-revert-mode}) and setting +@code{global-auto-revert-non-file-buffers} to @code{t}. The latter +enables Auto Reverting for all types of buffers for which it is +implemented, that is, for the types of buffers listed in the menu +below. + +Like file buffers, non-file buffers should normally not revert while +you are working on them, or while they contain information that might +get lost after reverting. Therefore, they do not revert if they are +``modified''. This can get tricky, because deciding when a non-file +buffer should be marked modified is usually more difficult than for +file buffers. + +Another tricky detail is that, for efficiency reasons, Auto Revert +often does not try to detect all possible changes in the buffer, only +changes that are ``major'' or easy to detect. Hence, enabling +auto-reverting for a non-file buffer does not always guarantee that +all information in the buffer is up to date and does not necessarily +make manual reverts useless. + +At the other extreme, certain buffers automatically auto-revert every +@code{auto-revert-interval} seconds. (This currently only applies to +the Buffer Menu.) In this case, Auto Revert does not print any +messages while reverting, even when @code{auto-revert-verbose} is +non-@code{nil}. + +The details depend on the particular types of buffers and are +explained in the corresponding sections. + +@menu +* Auto Reverting the Buffer Menu:: +* Auto Reverting Dired:: +* Supporting additional buffers:: +@end menu + +@node Auto Reverting the Buffer Menu +@subsection Auto Reverting the Buffer Menu + +If auto-reverting of non-file buffers is enabled, the Buffer Menu +automatically reverts every @code{auto-revert-interval} seconds, +whether there is a need for it or not. (It would probably take longer +to check whether there is a need than to actually revert.) + +If the Buffer Menu inappropriately gets marked modified, just revert +it manually using @kbd{g} and auto-reverting will resume. However, if +you marked certain buffers to get deleted or to be displayed, you have +to be careful, because reverting erases all marks. The fact that +adding marks sets the buffer's modified flag prevents Auto Revert from +automatically erasing the marks. + +@node Auto Reverting Dired +@subsection Auto Reverting Dired buffers + +Auto-reverting Dired buffers currently works on GNU or Unix style +operating systems. It may not work satisfactorily on some other +systems. + +Dired buffers only auto-revert when the file list of the buffer's main +directory changes. They do not auto-revert when information about a +particular file changes or when inserted subdirectories change. To be +sure that @emph{all} listed information is up to date, you have to +manually revert using @kbd{g}, @emph{even} if auto-reverting is +enabled in the Dired buffer. Sometimes, you might get the impression +that modifying or saving files listed in the main directory actually +does cause auto-reverting. This is because making changes to a file, +or saving it, very often causes changes in the directory itself, for +instance, through backup files or auto-save files. However, this is +not guaranteed. + +If the Dired buffer is marked modified and there are no changes you +want to protect, then most of the time you can make auto-reverting +resume by manually reverting the buffer using @kbd{g}. There is one +exception. If you flag or mark files, you can safely revert the +buffer. This will not erase the flags or marks (unless the marked +file has been deleted, of course). However, the buffer will stay +modified, even after reverting, and auto-reverting will not resume. +This is because, if you flag or mark files, you may be working on the +buffer and you might not want the buffer to change without warning. +If you want auto-reverting to resume in the presence of marks and +flags, mark the buffer non-modified using @kbd{M-~}. However, adding, +deleting or changing marks or flags will mark it modified again. + +Remote Dired buffers are not auto-reverted. Neither are Dired buffers +for which you used shell wildcards or file arguments to list only some +of the files. @samp{*Find*} and @samp{*Locate*} buffers do not +auto-revert either. + +@node Supporting additional buffers +@subsection Adding Support for Auto-Reverting additional Buffers. + +This section is intended for Elisp programmers who would like to add +support for auto-reverting new types of buffers. + +To support auto-reverting the buffer must first of all have a +@code{revert-buffer-function}. @xref{Definition of +revert-buffer-function,, Reverting, elisp, the Emacs Lisp Reference Manual}. + +In addition, it @emph{must} have a @code{buffer-stale-function}. + +@defvar buffer-stale-function +The value of this variable is a function to check whether a non-file +buffer needs reverting. This should be a function with one optional +argument @var{noconfirm}. The function should return non-@code{nil} +if the buffer should be reverted. The buffer is current when this +function is called. + +While this function is mainly intended for use in auto-reverting, it +could be used for other purposes as well. For instance, if +auto-reverting is not enabled, it could be used to warn the user that +the buffer needs reverting. The idea behind the @var{noconfirm} +argument is that it should be @code{t} if the buffer is going to be +reverted without asking the user and @code{nil} if the function is +just going to be used to warn the user that the buffer is out of date. +In particular, for use in auto-reverting, @var{noconfirm} is @code{t}. +If the function is only going to be used for auto-reverting, you can +ignore the @var{noconfirm} argument. + +If you just want to automatically auto-revert every +@code{auto-revert-interval} seconds, use: + +@example +(set (make-local-variable 'buffer-stale-function) + #'(lambda (&optional noconfirm) 'fast)) +@end example + +@noindent +in the buffer's mode function. + +The special return value @samp{fast} tells the caller that the need +for reverting was not checked, but that reverting the buffer is fast. +It also tells Auto Revert not to print any revert messages, even if +@code{auto-revert-verbose} is non-@code{nil}. This is important, as +getting revert messages every @code{auto-revert-interval} seconds can +be very annoying. The information provided by this return value could +also be useful if the function is consulted for purposes other than +auto-reverting. +@end defvar + +Once the buffer has a @code{revert-buffer-function} and a +@code{buffer-stale-function}, several problems usually remain. + +The buffer will only auto-revert if it is marked unmodified. Hence, +you will have to make sure that various functions mark the buffer +modified if and only if either the buffer contains information that +might be lost by reverting or there is reason to believe that the user +might be inconvenienced by auto-reverting, because he is actively +working on the buffer. The user can always override this by manually +adjusting the modified status of the buffer. To support this, calling +the @code{revert-buffer-function} on a buffer that is marked +unmodified should always keep the buffer marked unmodified. + +It is important to assure that point does not continuously jump around +as a consequence of auto-reverting. Of course, moving point might be +inevitable if the buffer radically changes. + +You should make sure that the @code{revert-buffer-function} does not +print messages that unnecessarily duplicate Auto Revert's own messages +if @code{auto-revert-verbose} is @code{t} and effectively override a +@code{nil} value for @code{auto-revert-verbose}. Hence, adapting a +mode for auto-reverting often involves getting rid of such messages. +This is especially important for buffers that automatically +auto-revert every @code{auto-revert-interval} seconds. + +Also, you may want to update the documentation string of +@code{global-auto-revert-non-file-buffers}. + +@ifinfo +Finally, you should add a node to this chapter's menu. This node +@end ifinfo +@ifnotinfo +Finally, you should add a section to this chapter. This section +@end ifnotinfo +should at the very least make clear whether enabling auto-reverting +for the buffer reliably assures that all information in the buffer is +completely up to date (or will be after @code{auto-revert-interval} +seconds). + +@ignore + arch-tag: 2983e613-a272-45f6-9593-3010ad7f865e +@end ignore diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi new file mode 100644 index 00000000000..333985e4a4a --- /dev/null +++ b/doc/emacs/basic.texi @@ -0,0 +1,776 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 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 + Here we explain the basics of how to enter text, make corrections, +and save the text in a file. If this material is new to you, we +suggest you first run the Emacs learn-by-doing tutorial, by typing +@kbd{Control-h t} inside Emacs. (@code{help-with-tutorial}). + + To clear and redisplay the screen, type @kbd{C-l} (@code{recenter}). + +@menu + +* Inserting Text:: Inserting text by simply typing it. +* Moving Point:: Moving the cursor to the place where you want to + change something. +* Erasing:: Deleting and killing text. +* Basic 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:: Making and deleting blank lines. +* Continuation Lines:: How Emacs displays lines too wide for the screen. +* Position Info:: What page, line, row, or column is point on? +* Arguments:: Numeric arguments for repeating a command N times. +* Repeating:: Repeating the previous command quickly. +@end menu + +@node Inserting Text +@section Inserting Text + +@cindex insertion +@cindex graphic characters + Typing printing characters inserts them into the text you are +editing. It inserts them into the buffer at the cursor; more +precisely, it inserts them at @dfn{point}, but the cursor normally +shows where point is. @xref{Point}. + + Insertion moves the cursor forward, and the following text moves +forward with the cursor. If the text in the buffer is @samp{FOOBAR}, +with the cursor before the @samp{B}, and 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 the large key +labeled @key{DEL}, @key{BACKSPACE} or @key{DELETE} which is a short +distance above the @key{RET} or @key{ENTER} key. Regardless of the +label on that key, Emacs thinks of it as @key{DEL}, and that's what we +call it in this manual. @key{DEL} is the key you normally use outside +Emacs to erase the last character that you typed. + + The @key{DEL} key deletes the character @emph{before} the cursor. +As a consequence, the cursor and all the characters after it move +backwards. If you type a printing character and then type @key{DEL}, +they cancel out. + + On most computers, Emacs sets up @key{DEL} automatically. In some +cases, especially with text-only terminals, Emacs may guess wrong. If +the key that ought to erase the last character doesn't do it in Emacs, +see @ref{DEL Does Not Delete}. + + Most PC keyboards have both a @key{BACKSPACE} key a little ways +above @key{RET} or @key{ENTER}, and a @key{DELETE} key elsewhere. On +these keyboards, Emacs tries to set up @key{BACKSPACE} as @key{DEL}. +The @key{DELETE} key deletes ``forwards'' like @kbd{C-d} (see below), +which means it deletes the character underneath the cursor (after +point). + +@kindex RET +@cindex newline + To end a line and start typing a new one, type @key{RET}. (This +key may be labeled @key{RETURN} or @key{ENTER}, but in Emacs we call +it @key{RET}.) This inserts a newline character in the buffer. If +point is at the end of the line, this creates a new blank line after +it. If point is in the middle of a line, the effect is to split that +line. Typing @key{DEL} when the cursor is at the beginning of a line +deletes the preceding newline character, thus joining the line with +the one before it. + + 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 Auto Fill mode and other methods of @dfn{filling} +text. + + If you prefer printing characters to replace (overwrite) existing +text, rather than shove it to the right, you should enable Overwrite +mode, a minor mode. @xref{Minor Modes}. + +@cindex quoting +@kindex C-q +@findex quoted-insert + Only printing characters and @key{SPC} insert themselves in Emacs. +Other characters act as editing commands and do not insert themselves. +These include control characters, and characters with codes above 200 +octal. If you need to insert one of these characters in the buffer, +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}: + +@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 terminates the sequence and then acts +as normal input---thus, @kbd{C-q 1 0 1 B} inserts @samp{AB}. + +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 + +@cindex 8-bit character codes +@noindent +When multibyte characters are enabled, if you specify a code in the +range 0200 through 0377 octal, @kbd{C-q} assumes that you intend to +use some ISO 8859-@var{n} character set, and converts the specified +code to the corresponding Emacs character code. @xref{Enabling +Multibyte}. You select @emph{which} of the ISO 8859 character sets to +use through 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 tells @kbd{C-q} how many copies of the quoted +character to insert (@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 you typed. Some +major modes rebind @key{DEL} to other commands. + +@node Moving Point +@section Changing the Location of Point + +@cindex arrow keys +@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 (it is faster to use these control +keys than move your hand over to the arrow keys). 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 +@kindex LEFT +@kindex RIGHT +@kindex UP +@kindex DOWN +@findex move-beginning-of-line +@findex move-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{move-beginning-of-line}). +@item C-e +Move to the end of the line (@code{move-end-of-line}). +@item C-f +Move forward one character (@code{forward-char}). The right-arrow key +does the same thing. +@item C-b +Move backward one character (@code{backward-char}). The left-arrow +key has the same effect. +@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 move to the middle of the next. The +down-arrow key does the same thing. +@item C-p +Move up one line, vertically (@code{previous-line}). The up-arrow key +has the same effect. This command preserves position within the line, +like @kbd{C-n}. +@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, counting +downward from the top of the window (zero means the top line). A +negative argument counts lines up from the bottom (@minus{}1 means 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 C-v +@itemx @key{PAGEDOWN} +@itemx @key{PRIOR} +Scroll the display one screen forward, and move point if necessary to +put it on the screen (@code{scroll-up}). This doesn't always move +point, but it is commonly used to do so. If your keyboard has a +@key{PAGEDOWN} or @key{PRIOR} key, it does the same thing. + +Scrolling commands are described further in @ref{Scrolling}. +@item M-v +@itemx @key{PAGEUP} +@itemx @key{NEXT} +Scroll one screen backward, and move point if necessary to put it on +the screen (@code{scroll-down}). This doesn't always move point, but +it is commonly used to do so. If your keyboard has a @key{PAGEUP} or +@key{NEXT} key, it does the same thing. +@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-g M-g +@itemx M-g g +@itemx M-x goto-line +Read a number @var{n} and move point to the beginning of line number +@var{n}. Line 1 is the beginning of the buffer. If point is on or +just after a number in the buffer, and you type @key{RET} with the +minibuffer empty, that number is used for @var{n}. +@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}). When a +semipermanent goal column is in effect, those commands always try to +move to this column, or as close as possible to it, after moving +vertically. The 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} try to +preserve the 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 starting at the end of the 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 + @kbd{C-n} normally stops at the end of the buffer when you use it on +the last line of the buffer. However, if you set the variable +@code{next-line-add-newlines} to a non-@code{nil} value, @kbd{C-n} on +the last line of a buffer creates an additional line at the end and +moves down into it. + +@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 @key{DELETE} +@itemx @key{BACKSPACE} +One of these keys, whichever is the large key above the @key{RET} or +@key{ENTER} key, deletes the character before point---it is @key{DEL}. +If @key{BACKSPACE} is @key{DEL}, and your keyboard also has @key{DELETE}, +then @key{DELETE} deletes forwards, like @kbd{C-d}. +@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 that line with the following line. + + To erase a larger amount of text, use the @kbd{C-k} key, which +erases (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 with the following line. + + @xref{Killing}, for more flexible ways of killing text. + +@node Basic Undo +@section Undoing Changes + + Emacs records a list of changes made in the buffer text, so you can +you can undo recent changes, as far as the records go. +Usually each editing command makes a separate entry in the undo +records, but sometimes an entry covers just part of a command, and +very simple commands may be grouped. + +@table @kbd +@item C-x u +Undo one entry of the undo records---usually, one command worth +(@code{undo}). +@item C-_ +@itemx C-/ +The same. +@end table + + The command @kbd{C-x u} (or @kbd{C-_} or @kbd{C-/}) is how you undo. +Normally this command undoes the last change, and moves point back to +where it was before the change. + + If you repeat @kbd{C-x u} (or its aliases), each repetition undoes +another, earlier change, back to the limit of the undo information +available. If all recorded changes have already been undone, the undo +command displays an error message and does nothing. + + The undo command applies only to changes in the buffer; you can't +use it to undo mere cursor motion. 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}). + +@node Basic Files +@section Files + + Text that you insert in an Emacs buffer lasts only as long as the +Emacs session. 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 use the +contents of a file in any way, you must specify the file name. That +includes editing the file with Emacs. + + Suppose there is a file named @file{test.emacs} in your home +directory. To begin editing this file in Emacs, type + +@example +C-x C-f test.emacs @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}). + + Emacs obeys this command by @dfn{visiting} the file: it creates a +buffer, it copies the contents of the file into the buffer, and then +displays the buffer for editing. 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 copies the altered buffer contents back +into the file @file{test.emacs}, making them permanent. Until you +save, the changed text exists only inside Emacs, and the file +@file{test.emacs} is unaltered. + + To create a file, just visit it 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. Emacs actually creates the file the +first time you save this buffer with @kbd{C-x C-s}. + + To learn more about using files in Emacs, see @ref{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 of interest; for +example, @kbd{C-h k C-n} tells you 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}. + +@node Blank Lines +@section Blank Lines + +@cindex inserting blank lines +@cindex deleting blank lines + Here are special commands and techniques for inserting and deleting +blank lines. + +@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 + To insert a new line of text before an existing line, +type 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 specifying how many blank lines to make. +@xref{Arguments}, for how. If you have a fill prefix, the @kbd{C-o} +command inserts the fill prefix on the new line, if typed 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 +lone blank line deletes that one. When point is on a nonblank line, +@kbd{C-x C-o} deletes all following blank lines (if any). + +@node Continuation Lines +@section Continuation Lines + +@cindex continuation line +@cindex wrapping +@cindex line wrapping +@cindex fringes, and continuation lines + When a text line is too long to fit in one screen line, Emacs +displays it on two or more screen lines. This is called +@dfn{continuation} or @dfn{line wrapping}. On graphical displays, +Emacs indicates line wrapping with small bent arrows in the left and +right window fringes. On text-only terminals, Emacs displays a +@samp{\} character at the right margin of a screen line if it is not +the last in its text line. This @samp{\} character says that the +following screen line is not really a new text line. + + When line wrapping occurs just before a character that is wider than one +column, some columns at the end of the previous screen line may be +``empty.'' In this case, Emacs displays additional @samp{\} +characters in the ``empty'' columns before the @samp{\} +character that indicates continuation. + + Continued lines can be difficult to read, since lines can break in +the middle of a word. If you prefer, you can make Emacs insert a +newline automatically when a line gets too long, by using Auto Fill +mode. Or enable Long Lines mode, which ensures that wrapping only +occurs between words. @xref{Filling}. + +@cindex truncation +@cindex line truncation, and fringes + Emacs can optionally @dfn{truncate} long lines---this means +displaying just one screen line worth, and the rest of the long line +does not appear at all. @samp{$} in the last column or a small +straight arrow in the window's right fringe indicates a truncated +line. + + @xref{Line Truncation}, for more about line truncation, +and other variables that control 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 +Display the page number of point, and the line number within that page. +@item M-x what-line +Display the line number of point in the whole buffer. +@item M-x line-number-mode +@itemx M-x column-number-mode +Toggle automatic display of the current line number or column number. +@xref{Optional Mode Line}. +@item M-= +Display the number of lines in the current region (@code{count-lines-region}). +@xref{Mark}, for information about the region. +@item C-x = +Display the character code of character after point, character position of +point, and column of point (@code{what-cursor-position}). +@item M-x hl-line-mode +Enable or disable highlighting of the current line. @xref{Cursor +Display}. +@item M-x size-indication-mode +Toggle automatic display of the size of the buffer. +@xref{Optional Mode Line}. +@end table + +@findex what-page +@findex what-line +@cindex line number commands +@cindex location of point +@cindex cursor location +@cindex point location + @kbd{M-x what-line} displays the current line number +in the echo area. You can also see the current line number in the +mode line; see @ref{Mode Line}; but if you narrow the buffer, 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. + + @kbd{M-x what-page} counts pages from the beginning of the file, and +counts lines within the page, showing both numbers in the echo area. +@xref{Pages}. + +@kindex M-= +@findex count-lines-region + Use @kbd{M-=} (@code{count-lines-region}) to displays 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}) shows what +cursor's column position, and other information about point and the +character after it. It displays a line in the echo area that looks +like this: + +@smallexample +Char: c (99, #o143, #x63) point=28062 of 36168 (78%) column=53 +@end smallexample + + The four values after @samp{Char:} describe the character that follows +point, first by showing it and then by giving its character code in +decimal, octal and hex. For a non-@acronym{ASCII} multibyte character, these are +followed by @samp{file} 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{file ...}. + + However, if the character displayed is in the range 0200 through +0377 octal, it may actually stand for an invalid UTF-8 byte read from +a file. In Emacs, that byte is represented as a sequence of 8-bit +characters, but all of them together display as the original invalid +byte, in octal code. In this case, @kbd{C-x =} shows @samp{part of +display ...} instead of @samp{file}. + + @samp{point=} is followed by the position of point expressed as a +character count. The start of the buffer is position 1, one character +later is position 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 =} displays +additional text describing the currently accessible range. For example, it +might display this: + +@smallexample +Char: C (67, #o103, #x43) 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=36169 of 36168 (EOB) column=0 +@end smallexample + +@cindex character set of character at point +@cindex font of character at point +@cindex text properties at point +@cindex face at point + @w{@kbd{C-u C-x =}} displays the following additional information about a +character. + +@itemize @bullet +@item +The character set name, and the codes that identify the character +within that character set; @acronym{ASCII} characters are identified +as belonging to the @code{ascii} character set. + +@item +The character's syntax and categories. + +@item +The character's encodings, both internally in the buffer, and externally +if you were to save the file. + +@item +What keys to type to input the character in the current input method +(if it supports the character). + +@item +If you are running Emacs on a graphical display, the font name and +glyph code for the character. If you are running Emacs on a text-only +terminal, the code(s) sent to the terminal. + +@item +The character's text properties (@pxref{Text Properties,,, +elisp, the Emacs Lisp Reference Manual}), including any non-default +faces used to display the character, and any overlays containing it +(@pxref{Overlays,,, elisp, the same manual}). +@end itemize + + Here's an example showing the Latin-1 character A with grave accent, +in a buffer whose coding system is @code{iso-latin-1}, whose +terminal coding system is @code{iso-latin-1} (so the terminal actually +displays the character as @samp{@`A}), and which has font-lock-mode +(@pxref{Font Lock}) enabled: + +@smallexample + character: @`A (2240, #o4300, #x8c0, U+00C0) + charset: latin-iso8859-1 + (Right-Hand Part of Latin Alphabet 1@dots{} + code point: #x40 + syntax: w which means: word + category: l:Latin + to input: type "`A" with latin-1-prefix +buffer code: #x81 #xC0 + file code: #xC0 (encoded by coding system iso-latin-1) + display: terminal code #xC0 + +There are text properties here: + fontified t +@end smallexample + +@node Arguments +@section Numeric Arguments +@cindex numeric arguments +@cindex prefix arguments +@cindex arguments to commands + + In mathematics and computer usage, @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 (labeled @key{ALT} on +PC keyboards), 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 +moves 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 set up an argument for the next command. +@kbd{Meta--} without digits normally means @minus{}1. Digits and +@kbd{-} modified with Control, or Control and Meta, also specify numeric +arguments. + +@kindex C-u +@findex universal-argument + You can also specify a numeric argument by typing @kbd{C-u} +(@code{universal-argument}) followed by the digits. The advantage of +@kbd{C-u} is that you can type the digits without modifier keys; thus, +@kbd{C-u} works on all terminals. For a negative argument, type a +minus sign after @kbd{C-u}. A minus sign without digits normally +means @minus{}1. + + @kbd{C-u} alone has the special meaning of +``four times'': it multiplies the argument for the next command by +four. @kbd{C-u C-u} 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). + + Some commands care whether there is an argument, but ignore its +value. For example, the command @kbd{M-q} (@code{fill-paragraph}) +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}.) + + 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 exist to make an individual command +more convenient, and they are documented in that command's +documentation string. + + You can use a numeric argument before a self-inserting character to +insert multiple copies of it. This is straightforward when the +character is not 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. You +can separate the argument from the digit to insert with 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 these argument before the command, and to +distinguish them from minibuffer arguments that come after the +command. + +@node Repeating +@section Repeating a Command +@cindex repeating a command + + Many simple commands, such as those invoked with a single key or +with @kbd{M-x @var{command-name} @key{RET}}, can be repeated by +invoking them with a numeric argument that serves as a repeat count +(@pxref{Arguments}). However, if the command you want to repeat +prompts for input, or uses a numeric argument in another way, that +method won't work. + +@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. + +@ignore + arch-tag: cda8952a-c439-41c1-aecf-4bc0d6482956 +@end ignore diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi new file mode 100644 index 00000000000..b43d72b1067 --- /dev/null +++ b/doc/emacs/buffers.texi @@ -0,0 +1,665 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 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{current}. It is also +called the @dfn{selected 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 current buffer (most commands do). + + When Emacs has multiple windows, each window has its own chosen +buffer and displays it; at any time, only one of the windows is +selected, and its chosen buffer is the current buffer. Each window's +mode line normally displays the name of the window's chosen buffer +(@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}. + +@cindex buffer size, maximum + A buffer's size cannot be larger than some maximum, which is defined +by the largest buffer position representable by the @dfn{Emacs integer} +data type. This is because Emacs tracks buffer positions using that +data type. For 32-bit machines, the largest buffer size is 256 +megabytes. + +@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. +* Buffer Convenience:: Convenience and customization features for + buffer handling. +@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}). +@item C-x @key{LEFT} +Select the previous buffer in the list of existing buffers. +@item C-x @key{RIGHT} +Select the next buffer in the list of existing buffers. +@item C-u M-g M-g +@itemx C-u M-g g +Read a number @var{n} and move to line @var{n} in the most recently +selected buffer other than the current buffer. +@end table + +@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 to enter the buffer +name (@pxref{Completion}). An empty argument to @kbd{C-x b} +specifies the buffer that was current most recently among those not +now displayed in any window. + +@kindex C-x @key{LEFT} +@kindex C-x @key{RIGHT} +@findex next-buffer +@findex previous-buffer + For conveniently switching between a few buffers, use the commands +@kbd{C-x @key{LEFT}} and @kbd{C-x @key{RIGHT}}. @kbd{C-x @key{RIGHT}} +(@code{previous-buffer}) selects the previous buffer (following the order +of most recent selection in the current frame), while @kbd{C-x @key{LEFT}} +(@code{next-buffer}) moves through buffers in the reverse direction. + +@kindex C-x 4 b +@findex switch-to-buffer-other-window +@vindex even-window-heights + To select a buffer in a window other than the current one, type +@kbd{C-x 4 b @var{bufname} @key{RET}}. This runs the command +@code{switch-to-buffer-other-window} which displays the buffer +@var{bufname} in another window. By default, if displaying the buffer +causes two vertically adjacent windows to be displayed, the heights of +those windows are evened out; to countermand that and preserve the +window configuration, set the variable @code{even-window-heights} to +@code{nil}. + +@kindex C-x 5 b +@findex switch-to-buffer-other-frame + Similarly, @kbd{C-x 5 b @var{buffer} @key{RET}} runs the command +@code{switch-to-buffer-other-frame} which selects a buffer in another +frame. + +@vindex display-buffer-reuse-frames + You can control how certain buffers are handled by these commands by +customizing the variables @code{special-display-buffer-names}, +@code{special-display-regexps}, @code{same-window-buffer-names}, and +@code{same-window-regexps}. See @ref{Force Same Window}, and +@ref{Special Buffer Frames}, for more about these variables. In +addition, if the value of @code{display-buffer-reuse-frames} is +non-@code{nil}, and the buffer you want to switch to is already +displayed in some frame, Emacs will just raise that frame. + + 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}. + + @kbd{C-u M-g M-g}, that is @code{goto-line} with a prefix argument +of just @kbd{C-u}, reads a number @var{n} using the minibuffer, +selects the most recently selected buffer other than the current +buffer in another window, and then moves point to the beginning of +line number @var{n} in that buffer. This is mainly useful in a buffer +that refers to line numbers in another buffer: if point is on or just +after a number, @code{goto-line} uses that number as the default for +@var{n}. Note that prefix arguments other than just @kbd{C-u} behave +differently. @kbd{C-u 4 M-g M-g} goes to line 4 in the @emph{current} +buffer, without reading a number from the minibuffer. (Remember that +@kbd{M-g M-g} without prefix argument reads a number @var{n} and then +moves to line number @var{n} in the current buffer.) + + 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 existing buffers, 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{*} in the first field 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{Save Commands}). @samp{%} indicates a +read-only buffer. @samp{.} marks the current buffer. Here is an +example of a buffer list:@refill + +@smallexample +CRM Buffer Size Mode File +. * .emacs 3294 Emacs-Lisp ~/.emacs + % *Help* 101 Help + search.c 86055 C ~/cvs/emacs/src/search.c + % src 20959 Dired by name ~/cvs/emacs/src/ + * *mail* 42 Mail + % HELLO 1607 Fundamental ~/cvs/emacs/etc/HELLO + % NEWS 481184 Outline ~/cvs/emacs/etc/NEWS + *scratch* 191 Lisp Interaction + * *Messages* 1554 Fundamental +@end smallexample + +@noindent +Note that the buffer @samp{*Help*} was made by a help request; it is +not visiting any file. The buffer @code{src} was made by Dired on the +directory @file{~/cvs/emacs/src/}. You can list only buffers that are +visiting files by giving the command a prefix argument, as in +@kbd{C-u C-x C-b}. + + @code{list-buffers} omits buffers whose names begin with a space, +unless they visit files: such buffers are used internally by Emacs. + +@need 2000 +@node Misc Buffer +@section Miscellaneous Buffer Operations + +@table @kbd +@item C-x C-q +Toggle read-only status of buffer (@code{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 +@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. + +@findex toggle-read-only + If you wish to make changes in a read-only buffer, use the command +@kbd{C-x C-q} (@code{toggle-read-only}). It makes a read-only buffer +writable, and makes a writable buffer read-only. 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 you have files under version control, you may find +it convenient to bind @kbd{C-x C-q} to @code{vc-toggle-read-only} +instead. Then, typing @kbd{C-x C-q} not only changes the read-only +flag, but it also checks the file in or out. @xref{Version +Control}. + +@findex rename-buffer + @kbd{M-x rename-buffer} changes the name of the current buffer. You +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. + +@findex rename-uniquely + @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. (With some of these features, such as +@kbd{M-x compile}, @kbd{M-x grep} an @kbd{M-x info}, you need to +switch to some other buffer before using the command, in order for it +to make a different buffer.) + +@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}. + +@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: + +@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 becomes current: one that was +current in the recent past but is not displayed 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. +@item M-x buffer-menu-other-window. +Similar, but do it in another window. +@end table + +@findex buffer-menu +@findex buffer-menu-other-window + The command @code{buffer-menu} writes a list of all Emacs +buffers@footnote{Buffers which don't visit files and whose names begin +with a space are omitted: these are used internally by Emacs.} 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 selected in +one, and the previously current buffer (aside from the buffer +@samp{*Buffer List*}) displayed 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 + + There is also a command that affects the entire buffer list: + +@table @kbd +@item T +Delete, or reinsert, lines for non-file buffers. This command toggles +the inclusion of such buffers in the buffer list. +@end table + + What @code{buffer-menu} actually does is create and switch to a +suitable buffer, and turn on Buffer Menu mode in it. 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 list in the @samp{*Buffer List*} buffer looks exactly like the +buffer list described in @ref{List Buffers}, because they really are +the same. 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 the same buffer 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. + + Normally, 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}). You can make this happen regularly +every @code{auto-revert-interval} seconds if you enable Auto Revert +mode in this buffer, as long as it is not marked modified. Global +Auto Revert mode applies to the @samp{*Buffer List*} buffer only if +@code{global-auto-revert-non-file-buffers} is non-@code{nil}. +@iftex +@inforef{Autorevert,, emacs-xtra}, for details. +@end iftex +@ifnottex +@xref{Autorevert, global-auto-revert-non-file-buffers}, for details. +@end ifnottex + + + The command @code{buffer-menu-other-window} works the same as +@code{buffer-menu}, except that it displays the buffers list in +another window. + +@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 @key{RET} @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}. +@findex clone-indirect-buffer +@item M-x clone-indirect-buffer @key{RET} +Create an indirect buffer that is a twin copy of the current buffer. +@item C-x 4 c +@kindex C-x 4 c +@findex clone-indirect-buffer-other-window +Create an indirect buffer that is a twin copy of the current buffer, and +select it in another window (@code{clone-indirect-buffer-other-window}). +@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}. + + A quick and handy way to make an indirect buffer is with the command +@kbd{M-x clone-indirect-buffer}. It creates and selects an indirect +buffer whose base buffer is the current buffer. With a numeric +argument, it prompts for the name of the indirect buffer; otherwise it +uses the name of the current buffer, with a @samp{<@var{n}>} suffix +added. @kbd{C-x 4 c} (@code{clone-indirect-buffer-other-window}) +works like @kbd{M-x clone-indirect-buffer}, but it selects the new +buffer in another window. + + The more general way to make an indirect buffer is with the command +@kbd{M-x make-indirect-buffer}. It creates an indirect buffer from +buffer @var{base-buffer}, under the name @var{indirect-name}. It +prompts for both @var{base-buffer} and @var{indirect-name} using the +minibuffer. + +@node Buffer Convenience +@section Convenience Features and Customization of Buffer Handling + + This section describes several modes and features that make it more +convenient to switch between buffers. + +@menu +* Uniquify:: Making buffer names unique with directory parts. +* Iswitchb:: Switching between buffers with substrings. +* Buffer Menus:: Configurable buffer menu. +@end menu + +@node Uniquify +@subsection Making Buffer Names Unique + +@cindex unique buffer names +@cindex directories in buffer names + When several buffers visit identically-named files, Emacs must give +the buffers distinct names. The usual method for making buffer names +unique adds @samp{<2>}, @samp{<3>}, etc. to the end of the buffer +names (all but one of them). + +@vindex uniquify-buffer-name-style + Other methods work by adding parts of each file's directory to the +buffer name. To select one, customize the variable +@code{uniquify-buffer-name-style} (@pxref{Easy Customization}). + + To begin with, the @code{forward} naming method includes part of the +file's directory name at the beginning of the buffer name; using this +method, buffers visiting the files @file{/u/rms/tmp/Makefile} and +@file{/usr/projects/zaphod/Makefile} would be named +@samp{tmp/Makefile} and @samp{zaphod/Makefile}, respectively (instead +of @samp{Makefile} and @samp{Makefile<2>}). + + In contrast, the @code{post-forward} naming method would call the +buffers @samp{Makefile|tmp} and @samp{Makefile|zaphod}, and the +@code{reverse} naming method would call them @samp{Makefile\tmp} and +@samp{Makefile\zaphod}. The nontrivial difference between +@code{post-forward} and @code{reverse} occurs when just one directory +name is not enough to distinguish two files; then @code{reverse} puts +the directory names in reverse order, so that @file{/top/middle/file} +becomes @samp{file\middle\top}, while @code{post-forward} puts them in +forward order after the file name, as in @samp{file|top/middle}. + + Which rule to follow for putting the directory names in the buffer +name is not very important if you are going to @emph{look} at the +buffer names before you type one. But as an experienced user, if you +know the rule, you won't have to look. And then you may find that one +rule or another is easier for you to remember and apply quickly. + +@node Iswitchb +@subsection Switching Between Buffers using Substrings + +@findex iswitchb-mode +@cindex Iswitchb mode +@cindex mode, Iswitchb +@kindex C-x b @r{(Iswitchb mode)} +@kindex C-x 4 b @r{(Iswitchb mode)} +@kindex C-x 5 b @r{(Iswitchb mode)} +@kindex C-x 4 C-o @r{(Iswitchb mode)} + + Iswitchb global minor mode provides convenient switching between +buffers using substrings of their names. It replaces the normal +definitions of @kbd{C-x b}, @kbd{C-x 4 b}, @kbd{C-x 5 b}, and @kbd{C-x +4 C-o} with alternative commands that are somewhat ``smarter.'' + + When one of these commands prompts you for a buffer name, you can +type in just a substring of the name you want to choose. As you enter +the substring, Iswitchb mode continuously displays a list of buffers +that match the substring you have typed. + + At any time, you can type @key{RET} to select the first buffer in +the list. So the way to select a particular buffer is to make it the +first in the list. There are two ways to do this. You can type more +of the buffer name and thus narrow down the list, excluding unwanted +buffers above the desired one. Alternatively, you can use @kbd{C-s} +and @kbd{C-r} to rotate the list until the desired buffer is first. + + @key{TAB} while entering the buffer name performs completion on the +string you have entered, based on the displayed list of buffers. + + To enable Iswitchb mode, type @kbd{M-x iswitchb-mode}, or customize +the variable @code{iswitchb-mode} to @code{t} (@pxref{Easy +Customization}). + +@node Buffer Menus +@subsection Customizing Buffer Menus + +@findex bs-show +@cindex buffer list, customizable +@table @kbd +@item M-x bs-show +Make a list of buffers similarly to @kbd{M-x list-buffers} but +customizable. +@end table + + @kbd{M-x bs-show} pops up a buffer list similar to the one normally +displayed by @kbd{C-x C-b} but which you can customize. If you prefer +this to the usual buffer list, you can bind this command to @kbd{C-x +C-b}. To customize this buffer list, use the @code{bs} Custom group +(@pxref{Easy Customization}). + +@findex msb-mode +@cindex mode, MSB +@cindex MSB mode +@cindex buffer menu +@findex mouse-buffer-menu +@kindex C-Down-Mouse-1 + MSB global minor mode (``MSB'' stands for ``mouse select buffer'') +provides a different and customizable mouse buffer menu which you may +prefer. It replaces the bindings of @code{mouse-buffer-menu}, +normally on @kbd{C-Down-Mouse-1}, and the menu bar buffer menu. You +can customize the menu in the @code{msb} Custom group. + +@ignore + arch-tag: 08c43460-f4f4-4b43-9cb5-1ea9ad991695 +@end ignore diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi new file mode 100644 index 00000000000..62e5f7b4316 --- /dev/null +++ b/doc/emacs/building.texi @@ -0,0 +1,1440 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Building, Maintaining, 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 compiling and testing programs. + +@menu +* Compilation:: Compiling programs in languages other + than Lisp (C, Pascal, etc.). +* Compilation Mode:: The mode for visiting compiler errors. +* Compilation Shell:: Customizing your shell properly + for use in the compilation buffer. +* Grep Searching:: Searching with grep. +* Flymake:: Finding syntax errors on the fly. +* 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. +* Eval: Lisp Eval. Executing a single Lisp expression in Emacs. +* Interaction: Lisp Interaction. Executing Lisp in an Emacs buffer. +* 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 going to +the @samp{*compilation*} buffer. +@item M-x recompile +Invoke a compiler with the same command as in the last invocation of +@kbd{M-x compile}. +@item M-x kill-compilation +Kill the running compilation 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 + The default for the compilation command is normally @samp{make -k}, +which is correct most of the time for nontrivial programs. +(@xref{Top,, Make, make, GNU Make Manual}.) If you have done @kbd{M-x +compile} before, the default each time is the command you used the +previous time. @code{compile} stores this command in the variable +@code{compile-command}, so setting that variable specifies the default +for the next use of @kbd{M-x compile}. If a file specifies a file +local value for @code{compile-command}, that provides the default when +you type @kbd{M-x compile} in that file's buffer. @xref{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}, +@samp{signal} 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. + +@cindex compilation buffer, keeping point at end +@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 recompile + To rerun the last compilation with the same command, type @kbd{M-x +recompile}. This automatically reuses the compilation command from +the last invocation of @kbd{M-x compile}. It also reuses the +@samp{*compilation*} buffer and starts the compilation in its default +directory, which is the directory in which the previous compilation +was started. + + When the compiler process terminates, for whatever reason, the mode +line of the @samp{*compilation*} buffer changes to say @samp{exit} +(followed by the exit code, @samp{[0]} for a normal exit), or +@samp{signal} (if a signal terminated the process), instead of +@samp{run}. + +@findex kill-compilation + Starting a new compilation also kills any compilation already +running in @samp{*compilation*}, as the buffer can only handle one +compilation at any time. However, @kbd{M-x compile} asks for +confirmation before actually killing a compilation that is running. +You can also kill the compilation process with @kbd{M-x +kill-compilation}. + + If you want to run two compilations at once, you should start the +first one, then rename the @samp{*compilation*} buffer (perhaps using +@code{rename-uniquely}; @pxref{Misc Buffer}), and start the other +compilation. That will create a new @samp{*compilation*} buffer. + + Emacs does not expect a compiler process to launch asynchronous +subprocesses; if it does, and they keep running after the main +compiler process has terminated, Emacs may kill them or their output +may not arrive in Emacs. To avoid this problem, make the main process +wait for its subprocesses to finish. In a shell script, you can do this +using @samp{$!} and @samp{wait}, like this: + +@example +(sleep 10; echo 2nd)& pid=$! # @r{Record pid of subprocess} +echo first message +wait $pid # @r{Wait for subprocess} +@end example + + If the background process does not output to the compilation buffer, +so you only need to prevent it from being killed when the main +compilation process terminates, this is sufficient: + +@example +nohup @var{command}; sleep 1 +@end example + +@vindex compilation-environment + You can control the environment passed to the compilation command +with the variable @code{compilation-environment}. Its value is a list +of environment variable settings; each element should be a string of +the form @code{"@var{envvarname}=@var{value}"}. These environment +variable settings override the usual ones. + +@node Compilation Mode +@section Compilation Mode + +@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 +visit the source line corresponding to an error message. These +commands are also available in other special buffers that list +locations in files, including those made by @kbd{M-x grep} and +@kbd{M-x occur}. + +@table @kbd +@item M-g M-n +@itemx M-g n +@itemx C-x ` +Visit the locus of the next error message or match. +@item M-g M-p +@itemx M-g p +Visit the locus of the previous error message or 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. +@item M-n +Find and highlight the locus of the next error message, without +selecting the source buffer. +@item M-p +Find and highlight the locus of the previous error message, without +selecting the source buffer. +@item M-@} +Move point to the next error for a different file than the current +one. +@item M-@{ +Move point to the previous error for a different file than the current +one. +@item C-c C-f +Toggle Next Error Follow minor mode, which makes cursor motion in the +compilation buffer produce automatic source display. +@end table + +@findex compile-goto-error + You can visit the source for any particular error message by moving +point in the @samp{*compilation*} buffer to that error message and +typing @key{RET} (@code{compile-goto-error}). Alternatively, you can +click @kbd{Mouse-2} on the error message; you need not switch to the +@samp{*compilation*} buffer first. + +@kindex M-g M-n +@kindex M-g n +@kindex C-x ` +@findex next-error +@vindex next-error-highlight + 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. It also temporarily +highlights the relevant source line, for a period controlled by the +variable @code{next-error-highlight}. + + The first time @w{@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 @w{@kbd{C-x `}} +commands advance from there. When @w{@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. @w{@kbd{C-u C-x `}} starts scanning from the beginning of +the compilation buffer, and goes to the first error's location. + +@vindex compilation-skip-threshold + By default, @w{@kbd{C-x `}} skips less important messages. The variable +@code{compilation-skip-threshold} controls this. If its value is 2, +@w{@kbd{C-x `}} skips anything less than error, 1 skips anything less +than warning, and 0 doesn't skip any messages. The default is 1. + + When the window has a left fringe, an arrow in the fringe points to +the current message in the compilation buffer. The variable +@code{compilation-context-lines} controls the number of lines of +leading context to display before the current message. Going to an +error message location scrolls the @samp{*compilation*} buffer to put +the message that far down from the top. The value @code{nil} is +special: if there's a left fringe, the window doesn't scroll at all +if the message is already visible. If there is no left fringe, +@code{nil} means display the message at the top of the window. + + If you're not in the compilation buffer when you run +@code{next-error}, Emacs will look for a buffer that contains error +messages. First, it looks for one displayed in the selected frame, +then for one that previously had @code{next-error} called on it, and +then at the current buffer. Finally, Emacs looks at all the remaining +buffers. @code{next-error} signals an error if it can't find any such +buffer. + +@vindex compilation-error-regexp-alist +@vindex grep-regexp-alist + To parse messages from the compiler, Compilation mode uses the +variable @code{compilation-error-regexp-alist} which lists various +formats of error messages and tells Emacs how to extract the source file +and the line number from the text of a message. If your compiler isn't +supported, you can tailor Compilation mode to it by adding elements to +that list. A similar variable @code{grep-regexp-alist} tells Emacs how +to parse output of a @code{grep} command. + +@findex compilation-next-error +@findex compilation-previous-error +@findex compilation-next-file +@findex compilation-previous-file + Compilation mode also redefines the keys @key{SPC} and @key{DEL} to +scroll by screenfuls, and @kbd{M-n} (@code{compilation-next-error}) +and @kbd{M-p} (@code{compilation-previous-error}) to move to the next +or previous error message. You can also use @kbd{M-@{} +(@code{compilation-next-file} and @kbd{M-@}} +(@code{compilation-previous-file}) to move up or down to an error +message for a different source file. + +@cindex Next Error Follow mode +@findex next-error-follow-minor-mode + You can type @kbd{C-c C-f} to toggle Next Error Follow mode. In +this minor mode, ordinary cursor motion in the compilation buffer +automatically updates the source buffer. For instance, moving the +cursor to the next error message causes the location of that error to +be displayed immediately. + + 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. Here's +how to do it in bash: + +@example +if [ "$@{PS1+set@}" = set ] +then PS1=@dots{} +fi +@end example + +@noindent +And here's how to do it in csh: + +@example +if ($?prompt) set prompt = @dots{} +@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. +@iftex +@inforef{MS-DOS,,emacs-xtra}. +@end iftex +@ifnottex +@xref{MS-DOS}. +@end ifnottex + +@node Grep Searching +@section Searching with Grep under Emacs + + Just as you can run a compiler from Emacs and then visit the lines +with 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.'' The +buffer of matches uses Grep mode, which is a variant of Compilation +mode (@pxref{Compilation Mode}). + +@table @kbd +@item M-x grep +@item M-x lgrep +Run @code{grep} asynchronously under Emacs, with matching lines +listed in the buffer named @samp{*grep*}. +@item M-x grep-find +@itemx M-x find-grep +@itemx M-x rgrep +Run @code{grep} via @code{find}, with user-specified arguments, and +collect output in the buffer named @samp{*grep*}. +@item M-x kill-grep +Kill the running @code{grep} subprocess. +@end table + +@findex grep + To run @code{grep}, 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. If you +specify a prefix argument for @kbd{M-x grep}, it finds the tag +(@pxref{Tags}) in the buffer around point, and puts that into the +default @code{grep} command. + + Your command need not simply run @code{grep}; you can use any shell +command that produces output in the same format. For instance, you +can chain @code{grep} commands, like this: + +@example +grep -nH -e foo *.el | grep bar | grep toto +@end example + + The output from @code{grep} goes in the @samp{*grep*} buffer. You +can find the corresponding lines in the original files using @w{@kbd{C-x +`}}, @key{RET}, and so forth, just like compilation errors. + + Some grep programs accept a @samp{--color} option to output special +markers around matches for the purpose of highlighting. You can make +use of this feature by setting @code{grep-highlight-matches} to +@code{t}. When displaying a match in the source buffer, the exact +match will be highlighted, instead of the entire source line. + +@findex grep-find +@findex find-grep + The command @kbd{M-x grep-find} (also available as @kbd{M-x +find-grep}) 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}. + +@findex lgrep +@findex rgrep + The commands @kbd{M-x lgrep} (local grep) and @kbd{M-x rgrep} +(recursive grep) are more user-friendly versions of @code{grep} and +@code{grep-find}, which prompt separately for the regular expression +to match, the files to search, and the base directory for the search. +Case sensitivity of the search is controlled by the +current value of @code{case-fold-search}. + +These commands build the shell commands based on the variables +@code{grep-template} (for @code{lgrep}) and @code{grep-find-template} +(for @code{rgrep}). + +The files to search can use aliases defined in the variable +@code{grep-files-aliases}. + +Subdirectories listed in the variable +@code{grep-find-ignored-directories} such as those typically used by +various version control systems, like CVS and arch, are automatically +skipped by @code{rgrep}. + +@node Flymake +@section Finding Syntax Errors On The Fly +@cindex checking syntax + + Flymake mode is a minor mode that performs on-the-fly syntax +checking for many programming and markup languages, including C, C++, +Perl, HTML, and @TeX{}/La@TeX{}. It is somewhat analogous to Flyspell +mode, which performs spell checking for ordinary human languages in a +similar fashion (@pxref{Spelling}). As you edit a file, Flymake mode +runs an appropriate syntax checking tool in the background, using a +temporary copy of the buffer. It then parses the error and warning +messages, and highlights the erroneous lines in the buffer. The +syntax checking tool used depends on the language; for example, for +C/C++ files this is usually the C compiler. Flymake can also use +build tools such as @code{make} for checking complicated projects. + + To activate Flymake mode, type @kbd{M-x flymake-mode}. You can move +to the errors spotted by Flymake mode with @kbd{M-x +flymake-goto-next-error} and @kbd{M-x flymake-goto-prev-error}. To +display any error messages associated with the current line, use +@kbd{M-x flymake-display-err-menu-for-current-line}. + + For more details about using Flymake, see @ref{Top, Flymake, +Flymake, flymake, The Flymake Manual}. + +@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 GUD can also run DBX, SDB or +XDB. GUD can also serve as an interface to Perl's debugging mode, the +Python debugger PDB, and to JDB, the Java Debugger. +@xref{Debugging,, The Lisp Debugger, elisp, the Emacs Lisp Reference +Manual}, for information on debugging Emacs Lisp programs. + +@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. +* GDB Graphical Interface:: An enhanced mode that uses GDB features to + implement a graphical debugging environment through + Emacs. +@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. By default, this uses an IDE-like +graphical interface; see @ref{GDB Graphical Interface}. Only GDB +works with the graphical interface. + +@item M-x dbx @key{RET} @var{file} @key{RET} +@findex dbx +Run DBX as a subprocess of Emacs. Since Emacs does not implement a +graphical interface for DBX, communication with DBX works by typing +commands in the GUD interaction buffer. The same is true for all +the other supported debuggers. + +@item M-x xdb @key{RET} @var{file} @key{RET} +@findex xdb +@vindex gud-xdb-directories +Similar, but run XDB. 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. + + 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. + +Tramp provides a facility to debug programs on remote hosts. +@xref{Running a debugger on a remote host, Running a debugger on a remote host,, tramp, The Tramp Manual}. +@c Running a debugger on a remote host + +@node Debugger Operation +@subsection Debugger Operation + +@cindex fringes, and current execution line in GUD + Generally 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. Input and output from the program you are debugging also use +this buffer. We call this @dfn{text command mode}. The GDB Graphical +Interface can use further buffers (@pxref{GDB Graphical Interface}). + + The debugger displays the source files of the program by visiting +them in Emacs buffers. An arrow in the left fringe indicates the +current execution line.@footnote{On a text-only terminal, the arrow +appears as @samp{=>} and overlays the first two text columns.} Moving +point in this buffer does not move the arrow. The arrow is not part +of the file's text; it appears only on the screen. + + You can start editing these source files at any time in the buffers +that display them. 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. + +@cindex tooltips with GUD +@vindex tooltip-gud-modes +@vindex gud-tooltip-mode +@vindex gud-tooltip-echo-area + The Tooltip facility (@pxref{Tooltips}) provides support for GUD@. +You activate this feature by turning on the minor mode +@code{gud-tooltip-mode}. Then you can display a variable's value in a +tooltip simply by pointing at it with the mouse. This operates in the +GUD buffer and in source buffers with major modes in the list +@code{gud-tooltip-modes}. If the variable @code{gud-tooltip-echo-area} +is non-@code{nil} then the variable's value is displayed in the echo +area. When debugging a C program using the GDB Graphical Interface, you +can also display macro definitions associated with an identifier when +the program is not executing. + + GUD tooltips are disabled when you use GDB in text command mode +(@pxref{GDB Graphical Interface}), because displaying an expression's +value in GDB can sometimes expand a macro and result in a side effect +that interferes with the program's operation. The GDB graphical +interface supports GUD tooltips and assures they will not cause side +effects. + +@node Commands of GUD +@subsection Commands of GUD + + The GUD interaction buffer uses a variant of Shell mode, so the +Emacs commands of Shell mode are available (@pxref{Shell Mode}). All +the usual commands for your debugger are available, and you can use +the Shell mode history commands to repeat them. If you wish, you can +control your debugger process entirely through this buffer. + + 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. It also has its own tool +bar from which you can invoke the more common commands by clicking on +the appropriate icon. This is particularly useful for repetitive +commands like @code{gud-next} and @code{gud-step}, and allows you to +keep the GUD buffer hidden. + + The breakpoint commands are normally used in source file buffers, +because that is the easiest 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. Some of these +commands are not available to all the supported debuggers. + +@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}). + +@item C-c C-p +@kindex C-c C-p @r{(GUD)} +@itemx C-x C-a C-p +@findex gud-print +Evaluate the expression at point (@code{gud-print}). If Emacs +does not print the exact expression that you want, mark it as a region +first. + +@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 +(@code{gud-tbreak}). If you use this command in the GUD interaction +buffer, it applies to the line where the program last stopped. + +@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 GDB command @samp{up}. + +@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 GDB command @samp{down}. + +@item C-c C-u +@kindex C-c C-u @r{(GUD)} +@itemx C-x C-a C-u +@findex gud-until +Continue execution to the current line (@code{gud-until}). The +program will run until it hits a breakpoint, terminates, gets a signal +that the debugger is checking for, or reaches the line on which the +cursor currently sits. + +@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 +stops for some other reason (@code{gud-finish}). +@end table + + If you are using GDB, these additional key bindings are available: + +@table @kbd +@item C-x C-a C-j +@kindex C-x C-a C-j @r{(GUD)} +@findex gud-jump +Only useful in a source buffer, @code{gud-jump} transfers the +program's execution point to the current line. In other words, the +next line that the program executes will be the one where you gave the +command. If the new execution line is in a different function from +the previously one, GDB prompts for confirmation since the results may +be bizarre. See the GDB manual entry regarding @code{jump} for +details. + +@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. +@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{pdb-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 then use the command @var{function} 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. + +@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 +In transient-mark-mode the text in the region, if it is active. +Otherwise 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. + +@item %d +The name of the directory of the current source file. + +@item %c +Fully qualified class name derived from the expression surrounding point +(jdb only). +@end table + +@node GDB Graphical Interface +@subsection GDB Graphical Interface + + By default, the command @code{gdb} starts GDB using a graphical +interface, using Emacs windows for display program state information. +In effect, this makes Emacs into an IDE (interactive development +environment). With it, you do not need to use textual GDB commands; +you can control the debugging session with the mouse. For example, +you can click in the fringe of a source buffer to set a breakpoint +there, or on a stack frame in the stack buffer to select that frame. + + This mode requires telling GDB that its ``screen size'' is +unlimited, so it sets the height and width accordingly. For correct +operation you must not change these values during the GDB session. + +@vindex gud-gdb-command-name +@findex gdba + You can also run GDB in text command mode, like other debuggers. To +do this, replace the GDB @code{"--annotate=3"} option with +@code{"--fullname"} either in the minibuffer for the current Emacs +session, or the custom variable @code{gud-gdb-command-name} for all +future sessions. You need to use text command mode to debug multiple +programs within one Emacs session. If you have customized +@code{gud-gdb-command-name} in this way, you can use @kbd{M-x gdba} to +invoke GDB in graphical mode. Moreover, this command succeeds where +@kbd{M-x gdb} fails, such as when your @file{.gdbinit} file contains +executable GDB commands. + +@menu +* GDB-UI Layout:: Control the number of displayed buffers. +* Source Buffers:: Use the mouse in the fringe/margin to + control your program. +* Breakpoints Buffer:: A breakpoint control panel. +* Stack Buffer:: Select a frame from the call stack. +* Other GDB-UI Buffers:: Input/output, locals, registers, + assembler, threads and memory buffers. +* Watch Expressions:: Monitor variable values in the speedbar. +@end menu + +@node GDB-UI Layout +@subsubsection GDB User Interface Layout +@cindex GDB User Interface layout + +@vindex gdb-many-windows + If the variable @code{gdb-many-windows} is @code{nil} (the default +value) then @kbd{M-x gdb} normally displays only the GUD buffer. +However, if the variable @code{gdb-show-main} is also non-@code{nil}, +it starts with two windows: one displaying the GUD buffer, and the +other showing the source for the @code{main} function of the program +you are debugging. + + If @code{gdb-many-windows} is non-@code{nil}, then @kbd{M-x gdb} +displays the following frame layout: + +@smallexample +@group ++--------------------------------+--------------------------------+ +| GUD buffer (I/O of GDB) | Locals buffer | +|--------------------------------+--------------------------------+ +| Primary Source buffer | I/O buffer for debugged pgm | +|--------------------------------+--------------------------------+ +| Stack buffer | Breakpoints buffer | ++--------------------------------+--------------------------------+ +@end group +@end smallexample + + However, if @code{gdb-use-separate-io-buffer} is @code{nil}, the I/O +buffer does not appear and the primary source buffer occupies the full +width of the frame. + +@findex gdb-restore-windows + If you change the window layout, for example, while editing and +re-compiling your program, then you can restore this standard window +layout with the command @code{gdb-restore-windows}. + +@findex gdb-many-windows + To switch between this standard layout and a simple layout +containing just the GUD buffer and a source file, type @kbd{M-x +gdb-many-windows}. + + You may also specify additional GDB-related buffers to display, +either in the same frame or a different one. Select the buffers you +want with the @samp{GUD->GDB-windows} and @samp{GUD->GDB-Frames} +sub-menus. If the menu-bar is unavailable, type @code{M-x +gdb-display-@var{buffertype}-buffer} or @code{M-x +gdb-frame-@var{buffertype}-buffer} respectively, where +@var{buffertype} is the relevant buffer type, such as +@samp{breakpoints}. Most of these buffers are read-only, and typing +@kbd{q} in them kills them. + + When you finish debugging, kill the GUD buffer with @kbd{C-x k}, +which will also kill all the buffers associated with the session. +However you need not do this if, after editing and re-compiling your +source code within Emacs, you wish continue debugging. When you +restart execution, GDB will automatically find your new executable. +Keeping the GUD buffer has the advantage of keeping the shell history +as well as GDB's breakpoints. You do need to check that the +breakpoints in recently edited source files are still in the right +places. + +@node Source Buffers +@subsubsection Source Buffers +@cindex GDB commands in Fringe + +@c @findex gdb-mouse-set-clear-breakpoint +@c @findex gdb-mouse-toggle-breakpoint +Many GDB commands can be entered using keybindings or the tool bar but +sometimes it is quicker to use the fringe. These commands either +manipulate breakpoints or control program execution. When there is no +fringe, you can use the margin but this is only present when the +source file already has a breakpoint. + +You can click @kbd{Mouse-1} in the fringe or display margin of a +source buffer to set a breakpoint there and, on a graphical display, a +red bullet will appear on that line. If a breakpoint already exists +on that line, the same click will remove it. You can also enable or +disable a breakpoint by clicking @kbd{C-Mouse-1} on the bullet. + +A solid arrow in the left fringe of a source buffer indicates the line +of the innermost frame where the debugged program has stopped. A +hollow arrow indicates the current execution line of higher level +frames. + +If you drag the arrow in the fringe with @kbd{Mouse-1} +(@code{gdb-mouse-until}), execution will continue to the line where +you release the button, provided it is still in the same frame. +Alternatively, you can click @kbd{Mouse-3} at some point in the fringe +of this buffer and execution will advance to there. A similar command +(@code{gdb-mouse-jump}) allows you to jump to a source line without +executing the intermediate lines by clicking @kbd{C-Mouse-3}. This +command allows you to go backwards which can be useful for running +through code that has already executed, in order to examine its +execution in more detail. + +@table @kbd +@item Mouse-1 +Set or clear a breakpoint. + +@item C-Mouse-1 +Enable or disable a breakpoint. + +@item Mouse-3 +Continue execution to here. + +@item C-Mouse-3 +Jump to here. +@end table + +If the variable @code{gdb-find-source-frame} is non-@code{nil} and +execution stops in a frame for which there is no source code e.g after +an interrupt, then Emacs finds and displays the first frame further up +stack for which there is source. If it is @code{nil} then the source +buffer continues to display the last frame which maybe more useful, +for example, when re-setting a breakpoint. + +@node Breakpoints Buffer +@subsubsection Breakpoints Buffer + + The breakpoints buffer shows the existing breakpoints, watchpoints and +catchpoints (@pxref{Breakpoints,,, gdb, The GNU debugger}). It has +these special commands, which mostly apply to the @dfn{current +breakpoint}, the breakpoint which point is on. + +@table @kbd +@item @key{SPC} +@kindex SPC @r{(GDB breakpoints buffer)} +@findex gdb-toggle-breakpoint +Enable/disable the current breakpoint (@code{gdb-toggle-breakpoint}). +On a graphical display, this changes the color of a bullet in the +margin of a source buffer at the relevant line. This is red when +the breakpoint is enabled and grey when it is disabled. Text-only +terminals correspondingly display a @samp{B} or @samp{b}. + +@item D +@kindex D @r{(GDB breakpoints buffer)} +@findex gdb-delete-breakpoint +Delete the current breakpoint (@code{gdb-delete-breakpoint}). + +@item @key{RET} +@kindex RET @r{(GDB breakpoints buffer)} +@findex gdb-goto-breakpoint +Visit the source line for the current breakpoint +(@code{gdb-goto-breakpoint}). + +@item Mouse-2 +@kindex Mouse-2 @r{(GDB breakpoints buffer)} +Visit the source line for the breakpoint you click on. +@end table + +@node Stack Buffer +@subsubsection Stack Buffer + + The stack buffer displays a @dfn{call stack}, with one line for each +of the nested subroutine calls (@dfn{stack frames}) now active in the +program. @xref{Backtrace,, Backtraces, gdb, The GNU debugger}. + +@findex gdb-frames-select +An arrow in the fringe points to the selected frame or, if the fringe is +not present, the number of the selected frame is displayed in reverse +contrast. To select a frame in GDB, move point in the stack buffer to +that stack frame and type @key{RET} (@code{gdb-frames-select}), or click +@kbd{Mouse-2} on a stack frame. If the locals buffer is visible, +selecting a stack frame updates it to display the local variables of the +new frame. + +@node Other GDB-UI Buffers +@subsubsection Other Buffers + +@table @asis +@item Input/Output Buffer +@vindex gdb-use-separate-io-buffer +If the variable @code{gdb-use-separate-io-buffer} is non-@code{nil}, +the program being debugged takes its input and displays its output +here. Otherwise it uses the GUD buffer for that. To toggle whether +GUD mode uses this buffer, do @kbd{M-x gdb-use-separate-io-buffer}. +This takes effect when you next restart the program you are debugging. + +The history and replay commands from Shell mode are available here, +as are the commands to send signals to the debugged program. +@xref{Shell Mode}. + +@item Locals Buffer +The locals buffer displays the values of local variables of the +current frame for simple data types (@pxref{Frame Info, Frame Info, +Information on a frame, gdb, The GNU debugger}). Press @key{RET} or +click @kbd{Mouse-2} on the value if you want to edit it. + +Arrays and structures display their type only. With GDB 6.4 or later, +move point to their name and press @key{RET}, or alternatively click +@kbd{Mouse-2} there, to examine their values. With earlier versions +of GDB, use @kbd{Mouse-2} or @key{RET} on the type description +(@samp{[struct/union]} or @samp{[array]}). @xref{Watch Expressions}. + +@item Registers Buffer +@findex toggle-gdb-all-registers +The registers buffer displays the values held by the registers +(@pxref{Registers,,, gdb, The GNU debugger}). Press @key{RET} or +click @kbd{Mouse-2} on a register if you want to edit its value. +With GDB 6.4 or later, recently changed register values display with +@code{font-lock-warning-face}. With earlier versions of GDB, you can +press @key{SPC} to toggle the display of floating point registers +(@code{toggle-gdb-all-registers}). + +@item Assembler Buffer +The assembler buffer displays the current frame as machine code. An +arrow points to the current instruction, and you can set and remove +breakpoints as in a source buffer. Breakpoint icons also appear in +the fringe or margin. + +@item Threads Buffer +@findex gdb-threads-select +The threads buffer displays a summary of all threads currently in your +program (@pxref{Threads, Threads, Debugging programs with multiple +threads, gdb, The GNU debugger}). Move point to any thread in the +list and press @key{RET} to select it (@code{gdb-threads-select}) and +display the associated source in the primary source buffer. +Alternatively, click @kbd{Mouse-2} on a thread to select it. If the +locals buffer is visible, its contents update to display the variables +that are local in the new thread. + +@item Memory Buffer +The memory buffer lets you examine sections of program memory +(@pxref{Memory, Memory, Examining memory, gdb, The GNU debugger}). +Click @kbd{Mouse-1} on the appropriate part of the header line to +change the starting address or number of data items that the buffer +displays. Click @kbd{Mouse-3} on the header line to select the +display format or unit size for these data items. +@end table + +@node Watch Expressions +@subsubsection Watch Expressions +@cindex Watching expressions in GDB + +@findex gud-watch +@kindex C-x C-a C-w @r{(GUD)} + If you want to see how a variable changes each time your program +stops, move point into the variable name and click on the watch icon +in the tool bar (@code{gud-watch}) or type @kbd{C-x C-a C-w}. If you +specify a prefix argument, you can enter the variable name in the +minibuffer. + + Each watch expression is displayed in the speedbar. Complex data +types, such as arrays, structures and unions are represented in a tree +format. Leaves and simple data types show the name of the expression +and its value and, when the speedbar frame is selected, display the +type as a tooltip. Higher levels show the name, type and address +value for pointers and just the name and type otherwise. Root expressions +also display the frame address as a tooltip to help identify the frame +in which they were defined. + + To expand or contract a complex data type, click @kbd{Mouse-2} or +press @key{SPC} on the tag to the left of the expression. Emacs asks +for confirmation before expanding the expression if its number of +immediate children exceeds the value of the variable +@code{gdb-max-children}. + +@kindex D @r{(GDB speedbar)} +@findex gdb-var-delete + To delete a complex watch expression, move point to the root +expression in the speedbar and type @kbd{D} (@code{gdb-var-delete}). + +@kindex RET @r{(GDB speedbar)} +@findex gdb-edit-value + To edit a variable with a simple data type, or a simple element of a +complex data type, move point there in the speedbar and type @key{RET} +(@code{gdb-edit-value}). Or you can click @kbd{Mouse-2} on a value to +edit it. Either way, this reads the new value using the minibuffer. + +@vindex gdb-show-changed-values + If you set the variable @code{gdb-show-changed-values} to +non-@code{nil} (the default value), Emacs uses +@code{font-lock-warning-face} to highlight values that have recently +changed and @code{shadow} face to make variables which have gone out of +scope less noticeable. When a variable goes out of scope you can't +edit its value. + +@vindex gdb-use-colon-colon-notation + If the variable @code{gdb-use-colon-colon-notation} is +non-@code{nil}, Emacs uses the @samp{@var{function}::@var{variable}} +format. This allows the user to display watch expressions which share +the same variable name. The default value is @code{nil}. + +@vindex gdb-speedbar-auto-raise +To automatically raise the speedbar every time the display of watch +expressions updates, set @code{gdb-speedbar-auto-raise} to +non-@code{nil}. This can be useful if you are debugging with a full +screen Emacs frame. + +@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}). + +@cindex byte code + Emacs Lisp code can be compiled into byte-code, which loads faster, +takes up less space, 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 ends in @samp{.elc}. Thus, the compiled code for +@file{foo.el} goes in @file{foo.elc}. + +@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}, 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 issues a warning, because it's likely +that somebody made changes to the @file{.el} file and forgot to +recompile it. Nonetheless, it loads @file{@var{lib}.elc}. This is +because people often leave unfinished edits the source file, and don't +recompile it until they think it is ready to use. + + 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 directories 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. + +@vindex load-dangerous-libraries +@cindex Lisp files byte-compiled by XEmacs + By default, Emacs refuses to load compiled Lisp files which were +compiled with XEmacs, a modified versions of Emacs---they can cause +Emacs to crash. Set the variable @code{load-dangerous-libraries} to +@code{t} if you want to try loading them. + +@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-buffer +Evaluate all the Lisp expressions in the buffer. +@end table + +@ifinfo +@c This uses ``colon'' instead of a literal `:' because Info cannot +@c cope with a `:' in a menu +@kindex M-@key{colon} +@end ifinfo +@ifnotinfo +@kindex M-: +@end ifnotinfo +@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. +@code{defcustom} expressions are treated similarly. +This special feature is convenient for debugging Lisp programs. +Typing @kbd{C-M-x} on a @code{defface} expression reinitializes +the face according to the @code{defface} specification. + +@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. + + When the result of an evaluation is an integer, you can type +@kbd{C-x C-e} a second time to display the value of the integer result +in additional formats (octal, hexadecimal, and character). + + If @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. +@kbd{C-M-x} with a numeric argument instruments the function +definition for Edebug (@pxref{Instrumenting, Instrumenting for Edebug,, elisp, the Emacs Lisp Reference Manual}). + +@findex eval-region +@findex eval-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-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 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. + +@vindex eval-expression-print-level +@vindex eval-expression-print-length +@vindex eval-expression-debug-on-error + The two customizable variables @code{eval-expression-print-level} and +@code{eval-expression-print-length} control the maximum depth and length +of lists to print in the result of the evaluation commands before +abbreviating them. @code{eval-expression-debug-on-error} controls +whether evaluation errors invoke the debugger when these commands are +used; its default is @code{t}. + +@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. For more information see that command's +documentation. + +@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. You can switch to this mode with @kbd{M-x lisp-mode}, and it is +used automatically for files whose names end in @file{.l}, +@file{.lsp}, or @file{.lisp}. + +@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; see @pxref{Lisp Eval}): 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. + + +@ignore + arch-tag: 9c3c2f71-b332-4144-8500-3ff9945a50ed +@end ignore diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi new file mode 100644 index 00000000000..61d519cbd12 --- /dev/null +++ b/doc/emacs/cal-xtra.texi @@ -0,0 +1,838 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@c +@c This file is included either in emacs-xtra.texi (when producing the +@c printed version) or in the main Emacs manual (for the on-line version). + +@c Moved here from the Emacs Lisp Reference Manual, 2005-03-26. +@node Advanced Calendar/Diary Usage +@section Customizing the Calendar and Diary + + There are many customizations that you can use to make the calendar and +diary suit your personal tastes. + +@menu +* Calendar Customizing:: Defaults you can set. +* Holiday Customizing:: Defining your own holidays. +* Date Display Format:: Changing the format. +* Time Display Format:: Changing the format. +* Diary Customizing:: Defaults you can set. +* Hebrew/Islamic Entries:: How to obtain them. +* Fancy Diary Display:: Enhancing the diary display, sorting entries, + using included diary files. +* Sexp Diary Entries:: Fancy things you can do. +@end menu + +@node Calendar Customizing +@subsection Customizing the Calendar +@vindex calendar-holiday-marker +@vindex diary-entry-marker + The variable @code{calendar-holiday-marker} specifies how to mark a +date as being a holiday. Its value may be a single-character string +to insert next to the date, or a face name to use for displaying the +date. Likewise, the variable @code{diary-entry-marker} specifies how +to mark a date that has diary entries. The calendar creates faces +named @code{holiday-face} and @code{diary-face} for these purposes; +those symbols are the default values of these variables. + +@vindex calendar-load-hook + The variable @code{calendar-load-hook} is a normal hook run when the +calendar package is first loaded (before actually starting to display +the calendar). + +@vindex initial-calendar-window-hook + Starting the calendar runs the normal hook +@code{initial-calendar-window-hook}. Recomputation of the calendar +display does not run this hook. But if you leave the calendar with the +@kbd{q} command and reenter it, the hook runs again.@refill + +@vindex today-visible-calendar-hook + The variable @code{today-visible-calendar-hook} is a normal hook run +after the calendar buffer has been prepared with the calendar when the +current date is visible in the window. One use of this hook is to +replace today's date with asterisks; to do that, use the hook function +@code{calendar-star-date}. + +@findex calendar-star-date +@example +(add-hook 'today-visible-calendar-hook 'calendar-star-date) +@end example + +@noindent +Another standard hook function marks the current date, either by +changing its face or by adding an asterisk. Here's how to use it: + +@findex calendar-mark-today +@example +(add-hook 'today-visible-calendar-hook 'calendar-mark-today) +@end example + +@noindent +@vindex calendar-today-marker +The variable @code{calendar-today-marker} specifies how to mark +today's date. Its value should be a single-character string to insert +next to the date or a face name to use for displaying the date. A +face named @code{calendar-today-face} is provided for this purpose; +that symbol is the default for this variable. + +@vindex today-invisible-calendar-hook +@noindent + A similar normal hook, @code{today-invisible-calendar-hook} is run if +the current date is @emph{not} visible in the window. + +@vindex calendar-move-hook + Each of the calendar cursor motion commands runs the hook +@code{calendar-move-hook} after it moves the cursor. + +@node Holiday Customizing +@subsection Customizing the Holidays + +@vindex calendar-holidays +@vindex christian-holidays +@vindex hebrew-holidays +@vindex islamic-holidays + Emacs knows about holidays defined by entries on one of several lists. +You can customize these lists of holidays to your own needs, adding or +deleting holidays. The lists of holidays that Emacs uses are for +general holidays (@code{general-holidays}), local holidays +(@code{local-holidays}), Christian holidays (@code{christian-holidays}), +Hebrew (Jewish) holidays (@code{hebrew-holidays}), Islamic (Muslim) +holidays (@code{islamic-holidays}), and other holidays +(@code{other-holidays}). + +@vindex general-holidays + The general holidays are, by default, holidays common throughout the +United States. To eliminate these holidays, set @code{general-holidays} +to @code{nil}. + +@vindex local-holidays + There are no default local holidays (but sites may supply some). You +can set the variable @code{local-holidays} to any list of holidays, as +described below. + +@vindex all-christian-calendar-holidays +@vindex all-hebrew-calendar-holidays +@vindex all-islamic-calendar-holidays + By default, Emacs does not include all the holidays of the religions +that it knows, only those commonly found in secular calendars. For a +more extensive collection of religious holidays, you can set any (or +all) of the variables @code{all-christian-calendar-holidays}, +@code{all-hebrew-calendar-holidays}, or +@code{all-islamic-calendar-holidays} to @code{t}. If you want to +eliminate the religious holidays, set any or all of the corresponding +variables @code{christian-holidays}, @code{hebrew-holidays}, and +@code{islamic-holidays} to @code{nil}.@refill + +@vindex other-holidays + You can set the variable @code{other-holidays} to any list of +holidays. This list, normally empty, is intended for individual use. + +@cindex holiday forms + Each of the lists (@code{general-holidays}, @code{local-holidays}, +@code{christian-holidays}, @code{hebrew-holidays}, +@code{islamic-holidays}, and @code{other-holidays}) is a list of +@dfn{holiday forms}, each holiday form describing a holiday (or +sometimes a list of holidays). + + Here is a table of the possible kinds of holiday form. Day numbers +and month numbers count starting from 1, but ``dayname'' numbers +count Sunday as 0. The element @var{string} is always the +name of the holiday, as a string. + +@table @code +@item (holiday-fixed @var{month} @var{day} @var{string}) +A fixed date on the Gregorian calendar. + +@item (holiday-float @var{month} @var{dayname} @var{k} @var{string}) +The @var{k}th @var{dayname} in @var{month} on the Gregorian calendar +(@var{dayname}=0 for Sunday, and so on); negative @var{k} means count back +from the end of the month. + +@item (holiday-hebrew @var{month} @var{day} @var{string}) +A fixed date on the Hebrew calendar. + +@item (holiday-islamic @var{month} @var{day} @var{string}) +A fixed date on the Islamic calendar. + +@item (holiday-julian @var{month} @var{day} @var{string}) +A fixed date on the Julian calendar. + +@item (holiday-sexp @var{sexp} @var{string}) +A date calculated by the Lisp expression @var{sexp}. The expression +should use the variable @code{year} to compute and return the date of a +holiday, or @code{nil} if the holiday doesn't happen this year. The +value of @var{sexp} must represent the date as a list of the form +@code{(@var{month} @var{day} @var{year})}. + +@item (if @var{condition} @var{holiday-form}) +A holiday that happens only if @var{condition} is true. + +@item (@var{function} @r{[}@var{args}@r{]}) +A list of dates calculated by the function @var{function}, called with +arguments @var{args}. +@end table + + For example, suppose you want to add Bastille Day, celebrated in +France on July 14. You can do this as follows: + +@smallexample +(setq other-holidays '((holiday-fixed 7 14 "Bastille Day"))) +@end smallexample + +@noindent +The holiday form @code{(holiday-fixed 7 14 "Bastille Day")} specifies the +fourteenth day of the seventh month (July). + + Many holidays occur on a specific day of the week, at a specific time +of month. Here is a holiday form describing Hurricane Supplication Day, +celebrated in the Virgin Islands on the fourth Monday in August: + +@smallexample +(holiday-float 8 1 4 "Hurricane Supplication Day") +@end smallexample + +@noindent +Here the 8 specifies August, the 1 specifies Monday (Sunday is 0, +Tuesday is 2, and so on), and the 4 specifies the fourth occurrence in +the month (1 specifies the first occurrence, 2 the second occurrence, +@minus{}1 the last occurrence, @minus{}2 the second-to-last occurrence, and +so on). + + You can specify holidays that occur on fixed days of the Hebrew, +Islamic, and Julian calendars too. For example, + +@smallexample +(setq other-holidays + '((holiday-hebrew 10 2 "Last day of Hanukkah") + (holiday-islamic 3 12 "Mohammed's Birthday") + (holiday-julian 4 2 "Jefferson's Birthday"))) +@end smallexample + +@noindent +adds the last day of Hanukkah (since the Hebrew months are numbered with +1 starting from Nisan), the Islamic feast celebrating Mohammed's +birthday (since the Islamic months are numbered from 1 starting with +Muharram), and Thomas Jefferson's birthday, which is 2 April 1743 on the +Julian calendar. + + To include a holiday conditionally, use either Emacs Lisp's @code{if} or the +@code{holiday-sexp} form. For example, American presidential elections +occur on the first Tuesday after the first Monday in November of years +divisible by 4: + +@smallexample +(holiday-sexp '(if (= 0 (% year 4)) + (calendar-gregorian-from-absolute + (1+ (calendar-dayname-on-or-before + 1 (+ 6 (calendar-absolute-from-gregorian + (list 11 1 year))))))) + "US Presidential Election") +@end smallexample + +@noindent +or + +@smallexample +(if (= 0 (% displayed-year 4)) + (fixed 11 + (extract-calendar-day + (calendar-gregorian-from-absolute + (1+ (calendar-dayname-on-or-before + 1 (+ 6 (calendar-absolute-from-gregorian + (list 11 1 displayed-year))))))) + "US Presidential Election")) +@end smallexample + + Some holidays just don't fit into any of these forms because special +calculations are involved in their determination. In such cases you +must write a Lisp function to do the calculation. To include eclipses, +for example, add @code{(eclipses)} to @code{other-holidays} +and write an Emacs Lisp function @code{eclipses} that returns a +(possibly empty) list of the relevant Gregorian dates among the range +visible in the calendar window, with descriptive strings, like this: + +@smallexample +(((6 27 1991) "Lunar Eclipse") ((7 11 1991) "Solar Eclipse") ... ) +@end smallexample + +@node Date Display Format +@subsection Date Display Format +@vindex calendar-date-display-form + + You can customize the manner of displaying dates in the diary, in mode +lines, and in messages by setting @code{calendar-date-display-form}. +This variable holds a list of expressions that can involve the variables +@code{month}, @code{day}, and @code{year}, which are all numbers in +string form, and @code{monthname} and @code{dayname}, which are both +alphabetic strings. In the American style, the default value of this +list is as follows: + +@smallexample +((if dayname (concat dayname ", ")) monthname " " day ", " year) +@end smallexample + +@noindent +while in the European style this value is the default: + +@smallexample +((if dayname (concat dayname ", ")) day " " monthname " " year) +@end smallexample + +@noindent +The ISO standard date representation is this: + +@smallexample +(year "-" month "-" day) +@end smallexample + +@noindent +This specifies a typical American format: + +@smallexample +(month "/" day "/" (substring year -2)) +@end smallexample + +@node Time Display Format +@subsection Time Display Format +@vindex calendar-time-display-form + + The calendar and diary by default display times of day in the +conventional American style with the hours from 1 through 12, minutes, +and either @samp{am} or @samp{pm}. If you prefer the European style, +also known in the US as military, in which the hours go from 00 to 23, +you can alter the variable @code{calendar-time-display-form}. This +variable is a list of expressions that can involve the variables +@code{12-hours}, @code{24-hours}, and @code{minutes}, which are all +numbers in string form, and @code{am-pm} and @code{time-zone}, which are +both alphabetic strings. The default value of +@code{calendar-time-display-form} is as follows: + +@smallexample +(12-hours ":" minutes am-pm + (if time-zone " (") time-zone (if time-zone ")")) +@end smallexample + +@noindent +Here is a value that provides European style times: + +@smallexample +(24-hours ":" minutes + (if time-zone " (") time-zone (if time-zone ")")) +@end smallexample + +@node Diary Customizing +@subsection Customizing the Diary + +@vindex holidays-in-diary-buffer + Ordinarily, the mode line of the diary buffer window indicates any +holidays that fall on the date of the diary entries. The process of +checking for holidays can take several seconds, so including holiday +information delays the display of the diary buffer noticeably. If you'd +prefer to have a faster display of the diary buffer but without the +holiday information, set the variable @code{holidays-in-diary-buffer} to +@code{nil}.@refill + +@vindex number-of-diary-entries + The variable @code{number-of-diary-entries} controls the number of +days of diary entries to be displayed at one time. It affects the +initial display when @code{view-diary-entries-initially} is @code{t}, as +well as the command @kbd{M-x diary}. For example, the default value is +1, which says to display only the current day's diary entries. If the +value is 2, both the current day's and the next day's entries are +displayed. The value can also be a vector of seven elements: for +example, if the value is @code{[0 2 2 2 2 4 1]} then no diary entries +appear on Sunday, the current date's and the next day's diary entries +appear Monday through Thursday, Friday through Monday's entries appear +on Friday, while on Saturday only that day's entries appear. + +@vindex print-diary-entries-hook +@findex print-diary-entries + The variable @code{print-diary-entries-hook} is a normal hook run +after preparation of a temporary buffer containing just the diary +entries currently visible in the diary buffer. (The other, irrelevant +diary entries are really absent from the temporary buffer; in the diary +buffer, they are merely hidden.) The default value of this hook does +the printing with the command @code{lpr-buffer}. If you want to use a +different command to do the printing, just change the value of this +hook. Other uses might include, for example, rearranging the lines into +order by day and time. + +@vindex diary-date-forms + You can customize the form of dates in your diary file, if neither the +standard American nor European styles suits your needs, by setting the +variable @code{diary-date-forms}. This variable is a list of patterns +for recognizing a date. Each date pattern is a list whose elements may +be regular expressions (@pxref{Regular Expressions,,, elisp, the Emacs +Lisp Reference Manual}) or the symbols @code{month}, @code{day}, +@code{year}, @code{monthname}, and @code{dayname}. All these elements +serve as patterns that match certain kinds of text in the diary file. +In order for the date pattern, as a whole, to match, all of its elements +must match consecutively. + + A regular expression in a date pattern matches in its usual fashion, +using the standard syntax table altered so that @samp{*} is a word +constituent. + + The symbols @code{month}, @code{day}, @code{year}, @code{monthname}, +and @code{dayname} match the month number, day number, year number, +month name, and day name of the date being considered. The symbols that +match numbers allow leading zeros; those that match names allow +three-letter abbreviations and capitalization. All the symbols can +match @samp{*}; since @samp{*} in a diary entry means ``any day'', ``any +month'', and so on, it should match regardless of the date being +considered. + + The default value of @code{diary-date-forms} in the American style is +this: + +@example +((month "/" day "[^/0-9]") + (month "/" day "/" year "[^0-9]") + (monthname " *" day "[^,0-9]") + (monthname " *" day ", *" year "[^0-9]") + (dayname "\\W")) +@end example + + The date patterns in the list must be @emph{mutually exclusive} and +must not match any portion of the diary entry itself, just the date and +one character of whitespace. If, to be mutually exclusive, the pattern +must match a portion of the diary entry text---beyond the whitespace +that ends the date---then the first element of the date pattern +@emph{must} be @code{backup}. This causes the date recognizer to back +up to the beginning of the current word of the diary entry, after +finishing the match. Even if you use @code{backup}, the date pattern +must absolutely not match more than a portion of the first word of the +diary entry. The default value of @code{diary-date-forms} in the +European style is this list: + +@example +((day "/" month "[^/0-9]") + (day "/" month "/" year "[^0-9]") + (backup day " *" monthname "\\W+\\<[^*0-9]") + (day " *" monthname " *" year "[^0-9]") + (dayname "\\W")) +@end example + +@noindent +Notice the use of @code{backup} in the third pattern, because it needs +to match part of a word beyond the date itself to distinguish it from +the fourth pattern. + +@node Hebrew/Islamic Entries +@subsection Hebrew- and Islamic-Date Diary Entries + + Your diary file can have entries based on Hebrew or Islamic dates, as +well as entries based on the world-standard Gregorian calendar. +However, because recognition of such entries is time-consuming and most +people don't use them, you must explicitly enable their use. If you +want the diary to recognize Hebrew-date diary entries, for example, +you must do this: + +@vindex nongregorian-diary-listing-hook +@vindex nongregorian-diary-marking-hook +@findex list-hebrew-diary-entries +@findex mark-hebrew-diary-entries +@smallexample +(add-hook 'nongregorian-diary-listing-hook 'list-hebrew-diary-entries) +(add-hook 'nongregorian-diary-marking-hook 'mark-hebrew-diary-entries) +@end smallexample + +@noindent +If you want Islamic-date entries, do this: + +@findex list-islamic-diary-entries +@findex mark-islamic-diary-entries +@smallexample +(add-hook 'nongregorian-diary-listing-hook 'list-islamic-diary-entries) +(add-hook 'nongregorian-diary-marking-hook 'mark-islamic-diary-entries) +@end smallexample + + Hebrew- and Islamic-date diary entries have the same formats as +Gregorian-date diary entries, except that @samp{H} precedes a Hebrew +date and @samp{I} precedes an Islamic date. Moreover, because the +Hebrew and Islamic month names are not uniquely specified by the first +three letters, you may not abbreviate them. For example, a diary entry +for the Hebrew date Heshvan 25 could look like this: + +@smallexample +HHeshvan 25 Happy Hebrew birthday! +@end smallexample + +@noindent +and would appear in the diary for any date that corresponds to Heshvan 25 +on the Hebrew calendar. And here is an Islamic-date diary entry that matches +Dhu al-Qada 25: + +@smallexample +IDhu al-Qada 25 Happy Islamic birthday! +@end smallexample + + As with Gregorian-date diary entries, Hebrew- and Islamic-date entries +are nonmarking if they are preceded with an ampersand (@samp{&}). + + Here is a table of commands used in the calendar to create diary entries +that match the selected date and other dates that are similar in the Hebrew +or Islamic calendar: + +@table @kbd +@item i h d +Add a diary entry for the Hebrew date corresponding to the selected date +(@code{insert-hebrew-diary-entry}). +@item i h m +Add a diary entry for the day of the Hebrew month corresponding to the +selected date (@code{insert-monthly-hebrew-diary-entry}). This diary +entry matches any date that has the same Hebrew day-within-month as the +selected date. +@item i h y +Add a diary entry for the day of the Hebrew year corresponding to the +selected date (@code{insert-yearly-hebrew-diary-entry}). This diary +entry matches any date which has the same Hebrew month and day-within-month +as the selected date. +@item i i d +Add a diary entry for the Islamic date corresponding to the selected date +(@code{insert-islamic-diary-entry}). +@item i i m +Add a diary entry for the day of the Islamic month corresponding to the +selected date (@code{insert-monthly-islamic-diary-entry}). +@item i i y +Add a diary entry for the day of the Islamic year corresponding to the +selected date (@code{insert-yearly-islamic-diary-entry}). +@end table + +@findex insert-hebrew-diary-entry +@findex insert-monthly-hebrew-diary-entry +@findex insert-yearly-hebrew-diary-entry +@findex insert-islamic-diary-entry +@findex insert-monthly-islamic-diary-entry +@findex insert-yearly-islamic-diary-entry + These commands work much like the corresponding commands for ordinary +diary entries: they apply to the date that point is on in the calendar +window, and what they do is insert just the date portion of a diary entry +at the end of your diary file. You must then insert the rest of the +diary entry. + +@node Fancy Diary Display +@subsection Fancy Diary Display +@vindex diary-display-hook +@findex simple-diary-display + + Diary display works by preparing the diary buffer and then running the +hook @code{diary-display-hook}. The default value of this hook +(@code{simple-diary-display}) hides the irrelevant diary entries and +then displays the buffer. However, if you specify the hook as follows, + +@cindex diary buffer +@findex fancy-diary-display +@example +(add-hook 'diary-display-hook 'fancy-diary-display) +@end example + +@noindent +this enables fancy diary display. It displays diary entries and +holidays by copying them into a special buffer that exists only for the +sake of display. Copying to a separate buffer provides an opportunity +to change the displayed text to make it prettier---for example, to sort +the entries by the dates they apply to. + + As with simple diary display, you can print a hard copy of the buffer +with @code{print-diary-entries}. To print a hard copy of a day-by-day +diary for a week, position point on Sunday of that week, type +@kbd{7 d}, and then do @kbd{M-x print-diary-entries}. As usual, the +inclusion of the holidays slows down the display slightly; you can speed +things up by setting the variable @code{holidays-in-diary-buffer} to +@code{nil}. + +@vindex diary-list-include-blanks + Ordinarily, the fancy diary buffer does not show days for which there are +no diary entries, even if that day is a holiday. If you want such days to be +shown in the fancy diary buffer, set the variable +@code{diary-list-include-blanks} to @code{t}.@refill + +@cindex sorting diary entries + If you use the fancy diary display, you can use the normal hook +@code{list-diary-entries-hook} to sort each day's diary entries by their +time of day. Here's how: + +@findex sort-diary-entries +@example +(add-hook 'list-diary-entries-hook 'sort-diary-entries t) +@end example + +@noindent +For each day, this sorts diary entries that begin with a recognizable +time of day according to their times. Diary entries without times come +first within each day. + + Fancy diary display also has the ability to process included diary +files. This permits a group of people to share a diary file for events +that apply to all of them. Lines in the diary file of this form: + +@smallexample +#include "@var{filename}" +@end smallexample + +@noindent +includes the diary entries from the file @var{filename} in the fancy +diary buffer. The include mechanism is recursive, so that included files +can include other files, and so on; you must be careful not to have a +cycle of inclusions, of course. Here is how to enable the include +facility: + +@vindex list-diary-entries-hook +@vindex mark-diary-entries-hook +@findex include-other-diary-files +@findex mark-included-diary-files +@smallexample +(add-hook 'list-diary-entries-hook 'include-other-diary-files) +(add-hook 'mark-diary-entries-hook 'mark-included-diary-files) +@end smallexample + +The include mechanism works only with the fancy diary display, because +ordinary diary display shows the entries directly from your diary file. + +@node Sexp Diary Entries +@subsection Sexp Entries and the Fancy Diary Display +@cindex sexp diary entries + + Sexp diary entries allow you to do more than just have complicated +conditions under which a diary entry applies. If you use the fancy +diary display, sexp entries can generate the text of the entry depending +on the date itself. For example, an anniversary diary entry can insert +the number of years since the anniversary date into the text of the +diary entry. Thus the @samp{%d} in this diary entry: + +@findex diary-anniversary +@smallexample +%%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) +@end smallexample + +@noindent +gets replaced by the age, so on October 31, 1990 the entry appears in +the fancy diary buffer like this: + +@smallexample +Arthur's birthday (42 years old) +@end smallexample + +@noindent +If the diary file instead contains this entry: + +@smallexample +%%(diary-anniversary 10 31 1948) Arthur's %d%s birthday +@end smallexample + +@noindent +the entry in the fancy diary buffer for October 31, 1990 appears like this: + +@smallexample +Arthur's 42nd birthday +@end smallexample + + Similarly, cyclic diary entries can interpolate the number of repetitions +that have occurred: + +@findex diary-cyclic +@smallexample +%%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time) +@end smallexample + +@noindent +looks like this: + +@smallexample +Renew medication (5th time) +@end smallexample + +@noindent +in the fancy diary display on September 8, 1990. + + There is an early reminder diary sexp that includes its entry in the +diary not only on the date of occurrence, but also on earlier dates. +For example, if you want a reminder a week before your anniversary, you +can use + +@findex diary-remind +@smallexample +%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary +@end smallexample + +@noindent +and the fancy diary will show +@smallexample +Ed's anniversary +@end smallexample +@noindent +both on December 15 and on December 22. + +@findex diary-date + The function @code{diary-date} applies to dates described by a month, +day, year combination, each of which can be an integer, a list of +integers, or @code{t}. The value @code{t} means all values. For +example, + +@smallexample +%%(diary-date '(10 11 12) 22 t) Rake leaves +@end smallexample + +@noindent +causes the fancy diary to show + +@smallexample +Rake leaves +@end smallexample + +@noindent +on October 22, November 22, and December 22 of every year. + +@findex diary-float + The function @code{diary-float} allows you to describe diary entries +that apply to dates like the third Friday of November, or the last +Tuesday in April. The parameters are the @var{month}, @var{dayname}, +and an index @var{n}. The entry appears on the @var{n}th @var{dayname} +of @var{month}, where @var{dayname}=0 means Sunday, 1 means Monday, and +so on. If @var{n} is negative it counts backward from the end of +@var{month}. The value of @var{month} can be a list of months, a single +month, or @code{t} to specify all months. You can also use an optional +parameter @var{day} to specify the @var{n}th @var{dayname} of +@var{month} on or after/before @var{day}; the value of @var{day} defaults +to 1 if @var{n} is positive and to the last day of @var{month} if +@var{n} is negative. For example, + +@smallexample +%%(diary-float t 1 -1) Pay rent +@end smallexample + +@noindent +causes the fancy diary to show + +@smallexample +Pay rent +@end smallexample + +@noindent +on the last Monday of every month. + + The generality of sexp diary entries lets you specify any diary +entry that you can describe algorithmically. A sexp diary entry +contains an expression that computes whether the entry applies to any +given date. If its value is non-@code{nil}, the entry applies to that +date; otherwise, it does not. The expression can use the variable +@code{date} to find the date being considered; its value is a list +(@var{month} @var{day} @var{year}) that refers to the Gregorian +calendar. + + The sexp diary entry applies to a date when the expression's value +is non-@code{nil}, but some values have more specific meanings. If +the value is a string, that string is a description of the event which +occurs on that date. The value can also have the form +@code{(@var{mark} . @var{string})}; then @var{mark} specifies how to +mark the date in the calendar, and @var{string} is the description of +the event. If @var{mark} is a single-character string, that character +appears next to the date in the calendar. If @var{mark} is a face +name, the date is displayed in that face. If @var{mark} is +@code{nil}, that specifies no particular highlighting for the date. + + Suppose you get paid on the 21st of the month if it is a weekday, and +on the Friday before if the 21st is on a weekend. Here is how to write +a sexp diary entry that matches those dates: + +@smallexample +&%%(let ((dayname (calendar-day-of-week date)) + (day (car (cdr date)))) + (or (and (= day 21) (memq dayname '(1 2 3 4 5))) + (and (memq day '(19 20)) (= dayname 5))) + ) Pay check deposited +@end smallexample + + The following sexp diary entries take advantage of the ability (in the fancy +diary display) to concoct diary entries whose text varies based on the date: + +@findex diary-sunrise-sunset +@findex diary-phases-of-moon +@findex diary-day-of-year +@findex diary-iso-date +@findex diary-julian-date +@findex diary-astro-day-number +@findex diary-hebrew-date +@findex diary-islamic-date +@findex diary-french-date +@findex diary-mayan-date +@table @code +@item %%(diary-sunrise-sunset) +Make a diary entry for the local times of today's sunrise and sunset. +@item %%(diary-phases-of-moon) +Make a diary entry for the phases (quarters) of the moon. +@item %%(diary-day-of-year) +Make a diary entry with today's day number in the current year and the number +of days remaining in the current year. +@item %%(diary-iso-date) +Make a diary entry with today's equivalent ISO commercial date. +@item %%(diary-julian-date) +Make a diary entry with today's equivalent date on the Julian calendar. +@item %%(diary-astro-day-number) +Make a diary entry with today's equivalent astronomical (Julian) day number. +@item %%(diary-hebrew-date) +Make a diary entry with today's equivalent date on the Hebrew calendar. +@item %%(diary-islamic-date) +Make a diary entry with today's equivalent date on the Islamic calendar. +@item %%(diary-french-date) +Make a diary entry with today's equivalent date on the French Revolutionary +calendar. +@item %%(diary-mayan-date) +Make a diary entry with today's equivalent date on the Mayan calendar. +@end table + +@noindent +Thus including the diary entry + +@example +&%%(diary-hebrew-date) +@end example + +@noindent +causes every day's diary display to contain the equivalent date on the +Hebrew calendar, if you are using the fancy diary display. (With simple +diary display, the line @samp{&%%(diary-hebrew-date)} appears in the +diary for any date, but does nothing particularly useful.) + + These functions can be used to construct sexp diary entries based on +the Hebrew calendar in certain standard ways: + +@cindex rosh hodesh +@findex diary-rosh-hodesh +@cindex parasha, weekly +@findex diary-parasha +@cindex candle lighting times +@findex diary-sabbath-candles +@cindex omer count +@findex diary-omer +@cindex yahrzeits +@findex diary-yahrzeit +@table @code +@item %%(diary-rosh-hodesh) +Make a diary entry that tells the occurrence and ritual announcement of each +new Hebrew month. +@item %%(diary-parasha) +Make a Saturday diary entry that tells the weekly synagogue scripture reading. +@item %%(diary-sabbath-candles) +Make a Friday diary entry that tells the @emph{local time} of Sabbath +candle lighting. +@item %%(diary-omer) +Make a diary entry that gives the omer count, when appropriate. +@item %%(diary-yahrzeit @var{month} @var{day} @var{year}) @var{name} +Make a diary entry marking the anniversary of a date of death. The date +is the @emph{Gregorian} (civil) date of death. The diary entry appears +on the proper Hebrew calendar anniversary and on the day before. (In +the European style, the order of the parameters is changed to @var{day}, +@var{month}, @var{year}.) +@end table + + All the functions documented above take an optional argument +@var{mark} which specifies how to mark the date in the calendar display. +If one of these functions decides that it applies to a certain date, +it returns a value that contains @var{mark}. + +@ignore + arch-tag: 52cb299f-fd1f-4616-bfe6-91b988669431 +@end ignore diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi new file mode 100644 index 00000000000..5182474622d --- /dev/null +++ b/doc/emacs/calendar.texi @@ -0,0 +1,1687 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 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. It also has facilities for managing your +appointments, and keeping track of how much time you spend working on +certain projects. + + 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{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}. + +@iftex + This chapter describes the basic calendar features. +@inforef{Advanced Calendar/Diary Usage,, emacs-xtra}, for information +about more specialized features. +@end iftex + +@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. +* Writing Calendar Files:: Writing calendars to files of various formats. +* 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. +* Importing Diary:: Converting diary events to/from other formats. +* Daylight Saving:: How to specify when daylight saving time is active. +* Time Intervals:: Keeping track of time intervals. +@ifnottex +* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. +@end ifnottex +@end menu + +@node Calendar Motion +@section Movement in the Calendar + +@cindex moving inside the calendar + Calendar mode provides commands to 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 by long 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. 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, keeping the same date within the 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 g D +Move point to specified day of year (@code{calendar-goto-day-of-year}). +@item g w +Move point to specified week of year (@code{calendar-goto-iso-week}). +@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 g D @r{(Calendar mode)} +@findex calendar-goto-day-of-year +@kindex g w @r{(Calendar mode)} +@findex calendar-goto-iso-week + @kbd{g D} (@code{calendar-goto-day-of-year}) prompts for a year and +day number, and moves to that date. Negative day numbers count +backward from the end of the year. @kbd{g w} +(@code{calendar-goto-iso-week}) prompts for a year and week number, +and moves to that week. + +@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 the calendar means moving the strip +horizontally, so that new months become visible in the window. + +@table @kbd +@item > +Scroll calendar one month forward (@code{scroll-calendar-left}). +@item < +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 > @r{(Calendar mode)} +@findex scroll-calendar-left +@kindex < @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{>} scrolls the +calendar contents one month forward in time. @kbd{<} scrolls the +contents one month 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 shown 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 up (@code{scroll-other-window}). +@item DEL +Scroll the next window down (@code{scroll-other-window-down}). +@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 display 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 count of days elapsed includes the +selected date. The count 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}) +and @kbd{DEL} (@code{scroll-other-window-down}) to scroll the other +window up or down, respectively. 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 Writing Calendar Files +@section Writing Calendar Files + + These packages produce files of various formats containing calendar +and diary entries, for display purposes. + +@cindex calendar and HTML + The Calendar HTML commands produce files of HTML code that contain +calendar and diary entries. Each file applies to one month, and has a +name of the format @file{@var{yyyy}-@var{mm}.html}, where @var{yyyy} and +@var{mm} are the four-digit year and two-digit month, respectively. The +variable @code{cal-html-directory} specifies the default output +directory for the HTML files. + +@vindex cal-html-css-default + Diary entries enclosed by @code{<} and @code{>} are interpreted as +HTML tags (for example: this is a diary entry with <font +color=''red''>some red text</font>). You can change the overall +appearance of the displayed HTML pages (for example, the color of +various page elements, header styles) via a stylesheet @file{cal.css} in +the directory containing the HTML files (see the value of the variable +@code{cal-html-css-default} for relevant style settings). + +@kindex t @r{(Calendar mode)} +@table @kbd +@item H m +Generate a one-month calendar (@code{cal-html-cursor-month}). +@item H y +Generate a calendar file for each month of a year, as well as an index +page (@code{cal-html-cursor-year}). By default, this command writes +files to a @var{yyyy} subdirectory - if this is altered some hyperlinks +between years will not work. +@end table + + If the variable @code{cal-html-print-day-number-flag} is +non-@code{nil}, then the monthly calendars show the day-of-the-year +number. The variable @code{cal-html-year-index-cols} specifies the +number of columns in the yearly index page. + +@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 monthly, filofax, and +iso-week calendars only). If the variable @code{cal-tex-rules} is +non-@code{nil} (the default is @code{nil}), the calendar displays ruled +pages in styles that have sufficient room. Consult the documentation of +the individual cal-tex functions to see which calendars support which +features. + + You can use the variable @code{cal-tex-preamble-extra} to insert extra +La@TeX{} commands in the preamble of the generated document if you need +to. + +@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 +@vindex view-calendar-holidays-initially + 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 +@vindex mark-holidays-in-calendar + 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). +@iftex +@inforef{Calendar Customizing, calendar-holiday-marker, emacs-xtra}. +@end iftex +@ifnottex +@xref{Calendar Customizing, calendar-holiday-marker}. +@end ifnottex + 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}). If the variable +@code{mark-holidays-in-calendar} is non-@code{nil}, creating or +updating the calendar marks holidays automatically. + +@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} and @key{DEL} in the +calendar window to scroll that list up and down, respectively. + +@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 the variable +@code{view-calendar-holidays-initially} is non-@code{nil}, creating +the calendar displays holidays in this way. 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. For example Veteran's Day began in +1919, but is shown in earlier 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 +@samp{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 saving time}. @xref{Daylight Saving}, +for how daylight saving 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 saving, when appropriate); but if +the variable @code{calendar-time-zone} is void, Coordinated Universal +Time (the Greenwich time zone) is used. @xref{Daylight Saving}. + +@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 @dfn{Julian day number} or the @dfn{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. +The calendar implemented here is the arithmetical Persian calendar +championed by Birashk, based on a 2,820-year cycle. It differs from +the astronomical Persian calendar, which is based on astronomical +events. As of this writing the first future discrepancy is projected +to occur on March 20, 2025. It is currently not clear what the +official calendar of Iran will be that far into the future. + +@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.) + + Otherwise, move point to the date you want to convert, then type the +appropriate command starting with @kbd{p} from the table above. The +prefix @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-iso-week +@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 w +Move to a week specified in the ISO commercial calendar +(@code{calendar-goto-iso-week}). +@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 with an 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.3, 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. + + The name of the diary file is specified by the variable +@code{diary-file}; @file{~/diary} is the default. A sample diary file +is (note that the file format is essentially the same as that used by +the external shell utility @samp{calendar}): + +@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 +* Displaying the Diary:: 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 Displaying the Diary +@subsection Displaying the Diary + + Once you have created a 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{diary-view-entries}). +@item Mouse-2 Diary +Display all diary entries for the date you click on. +@item s +Display the entire diary file (@code{diary-show-all-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 diary-view-entries +@vindex view-diary-entries-initially + 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 entries} from +the menu that appears. If the variable +@code{view-diary-entries-initially} is non-@code{nil}, creating the +calendar lists the diary entries for the current date (provided the +current date is visible). + +@kindex m @r{(Calendar mode)} +@findex mark-diary-entries +@vindex mark-diary-entries-in-calendar + 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). +@iftex +@inforef{Calendar Customizing, diary-entry-marker, emacs-xtra}. +@end iftex +@ifnottex +@xref{Calendar Customizing, diary-entry-marker}. +@end ifnottex + 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}). If the variable +@code{mark-diary-entries-in-calendar} is non-@code{nil}, creating or +updating the calendar marks diary dates automatically. + +@kindex s @r{(Calendar mode)} +@findex diary-show-all-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{Printing}). + +@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. +@iftex +@inforef{Diary Customizing,, emacs-xtra}. +@end iftex +@ifnottex +@xref{Diary Customizing, number-of-diary-entries}. +@end ifnottex + + 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{diary-show-all-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 (with or without a period). The +preferred abbreviations can be controlled using the variables +@code{calendar-abbrev-length}, @code{calendar-month-abbrev-array}, and +@code{calendar-day-abbrev-array}. The default is to use the first three +letters of a name as its abbreviation. 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} +with @kbd{M-x customize}, or @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 the 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. Saving the diary file after using any of the above +insertion commands will automatically update the diary marks in the +calendar window, if appropriate. You can use the command +@code{redraw-calendar} to force an update at any time. + +@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 + + Each of the standard sexp diary entries takes an optional parameter +specifying the name of a face or a single-character string to use when +marking the entry in the calendar. Most generally, sexp diary entries +can perform arbitrary computations to determine when they apply. +@iftex +@inforef{Sexp Diary Entries,, emacs-xtra}. +@end iftex +@ifnottex +@inforef{Sexp Diary Entries}. +@end ifnottex + +@node Appointments +@section Appointments +@cindex appointment notification + +@vindex appt-display-format +@vindex appt-audible +@vindex appt-display-mode-line + 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 your chosen format, as +specified by the variable @code{appt-display-format}. If the value of +@code{appt-audible} is non-@code{nil}, the warning includes an audible +reminder. In addition, if @code{appt-display-mode-line} is +non-@code{nil}, Emacs displays the number of minutes to the +appointment on the mode line. + +@vindex appt-display-duration +@vindex appt-disp-window-function +@vindex appt-delete-window-function + If @code{appt-display-format} has the value @code{window}, then the +variable @code{appt-display-duration} controls how long the reminder +window is visible for; and the variables +@code{appt-disp-window-function} and @code{appt-delete-window-function} +give the names of functions used to create and destroy the window, +respectively. + +@findex appt-activate + To enable appointment notification, use the command @kbd{M-x +appt-activate}. With a positive argument, it enables notification; +with a negative argument, it disables notification; with no argument, +it toggles. Enabling notification also sets up an appointment list +for today from the diary file, giving all 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 + +@vindex appt-message-warning-time +@noindent +Then on Mondays, you will be reminded at around 9:20am about your +coffee break and at around 11:50am about lunch. The variable +@code{appt-message-warning-time} specifies how many minutes in advance +to warn you; its default value is 12 (12 minutes). + + 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. Times must be at the beginning +of lines if they are to be recognized. + +@vindex appt-display-diary + Emacs updates the appointments list from the diary file +automatically just after midnight. You can force an update at any +time by re-enabling appointment notification. Both these actions also +display the day's diary buffer, unless you set +@code{appt-display-diary} to @code{nil}. The appointments list is +also updated whenever the diary file is saved. + +@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}. + +@node Importing Diary +@section Importing and Exporting Diary Entries + + You can transfer diary entries between Emacs diary files and a +variety of other formats. + +@vindex diary-outlook-formats + You can import diary entries from Outlook-generated appointment +messages. While viewing such a message in Rmail or Gnus, do @kbd{M-x +diary-from-outlook} to import the entry. You can make this command +recognize additional appointment message formats by customizing the +variable @code{diary-outlook-formats}. + +@cindex iCalendar support + The icalendar package allows you to transfer data between your Emacs +diary file and iCalendar files, which are defined in ``RFC +2445---Internet Calendaring and Scheduling Core Object Specification +(iCalendar)'' (as well as the earlier vCalendar format). + + Importing works for ``ordinary'' (i.e. non-recurring) events, but +(at present) may not work correctly (if at all) for recurring events. +Exporting of diary files into iCalendar files should work correctly +for most diary entries. This feature is a work in progress, so the +commands may evolve in future. + +@findex icalendar-import-buffer + The command @code{icalendar-import-buffer} extracts +iCalendar data from the current buffer and adds it to your (default) +diary file. This function is also suitable for automatic extraction of +iCalendar data; for example with the Rmail mail client one could use: + +@example +(add-hook 'rmail-show-message-hook 'icalendar-import-buffer) +@end example + +@findex icalendar-import-file + The command @code{icalendar-import-file} imports an iCalendar file +and adds the results to an Emacs diary file. For example: + +@example +(icalendar-import-file "/here/is/calendar.ics" + "/there/goes/ical-diary") +@end example + +@noindent +You can use an @code{#include} directive to add the import file contents +to the main diary file, if these are different files. +@iftex +@inforef{Fancy Diary Display,, emacs-xtra}. +@end iftex +@ifnottex +@xref{Fancy Diary Display}. +@end ifnottex + + +@findex icalendar-export-file, icalendar-export-region + Use @code{icalendar-export-file} to interactively export an entire +Emacs diary file to iCalendar format. To export only a part of a diary +file, mark the relevant area, and call @code{icalendar-export-region}. +In both cases the result is appended to the target file. + +@node Daylight Saving +@section Daylight Saving Time +@cindex daylight saving time + + Emacs understands the difference between standard time and daylight +saving time---the times given for sunrise, sunset, solstices, +equinoxes, and the phases of the moon take that into account. The rules +for daylight saving 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 +saving 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 saving time. + + Emacs uses these expressions to determine the starting date of +daylight saving 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 2 0 3 year) +(calendar-nth-named-day 1 0 11 year) +@end example + +@noindent +That is, the second 0th day (Sunday) of the third month (March) in +the year specified by @code{year}, and the first Sunday of the eleventh month +(November) of that year. If daylight saving 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 saving 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 saving 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 + Finally, 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 saving time should occur. For Cambridge, Massachusetts both +variables' values are 120. + +@node Time Intervals +@section Summing Time Intervals +@cindex time intervals, summing +@cindex summing time intervals +@cindex timeclock + + The timeclock feature adds up time intervals, so you can (for +instance) keep track of how much time you spend working on particular +projects. + +@findex timeclock-in +@findex timeclock-out +@findex timeclock-change +@findex timeclock-workday-remaining +@findex timeclock-when-to-leave + Use the @kbd{M-x timeclock-in} command when you start working on a +project, and @kbd{M-x timeclock-out} command when you're done. Each +time you do this, it adds one time interval to the record of the +project. You can change to working on a different project with @kbd{M-x +timeclock-change}. + + Once you've collected data from a number of time intervals, you can use +@kbd{M-x timeclock-workday-remaining} to see how much time is left to +work today (assuming a typical average of 8 hours a day), and @kbd{M-x +timeclock-when-to-leave} which will calculate when you're ``done.'' + +@vindex timeclock-modeline-display +@findex timeclock-modeline-display + If you want Emacs to display the amount of time ``left'' of your +workday in the mode line, either customize the +@code{timeclock-modeline-display} variable and set its value to +@code{t}, or invoke the @kbd{M-x timeclock-modeline-display} command. + +@vindex timeclock-ask-before-exiting + Terminating the current Emacs session might or might not mean that +you have stopped working on the project and, by default, Emacs asks +you. You can, however, set the value of the variable +@code{timeclock-ask-before-exiting} to @code{nil} (via @kbd{M-x +customize}) to avoid the question; then, only an explicit @kbd{M-x +timeclock-out} or @kbd{M-x timeclock-change} will tell Emacs that the +current interval is over. + +@cindex @file{.timelog} file +@vindex timeclock-file +@findex timeclock-reread-log + The timeclock functions work by accumulating the data in a file +called @file{.timelog} in your home directory. You can specify a +different name for this file by customizing the variable +@code{timeclock-file}. If you edit the timeclock file manually, or if +you change the value of any of timeclock's customizable variables, you +should run the command @kbd{M-x timeclock-reread-log} to update the +data in Emacs from the file. + +@ifnottex +@include cal-xtra.texi +@end ifnottex + +@ignore + arch-tag: 4531ef09-9df3-449d-9c52-2b5a4a337f92 +@end ignore diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi new file mode 100644 index 00000000000..28bad72f0bf --- /dev/null +++ b/doc/emacs/cmdargs.texi @@ -0,0 +1,1263 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, +@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Emacs Invocation, X Resources, GNU Free Documentation License, Top +@appendix Command Line Arguments for Emacs Invocation +@cindex command line arguments +@cindex arguments (command line) +@cindex options (command line) +@cindex switches (command line) +@cindex startup (command line arguments) +@cindex invocation (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}, and so is +@samp{+@var{linenum}}. All 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 visited in other buffers. If there are two files, they are +both displayed; otherwise the last file is displayed along with a +buffer list that shows what other buffers there are. As with most +programs, 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) +@vindex command-line-args + 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 +terminate 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. The @file{.emacs} file +can access the values of the action arguments as the elements of a list in +the variable @code{command-line-args}. + + + +@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:: Choosing display colors. +* 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. +* Misc X:: Other display options. +@end menu + +@node Action Arguments +@appendixsec Action Arguments + + Here is a table of the action arguments and options: + +@table @samp +@item @var{file} +@opindex --file +@itemx --file=@var{file} +@opindex --find-file +@itemx --find-file=@var{file} +@opindex --visit +@itemx --visit=@var{file} +@cindex visiting files, command-line argument +@vindex inhibit-startup-buffer-menu +Visit @var{file} using @code{find-file}. @xref{Visiting}. +If you visit several files at startup in this way, Emacs +also displays a Buffer Menu buffer to show you what files it +has visited. You can inhibit that by setting @code{inhibit-startup-buffer-menu} to @code{t}. + +@item +@var{linenum} @var{file} +@opindex +@var{linenum} +Visit @var{file} using @code{find-file}, then go to line number +@var{linenum} in it. + +@item +@var{linenum}:@var{columnnum} @var{file} +Visit @var{file} using @code{find-file}, then go to line number +@var{linenum} and put point at column number @var{columnnum}. + +@need 3000 +@item -l @var{file} +@opindex -l +@itemx --load=@var{file} +@opindex --load +@cindex loading Lisp libraries, command-line argument +Load a Lisp library named @var{file} with the function @code{load}. +@xref{Lisp Libraries}. If @var{file} is not an absolute file name, +the library can be found either in the current directory, or in the +Emacs library search path as specified with @env{EMACSLOADPATH} +(@pxref{General Variables}). + +@strong{Warning:} If previous command-line arguments have visited +files, the current directory is the directory of the last file +visited. + +@item -L @var{dir} +@opindex -L +@itemx --directory=@var{dir} +@opindex --directory +Add directory @var{dir} to the variable @code{load-path}. + +@item -f @var{function} +@opindex -f +@itemx --funcall=@var{function} +@opindex --funcall +@cindex call Lisp functions, command-line argument +Call Lisp function @var{function}. If it is an interactive function +(a command), it reads the arguments interactively just as if you had +called the same function with a key sequence. Otherwise, it calls the +function with no arguments. + +@item --eval=@var{expression} +@opindex --eval +@itemx --execute=@var{expression} +@opindex --execute +@cindex evaluate expression, command-line argument +Evaluate Lisp expression @var{expression}. + +@item --insert=@var{file} +@opindex --insert +@cindex insert file contents, command-line argument +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 +@opindex --kill +Exit from Emacs without asking for confirmation. + +@item --help +@opindex --help +Print a usage message listing all available options, then exit +successfully. + +@item --version +@opindex --version +Print Emacs version, then exit successfully. +@end table + +@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 the X Window System 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. @xref{Init File}. Certain options +prevent loading of some of these files or substitute other files for +them. + +@table @samp +@item -t @var{device} +@opindex -t +@itemx --terminal=@var{device} +@opindex --terminal +@cindex device for Emacs terminal I/O +Use @var{device} as the device for terminal input and output. +@samp{--terminal} implies @samp{--no-window-system}. + +@item -d @var{display} +@opindex -d +@itemx --display=@var{display} +@opindex --display +@cindex display for Emacs frame +Use the X Window System and use the display named @var{display} to open +the initial Emacs frame. @xref{Display X}, for more details. + +@item -nw +@opindex -nw +@itemx --no-window-system +@opindex --no-window-system +@cindex disable window system +Don't communicate directly with the window system, disregarding the +@env{DISPLAY} environment variable even if it is set. This means that +Emacs uses the terminal from which it was launched for all its display +and input. + +@need 3000 +@cindex batch mode +@item -batch +@opindex --batch +@itemx --batch +Run Emacs in @dfn{batch mode}. Batch mode is used for running +programs written in Emacs Lisp from shell scripts, makefiles, and so +on. You should also use the @samp{-l}, @samp{-f} or @samp{--eval} +option, to invoke a Lisp program to do batch processing. + +In batch mode, Emacs does not display the text being edited, and the +standard terminal interrupt characters such as @kbd{C-z} and @kbd{C-c} +continue to have their normal effect. The functions @code{prin1}, +@code{princ} and @code{print} output to @code{stdout} instead of the +echo area, while @code{message} and error messages output to +@code{stderr}. Functions that would normally read from the minibuffer +take their input from @code{stdin} instead. + +@samp{--batch} implies @samp{-q} (do not load an init file), but +@file{site-start.el} is loaded nonetheless. It also causes Emacs to +exit after processing all the command options. In addition, it +disables auto-saving except in buffers for which it has been +explicitly requested. + +@item --script @var{file} +@opindex --script +@cindex script mode +Run Emacs in batch mode, like @samp{--batch}, and then read and +execute the Lisp code in @var{file}. + +The normal use of this option is in executable script files that run +Emacs. They can start with this text on the first line + +@example +#!/usr/bin/emacs --script +@end example + +@noindent +which will invoke Emacs with @samp{--script} and supply the name of +the script file as @var{file}. Emacs Lisp then treats @samp{#!} as a +comment delimiter. + +@item -q +@opindex -q +@itemx --no-init-file +@opindex --no-init-file +@cindex bypassing init and @file{default.el} file +@cindex init file, not loading +@cindex @file{default.el} file, not loading +Do not load your Emacs init file @file{~/.emacs}, or @file{default.el} +either. Regardless of this switch, @file{site-start.el} is still loaded. +When invoked like this, Emacs does not allow saving options +changed with the @kbd{M-x customize} command and its variants. +@xref{Easy Customization}. + +@item --no-site-file +@opindex --no-site-file +@cindex @file{site-start.el} file, not loading +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 +option and @samp{-Q} are the only options that block it. + +@item -Q +@opindex -Q +@itemx --quick +@opindex --quick +Start emacs with minimum customizations. This is like using @samp{-q} +and @samp{--no-site-file}, but also disables the startup screen. + +@item --no-splash +@opindex --no-splash +@vindex inhibit-splash-screen +@cindex splash screen +@cindex startup message +Do not display a splash screen on startup. You can also achieve this +effect by setting the variable @code{inhibit-splash-screen} to +non-@code{nil} in you personal init file (but @emph{not} in +@file{site-start.el}). (This variable was called +@code{inhibit-startup-message} in previous Emacs versions.) + +@item --no-desktop +@opindex --no-desktop +Do not reload any saved desktop. @xref{Saving Emacs Sessions}. + +@item -u @var{user} +@opindex -u +@itemx --user=@var{user} +@opindex --user +@cindex load init file of another user +Load @var{user}'s Emacs init file @file{~@var{user}/.emacs} instead of +your own@footnote{ +This option has no effect on MS-Windows.}. + +@item --debug-init +@opindex --debug-init +@cindex errors in init file +Enable the Emacs Lisp debugger for errors in the init file. +@xref{Error Debugging,, Entering the Debugger on an Error, elisp, The +GNU Emacs Lisp Reference Manual}. + +@item --unibyte +@opindex --unibyte +@itemx --no-multibyte +@opindex --no-multibyte +@cindex unibyte operation, command-line argument +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. (Note that Emacs +always loads Lisp files in multibyte mode, even if @samp{--unibyte} is +specified; see @ref{Enabling Multibyte}.) Setting the environment +variable @env{EMACS_UNIBYTE} has the same effect +(@pxref{General Variables}). + +@item --multibyte +@opindex --multibyte +@itemx --no-unibyte +@opindex --no-unibyte +Inhibit the effect of @env{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}): + +@c `resume-suspend-hook' is correct. It is the name of a function. +@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. The scripts are found in the +@file{etc} subdirectory of the Emacs distribution. + + 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; there is no way to define a command that could +be made the value of @env{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 + + The @dfn{environment} is a feature of the operating system; it +consists of a collection of variables with names and values. Each +variable is called an @dfn{environment variable}; environment variable +names are case-sensitive, and it is conventional to use upper case +letters only. The values are all text strings. + + What makes the environment useful is that subprocesses inherit the +environment automatically from their parent process. This means you +can set up an environment variable in your login shell, and all the +programs you run (including Emacs) will automatically see it. +Subprocesses of Emacs (such as shells, compilers, and version-control +software) inherit the environment from Emacs, too. + +@findex setenv +@findex getenv + Inside Emacs, the command @kbd{M-x getenv} gets the value of an +environment variable. @kbd{M-x setenv} sets a variable in the Emacs +environment. (Environment variable substitutions with @samp{$} work +in the value just as in file names; see @ref{File Names with $}.) + + The way to set environment variables outside of Emacs depends on the +operating system, and especially the shell that you are using. For +example, here's how to set the environment variable @env{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 using the X Window System, various environment +variables that control X work for Emacs as well. See the X +documentation for more information. + +@menu +* General Variables:: Environment variables that all versions of Emacs use. +* Misc Variables:: Certain system-specific variables. +* MS-Windows Registry:: An alternative to the environment on MS-Windows. +@end menu + +@node General Variables +@appendixsubsec General Variables + + Here is an alphabetical list of specific environment variables that +have special meanings in Emacs, giving the name of each variable and +its meaning. Most of these variables are also used by some other +programs. Emacs does not require any of these environment variables +to be set, but it uses their values if they are set. + +@table @env +@item CDPATH +Used by the @code{cd} command to search for the directory you specify, +when you specify a relative directory name. +@item EMACS_UNIBYTE +@cindex unibyte operation, environment variable +Defining this environment variable with a nonempty value 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 +Directory for the architecture-independent files that come with Emacs. +This is used to initialize the Lisp variable @code{data-directory}. +@item EMACSDOC +Directory for the documentation string file, +@file{DOC-@var{emacsversion}}. This is used to initialize the Lisp +variable @code{doc-directory}. +@item EMACSLOADPATH +A colon-separated list of directories@footnote{ +Here and below, whenever we say ``colon-separated list of directories,'' +it pertains to Unix and GNU/Linux systems. On MS-DOS and MS-Windows, +the directories are separated by semi-colons instead, since DOS/Windows +file names might include a colon after a drive letter.} +to search for Emacs Lisp files---used to initialize @code{load-path}. +@item EMACSPATH +A colon-separated list of directories to search for executable +files---used to initialize @code{exec-path}. +@item EMAIL +@vindex user-mail-address@r{, initialization} +Your email address; used to initialize the Lisp variable +@code{user-mail-address}, which the Emacs mail interface puts into +the @samp{From} header of outgoing messages (@pxref{Mail Headers}). +@item ESHELL +Used for shell-mode to override the @env{SHELL} environment variable. +@item HISTFILE +The name of the file that shell commands are saved in between logins. +This variable defaults 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 your 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. On Windows, the +default value of @env{HOME} is the @file{Application Data} +subdirectory of the user profile directory (normally, this is +@file{C:/Documents and Settings/@var{username}/Application Data}, +where @var{username} is your user name), though for backwards +compatibility @file{C:/} will be used instead if a @file{.emacs} file +is found there. +@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 in which to search for Info files. +@item LC_ALL +@itemx LC_COLLATE +@itemx LC_CTYPE +@itemx LC_MESSAGES +@itemx LC_MONETARY +@itemx LC_NUMERIC +@itemx LC_TIME +@itemx LANG +The user's preferred locale. The locale has six categories, specified +by the environment variables @env{LC_COLLATE} for sorting, +@env{LC_CTYPE} for character encoding, @env{LC_MESSAGES} for system +messages, @env{LC_MONETARY} for monetary formats, @env{LC_NUMERIC} for +numbers, and @env{LC_TIME} for dates and times. If one of these +variables is not set, the category defaults to the value of the +@env{LANG} environment variable, or to the default @samp{C} locale if +@env{LANG} is not set. But if @env{LC_ALL} is specified, it overrides +the settings of all the other locale environment variables. + +On MS-Windows, if @env{LANG} is not already set in the environment +when Emacs starts, Emacs sets it based on the system-wide default +language, which you can set in the @samp{Regional Settings} Control Panel +on some versions of MS-Windows. + +The value of the @env{LC_CTYPE} category is +matched against entries in @code{locale-language-names}, +@code{locale-charset-language-names}, and +@code{locale-preferred-coding-systems}, to select a default language +environment and coding system. @xref{Language Environments}. +@item LOGNAME +The user's login name. See also @env{USER}. +@item MAIL +The name of your system mail inbox. +@item MH +Name of setup file for the mh system. (The default is @file{~/.mh_profile}.) +@item NAME +Your real-world name. +@item NNTPSERVER +The name of the news server. Used by the mh and Gnus packages. +@item ORGANIZATION +The name of the organization to which you belong. Used for setting the +`Organization:' header in your posts from the Gnus package. +@item PATH +A colon-separated list of directories in which executables reside. This +is used to initialize the Emacs Lisp variable @code{exec-path}. +@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 Gnus package. +@item SHELL +The name of an interpreter used to parse and execute programs run from +inside Emacs. +@item SMTPSERVER +The name of the outgoing mail server. Used by the SMTP library +(@pxref{Top,,,smtpmail,Sending mail via SMTP}). +@cindex background mode, on @command{xterm} +@item TERM +The type of the terminal that Emacs is using. This 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. If the value of @env{TERM} indicates +that Emacs runs in non-windowed mode from @command{xterm} or a similar +terminal emulator, the background mode defaults to @samp{light}, and +Emacs will choose colors that are appropriate for a light background. +@item TERMCAP +The name of the termcap library file describing how to program the +terminal specified by the @env{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 +saving time information. On MS-DOS, if @env{TZ} is not set in the +environment when Emacs starts, Emacs defines a default value as +appropriate for the country code returned by DOS. On MS-Windows, Emacs +does not use @env{TZ} at all. +@item USER +The user's login name. See also @env{LOGNAME}. On MS-DOS, this +defaults to @samp{root}. +@item VERSION_CONTROL +Used to initialize the @code{version-control} variable (@pxref{Numbered Backups}). +@end table + +@node Misc Variables +@appendixsubsec Miscellaneous Variables + +These variables are used only on particular configurations: + +@table @env +@item COMSPEC +On MS-DOS and MS-Windows, the name of the command interpreter to use +when invoking batch files and commands internal to the shell. On MS-DOS +this is also used to make a default value for the @env{SHELL} environment +variable. + +@item NAME +On MS-DOS, this variable defaults to the value of the @env{USER} +variable. + +@item TEMP +@itemx TMP +On MS-DOS and MS-Windows, 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 +On MS-DOS, this specifies the screen colors. It is useful to set them +this way, since otherwise Emacs would display the default colors +momentarily when it starts up. + +The value of this variable should be the 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. For example, to get blue text on a light gray background, +specify @samp{EMACSCOLORS=17}, since 1 is the code of the blue color and +7 is the code of the light gray color. + +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. + +@item PRELOAD_WINSOCK +On MS-Windows, if you set this variable, Emacs will load and initialize +the network library at startup, instead of waiting until the first +time it is required. + +@item emacs_dir +On MS-Windows, @env{emacs_dir} is a special environment variable, which +indicates the full path of the directory in which Emacs is installed. +If Emacs is installed in the standard directory structure, it +calculates this value automatically. It is not much use setting this +variable yourself unless your installation is non-standard, since +unlike other environment variables, it will be overridden by Emacs at +startup. When setting other environment variables, such as +@env{EMACSLOADPATH}, you may find it useful to use @env{emacs_dir} +rather than hard-coding an absolute path. This allows multiple +versions of Emacs to share the same environment variable settings, and +it allows you to move the Emacs installation directory, without +changing any environment or registry settings. +@end table + +@node MS-Windows Registry +@appendixsubsec The MS-Windows System Registry +@pindex addpm, MS-Windows installation program +@cindex registry, setting environment variables and resources on MS-Windows + +Under MS-Windows, the installation program @command{addpm.exe} adds +values for @env{emacs_dir}, @env{EMACSLOADPATH}, @env{EMACSDATA}, +@env{EMACSPATH}, @env{EMACSDOC}, @env{SHELL} and @env{TERM} to the +@file{HKEY_LOCAL_MACHINE} section of the system registry, under +@file{/Software/GNU/Emacs}. It does this because there is no standard +place to set environment variables across different versions of +Windows. Running @command{addpm.exe} is no longer strictly necessary +in recent versions of Emacs, but if you are upgrading from an older +version, running @command{addpm.exe} ensures that you do not have +older registry entries from a previous installation, which may not be +compatible with the latest version of Emacs. + +When Emacs starts, as well as checking the environment, it also checks +the System Registry for those variables and for @env{HOME}, @env{LANG} +and @env{PRELOAD_WINSOCK}. + +To determine the value of those variables, Emacs goes through the +following procedure. First, the environment is checked. If the +variable is not found there, Emacs looks for registry keys by that +name under @file{/Software/GNU/Emacs}; first in the +@file{HKEY_CURRENT_USER} section of the registry, and if not found +there, in the @file{HKEY_LOCAL_MACHINE} section. Finally, if Emacs +still cannot determine the values, compiled-in defaults are used. + +In addition to the environment variables above, you can also add many +of the settings which on X belong in the @file{.Xdefaults} file +(@pxref{X Resources}) to the @file{/Software/GNU/Emacs} registry key. +Settings you add to the @file{HKEY_LOCAL_MACHINE} section will affect +all users of the machine. Settings you add to the +@file{HKEY_CURRENT_USER} section will only affect you, and will +override machine wide settings. + +@node Display X +@appendixsec Specifying the Display Name +@cindex display name (X Window System) +@cindex @env{DISPLAY} environment variable + + The environment variable @env{DISPLAY} tells all X clients, including +Emacs, where to display their windows. Its value is set 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 log in +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 @env{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 +@env{DISPLAY} is @samp{glasperle:0.0}. + + You can specify the display name explicitly when you run Emacs, either +by changing the @env{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 the window system and GUI with the +@samp{-nw} option. It tells Emacs to display using ordinary @acronym{ASCII} on +its controlling terminal. This is also an initial option. + + 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 @command{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 Window System) + + By default, Emacs displays text in a twelve point Courier font (when +using X). You can specify a different font on your command line +through the option @samp{-fn @var{name}} (or @samp{--font}, which is +an alias for @samp{-fn}). + +@table @samp +@item -fn @var{name} +@opindex -fn +@itemx --font=@var{name} +@opindex --font +@cindex specify default font from the command line +Use font @var{name} as the default font. +@end table + + Under X, each font has a long name which consists of fourteen words +or numbers, separated by dashes. Some fonts also have shorter +nicknames. For instance, @samp{9x15} is such a nickname. This font +makes each character nine pixels wide and fifteen pixels high. You +can use either kind of name. Case is insignificant in both kinds. +You can use wildcard patterns for the font name; then Emacs lets X +choose one of the fonts that match the pattern. The wildcard +character @samp{*} matches any sequence of characters (including none) +and @samp{?} matches any single character. However, matching is +implementation-dependent, and can be inaccurate when wildcards match +dashes in a long name. For reliable results, supply all 14 dashes and +use wildcards only within a field. 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 + + Note that if you use a wildcard pattern on the command line, you +need to enclose it in single or double quotes, to prevent the shell +from accidentally expanding it into a list of file names. On the +other hand, you should not quote the name in the @file{.Xdefaults} +file. + +The default font used by Emacs (under X) is: + +@smallexample +-adobe-courier-medium-r-*-*-*-120-*-*-*-*-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{registry}-@var{encoding} +@end smallexample + +@table @var +@item maker +This is the name of the font manufacturer. +@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 pixels 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). +@item width +This is the average character width, in pixels, multiplied by ten. +@item registry +@itemx encoding +These together make up the X font character set that the font depicts. +(X font character sets are not the same as Emacs charsets, but they +are solutions for the same problem.) You can use the +@command{xfontsel} program to check which choices you have. However, +normally you should use @samp{iso8859} for @var{registry} and @samp{1} +for @var{encoding}. +@end table + +@cindex listing system fonts + You will probably want to use a fixed-width default font---that is, +a font in which all characters have the same width. 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 @command{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 @command{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 +@appendixsec Window Color Options +@cindex color of window, from command line +@cindex text colors, from command line + +@findex list-colors-display +@cindex available colors + 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, type @kbd{M-x list-colors-display}, or press +@kbd{C-Mouse-2} and select @samp{Display Colors} from the pop-up menu. +(A particular window system might support many more colors, but the +list displayed by @code{list-colors-display} shows their portable +subset that can be safely used on any display supported by Emacs.) +If you do not specify colors, on windowed displays 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. On terminals, the +background is usually black and the foreground is white. + + Here is a list of the command-line options for specifying colors: + +@table @samp +@item -fg @var{color} +@opindex -fg +@itemx --foreground-color=@var{color} +@opindex --foreground-color +@cindex foreground color, command-line argument +Specify the foreground color. @var{color} should be a standard color +name, or a numeric specification of the color's red, green, and blue +components as in @samp{#4682B4} or @samp{RGB:46/82/B4}. +@item -bg @var{color} +@opindex -bg +@itemx --background-color=@var{color} +@opindex --background-color +@cindex background color, command-line argument +Specify the background color. +@item -bd @var{color} +@opindex -bd +@itemx --border-color=@var{color} +@opindex --border-color +@cindex border color, command-line argument +Specify the color of the border of the X window. +@item -cr @var{color} +@opindex -cr +@itemx --cursor-color=@var{color} +@opindex --cursor-color +@cindex cursor color, command-line argument +Specify the color of the Emacs cursor which indicates where point is. +@item -ms @var{color} +@opindex -ms +@itemx --mouse-color=@var{color} +@opindex --mouse-color +@cindex mouse pointer color, command-line argument +Specify the color for the mouse cursor when the mouse is in the Emacs window. +@item -r +@opindex -r +@itemx -rv +@opindex -rv +@itemx --reverse-video +@opindex --reverse-video +@cindex reverse video, command-line argument +Reverse video---swap the foreground and background colors. +@item --color=@var{mode} +@opindex --color +@cindex standard colors on a character terminal +@cindex override character terminal color support +For a character terminal only, specify the mode of color support. +This option is intended for overriding the number of supported colors +that the character terminal advertises in its @code{termcap} or +@code{terminfo} database. The parameter @var{mode} can be one of the +following: +@table @samp +@item never +@itemx no +Don't use colors even if the terminal's capabilities specify color +support. +@item default +@itemx auto +Same as when @option{--color} is not used at all: Emacs detects at +startup whether the terminal supports colors, and if it does, turns on +colored display. +@item always +@itemx yes +@itemx ansi8 +Turn on the color support unconditionally, and use color commands +specified by the ANSI escape sequences for the 8 standard colors. +@item @var{num} +Use color mode for @var{num} colors. If @var{num} is -1, turn off +color support (equivalent to @samp{never}); if it is 0, use the +default color support for this terminal (equivalent to @samp{auto}); +otherwise use an appropriate standard mode for @var{num} colors. +Depending on your terminal's capabilities, Emacs might be able to turn +on a color mode for 8, 16, 88, or 256 as the value of @var{num}. If +there is no mode that supports @var{num} colors, Emacs acts as if +@var{num} were 0, i.e.@: it uses the terminal's default color support +mode. +@end table +If @var{mode} is omitted, it defaults to @var{ansi8}. +@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{-rv} option or with the X resource @samp{reverseVideo}. + + The @samp{-fg}, @samp{-bg}, and @samp{-rv} options function on +text-only terminals as well as on graphical displays. + +@node Window Size X +@appendixsec Options for Window Size and Position +@cindex geometry of Emacs window +@cindex position and size of Emacs frame +@cindex width and height of Emacs frame +@cindex specifying fullscreen for Emacs frame + + Here is a list of the command-line options for specifying size and +position of the initial Emacs frame: + +@table @samp +@item -g @var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} +@opindex -g +@itemx --geometry=@var{width}x@var{height}@r{[@{}+-@r{@}}@var{xoffset}@r{@{}+-@r{@}}@var{yoffset}@r{]]} +@opindex --geometry +@cindex geometry, command-line argument +Specify the size @var{width} and @var{height} (measured in character +columns and lines), and positions @var{xoffset} and @var{yoffset} +(measured in pixels). The @var{width} and @var{height} parameters +apply to all frames, whereas @var{xoffset} and @var{yoffset} only to +the initial frame. + +@item -fs +@opindex -fs +@itemx --fullscreen +@opindex --fullscreen +@cindex fullscreen, command-line argument +Specify that width and height shall be the size of the screen. + +@item -fh +@opindex -fh +@itemx --fullheight +@opindex --fullheight +@cindex fullheight, command-line argument +Specify that the height shall be the height of the screen. + +@item -fw +@opindex -fw +@itemx --fullwidth +@opindex --fullwidth +@cindex fullwidth, command-line argument +Specify that the width shall be the width of the screen. +@end table + + +@noindent +In the @samp{--geometry} option, @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 @command{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. (If you specify a proportional +font, Emacs uses its maximum bounds width as the width unit.) The +@var{xoffset} and @var{yoffset} are measured in pixels. + + 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. + + 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. But in the X +toolkit version, the menu bar is additional and does not count against +the specified height. The tool bar, if present, is also additional. + + Enabling or disabling the menu bar or tool bar alters the amount of +space available for ordinary text. Therefore, if Emacs starts up with +a tool bar (which is the default), and handles the geometry +specification assuming there is a tool bar, and then your +@file{~/.emacs} file disables the tool bar, you will end up with a +frame geometry different from what you asked for. To get the intended +size with no tool bar, use an X resource to specify ``no tool bar'' +(@pxref{Table of Resources}); then Emacs will already know there's no +tool bar when it processes the specified geometry. + + When using one of @samp{--fullscreen}, @samp{--fullwidth} or +@samp{--fullheight} there may be some space around the frame +anyway. That is because Emacs rounds the sizes so they are an +even number of character heights and widths. + + Some window managers have options that can make them ignore both +program-specified and user-specified positions (sawfish is one). +If these are set, Emacs fails to position the window correctly. + +@node Borders X +@appendixsec Internal and External Borders +@cindex borders (X Window System) + + An Emacs frame has an internal border and an external border. The +internal border is an extra strip of the background color around the +text portion of the frame. Emacs itself draws the internal border. +The external border is added by the window manager outside the frame; +depending on the window manager you use, it may contain various boxes +you can click on to move or iconify the window. + +@table @samp +@item -ib @var{width} +@opindex -ib +@itemx --internal-border=@var{width} +@opindex --internal-border +@cindex internal border width, command-line argument +Specify @var{width} as the width of the internal border (between the text +and the main border), in pixels. + +@item -bw @var{width} +@opindex -bw +@itemx --border-width=@var{width} +@opindex --border-width +@cindex main border width, command-line argument +Specify @var{width} as the width of the main border, in pixels. +@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 has the form @samp{@var{invocation-name}@@@var{machine}} +(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 -T @var{title} +@opindex -T +@itemx --title=@var{title} +@opindex --title +@cindex frame title, command-line argument +Specify @var{title} as the title for the initial Emacs frame. +@end table + + The @samp{--name} option (@pxref{Resources}) also specifies the title +for the initial Emacs frame. + +@node Icons X +@appendixsec Icons +@cindex icons (X Window System) + + Most window managers allow you 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 -nbi +@opindex -nbi +@itemx --no-bitmap-icon +@opindex --no-bitmap-icon +@cindex Emacs icon, a gnu +Do not use a picture of a gnu as the Emacs icon. + +@item -iconic +@opindex --iconic +@itemx --iconic +@cindex start iconified, command-line argument +Start Emacs in iconified state. +@end table + + By default Emacs uses an icon window containing a picture of the GNU gnu. +The @samp{-nbi} or @samp{--no-bitmap-icon} option tells Emacs to let 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 showing a frame right away. In this situation, the icon +is the only indication that Emacs has started; the text frame doesn't +appear until you deiconify it. + +@node Misc X +@appendixsec Other Display Options + +@table @samp +@item -hb +@opindex -hb +@itemx --horizontal-scroll-bars +@opindex --horizontal-scroll-bars +@c @cindex horizontal scroll bars, command-line argument +Enable horizontal scroll bars. Since horizontal scroll bars +are not yet implemented, this actually does nothing. + +@item -vb +@opindex -vb +@itemx --vertical-scroll-bars +@opindex --vertical-scroll-bars +@cindex vertical scroll bars, command-line argument +Enable vertical scroll bars. + +@item -lsp @var{pixels} +@opindex -lsp +@itemx --line-spacing=@var{pixels} +@opindex --line-spacing +@cindex line spacing, command-line argument +Specify @var{pixels} as additional space to put between lines, in pixels. + +@item -nbc +@opindex -nbc +@itemx --no-blinking-cursor +@opindex --no-blinking-cursor +@cindex blinking cursor disable, command-line argument +Disable the blinking cursor on graphical displays. + +@item -D +@opindex -D +@itemx --basic-display +@opindex --basic-display +Disable the menu-bar, the tool-bar, the scroll-bars, and tool tips, +and turn off the blinking cursor. This can be useful for making a +test case that simplifies debugging of display problems. +@end table + + The @samp{--xrm} option (@pxref{Resources}) specifies additional +X resource values. + +@ignore + arch-tag: fffecd9e-7329-4a51-a3cc-dd4a9889340e +@end ignore diff --git a/doc/emacs/commands.texi b/doc/emacs/commands.texi new file mode 100644 index 00000000000..d2daffe00bb --- /dev/null +++ b/doc/emacs/commands.texi @@ -0,0 +1,294 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, +@c 2003, 2004, 2005, 2006, 2007 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 the fundamental concepts of +@dfn{keys} and @dfn{commands}, whereby Emacs interprets your keyboard +and mouse input. +@end iftex + +@ifnottex +@raisesections +@end ifnottex + +@node User Input, Keys, Screen, Top +@section Kinds of User Input +@cindex input with the keyboard +@cindex keyboard input +@cindex character set (keyboard) +@cindex @acronym{ASCII} +@cindex C- +@cindex Control +@cindex control characters + + GNU Emacs is designed for use with keyboard commands because that is +the most efficient way to edit. You can do editing with the mouse, as +in other editors, and you can give commands with the menu bar and tool +bar, and scroll with the scroll bar. But if you keep on editing that +way, you won't get the benefits of Emacs. Therefore, this manual +documents primarily how to edit with the keyboard. You can force +yourself to practice using the keyboard by using the shell command +@samp{emacs -nw} to start Emacs, so that the mouse won't work. + + Emacs uses an extension of the @acronym{ASCII} character set for +keyboard input; it also accepts non-character input events including +function keys and mouse button actions. + + @acronym{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 @acronym{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 known as @key{SPC}, even though strictly speaking it is a +graphic character that is blank. + + Emacs extends the @acronym{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 @acronym{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. + + The Emacs character set has room for control variants of all +printing characters, and distinguishes @kbd{C-A} from @kbd{C-a}. +Graphical terminals make it possible to enter all these characters. +For example, @kbd{C--} (that's Control-Minus) and @kbd{C-5} are +meaningful Emacs commands on a graphical terminal. + + 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} (different from @kbd{M-a}, +but they are normally equivalent in Emacs), @kbd{M-@key{RET}}, and +@kbd{M-C-a}. That last means @kbd{a} with both the @key{CTRL} and +@key{META} modifiers. We usually write it as @kbd{C-M-a} rather than +@kbd{M-C-a}, for reasons of tradition. + +@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, you can type @kbd{Meta-a} +by holding down @key{META} and pressing @kbd{a}. The @key{META} key +works much like the @key{SHIFT} key. In fact, this key is more often +labeled @key{ALT} or @key{EDIT}, instead of @key{META}; on a Sun +keyboard, it may have a diamond on it. + + If there is no @key{META} key, you can still type Meta characters +using two-character sequences starting with @key{ESC}. Thus, you can +enter @kbd{M-a} by typing @kbd{@key{ESC} a}. You can enter +@kbd{C-M-a} by typing @kbd{@key{ESC} C-a}. Unlike @key{META}, which +modifies other characters, @key{ESC} is a separate character. You +don't hold down @key{ESC} while typing the next character; instead, +you press it and release it, then you enter the next character. +@key{ESC} is allowed on terminals with @key{META} keys, too, in case +you have formed a habit of using it. + + Emacs defines 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 graphical 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. + + If your keyboard lacks one of these modifier keys, you can enter it +using @kbd{C-x @@}: @kbd{C-x @@ h} adds the ``hyper'' flag to the next +character, @kbd{C-x @@ s} adds the ``super'' flag, and @kbd{C-x @@ a} +adds the ``alt'' flag. For instance, @kbd{C-x @@ h C-a} is a way to +enter @kbd{Hyper-Control-a}. (Unfortunately there is no way to add +two modifiers by using @kbd{C-x @@} twice for the same character, +because the first one goes to work on the @kbd{C-x}.) + + Keyboard input includes keyboard keys that are not characters at +all, such as function keys and arrow keys. Mouse buttons are also not +characters. However, 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 the full Lisp-level details. If you are not +doing Lisp programming, but simply want to redefine the meaning of +some characters or non-character events, see @ref{Customization}. + + @acronym{ASCII} terminals cannot really send anything to the computer except +@acronym{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 catch these special sequences +and convert them to function key events before any other part of Emacs +gets to see them. + +@cindex keys stolen by window manager +@cindex window manager, keys stolen by + On graphical displays, the window manager is likely to block the +character @kbd{Meta-@key{TAB}} before Emacs can see it. It may also +block @kbd{Meta-@key{SPC}}, @kbd{C-M-d} and @kbd{C-M-l}. If you have +these problems, we recommend that you customize your window manager to +turn off those commands, or put them on key combinations that Emacs +does not use. + +@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 is meaningful as a unit---a ``single command.'' Some +Emacs command sequences are invoked by just one character or one +event; for example, just @kbd{C-f} moves forward one character in the +buffer. 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-event +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-event key +sequences. There's no limit to the length of a key sequence, but in +practice people rarely use sequences longer than four events. + + You can't add input events onto a complete key. For example, the +two-event 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-o}. (@key{F1} and @key{F2} are +aliases for @kbd{C-h} and @kbd{C-x 6}.) This list is not cast in stone; +it describes the standard key bindings. If you customize Emacs, you can make +new prefix keys, or eliminate some of the standard ones (not +recommended for most users). @xref{Key Bindings}. + + If you 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 that too as a prefix). Conversely, if you remove the +prefix definition of @kbd{C-x 4}, then @kbd{C-x 4 f} and @kbd{C-x 4 +@var{anything}} are no longer keys. + + Typing the help character (@kbd{C-h} or @key{F1}) after a prefix key +displays a list of the commands starting with that prefix. There are +a few prefix keys after which @kbd{C-h} does not work---for historical +reasons, they define other meanings for @kbd{C-h} which are painful to +change. @key{F1} works after all prefix keys. + +@node Commands, Text Characters, Keys, Top +@section Keys and Commands + +@cindex binding +@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 how the +command does its work. In Emacs Lisp, a command is a Lisp function with +special options to read arguments and for interactive use. 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 here is simplified slightly.) + + The bindings between keys and commands are recorded in tables called +@dfn{keymaps}. @xref{Keymaps}. + + When we say that ``@kbd{C-n} moves down vertically one line'' we are +glossing over a subtle distinction that is irrelevant in ordinary use, +but vital for Emacs customization. The command @code{next-line} does +a vertical move downward. @kbd{C-n} has this effect @emph{because} it +is bound to @code{next-line}. If you rebind @kbd{C-n} to the command +@code{forward-word}, @kbd{C-n} will move forward one word instead. +Rebinding keys is an important method of customization. + + In the rest of this manual, we usually ignore this distinction to +keep things simple. We will often speak of keys like @kbd{C-n} as +commands, even though strictly speaking the key is bound to a command. +Usually 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 the command @code{next-line} moves +vertically down, and the key @kbd{C-n} is normally bound to it. + + Since we are discussing customization, we should 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 store a value. Most of the variables documented in this +manual are meant for customization: some command or other part of +Emacs examines the variable and behaves differently according to the +value that you set. You can ignore the information about variables +until you are interested in customizing them. Then read the basic +information on variables (@pxref{Variables}) and the information about +specific variables will make sense. + +@node Text Characters, Entering Emacs, Commands, Top +@section Character Set for Text +@cindex characters (in text) + + Text in Emacs buffers is a sequence of characters. In the simplest +case, these are @acronym{ASCII} characters, each stored in one 8-bit +byte. Both @acronym{ASCII} control characters (octal codes 000 +through 037, and 0177) and @acronym{ASCII} printing characters (codes +040 through 0176) are allowed. The other modifier flags used in +keyboard input, such as Meta, are not allowed in buffers. + + Non-@acronym{ASCII} printing characters can also appear in buffers, +when multibyte characters are enabled. They have character codes +starting at 256, octal 0400, and each one is represented as a sequence +of two or more bytes. @xref{International}. Single-byte characters +with codes 128 through 255 can also appear in multibyte buffers. +However, non-@acronym{ASCII} control characters cannot appear in a +buffer. + + Some @acronym{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}. + + If you disable multibyte characters, then you can use only one +alphabet of non-@acronym{ASCII} characters, which all fit in one byte. +They use octal codes 0200 through 0377. @xref{Unibyte Mode}. + +@ifnottex +@lowersections +@end ifnottex + +@ignore + arch-tag: 9be43eef-d1f4-4d03-a916-c741ea713a45 +@end ignore diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi new file mode 100644 index 00000000000..d496ab84b19 --- /dev/null +++ b/doc/emacs/custom.texi @@ -0,0 +1,2515 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 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 ways we have anticipated. +@iftex +See @cite{The Emacs Lisp Reference Manual} +@end iftex +@ifnottex +@xref{Top, Emacs Lisp, Emacs Lisp, elisp, The Emacs Lisp +Reference Manual}, +@end ifnottex +for how to make more far-reaching and open-ended changes. @xref{X +Resources}, for information on using X resources to customize Emacs. + + Customization that you do within Emacs normally affects only the +particular Emacs session that you do it in---it does not persist +between sessions unless you save the customization in a file such as +your init file (@file{.emacs}) that will affect future sessions. +(@xref{Init File}.) When you tell the customization buffer to save +customizations for future sessions, this actually works by editing +@file{.emacs} for you. + + Another means of customization is the keyboard macro, which is a +sequence of keystrokes to be replayed with a single command. +@xref{Keyboard Macros}, for full instruction how to record, manage, and +replay sequences of keys. + +@menu +* Minor Modes:: Each minor mode is one feature you can turn on + independently of any others. +* Easy Customization:: Convenient way to browse and change settings. +* Variables:: Many Emacs commands examine Emacs variables + to decide what to do; by setting variables, + you can control their functioning. +* Key Bindings:: The keymaps say what command each key runs. + By changing them, you can "redefine keys". +* 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 enabled; for example, @samp{Fill} in the mode line means +that Auto Fill mode is enabled. + + You should append @code{-mode} to the name of a minor mode to +produce the name of the command that turns the mode on or off. Thus, +the command to enable or disable Auto Fill mode is called +@code{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 minor mode 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. + + Some minor modes are global: while enabled, they affect everything +you do in the Emacs session, in all buffers. Other minor modes are +buffer-local; they apply only to the current buffer, so you can enable +the mode in certain buffers and not others. + + For most minor modes, the command name is also the name of a +variable. The variable's value is non-@code{nil} if the mode is +enabled and @code{nil} if it is disabled. Some minor-mode commands +work by just setting the variable. For example, the command +@code{abbrev-mode} works by setting the value of @code{abbrev-mode} as +a variable; it is this variable that directly turns Abbrev mode on and +off. You can directly set the variable's value instead of calling the +mode function. For other minor modes, you need to either set the +variable through the Customize interface or call the mode function to +correctly enable or disable the mode. To check which of these two +possibilities applies to a given minor mode, use @kbd{C-h v} to ask +for documentation on the variable name. + + For minor mode commands that work by just setting the minor mode +variable, that variable provides a good way for Lisp programs to turn +minor modes on and off; it is also useful in a file's local variables +list (@pxref{File Variables}). But please think twice before setting +minor modes with a local variables list, because most minor modes are +a matter of user preference---other users editing the same file might +not want the same minor modes you prefer. + + The most useful buffer-local minor modes include Abbrev mode, Auto +Fill mode, Auto Save mode, Font-Lock mode, Glasses 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 saves the buffer contents periodically to reduce the +amount of work you can lose in case of a 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 display that can show multiple fonts or +colors. @xref{Faces}. + +@ignore + 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. The +newer and more general feature of input methods more or less +supersedes ISO Accents mode. @xref{Unibyte Mode}. +@end ignore + + 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 + 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. + +@findex overwrite-mode +@kindex INSERT + The command @code{overwrite-mode} is an exception to the rule that +commands which toggle minor modes are normally not bound to keys: it is +bound to the @key{INSERT} function key. This is because many other +programs bind @key{INSERT} to similar functions. + +@findex binary-overwrite-mode + 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. +In Binary Overwrite mode, digits after @kbd{C-q} specify an +octal character code, as usual. + + Here are some useful minor modes that normally apply to all buffers +at once. Since Line Number mode and Transient Mark mode can be +enabled or disabled just by setting the value of the minor mode +variable, you @emph{can} set them differently for particular buffers, +by explicitly making the corresponding variable 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, and Column Number mode enables display of the +column number. @xref{Mode Line}. + + 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. @xref{Mark}. + +@node Easy Customization +@section Easy Customization Interface + +@cindex settings + Emacs has many @dfn{settings} which have values that you can specify +in order to customize various commands. Many are documented in this +manual. Most settings are @dfn{user options}---that is to say, Lisp +variables (@pxref{Variables})---so their names appear in the Variable +Index (@pxref{Variable Index}). The other settings are faces and +their attributes (@pxref{Faces}). + +@findex customize +@cindex customization buffer + You can browse interactively through settings and change them using +@kbd{M-x customize}. This command creates a @dfn{customization +buffer}, which offers commands to navigate through a logically +organized structure of the Emacs settings; you can also use it to edit +and set their values, and to save settings permanently in your +@file{~/.emacs} file (@pxref{Init File}). + + The appearance of the example buffers in this section is typically +different under a graphical display, since faces are then used to indicate +buttons, links and editable fields. + +@menu +* Groups: Customization Groups. How settings are classified in a structure. +* Browsing: Browsing Custom. Browsing and searching for settings. +* Changing a Variable:: How to edit an option's value and set the option. +* Saving Customizations:: Specifying the file for saving customizations. +* Face Customization:: How to edit the attributes of a face. +* Specific Customization:: Making a customization buffer for specific + variables, faces, or groups. +* Custom Themes:: How to define collections of customized options + that can be loaded and unloaded together. +@end menu + +@node Customization Groups +@subsection Customization Groups +@cindex customization groups + + For customization purposes, settings 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: + +@c we want the buffer example to all be on one page, but unfortunately +@c that's quite a bit of text, so force all space to the bottom. +@page +@smallexample +@group +/- Emacs group: ---------------------------------------------------\ + [State]: visible group members are all at standard values. + 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 group +@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 buttons (customization buffer) +@cindex links (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{buttons} and @dfn{links}, which do something when +you @dfn{invoke} them. To invoke a button or a link, either click on +it with @kbd{Mouse-1}, or move point to it and type @key{RET}. + + For example, the phrase @samp{[State]} that appears in +a second-level group is a button. It operates on the same +customization buffer. The phrase @samp{[Go to Group]} is a kind +of hypertext link to another group. Invoking it creates a new +customization buffer, which shows that group and its contents. + + The @code{Emacs} group includes a few settings, but mainly it +contains other groups, which contain more groups, which contain the +settings. By browsing the hierarchy of groups, you will eventually +find the feature you are interested in customizing. Then you can use +the customization buffer to set that feature's settings. You can also +go straight to a particular group by name, using the command @kbd{M-x +customize-group}. + +@node Browsing Custom +@subsection Browsing and Searching for Options and Faces +@findex customize-browse + + @kbd{M-x customize-browse} is another way to browse the available +settings. This command creates a special customization buffer which +shows only the names of groups and settings, and puts them in a +structure. + + In this buffer, you can show the contents of a group by invoking the +@samp{[+]} button. When the group contents are visible, this button +changes to @samp{[-]}; invoking that hides the group contents again. + + Each group or setting in this buffer has a link which says +@samp{[Group]}, @samp{[Option]} or @samp{[Face]}. Invoking this link +creates an ordinary customization buffer showing just that group and +its contents, just that user option, or just that face. This is the +way to change settings that you find with @kbd{M-x customize-browse}. + + If you can guess part of the name of the settings you are interested +in, @kbd{M-x customize-apropos} is another way to search for settings. +However, unlike @code{customize} and @code{customize-browse}, +@code{customize-apropos} can only find groups and settings that are +loaded in the current Emacs session. @xref{Specific Customization,, +Customizing Specific Items}. + +@node Changing a Variable +@subsection Changing a Variable + + Here is an example of what a variable (a user option) looks like in +the customization buffer: + +@smallexample +Kill Ring Max: [Hide Value] 60 + [State]: STANDARD. +Maximum length of kill ring before oldest elements are thrown away. +@end smallexample + + The text following @samp{[Hide Value]}, @samp{60} in this case, indicates +the current value of the variable. If you see @samp{[Show Value]} instead of +@samp{[Hide Value]}, it means that the value is hidden; the customization +buffer initially hides values that take up several lines. Invoke +@samp{[Show Value]} to show the value. + + The line after the variable name indicates the @dfn{customization +state} of the variable: in the example above, it says you have not +changed the option yet. The @samp{[State]} button at the beginning of +this line gives you a menu of various operations for customizing the +variable. + + The line after the @samp{[State]} line displays the beginning of the +variable's documentation string. If there are more lines of +documentation, this line ends with a @samp{[More]} button; invoke that +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. As you begin to alter the text, you will +see the @samp{[State]} line change to say that you have edited the +value: + +@smallexample +[State]: EDITED, shown value does not take effect until you set or @r{@dots{}} + save it. +@end smallexample + +@cindex user options, how to set +@cindex variables, how to set +@cindex settings, how to set + Editing the value does not actually set the variable. To do that, +you must @dfn{set} the variable. To do this, invoke the +@samp{[State]} button and choose @samp{Set for Current Session}. + + The state of the variable changes visibly when you set it: + +@smallexample +[State]: SET for current session only. +@end smallexample + + You don't have to worry about specifying a value that is not valid; +the @samp{Set for Current Session} operation checks for validity and +will not install an unacceptable value. + +@kindex M-TAB @r{(customization buffer)} +@findex widget-complete + While editing a 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. +(@kbd{@key{ESC} @key{TAB}} and @kbd{C-M-i} do the same thing.) + + Some variables have a small fixed set of possible legitimate values. +These variables don't let you edit the value textually. Instead, a +@samp{[Value Menu]} button appears before the value; invoke this +button to change the value. For a boolean ``on or off'' value, the +button says @samp{[Toggle]}, and it changes to the other value. +@samp{[Value Menu]} and @samp{[Toggle]} simply edit the buffer; the +changes take real effect when you use the @samp{Set for Current +Session} operation. + + Some variables have values with complex structure. For example, the +value of @code{file-coding-system-alist} is an association list. Here +is how it appears in the customization buffer: + +@smallexample +File Coding System Alist: [Hide Value] +[INS] [DEL] File regexp: \.elc\' + Choice: [Value Menu] Encoding/decoding pair: + Decoding: emacs-mule + Encoding: emacs-mule +[INS] [DEL] File regexp: \(\`\|/\)loaddefs.el\' + Choice: [Value Menu] Encoding/decoding pair: + Decoding: raw-text + Encoding: raw-text-unix +[INS] [DEL] File regexp: \.tar\' + Choice: [Value Menu] Encoding/decoding pair: + Decoding: no-conversion + Encoding: no-conversion +[INS] [DEL] File regexp: + Choice: [Value Menu] Encoding/decoding pair: + Decoding: undecided + Encoding: nil +[INS] + [State]: STANDARD. +Alist to decide a coding system to use for a file I/O @r{@dots{}} + operation. [Hide Rest] +The format is ((PATTERN . VAL) ...), +where PATTERN is a regular expression matching a file name, +@r{[@dots{}more lines of documentation@dots{}]} +@end smallexample + +@noindent +Each association in the list appears on four lines, with several +editable fields and/or buttons. You can edit the regexps and coding +systems using ordinary editing commands. You can also invoke +@samp{[Value Menu]} to switch to a different kind of value---for +instance, to specify a function instead of a pair of coding systems. + +To delete an association from the list, invoke the @samp{[DEL]} button +for that item. To add an association, invoke @samp{[INS]} at the +position where you want to add it. There is an @samp{[INS]} button +between each pair of associations, another at the beginning and another +at the end, so you can add a new association at any position in the +list. + +@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 button or editable +field; @kbd{S-@key{TAB}} (@code{widget-backward}) moves backward to +the previous button or editable field. + + Typing @key{RET} on an editable field also moves forward, just like +@key{TAB}. We set it up this way because people often type @key{RET} +when they are finished editing a field. To insert a newline within an +editable field, use @kbd{C-o} or @kbd{C-q C-j}. + +@cindex saving a setting +@cindex settings, how to save + Setting the variable changes its value in the current Emacs session; +@dfn{saving} the value changes it for future sessions as well. To +save the variable, invoke @samp{[State]} and select the @samp{Save for +Future Sessions} operation. This works by writing code so as to set +the variable again, each time you start Emacs (@pxref{Saving +Customizations}). + + You can also restore the variable to its standard value by invoking +@samp{[State]} and selecting the @samp{Erase Customization} operation. +There are actually four reset operations: + +@table @samp +@item Undo Edits +If you have made some modifications and not yet set the variable, +this restores the text in the customization buffer to match +the actual value. + +@item Reset to Saved +This restores the value of the variable to the last saved value, +and updates the text accordingly. + +@item Erase Customization +This sets the variable to its standard value, and updates the text +accordingly. This also eliminates any saved value for the variable, +so that you will get the standard value in future Emacs sessions. + +@item Set to Backup Value +This sets the variable to a previous value that was set in the +customization buffer in this session. If you customize a variable +and then reset it, which discards the customized value, +you can get the discarded value back again with this operation. +@end table + +@cindex comments on customized settings + Sometimes it is useful to record a comment about a specific +customization. Use the @samp{Add Comment} item from the +@samp{[State]} menu to create a field for entering the comment. The +comment you enter will be saved, and displayed again if you again view +the same variable in a customization buffer, even in another session. + + The state of a group indicates whether anything in that group has been +edited, set or saved. + + Near the top of the customization buffer there are two lines of buttons: + +@smallexample + [Set for Current Session] [Save for Future Sessions] + [Undo Edits] [Reset to Saved] [Erase Customization] [Finish] +@end smallexample + +@vindex custom-buffer-done-function +@noindent +Invoking @samp{[Finish]} either buries or kills this customization +buffer according to the setting of the option +@code{custom-buffer-done-kill}; the default is to bury the buffer. +Each of the other buttons performs an operation---set, save or +reset---on each of the settings in the buffer that could meaningfully +be set, saved or reset. They do not operate on settings whose values +are hidden, nor on subgroups which are hidden or not visible in the buffer. + +@node Saving Customizations +@subsection Saving Customizations + + Saving customizations from the customization buffer works by writing +code that future sessions will read, code to set up those +customizations again. + +@vindex custom-file + Normally this saves customizations in your init file, +@file{~/.emacs}. If you wish, you can save customizations in another +file instead. To make this work, your @file{~/.emacs} should set +@code{custom-file} to the name of that file. Then you should load the +file by calling @code{load}. For example: + +@example +(setq custom-file "~/.emacs-custom.el") +(load custom-file) +@end example + + You can use @code{custom-file} to specify different customization +files for different Emacs versions, like this: + +@example +(cond ((< emacs-major-version 21) + ;; @r{Emacs 20 customization.} + (setq custom-file "~/.custom-20.el")) + ((and (= emacs-major-version 21) (< emacs-minor-version 4)) + ;; @r{Emacs 21 customization, before version 21.4.} + (setq custom-file "~/.custom-21.el")) + ((< emacs-major-version 22) + ;; @r{Emacs version 21.4 or later.} + (setq custom-file "~/.custom-21.4.el")) + (t + ;; @r{Emacs version 22.1 or later.} + (setq custom-file "~/.custom-22.el"))) + +(load custom-file) +@end example + + If Emacs was invoked with the @option{-q} or @option{--no-init-file} +options (@pxref{Initial Options}), it will not let you save your +customizations in your @file{~/.emacs} init file. This is because +saving customizations from such a session would wipe out all the other +customizations you might have on your init file. + +@node Face Customization +@subsection Customizing Faces +@cindex customizing faces +@cindex bold font +@cindex italic font +@cindex fonts and faces + + In addition to variables, some customization groups also include +faces. When you show the contents of a group, both the variables 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) [Hide Face] + [State]: STANDARD. +Face used when the customize item has been changed. +Parent groups: [Custom Magic Faces] +Attributes: [ ] Font Family: * + [ ] Width: * + [ ] Height: * + [ ] Weight: * + [ ] Slant: * + [ ] Underline: * + [ ] Overline: * + [ ] Strike-through: * + [ ] Box around text: * + [ ] Inverse-video: * + [X] Foreground: white (sample) + [X] Background: blue (sample) + [ ] Stipple: * + [ ] Inherit: * +@end smallexample + + Each face attribute has its own line. The @samp{[@var{x}]} button +before the attribute name indicates whether the attribute is +@dfn{enabled}; @samp{[X]} means that it's enabled, and @samp{[ ]} +means that it's disabled. You can enable or disable the attribute by +clicking that button. When the attribute is enabled, you can change +the attribute value in the usual ways. + + For the colors, you can specify a color name (use @kbd{M-x +list-colors-display} for a list of them) or a hexadecimal color +specification of the form @samp{#@var{rr}@var{gg}@var{bb}}. +(@samp{#000000} is black, @samp{#ff0000} is red, @samp{#00ff00} is +green, @samp{#0000ff} is blue, and @samp{#ffffff} is white.) 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 +variables (@pxref{Changing a Variable}). + + 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{For All Kinds of Displays} 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 +@subsection Customizing Specific Items + + Instead of finding the setting you want to change by navigating the +structure of groups, here are other ways to specify the settings 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 user option variable, +@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 settings and groups that +match @var{regexp}. +@item M-x customize-changed @key{RET} @var{version} @key{RET} +Set up a customization buffer with all the settings and groups +whose meaning has changed since Emacs version @var{version}. +@item M-x customize-saved +Set up a customization buffer containing all settings that you +have saved with customization buffers. +@item M-x customize-unsaved +Set up a customization buffer containing all settings that you have +set but not saved. +@end table + +@findex customize-option + If you want to alter a particular user option with the customization +buffer, and you know its name, you can use the command @kbd{M-x +customize-option} and specify the user option (variable) name. This +sets up the customization buffer with just one user option---the one +that you asked for. Editing, setting and saving the value work as +described above, but only for the specified user option. Minibuffer +completion is handy if you only know part of the name. However, this +command can only see options that have been loaded in the current +Emacs session. + +@findex customize-face + Likewise, you can modify a specific face, chosen by name, using +@kbd{M-x customize-face}. By default it operates on the face used +on the character after point. + +@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 settings (user options and faces), and other groups, +all appear as well (even if not already loaded). However, the +subgroups' own contents are not included. + +@findex customize-apropos + For a more general way of controlling what to customize, you can use +@kbd{M-x customize-apropos}. You specify a regular expression as +argument; then all @emph{loaded} settings 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} +loaded groups and settings---which takes a long time to set up. + +@findex customize-changed + When you upgrade to a new Emacs version, you might want to consider +customizing new settings, and settings whose meanings or default +values have changed. To do this, use @kbd{M-x customize-changed} and +specify a previous Emacs version number using the minibuffer. It +creates a customization buffer which shows all the settings and groups +whose definitions have been changed since the specified version, +loading them if necessary. + +@findex customize-saved +@findex customize-unsaved + If you change settings and then decide the change was a mistake, you +can use two special commands to revisit your previous changes. Use +@kbd{M-x customize-saved} to look at the settings that you have saved. +Use @kbd{M-x customize-unsaved} to look at the settings that you +have set but not saved. + +@node Custom Themes +@subsection Customization Themes +@cindex custom themes + + @dfn{Custom themes} are collections of settings that can be enabled +or disabled as a unit. You can use Custom themes to switch quickly +and easily between various collections of settings, and to transfer +such collections from one computer to another. + +@findex customize-create-theme + To define a Custom theme, use @kbd{M-x customize-create-theme}, +which brings up a buffer named @samp{*New Custom Theme*}. At the top +of the buffer is an editable field where you can specify the name of +the theme. Click on the button labelled @samp{Insert Variable} to add +a variable to the theme, and click on @samp{Insert Face} to add a +face. You can edit these values in the @samp{*New Custom Theme*} +buffer like in an ordinary Customize buffer. To remove an option from +the theme, click on its @samp{State} button and select @samp{Delete}. + +@vindex custom-theme-directory + After adding the desired options, click on @samp{Save Theme} to save +the Custom theme. This writes the theme definition to a file +@file{@var{foo}-theme.el} (where @var{foo} is the theme name you +supplied), in the directory @file{~/.emacs.d/}. You can specify the +directory by setting @code{custom-theme-directory}. + + You can view and edit the settings of a previously-defined theme by +clicking on @samp{Visit Theme} and specifying the theme name. You can +also import the variables and faces that you have set using Customize +by visiting the ``special'' theme named @samp{user}. This theme, which +records all the options that you set in the ordinary customization +buffer, is always enabled, and always takes precedence over all other +enabled Custom themes. Additionally, the @samp{user} theme is +recorded with code in your @file{.emacs} file, rather than a +@file{user-theme.el} file. + +@vindex custom-enabled-themes + Once you have defined a Custom theme, you can use it by customizing +the variable @code{custom-enabled-themes}. This is a list of Custom +themes that are @dfn{enabled}, or put into effect. If you set +@code{custom-enabled-themes} using the Customize interface, the theme +definitions are automatically loaded from the theme files, if they +aren't already. If you save the value of @code{custom-enabled-themes} +for future Emacs sessions, those Custom themes will be enabled +whenever Emacs is started up. + + If two enabled themes specify different values for an option, the +theme occurring earlier in @code{custom-enabled-themes} takes effect. + +@findex load-theme +@findex enable-theme +@findex disable-theme + You can temporarily enable a Custom theme with @kbd{M-x +enable-theme}. This prompts for a theme name in the minibuffer, loads +the theme from the theme file if necessary, and enables the theme. +You can @dfn{disable} any enabled theme with the command @kbd{M-x +disable-theme}; this returns the options specified in the theme to +their original values. To re-enable the theme, type @kbd{M-x +enable-theme} again. If a theme file is changed during your Emacs +session, you can reload it by typing @kbd{M-x load-theme}. (This also +enables the theme.) + +@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. + + Emacs Lisp allows any variable (with a few exceptions) to have any +kind of value, but most variables that Emacs uses expect 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, but the +most interesting variables for a non-programmer user are those meant +for users to change---these are called @dfn{user options}. + + Each user option that you can set with the customization buffer is +in fact a Lisp variable. Emacs does not (usually) change the values +of these variables on its own; instead, you set the values in order to +control the behavior of certain Emacs commands. Use of the +customization buffer is explained above (@pxref{Easy Customization}); +here we describe other aspects of Emacs variables. + +@menu +* Examining:: Examining or setting one variable's value. +* 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 is a variable defined in `C source code'. +fill-column's value is 70 +Local in buffer custom.texi; global value is 70 +Automatically becomes buffer-local when set in any fashion. + +This variable is safe to use as a file local variable only if its value +satisfies the predicate `integerp'. + +Documentation: +*Column beyond which automatic line-wrapping should happen. +Interactively, you can set the buffer local value using C-x f. + +You can customize this variable. +@end smallexample + +@noindent +The line that says you can customize the variable indicates that this +variable is a user option. (The star also indicates this, but it is +an obsolete indicator that may eventually disappear.) @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 variable 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 (you can insert the old +value into the minibuffer for editing via @kbd{M-n}). 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. The only +way to alter the variable in future sessions is to put something in +the @file{~/.emacs} file to set it those sessions (@pxref{Init File}). + +@node Hooks +@subsection Hooks +@cindex hook +@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-functions} (@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. + +@findex add-hook + You can set a hook variable with @code{setq} like any other Lisp +variable, but the recommended way to add a hook function to a hook +(either normal or abnormal) is by calling @code{add-hook}. +@xref{Hooks,,, elisp, The Emacs Lisp Reference Manual}. + + 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 + '(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. + +@findex remove-hook + If you play with adding various different versions of a hook +function by calling @code{add-hook} over and over, remember that all +the versions you added will remain in the hook variable together. You +can clear out individual functions by calling @code{remove-hook}, or +do @code{(setq @var{hook-variable} nil)} to remove everything. + +@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. Changing its value subsequently in +this buffer will not affect others, and changes in its global value +will not affect this buffer. + +@findex make-variable-buffer-local +@cindex per-buffer variables + @kbd{M-x make-variable-buffer-local} marks a variable so it will +become local automatically whenever 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. Many variables in Emacs +are normally per-buffer; the variable's document string tells you when +this is so. A per-buffer variable's global value is normally never +effective in any buffer, but it still has a meaning: it is the initial +value of the variable for each new buffer. + + 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 many minor modes, the controlling variable +is per buffer, and thus always buffer-local. Otherwise, you can make +it local in a specific buffer like any other variable. + + 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} makes a specified variable 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. + +@menu +* Specifying File Variables:: Specifying file local variables. +* Safe File Variables:: Making sure file local variables are safe. +@end menu + +@node Specifying File Variables +@subsubsection Specifying File Variables + + There are two ways to specify file 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}. @w{@samp{unibyte: t}} specifies unibyte loading for a +particular Lisp file. @xref{Enabling Multibyte}. + + The @code{eval} pseudo-variable, described below, can be specified in +the first line as well. + +@cindex shell scripts, and local file variables + In shell scripts, the first line is used to identify the script +interpreter, so you cannot put any local variables there. To +accommodate this, Emacs looks for local variable specifications in the +@emph{second} line when the first line specifies an interpreter. + + 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 + + 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. + + If you write a multi-line string value, you should put the prefix +and suffix on each line, even lines that start or end within the +string. They will be stripped off for processing the list. If you +want to split a long string across multiple lines of the file, you can +use backslash-newline, which is ignored in Lisp string constants. +Here's an example of doing this: + +@example +# Local Variables: +# compile-command: "cc foo.c -Dfoo=bar -Dhack=whatever \ +# -Dmumble=blaah" +# End: +@end example + + Some ``variable names'' have special meanings in a local variables +list. Specifying the ``variable'' @code{mode} really sets the major +mode, while any value specified for the ``variable'' @code{eval} is +simply evaluated as an expression (its value is ignored). A value for +@code{coding} specifies the coding system for character code +conversion of this file, and a value of @code{t} for @code{unibyte} +says to visit the file in a unibyte buffer. These four ``variables'' +are not really variables; setting them in any other context has no +special meaning. + + @emph{If @code{mode} is used to set a major mode, it should be the +first ``variable'' in the list.} Otherwise, the entries that precede +it will usually be ignored, since most modes kill all local variables +as part of their initialization. + + You can use the @code{mode} ``variable'' to set minor modes as well +as the 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 at all, 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}. + +@node Safe File Variables +@subsubsection Safety of File Variables + + File-local variables can be dangerous; when you visit someone else's +file, there's no telling what its local variables list could do to +your Emacs. Improper values of the @code{eval} ``variable,'' and +other variables such as @code{load-path}, could execute Lisp code you +didn't intend to run. + + Therefore, whenever Emacs encounters file local variable values that +are not known to be safe, it displays the file's entire local +variables list, and asks you for confirmation before setting them. +You can type @kbd{y} or @key{SPC} to put the local variables list into +effect, or @kbd{n} to ignore it. When Emacs is run in batch mode +(@pxref{Initial Options}), it can't really ask you, so it assumes the +answer @kbd{n}. + + Emacs normally recognizes certain variables/value pairs as safe. +For instance, it is safe to give @code{comment-column} or +@code{fill-column} any integer value. If a file specifies only +known-safe variable/value pairs, Emacs does not ask for confirmation +before setting them. Otherwise, you can tell Emacs to record all the +variable/value pairs in this file as safe, by typing @kbd{!} at the +confirmation prompt. When Emacs encounters these variable/value pairs +subsequently, in the same file or others, it will assume they are +safe. + +@vindex safe-local-variable-values +@cindex risky variable + Some variables, such as @code{load-path}, are considered +particularly @dfn{risky}: there is seldom any reason to specify them +as local variables, and changing them can be dangerous. If a file +contains only risky local variables, Emacs neither offers nor accepts +@kbd{!} as input at the confirmation prompt. If some of the local +variables in a file are risky, and some are only potentially unsafe, you +can enter @kbd{!} at the prompt. It applies all the variables, but only +marks the non-risky ones as safe for the future. If you really want to +record safe values for risky variables, do it directly by customizing +@samp{safe-local-variable-values} (@pxref{Easy Customization}). + +@vindex enable-local-variables + The variable @code{enable-local-variables} allows you to change the +way Emacs processes local variables. Its default value is @code{t}, +which specifies the behavior described above. If it is @code{nil}, +Emacs simply ignores all file local variables. @code{:safe} means use +only the safe values and ignore the rest. Any other value says to +query you about each file that has local variables, without trying to +determine whether the values are known to be safe. + +@vindex enable-local-eval + The variable @code{enable-local-eval} controls whether Emacs +processes @code{eval} variables. The three possibilities for the +variable'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 processing @code{eval} variables. + +@vindex safe-local-eval-forms + But there is an exception. The @code{safe-local-eval-forms} is a +customizable list of eval forms which are safe. Emacs does not ask +for confirmation when it finds these forms for the @code{eval} +variable. + +@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. +* 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 text 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 +key sequences are inconvenient to use. + + As a user, you can redefine any key; but it is usually best to stick +to key sequences that consist of @kbd{C-c} followed by a letter (upper +or lower case). 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{Control-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. + + 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 the results in ordinary +circumstances. + +@cindex rebinding major mode keys + Most major modes construct their keymaps when the mode is used for +the first time in a session. If you wish to change one of these +keymaps, you must use the major mode's @dfn{mode hook} +(@pxref{Hooks}). + +@findex define-key + 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 + +@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 +@vindex minibuffer-local-filename-completion-map +@vindex minibuffer-local-must-match-filename-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. +@item +Finally, @code{minibuffer-local-filename-completion-map} and +@code{minibuffer-local-must-match-filename-map} are like the two +previous ones, but they are specifically for file name completion. +They do not bind @key{SPC}. +@end itemize + +@node Rebinding +@subsection Changing Key Bindings Interactively +@cindex key rebinding, this session +@cindex redefining 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; it enters the minibuffer immediately to +read @var{cmd}. But if you type @kbd{C-x}, since that's a prefix, it +reads another character; if that is @kbd{4}, another prefix character, +it reads one more character, 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 in a +fresh Emacs 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 + + 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. (@xref{Init File}.) + + The simplest method for doing this works for @acronym{ASCII} characters and +Meta-modified @acronym{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}. (@samp{\C-} is string syntax for a control character.) 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 the key sequence @kbd{C-x M-l}: + +@example +(global-set-key "\C-x\M-l" 'make-symbolic-link) +@end example + + To put @key{TAB}, @key{RET}, @key{ESC}, or @key{DEL} in the +string, you can use the Emacs Lisp escape sequences, @samp{\t}, +@samp{\r}, @samp{\e}, and @samp{\d}. Here is an example which binds +@kbd{C-x @key{TAB}}: + +@example +(global-set-key "\C-x\t" 'indent-rigidly) +@end example + + These examples show how to write some other special @acronym{ASCII} characters +in strings for key bindings: + +@example +(global-set-key "\r" 'newline) ;; @key{RET} +(global-set-key "\d" 'delete-backward-char) ;; @key{DEL} +(global-set-key "\C-x\e\e" 'repeat-complex-command) ;; @key{ESC} +@end example + + When the key sequence includes function keys or mouse button events, +or non-@acronym{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 not in @acronym{ASCII}), @kbd{C-M-=} (not in @acronym{ASCII} because @kbd{C-=} +is not), @kbd{H-a} (a Hyper character; @acronym{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 [?\M-\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 six examples above to use vectors: + +@example +(global-set-key [?\C-z] 'shell) +(global-set-key [?\C-x ?l] 'make-symbolic-link) +(global-set-key [?\C-x ?\t] 'indent-rigidly) +(global-set-key [?\r] 'newline) +(global-set-key [?\d] 'delete-backward-char) +(global-set-key [?\C-x ?\e ?\e] 'repeat-complex-command) +@end example + +@noindent +As you see, you represent a multi-character key sequence with a vector +by listing all of the characters, in order, within the square brackets +that delimit the vector. + + Language and coding systems can cause problems with key bindings +for non-@acronym{ASCII} characters. @xref{Init Non-ASCII}. + +@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) 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 +@acronym{ASCII} characters) must be a vector rather than a string. +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 + +@cindex keypad + Many keyboards have a ``numeric keypad'' on the right hand side. +The numeric keys in the keypad double up as cursor motion keys, +toggled by a key labeled @samp{Num Lock}. By default, Emacs +translates these keys to the corresponding keys in the main keyboard. +For example, when @samp{Num Lock} is on, the key labeled @samp{8} on +the numeric keypad produces @code{kp-8}, which is translated to +@kbd{8}; when @samp{Num Lock} is off, the same key produces +@code{kp-up}, which is translated to @key{UP}. If you rebind a key +such as @kbd{8} or @key{UP}, it affects the equivalent keypad key too. +However, if you rebind a @samp{kp-} key directly, that won't affect +its non-keypad equivalent. + + Emacs provides a convenient method for binding the numeric keypad +keys, using the variables @code{keypad-setup}, +@code{keypad-numlock-setup}, @code{keypad-shifted-setup}, and +@code{keypad-numlock-shifted-setup}. These can be found in the +@samp{keyboard} customization group (@pxref{Easy Customization}). You +can rebind the keys to perform other tasks, such as issuing numeric +prefix arguments. + +@node Named ASCII Chars +@subsection Named @acronym{ASCII} Control Characters + + @key{TAB}, @key{RET}, @key{BS}, @key{LFD}, @key{ESC} and @key{DEL} +started out as names for certain @acronym{ASCII} control characters, +used so often that they have special keys of their own. For instance, +@key{TAB} was another name for @kbd{C-i}. Later, users found it +convenient to distinguish in Emacs between these keys and the ``same'' +control characters typed with the @key{CTRL} key. Therefore, on most +modern terminals, they are no longer the same, and @key{TAB} is +distinguishable from @kbd{C-i}. + + Emacs can distinguish these two kinds of input if the keyboard does. +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 @acronym{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 @acronym{ASCII} character @key{TAB} +(octal code 011). If you do want to distinguish, make one binding for +this @acronym{ASCII} character, and another for the ``function key'' @code{tab}. + + With an ordinary @acronym{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 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 +if you know Emacs Lisp you can distinguish if you really want to +(@pxref{Accessing Events,,, elisp, The Emacs Lisp Reference Manual}). +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 much time can +elapse between clicks and still allow them to be grouped as a multiple +click. Its value is in units of 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 default is 500. + +@vindex double-click-fuzz + The variable @code{double-click-fuzz} specifies how much the mouse +can move between clicks and still allow them to be grouped as a multiple +click. Its value is in units of pixels on windowed displays and in +units of 1/8 of a character cell on text-mode terminals; the default is +3. + + 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.) +@item menu-bar +The mouse was in the menu bar. +@item header-line +The mouse was in a header line. +@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 means that invoking it interactively asks for +confirmation from the user. The purpose of disabling a command is to +prevent users from executing it by accident; we do this for commands +that might be confusing to the uninitiated. + + Attempting 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 +must then answer another question---whether to do this permanently, or +just for the current session. (Enabling permanently works by +automatically editing your @file{.emacs} file.) You can also type +@kbd{!} to enable @emph{all} commands, for the current session only. + + 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 displayed 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}. + + If Emacs was invoked with the @option{-q} or @option{--no-init-file} +options (@pxref{Initial Options}), it will not edit your +@file{~/.emacs} init file. Doing so could lose information +because Emacs has not read your 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}. However, disabling a command has no effect on calling it +as a function from Lisp programs. + +@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. It does this by assigning each character to +one of fifteen-odd @dfn{syntax classes}. In some cases it specifies +some additional information also. + + Each major mode has its own syntax table (though related major modes +sometimes share one syntax table), which it installs in each buffer +that uses the mode. The syntax table installed in the current buffer +is the one that all commands use, so we call it ``the'' syntax table. + +@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 the string you would have to give to +@code{modify-syntax-entry} to set up that character's current syntax, +starting with the character which designates its syntax class, plus +some English text to explain its meaning. + + A syntax table is actually a Lisp object, a char-table, whose +elements are cons cells. 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 (@pxref{Find Init}). +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{Initial +Options}). + + You can also use @file{~/.emacs.d/init.el} as the init file. Emacs +tries this if it cannot find @file{~/.emacs} or @file{~/.emacs.el}. + +@cindex @file{default.el}, the default init file + 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. + +@cindex site init file +@cindex @file{site-start.el}, the site startup file + Your site may also have a @dfn{site startup file}; this is named +@file{site-start.el}, if it exists. Like @file{default.el}, Emacs +finds this file via the standard search path for Lisp libraries. +Emacs loads this library before it loads your init file. To inhibit +loading of this library, use the option @samp{--no-site-file}. +@xref{Initial Options}. We recommend against using +@file{site-start.el} for changes that some users may not like. It is +better to put them in @file{default.el}, so that users can more easily +override them. + + You can place @file{default.el} and @file{site-start.el} in any of +the directories which Emacs searches for Lisp libraries. The variable +@code{load-path} (@pxref{Lisp Libraries}) specifies these directories. +Many sites put these files in the @file{site-lisp} subdirectory of the +Emacs installation directory, typically +@file{/usr/local/share/emacs/site-lisp}. + + 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}. +@ifnottex +@xref{Top, Emacs Lisp, Emacs Lisp, elisp, the Emacs Lisp Reference +Manual}. +@end ifnottex + +@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. +* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an 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. + + You can set any Lisp variable with @code{setq}, but with certain +variables @code{setq} won't do what you probably want in the +@file{.emacs} file. Some variables automatically become buffer-local +when set with @code{setq}; what you want in @file{.emacs} is to set +the default value, using @code{setq-default}. Some customizable minor +mode variables do special things to enable the mode when you set them +with Customize, but ordinary @code{setq} won't do that; to enable the +mode in your @file{.emacs} file, call the minor mode command. The +following section has examples of both of these methods. + + 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 @acronym{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 + +@xref{Init Non-ASCII}, for information about including +non-@acronym{ASCII} in your init file. + +@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. + +@xref{Init Non-ASCII}, for information about binding commands to +keys which send non-@acronym{ASCII} characters. + +@item True: +@code{t} stands for `true'. + +@item False: +@code{nil} stands for `false'. + +@item Other Lisp objects: +Write a single-quote (@code{'}) 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 "rumsfeld@@torture.gov") +@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 off Line Number mode, a global minor mode. + +@example +(line-number-mode 0) +@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 +@cindex loading Lisp libraries automatically +@cindex autoload Lisp libraries +Tell Emacs to find the definition for the function @code{myfunction} +by loading a Lisp library named @file{mypackage} (i.e.@: a file +@file{mypackage.elc} or @file{mypackage.el}): + +@example +(autoload 'myfunction "mypackage" "Do what I say." t) +@end example + +@noindent +Here the string @code{"Do what I say."} is the function's +documentation string. You specify it in the @code{autoload} +definition so it will be available for help commands even when the +package is not loaded. The last argument, @code{t}, indicates that +this function is interactive; that is, it can be invoked interactively +by typing @kbd{M-x myfunction @key{RET}} or by binding it to a key. +If the function is not interactive, omit the @code{t} or use +@code{nil}. + +@item +Rebind the key @kbd{C-x l} to run the function @code{make-symbolic-link} +(@pxref{Init Rebinding}). + +@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. + +@findex substitute-key-definition +@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 + +@item +Adjusting the configuration to various platforms and Emacs versions. + +Users typically want Emacs to behave the same on all systems, so the +same init file is right for all platforms. However, sometimes it +happens that a function you use for customizing Emacs is not available +on some platforms or in older Emacs versions. To deal with that +situation, put the customization inside a conditional that tests whether +the function or facility is available, like this: + +@example +(if (fboundp 'blink-cursor-mode) + (blink-cursor-mode 0)) + +(if (boundp 'coding-category-utf-8) + (set-coding-priority '(coding-category-utf-8))) +@end example + +@noindent +You can also simply disregard the errors that occur if the +function is not defined. + +@example +(condition case () + (set-face-background 'region "grey75") + (error nil)) +@end example + +A @code{setq} on a variable which does not exist is generally +harmless, so those do not need a conditional. +@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 @env{HOME} +(@pxref{General Variables, HOME}) to find @file{.emacs}; that's what +@samp{~} means in a file name. If @file{.emacs} is not found inside +@file{~/} (nor @file{.emacs.el}), Emacs looks for +@file{~/.emacs.d/init.el} (which, like @file{~/.emacs.el}, can be +byte-compiled). + + However, if you run Emacs from a shell started by @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 your user name from the environment variables @env{LOGNAME} and +@env{USER}; if neither of those exists, it uses effective user-ID. +If that user name matches the real user-ID, then Emacs uses @env{HOME}; +otherwise, it looks up the home directory corresponding to that user +name in the system's data base of users. +@c LocalWords: backtab + +@node Init Non-ASCII +@subsection Non-@acronym{ASCII} Characters in Init Files +@cindex international characters in @file{.emacs} +@cindex non-@acronym{ASCII} characters in @file{.emacs} +@cindex non-@acronym{ASCII} keys, binding +@cindex rebinding non-@acronym{ASCII} keys + + Language and coding systems may cause problems if your init file +contains non-@acronym{ASCII} characters, such as accented letters, in +strings or key bindings. + + If you want to use non-@acronym{ASCII} characters in your init file, +you should put a @w{@samp{-*-coding: @var{coding-system}-*-}} tag on +the first line of the init file, and specify a coding system that +supports the character(s) in question. @xref{Recognize Coding}. This +is because the defaults for decoding non-@acronym{ASCII} text might +not yet be set up by the time Emacs reads those parts of your init +file which use such strings, possibly leading Emacs to decode those +strings incorrectly. You should then avoid adding Emacs Lisp code +that modifies the coding system in other ways, such as calls to +@code{set-language-environment}. + + To bind non-@acronym{ASCII} keys, you must use a vector (@pxref{Init +Rebinding}). The string syntax cannot be used, since the +non-@acronym{ASCII} characters will be interpreted as meta keys. For +instance: + +@example +(global-set-key [?@var{char}] 'some-function) +@end example + +@noindent +Type @kbd{C-q}, followed by the key you want to bind, to insert @var{char}. + + @strong{Warning:} if you change the keyboard encoding, or change +between multibyte and unibyte mode, or anything that would alter which +code @kbd{C-q} would insert for that character, this keybinding may +stop working. It is therefore advisable to use one and only one +coding system, for your init file as well as the files you edit. For +example, don't mix the @samp{latin-1} and @samp{latin-9} coding +systems. + +@ignore + arch-tag: c68abddb-4410-4fb5-925f-63394e971d93 +@end ignore diff --git a/doc/emacs/dired-xtra.texi b/doc/emacs/dired-xtra.texi new file mode 100644 index 00000000000..e8fdf8ab468 --- /dev/null +++ b/doc/emacs/dired-xtra.texi @@ -0,0 +1,49 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@c +@c This file is included either in emacs-xtra.texi (when producing the +@c printed version) or in the main Emacs manual (for the on-line version). +@node Subdir Switches +@section Subdirectory Switches in Dired + +You can insert subdirectories with specified @code{ls} switches in +Dired buffers, using @kbd{C-u i}. You can change the @code{ls} +switches of an already inserted subdirectory using @kbd{C-u l}. + +In Emacs versions 22.1 and later, Dired remembers the switches, so +that reverting the buffer will not change them back to the main +directory's switches. Deleting a subdirectory forgets about its +switches. + +Using @code{dired-undo} (usually bound to @kbd{C-_} and @kbd{C-x u}) +to reinsert or delete subdirectories, that were inserted with explicit +switches, can bypass Dired's machinery for remembering (or forgetting) +switches. Deleting a subdirectory using @code{dired-undo} does not +forget its switches. When later reinserted using @kbd{i}, it will be +reinserted using its old switches. Using @code{dired-undo} to +reinsert a subdirectory that was deleted using the regular +Dired commands (not @code{dired-undo}) will originally insert it with +its old switches. However, reverting the buffer will relist it using +the buffer's default switches. If any of this yields problems, you +can easily correct the situation using @kbd{C-u i} or @kbd{C-u l}. + +Dired does not remember the @code{R} switch. Inserting a subdirectory +with switches that include the @code{R} switch is equivalent with +inserting each of its subdirectories using all remaining switches. +For instance, updating or killing a subdirectory that was inserted +with the @code{R} switch will not update or kill its subdirectories. + +The buffer's default switches do not affect subdirectories that were +inserted using explicitly specified switches. In particular, +commands such as @kbd{s}, that change the buffer's switches do not +affect such subdirectories. (They do affect subdirectories without +explicitly assigned switches, however.) + +You can make Dired forget about all subdirectory switches and relist +all subdirectories with the buffer's default switches using +@kbd{M-x dired-reset-subdir-switches}. This also reverts the Dired buffer. + +@ignore + arch-tag: e3865701-9179-4ffb-bc34-d321111c688d +@end ignore diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi new file mode 100644 index 00000000000..3dda3f588eb --- /dev/null +++ b/doc/emacs/dired.texi @@ -0,0 +1,1317 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 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 +@cindex file management + + 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. + + 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 redefined 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. You first mark certain files in order to operate +on all of them with on command. + + The Dired-X package provides various extra features for Dired mode. +@xref{Top, Dired-X,,dired-x, Dired Extra Version 2 User's Manual}. + +@menu +* Enter: Dired Enter. How to invoke Dired. +* Navigation: Dired Navigation. Special motion 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. +@ifnottex +* Subdir Switches:: Subdirectory switches in Dired. +@end ifnottex +* 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. +* Wdired:: Operating on files by editing the Dired buffer. +* Image-Dired:: Viewing image thumbnails in Dired +* Misc: Misc Dired Features. Various other features. +@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 the files to list. @kbd{C-x C-f} given a +directory name also invokes Dired. Where @code{dired} differs from +@code{list-directory} is that it puts 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 the 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. No matter +how they are specified, the @code{ls} switches can include short +options (that is, single characters) requiring no arguments, and long +options (starting with @samp{--}) whose arguments are specified with +@samp{=}. + + On MS-Windows and MS-DOS systems, Emacs @emph{emulates} @code{ls}; +see @ref{ls in Lisp}, for options and peculiarities of that emulation. + + +@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 Navigation +@section Navigation in the Dired Buffer + +@kindex C-n @r{(Dired)} +@kindex C-p @r{(Dired)} + All the usual Emacs cursor motion commands are available in Dired +buffers. 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. + +@findex dired-goto-file +@kindex j @r{(Dired)} + @kbd{j} (@code{dired-goto-file}) moves point to the line that +describes a specified file or directory. + + Some additional navigation commands are available when the Dired +buffer includes several directories. @xref{Subdirectory Motion}. + +@node Dired Deletion +@section Deleting Files with Dired +@cindex flagging files (in Dired) +@cindex deleting files (in Dired) + + One of the most frequent uses of Dired is to first @dfn{flag} files for +deletion, then delete the files that were 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 reason for flagging files for deletion, rather than deleting +files immediately, is to reduce the danger of deleting a file +accidentally. Until you direct Dired to delete 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-do-flagged-delete +@cindex expunging (Dired) + To delete the flagged files, type @kbd{x} +(@code{dired-do-flagged-delete}). (This is also known as +@dfn{expunging}.) 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 Dired buffer, with +somewhat fewer lines, 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. + +@cindex recursive deletion +@vindex dired-recursive-deletes + You can delete empty directories just like other files, but normally +Dired cannot delete directories that are nonempty. If the variable +@code{dired-recursive-deletes} is non-@code{nil}, then Dired can +delete nonempty directories including all their contents. That can +be somewhat risky. + +@node Flagging Many Files +@section Flagging Many Files at Once +@cindex flagging many files for deletion (in Dired) + +@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 which suggest +you could easily create those 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 +@cindex deleting some backup files + @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{}, @samp{.bak} files, and the @samp{.orig} and +@samp{.rej} files produced by @code{patch}. + +@kindex # @r{(Dired)} +@findex dired-flag-auto-save-files +@cindex deleting auto-save files + @kbd{#} (@code{dired-flag-auto-save-files}) flags for deletion all +files whose names look like auto-save files---that is, files whose +names begin and end with @samp{#}. @xref{Auto Save}. + +@kindex ~ @r{(Dired)} +@findex dired-flag-backup-files + @kbd{~} (@code{dired-flag-backup-files}) flags for deletion all +files whose names say they are backup files---that is, files whose +names end in @samp{~}. @xref{Backup}. + +@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 certain +subdirectories from marking by hiding them while you use @kbd{% d}. +@xref{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} +@itemx e +@kindex RET @r{(Dired)} +@kindex e @r{(Dired)} +Equivalent to @kbd{f}. + +@ignore @c This command seems too risky to document at all. +@item a +@kindex a @r{(Dired)} +@findex dired-find-alternate-file +Like @kbd{f}, but replaces the contents of the Dired buffer with +that of an alternate file or directory (@code{dired-find-alternate-file}). +@end ignore + +@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-1 +@itemx 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 with @code{view-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, Miscellaneous File Operations}. + +@item ^ +@kindex ^ @r{(Dired)} +@findex dired-up-directory +Visit the parent directory of the current directory +(@code{dired-up-directory}). This is equivalent to moving to the line +for @file{..} and typing @kbd{f} there. +@end table + +@node Marks vs Flags +@section Dired Marks vs. Flags + +@cindex marking many files (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 use the files marked with @samp{*}. The +only command that operates on flagged files is @kbd{x}, which expunges +them. + + Here are some commands for marking with @samp{*}, for unmarking, and +for 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 +@cindex marking executable files (in Dired) +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 +@cindex marking symbolic links (in Dired) +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 +@cindex marking subdirectories (in Dired) +Mark with @samp{*} all files which are 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 +@cindex unmarking files (in Dired) +Move point to previous line and remove any mark on that line +(@code{dired-unmark-backward}). + +@item * ! +@itemx U +@kindex * ! @r{(Dired)} +@kindex U @r{(Dired)} +@findex dired-unmark-all-marks +Remove all marks from all the files in this Dired buffer +(@code{dired-unmark-all-marks}). + +@item * ? @var{markchar} +@itemx M-@key{DEL} +@kindex * ? @r{(Dired)} +@kindex M-DEL @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. See the description +of the @kbd{* c} command below, which lets you replace one mark +character with another. + +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 +@itemx M-@} +@findex dired-next-marked-file +@kindex * C-n @r{(Dired)} +@kindex M-@} @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 +@itemx M-@{ +@findex dired-prev-marked-file +@kindex * C-p @r{(Dired)} +@kindex M-@{ @r{(Dired)} +Move up to the previous marked file (@code{dired-prev-marked-file}) + +@item t +@itemx * t +@kindex t @r{(Dired)} +@kindex * t @r{(Dired)} +@findex dired-toggle-marks +@cindex toggling marks (in Dired) +Toggle all marks (@code{dired-toggle-marks}): 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-markchar} @var{new-markchar} +@kindex * c @r{(Dired)} +@findex dired-change-marks +Replace all marks that use the character @var{old-markchar} with marks +that use the character @var{new-markchar} (@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-markchar} +is a space (@samp{ }), then the command operates on all unmarked files; +if @var{new-markchar} 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 were already 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}. + +Only the non-directory part of the file name is used in matching. Use +@samp{^} and @samp{$} to anchor matches. You can exclude +subdirectories by temporarily hiding them (@pxref{Hiding +Subdirectories}). + +@item % g @var{regexp} @key{RET} +@findex dired-mark-files-containing-regexp +@kindex % g @r{(Dired)} +@cindex finding files containing regexp matches (in 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-x u +@itemx C-_ +@itemx C-/ +@kindex C-_ @r{(Dired)} +@findex dired-undo +Undo changes in the Dired buffer, such as adding or removing +marks (@code{dired-undo}). @emph{This command does not revert the +actual file operations, nor recover lost files!} It just undoes +changes in the buffer itself. + +In some cases, using this after commands that operate on files can +cause trouble. For example, after renaming one or more files, +@code{dired-undo} restores the original names in the Dired buffer, +which gets the Dired buffer out of sync with the actual contents of +the directory. +@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 let you specify the +files to manipulate in these ways: + +@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 + +@noindent +Certain other Dired commands, such as @kbd{!} and the @samp{%} +commands, use the same conventions to decide which files to work on. + +@vindex dired-dwim-target +@cindex two directories (in Dired) + Commands which ask for a destination directory, such as those which +copy and rename files or create links for them, try to guess the default +target directory for the operation. Normally, they suggest the Dired +buffer's default directory, but if the variable @code{dired-dwim-target} +is non-@code{nil}, and if there is another Dired buffer displayed in the +next window, that other buffer's directory is suggested instead. + + Here are the file-manipulating Dired commands that operate on files. + +@table @kbd +@findex dired-do-copy +@kindex C @r{(Dired)} +@cindex copying files (in 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. This is like the shell command @code{cp}. + +@vindex dired-copy-preserve-time +If @code{dired-copy-preserve-time} is non-@code{nil}, then copying +with this command preserves the modification time of the old file in +the copy, like @samp{cp -p}. + +@vindex dired-recursive-copies +@cindex recursive copying +The variable @code{dired-recursive-copies} controls whether to copy +directories recursively (like @samp{cp -r}). The default is +@code{nil}, which means that directories cannot be copied. + +@item D +@findex dired-do-delete +@kindex D @r{(Dired)} +Delete the specified files (@code{dired-do-delete}). This is like the +shell command @code{rm}. + +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-do-flagged-delete}) deletes all @dfn{flagged} files. + +@findex dired-do-rename +@kindex R @r{(Dired)} +@cindex renaming files (in Dired) +@cindex moving files (in Dired) +@item R @var{new} @key{RET} +Rename the specified files (@code{dired-do-rename}). If you rename a +single file, the argument @var{new} is the new name of the file. If +you rename several files, the argument @var{new} is the directory into +which to move the files (this is like the shell command @code{mv}). + +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)} +@cindex hard links (in Dired) +@item H @var{new} @key{RET} +Make hard links to the specified files (@code{dired-do-hardlink}). +This is like the shell command @code{ln}. 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)} +@cindex symbolic links (creation in Dired) +@item S @var{new} @key{RET} +Make symbolic links to the specified files (@code{dired-do-symlink}). +This is like @samp{ln -s}. 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)} +@cindex changing file permissions (in 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)} +@cindex changing file group (in 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)} +@cindex changing file owner (in 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-touch +@kindex T @r{(Dired)} +@cindex changing file time (in Dired) +@item T @var{timestamp} @key{RET} +Touch the specified files (@code{dired-do-touch}). This means +updating their modification times to the present time. This is like +the shell command @code{touch}. + +@findex dired-do-print +@kindex P @r{(Dired)} +@cindex printing files (in 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{Printing}). + +@findex dired-do-compress +@kindex Z @r{(Dired)} +@cindex compressing files (in Dired) +@item Z +Compress the specified files (@code{dired-do-compress}). If the file +appears to be a compressed file already, uncompress it instead. + +@findex dired-do-load +@kindex L @r{(Dired)} +@cindex loading several files (in 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)} +@cindex byte-compiling several files (in 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 +@cindex search multiple files (in Dired) +@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-regexp +@cindex search and replace in multiple files (in Dired) +@item Q @var{regexp} @key{RET} @var{to} @key{RET} +Perform @code{query-replace-regexp} on each of the specified files, +replacing matches for @var{regexp} with the string +@var{to} (@code{dired-do-query-replace-regexp}). + +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 + +@node Shell Commands in Dired +@section Shell Commands in Dired +@cindex shell commands, Dired + +@findex dired-do-shell-command +@kindex ! @r{(Dired)} +@kindex X @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. (@kbd{X} is a synonym for @kbd{!}.) You can +specify the files to operate on in the usual ways for Dired commands +(@pxref{Operating on Files}). + + The working directory for the shell command is the top-level directory +of the Dired buffer. + + There are two ways of applying a shell command to multiple files: + +@itemize @bullet +@item +If you use @samp{*} surrounded by whitespace in the shell command, +then the command 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}. + +If you want to use @samp{*} as a shell wildcard with whitespace around +it, write @samp{*""}. In the shell, this is equivalent to @samp{*}; +but since the @samp{*} is not surrounded by whitespace, Dired does +not treat it specially. + +@item +If the command string doesn't contain @samp{*} surrounded by +whitespace, then it runs once @emph{for each file}. Normally the file +name is added at the end. + +For example, @kbd{! uudecode @key{RET}} runs @code{uudecode} on each +file. + +@item +However, if the command string contains @samp{?} surrounded by +whitespace, the current file name is substituted for @samp{?} (rather +than added at the end). You can use @samp{?} this way more than once +in the command, and the same file name replaces each occurrence. +@end itemize + + To iterate over the file names in a more complicated fashion, use an +explicit shell loop. For example, here is how to uuencode each file, +making the output file name by appending @samp{.uu} to the input file +name: + +@example +for file in * ; do uuencode "$file" "$file" >"$file".uu; done +@end example + + The @kbd{!} command does not attempt to update the Dired buffer to +show new or modified files, because it doesn't 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 + + This section describes Dired commands which alter file names in a +systematic way. Each command operates on some or all of the marked +files, using a new name made by transforming the existing name. + + Like the basic Dired file-manipulation commands (@pxref{Operating on +Files}), the commands described here operate either on the next +@var{n} files, or on all files marked with @samp{*}, or on the current +file. (To mark files, use the commands described in @ref{Marks vs +Flags}.) + + All of the commands described in this section work +@emph{interactively}: they ask you to confirm the operation for each +candidate file. Thus, you can select more files than you actually +need to operate on (e.g., with a regexp that matches many files), and +then filter the selected names by typing @kbd{y} or @kbd{n} when the +command prompts for confirmation. + +@table @kbd +@findex dired-upcase +@kindex % u @r{(Dired)} +@cindex upcase file names +@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)} +@cindex downcase file names +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. They read +two arguments: a regular expression @var{from}, and a substitution +pattern @var{to}; they match each ``old'' file name against +@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 file name.) + + 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. (A non-zero +argument specifies the number of files to operate on.) + + You may want to select the set of files to operate on using the same +regexp @var{from} that you will use to operate on them. To do this, +mark those files with @kbd{% m @var{from} @key{RET}}, then use the +same regular expression in the command to operate on the files. To +make this more convenient, 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 +@cindex file comparison (in Dired) +@cindex compare files (in Dired) + + Here are two Dired commands that compare specified files using +@code{diff}. They show the output in a buffer using Diff mode +(@pxref{Comparing Files}). + +@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. This refers to the ordinary +Emacs mark, not Dired marks; use @kbd{C-@key{SPC}} +(@code{set-mark-command}) to set the mark at the first file's line +(@pxref{Setting Mark}). + +@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 one of its backups. + +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. + + More often, you will want to show only specific subdirectories. 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{C-u k} on the subdirectory header +line to delete the subdirectory. @xref{Dired Updating}. + + + + +@ifnottex +@include dired-xtra.texi +@end ifnottex + +@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 +(@pxref{Pages}). + +@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. + +@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 Dired marks on files in those +subdirectories. + +@node Dired Updating +@section Updating the Dired Buffer +@cindex updating Dired buffer +@cindex refreshing displayed files + + 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}). You specify the +files for @kbd{l} in the same way as for file operations. + +@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}). Like the Dired file-operating commands, +this command operates on the next @var{n} files (or previous +@minus{}@var{n} files), or on the marked files if any, or on the +current file. Updating the files means reading their current status, +then updating their lines in the buffer to indicate that status. + + 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} from the buffer---not +delete the files---type @kbd{k} (@code{dired-do-kill-lines}). Like +the file-operating commands, this command operates on the next @var{n} +files, or on the marked files if any; but it does not operate on the +current file as a last resort. + + If you use @kbd{k} with a numeric prefix argument to kill the line +for a file that is a directory, which you have inserted in the Dired +buffer as a subdirectory, it deletes that subdirectory from the buffer +as well. Typing @kbd{C-u k} on the header line for a subdirectory +also deletes the 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 a 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{Grep Searching}. +Remember to write the regular expression for @code{grep}, not for Emacs. +(An alternative method of showing files whose contents match a given +regexp is the @kbd{% g @var{regexp}} command, see @ref{Marks vs Flags}.) + +@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. + +@findex locate +@findex locate-with-filter +@cindex file database (locate) +@vindex locate-command + The command @kbd{M-x locate} provides a similar interface to the +@code{locate} program. @kbd{M-x locate-with-filter} is similar, but +keeps only files whose names match a given regular expression. + + These buffers don't work entirely like ordinary Dired buffers: file +operations work, but do not always automatically update the buffer. +Reverting the buffer with @kbd{g} deletes all inserted subdirectories, +and erases all flags and marks. + +@node Wdired +@section Editing the Dired Buffer + +@cindex wdired mode +@findex wdired-change-to-wdired-mode + Wdired is a special mode that allows you to perform file operations +by editing the Dired buffer directly (the ``W'' in ``Wdired'' stands +for ``writable.'') To enter Wdired mode, type @kbd{C-x C-q} or @kbd{M-x +wdired-change-to-wdired-mode} while in a Dired buffer. Alternatively, +use @samp{Edit File Names} in the @samp{Immediate} menu bar menu. + +@findex wdired-finish-edit + While in Wdired mode, you can rename files by editing the file names +displayed in the Dired buffer. All the ordinary Emacs editing +commands, including rectangle operations and @code{query-replace}, are +available for this. Once you are done editing, type @kbd{C-c C-c} +(@code{wdired-finish-edit}). This applies your changes and switches +back to ordinary Dired mode. + + Apart from simply renaming files, you can move a file to another +directory by typing in the new file name (either absolute or +relative). To mark a file for deletion, delete the entire file name. +To change the target of a symbolic link, edit the link target name +which appears next to the link name. + + The rest of the text in the buffer, such as the file sizes and +modification dates, is marked read-only, so you can't edit it. +However, if you set @code{wdired-allow-to-change-permissions} to +@code{t}, you can edit the file permissions. For example, you can +change @samp{-rw-r--r--} to @samp{-rw-rw-rw-} to make a file +world-writable. These changes also take effect when you type @kbd{C-c +C-c}. + +@node Image-Dired +@section Viewing Image Thumbnails in Dired +@cindex image-dired mode +@cindex image-dired + + Image-Dired is a facility for browsing image files. It provides viewing +the images either as thumbnails or in full size, either inside Emacs +or through an external viewer. + +@kindex C-t d @r{(Image-Dired)} +@findex image-dired-display-thumbs + To enter Image-Dired, mark the image files you want to look at in +the Dired buffer, using @kbd{m} as usual. Then type @kbd{C-t d} +(@code{image-dired-display-thumbs}). This creates and switches to a +buffer containing image-dired, corresponding to the marked files. + + You can also enter Image-Dired directly by typing @kbd{M-x +image-dired}. This prompts for a directory; specify one that has +image files. This creates thumbnails for all the images in that +directory, and displays them all in the ``thumbnail buffer.'' This +takes a long time if the directory contains many image files, and it +asks for confirmation if the number of image files exceeds +@code{image-dired-show-all-from-dir-max-files}. + + With point in the thumbnail buffer, you can type @kbd{RET} +(@code{image-dired-display-thumbnail-original-image}) to display a +sized version of it in another window. This sizes the image to fit +the window. Use the arrow keys to move around in the buffer. For +easy browsing, use @kbd{SPC} +(@code{image-dired-display-next-thumbnail-original}) to advance and +display the next image. Typing @kbd{DEL} +(@code{image-dired-display-previous-thumbnail-original}) backs up to +the previous thumbnail and displays that instead. + +@vindex image-dired-external-viewer + To view and the image in its original size, either provide a prefix +argument (@kbd{C-u}) before pressing @kbd{RET}, or type +@kbd{C-@key{RET}} (@code{image-dired-thumbnail-display-external}) to +display the image in an external viewer. You must first configure +@code{image-dired-external-viewer}. + + You can delete images through Image-Dired also. Type @kbd{d} +(@code{image-dired-flag-thumb-original-file}) to flag the image file +for deletion in the Dired buffer. You can also delete the thumbnail +image from the thumbnail buffer with @kbd{C-d} +(@code{image-dired-delete-char}). + + More advanced features include @dfn{image tags}, which are metadata +used to categorize image files. The tags are stored in a plain text +file configured by @code{image-dired-db-file}. + + To tag image files, mark them in the dired buffer (you can also mark +files in Dired from the thumbnail buffer by typing @kbd{m}) and type +@kbd{C-t t} (@code{image-dired-tag-files}). You will be prompted for +a tag. To mark files having a certain tag, type @kbd{C-t f} +(@code{image-dired-mark-tagged-files}). After marking image files +with a certain tag, you can use @kbd{C-t d} to view them. + + You can also tag a file directly from the thumbnail buffer by typing +@kbd{t t} and you can remove a tag by typing @kbd{t r}. There is also +a special ``tag'' called ``comment'' for each file (it is not a tag in +the exact same sense as the other tags, it is handled slightly +different). That is used to enter a comment or description about the +image. You comment a file from the thumbnail buffer by typing +@kbd{c}. You will be prompted for a comment. Type @kbd{C-t c} to add +a comment from Dired (@code{image-dired-dired-comment-files}). + + Image-Dired also provides simple image manipulation. In the +thumbnail buffer, type @kbd{L} to rotate the original image 90 degrees +anti clockwise, and @kbd{R} to rotate it 90 degrees clockwise. This +rotation is lossless, and uses an external utility called JpegTRAN. + +@node Misc Dired Features +@section Other Dired Features + +@kindex + @r{(Dired)} +@findex dired-create-directory + An unusual Dired 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. + +@cindex Adding to the kill ring in Dired. +@kindex w @r{(Dired)} +@findex dired-copy-filename-as-kill + The @kbd{w} command (@code{dired-copy-filename-as-kill}) 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}. The names are separated by a space. + + With a zero prefix argument, this uses the absolute file name of +each marked file. With just @kbd{C-u} as the prefix argument, it uses +file names relative to the Dired buffer's default directory. (This +can still contain slashes if in a subdirectory.) As a special case, +if point is on a directory headerline, @kbd{w} gives you the absolute +name of that directory. Any prefix argument or marked files are +ignored in this case. + + The main purpose of this command is so that you can yank the file +names into arguments for other Emacs commands. It also displays what +it added to the kill ring, so you can use it to display the list of +currently marked files in the echo area. + +@findex dired-compare-directories + The command @kbd{M-x dired-compare-directories} is used to compare +the current Dired buffer with another directory. It marks all the files +that are ``different'' between the two directories. It puts these marks +in all Dired buffers where these files are listed, which of course includes +the current buffer. + + The default comparison method (used if you type @key{RET} at the +prompt) is to compare just the file names---each file name that does +not appear in the other directory is ``different.'' You can specify +more stringent comparisons by entering a Lisp expression, which can +refer to the variables @code{size1} and @code{size2}, the respective +file sizes; @code{mtime1} and @code{mtime2}, the last modification +times in seconds, as floating point numbers; and @code{fa1} and +@code{fa2}, the respective file attribute lists (as returned by the +function @code{file-attributes}). This expression is evaluated for +each pair of like-named files, and if the expression's value is +non-@code{nil}, those files are considered ``different.'' + + For instance, the sequence @code{M-x dired-compare-directories +@key{RET} (> mtime1 mtime2) @key{RET}} marks files newer in this +directory than in the other, and marks files older in the other +directory than in this one. It also marks files with no counterpart, +in both directories, as always. + +@cindex drag and drop, Dired + On the X window system, Emacs supports the ``drag and drop'' +protocol. You can drag a file object from another program, and drop +it onto a Dired buffer; this either moves, copies, or creates a link +to the file in that directory. Precisely which action is taken is +determined by the originating program. Dragging files out of a Dired +buffer is currently not supported. + +@ignore + arch-tag: d105f9b9-fc1b-4c5f-a949-9b2cf3ca2fc1 +@end ignore diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi new file mode 100644 index 00000000000..21a65999ec3 --- /dev/null +++ b/doc/emacs/display.texi @@ -0,0 +1,1259 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 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. Many variables also affect the details of +redisplay. Unless otherwise stated, the variables described in this +chapter have their effect by customizing redisplay itself; therefore, +their values only make a difference at the time of redisplay. + +@menu +* Scrolling:: Commands to move text up and down in a window. +* Auto Scrolling:: Redisplay scrolls text automatically when needed. +* Horizontal Scrolling:: Moving text left and right in a window. +* Follow Mode:: Follow mode lets two windows scroll as one. +* Faces:: How to change the display style using faces. +* Standard Faces:: Emacs' predefined faces. +* Font Lock:: Minor mode for syntactic highlighting using faces. +* Highlight Interactively:: Tell Emacs what text to highlight. +* Fringes:: Enabling or disabling window fringes. +* Displaying Boundaries:: Displaying top and bottom of the buffer. +* Useless Whitespace:: Showing possibly-spurious trailing whitespace. +* Selective Display:: Hiding lines with lots of indentation. +* Optional Mode Line:: Optional mode line display features. +* Text Display:: How text characters are normally displayed. +* Cursor Display:: Features for displaying the cursor. +* Line Truncation:: Truncating lines to fit the screen width instead + of continuing them to multiple screen lines. +* Display Custom:: 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'' or +``up'' means that text moves up, and new text appears at the bottom. +Scrolling ``backward'' or ``down'' 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 scroll explicitly 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} +@itemx @key{PAGEDOWN} +Likewise, scroll forward. +@item M-v +Scroll backward (@code{scroll-down}). +@item @key{PRIOR} +@itemx @key{PAGEUP} +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 scrolls the selected window so that point is halfway +down from the top of the window. On a text terminal, it also clears +the screen and redisplays all windows. That is useful in case the +screen is garbled (@pxref{Screen Garbled}). + +@kindex C-v +@kindex M-v +@kindex NEXT +@kindex PRIOR +@kindex PAGEDOWN +@kindex PAGEUP +@findex scroll-up +@findex scroll-down + To read the buffer a windowful at a time, use @kbd{C-v} +(@code{scroll-up}) with no argument. This scrolls forward by nearly +the whole window height. The effect is to take the two lines at the +bottom of the window and put them at the top, followed by nearly a +whole windowful of lines that were not previously visible. If point +was in the text that scrolled off the top, it ends up at the new top +of the window. + +@vindex next-screen-context-lines + @kbd{M-v} (@code{scroll-down}) with no argument scrolls backward in +a similar way, also with overlap. The number of lines of overlap that +the @kbd{C-v} or @kbd{M-v} commands leave is controlled by the +variable @code{next-screen-context-lines}; by default, it is 2. The +function keys @key{NEXT} and @key{PRIOR}, or @key{PAGEDOWN} and +@key{PAGEUP}, are equivalent to @kbd{C-v} and @kbd{M-v}. + + The commands @kbd{C-v} and @kbd{M-v} with a numeric argument scroll +the text in the selected window up or down a few lines. @kbd{C-v} +with an argument moves the text and point up, together, that many +lines; it brings the same number of new lines into view at the bottom +of the window. @kbd{M-v} with numeric argument scrolls the text +downward, bringing that many new lines into view at the top of the +window. @kbd{C-v} with a negative argument is like @kbd{M-v} and vice +versa. + + 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. The keys @key{PAGEDOWN} and @key{PAGEUP} derive their names +and customary meanings from a different convention that developed +elsewhere; hence the strange result that @key{PAGEDOWN} runs +@code{scroll-up}. + +@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. In +this mode, when these commands would scroll the text around point off +the screen, or within @code{scroll-margin} lines of the edge, they +move point to keep the same vertical position within the window. +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. @kbd{C-u C-l} scrolls to put +point at the center (vertically) 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. + +@node Auto Scrolling +@section Automatic Scrolling + +@vindex scroll-conservatively + Redisplay scrolls the buffer automatically when point moves out of +the visible portion of the text. The purpose of automatic scrolling +is to make point visible, but you can customize many aspects of how +this is done. + + 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@tie{}0. + +@cindex aggressive scrolling +@vindex scroll-up-aggressively +@vindex scroll-down-aggressively + When the window does scroll by a longer distance, you can control +how aggressively it scrolls, by setting the variables +@code{scroll-up-aggressively} and @code{scroll-down-aggressively}. +The value of @code{scroll-up-aggressively} should be either +@code{nil}, or a fraction @var{f} between 0 and 1. A fraction +specifies where on the screen to put point when scrolling upward. +More precisely, when a window scrolls up because point is above the +window start, the new start position is chosen to put point @var{f} +part of the window height from the top. The larger @var{f}, the more +aggressive the scrolling. + + @code{nil}, which is the default, scrolls to put point at the center. +So it is equivalent to .5. + + Likewise, @code{scroll-down-aggressively} is used for scrolling +down. The value, @var{f}, specifies how far point should be placed +from the bottom of the window; thus, as with +@code{scroll-up-aggressively}, a larger value is more aggressive. + +@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. When the text in a window is scrolled horizontally, +text lines are truncated rather than continued (@pxref{Line +Truncation}). Whenever a window shows truncated lines, Emacs +automatically updates its horizontal scrolling whenever point moves +off the left or right edge of the screen. You can also use these +commands to do explicit horizontal scrolling. + +@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 + +@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. + + If you use those commands to scroll a window horizontally, that sets +a lower bound for automatic horizontal scrolling. Automatic scrolling +will continue to scroll the window, but never farther to the right +than the amount you previously set by @code{scroll-left}. + +@vindex hscroll-margin + The value of the variable @code{hscroll-margin} controls how close +to the window's edges point is allowed to get before the window will +be automatically scrolled. It is measured in columns. If the value +is 5, then moving point within 5 columns of the edge causes horizontal +scrolling away from that edge. + +@vindex hscroll-step + The variable @code{hscroll-step} determines how many columns to +scroll the window when point gets too close to the edge. If it's +zero, horizontal scrolling centers point horizontally within the +window. If it's a positive integer, it specifies the number of +columns to scroll by. If it's a floating-point number, it specifies +the fraction of the window's width to scroll by. The default is zero. + +@vindex auto-hscroll-mode + To disable automatic horizontal scrolling, set the variable +@code{auto-hscroll-mode} to @code{nil}. + +@node Follow Mode +@section Follow Mode +@cindex Follow mode +@cindex mode, Follow +@findex follow-mode +@cindex windows, synchronizing +@cindex synchronizing windows + + @dfn{Follow mode} is a minor mode that makes two windows, both +showing the same buffer, scroll as a single 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. + + In Follow mode, if you move point outside the portion visible in one +window and into the portion visible in the other window, that selects +the other window---again, treating the two as if they were parts of +one large window. + + To turn off Follow mode, type @kbd{M-x follow-mode} a second time. + +@node Faces +@section Using Multiple Typefaces +@cindex faces + + You can specify various styles for displaying text using +@dfn{faces}. Each face can specify various @dfn{face attributes}, +such as the font family, the height, weight and slant of the +characters, the foreground and background color, and underlining or +overlining. A face does not have to specify all of these attributes; +often it inherits most of them from another face. + + On graphical display, all the Emacs face attributes are meaningful. +On a text-only terminal, only some of them work. Some text-only +terminals support inverse video, bold, and underline attributes; some +support colors. Text-only terminals generally do not support changing +the height and width or the font family. + + Emacs uses faces automatically for highlighting, through the work of +Font Lock mode. @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}. + + You control the appearance of a part of the text in the buffer by +specifying the face or faces to use for it. The style of display used +for any given character is determined by combining the attributes of +all the applicable faces specified for that character. Any attribute +that isn't specified by these faces is taken from the @code{default} face, +whose attributes reflect the default settings of the frame itself. + + Enriched mode, the mode for editing formatted text, includes several +commands and menus for specifying faces for text in the buffer. +@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. + +@cindex face colors, setting +@findex set-face-foreground +@findex set-face-background + 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}). Alternatively, +you can change the foreground and background colors of a specific face +with @kbd{M-x set-face-foreground} and @kbd{M-x set-face-background}. +These commands prompt in the minibuffer for a face name and a color +name, with completion, and then set that face to use the specified +color. Changing the colors of the @code{default} face also changes +the foreground and background colors on all frames, both existing and +those to be created in the future. (You can also set foreground and +background colors for the current frame only; see @ref{Frame +Parameters}.) + + If you want to alter the appearance of all Emacs frames, you need to +customize the frame parameters in the variable +@code{default-frame-alist}; see @ref{Creating Frames, +default-frame-alist}. + + Emacs can correctly display variable-width fonts, but Emacs commands +that calculate width and indentation do not know how to calculate +variable widths. This can sometimes lead to incorrect results when +you use variable-width fonts. In particular, indentation commands can +give inconsistent results, so we recommend you avoid variable-width +fonts for editing program source code. Filling will sometimes make +lines too long or too short. We plan to address these issues in +future Emacs versions. + +@node Standard Faces +@section Standard Faces + +@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. With a prefix argument, this +prompts for a regular expression, and displays only faces with names +matching that regular expression. + + Here are the standard faces for specifying text appearance. You can +apply them to specific text when you want the effects they produce. + +@table @code +@item default +This face is used for ordinary text that doesn't specify any face. +@item bold +This face uses a bold variant of the default font, if it has one. +It's up to you to choose a default font that has a bold variant, +if you want to use 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. +@item fixed-pitch +This face forces use of a particular fixed-width font. +@item variable-pitch +This face forces use of a particular variable-width font. It's +reasonable to customize this face to use a different variable-width font, +if you like, but you should not make it a fixed-width font. +@item shadow +This face is used for making the text less noticeable than the surrounding +ordinary text. Usually this can be achieved by using shades of gray in +contrast with either black or white default foreground color. +@end table + + Here's an incomplete list of faces used to highlight parts of the +text temporarily for specific purposes. (Many other modes define +their own faces for this purpose.) + +@table @code +@item highlight +This face is used for highlighting portions of text, in various modes. +For example, mouse-sensitive text is highlighted using this face. +@item isearch +This face is used for highlighting the current Isearch match. +@item query-replace +This face is used for highlighting the current Query Replace match. +@item lazy-highlight +This face is used for lazy highlighting of Isearch and Query Replace +matches other than the current one. +@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 X selection (@pxref{Secondary +Selection}). +@item trailing-whitespace +The face for highlighting excess spaces and tabs at the end of a line +when @code{show-trailing-whitespace} is non-@code{nil}; see +@ref{Useless Whitespace}. +@item nobreak-space +The face for displaying the character ``nobreak space.'' +@item escape-glyph +The face for highlighting the @samp{\} or @samp{^} that indicates +a control character. It's also used when @samp{\} indicates a +nobreak space or nobreak (soft) hyphen. +@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. + + These faces control the appearance of parts of the Emacs frame. +They exist as faces to provide a consistent way to customize the +appearance of these parts of the frame. + +@table @code +@item mode-line +@itemx modeline +This face is used for the mode line of the currently selected window, +and for menu bars when toolkit menus are not used. By default, it's +drawn with shadows for a ``raised'' effect on graphical displays, and +drawn as the inverse of the default face on non-windowed terminals. +@code{modeline} is an alias for the @code{mode-line} face, for +compatibility with old Emacs versions. +@item mode-line-inactive +Like @code{mode-line}, but used for mode lines of the windows other +than the selected one (if @code{mode-line-in-non-selected-windows} is +non-@code{nil}). This face inherits from @code{mode-line}, so changes +in that face affect mode lines in all windows. +@item mode-line-highlight +Like @code{highlight}, but used for portions of text on mode lines. +@item mode-line-buffer-id +This face is used for buffer identification parts in the mode line. +@item header-line +Similar to @code{mode-line} for a window's header line, which appears +at the top of a window just as the mode line appears at the bottom. +Most windows do not have a header line---only some special modes, such +Info mode, create one. +@item vertical-border +This face is used for the vertical divider between windows. +By default this face inherits from the @code{mode-line-inactive} face +on character terminals. On graphical displays the foreground color of +this face is used for the vertical line between windows without +scrollbars. +@item minibuffer-prompt +@cindex @code{minibuffer-prompt} face +@vindex minibuffer-prompt-properties +This face is used for the prompt strings displayed in the minibuffer. +By default, Emacs automatically adds this face to the value of +@code{minibuffer-prompt-properties}, which is a list of text +properties used to display the prompt text. (This variable takes +effect when you enter the minibuffer.) +@item fringe +@cindex @code{fringe} face +The face for the fringes to the left and right of windows on graphic +displays. (The fringes are the narrow portions of the Emacs frame +between the text area and the window's right and left borders.) +@xref{Fringes}. +@item scroll-bar +This face determines the visual appearance of the scroll bar. +@xref{Scroll Bars}. +@item border +This face determines the color of the frame border. +@item cursor +This face determines the color of the cursor. +@item mouse +This face determines the color of the mouse pointer. +@item tool-bar +This face determines the color of tool bar icons. @xref{Tool Bars}. +@item tooltip +This face is used for tooltips. @xref{Tooltips}. +@item menu +@cindex menu bar appearance +@cindex @code{menu} face, no effect if customized +@cindex customization of @code{menu} face +This face determines the colors and font of Emacs's menus. @xref{Menu +Bars}. Setting the font of LessTif/Motif menus is currently not +supported; attempts to set the font are ignored in this case. +Likewise, attempts to customize this face in Emacs built with GTK and +in the MS-Windows/Mac ports are ignored by the respective GUI toolkits; +you need to use system-wide styles and options to change the +appearance of the menus. +@end table + +@node Font Lock +@section Font Lock mode +@cindex Font Lock mode +@cindex mode, Font Lock +@cindex syntax highlighting and coloring + + Font Lock mode is a minor mode, always local to a particular buffer, +which highlights (or ``fontifies'') the buffer contents 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. +Some special modes, such as Occur mode and Info mode, have completely +specialized ways of assigning fonts for Font Lock mode. + +@findex font-lock-mode + Font Lock mode is turned on by default in all modes which support it. +You can toggle font-lock for each buffer with the command @kbd{M-x +font-lock-mode}. Using a positive argument unconditionally turns Font +Lock mode on, and a negative or zero argument turns it off. + +@findex global-font-lock-mode +@vindex global-font-lock-mode + If you do not wish Font Lock mode to be turned on by default, +customize the variable @code{global-font-lock-mode} using the Customize +interface (@pxref{Easy Customization}), or use the function +@code{global-font-lock-mode} in your @file{.emacs} file, like this: + +@example +(global-font-lock-mode 0) +@end example + +@noindent +This variable, like all the variables that control Font Lock mode, +take effect whenever fontification is done; that is, potentially at +any time. + +@findex turn-on-font-lock + If you have disabled Global Font Lock mode, you can still enable Font +Lock for specific major modes by adding the function +@code{turn-on-font-lock} to the mode hooks (@pxref{Hooks}). For +example, to enable Font Lock mode for editing C files, you can do this: + +@example +(add-hook 'c-mode-hook 'turn-on-font-lock) +@end example + + Font Lock mode uses several specifically named faces to do its job, +including @code{font-lock-string-face}, @code{font-lock-comment-face}, +and others. The easiest way to find them all is to use @kbd{M-x +customize-group @key{RET} font-lock-faces @key{RET}}. You can then +use that customization buffer to customize the appearance of these +faces. @xref{Face Customization}. + + You can also customize these faces using @kbd{M-x +set-face-foreground} or @kbd{M-x set-face-background}. @xref{Faces}. + +@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 for buffers above a certain size. 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 +@cindex incorrect fontification +@cindex parenthesis in column zero and fontification +@cindex brace in column zero and fontification + Comment and string fontification (or ``syntactic'' fontification) +relies on analysis of the syntactic structure of the buffer text. For +the sake of speed, some modes, including Lisp mode, rely on a special +convention: an open-parenthesis or open-brace in the leftmost column +always defines the @w{beginning} of a defun, and is thus always +outside any string or comment. (@xref{Left Margin Paren}.) If you +don't follow this convention, Font Lock mode can misfontify the text +that follows an open-parenthesis or open-brace in the leftmost column +that is inside a string or comment. + +@cindex slow display during scrolling + 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. This can considerably +slow down redisplay while scrolling, particularly if you are close to +the end of a large 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 + +@findex font-lock-remove-keywords + To remove keywords from the font-lock highlighting patterns, use the +function @code{font-lock-remove-keywords}. @xref{Search-based +Fontification,,, elisp, The Emacs Lisp Reference Manual}, for +documentation of the format of this list. + +@cindex just-in-time (JIT) font-lock +@cindex background syntax highlighting + Fontifying large buffers can take a long time. To avoid large +delays when a file is visited, Emacs fontifies only the visible +portion of a buffer. As you scroll through the buffer, each portion +that becomes visible is fontified as soon as it is displayed. The +parts of the buffer that are not displayed are fontified +``stealthily,'' in the background, i.e.@: when Emacs is idle. You can +control this background fontification, also called @dfn{Just-In-Time} +(or @dfn{JIT}) Lock, by customizing variables in the customization +group @samp{jit-lock}. @xref{Specific Customization}. + +@node Highlight Interactively +@section Interactive Highlighting +@cindex highlighting by matching +@cindex interactive highlighting +@cindex Highlight Changes mode + +@findex highlight-changes-mode + Use @kbd{M-x highlight-changes-mode} to enable (or disable) +Highlight Changes mode, a minor mode that uses faces (colors, +typically) to indicate which parts of the buffer were changed most +recently. + +@cindex Hi Lock mode +@findex hi-lock-mode + Hi Lock mode highlights text that matches regular expressions you +specify. For example, you might wish to see all the references to a +certain variable in a program source file, highlight certain parts in +a voluminous output of some program, or make certain names stand out +in an article. Use the @kbd{M-x hi-lock-mode} command to enable (or +disable) Hi Lock mode. To enable Hi Lock mode for all buffers, use +@kbd{M-x global-hi-lock-mode} or place @code{(global-hi-lock-mode 1)} +in your @file{.emacs} file. + + Hi Lock mode works like Font Lock mode (@pxref{Font Lock}), except +that you specify explicitly the regular expressions to highlight. You +control them with these commands: + +@table @kbd +@item C-x w h @var{regexp} @key{RET} @var{face} @key{RET} +@kindex C-x w h +@findex highlight-regexp +Highlight text that matches @var{regexp} using face @var{face} +(@code{highlight-regexp}). The highlighting will remain as long as +the buffer is loaded. For example, to highlight all occurrences of +the word ``whim'' using the default face (a yellow background) +@kbd{C-x w h whim @key{RET} @key{RET}}. Any face can be used for +highlighting, Hi Lock provides several of its own and these are +pre-loaded into a history list. While being prompted for a face use +@kbd{M-p} and @kbd{M-n} to cycle through them. + +You can use this command multiple times, specifying various regular +expressions to highlight in different ways. + +@item C-x w r @var{regexp} @key{RET} +@kindex C-x w r +@findex unhighlight-regexp +Unhighlight @var{regexp} (@code{unhighlight-regexp}). + +If you invoke this from the menu, you select the expression to +unhighlight from a list. If you invoke this from the keyboard, you +use the minibuffer. It will show the most recently added regular +expression; use @kbd{M-p} to show the next older expression and +@kbd{M-n} to select the next newer expression. (You can also type the +expression by hand, with completion.) When the expression you want to +unhighlight appears in the minibuffer, press @kbd{@key{RET}} to exit +the minibuffer and unhighlight it. + +@item C-x w l @var{regexp} @key{RET} @var{face} @key{RET} +@kindex C-x w l +@findex highlight-lines-matching-regexp +@cindex lines, highlighting +@cindex highlighting lines of text +Highlight entire lines containing a match for @var{regexp}, using face +@var{face} (@code{highlight-lines-matching-regexp}). + +@item C-x w b +@kindex C-x w b +@findex hi-lock-write-interactive-patterns +Insert all the current highlighting regexp/face pairs into the buffer +at point, with comment delimiters to prevent them from changing your +program. (This key binding runs the +@code{hi-lock-write-interactive-patterns} command.) + +These patterns are extracted from the comments, if appropriate, if you +invoke @kbd{M-x hi-lock-find-patterns}, or if you visit the file while +Hi Lock mode is enabled (since that runs @code{hi-lock-find-patterns}). + +@item C-x w i +@kindex C-x w i +@findex hi-lock-find-patterns +Extract regexp/face pairs from comments in the current buffer +(@code{hi-lock-find-patterns}). Thus, you can enter patterns +interactively with @code{highlight-regexp}, store them into the file +with @code{hi-lock-write-interactive-patterns}, edit them (perhaps +including different faces for different parenthesized parts of the +match), and finally use this command (@code{hi-lock-find-patterns}) to +have Hi Lock highlight the edited patterns. + +@vindex hi-lock-file-patterns-policy +The variable @code{hi-lock-file-patterns-policy} controls whether Hi +Lock mode should automatically extract and highlight patterns found in +a file when it is visited. Its value can be @code{nil} (never +highlight), @code{t} (highlight the patterns), @code{ask} (query the +user), or a function. If it is a function, +@code{hi-lock-find-patterns} calls it with the patterns as argument; +if the function returns non-@code{nil}, the patterns are used. The +default is @code{nil}. Note that patterns are always highlighted if +you call @code{hi-lock-find-patterns} directly, regardless of the +value of this variable. + +@vindex hi-lock-exclude-modes +Also, @code{hi-lock-find-patterns} does nothing if the current major +mode's symbol is a member of the list @code{hi-lock-exclude-modes}. +@end table + +@node Fringes +@section Window Fringes +@cindex fringes + + On a graphical display, each Emacs window normally has narrow +@dfn{fringes} on the left and right edges. The fringes display +indications about the text in the window. + + The most common use of the fringes is to indicate a continuation +line, when one line of text is split into multiple lines on the +screen. The left fringe shows a curving arrow for each screen line +except the first, indicating that ``this is not the real beginning.'' +The right fringe shows a curving arrow for each screen line except the +last, indicating that ``this is not the real end.'' + + The fringes indicate line truncation with short horizontal arrows +meaning ``there's more text on this line which is scrolled +horizontally out of view;'' clicking the mouse on one of the arrows +scrolls the display horizontally in the direction of the arrow. The +fringes can also indicate other things, such as empty lines, or where a +program you are debugging is executing (@pxref{Debuggers}). + +@findex set-fringe-style +@findex fringe-mode + You can enable and disable the fringes for all frames using +@kbd{M-x fringe-mode}. To enable and disable the fringes +for the selected frame, use @kbd{M-x set-fringe-style}. + +@node Displaying Boundaries +@section Displaying Boundaries + +@vindex indicate-buffer-boundaries + On a graphical display, Emacs can indicate the buffer boundaries in +the fringes. It indicates the first line and the last line with +angle images in the fringes. This can be combined with up and down +arrow images which say whether it is possible to scroll the window up +and down. + + The buffer-local variable @code{indicate-buffer-boundaries} controls +how the buffer boundaries and window scrolling is indicated in the +fringes. If the value is @code{left} or @code{right}, both angle and +arrow bitmaps are displayed in the left or right fringe, respectively. + + If value is an alist, each element @code{(@var{indicator} . +@var{position})} specifies the position of one of the indicators. +The @var{indicator} must be one of @code{top}, @code{bottom}, +@code{up}, @code{down}, or @code{t} which specifies the default +position for the indicators not present in the alist. +The @var{position} is one of @code{left}, @code{right}, or @code{nil} +which specifies not to show this indicator. + + For example, @code{((top . left) (t . right))} places the top angle +bitmap in left fringe, the bottom angle bitmap in right fringe, and +both arrow bitmaps in right fringe. To show just the angle bitmaps in +the left fringe, but no arrow bitmaps, use @code{((top . left) +(bottom . left))}. + +@vindex default-indicate-buffer-boundaries + The value of the variable @code{default-indicate-buffer-boundaries} +is the default value for @code{indicate-buffer-boundaries} in buffers +that do not override it. + +@node Useless Whitespace +@section Useless Whitespace + +@cindex trailing whitespace +@cindex whitespace, trailing +@vindex show-trailing-whitespace + It is easy to leave unnecessary spaces at the end of a line, or +empty lines at the end of a file, without realizing it. In most +cases, this @dfn{trailing whitespace} has no effect, but there are +special circumstances where it matters. It can also be a nuisance +that the line has ``changed,'' when the change is just spaces added or +removed at the end. + + You can make trailing whitespace at the end of a line visible on the +screen by setting the buffer-local variable +@code{show-trailing-whitespace} to @code{t}. Then Emacs displays +trailing whitespace in the face @code{trailing-whitespace}. + + This feature does not apply when point is at the end of the line +containing the whitespace. Strictly speaking, that is ``trailing +whitespace'' nonetheless, but displaying it specially in that case +looks ugly while you are typing in new text. In this special case, +the location of point is enough to show you that the spaces are +present. + +@findex delete-trailing-whitespace + To delete all trailing whitespace within the current buffer's +accessible portion (@pxref{Narrowing}), type @kbd{M-x +delete-trailing-whitespace @key{RET}}. (This command does not remove +the form-feed characters.) + +@vindex indicate-empty-lines +@vindex default-indicate-empty-lines +@cindex unused lines +@cindex fringes, and unused line indication + Emacs can indicate unused lines at the end of the window with a +small image in the left fringe (@pxref{Fringes}). The image appears +for window lines that do not correspond to any buffer text. Blank +lines at the end of the buffer then stand out because they do not have +this image in the fringe. + + To enable this feature, set the buffer-local variable +@code{indicate-empty-lines} to a non-@code{nil} value. The default +value of this variable is controlled by the variable +@code{default-indicate-empty-lines}; by setting that variable, you +can enable or disable this feature for all new buffers. (This feature +currently doesn't work on text-only terminals.) + +@node Selective Display +@section Selective Display +@cindex 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 in the current buffer, 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. + + See also @ref{Outline Mode} for another way to hide part of +the text in a buffer. + +@node Optional Mode Line +@section Optional Mode Line Features + +@cindex buffer size display +@cindex display of buffer size +@findex size-indication-mode + The buffer percentage @var{pos} indicates the percentage of the +buffer above the top of the window. You can additionally display the +size of the buffer by typing @kbd{M-x size-indication-mode} to turn on +Size Indication mode. The size will be displayed immediately +following the buffer percentage like this: + +@example +@var{POS} of @var{SIZE} +@end example + +@noindent +Here @var{SIZE} is the human readable representation of the number of +characters in the buffer, which means that @samp{k} for 10^3, @samp{M} +for 10^6, @samp{G} for 10^9, etc., are used to abbreviate. + +@cindex narrowing, and buffer size display + If you have narrowed the buffer (@pxref{Narrowing}), the size of the +accessible part of the buffer is shown. + +@cindex line number display +@cindex display of 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 +after the buffer percentage @var{pos}, with the letter @samp{L} to +indicate what it is. + +@cindex Column Number mode +@cindex mode, Column Number +@findex column-number-mode + Similarly, you can display the current column number by turning on +Column number mode with @kbd{M-x column-number-mode}. The column +number is indicated by the letter @samp{C}. However, when both of +these modes are enabled, the line and column numbers are displayed in +parentheses, the line number first, rather than with @samp{L} and +@samp{C}. For example: @samp{(561,2)}. @xref{Minor Modes}, for more +information about minor modes and about how to use these commands. + +@cindex narrowing, and line number display + If you have narrowed the buffer (@pxref{Narrowing}), the displayed +line number is relative to the accessible portion of the buffer. +Thus, it isn't suitable as an argument to @code{goto-line}. (Use +@code{what-line} command to see the line number relative to the whole +file.) + +@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. Set it to @code{nil} to remove the limit. + +@vindex line-number-display-limit-width + Line-number computation can also be slow if the lines in the buffer +are too long. For this reason, Emacs normally doesn't display line +numbers if the average width, in characters, of lines near point is +larger than the value of the variable +@code{line-number-display-limit-width}. The default value is 200 +characters. + +@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} or customize +the option @code{display-time-mode}. 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) +@vindex display-time-use-mail-icon +@vindex display-time-mail-face +@vindex display-time-mail-file +@vindex display-time-mail-directory + The word @samp{Mail} appears after the load level if there is mail +for you that you have not read yet. On a graphical display you can use +an icon instead of @samp{Mail} by customizing +@code{display-time-use-mail-icon}; this may save some space on the mode +line. You can customize @code{display-time-mail-face} to make the mail +indicator prominent. Use @code{display-time-mail-file} to specify +the mail file to check, or set @code{display-time-mail-directory} +to specify the directory to check for incoming mail (any nonempty regular +file in the directory is considered as ``newly arrived mail''). + +@cindex mode line, 3D appearance +@cindex attributes of mode line, changing +@cindex non-integral number of lines in a window + By default, the mode line is drawn on graphics displays with +3D-style highlighting, like that of a button when it is not being +pressed. If you don't like this effect, you can disable the 3D +highlighting of the mode line, by customizing the attributes of the +@code{mode-line} face. @xref{Face Customization}. + +@cindex non-selected windows, mode line appearance + By default, the mode line of nonselected windows is displayed in a +different face, called @code{mode-line-inactive}. Only the selected +window is displayed in the @code{mode-line} face. This helps show +which window is selected. When the minibuffer is selected, since +it has no mode line, the window from which you activated the minibuffer +has its mode line displayed using @code{mode-line}; as a result, +ordinary entry to the minibuffer does not change any mode lines. + +@vindex mode-line-in-non-selected-windows + You can disable use of @code{mode-line-inactive} by setting variable +@code{mode-line-in-non-selected-windows} to @code{nil}; then all mode +lines are displayed in the @code{mode-line} face. + +@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 the strings you prefer. + +@node Text Display +@section How Text Is Displayed +@cindex characters (in text) + + @acronym{ASCII} printing characters (octal codes 040 through 0176) in Emacs +buffers are displayed with their graphics, as are non-ASCII multibyte +printing characters (octal codes above 0400). + + Some @acronym{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 @acronym{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}. The caret appears in face +@code{escape-glyph}. + + Non-@acronym{ASCII} characters 0200 through 0237 (octal) are +displayed with octal escape sequences; thus, character code 0230 +(octal) is displayed as @samp{\230}. The backslash appears in face +@code{escape-glyph}. + +@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}. + + The display of character codes 0240 through 0377 (octal) may be +either as escape sequences or as graphics. They do not normally occur +in multibyte buffers, but if they do, they are displayed as Latin-1 +graphics. In unibyte mode, if you enable European display they are +displayed using their graphics (assuming your terminal supports them), +otherwise as escape sequences. @xref{Unibyte Mode}. + +@vindex nobreak-char-display +@cindex no-break space, display +@cindex no-break hyphen, display +@cindex soft hyphen, display + Some character sets define ``no-break'' versions of the space and +hyphen characters, which are used where a line should not be broken. +Emacs normally displays these characters with special faces +(respectively, @code{nobreak-space} and @code{escape-glyph}) to +distinguish them from ordinary spaces and hyphens. You can turn off +this feature by setting the variable @code{nobreak-char-display} to +@code{nil}. If you set the variable to any other value, that means to +prefix these characters with an escape character. + +@vindex tab-width +@vindex default-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. 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. The variable +@code{default-tab-width} controls the default value of this variable +for buffers where you have not set it locally. + + 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}. + +@node Cursor Display +@section Displaying the Cursor + +@findex blink-cursor-mode +@vindex blink-cursor-alist +@cindex cursor, locating visually +@cindex cursor, blinking + You can customize the cursor's color, and whether it blinks, using +the @code{cursor} Custom group (@pxref{Easy Customization}). On +a graphical display, the command @kbd{M-x blink-cursor-mode} enables +or disables the blinking of the cursor. (On text terminals, the +terminal itself blinks the cursor, and Emacs has no control over it.) +You can control how the cursor appears when it blinks off by setting +the variable @code{blink-cursor-alist}. + +@vindex visible-cursor + Some text terminals offer two different cursors: the normal cursor +and the very visible cursor, where the latter may be e.g. bigger or +blinking. By default Emacs uses the very visible cursor, and switches +to it when you start or resume Emacs. If the variable +@code{visible-cursor} is @code{nil} when Emacs starts or resumes, it +doesn't switch, so it uses the normal cursor. + +@cindex cursor in non-selected windows +@vindex cursor-in-non-selected-windows + Normally, the cursor appears in non-selected windows in the ``off'' +state, with the same appearance as when the blinking cursor blinks +``off.'' For a box cursor, this is a hollow box; for a bar cursor, +this is a thinner bar. To turn off cursors in non-selected windows, +customize the variable @code{cursor-in-non-selected-windows} and assign +it a @code{nil} value. + +@vindex x-stretch-cursor +@cindex wide block cursor + On graphical displays, Emacs can optionally draw the block cursor +as wide as the character under the cursor---for example, if the cursor +is on a tab character, it would cover the full width occupied by that +tab character. To enable this feature, set the variable +@code{x-stretch-cursor} to a non-@code{nil} value. + +@findex hl-line-mode +@findex global-hl-line-mode +@cindex highlight current line + To make the cursor even more visible, you can use HL Line mode, a +minor mode that highlights the line containing point. Use @kbd{M-x +hl-line-mode} to enable or disable it in the current buffer. @kbd{M-x +global-hl-line-mode} enables or disables the same mode globally. + +@node Line Truncation +@section Truncation of Lines + +@cindex truncation +@cindex line truncation, and fringes + 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. On +graphical displays, a small straight arrow in the fringe indicates +truncation at either end of the line. On text-only terminals, @samp{$} +appears 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. + +@vindex truncate-lines +@findex toggle-truncate-lines + Horizontal scrolling automatically causes line truncation +(@pxref{Horizontal Scrolling}). You can explicitly enable line +truncation for a particular buffer with the command @kbd{M-x +toggle-truncate-lines}. This works by locally changing the variable +@code{truncate-lines}. If that variable is non-@code{nil}, long lines +are truncated; if it is @code{nil}, they are continued onto multiple +screen lines. Setting the variable @code{truncate-lines} in any way +makes it local to the current buffer; until that time, the default +value is in effect. The default value is normally @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 overflow-newline-into-fringe + If the variable @code{overflow-newline-into-fringe} is +non-@code{nil} on a graphical display, then Emacs does not continue or +truncate a line which is exactly as wide as the window. Instead, the +newline overflows into the right fringe, and the cursor appears in the +fringe when positioned on that newline. + +@node Display Custom +@section Customization of Display + + This section describes variables (@pxref{Variables}) that you can +change to customize how Emacs displays. Beginning users can skip +it. +@c the reason for that pxref is because an xref early in the +@c ``echo area'' section leads here. + +@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. + +@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. The value takes effect when +there is someting to echo. @xref{Echo Area}. + +@vindex baud-rate + The variable @anchor{baud-rate}@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. On text-only terminals, it affects padding, +and decisions about whether to scroll part of the screen or redraw it +instead. It also affects the behavior of incremental search. + + On graphical displays, @code{baud-rate} is only used to determine +how frequently to look for pending input during display updating. A +higher value of @code{baud-rate} means that check for pending input +will be done less frequently. + +@cindex hourglass pointer display +@vindex hourglass-delay + On graphical display, Emacs can optionally display the mouse pointer +in a special shape to say that Emacs is busy. To turn this feature on +or off, customize the group @code{cursor}. You can also control the +amount of time Emacs must remain busy before the busy indicator is +displayed, by setting the variable @code{hourglass-delay}. + +@vindex overline-margin + On graphical display, this variables specifies the vertical position +of an overline above the text, including the height of the overline +itself (1 pixel). The default value is 2 pixels. + +@vindex x-underline-at-descent-line + On graphical display, Emacs normally draws an underline at the +baseline level of the font. If @code{x-underline-at-descent-line} is +non-@code{nil}, Emacs draws the underline at the same height as the +font's descent line. + +@findex tty-suppress-bold-inverse-default-colors + On some text-only terminals, bold face and inverse video together +result in text that is hard to read. Call the function +@code{tty-suppress-bold-inverse-default-colors} with a non-@code{nil} +argument to suppress the effect of bold-face in this case. + +@vindex no-redraw-on-reenter + On a text-only terminal, 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. On such terminals, 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. + +@ignore + arch-tag: 2219f910-2ff0-4521-b059-1bd231a536c4 +@end ignore diff --git a/doc/emacs/doclicense.texi b/doc/emacs/doclicense.texi new file mode 100644 index 00000000000..83e9d6b5579 --- /dev/null +++ b/doc/emacs/doclicense.texi @@ -0,0 +1,416 @@ +@c -*-texinfo-*- +@center Version 1.2, November 2002 + +@display +Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. +51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display +@sp 1 +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document ``free'' in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft,'' which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@sp 1 +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document,'' below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you.'' You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section of +the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall subject +(or to related matters) and contains nothing that could fall directly +within that overall subject. (Thus, if the Document is in part a +textbook of mathematics, a Secondary Section may not explain any +mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque.'' + + +Examples of suitable formats for Transparent copies include plain +ASCII without markup, Texinfo input format, LaTeX input format, SGML +or XML using a publicly available DTD, and standard-conforming simple +HTML, PostScript or PDF designed for human modification. Examples of +transparent image formats include PNG, XCF and JPG. Opaque formats +include proprietary formats that can be read and edited only by +proprietary word processors, SGML or XML for which the DTD and/or +processing tools are not generally available, and the +machine-generated HTML, PostScript or PDF produced by some word +processors for output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements,'' +``Dedications,'' ``Endorsements,'' or ``History.'') To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. +@sp 1 +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. +@sp 1 +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. +@sp 1 +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +A. Use in the Title Page (and on the covers, if any) a title distinct + from that of the Document, and from those of previous versions + (which should, if there were any, be listed in the History section + of the Document). You may use the same title as a previous version + if the original publisher of that version gives permission.@* +B. List on the Title Page, as authors, one or more persons or entities + responsible for authorship of the modifications in the Modified + Version, together with at least five of the principal authors of the + Document (all of its principal authors, if it has fewer than five), + unless they release you from this requirement.@* +C. State on the Title page the name of the publisher of the + Modified Version, as the publisher.@* +D. Preserve all the copyright notices of the Document.@* +E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices.@* +F. Include, immediately after the copyright notices, a license notice + giving the public permission to use the Modified Version under the + terms of this License, in the form shown in the Addendum below.@* +G. Preserve in that license notice the full lists of Invariant Sections + and required Cover Texts given in the Document's license notice.@* +H. Include an unaltered copy of this License.@* +I. Preserve the section Entitled ``History,'' Preserve its Title, and add + to it an item stating at least the title, year, new authors, and + publisher of the Modified Version as given on the Title Page. If + there is no section Entitled ``History'' in the Document, create one + stating the title, year, authors, and publisher of the Document as + given on its Title Page, then add an item describing the Modified + Version as stated in the previous sentence.@* +J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and likewise + the network locations given in the Document for previous versions + it was based on. These may be placed in the ``History'' section. + You may omit a network location for a work that was published at + least four years before the Document itself, or if the original + publisher of the version it refers to gives permission.@* +K. For any section Entitled ``Acknowledgements'' or ``Dedications,'' + Preserve the Title of the section, and preserve in the section all + the substance and tone of each of the contributor acknowledgements + and/or dedications given therein.@* +L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section titles.@* +M. Delete any section Entitled ``Endorsements.'' Such a section + may not be included in the Modified Version.@* +N. Do not retitle any existing section to be Entitled ``Endorsements'' + or to conflict in title with any Invariant Section.@* +O. Preserve any Warranty Disclaimers.@* +@sp 1 +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements,'' provided it contains +nothing but endorsements of your Modified Version by various +parties--for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. +@sp 1 +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements,'' +and any sections Entitled ``Dedications.'' You must delete all sections +Entitled ``Endorsements.'' +@sp 1 +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. +@sp 1 +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. +@sp 1 +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements,'' +``Dedications,'' or ``History,'' the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. +@sp 1 +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document 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. +@sp 1 +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation 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. See +http://www.gnu.org/copyleft/. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. + +@end enumerate + +@unnumberedsec ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group +Copyright (C) @var{year} @var{your name}. +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 +or any later version published by the Free Software Foundation; +with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled ``GNU +Free Documentation License.'' +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + +@smallexample +@group +with the Invariant Sections being @var{list their titles}, with the +Front-Cover Texts being @var{list}, and with the Back-Cover Texts being +@var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@ignore + arch-tag: c1679162-1d8a-4f02-bc52-2e71765f0165 +@end ignore diff --git a/doc/emacs/emacs-xtra.texi b/doc/emacs/emacs-xtra.texi new file mode 100644 index 00000000000..841c62a527f --- /dev/null +++ b/doc/emacs/emacs-xtra.texi @@ -0,0 +1,126 @@ +\input texinfo @c -*-texinfo-*- +@comment %**start of header +@setfilename ../info/emacs-xtra +@settitle Specialized Emacs Features +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex ky cp +@comment %**end of header + +@copying +This manual describes specialized features of Emacs. + +Copyright @copyright{} 2004, 2005, 2006, 2007 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Emacs-Xtra: (emacs-xtra). Specialized Emacs features. +@end direntry + +@titlepage +@title Specialized Emacs Features +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Specialized Emacs Features + +@insertcopying + +@end ifnottex + +@menu +* Introduction:: What documentation belongs here? +@iftex +* Picture Mode:: Editing pictures made up of characters using + the quarter-plane screen model. + +* Autorevert:: Auto Reverting non-file buffers. +* Subdir Switches:: Subdirectory switches in Dired. +* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. +* Emerge:: A convenient way of merging two versions of a program. +* Advanced VC Usage:: Advanced VC (version control) features. +* Fortran:: Fortran mode and its special features. +* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}). +@end iftex +* Index:: +@end menu + +@node Introduction +@unnumbered Introduction + +This manual contains detailed information about various features that +are too specialized to be included in the printed Emacs manual. It is +intended to be readable by anyone having a basic knowledge of Emacs. +However, certain sections may be intended for a more specialized +audience, such as Elisp authors. This should be clearly pointed out +at the beginning of these sections. + +Certain packages, or collections of related features, have their own +manuals, separate from the main Emacs User's manual. This manual is +intended as a complement, rather than an alternative, to reading those +additional manuals; in a nutshell, it is a collection of smaller +specialized features, too small or too obscure to justify their own +manual. + +Sections intended specifically for Elisp programmers can follow the +style of the Elisp manual. Other sections should follow the style of +the Emacs manual. + +@iftex +@c ``Picture Mode'' is a chapter, not a section, so it's outside @raisesections. +@include picture-xtra.texi + +@raisesections +@include arevert-xtra.texi + +@include dired-xtra.texi + +@include cal-xtra.texi + +@include emerge-xtra.texi + +@include vc-xtra.texi + +@include fortran-xtra.texi + +@include msdog-xtra.texi + +@lowersections +@end iftex + +@node Index +@unnumbered Index + +@printindex cp + +@bye + +@ignore + arch-tag: 75c33f13-32c6-41b6-9537-847a312e2e49 +@end ignore diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi new file mode 100644 index 00000000000..1e6fd8461c3 --- /dev/null +++ b/doc/emacs/emacs.texi @@ -0,0 +1,1365 @@ +\input texinfo + +@setfilename ../info/emacs +@settitle GNU Emacs Manual + +@c The edition number appears in several places in this file +@set EDITION Sixteenth +@set EMACSVER 23.0.50 + +@copying +This is the @value{EDITION} edition of the @cite{GNU Emacs Manual},@* +updated for Emacs version @value{EMACSVER}. + +Copyright @copyright{} 1985, 1986, 1987, 1993, 1994, 1995, 1996, 1997, +1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software +Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``The GNU Manifesto,'' ``Distribution'' and +``GNU GENERAL PUBLIC LICENSE,'' with the Front-Cover texts being ``A GNU +Manual,'' and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License.'' + +(a) The FSF's Back-Cover Text is: ``You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom.'' +@end quotation +@end copying + +@dircategory Emacs +@direntry +* Emacs: (emacs). The extensible self-documenting text editor. +@end direntry + +@c in general, keep the following line commented out, unless doing a +@c copy of this manual that will be published. The manual should go +@c onto the distribution in the full, 8.5 x 11" size. +@c set smallbook + +@ifset smallbook +@smallbook +@end ifset + +@c per rms and peterb, use 10pt fonts for the main text, mostly to +@c save on paper cost. +@c Do this inside @tex for now, so current makeinfo does not complain. +@tex +@ifset smallbook +@fonttextsize 10 +@set EMACSVER 22 +\global\let\urlcolor=\Black % don't print links in grayscale +\global\let\linkcolor=\Black +@end ifset +\global\hbadness=6666 % don't worry about not-too-underfull boxes +@end tex + +@defcodeindex op +@synindex pg cp + +@iftex +@kbdinputstyle code + +@shorttitlepage GNU Emacs Manual +@end iftex + +@titlepage +@sp 6 +@center @titlefont{GNU Emacs Manual} +@sp 4 +@center @value{EDITION} Edition, Updated for Emacs Version @value{EMACSVER}. +@sp 5 +@center Richard Stallman +@page +@vskip 0pt plus 1filll +@insertcopying + +@sp 2 +Published by the Free Software Foundation @* +51 Franklin Street, Fifth Floor @* +Boston, MA 02110-1301 USA @* +ISBN 1-882114-86-8 + +@sp 2 +Cover art by Etienne Suvasa. + +@end titlepage + + +@summarycontents +@contents + + +@ifnottex +@node Top, Distrib, (dir), (dir) +@top The Emacs Editor + +Emacs is the extensible, customizable, self-documenting real-time +display editor. This Info file describes how to edit with Emacs and +some of how to customize it; it corresponds to GNU Emacs version +@value{EMACSVER}. + +@ifinfo +To learn more about the Info documentation system, type @kbd{h}, and +Emacs will take you to a programmed instruction sequence for the Info +commands. +@end ifinfo + +For information on extending Emacs, see @ref{Top, Emacs Lisp,, elisp, The +Emacs Lisp Reference Manual}. +@end ifnottex + +@ignore +These subcategories have been deleted for simplicity +and to avoid conflicts. +Completion +Backup Files +Auto-Saving: Protection Against Disasters +Snapshots +Text Mode +Outline Mode +@TeX{} Mode +Formatted Text +Shell Command History + +The ones for Dired and Rmail have had the items turned into :: items +to avoid conflicts. +Also Running Shell Commands from Emacs +and Sending Mail and Registers and Minibuffer. +@end ignore + +@menu +* Distrib:: How to get the latest Emacs distribution. +* Copying:: The GNU General Public License gives you permission + to redistribute GNU Emacs on certain terms; + it also explains that there is no warranty. +* GNU Free Documentation License:: The license for this documentation. +* Intro:: An introduction to Emacs concepts. +* Glossary:: The glossary. +* Antinews:: Information about Emacs version 21. +* Mac OS:: Using Emacs in the Mac. +* Microsoft Windows:: Using Emacs on Microsoft Windows and MS-DOS. +* Manifesto:: What's GNU? Gnu's Not Unix! +* Acknowledgments:: Major contributors to GNU Emacs. + +Indexes (each index contains a large menu) +* Key Index:: An item for each standard Emacs key sequence. +* Option Index:: An item for every command-line option. +* Command Index:: An item for each command name. +* Variable Index:: An item for each documented variable. +* Concept Index:: An item for each concept. + +Important General Concepts +* Screen:: How to interpret what you see on the screen. +* User Input:: Kinds of input events (characters, buttons, + function keys). +* Keys:: Key sequences: what you type to request one + editing action. +* Commands:: Named functions run by key sequences to do editing. +* Text Characters:: Character set for text (the contents of buffers + and strings). +* Entering Emacs:: Starting Emacs from the shell. +* Exiting:: Stopping or killing Emacs. +* Emacs Invocation:: Hairy startup options. + +Fundamental Editing Commands +* Basic:: The most basic editing commands. +* Minibuffer:: Entering arguments that are prompted for. +* M-x:: Invoking commands by their names. +* Help:: Commands for asking Emacs about its commands. + +Important Text-Changing Commands +* Mark:: The mark: how to delimit a ``region'' of text. +* Killing:: Killing (cutting) text. +* Yanking:: Recovering killed text. Moving text. (Pasting.) +* Accumulating Text:: Other ways of copying text. +* Rectangles:: Operating on the text inside a rectangle on the screen. +* Registers:: Saving a text string or a location in the buffer. +* Display:: Controlling what text is displayed. +* Search:: Finding or replacing occurrences of a string. +* Fixit:: Commands especially useful for fixing typos. +* Keyboard Macros:: A keyboard macro records a sequence of + keystrokes to be replayed with a single command. + +Major Structures of Emacs +* Files:: All about handling files. +* Buffers:: Multiple buffers; editing several files at once. +* Windows:: Viewing two pieces of text at once. +* Frames:: Running the same Emacs session in multiple X windows. +* International:: Using non-@acronym{ASCII} character sets (the MULE features). + +Advanced Features +* Major Modes:: Text mode vs. Lisp mode vs. C mode ... +* Indentation:: Editing the white space at the beginnings of lines. +* Text:: Commands and modes for editing English. +* Programs:: Commands and modes for editing programs. +* Building:: Compiling, running and debugging programs. +* Maintaining:: Features for maintaining large programs. +* Abbrevs:: How to define text abbreviations to reduce + the number of characters you must type. +@ifnottex +* Picture Mode:: Editing pictures made up of characters using + the quarter-plane screen model. +@end ifnottex +* Sending Mail:: Sending mail in Emacs. +* Rmail:: Reading mail in Emacs. +* Dired:: You can ``edit'' a directory to manage files in it. +* Calendar/Diary:: The calendar and diary facilities. +* Gnus:: How to read netnews with Emacs. +* Shell:: Executing shell commands from Emacs. +* Emacs Server:: Using Emacs as an editing server for @code{mail}, etc. +* Printing:: Printing hardcopies of buffers or regions. +* Sorting:: Sorting lines, paragraphs or pages within Emacs. +* Narrowing:: Restricting display and editing to a portion + of the buffer. +* Two-Column:: Splitting apart columns to edit them + in side-by-side windows. +* Editing Binary Files::Using Hexl mode to edit binary files. +* Saving Emacs Sessions:: Saving Emacs state from one session to the next. +* Recursive Edit:: A command can allow you to do editing + "within the command". This is called a + "recursive editing level". +* Emulation:: Emulating some other editors with Emacs. +* Hyperlinking:: Following links in buffers. +* Dissociated Press:: Dissociating text for fun. +* Amusements:: Various games and hacks. +* Customization:: Modifying the behavior of Emacs. +* X Resources:: X resources for customizing Emacs. + +Recovery from Problems +* Quitting:: Quitting and aborting. +* Lossage:: What to do if Emacs is hung or malfunctioning. +* Bugs:: How and when to report a bug. +* Contributing:: How to contribute improvements to Emacs. +* Service:: How to get help for your own Emacs needs. + +@c Do NOT modify the following 3 lines! They must have this form to +@c be correctly identified by `texinfo-multiple-files-update'. In +@c particular, the detailed menu header line MUST be identical to the +@c value of `texinfo-master-menu-header'. See texnfo-upd.el. + +@detailmenu + --- The Detailed Node Listing --- + --------------------------------- + +Here are some other nodes which are really inferiors of the ones +already listed, mentioned here so you can get to them in one step: + +The Organization of the Screen + +* 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. + +Basic Editing Commands + +* 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. +* Basic Undo:: Undoing recent changes in the text. +* Basic Files:: Visiting, creating, and saving files. +* 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. + +The Minibuffer + +* Minibuffer File:: Entering file names with the minibuffer. +* 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. + +Completion + +* Example: Completion Example. Examples of using completion. +* Commands: Completion Commands. A list of completion commands. +* Strict Completion:: Different types of completion. +* Options: Completion Options. Options for completion. + +Help + +* 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. +* Help Mode:: Special features of Help mode and Help buffers. +* Library Keywords:: Finding Lisp libraries by keywords (topics). +* Language Help:: Help relating to international language support. +* Misc Help:: Other help commands. +* Help Files:: Commands to display pre-written help files. +* Help Echo:: Help on active text and tooltips (`balloon help') + +The Mark and the Region + +* Setting Mark:: Commands to set the mark. +* Transient Mark:: How to make Emacs highlight the region-- + when there is one. +* Momentary Mark:: Enabling Transient Mark mode momentarily. +* 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. + +Killing and Moving Text + +* 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. +* CUA Bindings:: Using @kbd{C-x}, @kbd{C-c}, @kbd{C-v} for copy + and paste, with enhanced rectangle support. + +Yanking + +* 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. + +Registers + +* RegPos:: Saving positions in registers. +* RegText:: Saving text in registers. +* RegRect:: Saving rectangles in registers. +* RegConfig:: Saving window configurations in registers. +* RegNumbers:: Numbers in registers. +* RegFiles:: File names in registers. +* Bookmarks:: Bookmarks are like registers, but persistent. + +Controlling the Display + +* Scrolling:: Moving text up and down in a window. +* Auto Scrolling:: Redisplay scrolls text automatically when needed. +* Horizontal Scrolling:: Moving text left and right in a window. +* Follow Mode:: Follow mode lets two windows scroll as one. +* Faces:: How to change the display style using faces. +* Standard Faces:: Emacs' predefined faces. +* Font Lock:: Minor mode for syntactic highlighting using faces. +* Highlight Interactively:: Tell Emacs what text to highlight. +* Fringes:: Enabling or disabling window fringes. +* Displaying Boundaries:: Displaying top and bottom of the buffer. +* Useless Whitespace:: Showing possibly-spurious trailing whitespace. +* Selective Display:: Hiding lines with lots of indentation. +* Optional Mode Line:: Optional mode line display features. +* Text Display:: How text characters are normally displayed. +* Cursor Display:: Features for displaying the cursor. +* Line Truncation:: Truncating lines to fit the screen width instead + of continuing them to multiple screen lines. +* Display Custom:: Information on variables for customizing display. + +Searching and Replacement + +* 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. +* Regexp Backslash:: Regular expression constructs starting with `\'. +* Regexp Example:: A complex regular expression explained. +* 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. + +Incremental Search + +* Basic Isearch:: Basic incremental search commands. +* Repeat Isearch:: Searching for the same string again. +* Error in Isearch:: When your string is not found. +* Special Isearch:: Special input in incremental search. +* Non-ASCII Isearch:: How to search for non-ASCII characters. +* Isearch Yank:: Commands that grab text into the search string + or else edit the search string. +* Highlight Isearch:: Isearch highlights the other possible matches. +* Isearch Scroll:: Scrolling during an incremental search. +* Slow Isearch:: Incremental search features for slow terminals. + +Replacement Commands + +* 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. + +Commands for Fixing Typos + +* Undo:: Full details of Emacs undo commands. +* 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 buffer. + +Keyboard Macros + +* Basic Keyboard Macro:: Defining and running keyboard macros. +* Keyboard Macro Ring:: Where previous keyboard macros are saved. +* Keyboard Macro Counter:: Inserting incrementing numbers in macros. +* Keyboard Macro Query:: Making keyboard macros do different things each time. +* Save Keyboard Macro:: Giving keyboard macros names; saving them in files. +* Edit Keyboard Macro:: Editing keyboard macros. +* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard + macro. + +File Handling + +* 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. +* Autorevert:: Auto Reverting non-file buffers. +* 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. +* Diff Mode:: Editing diff output. +* Misc File Ops:: Other things you can do on files. +* Compressed Files:: Accessing compressed files. +* File Archives:: Operating on tar, zip, jar etc. archive files. +* Remote Files:: Accessing files on other sites. +* Quoted File Names:: Quoting special characters in file names. +* File Name Cache:: Completion against a list of files you often use. +* File Conveniences:: Convenience Features for Finding Files. +* Filesets:: Handling sets of files. + +Saving Files + +* Save Commands:: Commands for saving files. +* Backup:: How Emacs saves the old version of your file. +* Customize Save:: Customizing the saving of files. +* Interlocking:: How Emacs protects against simultaneous editing + of one file by two users. +* File Shadowing:: Copying files to "shadows" automatically. +* Time Stamps:: Emacs can update time stamps on saved files. + +Backup Files + +* One or Many: Numbered Backups. Whether to make one backup file or many. +* Names: Backup Names. How backup files are named. +* Deletion: Backup Deletion. Emacs deletes excess numbered backups. +* Copying: Backup Copying. Backups can be made by copying or renaming. + +Auto-Saving: Protection Against Disasters + +* 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. + +Version Control + +* 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. +* Remote Repositories:: Efficient access to remote CVS servers. +* 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. + +Using Multiple Buffers + +* 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-onliness; 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. +* Buffer Convenience:: Convenience and customization features for + buffer handling. + +Multiple Windows + +* 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. +* Window Convenience:: Convenience functions for window handling. + +Frames and Graphical Displays + +* Cut and Paste:: Mouse commands for cut and paste. +* 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. +* Creating Frames:: Creating additional Emacs frames with various contents. +* Frame Commands:: Iconifying, deleting, and switching frames. +* Speedbar:: How to make and use a speedbar frame. +* 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. +* Wheeled Mice:: Using mouse wheels for scrolling. +* Drag and Drop:: Using drag and drop to open files and insert text. +* Menu Bars:: Enabling and disabling the menu bar. +* Tool Bars:: Enabling and disabling the tool bar. +* Dialog Boxes:: Controlling use of dialog boxes. +* Tooltips:: Showing "tooltips", AKA "balloon help" for active text. +* Mouse Avoidance:: Moving the mouse pointer out of the way. +* Non-Window Terminals:: Multiple frames on terminals that show only one. +* Text-Only Mouse:: Using the mouse in text-only terminals. + +International Character Set Support + +* International Chars:: 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:: Specifying a file's coding system explicitly. +* Output Coding:: Choosing coding systems for output. +* Text Coding:: Choosing conversion to use for file text. +* Communication Coding:: Coding systems for interprocess communication. +* File Name Coding:: Coding systems for file @emph{names}. +* Terminal Coding:: Specifying coding systems for converting + terminal input and output. +* Fontsets:: Fontsets are collections of fonts + that cover the whole spectrum of characters. +* Defining Fontsets:: Defining a new fontset. +* Undisplayable Characters::When characters don't display. +* Unibyte Mode:: You can pick one European character set + to use without multibyte characters. +* Charsets:: How Emacs groups its internal character codes. + +Major Modes + +* Choosing Modes:: How major modes are specified or chosen. + +Indentation + +* 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. + +Commands for Human Languages + +* 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. +* HTML Mode:: Editing HTML, SGML, and XML files. +* Nroff Mode:: Editing input to the formatter nroff. +* Formatted Text:: Editing formatted text directly in WYSIWYG fashion. +* Text Based Tables:: Editing text-based tables in WYSIWYG fashion. + +Filling Text + +* Auto Fill:: Auto Fill mode breaks long lines automatically. +* Refill:: Keeping paragraphs filled. +* 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. +* Longlines:: Editing text with very long lines. + +Outline Mode + +* 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. +* Foldout:: Folding means zooming in on outlines. + +@TeX{} Mode + +* 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. +* Misc: TeX Misc. Customization of TeX mode, and related features. + +Editing Formatted Text + +* 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. + +Editing Text-based Tables + +* Table Definition:: What is a text based table. +* Table Creation:: How to create a table. +* Table Recognition:: How to activate and deactivate tables. +* Cell Commands:: Cell-oriented commands in a table. +* Cell Justification:: Justifying cell contents. +* Row Commands:: Manipulating rows of table cell. +* Column Commands:: Manipulating columns of table cell. +* Fixed Width Mode:: Fixing cell width. +* Table Conversion:: Converting between plain text and tables. +* Measuring Tables:: Analyzing table dimension. +* Table Misc:: Table miscellany. + +Editing Programs + +* Program Modes:: Major modes for editing programs. +* Defuns:: Commands to operate on major top-level parts + of a program. +* Program Indent:: Adjusting indentation to show the nesting. +* Parentheses:: Commands that operate on parentheses. +* Comments:: Inserting, killing, and aligning comments. +* Documentation:: Getting documentation of functions you plan to call. +* Hideshow:: Displaying blocks selectively. +* Symbol Completion:: Completion on symbol names of your program or language. +* Glasses:: Making identifiersLikeThis more readable. +* Misc for Programs:: Other Emacs features useful for editing programs. +* C Modes:: Special commands of C, C++, Objective-C, + Java, and Pike modes. +* Asm Mode:: Asm mode and its special features. +* Fortran:: Fortran mode and its special features. + +Top-Level Definitions, or Defuns + +* Left Margin Paren:: An open-paren or similar opening delimiter + starts a defun if it is at the left margin. +* Moving by Defuns:: Commands to move over or mark a major definition. +* Imenu:: Making buffer indexes as menus. +* Which Function:: Which Function mode shows which function you are in. + +Indentation for Programs + +* 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. + +Commands for Editing with Parentheses + +* Expressions:: Expressions with balanced parentheses. +* Moving by Parens:: Commands for moving up, down and across + in the structure of parentheses. +* Matching:: Insertion of a close-delimiter flashes matching open. + +Manipulating Comments + +* Comment Commands:: Inserting, killing, and aligning comments. +* Multi-Line Comments:: Commands for adding and editing multi-line comments. +* Options for Comments::Customizing the comment features. + +Documentation Lookup + +* Info Lookup:: Looking up library functions and commands + in Info files. +* Man Page:: Looking up man pages of library functions and commands. +* Lisp Doc:: Looking up Emacs Lisp functions, etc. + +C and Related Modes + +* Motion in C:: Commands to move by C statements, etc. +* Electric C:: Colon and other chars can automatically reindent. +* Hungry Delete:: A more powerful DEL command. +* Other C Commands:: Filling comments, viewing expansion of macros, + and other neat features. + +Compiling and Testing Programs + +* Compilation:: Compiling programs in languages other + than Lisp (C, Pascal, etc.). +* Compilation Mode:: The mode for visiting compiler errors. +* Compilation Shell:: Customizing your shell properly + for use in the compilation buffer. +* Grep Searching:: Searching with grep. +* Flymake:: Finding syntax errors on the fly. +* Debuggers:: Running symbolic debuggers for non-Lisp programs. +* Executing Lisp:: Various modes for editing Lisp programs, + with different facilities for running + the Lisp programs. +* Lisp Libraries:: Creating Lisp programs to run in Emacs. +* Lisp Eval:: Executing a single Lisp expression in Emacs. +* Lisp Interaction:: Executing Lisp in an Emacs buffer. +* External Lisp:: Communicating through Emacs with a separate Lisp. + +Running Debuggers Under Emacs + +* 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. +* GDB Graphical Interface:: An enhanced mode that uses GDB features to + implement a graphical debugging environment through + Emacs. + +Maintaining Large Programs + +* Change Log:: Maintaining a change history for your program. +* Format of ChangeLog:: What the change log file looks like. +* 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. + +Tags Tables + +* Tag Syntax:: Tag syntax for various types of code and text files. +* Create Tags Table:: Creating a tags table with @code{etags}. +* Etags Regexps:: Create arbitrary tags using regular expressions. +* 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. + +Abbrevs + +* 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. + +@ifnottex +Editing Pictures + +* 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 ifnottex + +Sending Mail + +* Mail Format:: Format of the mail being composed. +* Mail Headers:: Details of permitted mail header fields. +* Mail Aliases:: Abbreviating and grouping mail addresses. +* Mail Mode:: Special commands for editing mail being composed. +* Mail Amusements:: Distract the NSA's attention; add a fortune to a msg. +* Mail Methods:: Using alternative mail-composition methods. + +Reading Mail with Rmail + +* Rmail Basics:: Basic concepts of Rmail, and simple use. +* Rmail Scrolling:: Scrolling through a message. +* Rmail Motion:: Moving to another message. +* Rmail Deletion:: Deleting and expunging messages. +* Rmail Inbox:: How mail gets into the Rmail file. +* Rmail Files:: Using multiple Rmail files. +* Rmail Output:: Copying message out to files. +* Rmail Labels:: Classifying messages by labeling them. +* Rmail Attributes:: Certain standard labels, called attributes. +* Rmail Reply:: Sending replies to messages you are viewing. +* Rmail Summary:: Summaries show brief info on many messages. +* Rmail Sorting:: Sorting messages in Rmail. +* Rmail Display:: How Rmail displays a message; customization. +* Rmail Coding:: How Rmail handles decoding character sets. +* Rmail Editing:: Editing message text and headers in Rmail. +* Rmail Digest:: Extracting the messages from a digest message. +* Out of Rmail:: Converting an Rmail file to mailbox format. +* Rmail Rot13:: Reading messages encoded in the rot13 code. +* Movemail:: More details of fetching new mail. +* Remote Mailboxes:: Retrieving Mail from Remote Mailboxes. +* Other Mailbox Formats:: Retrieving Mail from Local Mailboxes in + Various Formats + +Dired, the Directory Editor + +* Dired Enter:: How to invoke Dired. +* Dired Navigation:: How to move in the Dired buffer. +* Dired Deletion:: Deleting files with Dired. +* Flagging Many Files:: Flagging files based on their names. +* 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. +* Subdir Switches:: Subdirectory switches in Dired. +* Subdirectory Motion:: Moving across subdirectories, and up and down. +* Hiding Subdirectories:: Making subdirectories visible or invisible. +* Dired Updating:: Discarding lines for files of no interest. +* Dired and Find:: Using `find' to choose the files for Dired. +* Wdired:: Operating on files by editing the Dired buffer. +* Image-Dired:: Viewing image thumbnails in Dired +* Misc Dired Features:: Various other features. + +The Calendar and the Diary + +* 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. +* Writing Calendar Files:: Writing calendars to files of various formats. +* 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. +* Importing Diary:: Converting diary events to/from other formats. +* Daylight Saving:: How to specify when daylight saving time is active. +* Time Intervals:: Keeping track of time intervals. +* Advanced Calendar/Diary Usage:: Advanced Calendar/Diary customization. + +Movement in the Calendar + +* 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. + +Conversion To and From Other Calendars + +* 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. + +The Diary + +* Displaying the Diary:: 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. + +Gnus + +* 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. + +Running Shell Commands from Emacs + +* 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. +* Shell Prompts:: Two ways to recognize shell prompts. +* Shell History:: Repeating previous commands in a shell buffer. +* Directory Tracking:: Keeping track when the subshell changes directory. +* Shell Options:: Options for customizing Shell mode. +* Terminal emulator:: An Emacs window as a terminal emulator. +* Term Mode:: Special Emacs commands used in Term mode. +* Paging in Term:: Paging in the terminal emulator. +* Remote Host:: Connecting to another computer. + +Using Emacs as a Server + +* Invoking emacsclient:: Emacs client startup options. + +Printing Hard Copies + +* PostScript:: Printing buffers or regions as PostScript. +* PostScript Variables:: Customizing the PostScript printing commands. +* Printing Package:: An optional advanced printing interface. + +Hyperlinking and Navigation Features + +* Browse-URL:: Following URLs. +* Goto-address:: Activating URLs. +* FFAP:: Finding files etc. at point. + +Customization + +* Minor Modes:: Each minor mode is one feature you can turn on + independently of any others. +* Easy Customization:: Convenient way to browse and change user options. +* Variables:: Many Emacs commands examine Emacs variables + to decide what to do; by setting variables, + you can control their functioning. +* Key Bindings:: The keymaps say what command each key runs. + By changing them, you can "redefine keys". +* Syntax:: The syntax table controls how words and + expressions are parsed. +* Init File:: How to write common customizations in the + @file{.emacs} file. + +Variables + +* Examining:: Examining or setting one variable's value. +* 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. + +Customizing Key Bindings + +* 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. +* 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. + +The Init File, @file{~/.emacs} + +* 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. +* Init Non-ASCII:: Using non-@acronym{ASCII} characters in an init file. + +Dealing with Emacs Trouble + +* DEL Does Not Delete:: 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. +* 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. + +Reporting Bugs + +* 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. + +Command Line Arguments for Emacs Invocation + +* 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:: Choosing display colors. +* 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. +* Misc X:: Other display options. + +Environment Variables + +* General Variables:: Environment variables that all versions of Emacs use. +* Misc Variables:: Certain system specific variables. +* MS-Windows Registry:: An alternative to the environment on MS-Windows. + +X Options and Resources + +* Resources:: Using X resources with Emacs (in general). +* Table of Resources:: Table of specific X resources that affect Emacs. +* Face Resources:: X resources for customizing faces. +* Lucid Resources:: X resources for Lucid menus. +* LessTif Resources:: X resources for LessTif and Motif menus. +* GTK resources:: Resources for GTK widgets. + +Emacs and Mac OS + +* Mac Input:: Keyboard and mouse input on Mac. +* Mac International:: International character sets on Mac. +* Mac Environment Variables:: Setting environment variables for Emacs. +* Mac Directories:: Volumes and directories on Mac. +* Mac Font Specs:: Specifying fonts on Mac. +* Mac Functions:: Mac-specific Lisp functions. + +Emacs and Microsoft Windows/MS-DOS + +* Text and Binary:: Text files use CRLF to terminate lines. +* Windows Files:: File-name conventions on Windows. +* ls in Lisp:: Emulation of @code{ls} for Dired. +* Windows HOME:: Where Emacs looks for your @file{.emacs}. +* Windows Keyboard:: Windows-specific keyboard features. +* Windows Mouse:: Windows-specific mouse features. +* Windows Processes:: Running subprocesses on Windows. +* Windows Printing:: How to specify the printer on MS-Windows. +* Windows Misc:: Miscellaneous Windows features. +* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}). +@end detailmenu +@end menu + +@iftex +@unnumbered Preface + + This manual documents the use and simple customization of the Emacs +editor. Simple Emacs customizations do not require you to be a +programmer, but if you are not interested in customizing, you can +ignore the customization hints. + + This is primarily a reference manual, but can also be used as a +primer. If you are new to Emacs, we recommend you start with +the on-line, learn-by-doing tutorial, before reading the manual. To +run the tutorial, start Emacs and type @kbd{C-h t}. The tutorial +describes commands, tells you when to try them, and explains the +results. + + On first reading, just skim chapters 1 and 2, which describe the +notational conventions of the manual and the general appearance of the +Emacs display screen. Note which questions are answered in these +chapters, so you can refer back later. After reading chapter 4, you +should practice the commands shown there. The next few chapters +describe fundamental techniques and concepts that are used constantly. +You need to understand them thoroughly, so experiment with them +until you are fluent. + + Chapters 14 through 19 describe intermediate-level features that are +useful for many kinds of editing. Chapter 20 and following chapters +describe optional but useful features; read those chapters when you +need them. + + Read the Trouble chapter if Emacs does not seem to be working +properly. It explains how to cope with several common problems +(@pxref{Lossage}), as well as when and how to report Emacs bugs +(@pxref{Bugs}). + + To find the documentation of a particular command, look in the index. +Keys (character commands) and command names have separate indexes. +There is also a glossary, with a cross reference for each term. + + This manual is available as a printed book and also as an Info file. +The Info file is for on-line perusal with the Info program, which is +the principal means of accessing on-line documentation in the GNU +system. Both the Emacs Info file and an Info reader are included with +GNU Emacs. The Info file and the printed book contain substantially +the same text and are generated from the same source files, which are +also distributed with GNU Emacs. + + GNU Emacs is a member of the Emacs editor family. There are many +Emacs editors, all sharing common principles of organization. For +information on the underlying philosophy of Emacs and the lessons +learned from its development, see @cite{Emacs, the Extensible, +Customizable Self-Documenting Display Editor}, available from +@url{ftp://publications.ai.mit.edu/ai-publications/pdf/AIM-519A.pdf}. + +This edition of the manual is intended for use with GNU Emacs +installed on GNU and Unix systems. GNU Emacs can also be used on VMS, +MS-DOS (also called MS-DOG), Microsoft Windows, and Macintosh systems. +Those systems use different file name syntax; in addition, VMS and +MS-DOS do not support all GNU Emacs features. @xref{Microsoft +Windows}, for information about using Emacs on Windows. +@xref{Mac OS}, for information about using Emacs on Macintosh. We +don't try to describe VMS usage in this manual. +@end iftex + +@node Distrib, Intro, Top, Top +@unnumbered Distribution + +GNU Emacs is @dfn{free software}; this means that everyone is free to +use it and free to redistribute it on certain conditions. GNU Emacs +is not in the public domain; it is copyrighted and there are +restrictions on its distribution, but these restrictions are designed +to permit everything that a good cooperating citizen would want to do. +What is not allowed is to try to prevent others from further sharing +any version of GNU Emacs that they might get from you. The precise +conditions are found in the GNU General Public License that comes with +Emacs and also appears in this manual@footnote{This manual is itself +covered by the GNU Free Documentation License. This license is +similar in spirit to the General Public License, but is more suitable +for documentation. @xref{GNU Free Documentation License}.}. +@xref{Copying}. + +One way to get a copy of GNU Emacs is from someone else who has it. +You need not ask for our permission to do so, or tell any one else; +just copy it. If you have access to the Internet, you can get the +latest distribution version of GNU Emacs by anonymous FTP; see +@url{http://www.gnu.org/software/emacs} on our website for more +information. + +You may also receive GNU Emacs when you buy a computer. Computer +manufacturers are free to distribute copies on the same terms that apply to +everyone else. These terms require them to give you the full sources, +including whatever changes they may have made, and to permit you to +redistribute the GNU Emacs received from them under the usual terms of the +General Public License. In other words, the program must be free for you +when you get it, not just free for the manufacturer. + +You can also order copies of GNU Emacs from the Free Software +Foundation. This is a convenient and reliable way to get a copy; it is +also a good way to help fund our work. We also sell hardcopy versions +of this manual and @cite{An Introduction to Programming in Emacs Lisp}, +by Robert J. Chassell. You can find an order form on our web site at +@url{http://www.gnu.org/order/order.html}. For further information, +write to + +@display +Free Software Foundation +51 Franklin Street, Fifth Floor +Boston, MA 02110-1301 +USA +@end display + +The income from distribution fees goes to support the foundation's +purpose: the development of new free software, and improvements to our +existing programs including GNU Emacs. + +If you find GNU Emacs useful, please @strong{send a donation} to the +Free Software Foundation to support our work. Donations to the Free +Software Foundation are tax deductible in the US. If you use GNU Emacs +at your workplace, please suggest that the company make a donation. If +company policy is unsympathetic to the idea of donating to charity, you +might instead suggest ordering a CD-ROM from the Foundation +occasionally, or subscribing to periodic updates. + +@iftex +@node Acknowledgments, Intro, Distrib, Top +@unnumberedsec Acknowledgments + +Contributors to GNU Emacs include Jari Aalto, Per Abrahamsen, Tomas +Abrahamsson, Jay K.@: Adams, Michael Albinus, Nagy Andras, Ralf +Angeli, Joe Arceneaux, Miles Bader, David Bakhash, Juanma Barranquero, +Eli Barzilay, Steven L.@: Baur, Jay Belanger, Alexander L.@: Belikoff, +Boaz Ben-Zvi, Karl Berry, Anna M.@: Bigatti, Ray Blaak, Jim Blandy, Johan Bockg@aa{}rd, +Per Bothner, Terrence Brannon, Frank Bresz, Peter Breton, Emmanuel +Briot, Kevin Broadey, Vincent Broman, David M.@: Brown, Georges +Brun-Cottan, Joe Buehler, W@l{}odek Bzyl, Bill Carpenter, Per +Cederqvist, Hans Chalupsky, Chris Chase, Bob Chassell, Andrew Choi, +Sacha Chua, James Clark, Mike Clarkson, Glynn Clements, Andrew +Csillag, Doug Cutting, Mathias Dahl, Satyaki Das, Michael DeCorte, +Gary Delp, Matthieu Devin, Eri Ding, Jan Dj@"{a}rv, Carsten Dominik, +Scott Draves, Benjamin Drieu, Viktor Dukhovni, John Eaton, Rolf Ebert, +Paul Eggert, Stephen Eglen, Torbj@"orn Einarsson, Tsugutomo Enami, +Hans Henrik Eriksen, Michael Ernst, Ata Etemadi, Frederick Farnbach, +Oscar Figueiredo, Fred Fish, Karl Fogel, Gary Foster, Romain +Francoise, Noah Friedman, Andreas Fuchs, Hallvard Furuseth, Keith +Gabryelski, Peter S.@: Galbraith, Kevin Gallagher, Kevin Gallo, Juan +Le@'{o}n Lahoz Garc@'{@dotless{i}}a, Howard Gayle, Stephen Gildea, Julien +Gilles, David Gillespie, Bob Glickstein, Deepak Goel, Boris Goldowsky, +Michelangelo Grigni, Odd Gripenstam, Kai Gro@ss{}johann, Michael +Gschwind, Henry Guillaume, Doug Gwyn, Ken'ichi Handa, Lars Hansen, +Chris Hanson, K. Shane Hartman, John Heidemann, Jon K.@: Hellan, +Jesper Harder, Markus Heritsch, Karl Heuer, Manabu Higashida, Anders +Holst, Jeffrey C.@: Honig, Kurt Hornik, Tom Houlder, Joakim Hove, +Denis Howe, Lars Ingebrigtsen, Andrew Innes, Seiichiro Inoue, Pavel +Janik, Paul Jarc, Ulf Jasper, Michael K. Johnson, Kyle Jones, Terry +Jones, Simon Josefsson, Arne J@o{}rgensen, Tomoji Kagatani, Brewster +Kahle, Lute Kamstra, David Kastrup, David Kaufman, Henry Kautz, Taichi +Kawabata, Howard Kaye, Michael Kifer, Richard King, Peter Kleiweg, +Shuhei Kobayashi, Pavel Kobiakov, Larry K.@: Kolodney, David M.@: +Koppelman, Koseki Yoshinori, Robert Krawitz, Sebastian Kremer, Ryszard +Kubiak, Geoff Kuenning, David K@aa{}gedal, Daniel LaLiberte, Mario +Lang, Aaron Larson, James R.@: Larus, Vinicius Jose Latorre, Werner +Lemberg, Frederic Lepied, Peter Liljenberg, Lars Lindberg, Chris +Lindblad, Anders Lindgren, Thomas Link, Juri Linkov, Francis Litterio, +Emilio C. Lopes, Dave Love, Sascha L@"{u}decke, Eric Ludlam,Alan +Mackenzie, Christopher J.@: Madsen, Neil M.@: Mager, Ken Manheimer, +Bill Mann, Brian Marick, Simon Marshall, Bengt Martensson, Charlie +Martin, Thomas May, Roland McGrath, Will Mengarini, David Megginson, +Ben A. Mesander, Wayne Mesard, Brad Miller, Lawrence Mitchell, Richard +Mlynarik, Gerd Moellmann, Stefan Monnier, Morioka Tomohiko, Keith +Moore, Glenn Morris, Diane Murray, Sen Nagata, Erik Naggum, Thomas +Neumann, Thien-Thi Nguyen, Mike Newton, Jurgen Nickelsen, Dan +Nicolaescu, Hrvoje Niksic, Jeff Norden, Andrew Norman, Alexandre +Oliva, Bob Olson, Michael Olson, Takaaki Ota, Pieter E.@: J.@: Pareit, +David Pearson, Jeff Peck, Damon Anton Permezel, Tom Perrine, William +M.@: Perry, Per Persson, Jens Petersen, Daniel Pfeiffer, Richard L.@: +Pieri, Fred Pierresteguy, Christian Plaunt, David Ponce, Francesco +A.@: Potorti, Michael D. Prange, Mukesh Prasad, Ken Raeburn, Marko +Rahamaa, Ashwin Ram, Eric S. Raymond, Paul Reilly, Edward M. Reingold, +Alex Rezinsky, Rob Riepel, David Reitter, Nick Roberts, Roland B.@: +Roberts, John Robinson, Danny Roozendaal, William Rosenblatt, +Guillermo J.@: Rozas, Martin Rudalics, Ivar Rummelhoff, Jason Rumney, +Wolfgang Rupprecht, Kevin Ryde, James B. Salem, Masahiko Sato, Jorgen +Schaefer, Holger Schauer, William Schelter, Ralph Schleicher, Gregor +Schmid, Michael Schmidt, Ronald S. Schnell, Philippe Schnoebelen, Jan +Schormann, Alex Schroeder, Stephen Schoef, Raymond Scholz, Randal +Schwartz, Oliver Seidel, Manuel Serrano, Hovav Shacham, Stanislav +Shalunov, Marc Shapiro, Richard Sharman, Olin Shivers, Espen Skoglund, +Rick Sladkey, Lynn Slater, Chris Smith, David Smith, Paul D.@: Smith, +Andre Spiegel, Michael Staats, William Sommerfeld, Michael Staats, +Reiner Steib, Sam Steingold, Ake Stenhoff, Peter Stephenson, Ken +Stevens, Jonathan Stigelman, Martin Stjernholm, Kim F.@: Storm, Steve +Strassman, Olaf Sylvester, Naoto Takahashi, Steven Tamm, Jean-Philippe +Theberge, Jens T.@: Berger Thielemann, Spencer Thomas, Jim Thompson, +Luc Teirlinck, Tom Tromey, Enami Tsugutomo, Eli Tziperman, Daiki Ueno, +Masanobu Umeda, Rajesh Vaidheeswarran, Neil W.@: Van Dyke, Didier +Verna, Ulrik Vieth, Geoffrey Voelker, Johan Vromans, Inge Wallin, John +Paul Wallington, Colin Walters, Barry Warsaw, Morten Welinder, Joseph +Brian Wells, Rodney Whitby, John Wiegley, Ed Wilkinson, Mike Williams, +Bill Wohler, Steven A. Wood, Dale R.@: Worley, Francis J.@: Wright, +Felix S. T. Wu, Tom Wurgler, Katsumi Yamaoka, Masatake Yamato, +Jonathan Yavner, Ryan Yeske, Chong Yidong, Ilya Zakharevich, Milan +Zamazal, Victor Zandy, Eli Zaretskii, Jamie Zawinski, Shenghuo Zhu, +Ian T.@: Zimmermann, Reto Zimmermann, Neal Ziring, Teodor Zlatanov, +and Detlev Zundel. +@end iftex + +@node Intro, Glossary, Distrib, Top +@unnumbered Introduction + + You are reading about GNU Emacs, the GNU incarnation of the +advanced, self-documenting, customizable, extensible editor Emacs. +(The `G' in `GNU' is not silent.) + + We call Emacs advanced because it provides much more than simple +insertion and deletion. It can control subprocesses, indent programs +automatically, show two or more files at once, and edit formatted +text. Emacs editing commands operate in terms of characters, words, +lines, sentences, paragraphs, and pages, as well as expressions and +comments in various programming languages. + + @dfn{Self-documenting} means that at any time you can type a special +character, @kbd{Control-h}, to find out what your options are. You can +also use it to find out what any command does, or to find all the commands +that pertain to a topic. @xref{Help}. + + @dfn{Customizable} means that you can alter Emacs commands' behavior +in simple ways. For example, if you use a programming language in +which comments start with @samp{<**} and end with @samp{**>}, you can +tell the Emacs comment manipulation commands to use those strings +(@pxref{Comments}). Another sort of customization is rearrangement of +the command set. For example, you can rebind the basic cursor motion +commands (up, down, left and right) to any keys on the keyboard that +you find comfortable. @xref{Customization}. + + @dfn{Extensible} means that you can go beyond simple customization +and write entirely new commands---programs in the Lisp language to be +run by Emacs's own Lisp interpreter. Emacs is an ``on-line +extensible'' system, which means that it is divided into many +functions that call each other, any of which can be redefined in the +middle of an editing session. Almost any part of Emacs can be +replaced without making a separate copy of all of Emacs. Most of the +editing commands of Emacs are written in Lisp; the few exceptions +could have been written in Lisp but use C instead for efficiency. +Writing an extension is programming, but non-programmers can use it +afterwards. @xref{Top, Emacs Lisp Intro, Preface, eintr, An +Introduction to Programming in Emacs Lisp}, if you want to learn Emacs +Lisp programming. + + When running on a graphical display, Emacs provides its own menus +and convenient handling of mouse buttons. In addition, Emacs provides +many of the benefits of a graphical display even on a text-only +terminal. For instance, it can highlight parts of a file, display and +edit several files at once, move text between files, and edit files +while running shell commands. + +@include screen.texi +@include commands.texi +@include entering.texi +@include basic.texi +@include mini.texi +@include m-x.texi +@include help.texi +@include mark.texi +@include killing.texi +@include regs.texi +@include display.texi +@include search.texi +@include fixit.texi +@include kmacro.texi +@include files.texi +@include buffers.texi +@include windows.texi +@include frames.texi +@include mule.texi +@include major.texi +@include indent.texi +@include text.texi +@include programs.texi +@include building.texi +@include maintaining.texi +@include abbrevs.texi +@ifnottex +@include picture-xtra.texi +@end ifnottex +@include sending.texi +@include rmail.texi +@include dired.texi +@include calendar.texi +@include misc.texi +@include custom.texi +@include trouble.texi + +@node Copying, GNU Free Documentation License, Service, Top +@appendix GNU GENERAL PUBLIC LICENSE +@include gpl.texi + +@node GNU Free Documentation License, Emacs Invocation, Copying, Top +@appendix GNU Free Documentation License +@include doclicense.texi + +@include cmdargs.texi +@include xresources.texi + +@include anti.texi +@include macos.texi +@include msdog.texi +@include gnu.texi +@include glossary.texi +@ifnottex +@include ack.texi +@end ifnottex + +@c The Option Index is produced only in the on-line version, +@c because the index entries related to command-line options +@c tend to point to the same pages and all begin with a dash. +@c This, and the need to keep the node links consistent, are +@c the reasons for the funky @iftex/@ifnottex dance below. +@c The Option Index is _not_ before Key Index, because that +@c would require changes in the glossary.texi's @node line. +@c It is not after Concept Index for similar reasons. + +@iftex +@node Key Index, Command Index, Glossary, Top +@unnumbered Key (Character) Index +@printindex ky +@end iftex + +@ifnottex +@node Key Index, Option Index, Glossary, Top +@unnumbered Key (Character) Index +@printindex ky + +@node Option Index, Command Index, Key Index, Top +@unnumbered Command-Line Options Index +@printindex op + +@node Command Index, Variable Index, Option Index, Top +@unnumbered Command and Function Index +@printindex fn +@end ifnottex + +@iftex +@node Command Index, Variable Index, Key Index, Top +@unnumbered Command and Function Index +@printindex fn +@end iftex + +@node Variable Index, Concept Index, Command Index, Top +@unnumbered Variable Index +@printindex vr + +@node Concept Index, Acknowledgments, Variable Index, Top +@unnumbered Concept Index +@printindex cp + +@bye + +@ignore + arch-tag: ed48740a-410b-46ea-9387-c9a9252a3392 +@end ignore diff --git a/doc/emacs/emerge-xtra.texi b/doc/emacs/emerge-xtra.texi new file mode 100644 index 00000000000..e78f17e59d6 --- /dev/null +++ b/doc/emacs/emerge-xtra.texi @@ -0,0 +1,414 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@c +@c This file is included either in emacs-xtra.texi (when producing the +@c printed version) or in the main Emacs manual (for the on-line version). +@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. For other ways to compare files, see +@iftex +@ref{Comparing Files,,, emacs, the Emacs Manual}, +@end iftex +@ifnottex +@ref{Comparing Files}, +@end ifnottex +and @ref{Top, Ediff,, 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. +@iftex +@xref{Narrowing,,, emacs, the Emacs Manual}. +@end iftex +@ifnottex +@xref{Narrowing}. +@end ifnottex + + + 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 (@pxref{Merge Commands}). +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}. +@iftex +@xref{Hooks,,, emacs, the Emacs Manual}. +@end iftex +@ifnottex +@xref{Hooks}. +@end ifnottex + +@ignore + arch-tag: cda63f09-9c5f-4ea1-adb9-4a820fdfb24e +@end ignore diff --git a/doc/emacs/entering.texi b/doc/emacs/entering.texi new file mode 100644 index 00000000000..e338a6a8619 --- /dev/null +++ b/doc/emacs/entering.texi @@ -0,0 +1,170 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 2001, 2002, 2003, +@c 2004, 2005, 2006, 2007 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 +@command{emacs}. Emacs clears the screen, then displays an initial +help message and copyright notice. Some operating systems discard +your type-ahead when Emacs starts up; they give Emacs no way to +prevent this. On those systems, wait for Emacs to clear the screen +before you start typing. + + From a shell window under the X Window System, run Emacs in the +background with @command{emacs&}. This way, Emacs won't tie up the +shell window, so you can use it to run other shell commands while +Emacs is running. You can type Emacs commands as soon as you direct +your keyboard input to an Emacs frame. + +@vindex initial-major-mode + When Emacs starts up, it creates 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. You can also ignore that capability and just write notes +there. 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 through Emacs command-line +arguments. @xref{Emacs Invocation}. The feature exists mainly for +compatibility with other editors, and for scripts. + + Many editors are designed to edit one file. When done with that +file, you exit the editor. The next time you want to edit a file, you +must start the editor again. Working this way, it is convenient to +use a command-line argument to say which file to edit. + + However, killing Emacs after editing one each and starting it afresh +for the next file is both unnecessary and harmful, since it denies you +the full power of Emacs. Emacs can visit more than one file in a +single editing session, and that is the right way to use it. Exiting +the Emacs session loses valuable accumulated context, such as the kill +ring, registers, undo history, and mark ring. These features are +useful for operating on multiple files, or even continuing to edit one +file. If you kill Emacs after each file, you don't take advantage of +them. + + 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 edit a file, you visit it with the existing Emacs, which +eventually has many files in it ready for editing. Usually you do not +kill Emacs until you are about to log out. @xref{Files}, for more +information on visiting more than one file. + + To edit a file from another program while Emacs is running, you can +use the @command{emacsclient} helper program to open a file in the +already running Emacs. @xref{Emacs Server}. + +@ifnottex +@raisesections +@end ifnottex + +@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, and three kinds of +exiting: @dfn{iconifying} Emacs, @dfn{suspending} Emacs, and +@dfn{killing} Emacs. + + @dfn{Iconifying} means replacing the Emacs frame with a small box or +``icon'' on the screen. This is the usual way to exit Emacs when +you're using a graphical display---if you bother to ``exit'' at all. +(Just switching to another application is usually sufficient.) + + @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. This is the usual way to +exit Emacs when running it on a text terminal. + + @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 iconify-or-deiconify-frame + On graphical displays, @kbd{C-z} runs the command +@code{iconify-or-deiconify-frame}, which temporarily iconifies (or +``minimizes'') the selected Emacs frame (@pxref{Frames}). You can +then use the window manager to select some other application. (You +could select another application without iconifying Emacs first, but +getting the Emacs frame out of the way can make it more convenient to +find the other application.) + +@findex suspend-emacs + On a text terminal, @kbd{C-z} runs the command @code{suspend-emacs}. +Suspending Emacs takes you back to the shell from which you invoked +Emacs. You can resume Emacs with the shell command @command{%emacs} +in most common shells. On systems that don't support suspending +programs, @kbd{C-z} starts an inferior shell that communicates +directly with the terminal, and Emacs waits until you exit the +subshell. (The way to do that is probably with @kbd{C-d} or +@command{exit}, but it depends on which shell you use.) On these +systems, you can only get back to the shell from which Emacs was run +(to log out, for example) when you kill Emacs. + +@vindex cannot-suspend + Suspending can fail if you run Emacs under a shell that doesn't +support suspendion of its subjobs, 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. + +@kindex C-x C-c +@findex save-buffers-kill-emacs + To exit and kill Emacs, type @kbd{C-x C-c} +(@code{save-buffers-kill-emacs}). A two-character key is used to make +it harder to type by accident. This command first offers to save any +modified file-visiting buffers. If you do not save them all, it asks +for confirmation with @kbd{yes} before killing Emacs, since any +changes not saved now 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 also kill the subprocesses. + +@vindex confirm-kill-emacs + If the value of the variable @code{confirm-kill-emacs} is +non-@code{nil}, @kbd{C-x C-c} assumes that its value is a predicate +function, and calls that function. If the result is non-@code{nil}, the +session is killed, otherwise Emacs continues to run. One convenient +function to use as the value of @code{confirm-kill-emacs} is the +function @code{yes-or-no-p}. The default value of +@code{confirm-kill-emacs} is @code{nil}. + + You can't resume an Emacs session after killing it. Emacs can, +however, record certain session information when you kill it, such as +which files you visited, so the next time you start Emacs it will try +to visit the same files. @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}). + +@ifnottex +@lowersections +@end ifnottex + +@ignore + arch-tag: df798d8b-f253-4113-b585-f528f078a944 +@end ignore diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi new file mode 100644 index 00000000000..7ba36916684 --- /dev/null +++ b/doc/emacs/files.texi @@ -0,0 +1,2950 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, +@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Files, Buffers, Keyboard Macros, 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. +@ifnottex +* Autorevert:: Auto Reverting non-file buffers. +@end ifnottex +* 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. +* Diff Mode:: Mode for editing file differences. +* Misc File Ops:: Other things you can do on files. +* Compressed Files:: Accessing compressed files. +* File Archives:: Operating on tar, zip, jar etc. archive files. +* Remote Files:: Accessing files on other sites. +* Quoted File Names:: Quoting special characters in file names. +* File Name Cache:: Completion against a list of files you often use. +* File Conveniences:: Convenience Features for Finding Files. +* Filesets:: Handling sets of files. +@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 +(@pxref{Completion}) to make it easier to specify long file names. When +completing file names, Emacs ignores those whose file-name extensions +appear in the variable @code{completion-ignored-extensions}; see +@ref{Completion Options}. + + 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 which is 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. + +@findex cd +@findex pwd + The command @kbd{M-x pwd} displays 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 it visits. 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. + + For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} +then the default directory is normally @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}. + +@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}. + +@cindex home directory shorthand + You can use @file{~/} in a file name to mean your home directory, +or @file{~@var{user-id}/} to mean the home directory of a user whose +login name is @code{user-id}@footnote{ +On MS-Windows and MS-DOS systems, where a user doesn't have a home +directory, Emacs replaces @file{~/} with the value of the +environment variable @code{HOME}; see @ref{General Variables}. On +these systems, the @file{~@var{user-id}/} construct is supported only +for the current user, i.e., only if @var{user-id} is the current +user's login name.}. + +@cindex environment variables in file names +@cindex expansion of environment variables +@cindex @code{$} in file names + @anchor{File Names with $}@samp{$} in a file name is used to +substitute an environment variable. The environment variable name +consists of all the alphanumeric characters after the @samp{$}; +alternatively, it can be enclosed in braces after the @samp{$}. For +example, if you have used the shell command @command{export +FOO=rms/hacks} to set up an environment variable named @env{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}. If the environment +variable is not defined, no substitution occurs: @file{/u/$notdefined} +stands for itself (assuming the environment variable @env{notdefined} +is not defined). + + Note that shell commands to set environment variables affect Emacs +only when done before Emacs is started. + + To access a file with @samp{$} in its name, if the @samp{$} causes +expansion, type @samp{$$}. This pair is converted to a single +@samp{$} at the same time as variable substitution is performed for a +single @samp{$}. Alternatively, quote the whole file name with +@samp{/:} (@pxref{Quoted File Names}). File names which begin with a +literal @samp{~} should also be quoted with @samp{/:}. + +@findex substitute-in-file-name + The Lisp function that performs the @samp{$}-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-@acronym{ASCII} characters in file names if you set the +variable @code{file-name-coding-system} to a non-@code{nil} value. +@xref{File Name Coding}. + +@node Visiting +@section Visiting Files +@cindex visiting files +@cindex open file + +@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 saving files + @dfn{Visiting} a file means reading its contents into an Emacs +buffer so you can edit them. Emacs makes a new buffer for each file +that you visit. We often say that this buffer ``is visiting'' that +file, or that the buffer's ``visited file'' is that file. 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, Emacs constructs a unique +name---the normal method is to append @samp{<2>}, @samp{<3>}, and so +on, but you can select other methods (@pxref{Uniquify}). + + 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 +permanent place, 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}. File-name completion ignores certain file names; for more +about this, see @ref{Completion Options}. + + 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 you could not +create it, or exists but you can't read it, 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 whether the file itself has changed +since you visited or saved it last. If the file has changed, Emacs offers +to reread it. + +@vindex large-file-warning-threshold +@cindex maximum buffer size exceeded, error message + If you try to visit a file larger than +@code{large-file-warning-threshold} (the default is 10000000, which is +about 10 megabytes), Emacs will ask you for confirmation first. You +can answer @kbd{y} to proceed with visiting the file. Note, however, +that Emacs cannot visit files that are larger than the maximum Emacs +buffer size, which is around 256 megabytes on 32-bit machines +(@pxref{Buffers}). If you try, Emacs will display an error message +saying that the maximum buffer size has been exceeded. + +@cindex file selection dialog + On graphical displays there are two additional methods for +visiting files. Firstly, when Emacs is built with a suitable GUI +toolkit, commands invoked with the mouse (by clicking on the menu bar +or tool bar) use the toolkit's standard File Selection dialog instead +of prompting for the file name in the minibuffer. On Unix and +GNU/Linux platforms, Emacs does that when built with GTK, LessTif, and +Motif toolkits; on MS-Windows and Mac, the GUI version does that by default. +For information on how to customize this, see @ref{Dialog Boxes}. + + Secondly, Emacs supports ``drag and drop''; dropping a file into an +ordinary Emacs window visits the file using that window. However, +dropping a file into a window displaying a Dired buffer moves or +copies the file into the displayed directory. For details, see +@ref{Drag and Drop}, and @ref{Misc Dired Features}. + +@cindex creating files + What if you want to create a new file? Just visit it. Emacs displays +@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 end-of-line +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 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 view, delete, +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. + + Files which are actually collections of other files, or @dfn{file +archives}, are visited in special modes which invoke a Dired-like +environment to allow operations on archive members. @xref{File +Archives}, for more about these features. + +@cindex wildcard characters in file names +@vindex find-file-wildcards + If the file name you specify contains shell-style wildcard +characters, Emacs visits all the files that match it. (On +case-insensitive filesystems, Emacs matches the wildcards disregarding +the letter case.) Wildcards include @samp{?}, @samp{*}, and +@samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file +name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted +File Names}, for information on how to visit a file whose name +actually contains wildcard characters. You can disable the wildcard +feature by customizing @code{find-file-wildcards}. + + If you visit a file that the operating system won't let you modify, +or that is marked read-only, Emacs makes the buffer read-only too, 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{toggle-read-only}). @xref{Misc Buffer}. + +@kindex C-x C-r +@findex find-file-read-only + If you want to visit a file as read-only in order to protect +yourself from entering changes accidentally, visit it with the command +@kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}. + +@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 +@kbd{C-x C-v} 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. + +@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 @acronym{ASCII} 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}), and +does not add a final newline because of @code{require-final-newline}. +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-hook +@vindex find-file-not-found-functions + 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-functions}; 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{-functions} rather than @samp{-hook} +to indicate that fact. + + Successful visiting of any file, whether existing or not, calls the +functions in the list @code{find-file-hook}, with no arguments. +This variable is a normal hook. In the case of a nonexistent file, the +@code{find-file-not-found-functions} 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. + +@menu +* Save Commands:: Commands for saving files. +* Backup:: How Emacs saves the old version of your file. +* Customize Save:: Customizing the saving of files. +* Interlocking:: How Emacs protects against simultaneous editing + of one file by two users. +* Shadowing: File Shadowing. Copying files to "shadows" automatically. +* Time Stamps:: Emacs can update time stamps on saved files. +@end menu + +@node Save Commands +@subsection Commands for Saving Files + + These are the commands that relate to saving and writing files. + +@table @kbd +@item C-x C-s +Save the current buffer in its visited file on disk (@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}). +With prefix argument (@kbd{C-u}), mark the current buffer as changed. +@item C-x C-w +Save the current buffer with a specified file name (@code{write-file}). +@item M-x set-visited-file-name +Change the file 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 d +Diff the buffer against its corresponding file, so you can see +what changes you would be saving. +@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.) You can also kill the buffer. + +@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 marks the buffer as visiting that file name, and +changes the buffer name correspondingly. @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 +equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s} +(except that @kbd{C-x C-w} asks for confirmation if the file exists). +@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 (@pxref{File Names}). + + 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}. + +@node Backup +@subsection Backup Files +@cindex backup file +@vindex make-backup-files +@vindex vc-make-backup-files + + 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. +@iftex +@xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}. +@end iftex +@ifnottex +@xref{General VC Options}. +@end ifnottex + + + At your option, Emacs can keep either a single backup for each file, +or make a series of numbered backup files for each file that you edit. + +@vindex backup-enable-predicate +@vindex temporary-file-directory +@vindex small-temporary-file-directory + The default value of the @code{backup-enable-predicate} variable +prevents backup files being written for files in the directories used +for temporary files, specified by @code{temporary-file-directory} or +@code{small-temporary-file-directory}. + + 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 +* One or Many: Numbered Backups. Whether to make one backup file or many. +* Names: Backup Names. How backup files are named. +* Deletion: Backup Deletion. Emacs deletes excess numbered backups. +* Copying: Backup Copying. Backups can be made by copying or renaming. +@end menu + +@node Numbered Backups +@subsubsection Numbered Backups + +@vindex version-control + The choice of single backup file or multiple numbered backup files +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 +Never make numbered backups; always make single backups. +@end table + +@noindent +The usual way to set this variable is globally, through your +@file{.emacs} file or the customization buffer. However, 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 @env{VERSION_CONTROL} environment variable + If you set the environment variable @env{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 Names +@subsubsection Single or Numbered Backups + + When Emacs makes a single backup file, its name is normally +constructed by appending @samp{~} to the file name being edited; thus, +the backup file for @file{eval.c} would be @file{eval.c~}. + +@vindex make-backup-file-name-function +@vindex backup-directory-alist + You can change this behavior by defining the variable +@code{make-backup-file-name-function} to a suitable function. +Alternatively you can customize the variable +@code{backup-directory-alist} to specify that files matching certain +patterns should be backed up in specific directories. + + A typical use is to add an element @code{("." . @var{dir})} to make +all backups in the directory with absolute name @var{dir}; Emacs +modifies the backup file names to avoid clashes between files with the +same names originating in different directories. Alternatively, +adding, say, @code{("." . ".~")} would make backups in the invisible +subdirectory @file{.~} of the original file's directory. Emacs +creates the directory, if necessary, to make the backup. + + If access control stops Emacs from writing backup files under the usual +names, it writes the backup file as @file{%backup%~} in your home +directory. Only one such file can exist, so only the most recently +made such backup is available. + + If you choose to have a series of numbered backup files, backup file +names contain @samp{.~}, the number, and another @samp{~} after 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, all the way +through names like @file{eval.c.~259~} and beyond. The variable +@code{backup-directory-alist} applies to numbered backups just as +usual. + +@node Backup Deletion +@subsubsection Automatic Deletion of Backups + + To prevent excessive 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. The backups in the middle (excluding those oldest +and newest) are the excess middle versions---those backups are +deleted. These variables' values are used when it is time to delete +excess versions, just after a new backup version is made; the 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 @code{t}, Emacs deletes the excess +backup files silently. If it is @code{nil}, the default, Emacs asks +you whether it should delete the excess backup versions. If it has +any other value, then Emacs never automatically deletes backups. + + 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 (hard +links). 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 +@vindex backup-by-copying-when-privileged-mismatch +@cindex file ownership, and backup +@cindex backup, and user-id + The choice of renaming or copying is controlled by four 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. The fourth variable, +@code{backup-by-copying-when-privileged-mismatch}, gives the highest +numeric user-id for which @code{backup-by-copying-when-mismatch} will be +forced on. This is useful when low-numbered user-ids are assigned to +special system users, such as @code{root}, @code{bin}, @code{daemon}, +etc., which must maintain ownership of files. + + 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 Customize Save +@subsection Customizing Saving of Files + +@vindex require-final-newline + If the value of the variable @code{require-final-newline} is +@code{t}, saving or writing a file silently puts a newline at the end +if there isn't already one there. If the value is @code{visit}, Emacs +adds a newline at the end of any file that doesn't have one, just +after it visits the file. (This marks the buffer as modified, and you +can undo it.) If the value is @code{visit-save}, that means to add +newlines both on visiting and on saving. If the value is @code{nil}, +Emacs leaves the end of the file unchanged; if it's neither @code{nil} +nor @code{t}, Emacs asks you whether to add a newline. The default is +@code{nil}. + +@vindex mode-require-final-newline + Many major modes are designed for specific kinds of files that are +always supposed to end in newlines. These major modes set the +variable @code{require-final-newline} according to +@code{mode-require-final-newline}. By setting the latter variable, +you can control how these modes handle final newlines. + +@vindex write-region-inhibit-fsync + When Emacs saves a file, it invokes the @code{fsync} system call to +force the data immediately out to disk. This is important for safety +if the system crashes or in case of power outage. However, it can be +disruptive on laptops using power saving, because it requires the disk +to spin up each time you save a file. Setting +@code{write-region-inhibit-fsync} to a non-@code{nil} value disables +this synchronization. Be careful---this means increased risk of data +loss. + +@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 buffer +contents remain unchanged---the modification you were trying to make +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 +displays 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 File Shadowing +@subsection Shadowing Files +@cindex shadow files +@cindex file shadows +@findex shadow-initialize + +@table @kbd +@item M-x shadow-initialize +Set up file shadowing. +@item M-x shadow-define-literal-group +Declare a single file to be shared between sites. +@item M-x shadow-define-regexp-group +Make all files that match each of a group of files be shared between hosts. +@item M-x shadow-define-cluster @key{RET} @var{name} @key{RET} +Define a shadow file cluster @var{name}. +@item M-x shadow-copy-files +Copy all pending shadow files. +@item M-x shadow-cancel +Cancel the instruction to shadow some files. +@end table + +You can arrange to keep identical @dfn{shadow} copies of certain files +in more than one place---possibly on different machines. To do this, +first you must set up a @dfn{shadow file group}, which is a set of +identically-named files shared between a list of sites. The file +group is permanent and applies to further Emacs sessions as well as +the current one. Once the group is set up, every time you exit Emacs, +it will copy the file you edited to the other files in its group. You +can also do the copying without exiting Emacs, by typing @kbd{M-x +shadow-copy-files}. + +To set up a shadow file group, use @kbd{M-x +shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}. +See their documentation strings for further information. + +Before copying a file to its shadows, Emacs asks for confirmation. +You can answer ``no'' to bypass copying of this file, this time. If +you want to cancel the shadowing permanently for a certain file, use +@kbd{M-x shadow-cancel} to eliminate or change the shadow file group. + +A @dfn{shadow cluster} is a group of hosts that share directories, so +that copying to or from one of them is sufficient to update the file +on all of them. Each shadow cluster has a name, and specifies the +network address of a primary host (the one we copy files to), and a +regular expression that matches the host names of all the other hosts +in the cluster. You can define a shadow cluster with @kbd{M-x +shadow-define-cluster}. + +@node Time Stamps +@subsection Updating Time Stamps Automatically +@cindex time stamps +@cindex modification dates +@cindex locale, date format + +You can arrange to put a time stamp in a file, so that it will be updated +automatically each time you edit and save the file. The time stamp +has to be in the first eight lines of the file, and you should +insert it like this: + +@example +Time-stamp: <> +@end example + +@noindent +or like this: + +@example +Time-stamp: " " +@end example + +@findex time-stamp + Then add the hook function @code{time-stamp} to the hook +@code{before-save-hook}; that hook function will automatically update +the time stamp, inserting the current date and time when you save the +file. You can also use the command @kbd{M-x time-stamp} to update the +time stamp manually. For other customizations, see the Custom group +@code{time-stamp}. Note that non-numeric fields in the time stamp are +formatted according to your locale setting (@pxref{Environment}). + +@node Reverting +@section Reverting a Buffer +@findex revert-buffer +@cindex drastic changes +@cindex reread a file + + 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} tries to position point in such a way that, if +the file was edited only slightly, you will be at approximately the +same piece of text after reverting as before. However, if you have made +drastic changes, point may wind up in 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.) + +@cindex Global Auto-Revert mode +@cindex mode, Global Auto-Revert +@cindex Auto-Revert mode +@cindex mode, Auto-Revert +@findex global-auto-revert-mode +@findex auto-revert-mode +@findex auto-revert-tail-mode + + You may find it useful to have Emacs revert files automatically when +they change. Three minor modes are available to do this. + + @kbd{M-x global-auto-revert-mode} enables Global Auto-Revert mode, +which periodically checks all file buffers and reverts when the +corresponding file has changed. @kbd{M-x auto-revert-mode} enables a +local version, Auto-Revert mode, which applies only to the current +buffer. + + You can use Auto-Revert mode to ``tail'' a file such as a system +log, so that changes made to that file by other programs are +continuously displayed. To do this, just move the point to the end of +the buffer, and it will stay there as the file contents change. +However, if you are sure that the file will only change by growing at +the end, use Auto-Revert Tail mode instead +(@code{auto-revert-tail-mode}). It is more efficient for this. + +@vindex auto-revert-interval + The variable @code{auto-revert-interval} controls how often to check +for a changed file. Since checking a remote file is too slow, these +modes do not check or revert remote files. + + @xref{VC Mode Line}, for Auto Revert peculiarities in buffers that +visit files under version control. + +@ifnottex +@include arevert-xtra.texi +@end ifnottex + +@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, it considers +each buffer, and each is auto-saved if auto-saving is enabled 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 rear of buffer name, then +adding digits and letters at the end for uniqueness. For +example, the @samp{*mail*} buffer in which you compose messages to be +sent might be auto-saved in a file named @file{#*mail*#704juu}. 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. + +@cindex auto-save for remote files +@vindex auto-save-file-name-transforms + The variable @code{auto-save-file-name-transforms} allows a degree +of control over the auto-save file name. It lets you specify a series +of regular expressions and replacements to transform the auto save +file name. The default value puts the auto-save files for remote +files (@pxref{Remote Files}) into the temporary file directory on the +local machine. + + 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-mode}. + +@vindex auto-save-visited-file-name + If you want auto-saving to be done in the visited file rather than +in a separate auto-save file, set the variable +@code{auto-save-visited-file-name} to a non-@code{nil} value. In this +mode, there is no real 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. (You can inhibit this by setting 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. Emacs doesn't accept values that are +too small: if you customize @code{auto-save-interval} to a value less +than 20, Emacs will behave as if the value is 20. + +@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 + Emacs records information about interrupted sessions for later +recovery in files named +@file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}. All +of this name except the @file{@var{pid}-@var{hostname}} part comes +from the value of @code{auto-save-list-file-prefix}. You can record +sessions in a different place by customizing that variable. 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 +@cindex symbolic links (visiting) +@cindex hard links (visiting) + + 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. + +@vindex find-file-existing-other-name +@vindex find-file-suppress-same-file-warnings + + Normally, if you visit a file which Emacs is already visiting under +a different name, Emacs displays a message in the echo area and uses +the existing buffer visiting that file. This can happen on systems +that support hard or symbolic links, or if you use a long file name on +a system that truncates long file names, or on a case-insensitive file +system. You can suppress the message by setting the variable +@code{find-file-suppress-same-file-warnings} to a non-@code{nil} +value. You can disable this feature entirely by setting the variable +@code{find-file-existing-other-name} to @code{nil}: then if you visit +the same file under two different names, you get a separate buffer for +each file name. + +@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 different version control systems---currently, it supports CVS, +GNU Arch, RCS, Meta-CVS, Subversion, and SCCS. Of these, the GNU +project distributes CVS, GNU Arch, and RCS; we recommend that you use +either CVS or GNU Arch for your projects, and RCS for individual +files. We also have free software to replace SCCS, known as CSSC; if +you are using SCCS and don't want to make the incompatible change to +RCS or CVS, you can switch to CSSC. + + VC is enabled by default in Emacs. To disable it, set the +customizable variable @code{vc-handled-backends} to @code{nil} +@iftex +(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). +@end iftex +@ifnottex +(@pxref{Customizing VC}). +@end ifnottex + + +@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. +@ifnottex +* Remote Repositories:: Efficient access to remote CVS servers. +* 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 ifnottex +@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 +* Why Version Control?:: Understanding the problems it addresses +* Version Systems:: Supported version control back-end systems. +* VC Concepts:: Words and concepts related to version control. +* Types of Log File:: The per-file VC log in contrast to the ChangeLog. +@end menu + +@node Why Version Control? +@subsubsection Understanding the problems it addresses + + Version control systems provide you with three important capabilities: +reversibility, concurrency, and history. + + The most basic capability you get from a version-control system is +reversibility, the ability to back up to a saved, known-good state when +you discover that some modification you did was a mistake or a bad idea. + + Version-control systems also support concurrency, the ability to +have many people modifying the same collection of code or documents +knowing that conflicting modifications can be detected and resolved. + + Version-control systems give you the capability to attach a history +to your data, explanatory comments about the intention behind each +change to it. Even for a programmer working solo change histories +are an important aid to memory; for a multi-person project they +become a vitally important form of communication among developers. + +@node Version Systems +@subsubsection Supported Version Control Systems + +@cindex back end (version control) + VC currently works with six different version control systems or +``back ends'': CVS, GNU Arch, RCS, Meta-CVS, Subversion, and SCCS. + +@cindex CVS + CVS is a free version control system that is used for the majority +of free software projects today. It allows concurrent multi-user +development either locally or over the network. Some of its +shortcomings, corrected by newer systems such as GNU Arch, are that it +lacks atomic commits or support for renaming files. VC supports all +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 GNU Arch +@cindex Arch + GNU Arch is a new version control system that is designed for +distributed work. It differs in many ways from old well-known +systems, such as CVS and RCS. It supports different transports for +interoperating between users, offline operations, and it has good +branching and merging features. It also supports atomic commits, and +history of file renaming and moving. VC does not support all +operations provided by GNU Arch, so you must sometimes invoke it from +the command line, or use a specialized module. + +@cindex RCS + RCS is the free version control system around which VC was initially +built. The VC commands are therefore conceptually closest to RCS. +Almost everything you can do with RCS can be done through VC. You +cannot use RCS over the network though, and it only works at the level +of individual files, rather than projects. You should use it if you +want a simple, yet reliable tool for handling individual files. + +@cindex SVN +@cindex Subversion + Subversion is a free version control system designed to be similar +to CVS but without CVS's problems. Subversion supports atomic commits, +and versions directories, symbolic links, meta-data, renames, copies, +and deletes. It can be used via http or via its own protocol. + +@cindex MCVS +@cindex Meta-CVS + Meta-CVS is another attempt to solve problems arising in CVS. It +supports directory structure versioning, improved branching and +merging, and use of symbolic links and meta-data in repositories. + +@cindex SCCS + SCCS is a proprietary but widely used version control system. In +terms of capabilities, it is the weakest of the six 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. Since SCCS is +non-free, not respecting its users freedom, you should not use it; +use its free replacement CSSC instead. But you should use CSSC only +if for some reason you cannot use RCS, or one of the higher-level +systems such as CVS or GNU Arch. + +In the following, we discuss mainly RCS, SCCS and CVS. Nearly +everything said about CVS applies to GNU Arch, Subversion and Meta-CVS +as well. + +@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. + + To go beyond these basic concepts, you will need to understand three +ways in which version-control systems can differ from each other. They +can be locking or merging; they can be file-based or changeset-based; +and they can be centralized or decentralized. VC handles all these +choices, but they lead to differing behaviors which you will need +to understand as you use it. + +@cindex locking versus merging + 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). In a locking +system, such as SCCS, you must @dfn{lock} a file before you start to +edit it. The other method is @dfn{merging}; the system tries 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. + + By contrast, a merging system lets each user check out and modify a +work file at any time. When you check in a a file, the system will +attempt to merge your changes with any others checked into the +repository since you checked out the file. + + Both locking and merging systems can have problems when multiple users +try to modify the same file at the same time. Locking systems have +@dfn{lock conflicts}; a user may try to check a file out and be unable +to because it is locked. In merging systems, @dfn{merge conflicts} +happen when you check in a change to a file that conflicts with a change +checked in by someone else after your checkout. Both kinds of conflict +have to be resolved by human judgment and communication. + + SCCS always uses locking. RCS is lock-based by default but can be told +to operate in a merging style. CVS is merge-based by default but can +be told to operate in a locking mode. Most later version-control +systems, such as Subversion and GNU Arch, have been fundamentally +merging-based rather than locking-based. This is because experience +has shown that the merging-based approach is generally superior to +the locking one, both in convenience to developers and in minimizing +the number and severity of conflicts that actually occur. + + While it is rather unlikely that anyone will ever again build a +fundamentally locking-based rather than merging-based version-control +system in the future, merging-based version-systems sometimes have locks +retrofitted onto them for reasons having nothing to do with technology. +@footnote{Usually the control-freak instincts of managers.} For this +reason, and to support older systems still in use, VC mode supports +both locking and merging version control and tries to hide the differences +between them as much as possible. + +@cindex files versus changesets. + On SCCS, RCS, CVS, and other early version-control systems, checkins +and other operations are @dfn{file-based}; each file has its own +@dfn{master file} with its own comment- and revision history separate +from that of all other files in the system. Later systems, beginning +with Subversion, are @dfn{changeset-based}; a checkin may include +changes to several files and that change set is treated as a unit by the +system. Any comment associated with the change doesn't belong to any +one file, but is attached to the changeset itself. + + Changeset-based version control is in general both more flexible and +more powerful than file-based version control; usually, when a change to +multiple files has to be backed out, it's good to be able to easily +identify and remove all of it. + +@cindex centralized vs. decentralized + Early version-control systems were designed around a @dfn{centralized} +model in which each project has only one repository used by all +developers. SCCS, RCS, CVS, and Subversion share this kind of model. +It has two important problems. One is that a single repository is a +single point of failure---if the repository server is down all work +stops. The other is that you need to be connected live to the server to +do checkins and checkouts; if you're offline, you can't work. + + Newer version-control systems like GNU Arch are @dfn{decentralized}. +A project may have several different repositories, and these systems +support a sort of super-merge between repositories that tries to +reconcile their change histories. At the limit, each developer has +his/her own repository, and repository merges replace checkin/commit +operations. + + VC's job is to help you manage the traffic between your personal +workfiles and a repository. Whether that repository is a single master +or one of a network of peer repositories is not something VC has to care +about. Thus, the difference between a centralized and a decentralized +version-control system is invisible to VC mode. + +@iftex +(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}). +@end iftex +@ifnottex +(@pxref{CVS Options}). +@end ifnottex + + +@node Types of Log File +@subsubsection Types of Log File +@cindex types of log file +@cindex log File, types of +@cindex version control log + + Projects that use a revision control system can have @emph{two} +types of log for changes. One is the per-file log maintained by the +revision control system: each time you check in a change, you must +fill out a @dfn{log entry} for the change (@pxref{Log Buffer}). This +kind of log is called the @dfn{version control log}, also the +@dfn{revision control log}, @dfn{RCS log}, or @dfn{CVS log}. + + The other kind of log is the file @file{ChangeLog} (@pxref{Change +Log}). It provides a chronological record of all changes to a large +portion of a program---typically one directory and its subdirectories. +A small program would use one @file{ChangeLog} file; a large program +may well merit a @file{ChangeLog} file in each major directory. +@xref{Change Log}. + + A project maintained with version control can use just the per-file +log, or it can use both kinds of logs. It can handle some files one +way and some files the other way. Each project has its policy, which +you should follow. + + When the policy is to use both, you typically want to write an entry +for each change just once, then put it into both logs. You can write +the entry in @file{ChangeLog}, then copy it to the log buffer when you +check in the change. Or you can write the entry in the log buffer +while checking in the change, and later use the @kbd{C-x v a} command +to copy it to @file{ChangeLog} +@iftex +(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). +@end iftex +@ifnottex +(@pxref{Change Logs and VC}). +@end ifnottex + + +@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}. + +@vindex auto-revert-check-vc-info + When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is +under version control, it updates the version control information in +the mode line. However, Auto Revert mode may not properly update this +information if the version control status changes without changes to +the work file, from outside the current Emacs session. If you set +@code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates +the version control status information every +@code{auto-revert-interval} seconds, even if the work file itself is +unchanged. The resulting CPU usage depends on the version control +system, but is usually not excessive. + +@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 +@itemx C-x v v +Perform the next logical version control operation on this file. +@end table + +@findex vc-next-action +@kindex 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. + +@findex vc-toggle-read-only +@kindex C-x C-q @r{(Version Control)} + As a special convenience that is particularly useful for files with +locking, you can let Emacs check a file in or out whenever you change +its read-only flag. This means, for example, that you cannot +accidentally edit a file without properly checking it out first. To +achieve this, bind the key @kbd{C-x C-q} to @kbd{vc-toggle-read-only} +in your @file{~/.emacs} file. (@xref{Init Rebinding}.) + +@menu +* VC with Locking:: RCS in its default mode, SCCS, and optionally CVS. +* Without Locking:: Without locking: default mode for CVS. +* Advanced C-x v v:: Advanced features available with a prefix argument. +* 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 v v} can either lock a file or check it in: + +@itemize @bullet +@item +If the file is not locked, @kbd{C-x v v} 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 v v} 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 v v} releases the lock and makes the file read-only +again. + +@item +If the file is locked by some other user, @kbd{C-x v v} 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 v v} 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. You must do this before you can check in your own changes. (To +pick up any recent changes from the master file @emph{without} trying +to commit your own changes, type @kbd{C-x v m @key{RET}}.) +@xref{Merging}. + +@item +If there are no new changes in the master file, but you have made +modifications in your work file, @kbd{C-x v v} 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 v v} 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 that 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 v v} with an unmodified file locks the +file, just as it does with RCS in its normal (locking) mode. + +@node Advanced C-x v v +@subsubsection Advanced Control in @kbd{C-x v v} + +@cindex version number to check in/out + When you give a prefix argument to @code{vc-next-action} (@kbd{C-u +C-x v v}), it still performs the next logical version control +operation, but accepts additional arguments to specify precisely how +to do the operation. + +@itemize @bullet +@item +If the file is modified (or locked), you can specify the version +number to use for the new version that you check in. This is one way +to create a new branch (@pxref{Branches}). + +@item +If the file is not modified (and unlocked), you can specify the +version to select; this lets you start working from an older version, +or on another branch. If you do not enter any version, that takes you +to the highest version on the current branch; therefore @kbd{C-u C-x +v v @key{RET}} is a convenient way to get the latest version of a file from +the repository. + +@item +@cindex specific version control system +Instead of the version number, you can also specify the name of a +version control system. This is useful when one file is being managed +with two version control systems at the same time +@iftex +(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs +Features}). +@end iftex +@ifnottex +(@pxref{Local Version Control}). +@end ifnottex + +@end itemize + +@node Log Buffer +@subsubsection Features of the Log Entry Buffer + + When you check in changes, @kbd{C-x v v} first reads a log entry. It +pops up a buffer called @samp{*VC-Log*} for you to enter the log entry. + + Sometimes the @samp{*VC-Log*} buffer contains default text when you enter it, +typically the last log message entered. If it does, mark and point +are set around the entire contents of the buffer so that it is easy to +kill the contents of the buffer with @kbd{C-w}. + +@findex log-edit-insert-changelog + If you work by writing entries in the @file{ChangeLog} +(@pxref{Change Log}) and then commit the change under revision +control, you can generate the Log Edit text from the ChangeLog using +@kbd{C-c C-a} (@kbd{log-edit-insert-changelog}). This looks for +entries for the file(s) concerned in the top entry in the ChangeLog +and uses those paragraphs as the log text. This text is only inserted +if the top entry was made under your user name on the current date. +@iftex +@xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}, +@end iftex +@ifnottex +@xref{Change Logs and VC}, +@end ifnottex +for the opposite way of working---generating ChangeLog entries from +the revision control log. + + In the @samp{*VC-Log*} buffer, @kbd{C-c C-f} (@kbd{M-x +log-edit-show-files}) shows the list of files to be committed in case +you need to check that. (This can be a list of more than one file if +you use VC Dired mode or PCL-CVS. +@iftex +@xref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}, +@end iftex +@ifnottex +@xref{VC Dired Mode}, +@end ifnottex +and @ref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs +Front-End to CVS}.) + + When you have finished editing the log message, type @kbd{C-c C-c} to +exit the buffer and commit the change. + + 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 master version from which +you started editing. + +@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 file with per-line version information and using colors. +@end table + +@findex vc-version-other-window +@kindex C-x v ~ + To examine an old version in its entirety, 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 = + It is usually 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 master version from which you started editing the +file (this is not necessarily the latest 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. +Both forms display the output in a special buffer in another window. + + 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 +@iftex +(@pxref{Snapshots,,,emacs-xtra, Specialized Emacs Features}) +@end iftex +@ifnottex +(@pxref{Snapshots}) +@end ifnottex +instead of one or both version numbers. + + 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. + +@vindex vc-diff-switches +@vindex vc-rcs-diff-switches + @kbd{C-x v =} works by running a variant of the @code{diff} utility +designed to work with the version control system in use. When you +invoke @code{diff} this way, in addition to the options specified by +@code{diff-switches} (@pxref{Comparing Files}), it receives those +specified by @code{vc-diff-switches}, plus those specified for the +specific back end by @code{vc-@var{backend}-diff-switches}. For +instance, when the version control back end is RCS, @code{diff} uses +the options in @code{vc-rcs-diff-switches}. The +@samp{vc@dots{}diff-switches} variables are @code{nil} by default. + + The buffer produced by @kbd{C-x v =} supports the commands of +Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and +@kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always +find the corresponding locations in the current work file. (Older +versions are not, in general, present as files on your disk.) + +@findex vc-annotate +@kindex C-x v g + For some back ends, you can display the file @dfn{annotated} with +per-line version information and using colors to enhance the visual +appearance, with the command @kbd{M-x vc-annotate}. It creates a new +buffer (the ``annotate buffer'') displaying the file's text, with each +part colored to show how old it is. Text colored red is new, blue means +old, and intermediate colors indicate intermediate ages. By default, +the color is scaled over the full range of ages, such that the oldest +changes are blue, and the newest changes are red. + + When you give a prefix argument to this command, it uses the +minibuffer to read two arguments: which version number to display and +annotate (instead of the current file contents), and the time span in +days the color range should cover. + + From the annotate buffer, these and other color scaling options are +available from the @samp{VC-Annotate} menu. In this buffer, you can +also use the following keys to browse the annotations of past revisions, +view diffs, or view log entries: + +@table @kbd +@item P +Annotate the previous revision, that is to say, the revision before +the one currently annotated. A numeric prefix argument is a repeat +count, so @kbd{C-u 10 P} would take you back 10 revisions. + +@item N +Annotate the next revision---the one after the revision currently +annotated. A numeric prefix argument is a repeat count. + +@item J +Annotate the revision indicated by the current line. + +@item A +Annotate the revision before the one indicated by the current line. +This is useful to see the state the file was in before the change on +the current line was made. + +@item D +Display the diff between the current line's revision and the previous +revision. This is useful to see what the current line's revision +actually changed in the file. + +@item L +Show the log of the current line's revision. This is useful to see +the author's description of the changes in the revision on the current +line. + +@item W +Annotate the workfile version--the one you are editing. If you used +@kbd{P} and @kbd{N} to browse to other revisions, use this key to +return to your current version. +@end table + +@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:: Canceling changes before or after check-in. +@ifnottex +* VC Dired Mode:: Listing files managed by version control. +* VC Dired Commands:: Commands to use in a VC Dired buffer. +@end ifnottex +@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 + + To register the file, Emacs must choose which version control system +to use for it. If the file's directory already contains files +registered in a version control system, Emacs uses that system. If +there is more than one system in use for a directory, Emacs uses the +one that appears first in @code{vc-handled-backends} +@iftex +(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). +@end iftex +@ifnottex +(@pxref{Customizing VC}). +@end ifnottex +On the other hand, if there are no files already registered, Emacs uses +the first system from @code{vc-handled-backends} that could register +the file (for example, you cannot register a file under CVS if its +directory is not already part of a CVS tree); with the default value +of @code{vc-handled-backends}, this means that Emacs uses RCS in this +situation. + + If locking is in use, @kbd{C-x v i} leaves the file unlocked and +read-only. Type @kbd{C-x v v} 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 v v}. Until you do that, the version +appears as @samp{@@@@} in the mode line. + +@vindex vc-default-init-version +@cindex initial version number to register + 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. The point is centered at the +revision of the file that is currently being visited. + + In the change log buffer, you can use the following keys to move +between the logs of revisions and of files, to view past revisions, and +to view diffs: + +@table @kbd +@item p +Move to the previous revision-item in the buffer. (Revision entries in the log +buffer are usually in reverse-chronological order, so the previous +revision-item usually corresponds to a newer revision.) A numeric +prefix argument is a repeat count. + +@item n +Move to the next revision-item (which most often corresponds to the +previous revision of the file). A numeric prefix argument is a repeat +count. + +@item P +Move to the log of the previous file, when the logs of multiple files +are in the log buffer +@iftex +(@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}). +@end iftex +@ifnottex +(@pxref{VC Dired Mode}). +@end ifnottex +Otherwise, just move to the beginning of the log. A numeric prefix +argument is a repeat count, so @kbd{C-u 10 P} would move backward 10 +files. + +@item N +Move to the log of the next file, when the logs of multiple files are +in the log buffer +@iftex +(@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}). +@end iftex +@ifnottex +(@pxref{VC Dired Mode}). +@end ifnottex +It also takes a numeric prefix argument as a repeat count. + +@item f +Visit the revision indicated at the current line, like typing @kbd{C-x +v ~} and specifying this revision's number (@pxref{Old Versions}). + +@item d +Display the diff (@pxref{Comparing Files}) between the revision +indicated at the current line and the next earlier revision. This is +useful to see what actually changed when the revision indicated on the +current line was committed. +@end table + +@node VC Undo +@subsubsection Undoing Version Control Actions + +@table @kbd +@item C-x v u +Revert the buffer and the file to the version from which you started +editing the file. + +@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 +version from which you started editing the file, 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 with respect to the master 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, but only if your work file corresponds +to that version---you cannot use @kbd{C-x v c} to cancel a version +that is not the latest on its branch. @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 +@iftex +(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). +@end iftex +@ifnottex +(@pxref{Version Headers}). +@end ifnottex +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. + +@ifnottex +@c vc1-xtra.texi needs extra level of lowering. +@lowersections +@include vc1-xtra.texi +@raisesections +@end ifnottex + +@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 not supported for SCCS. + + 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 v v} 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 v v}, and make whatever changes you want. Then, +when you check in the changes, use @kbd{C-u C-x v v}. 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 v v}. 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 v v} 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 +v v}. 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 firsts asks you in the +minibuffer where the changes should come from. If you just type +@key{RET}, Emacs merges any changes that were made on the same branch +since you checked the file out (we call this @dfn{merging the news}). +This is the common way to pick up recent changes from the repository, +regardless of whether you have already changed the file yourself. + + You can also enter a branch number or a pair of version numbers in +the minibuffer. Then @kbd{C-x v m} finds the changes from that +branch, or the differences 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 v v +@key{RET}}. Version 1.5 is now current. If locking is used for the file, +type @kbd{C-x v v} to lock version 1.5 so that you can change it. Next, +type @kbd{C-x v m 1.3.1 @key{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. Don't forget to +check in the merged version afterwards. + +@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 +@iftex +(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). +@end iftex +@ifnottex +(@pxref{Version Headers}). +@end ifnottex +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 v v} and specify the correct +branch number. This ensures that Emacs knows which branch it is using +during this particular editing session. + +@ifnottex +@include vc2-xtra.texi +@end ifnottex + +@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). Emacs also includes a directory browser +feature 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} displays 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 owners (like +@samp{ls -l}). + +@vindex list-directory-brief-switches +@vindex list-directory-verbose-switches + The text of a directory listing is mostly 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). + +@vindex directory-free-space-program +@vindex directory-free-space-args + In verbose directory listings, Emacs adds information about the +amount of free space on the disk that contains the directory. To do +this, it runs the program specified by +@code{directory-free-space-program} with arguments +@code{directory-free-space-args}. + +@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}. The value of @code{diff-switches} should be a +string; the default is @code{"-c"} to specify a context diff. +@xref{Top,, Diff, diff, Comparing and Merging Files}, for more +information about @command{diff} output formats. + +@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. (For more information +about windows in Emacs, @ref{Windows}.) Comparison starts at point in +each window, after pushing each initial point value on the mark ring +in its respective buffer. Then it moves point forward in each window, +one character at a time, until it reaches characters that don't match. +Then the command exits. + + If point in the two windows is followed by non-matching text when +the command starts, @kbd{M-x compare-windows} tries heuristically to +advance up to matching text in the two windows, and then exits. So if +you use @kbd{M-x compare-windows} repeatedly, each time it either +skips one matching range or finds the start of another. + +@vindex compare-ignore-case +@vindex compare-ignore-whitespace + With a numeric argument, @code{compare-windows} ignores changes in +whitespace. If the variable @code{compare-ignore-case} is +non-@code{nil}, the comparison ignores differences in case as well. +If the variable @code{compare-ignore-whitespace} is non-@code{nil}, +@code{compare-windows} normally ignores changes in whitespace, and a +prefix argument turns that off. + +@cindex Smerge mode +@findex smerge-mode +@cindex failed merges +@cindex merges, failed +@cindex comparing 3 files (@code{diff3}) + You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor +mode for editing output from the @command{diff3} program. This is +typically the result of a failed merge from a version control system +``update'' outside VC, due to conflicting changes to a file. Smerge +mode provides commands to resolve conflicts by selecting specific +changes. + +@iftex +@xref{Emerge,,, emacs-xtra, Specialized Emacs Features}, +@end iftex +@ifnottex +@xref{Emerge}, +@end ifnottex +for the Emerge facility, which provides a powerful interface for +merging files. + +@node Diff Mode +@section Diff Mode +@cindex Diff mode +@findex diff-mode +@cindex patches, editing + + Diff mode is used for the output of @kbd{M-x diff}; it is also +useful for editing patches and comparisons produced by the +@command{diff} program. To select Diff mode manually, type @kbd{M-x +diff-mode}. + + One general feature of Diff mode is that manual edits to the patch +automatically correct line numbers, including those in the hunk +header, so that you can actually apply the edited patch. Diff mode +treats each hunk location as an ``error message,'' so that you can use +commands such as @kbd{C-x '} to visit the corresponding source +locations. It also provides the following commands to navigate, +manipulate and apply parts of patches: + +@table @kbd +@item M-n +Move to the next hunk-start (@code{diff-hunk-next}). + +@item M-p +Move to the previous hunk-start (@code{diff-hunk-prev}). + +@item M-@} +Move to the next file-start, in a multi-file patch +(@code{diff-file-next}). + +@item M-@{ +Move to the previous file-start, in a multi-file patch +(@code{diff-file-prev}). + +@item M-k +Kill the hunk at point (@code{diff-hunk-kill}). + +@item M-K +In a multi-file patch, kill the current file part. +(@code{diff-file-kill}). + +@item C-c C-a +Apply this hunk to its target file (@code{diff-apply-hunk}). With a +prefix argument of @kbd{C-u}, revert this hunk. + +@item C-c C-c +Go to the source corresponding to this hunk (@code{diff-goto-source}). + +@item C-c C-e +Start an Ediff session with the patch (@code{diff-ediff-patch}). +@xref{Top, Ediff, Ediff, ediff, The Ediff Manual}. + +@item C-c C-n +Restrict the view to the current hunk (@code{diff-restrict-view}). +@xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the +view to the current patch of a multiple file patch. To widen again, +use @kbd{C-x n w}. + +@item C-c C-r +Reverse the direction of comparison for the entire buffer +(@code{diff-reverse-direction}). + +@item C-c C-s +Split the hunk at point (@code{diff-split-hunk}). This is for +manually editing patches, and only works with the unified diff format. + +@item C-c C-u +Convert the entire buffer to unified format +(@code{diff-context->unified}). With a prefix argument, convert +unified format to context format. In Transient Mark mode, when the +mark is active, this command operates only on the region. + +@item C-c C-w +Refine the current hunk so that it disregards changes in whitespace +(@code{diff-refine-hunk}). +@end table + + @kbd{C-x 4 a} in Diff mode operates on behalf of the target file, +but gets the function name from the patch itself. @xref{Change Log}. +This is useful for making log entries for functions that are deleted +by the patch. + +@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 minor mode called View +mode. + + A related command, @kbd{M-x view-buffer}, views a buffer already present +in Emacs. @xref{Misc Buffer}. + +@kindex C-x i +@findex insert-file + @kbd{M-x insert-file} (also @kbd{C-x i}) 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 insert-file-literally + @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file}, +except the file is inserted ``literally'': it is treated as a sequence +of @acronym{ASCII} characters with no special encoding or conversion, +similar to the @kbd{M-x find-file-literally} command +(@pxref{Visiting}). + +@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}. The variable +@code{write-region-inhibit-fsync} applies to these commands, as well +as saving files; see @ref{Customize Save}. + +@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 the file name +@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. + + If the argument @var{new} is just a directory name, the real new +name is in that directory, with the same non-directory component as +@var{old}. For example, @kbd{M-x rename-file RET ~/foo RET /tmp RET} +renames @file{~/foo} to @file{/tmp/foo}. The same rule applies to all +the remaining commands in this section. All of them ask for +confirmation when the new file name already exists, too. + +@findex add-name-to-file +@cindex hard links (creation) + 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 is created as a ``hard link'' to the existing file. +The new name must belong on the same file system that the file is on. +On MS-Windows, this command works only if the file resides in an NTFS +file system. On MS-DOS, it works by copying the file. + +@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. + +@findex make-symbolic-link +@cindex symbolic links (creation) + @kbd{M-x make-symbolic-link} reads two file names @var{target} and +@var{linkname}, then creates a symbolic link named @var{linkname}, +which points 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 nonexistent 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. + + Not all systems support symbolic links; on systems that don't +support them, this command is not defined. + +@node Compressed Files +@section Accessing Compressed Files +@cindex compression +@cindex uncompression +@cindex Auto Compression mode +@cindex mode, Auto Compression +@pindex gzip + + Emacs automatically uncompresses compressed files when you visit +them, and automatically recompresses them if you alter them and save +them. 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. + +@findex auto-compression-mode +@vindex auto-compression-mode + To disable this feature, type the command @kbd{M-x +auto-compression-mode}. You can disable it permanently by +customizing the variable @code{auto-compression-mode}. + +@node File Archives +@section File Archives +@cindex mode, tar +@cindex Tar mode +@cindex file archives + + A file whose name ends in @samp{.tar} is normally an @dfn{archive} +made by the @code{tar} program. Emacs views these files in a special +mode called Tar mode which provides a Dired-like list of the contents +(@pxref{Dired}). You can move around through the list just as you +would in Dired, and visit the subfiles contained in the archive. +However, not all Dired commands are available in Tar mode. + + If Auto Compression mode is enabled (@pxref{Compressed Files}), then +Tar mode is used also for compressed archives---files with extensions +@samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}. + + The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file +into its own buffer. You can edit it there, and if you save the +buffer, the edited version will replace the version in the Tar buffer. +@kbd{v} extracts a file into a buffer in View mode. @kbd{o} extracts +the file and displays it in another window, so you could edit the file +and operate on the archive simultaneously. @kbd{d} marks a file for +deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in +Dired. @kbd{C} copies a file from the archive to disk and @kbd{R} +renames a file within the archive. @kbd{g} reverts the buffer from +the archive on disk. + + The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission +bits, group, and owner, respectively. + + If your display supports colors and the mouse, moving the mouse +pointer across a file name highlights that file name, indicating that +you can click on it. Clicking @kbd{Mouse-2} on the highlighted file +name extracts the file into a buffer and displays that buffer. + + Saving the Tar buffer writes a new version of the archive to disk with +the changes you made to the components. + + You don't need the @code{tar} program to use Tar mode---Emacs reads +the archives directly. However, accessing compressed archives +requires the appropriate uncompression program. + +@cindex Archive mode +@cindex mode, archive +@cindex @code{arc} +@cindex @code{jar} +@cindex @code{zip} +@cindex @code{lzh} +@cindex @code{zoo} +@pindex arc +@pindex jar +@pindex zip +@pindex lzh +@pindex zoo +@cindex Java class archives +@cindex unzip archives + A separate but similar Archive mode is used for archives produced by +the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip}, and +@code{zoo}, which have extensions corresponding to the program names. +Archive mode also works for those @code{exe} files that are +self-extracting executables. + + The key bindings of Archive mode are similar to those in Tar mode, +with the addition of the @kbd{m} key which marks a file for subsequent +operations, and @kbd{M-@key{DEL}} which unmarks all the marked files. +Also, the @kbd{a} key toggles the display of detailed file +information, for those archive types where it won't fit in a single +line. Operations such as renaming a subfile, or changing its mode or +owner, are supported only for some of the archive formats. + + Unlike Tar mode, Archive mode runs the archiving program to unpack +and repack archives. Details of the program names and their options +can be set in the @samp{Archive} Customize group. However, you don't +need these programs to look at the archive table of contents, only to +extract or manipulate the subfiles in the archive. + +@node Remote Files +@section Remote Files + +@cindex Tramp +@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} +/@var{user}@@@var{host}#@var{port}:@var{filename} +/@var{method}:@var{user}@@@var{host}:@var{filename} +/@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename} +@end group +@end example + +@noindent +To carry out this request, Emacs uses either the FTP program or a +remote-login program such as @command{ssh}, @command{rlogin}, or +@command{telnet}. You can always specify in the file name which +method to use---for example, +@file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, whereas +@file{/ssh:@var{user}@@@var{host}:@var{filename}} uses @command{ssh}. +When you don't specify a method in the file name, Emacs chooses +the method as follows: + +@enumerate +@item +If the host name starts with @samp{ftp.} (with dot), then Emacs uses +FTP. +@item +If the user name is @samp{ftp} or @samp{anonymous}, then Emacs uses +FTP. +@item +Otherwise, Emacs uses @command{ssh}. +@end enumerate + +@noindent +Remote file access through FTP is handled by the Ange-FTP package, which +is documented in the following. Remote file access through the other +methods is handled by the Tramp package, which has its own manual. +@xref{Top, The Tramp Manual,, tramp, The Tramp Manual}. + +When the Ange-FTP package is used, Emacs 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}. The form using +@var{port} allows you to access servers running on a non-default TCP +port. + +@cindex backups for remote files +@vindex ange-ftp-make-backup-files + If you want to disable backups for remote files, set the variable +@code{ange-ftp-make-backup-files} to @code{nil}. + + By default, the auto-save files (@pxref{Auto Save Files}) for remote +files are made in the temporary file directory on the local machine. +This is achieved using the variable @code{auto-save-file-name-transforms}. + +@cindex ange-ftp +@vindex ange-ftp-default-user +@cindex user name for remote file access + 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. + +@cindex anonymous FTP +@vindex ange-ftp-generate-anonymous-password + To visit files accessible by anonymous FTP, you use special user +names @samp{anonymous} or @samp{ftp}. Passwords for these user names +are handled specially. The variable +@code{ange-ftp-generate-anonymous-password} controls what happens: if +the value of this variable is a string, then that string is used as +the password; if non-@code{nil} (the default), then the value of +@code{user-mail-address} is used; if @code{nil}, then Emacs prompts +you for a password as usual. + +@cindex firewall, and accessing remote files +@cindex gateway, and remote file access with @code{ange-ftp} +@vindex ange-ftp-smart-gateway +@vindex ange-ftp-gateway-host + Sometimes you may be unable to access files on a remote machine +because a @dfn{firewall} in between blocks the connection for security +reasons. If you can log in on a @dfn{gateway} machine from which the +target files @emph{are} accessible, and whose FTP server supports +gatewaying features, you can still use remote file names; all you have +to do is specify the name of the gateway machine by setting the +variable @code{ange-ftp-gateway-host}, and set +@code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able +to make remote file names work, but the procedure is complex. You can +read the instructions by typing @kbd{M-x finder-commentary @key{RET} +ange-ftp @key{RET}}. + +@vindex file-name-handler-alist +@cindex disabling remote files + You can entirely turn off the FTP file name feature by removing the +entries @code{ange-ftp-completion-hook-function} and +@code{ange-ftp-hook-function} from the variable +@code{file-name-handler-alist}. You can turn off the feature in +individual cases by quoting the file name with @samp{/:} (@pxref{Quoted +File Names}). + +@node Quoted File Names +@section Quoted File Names + +@cindex quoting file names +@cindex file names, quote special characters + 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}. + + Quoting with @samp{/:} is also a way to enter in the minibuffer a +file name that contains @samp{$}. In order for this to work, the +@samp{/:} must be at the beginning of the minibuffer contents. (You +can also double each @samp{$}; see @ref{File Names with $}.) + + You can also quote wildcard characters with @samp{/:}, for visiting. +For example, @file{/:/tmp/foo*bar} visits the file +@file{/tmp/foo*bar}. + + Another method of getting the same result is to enter +@file{/tmp/foo[*]bar}, which is a wildcard specification that matches +only @file{/tmp/foo*bar}. However, in many cases there is no need to +quote the wildcard characters because even unquoted they give the +right result. 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 only +@file{/tmp/foo*bar}. + +@node File Name Cache +@section File Name Cache + +@cindex file name caching +@cindex cache of file names +@pindex find +@kindex C-@key{TAB} +@findex file-cache-minibuffer-complete + You can use the @dfn{file name cache} to make it easy to locate a +file by name, without having to remember exactly where it is located. +When typing a file name in the minibuffer, @kbd{C-@key{tab}} +(@code{file-cache-minibuffer-complete}) completes it using the file +name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the +possible completions of what you had originally typed. (However, note +that the @kbd{C-@key{tab}} character cannot be typed on most text-only +terminals.) + + The file name cache does not fill up automatically. Instead, you +load file names into the cache using these commands: + +@findex file-cache-add-directory +@table @kbd +@item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET} +Add each file name in @var{directory} to the file name cache. +@item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET} +Add each file name in @var{directory} and all of its nested +subdirectories to the file name cache. +@item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET} +Add each file name in @var{directory} and all of its nested +subdirectories to the file name cache, using @command{locate} to find +them all. +@item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET} +Add each file name in each directory listed in @var{variable} +to the file name cache. @var{variable} should be a Lisp variable +such as @code{load-path} or @code{exec-path}, whose value is a list +of directory names. +@item M-x file-cache-clear-cache @key{RET} +Clear the cache; that is, remove all file names from it. +@end table + + The file name cache is not persistent: it is kept and maintained +only for the duration of the Emacs session. You can view the contents +of the cache with the @code{file-cache-display} command. + +@node File Conveniences +@section Convenience Features for Finding Files + + In this section, we introduce some convenient facilities for finding +recently-opened files, reading file names from a buffer, and viewing +image files. + +@findex recentf-mode +@vindex recentf-mode +@findex recentf-save-list +@findex recentf-edit-list + If you enable Recentf mode, with @kbd{M-x recentf-mode}, the +@samp{File} menu includes a submenu containing a list of recently +opened files. @kbd{M-x recentf-save-list} saves the current +@code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list} +edits it. + + The @kbd{M-x ffap} command generalizes @code{find-file} with more +powerful heuristic defaults (@pxref{FFAP}), often based on the text at +point. Partial Completion mode offers other features extending +@code{find-file}, which can be used with @code{ffap}. +@xref{Completion Options}. + +@findex image-mode +@findex image-toggle-display +@cindex images, viewing + Visiting image files automatically selects Image mode. This major +mode allows you to toggle between displaying the file as an image in +the Emacs buffer, and displaying its underlying text representation, +using the command @kbd{C-c C-c} (@code{image-toggle-display}). This +works only when Emacs can display the specific image type. If the +displayed image is wider or taller than the frame, the usual point +motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts +of the image to be displayed. + +@findex thumbs-mode +@findex mode, thumbs + See also the Image-Dired package (@pxref{Image-Dired}) for viewing +images as thumbnails. + +@node Filesets +@section Filesets +@cindex filesets + +@findex filesets-init + If you regularly edit a certain group of files, you can define them +as a @dfn{fileset}. This lets you perform certain operations, such as +visiting, @code{query-replace}, and shell commands on all the files +at once. To make use of filesets, you must first add the expression +@code{(filesets-init)} to your @file{.emacs} file (@pxref{Init File}). +This adds a @samp{Filesets} menu to the menu bar. + +@findex filesets-add-buffer +@findex filesets-remove-buffer + The simplest way to define a fileset is by adding files to it one +at a time. To add a file to fileset @var{name}, visit the file and +type @kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If +there is no fileset @var{name}, this creates a new one, which +initially creates only the current file. The command @kbd{M-x +filesets-remove-buffer} removes the current file from a fileset. + + You can also edit the list of filesets directly, with @kbd{M-x +filesets-edit} (or by choosing @samp{Edit Filesets} from the +@samp{Filesets} menu). The editing is performed in a Customize buffer +(@pxref{Easy Customization}). Filesets need not be a simple list of +files---you can also define filesets using regular expression matching +file names. Some examples of these more complicated filesets are +shown in the Customize buffer. Remember to select @samp{Save for +future sessions} if you want to use the same filesets in future Emacs +sessions. + + You can use the command @kbd{M-x filesets-open} to visit all the +files in a fileset, and @kbd{M-x filesets-close} to close them. Use +@kbd{M-x filesets-run-cmd} to run a shell command on all the files in +a fileset. These commands are also available from the @samp{Filesets} +menu, where each existing fileset is represented by a submenu. + +@ignore + arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250 +@end ignore diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi new file mode 100644 index 00000000000..d1577e2f528 --- /dev/null +++ b/doc/emacs/fixit.texi @@ -0,0 +1,471 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, +@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Fixit, Keyboard Macros, 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-_} 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 the undo command undo earlier +and earlier changes, back to the limit of the undo information +available. @xref{Undo}, for more information. + +@menu +* Undo:: The Undo commands. +* 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 Undo +@section Undo +@cindex undo +@cindex changes, undoing + + The @dfn{undo} commands undo recent changes in the buffer's text. +Each buffer records changes individually, and the undo command always +applies to the current buffer. You can undo all the changes in a +buffer for as far as back these records go. Usually each editing +command makes a separate entry in the undo records, but some commands +such as @code{query-replace} divide their changes into multiple +entries for flexibility in undoing. Meanwhile, self-inserting +characters are usually grouped to make undoing less tedious. + +@table @kbd +@item C-x u +@itemx C-_ +@itemx C-/ +Undo one entry in the current buffer's undo records (@code{undo}). +@end table + +@kindex C-x u +@kindex C-_ +@kindex C-/ +@findex undo + To begin to undo, type the command @kbd{C-x u} (or its aliases, +@kbd{C-_} or @kbd{C-/}). This undoes the most recent change in the +buffer, and moves point back to where it was before that change. + + Consecutive repetitions of @kbd{C-x u} (or its aliases) undo earlier +and earlier changes in the current buffer, back to the limit of the +current buffer's undo records. If all the recorded changes have +already been undone, the undo command just signals an error. + + 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 +below. + +@findex undo-only + 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 undo commands again. On the +other hand, if you want to resume undoing, without redoing previous +undo commands, use @kbd{M-x undo-only}. This is like @code{undo}, but +will not redo changes you have just undone. + +@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 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 (@pxref{Transient Mark}), any use of @code{undo} when there is an +active region performs selective undo; you do not need a prefix +argument. + + Some specialized buffers do not make undo records. Buffers +whose names start with spaces never do; these buffers are used +internally by Emacs and its extensions to hold text that users don't +normally look at or edit. + +@vindex undo-limit +@vindex undo-strong-limit +@vindex undo-outer-limit +@cindex undo limit + When the undo records for a buffer becomes too large, Emacs +discards the oldest undo records from time to time (during garbage +collection). You can specify how much undo records to keep by +setting three variables: @code{undo-limit}, @code{undo-strong-limit}, +and @code{undo-outer-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: a previous command (not the most recent one) which +pushes the size past this amount is itself forgotten. The default +value of @code{undo-strong-limit} is 30000. + + Regardless of the values of those variables, the most recent change +is never discarded unless it gets bigger than @code{undo-outer-limit} +(normally 3,000,000). At that point, Emacs discards the undo data and +warns you about it. This is the only situation in which you cannot +undo the last command. If this happens, you can increase the value of +@code{undo-outer-limit} to make it even less likely to happen in the +future. But if you didn't expect the command to create such large +undo data, then it is probably a bug and you should report it. +@xref{Bugs,, Reporting Bugs}. + + The reason the @code{undo} command has three key bindings, @kbd{C-x +u}, @kbd{C-_} and @kbd{C-/}, is that it is worthy of a +single-character key, but @kbd{C-x u} is more straightforward for +beginners to remember and type. Meanwhile, @kbd{C--} on a text-only +terminal is really @kbd{C-_}, which makes it a natural and easily +typed binding for undoing. + +@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 confusion 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 between the two transposed +characters before you type @kbd{C-t}. 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 +@c Don't index C-M-t and transpose-sexps here, they are indexed in +@c programs.texi, in the "List Commands" node. +@c @kindex C-M-t +@c @findex transpose-sexps + @kbd{M-t} transposes the word before point with the word after point +(@code{transpose-words}). 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{Expressions}), and @kbd{C-x C-t} +(@code{transpose-lines}) exchanges lines. They work like @kbd{M-t} +except as regards what units of text they transpose. + + A numeric argument to a transpose command serves as a repeat count: it +tells the transpose command to move the character (word, expression, line) +before or containing point across several other characters (words, +expressions, 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, expression, 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 programs Aspell and Ispell, which are not part of Emacs. +@ifnottex +@xref{Top, Aspell,, aspell, The Aspell Manual}. +@end ifnottex + +@table @kbd +@item M-x flyspell-mode +Enable Flyspell mode, which highlights all misspelled words. +@item M-x flyspell-prog-mode +Enable Flyspell mode for comments and strings only. +@item M-$ +Check and correct spelling of the word at point (@code{ispell-word}). +@item M-@key{TAB} +@itemx @key{ESC} @key{TAB} +Complete the word before point based on the spelling dictionary +(@code{ispell-complete-word}). +@item M-x ispell +Spell-check the active region or the current buffer. +@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 Aspell or Ispell process, using @var{dict} as the dictionary. +@item M-x ispell-kill-ispell +Kill the Aspell or 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. + +@findex flyspell-prog-mode +Flyspell Prog mode works just like ordinary Flyspell mode, except that +it only checks words in comments and string constants. This feature +is useful for editing programs. Type @kbd{M-x flyspell-prog-mode} to +enable or disable this mode in the current buffer. + + The other Emacs spell-checking features check or look up words when +you give an explicit command to do so. + +@kindex M-$ +@findex ispell-word + To check the spelling of the word around or before 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 command checks the whole buffer, except for +material that is indented or appears to be cited from other messages. + +@findex ispell +@cindex spell-checking the active region + The @kbd{M-x ispell} command spell-checks the active region if the +Transient Mark mode is on (@pxref{Transient Mark}), otherwise it +spell-checks the current buffer. + + 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 single-character response. 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}. (The replacement +string will be rescanned for more spelling errors.) + +@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. (The replacements +will be rescanned for more spelling errors.) + +@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 Aspell or Ispell will +consider it correct from now on, even in future sessions. + +@item u +Insert the lower-case version of this word in your private dic@-tion@-ary +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 as +the replacement by typing a digit. You can use @samp{*} in @var{word} as a +wildcard. + +@item C-g +Quit interactive spell checking, leaving point at the word that was +being checked. You can restart checking 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). + +@item ? +Show the list of options. +@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. (If your window manager intercepts +@kbd{M-@key{TAB}}, type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.) To +choose one of the completions listed, click @kbd{Mouse-2} or +@kbd{Mouse-1} fast 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 Aspell or 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 +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 and Aspell use two dictionaries together for spell checking: the +standard dictionary and your private dictionary. The variable +@code{ispell-dictionary} specifies the file name to use for the +standard dictionary; a value of @code{nil} selects the default +dictionary. The command @kbd{M-x ispell-change-dictionary} sets this +variable and then restarts the subprocess, so that it will use +a different standard dictionary. + +@vindex ispell-complete-word-dict + Aspell and Ispell use a separate dictionary for word completion. +The variable @code{ispell-complete-word-dict} specifies the file name +of this dictionary. The completion dictionary must be different +because it cannot use root and affix information. For some languages +there is a spell checking dictionary but no word completion +dictionary. + +@ignore + arch-tag: 3359a443-96ed-448f-9f05-c8111ba8eac0 +@end ignore diff --git a/doc/emacs/fortran-xtra.texi b/doc/emacs/fortran-xtra.texi new file mode 100644 index 00000000000..9249f5f006c --- /dev/null +++ b/doc/emacs/fortran-xtra.texi @@ -0,0 +1,548 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@c +@c This file is included either in emacs-xtra.texi (when producing the +@c printed version) or in the main Emacs manual (for the on-line version). +@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 support for 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. + + Use @kbd{M-x fortran-mode} to switch to this major mode. This +command runs the hook @code{fortran-mode-hook}. +@iftex +@xref{Hooks,,, emacs, the Emacs Manual}. +@end iftex +@ifnottex +@xref{Hooks}. +@end ifnottex + +@cindex Fortran77 and Fortran90 +@findex f90-mode +@findex fortran-mode + Fortran mode is meant for editing Fortran77 ``fixed format'' (and also +``tab format'') source code. For editing the modern Fortran90 or +Fortran95 ``free format'' source code, use F90 mode (@code{f90-mode}). +Emacs normally uses Fortran mode for files with extension @samp{.f}, +@samp{.F} or @samp{.for}, and F90 mode for the extension @samp{.f90} and +@samp{.f95}. GNU Fortran supports both kinds of format. + +@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 support for Fortran. +* Columns: Fortran Columns. Measuring columns for valid Fortran. +* Abbrev: Fortran Abbrev. Built-in abbrevs for Fortran keywords. +@end menu + +@node Fortran Motion +@subsection Motion Commands + + In addition to the normal commands for moving by and operating on +``defuns'' (Fortran subprograms---functions and subroutines, as well as +modules for F90 mode), Fortran mode provides special commands to move by +statements and other program units. + +@table @kbd +@kindex C-c C-n @r{(Fortran mode)} +@findex fortran-next-statement +@findex f90-next-statement +@item C-c C-n +Move to the beginning of the next statement +(@code{fortran-next-statement}/@code{f90-next-statement}). + +@kindex C-c C-p @r{(Fortran mode)} +@findex fortran-previous-statement +@findex f90-previous-statement +@item C-c C-p +Move to the beginning of the previous statement +(@code{fortran-previous-statement}/@code{f90-previous-statement}). +If there is no previous statement (i.e. if called from the first +statement in the buffer), move to the start of the buffer. + +@kindex C-c C-e @r{(F90 mode)} +@findex f90-next-block +@item C-c C-e +Move point forward to the start of the next code block +(@code{f90-next-block}). A code block is a subroutine, +@code{if}--@code{endif} statement, and so forth. This command exists +for F90 mode only, not Fortran mode. With a numeric argument, this +moves forward that many blocks. + +@kindex C-c C-a @r{(F90 mode)} +@findex f90-previous-block +@item C-c C-a +Move point backward to the previous code block +(@code{f90-previous-block}). This is like @code{f90-next-block}, but +moves backwards. + +@kindex C-M-n @r{(Fortran mode)} +@findex fortran-end-of-block +@findex f90-end-of-block +@item C-M-n +Move to the end of the current code block +(@code{fortran-end-of-block}/@code{f90-end-of-block}). With a numeric +argument, move forward that number of blocks. The mark is set before +moving point. The F90 mode version of this command checks for +consistency of block types and labels (if present), but it does not +check the outermost block since that may be incomplete. + +@kindex C-M-p @r{(Fortran mode)} +@findex fortran-beginning-of-block +@findex f90-beginning-of-block +@item C-M-p +Move to the start of the current code block +(@code{fortran-beginning-of-block}/@code{f90-beginning-of-block}). This +is like @code{fortran-end-of-block}, but moves backwards. +@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, fixed (or tab) format Fortran. + +@menu +* Commands: ForIndent Commands. Commands for indenting and filling 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 and Filling Commands + +@table @kbd +@item C-M-j +Break the current line at point and set up a continuation line +(@code{fortran-split-line}). +@item M-^ +Join this line to the previous line (@code{fortran-join-line}). +@item C-M-q +Indent all the lines of the subprogram point is in +(@code{fortran-indent-subprogram}). +@item M-q +Fill a comment block or statement. +@end table + +@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)} +@kindex C-c C-d @r{(Fortran mode)} +@findex fortran-join-line + @kbd{M-^} or @kbd{C-c C-d} runs the command @code{fortran-join-line}, +which joins a continuation line back to the previous line, roughly as +the inverse of @code{fortran-split-line}. The point must be on a +continuation line when this command is invoked. + +@kindex M-q @r{(Fortran mode)} +@kbd{M-q} in Fortran mode fills the comment block or statement that +point is in. This removes any excess statement continuations. + +@node ForIndent Cont +@subsubsection Continuation Lines +@cindex Fortran continuation lines + +@vindex fortran-continuation-string + Most Fortran77 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; but note that +the Fortran standard counts from 1.) The variable +@code{fortran-continuation-string} specifies what character to put in +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}. (Fortran90 introduced ``free format,'' +with another style of continuation lines). + +@vindex indent-tabs-mode @r{(Fortran mode)} +@vindex fortran-analyze-depth +@vindex fortran-tab-mode-default + Fortran mode can use either style of continuation line. When you +enter Fortran mode, it tries to deduce the proper continuation style +automatically from the buffer contents. It does this by scanning up to +@code{fortran-analyze-depth} (default 100) lines from the start of the +buffer. The first line that begins with either a tab character or six +spaces determines the choice. If the scan fails (for example, if the +buffer is new and therefore empty), the value of +@code{fortran-tab-mode-default} (@code{nil} for fixed format, and +non-@code{nil} for tab format) is used. @samp{/t} in the mode line +indicates tab format is selected. Fortran mode sets the value of +@code{indent-tabs-mode} accordingly. + + If the text on a line starts with the 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. + +@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. The default +value of the variable is 1. Fortran mode tries to prevent line number +digits passing column 4, reducing the indentation below the specified +maximum if necessary. If @code{fortran-line-number-indent} has the +value 5, line numbers are right-justified to end in column 4. + +@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}. + + +@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}, @samp{select case}, or +@samp{where} statements (default 3). + +@item fortran-structure-indent +Extra indentation within each level of @samp{structure}, @samp{union}, +@samp{map}, or @samp{interface} statements (default 3). + +@item fortran-continuation-indent +Extra indentation for bodies of continuation lines (default 5). + +@item fortran-check-all-num-for-matching-do +In Fortran77, a numbered @samp{do} statement is ended by any statement +with a matching line number. It is common (but not compulsory) to use a +@samp{continue} statement for this purpose. If this variable has a +non-@code{nil} value, indenting any numbered statement must check for a +@samp{do} that ends there. If you always end @samp{do} statements with +a @samp{continue} line (or if you use the more modern @samp{enddo}), +then you can speed up indentation by setting this variable to +@code{nil}. The default is @code{nil}. + +@item fortran-blink-matching-if +If this is @code{t}, indenting an @samp{endif} (or @samp{enddo} +statement moves the cursor momentarily to the matching @samp{if} (or +@samp{do}) 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 + +The variables controlling the indentation of comments are described in +the following section. + +@node Fortran Comments +@subsection Fortran Comments + + The usual Emacs comment commands assume that a comment can follow a +line of code. In Fortran77, 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. + +@vindex fortran-comment-line-start + Fortran mode can also handle the Fortran90 comment syntax where comments +start with @samp{!} and can follow other text. Because only some Fortran77 +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{fortran-comment-line-start} to @samp{"!"}. + +@table @kbd +@item M-; +Align comment or insert new comment (@code{fortran-indent-comment}). + +@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 + +@findex fortran-indent-comment + @kbd{M-;} in Fortran mode is redefined as the command +@code{fortran-indent-comment}. 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. +@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 fortran-directive-re + Compiler directive lines, or preprocessor lines, have much the same +appearance as comment lines. It is important, though, that such lines +never be indented at all, no matter what the value of +@code{fortran-comment-indent-style}. The variable +@code{fortran-directive-re} is a regular expression that specifies which +lines are directives. Matching lines are never indented, and receive +distinctive font-locking. + + 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 Auto Fill in Fortran Mode + + Fortran mode has specialized support for Auto Fill mode, which is a +minor mode that automatically splits 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. You activate Auto Fill in Fortran mode in the +normal way. +@iftex +@xref{Auto Fill,,, emacs, the Emacs Manual}. +@end iftex +@ifnottex +@xref{Auto Fill}. +@end ifnottex + +@vindex fortran-break-before-delimiters + Auto Fill breaks lines at spaces or delimiters when the lines get +longer than the desired width (the value of @code{fill-column}). The +delimiters (besides whitespace) that Auto Fill can 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. + + To enable Auto Fill in all Fortran buffers, add +@code{turn-on-auto-fill} to @code{fortran-mode-hook}. +@iftex +@xref{Hooks,,, emacs, the Emacs Manual}. +@end iftex +@ifnottex +@xref{Hooks}. +@end ifnottex + +@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 (@code{fortran-window-create-momentarily}). This may +help you avoid making lines longer than the 72-character limit that +some Fortran compilers impose. +@item C-u C-c C-w +Split the current window horizontally so that it is 72 columns wide +(@code{fortran-window-create}). You can then continue editing. +@item M-x fortran-strip-sequence-nos +Delete all text in column 72 and beyond. +@end table + +@kindex C-c C-r @r{(Fortran mode)} +@findex 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. + +@vindex fortran-column-ruler-fixed +@vindex fortran-column-ruler-tabs + 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 value of 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-momentarily + @kbd{C-c C-w} (@code{fortran-window-create-momentarily}) temporarily +splits the current window horizontally, making a window 72 columns +wide, so you can see any lines that are too long. Type a space to +restore the normal width. + +@kindex C-u C-c C-w @r{(Fortran mode)} +@findex fortran-window-create + You can also split the window horizontally and continue editing with +the split in place. To do this, use @kbd{C-u C-c C-w} (@code{M-x +fortran-window-create}). By editing in this window you can +immediately see when you make a line too wide to be correct Fortran. + +@findex fortran-strip-sequence-nos + The command @kbd{M-x fortran-strip-sequence-nos} deletes all text in +column 72 and beyond, on all lines in the current buffer. This is the +easiest way to get rid of old sequence numbers. + +@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. +@iftex +@xref{Abbrevs,,, emacs, the Emacs Manual}. +@end iftex +@ifnottex +@xref{Abbrevs}. +@end ifnottex + + 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. + +@ignore + arch-tag: 23ed7c36-1517-4646-9235-2d5ade5f06f6 +@end ignore diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi new file mode 100644 index 00000000000..a45b582b455 --- /dev/null +++ b/doc/emacs/frames.texi @@ -0,0 +1,1113 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, +@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Frames, International, Windows, Top +@chapter Frames and Graphical Displays +@cindex frames + + When using a graphical display, you can create multiple windows at +the system in a single Emacs session. Each system-level 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. + + To avoid confusion, we reserve the word ``window'' for the +subdivisions that Emacs implements, and never use it to refer to a +frame. + + Editing you do in one frame 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} (that is zero, not @kbd{o}). + + Emacs compiled for MS-DOS emulates some windowing functionality, +so that you can use many of the features described in this chapter. +@iftex +@xref{MS-DOS Mouse,,,emacs-xtra,Specialized Emacs Features}. +@end iftex +@ifnottex +@xref{MS-DOS Mouse}. +@end ifnottex + +@menu +* Cut and Paste:: Mouse commands for cut and paste. +* 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. +* Creating Frames:: Creating additional Emacs frames with various contents. +* Frame Commands:: Iconifying, deleting, and switching frames. +* Speedbar:: How to make and use a speedbar frame. +* 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. +* Wheeled Mice:: Using mouse wheels for scrolling. +* Drag and Drop:: Using drag and drop to open files and insert text. +* Menu Bars:: Enabling and disabling the menu bar. +* Tool Bars:: Enabling and disabling the tool bar. +* Dialog Boxes:: Controlling use of dialog boxes. +* Tooltips:: Displaying information at the current mouse position. +* Mouse Avoidance:: Moving the mouse pointer out of the way. +* Non-Window Terminals:: Multiple frames on terminals that show only one. +* Text-Only Mouse:: Using the mouse in text-only terminals. +@end menu + +@node Cut and Paste +@section Killing and Yanking on Graphical Displays + + This section describes facilities for selecting a region, killing, +and yanking using the mouse. + +@menu +* Mouse Commands:: Moving, cutting, and pasting, with the mouse. +* Cut/Paste Other App:: Transfering text between Emacs and other apps. +* Word and Line Mouse:: Mouse commands for selecting whole words or lines. +* Secondary Selection:: Cutting without altering point and mark. +* Clipboard:: Using the clipboard for selections. +@end menu + +@node Mouse Commands +@subsection 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 window-based programs. +Most of these commands also work in Emacs when you run it under an +@code{xterm} terminal. + +@kindex DELETE @r{(and mouse selection)} + 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 +@acronym{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. + +@vindex x-mouse-click-focus-ignore-position +Normally, Emacs does not distinguish between ordinary mouse clicks and +clicks that select a frame. When you click on a frame to select it, +that also changes the selected window and cursor position according to +the mouse click position. On the X window system, you can change this +behavior by setting the variable +@code{x-mouse-click-focus-ignore-position} to @code{t}. Then the +first click selects the frame, but does not affect the selected window +or cursor position. If you click again in the same place, since that +click will be in the selected frame, it will change the window or +cursor position. + +@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. + +@vindex mouse-drag-copy-region +If the variable @code{mouse-drag-copy-region} is @code{nil}, this +mouse command does not copy the selected region into the kill ring. + +@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. +@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 Delete Selection mode +@cindex mode, Delete Selection +@findex delete-selection-mode + Many graphical applications follow the convention that insertion while text +is selected deletes the selected text. You can make Emacs behave this +way by enabling Delete Selection mode---with @kbd{M-x +delete-selection-mode} or using Custom. Another effect of this mode +is that @key{DEL}, @kbd{C-d} and some other keys, when a selection +exists, will kill the whole selection. It also enables Transient Mark +mode (@pxref{Transient Mark}). + +@node Cut/Paste Other App +@subsection Cut and Paste with Other Window Applications + +@cindex cutting +@cindex pasting +@cindex X cutting and pasting + To copy text to another windowing application, kill it or save it in +the kill ring. Then use the ``paste'' or ``yank'' command of the +other application to insert the text. + + To copy text from another windowing application, use its ``cut'' or +``copy'' command to select the text you want. Then yank it in Emacs +with @kbd{C-y} or @kbd{Mouse-2}. + +@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 +window system. This is how other windowing applications can access +the text. On the X Window System, emacs also stores the text in the +cut buffer, but only if the text is short enough (the value of +@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. + + The standard coding system for X Window System selections is +@code{compound-text-with-extensions}. To specify another coding +system for selections, use @kbd{C-x @key{RET} x} or @kbd{C-x @key{RET} +X}. @xref{Communication Coding}. + +@node Word and Line Mouse +@subsection Mouse Commands for Words and Lines + + These variants of @kbd{Mouse-1} select entire words or lines at a time. + +@table @kbd +@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 +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 + +@node Secondary Selection +@subsection Secondary Selection +@cindex secondary selection + + The @dfn{secondary selection} is another way of selecting text using +the X Window System. 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. You can control the appearance of the highlighting by +customizing the @code{secondary-selection} face (@pxref{Face +Customization}). + +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. + +This way of setting the secondary selection does not alter the kill ring. + +@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}). This also +puts the selected text in the kill ring. 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, or even +which of the frame's windows you click on. @xref{Mouse Commands}. + +@node Clipboard +@subsection Using the Clipboard +@cindex clipboard +@vindex x-select-enable-clipboard +@findex menu-bar-enable-clipboard +@cindex OpenWindows +@cindex Gnome + + Apart from the primary and secondary selection types, Emacs can +handle the @dfn{clipboard} selection type which is used by some +applications, particularly under OpenWindows and Gnome. + + The command @kbd{M-x menu-bar-enable-clipboard} makes the @code{Cut}, +@code{Paste} and @code{Copy} menu items, as well as the keys of the same +names, all use the clipboard. + + You can customize the variable @code{x-select-enable-clipboard} to make +the Emacs yank functions consult the clipboard before the primary +selection, and to make the kill functions to store in the clipboard as +well as the primary selection. Otherwise they do not access the +clipboard at all. Using the clipboard is the default on MS-Windows and Mac, +but not on other systems. + +@node Mouse References +@section Following References with the Mouse +@kindex Mouse-1 @r{(selection)} +@kindex Mouse-2 @r{(selection)} + + Some read-only Emacs buffers include references you can follow, or +commands you can activate. These include names of files, of buffers, +of possible completions, of matches for a pattern, as well as the +buttons in Help buffers and customization buffers. You can follow the +reference or activate the command by moving point to it and typing +@key{RET}. You can also do this with the mouse, using either +@kbd{Mouse-1} or @kbd{Mouse-2}. + + Since yanking text into a read-only buffer is not allowed, these +buffers generally define @kbd{Mouse-2} to follow a reference or +activate a command. 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. + + However, most applications use @kbd{Mouse-1} to do this sort of +thing, so Emacs implements this too. If you click @kbd{Mouse-1} +quickly on a reference or button, it follows or activates. If you +click slowly, it moves point as usual. Dragging, meaning moving the +mouse while it is held down, also has its usual behavior of setting +the region. + +@vindex mouse-1-click-in-non-selected-windows + Normally, the @kbd{Mouse-1} click behavior is performed on links in +any window. The variable @code{mouse-1-click-in-non-selected-windows} +controls whether @kbd{Mouse-1} has this behavior even in non-selected +windows, or only in the selected window. + +@vindex mouse-highlight + You can usually tell when @kbd{Mouse-1} and @kbd{Mouse-2} have this +special sort of meaning because the sensitive text highlights when you +move the mouse over it. The variable @code{mouse-highlight} controls +whether to do this highlighting always (even when such text appears +where the mouse already is), never, or only immediately after you move +the mouse. + +@vindex mouse-1-click-follows-link + In Emacs versions before 22, only @kbd{Mouse-2} follows links and +@kbd{Mouse-1} always sets point. If you prefer this older behavior, +set the variable @code{mouse-1-click-follows-link} to @code{nil}. +This variable also lets you choose various other alternatives for +following links with the mouse. Type @kbd{C-h v +mouse-1-click-follows-link @key{RET}} for more details. + +@node Menu Mouse Clicks +@section Mouse Clicks for Menus + + Several mouse clicks with the @key{CTRL} and @key{SHIFT} modifiers +bring up menus. + +@table @kbd +@item C-Mouse-1 +@kindex C-Mouse-1 +This menu is for selecting a buffer. + +The MSB (``mouse select buffer'') global minor mode makes this +menu smarter and more customizable. @xref{Buffer Menus}. + +@item C-Mouse-2 +@kindex C-Mouse-2 +This menu is for specifying faces and other text properties +for editing formatted text. @xref{Formatted Text}. + +@item C-Mouse-3 +@kindex C-Mouse-3 +This menu is mode-specific. For most modes if Menu-bar mode is on, +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. To use @kbd{Mouse-3} instead, +do @code{(global-set-key [mouse-3] 'mouse-popup-menubar-stuff)}.} If +Menu-bar mode is off, this menu contains all the items which would be +present in the menu bar---not just the mode-specific ones---so that +you can access them without having to display the menu bar. + +@item S-Mouse-1 +This menu is for specifying the frame's default font. +@end table + +@node Mode Line Mouse +@section Mode Line Mouse Commands +@cindex mode line, mouse +@cindex mouse on mode line + + You can use mouse clicks on window mode lines to select and manipulate +windows. + + Some areas of the mode line, such as the buffer name and the major +mode name, have their own special mouse bindings. These areas are +highlighted when you hold the mouse over them, and information about +the special bindings will be displayed (@pxref{Tooltips}). This +section's commands do not apply in those areas. + +@table @kbd +@item Mouse-1 +@kindex Mouse-1 @r{(mode line)} +@kbd{Mouse-1} on a mode line selects the window it belongs to. By +dragging @kbd{Mouse-1} on the mode line, you can move it, thus +changing the height of the windows above and below. Changing heights +with the mouse in this way never deletes windows, it just refuses to +make any window smaller than the minimum height. + +@item Mouse-2 +@kindex Mouse-2 @r{(mode line)} +@kbd{Mouse-2} on a mode line expands that window to fill its frame. + +@item Mouse-3 +@kindex Mouse-3 @r{(mode line)} +@kbd{Mouse-3} on a mode line deletes the window it belongs to. If the +frame has only one window, it buries the current buffer instead, and +switches to another buffer. + +@item C-Mouse-2 +@kindex C-mouse-2 @r{(mode line)} +@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 + +@kindex C-Mouse-2 @r{(scroll bar)} +@kindex Mouse-1 @r{(scroll bar)} + Using @kbd{Mouse-1} on the divider between two side-by-side mode +lines, you can move the vertical boundary left or right. Using +@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 +@cindex face customization, in @file{~/.emacs} +@cindex color customization, in @file{~/.emacs} + 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 + +@noindent +Here's a similar example for specifying a foreground color: + +@example +(add-to-list 'default-frame-alist '(foreground-color . "blue")) +@end example + +@noindent +By putting such customizations in your @file{~/.emacs} init file, you +can control the appearance of all the frames Emacs creates, including +the initial one. + +@node Frame Commands +@section Frame Commands + + 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}). +When typed on an Emacs frame's icon, deiconify instead. + +The normal meaning of @kbd{C-z}, to suspend Emacs, is not useful under +a graphical display that allows multiple applications to operate +simultaneously in their own windows, so Emacs gives @kbd{C-z} a +different binding in that case. + +@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. + +@item C-x 5 1 +@kindex C-x 5 1 +@findex delete-other-frames +Delete all frames except the selected one. +@end table + +@vindex focus-follows-mouse + To make the command @kbd{C-x 5 o} work properly, you must tell Emacs +how the system (or the window manager) generally handles +focus-switching between windows. There are two possibilities: either +simply moving the mouse onto a window selects it (gives it focus), or +you have to click on it in a suitable way to do so. On X, this focus +policy also affects whether the focus is given to a frame that Emacs +raises. Unfortunately there is no way Emacs can find out +automatically which way the system handles this, so you have to +explicitly say, by setting the variable @code{focus-follows-mouse}. +If just moving the mouse onto a window selects it, that variable +should be @code{t}; if a click is necessary, the variable should be +@code{nil}. + +The window manager that is part of MS-Windows always gives focus to a +frame that raises, so this variable has no effect in the native +MS-Windows build of Emacs. + +@node Speedbar +@section Speedbar Frames +@cindex speedbar + +@cindex attached frame (of speedbar) + The @dfn{speedbar} is a special frame for conveniently navigating in +or operating on another frame. The speedbar, when it exists, is +always associated with a specific frame, called its @dfn{attached +frame}; all speedbar operations act on that frame. + + Type @kbd{M-x speedbar} to create the speedbar and associate it with +the current frame. To dismiss the speedbar, type @kbd{M-x speedbar} +again, or select the speedbar and type @kbd{q}. (You can also delete +the speedbar frame like any other Emacs frame.) If you wish to +associate the speedbar with a different frame, dismiss it and call +@kbd{M-x speedbar} from that frame. + + The speedbar can operate in various modes. Its default mode is +@dfn{File Display} mode, which shows the files in the current +directory of the selected window of the attached frame, one file per +line. Clicking on a file name visits that file in the selected window +of the attached frame, and clicking on a directory name shows that +directory in the speedbar (@pxref{Mouse References}). Each line also +has a box, @samp{[+]} or @samp{<+>}, that you can click on to +@dfn{expand} the contents of that item. Expanding a directory adds +the contents of that directory to the speedbar display, underneath the +directory's own line. Expanding an ordinary file adds a list of the +tags in that file to the speedbar display; you can click on a tag name +to jump to that tag in the selected window of the attached frame. +When a file or directory is expanded, the @samp{[+]} changes to +@samp{[-]}; you can click on that box to @dfn{contract} the item, +hiding its contents. + + You navigate through the speedbar using the keyboard, too. Typing +@kbd{RET} while point is on a line in the speedbar is equivalent to +clicking the item on the current line, and @kbd{SPC} expands or +contracts the item. @kbd{U} displays the parent directory of the +current directory. To copy, delete, or rename the file on the current +line, type @kbd{C}, @kbd{D}, and @kbd{R} respectively. To create a +new directory, type @kbd{M}. + + Another general-purpose speedbar mode is @dfn{Buffer Display} mode; +in this mode, the speedbar displays a list of Emacs buffers. To +switch to this mode, type @kbd{b} in the speedbar. To return to File +Display mode, type @kbd{f}. You can also change the display mode by +clicking @kbd{mouse-3} anywhere in the speedbar window (or +@kbd{mouse-1} on the mode-line) and selecting @samp{Displays} in the +pop-up menu. + + 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. + + For more details on using and programming the speedbar, @xref{Top, +Speedbar,,speedbar, Speedbar Manual}. + +@node Multiple Displays +@section Multiple Displays +@cindex multiple displays + + A single Emacs can talk to more than one X display. Initially, Emacs +uses just one display---the one specified with the @env{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, which Emacs normally displays +in ``another 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 ``another 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}. If you specify the symbol +@code{same-window} as a ``frame parameter'' in this list, with a +non-@code{nil} value, that means to use the selected window if +possible. If you use the symbol @code{same-frame} as a ``frame +parameter'' in this list, with a non-@code{nil} value, that means to +use the selected frame if possible. + + Alternatively, the value 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 Auto-Raise mode +@cindex Auto-Lower mode + +@kindex S-Mouse-1 + You can specify the font and colors used for text display, and the +colors for the frame borders, the cursor, and the mouse cursor, by +customizing the faces @code{default}, @code{border}, @code{cursor} and +@code{mouse}. @xref{Face Customization}. You can also set a frame's +default font through a pop-up menu. Press @kbd{S-Mouse-1} to activate +this menu. + + These commands are available for controlling the window management +behavior of the selected frame. + +@table @kbd +@findex auto-raise-mode +@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. + +Some window managers also implement auto-raise. If you enable +auto-raise for Emacs frames in your window manager, it will work, but +it is beyond Emacs' control, so @code{auto-raise-mode} has no effect +on it. + +@findex auto-lower-mode +@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 on the screen. + +The command @code{auto-lower-mode} has no effect on auto-lower +implemented by the window manager. To control that, you must use the +appropriate window manager features. +@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}). +@xref{Colors}, regarding colors. @xref{Font X}, regarding choice of +font. + + Colors, fonts, and other attributes of the frame's display can also +be customized by setting frame parameters in the variable +@code{default-frame-alist} (@pxref{Creating Frames}). For a detailed +description of 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 + + On graphical displays, Emacs normally makes a @dfn{scroll bar} at +the left of each Emacs window.@footnote{Placing it at the left is +usually more useful with overlapping frames with text starting at the +left margin.} 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. + + 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 +@vindex 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. Customize the variable +@code{scroll-bar-mode} to control the use of scroll bars at startup. +You can use it to specify that they are placed at the right of windows +if you prefer that. You have to set this variable through the +@samp{Customize} interface (@pxref{Easy Customization}), or it will +not work properly. + + You can also use the X resource @samp{verticalScrollBars} to control +the initial setting of Scroll Bar mode. @xref{Resources}. + +@findex toggle-scroll-bar + To enable or disable scroll bars for just the selected frame, use the +command @kbd{M-x toggle-scroll-bar}. + +@vindex scroll-bar-width +@cindex width of the scroll bar + You can control the scroll bar width by changing the value of the +@code{scroll-bar-width} frame parameter. + +@node Wheeled Mice +@section Scrolling With ``Wheeled'' Mice + +@cindex mouse wheel +@cindex wheel, mouse +@findex mouse-wheel-mode +@cindex Mouse Wheel minor mode +@cindex mode, Mouse Wheel + Some mice have a ``wheel'' instead of a third button. You can +usually click the wheel to act as either @kbd{Mouse-2} or +@kbd{Mouse-3}, depending on the setup. You can also use the wheel to +scroll windows instead of using the scroll bar or keyboard commands. +Mouse wheel support only works if the system generates appropriate +events; whenever possible, it is turned on by default. To toggle this +feature, use @kbd{M-x mouse-wheel-mode}. + +@vindex mouse-wheel-follow-mouse +@vindex mouse-wheel-scroll-amount +@vindex mouse-wheel-progressive-speed + The two variables @code{mouse-wheel-follow-mouse} and +@code{mouse-wheel-scroll-amount} determine where and by how much +buffers are scrolled. The variable +@code{mouse-wheel-progressive-speed} determines whether the scroll +speed is linked to how fast you move the wheel. + +@node Drag and Drop +@section Drag and Drop +@cindex drag and drop + + Emacs supports @dfn{drag and drop} using the mouse. For instance, +dropping text onto an Emacs frame inserts the text where it is dropped. +Dropping a file onto an Emacs frame visits that file. As a special +case, dropping the file on a Dired buffer moves or copies the file +(according to the conventions of the application it came from) into the +directory displayed in that buffer. + +@vindex dnd-open-file-other-window + Dropping a file normally visits it in the window you drop it on. If +you prefer to visit the file in a new window in such cases, customize +the variable @code{dnd-open-file-other-window}. + + The XDND and Motif drag and drop protocols, and the old KDE 1.x +protocol, are currently supported. + +@node Menu Bars +@section Menu Bars +@cindex Menu Bar mode +@cindex mode, Menu Bar +@findex menu-bar-mode +@vindex menu-bar-mode + + You can turn display of menu bars on or off with @kbd{M-x +menu-bar-mode} or by customizing the variable @code{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}. + +@kindex C-Mouse-3 @r{(when menu bar is disabled)} + Expert users often turn off the menu bar, especially on text-only +terminals, where this makes one additional line available for text. +If the menu bar is off, you can still pop up a menu of its contents +with @kbd{C-Mouse-3} on a display which supports pop-up menus. +@xref{Menu Mouse Clicks}. + + @xref{Menu Bar}, for information on how to invoke commands with the +menu bar. @xref{X Resources}, for how to customize the menu bar +menus' visual appearance. + +@node Tool Bars +@section Tool Bars +@cindex Tool Bar mode +@cindex mode, Tool Bar +@cindex icons, toolbar + + The @dfn{tool bar} is a line (or lines) of icons at the top of the +Emacs window, just below the menu bar. You can click on these icons +with the mouse to do various jobs. + + The global tool bar contains general commands. Some major modes +define their own tool bars to replace it. A few ``special'' modes +that are not designed for ordinary editing remove some items from the +global tool bar. + + Tool bars work only on a graphical display. The tool bar uses colored +XPM icons if Emacs was built with XPM support. Otherwise, the tool +bar uses monochrome icons (PBM or XBM format). + +@findex tool-bar-mode +@vindex tool-bar-mode + You can turn display of tool bars on or off with @kbd{M-x +tool-bar-mode} or by customizing the option @code{tool-bar-mode}. + +@node Dialog Boxes +@section Using Dialog Boxes +@cindex dialog boxes + +@vindex use-dialog-box + A dialog box is a special kind of menu for asking you a yes-or-no +question or some other special question. Many Emacs commands use a +dialog box to ask a yes-or-no question, if you used the mouse to +invoke the command to begin with. + + You can customize the variable @code{use-dialog-box} to suppress the +use of dialog boxes. This also controls whether to use file selection +windows (but those are not supported on all platforms). + +@vindex use-file-dialog + A file selection window is a special kind of dialog box for asking +for file names. You can customize the variable @code{use-file-dialog} +to suppress the use of file selection windows, even if you still want +other kinds of dialogs. This variable has no effect if you have +suppressed all dialog boxes with the variable @code{use-dialog-box}. + +@vindex x-gtk-show-hidden-files + For Gtk+ version 2.4 and newer, Emacs use the Gtk+ file chooser +dialog. Emacs adds a toggle button that enables and disables showing +of hidden files (files starting with a dot) in that dialog. The +variable @code{x-gtk-show-hidden-files} controls whether to show +hidden files by default. + +@vindex x-gtk-use-old-file-dialog + For Gtk+ versions 2.4 through 2.10, you can select the old file +dialog (@code{gtk-file-selector}) by setting the variable +@code{x-gtk-use-old-file-dialog} to a non-@code{nil} value. If it is +@code{nil}, Emacs uses @code{gtk-file-chooser}. If Emacs is built +with a Gtk+ version that has only one file dialog, this variable has +no effect. + +@vindex x-gtk-file-dialog-help-text + Emacs adds help text to the Gtk+ file chooser dialog. The variable +@code{x-gtk-file-dialog-help-text} specifies the text to add; if it is +@code{nil}, that disables the added text. + +@node Tooltips +@section Tooltips +@cindex tooltips + + @dfn{Tooltips} are small windows that display text information at the +current mouse position. They activate when there is a pause in mouse +movement. There are two types of tooltip: help tooltips and GUD +tooltips. + + @dfn{Help tooltips} typically display over text---including the mode +line---but are also available for other parts of the Emacs frame, such +as the tool bar and menu items. + +@findex tooltip-mode + You can toggle display of help tooltips (Tooltip mode) with the +command @kbd{M-x tooltip-mode}. When Tooltip mode is disabled, the +help text is displayed in the echo area instead. + + @dfn{GUD tooltips} show values of variables. They are useful when +you are debugging a program. @xref{Debugger Operation}. + +@vindex tooltip-delay + The variables @code{tooltip-delay} specifies how long Emacs should +wait before displaying a tooltip. For additional customization +options for displaying tooltips, use @kbd{M-x customize-group +@key{RET} tooltip @key{RET}}. @xref{X Resources}, for information on +customizing the windows that display tooltips. + +@node Mouse Avoidance +@section Mouse Avoidance +@cindex avoiding mouse in the way of your typing +@cindex mouse avoidance + +@vindex mouse-avoidance-mode +Mouse Avoidance mode keeps the mouse pointer away from point, to avoid +obscuring text you want to edit. Whenever it moves the mouse, it also +raises the frame. To use Mouse Avoidance mode, customize the variable +@code{mouse-avoidance-mode}. You can set this to various values to +move the mouse in several ways: + +@table @code +@item banish +Move the mouse to the upper-right corner on any key-press; +@item exile +Move the mouse to the corner only if the cursor gets too close, +and allow it to return once the cursor is out of the way; +@item jump +If the cursor gets too close to the mouse, displace the mouse +a random distance & direction; +@item animate +As @code{jump}, but shows steps along the way for illusion of motion; +@item cat-and-mouse +The same as @code{animate}; +@item proteus +As @code{animate}, but changes the shape of the mouse pointer too. +@end table + +@findex mouse-avoidance-mode +You can also use the command @kbd{M-x mouse-avoidance-mode} to enable +the mode. + +@node Non-Window Terminals +@section Non-Window Terminals +@cindex non-window terminals +@cindex single-frame terminals + + On a text-only terminal, Emacs 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 in fact the frame's initial name. You can give +frames more meaningful names 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. + +@node Text-Only Mouse +@section Using a Mouse in Terminal Emulators +@cindex mouse support +@cindex terminal emulators, mouse support + +Some terminal emulators support mouse clicks in the terminal window. + +@cindex xterm +In a terminal emulator which is compatible with @code{xterm}, +you can use @kbd{M-x xterm-mouse-mode} to give Emacs control over +simple use of the mouse---basically, only non-modified single clicks +are supported. The normal @code{xterm} mouse functionality for such +clicks is still available by holding down the @kbd{SHIFT} key when you +press the mouse button. Xterm Mouse mode is a global minor mode +(@pxref{Minor Modes}). Repeating the command turns the mode off +again. + +In the console on GNU/Linux, you can use @kbd{M-x t-mouse-mode}. You +need to have the gpm package installed and running on your system in +order for this to work. + +@ignore + arch-tag: 7dcf3a31-a43b-45d4-a900-445b10d77e49 +@end ignore diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi new file mode 100644 index 00000000000..f289c2ca1cb --- /dev/null +++ b/doc/emacs/glossary.texi @@ -0,0 +1,1323 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, +@c 2003, 2004, 2005, 2006, 2007 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 Argument +See `numeric argument.' + +@item @acronym{ASCII} character +An @acronym{ASCII} character is either an @acronym{ASCII} control character or an @acronym{ASCII} +printing character. @xref{User Input}. + +@item @acronym{ASCII} control character +An @acronym{ASCII} control character is the Control version of an upper-case +letter, or the Control version of one of the characters @samp{@@[\]^_?}. + +@item @acronym{ASCII} printing character +@acronym{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 a given maximum 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 Autoloading +Emacs automatically loads Lisp libraries when a Lisp program requests a +function or a variable from those libraries. This is called +`autoloading'. @xref{Lisp Libraries}. + +@item Backtrace +A backtrace is a trace of a series of function calls showing how a +program arrived to a certain point. It is used mainly for finding and +correcting bugs (q.v.@:). Emacs can display a backtrace when it signals +an error or when you type @kbd{C-g} (see `quitting'). @xref{Checklist}. + +@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 Balancing Parentheses +Emacs can balance parentheses (or other matching delimiters) either +manually or automatically. You do manual balancing with the commands +to move over parenthetical groupings (@pxref{Moving by Parens}). +Automatic balancing works by blinking or highlighting the delimiter +that matches the one you just inserted (@pxref{Matching,,Matching +Parens}). + +@item Balanced Expressions +A balanced expression is a syntactically recognizable expression, such +as a symbol, number, string constant, block, or parenthesized expression +in C. @xref{Expressions,Balanced Expressions}. + +@item Balloon Help +See `tooltips.' + +@item Base Buffer +A base buffer is a buffer whose text is shared by an indirect buffer +(q.v.@:). + +@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 Bookmark +Bookmarks are akin to registers (q.v.@:) in that they record positions +in buffers to which you can return later. Unlike registers, bookmarks +persist between Emacs sessions. + +@item Border +A border is a thin space along the edge of the frame, used just for +spacing, not for displaying anything. An Emacs frame has an ordinary +external border, outside of everything including the menu bar, plus an +internal border that surrounds the text windows and their scroll bars +and separates them from the menu bar and tool bar. You can customize +both borders with options and resources (@pxref{Borders X}). Borders +are not the same as fringes (q.v.@:). + +@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 `current 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 Bug +A bug is an incorrect or unreasonable behavior of a program, or +inaccurate or confusing documentation. Emacs developers treat bug +reports, both in Emacs code and its documentation, very seriously and +ask you to report any bugs you find. @xref{Bugs}. + +@item Button Down Event +A button down event is the kind of input event generated right away when +you press down on a mouse button. @xref{Mouse Buttons}. + +@item By Default +See `default.' + +@item Byte Compilation +See `compilation.' + +@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 Character Terminal +See `text-only terminal.' + +@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 Clipboard +A clipboard is a buffer provided by the window system for transferring +text between applications. On the X Window system, the clipboard is +provided in addition to the primary selection (q.v.@:); on MS-Windows and Mac, +the clipboard is used @emph{instead} of the primary selection. +@xref{Clipboard}. + +@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 History +See `minibuffer history.' + +@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,M-x,Running Commands by Name}). + +@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 Common Lisp +Common Lisp is a dialect of Lisp (q.v.@:) much larger and more powerful +than Emacs Lisp. Emacs provides a subset of Common Lisp in the CL +package. @xref{Top, Common Lisp, Overview, cl, Common Lisp Extensions}. + +@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,,, 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{Continuation Lines}. +A related Emacs feature is `filling' (q.v.@:). + +@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 and modify a program or other work of art, but requiring +modified versions to carry similar permission. Copyright is normally +used to keep users divided and helpless; with copyleft we turn that +around to empower users and encourage them to cooperate. + +The particular form of copyleft used by the GNU project is called the +GNU General Public License. @xref{Copying}. + +@item @key{CTRL} +The @key{CTRL} or ``control'' key is what you hold down +in order to enter a control character (q.v.). + +@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 current line is the line that point is on (@pxref{Point}). + +@item Current Paragraph +The current paragraph is the paragraph that point is in. If point is +between two paragraphs, the current paragraph is the one that follows +point. @xref{Paragraphs}. + +@item Current Defun +The current defun is 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{Point,Cursor}. + +@item Customization +Customization is making minor changes in the way Emacs works. It is +often done by setting variables (@pxref{Variables}) or faces +(@pxref{Face Customization}), or by rebinding key sequences +(@pxref{Keymaps}). + +@cindex cut and paste +@item Cut and Paste +See `killing' and `yanking.' + +@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 +A default is the value that is used for a certain purpose if and when +you do not specify a value to use. + +@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. +(On MS-Windows and MS-DOS, file names which start with a drive letter +@samp{@var{x}:} are treated as absolute, not relative.) +@xref{Minibuffer File,Default Directory}. + +@item Defun +A defun is a major definition at the top level in a program. The name +`defun' comes from Lisp, where most such definitions use the construct +@code{defun}. @xref{Defuns}. + +@item @key{DEL} +@key{DEL} is a character that runs the command to delete one character +of text before the cursor. It is typically either the @key{DELETE} +key or the @key{BACKSPACE} key, whichever one is easy to type. +@xref{Erasing,DEL}. + +@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,Misc File Ops,Miscellaneous File Operations}. + +@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' (q.v.@:). + +@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 dribble file is a file into which Emacs writes all the characters that +you type 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 showing 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 input events 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 End Of Line +End of line is a character or a sequence of characters that indicate +the end of a text line. On GNU and Unix systems, this is a newline +(q.v.@:), but other systems have other conventions. @xref{Coding +Systems,end-of-line}. Emacs can recognize several end-of-line +conventions in files and convert between them. + +@item Environment Variable +An environment variable is one of a collection of variables stored by +the operating system, each one having a name and a value. Emacs can +access environment variables set by its parent shell, and it can set +variables in the environment it passes to programs it invokes. +@xref{Environment}. + +@item EOL +See `end of line.' + +@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 displaying 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 Expression +See `balanced expression.' + +@item Expunging +Expunging an Rmail file or Dired buffer or a Gnus newsgroup buffer is an +operation that truly discards the messages or files you have previously +flagged for deletion. + +@item Face +A face is a style of displaying characters. It specifies attributes +such as font family and size, foreground and background colors, +underline and strike-through, background stipple, etc. Emacs provides +features to associate specific faces with portions of buffer text, in +order to display that text as specified by the face attributes. +@xref{Faces}. + +@item File Locking +Emacs uses 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). On MS-Windows/MS-DOS, an +absolute file name can also start with a drive letter and a colon +@samp{@var{d}:}. + +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. MS-DOS/MS-Windows file names can also use +backslashes to separate components, as in @file{foo\bar}. + +@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}. Some +other editors call this feature `line wrapping.' + +@item Font Lock +Font Lock is a mode that highlights parts of buffer text according to +its syntax. @xref{Font Lock}. + +@item Fontset +A fontset is a named collection of fonts. A fontset specification lists +character sets and which font to use to display each of them. Fontsets +make it easy to change several fonts at once by specifying the name of a +fontset, rather than changing each font separately. @xref{Fontsets}. + +@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 Formfeed Character +See `page.' + +@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 a window system +(q.v.@:), all the frames can be visible at the same time. +@xref{Frames}. Some other editors use the term ``window'' for this, +but in Emacs a window means something else. + +@item Fringe +On a graphical display (q.v.@:), there's a narrow portion of the +frame (q.v.@:) between the text area and the window's border. Emacs +displays the fringe using a special face (q.v.@:) called +@code{fringe}. @xref{Faces,fringe}. + +@item FTP +FTP is an acronym for File Transfer Protocol. Emacs uses an FTP client +program to provide access to remote files (q.v.@:). + +@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 (q.v.@:) in. In many cases you can use this to backtrack +through buffers you have been editing in, or in which you have found +tags (see `tags table'). @xref{Global Mark Ring}. + +@item Global Substitution +Global substitution means replacing each occurrence of one string by +another string throughout 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{Inserting Text}. + +@item Graphical Display +A graphical display is one that can display images and multiple fonts. +Usually it also has a window system (q.v.@:). + +@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. + +Emacs uses highlighting in several ways. When you mark a region with +the mouse, the region is always highlighted. Optionally Emacs can +also highlight the region whenever it is active (@pxref{Transient +Mark}). Incremental search also highlights matches (@pxref{Incremental +Search}). See also `font lock'. + +@item Hardcopy +Hardcopy means printed output. Emacs has commands for making printed +listings of text in Emacs buffers. @xref{Printing}. + +@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 Help Echo +Help echo is a short message displayed in the echo area when the mouse +pointer is located on portions of display that require some +explanations. Emacs displays help echo for menu items, parts of the +mode line, tool-bar buttons, etc. On graphics displays, the messages +can be displayed as tooltips (q.v.@:). @xref{Tooltips}. + +@item Hook +A hook is a list of functions to be called on specific occasions, such +as saving a buffer in a file, major mode activation, etc. By +customizing the various hooks, you can modify Emacs's behavior without +changing any of its code. @xref{Hooks}. + +@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 Iff +``Iff'' means ``if and only if.'' This terminology comes from +mathematics. Try to avoid using this term in documentation, since +many are unfamiliar with it and mistake it for a typo. + +@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 Incremental Search +Emacs provides an incremental search facility, whereby Emacs searches +for the string as you type it. @xref{Incremental Search}. + +@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 (q.v.@:). @xref{Indirect Buffers}. + +@item Info +Info is the hypertext format used by the GNU project for writing +documentation. + +@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-@acronym{ASCII} text characters by +typing sequences of @acronym{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,Interlocking,Simultaneous Editing}. + +@item Isearch +See `incremental search.' + +@item Justification +Justification means adding extra spaces within lines of text to make +them extend exactly to a specified width. +@xref{Format Justification}. + +@item Keybinding +See `binding.' + +@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}. + +@cindex keyboard shortcuts +@item Keyboard Shortcut +A keyboard shortcut is a key sequence (q.v.@:) which invokes a +command. What some programs call ``assigning a keyboard shortcut,'' +Emacs calls ``binding a key sequence.'' See `binding.' + +@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. + +@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 that erase text perform killing, as opposed to +deletion (q.v.@:). @xref{Killing}. + +@item Killing a Job +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-@acronym{ASCII} text +(@pxref{International}). + +@item Line Wrapping +See `filling.' + +@item Lisp +Lisp is a programming language. Most of Emacs is written in a dialect +of Lisp, called Emacs Lisp, that is extended with special features which +make it especially suitable for text editing tasks. + +@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{Moving by Parens}. + +@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,M-}. + +@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,M-x,Running Commands by Name}. + +@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 Margin +The space between the usable part of a window (including the +fringe) and the window edge. + +@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, or you can use +a keyboard interface to navigate it. @xref{Menu Bars}. + +@item Message +See `mail.' + +@item Meta +Meta is the name of a modifier bit which you can use in a command +character. To enter a meta character, you hold down the @key{META} +key while typing the character. We refer to such characters with +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}. + +On some terminals, the @key{META} key is actually labeled @key{ALT} +or @key{EDIT}. + +@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 minor mode keymap is 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 is by killing (q.v.@:) it and then +yanking (q.v.@:) it. @xref{Killing}. + +@item MULE +MULE refers to the Emacs features for editing multilingual non-@acronym{ASCII} text +using multibyte characters (q.v.@:). @xref{International}. + +@item Multibyte Character +A multibyte character is a character that takes up several bytes in a +buffer. Emacs uses multibyte characters to represent non-@acronym{ASCII} text, +since the number of non-@acronym{ASCII} characters is much more than 256. +@xref{International Chars, International Characters}. + +@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 for editing 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}. + +@cindex nil +@cindex t +@item @code{nil} +@code{nil} is a value usually interpreted as a logical ``false.'' Its +opposite is @code{t}, interpreted as ``true.'' + +@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 (@acronym{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 human-language 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{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 used 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 Query-Replace +Query-replace is an interactive string replacement feature provided by +Emacs. @xref{Query Replace}. + +@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{Inserting Text,Quoting}. + +@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 diagonally 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 you 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 Register +Registers are named slots in which text or buffer positions or +rectangles can be saved for later use. @xref{Registers}. A related +Emacs feature is `bookmarks' (q.v.@:). + +@item Regular Expression +A regular expression is a pattern that can match various text strings; +for example, @samp{a[0-9]+} matches @samp{a} followed by one or more +digits. @xref{Regexps}. + +@item Remote File +A remote file is a file that is stored on a system other than your own. +Emacs can access files on other computers provided that they are +connected to the same network as your machine, and (obviously) that +you have a supported method to gain access to those files. +@xref{Remote Files}. + +@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.@:); removing +a restriction is called widening (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 Reverting +Reverting means returning to the original state. Emacs lets you +revert a buffer by re-reading its file from disk. @xref{Reverting}. + +@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 under windowing +systems. @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{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 Selected Frame +The selected frame is the one your input currently operates on. +@xref{Frames}. + +@item Selected Window +The selected frame is the one your input currently operates on. +@xref{Basic Window}. + +@item Selecting a Buffer +Selecting a buffer means making it the current (q.v.@:) buffer. +@xref{Select Buffer}. + +@item Selection +Windowing systems allow an application program to specify +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, and also with the clipboard (q.v.@:). + +@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. Sexps are also +the balanced expressions (q.v.@:) of the Lisp language; this is why +the commands for editing balanced expressions have `sexp' in their +name. @xref{Expressions,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 +or her work. Emacs detects all cases of simultaneous editing, and +warns one of the users to investigate. +@xref{Interlocking,Interlocking,Simultaneous Editing}. + +@item @key{SPC} +@key{SPC} is the space character, which you enter by pressing the +space bar. + +@item Speedbar +The speedbar is a special tall frame that provides fast access to Emacs +buffers, functions within those buffers, Info nodes, and other +interesting parts of text within Emacs. @xref{Speedbar}. + +@item Spell Checking +Spell checking means checking correctness of the written form of each +one of the words in a text. Emacs uses the Ispell spelling-checker +program to check the spelling of parts of a buffer via a convenient user +interface. @xref{Spelling}. + +@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 Highlighting +See `font lock.' + +@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 Suspending +Suspending Emacs means stopping it temporarily and returning control +to its parent process, which is usually a shell. Unlike killing a job +(q.v.@:), you can later resume the suspended Emacs job without losing +your buffers, unsaved edits, undo history, etc. @xref{Exiting}. + +@item @key{TAB} +@key{TAB} is the tab character. In Emacs it is typically used for +indentation or completion. + +@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 +`Text' has two meanings (@pxref{Text}): + +@itemize @bullet +@item +Data consisting of a sequence of characters, as opposed to binary +numbers, executable programs, and the like. The basic contents of an +Emacs buffer (aside from the text properties, q.v.@:) 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 Text-only Terminal +A text-only terminal is a display that is limited to displaying text in +character units. Such a terminal cannot control individual pixels it +displays. Emacs supports a subset of display features on text-only +terminals. + +@item Text Properties +Text properties are annotations recorded for particular characters in +the buffer. Images in the buffer are recorded as text properties; +they also specify formatting information. @xref{Editing Format Info}. + +@item Tool Bar +The tool bar is a line (sometimes multiple lines) of icons at the top +of an Emacs frame. Clicking on one of these icons executes a command. +You can think of this as a graphical relative of the menu bar (q.v.@:). +@xref{Tool Bars}. + +@item Tooltips +Tooltips are small windows displaying a help echo (q.v.@:) text that +explains parts of the display, lists useful options available via mouse +clicks, etc. @xref{Tooltips}. + +@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, balanced expressions (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{Continuation Lines,Truncation}. + +@item TTY +See `text-only terminal.' + +@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 face (q.v.@:) or a variable (q.v.@:) that exists so +that you can customize Emacs by setting it to a new value. +@xref{Easy Customization}. + +@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 (@pxref{Variable Index}). @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. Some +other editors use the term ``window'' for what we call a `frame' +(q.v.@:) in Emacs. + +@item Window System +A window system is software that operates on a graphical display +(q.v.@:), to subdivide the screen so that multiple applications can +have their] own windows at the same time. All modern operating systems +include a window system. + +@item Word Abbrev +See `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 + +@ignore + arch-tag: 0dd53ce1-5f09-4ac2-b13b-cf22b0f28d23 +@end ignore diff --git a/doc/emacs/gnu.texi b/doc/emacs/gnu.texi new file mode 100644 index 00000000000..1cf85f41c3c --- /dev/null +++ b/doc/emacs/gnu.texi @@ -0,0 +1,567 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1995, 2001, 2002, 2003, 2004, +@c 2005, 2006, 2007 Free Software Foundation, Inc. +@ifclear justgnu +@node Manifesto,, Microsoft Windows, Top +@unnumbered The GNU Manifesto +@end ifclear +@ifset justgnu +Copyright @copyright{} 1985, 1993, 2001, 2002, 2003, 2004, +2005, 2006, 2007 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. + +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' + +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. + +@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 available GNU software, please see +our web site, @uref{http://www.gnu.org}. For software tasks and other +ways to contribute, see @uref{http://www.gnu.org/help}. +@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@footnote{In the 80s I had not yet realized how confusing it was +to speak of ``the issue'' of ``intellectual property.'' That term is +obviously biased; more subtle is the fact that it lumps together +various disparate laws which raise very different issues. Nowadays I +urge people to reject the term ``intellectual property'' entirely, +lest it lead others to suppose that those laws form one coherent +issue. The way to be clear is to discuss patents, copyrights, and +trademarks separately. See +@uref{http://www.gnu.org/philosophy/not-ipr.xhtml} for more +explanation of how this term spreads confusion and bias.} 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@footnote{Subsequently we have discovered the need to +distinguish between ``free software'' and ``freeware''. The term +``freeware'' means software you are free to redistribute, but usually +you are not free to study and change the source code, so most of it is +not free software. See +@uref{http://www.gnu.org/philosophy/words-to-avoid.html} for more +explanation.}, 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. + +@ignore + arch-tag: 21eb38f8-6fa0-480a-91cd-f3dab7148542 +@end ignore diff --git a/doc/emacs/gpl.texi b/doc/emacs/gpl.texi new file mode 100644 index 00000000000..5b416d3cb41 --- /dev/null +++ b/doc/emacs/gpl.texi @@ -0,0 +1,721 @@ +@c The GNU General Public License. +@center Version 3, 29 June 2007 + +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + +@display +Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. +@end display + +@heading Preamble + +The GNU General Public License is a free, copyleft license for +software and other kinds of works. + +The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom +to share and change all versions of a program---to make sure it remains +free software for all its users. We, the Free Software Foundation, +use the GNU General Public License for most of our software; it +applies also to any other work released this way by its authors. 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 +them 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 prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you +have certain responsibilities if you distribute copies of the +software, or if you modify it: responsibilities to respect the freedom +of others. + +For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. 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. + +Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + +For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + +Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the +manufacturer can do so. This is fundamentally incompatible with the +aim of protecting users' freedom to change the software. The +systematic pattern of such abuse occurs in the area of products for +individuals to use, which is precisely where it is most unacceptable. +Therefore, we have designed this version of the GPL to prohibit the +practice for those products. If such problems arise substantially in +other domains, we stand ready to extend this provision to those +domains in future versions of the GPL, as needed to protect the +freedom of users. + +Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish +to avoid the special danger that patents applied to a free program +could make it effectively proprietary. To prevent this, the GPL +assures that patents cannot be used to render the program non-free. + +The precise terms and conditions for copying, distribution and +modification follow. + +@heading TERMS AND CONDITIONS + +@enumerate 0 +@item Definitions. + +``This License'' refers to version 3 of the GNU General Public License. + +``Copyright'' also means copyright-like laws that apply to other kinds +of works, such as semiconductor masks. + +``The Program'' refers to any copyrightable work licensed under this +License. Each licensee is addressed as ``you''. ``Licensees'' and +``recipients'' may be individuals or organizations. + +To ``modify'' a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of +an exact copy. The resulting work is called a ``modified version'' of +the earlier work or a work ``based on'' the earlier work. + +A ``covered work'' means either the unmodified Program or a work based +on the Program. + +To ``propagate'' a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + +To ``convey'' a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user +through a computer network, with no transfer of a copy, is not +conveying. + +An interactive user interface displays ``Appropriate Legal Notices'' to +the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + +@item Source Code. + +The ``source code'' for a work means the preferred form of the work for +making modifications to it. ``Object code'' means any non-source form +of a work. + +A ``Standard Interface'' means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + +The ``System Libraries'' of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +``Major Component'', in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + +The ``Corresponding Source'' for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + +The Corresponding Source need not include anything that users can +regenerate automatically from other parts of the Corresponding Source. + +The Corresponding Source for a work in source code form is that same +work. + +@item Basic Permissions. + +All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + +You may make, run and propagate covered works that you do not convey, +without conditions so long as your license otherwise remains in force. +You may convey covered works to others for the sole purpose of having +them make modifications exclusively for you, or provide you with +facilities for running those works, provided that you comply with the +terms of this License in conveying all material for which you do not +control copyright. Those thus making or running the covered works for +you must do so exclusively on your behalf, under your direction and +control, on terms that prohibit them from making any copies of your +copyrighted material outside their relationship with you. + +Conveying under any other circumstances is permitted solely under the +conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + +@item Protecting Users' Legal Rights From Anti-Circumvention Law. + +No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + +When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such +circumvention is effected by exercising rights under this License with +respect to the covered work, and you disclaim any intention to limit +operation or modification of the work as a means of enforcing, against +the work's users, your or third parties' legal rights to forbid +circumvention of technological measures. + +@item Conveying Verbatim Copies. + +You may convey 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; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + +You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + +@item Conveying Modified Source Versions. + +You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these +conditions: + +@enumerate a +@item +The work must carry prominent notices stating that you modified it, +and giving a relevant date. + +@item +The work must carry prominent notices stating that it is released +under this License and any conditions added under section 7. This +requirement modifies the requirement in section 4 to ``keep intact all +notices''. + +@item +You must license the entire work, as a whole, under this License to +anyone who comes into possession of a copy. This License will +therefore apply, along with any applicable section 7 additional terms, +to the whole of the work, and all its parts, regardless of how they +are packaged. This License gives no permission to license the work in +any other way, but it does not invalidate such permission if you have +separately received it. + +@item +If the work has interactive user interfaces, each must display +Appropriate Legal Notices; however, if the Program has interactive +interfaces that do not display Appropriate Legal Notices, your work +need not make them do so. +@end enumerate + +A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +``aggregate'' if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + +@item Conveying Non-Source Forms. + +You may convey a covered work in object code form under the terms of +sections 4 and 5, provided that you also convey the machine-readable +Corresponding Source under the terms of this License, in one of these +ways: + +@enumerate a +@item +Convey the object code in, or embodied in, a physical product +(including a physical distribution medium), accompanied by the +Corresponding Source fixed on a durable physical medium customarily +used for software interchange. + +@item +Convey the object code in, or embodied in, a physical product +(including a physical distribution medium), accompanied by a written +offer, valid for at least three years and valid for as long as you +offer spare parts or customer support for that product model, to give +anyone who possesses the object code either (1) a copy of the +Corresponding Source for all the software in the product that is +covered by this License, on a durable physical medium customarily used +for software interchange, for a price no more than your reasonable +cost of physically performing this conveying of source, or (2) access +to copy the Corresponding Source from a network server at no charge. + +@item +Convey individual copies of the object code with a copy of the written +offer to provide the Corresponding Source. This alternative is +allowed only occasionally and noncommercially, and only if you +received the object code with such an offer, in accord with subsection +6b. + +@item +Convey the object code by offering access from a designated place +(gratis or for a charge), and offer equivalent access to the +Corresponding Source in the same way through the same place at no +further charge. You need not require recipients to copy the +Corresponding Source along with the object code. If the place to copy +the object code is a network server, the Corresponding Source may be +on a different server (operated by you or a third party) that supports +equivalent copying facilities, provided you maintain clear directions +next to the object code saying where to find the Corresponding Source. +Regardless of what server hosts the Corresponding Source, you remain +obligated to ensure that it is available for as long as needed to +satisfy these requirements. + +@item +Convey the object code using peer-to-peer transmission, provided you +inform other peers where the object code and Corresponding Source of +the work are being offered to the general public at no charge under +subsection 6d. + +@end enumerate + +A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + +A ``User Product'' is either (1) a ``consumer product'', which means any +tangible personal property which is normally used for personal, +family, or household purposes, or (2) anything designed or sold for +incorporation into a dwelling. In determining whether a product is a +consumer product, doubtful cases shall be resolved in favor of +coverage. For a particular product received by a particular user, +``normally used'' refers to a typical or common use of that class of +product, regardless of the status of the particular user or of the way +in which the particular user actually uses, or expects or is expected +to use, the product. A product is a consumer product regardless of +whether the product has substantial commercial, industrial or +non-consumer uses, unless such uses represent the only significant +mode of use of the product. + +``Installation Information'' for a User Product means any methods, +procedures, authorization keys, or other information required to +install and execute modified versions of a covered work in that User +Product from a modified version of its Corresponding Source. The +information must suffice to ensure that the continued functioning of +the modified object code is in no case prevented or interfered with +solely because modification has been made. + +If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + +The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or +updates for a work that has been modified or installed by the +recipient, or for the User Product in which it has been modified or +installed. Access to a network may be denied when the modification +itself materially and adversely affects the operation of the network +or violates the rules and protocols for communication across the +network. + +Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + +@item Additional Terms. + +``Additional permissions'' are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + +When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + +Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders +of that material) supplement the terms of this License with terms: + +@enumerate a +@item +Disclaiming warranty or limiting liability differently from the terms +of sections 15 and 16 of this License; or + +@item +Requiring preservation of specified reasonable legal notices or author +attributions in that material or in the Appropriate Legal Notices +displayed by works containing it; or + +@item +Prohibiting misrepresentation of the origin of that material, or +requiring that modified versions of such material be marked in +reasonable ways as different from the original version; or + +@item +Limiting the use for publicity purposes of names of licensors or +authors of the material; or + +@item +Declining to grant rights under trademark law for use of some trade +names, trademarks, or service marks; or + +@item +Requiring indemnification of licensors and authors of that material by +anyone who conveys the material (or modified versions of it) with +contractual assumptions of liability to the recipient, for any +liability that these contractual assumptions directly impose on those +licensors and authors. +@end enumerate + +All other non-permissive additional terms are considered ``further +restrictions'' within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + +If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + +Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; the +above requirements apply either way. + +@item Termination. + +You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + +@item Acceptance Not Required for Having Copies. + +You are not required to accept this License in order to receive or run +a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + +@item Automatic Licensing of Downstream Recipients. + +Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + +An ``entity transaction'' is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + +You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + +@item Patents. + +A ``contributor'' is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's ``contributor version''. + +A contributor's ``essential patent claims'' are all patent claims owned +or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, ``control'' includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + +Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + +In the following three paragraphs, a ``patent license'' is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To ``grant'' such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + +If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. ``Knowingly relying'' means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + +If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + +A patent license is ``discriminatory'' if it does not include within the +scope of its coverage, prohibits the exercise of, or is conditioned on +the non-exercise of one or more of the rights that are specifically +granted under this License. You may not convey a covered work if you +are a party to an arrangement with a third party that is in the +business of distributing software, under which you make payment to the +third party based on the extent of your activity of conveying the +work, and under which the third party grants, to any of the parties +who would receive the covered work from you, a discriminatory patent +license (a) in connection with copies of the covered work conveyed by +you (or copies made from those copies), or (b) primarily for and in +connection with specific products or compilations that contain the +covered work, unless you entered into that arrangement, or that patent +license was granted, prior to 28 March 2007. + +Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + +@item No Surrender of Others' Freedom. + +If 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 convey +a covered work so as to satisfy simultaneously your obligations under +this License and any other pertinent obligations, then as a +consequence you may not convey it at all. For example, if you agree +to terms that obligate you to collect a royalty for further conveying +from those to whom you convey the Program, the only way you could +satisfy both those terms and this License would be to refrain entirely +from conveying the Program. + +@item Use with the GNU Affero General Public License. + +Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + +@item Revised Versions of this License. + +The Free Software Foundation may publish revised and/or new versions +of the GNU 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 that a certain numbered version of the GNU General Public +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that numbered version or +of any later version published by the Free Software Foundation. If +the Program does not specify a version number of the GNU General +Public License, you may choose any version ever published by the Free +Software Foundation. + +If the Program specifies that a proxy can decide which future versions +of the GNU General Public License can be used, that proxy's public +statement of acceptance of a version permanently authorizes you to +choose that version for the Program. + +Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + +@item Disclaimer of Warranty. + +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 Limitation of Liability. + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR +CONVEYS 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. + +@item Interpretation of Sections 15 and 16. + +If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + +@end enumerate + +@heading END OF TERMS AND CONDITIONS + +@heading 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 +state the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and a brief idea of what it does.} +Copyright (C) @var{year} @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 3 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, see @url{http://www.gnu.org/licenses/}. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + +@smallexample +@var{program} Copyright (C) @var{year} @var{name of author} +This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. +This is free software, and you are welcome to redistribute it +under certain conditions; type @samp{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, your +program's commands might be different; for a GUI interface, you would +use an ``about box''. + +You should also get your employer (if you work as a programmer) or school, +if any, to sign a ``copyright disclaimer'' for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +@url{http://www.gnu.org/licenses/}. + +The GNU 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 Lesser General Public License instead of this License. But +first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. + +@ignore + arch-tag: 0c4a2556-f87e-464f-9b1d-efd920fcaf67 +@end ignore diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi new file mode 100644 index 00000000000..fe7c2a85ffa --- /dev/null +++ b/doc/emacs/help.texi @@ -0,0 +1,666 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 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, all accessible through the +@dfn{help character}, @kbd{C-h}. This is a prefix key that is used +for commands that display documentation; the next character you type +should be a @dfn{help options}, to ask for a particular kind of help. +You can cancel the @kbd{C-h} command with @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} itself is one of the help options; @kbd{C-h C-h} displays +a list of help options, with a brief description of each one +(@code{help-for-help}). You can scroll the list with @key{SPC} and +@key{DEL}, then type the help option you want. To cancel, type +@kbd{C-g}. + + @kbd{C-h} or @key{F1} means ``help'' in various other contexts as +well. For instance, you can type them after a prefix key to display +list of the keys that can follow the prefix key. (A few prefix keys +don't support @kbd{C-h} in this way, because they define other +meanings for it, but they all support @key{F1} for help.) + + Most help buffers use a special major mode, Help mode, which lets +you scroll conveniently with @key{SPC} and @key{DEL}. You can also +follow hyperlinks to URLs, and to other facilities including Info +nodes and customization buffers. @xref{Help Mode}. + +@cindex searching documentation efficiently +@cindex looking for a subject in documentation + If you are looking for a certain feature, but don't know what it is +called or where to look, we recommend three methods. First, try an +apropos command, then try searching the manual index, then look in the +FAQ and the package keywords. + +@table @kbd +@item C-h a @var{topics} @key{RET} +This searches for commands whose names match the argument +@var{topics}. The argument can be a keyword, a list of keywords, or a +regular expression (@pxref{Regexps}). This command displays all the +matches in a new buffer. @xref{Apropos}. + +@item C-h i d m emacs @key{RET} i @var{topic} @key{RET} +This searches for @var{topic} in the indices of the on-line Emacs +manual, and displays the first match found. Press @kbd{,} to see +subsequent matches. You can use a regular expression as @var{topic}. + +@item C-h i d m emacs @key{RET} s @var{topic} @key{RET} +Similar, but searches the @emph{text} of the manual rather than the +indices. + +@item C-h C-f +This displays the Emacs FAQ. You can use the Info commands +to browse it. + +@item C-h p +This displays the available Emacs packages based on keywords. +@xref{Library Keywords}. +@end table + +@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. +* Help Mode:: Special features of Help mode and Help buffers. +* Library Keywords:: Finding Lisp libraries by keywords (topics). +* Language Help:: Help relating to international language support. +* Misc Help:: Other help commands. +* Help Files:: Commands to display pre-written help files. +* Help Echo:: Help on active text and tooltips (`balloon help') +@end menu + +@iftex +@node Help Summary +@end iftex +@ifnottex +@node Help Summary +@section Help Summary +@end ifnottex + + Here is a summary of the Emacs interactive help commands. (The +character that follows @kbd{C-h} is the ``help option.'') @xref{Help +Files}, for other help commands that display fixed files of +information. + +@table @kbd +@item C-h a @var{topics} @key{RET} +Display a list of commands whose names match @var{topics} +(@code{apropos-command}; @pxref{Apropos}). +@item C-h b +Display all active key bindings; minor mode bindings first, then those +of the major mode, then global bindings (@code{describe-bindings}). +@item C-h c @var{key} +Given a key sequence @var{key}, show the name of the command that it +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 d @var{topics} @key{RET} +Display the commands and variables whose documentation matches +@var{topics} (@code{apropos-documentation}). +@item C-h e +Display the @code{*Messages*} buffer +(@code{view-echo-area-messages}). +@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, +this works for commands too. +@item C-h h +Display the @file{HELLO} file, which shows examples of various character +sets. +@item C-h i +Run Info, the GNU documentation browser (@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 p +Find packages by topic keyword (@code{finder-by-keyword}). +@item C-h s +Display the current contents of the syntax table, with 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} +Show which keys run the command named @var{command} (@code{where-is}). +@item C-h C @var{coding} @key{RET} +Describe the 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 the input method @var{method} (@code{describe-input-method}). +@item C-h L @var{language-env} @key{RET} +Display information on the character sets, coding systems, and input +methods used in language environment @var{language-env} +(@code{describe-language-environment}). +@item C-h F @var{function} @key{RET} +Enter Info and goes to the node that documents the Emacs function +@var{function} (@code{Info-goto-emacs-command-node}). +@item C-h K @var{key} +Enter Info and goes to the node that documents the key sequence +@var{key} (@code{Info-goto-emacs-key-command-node}). +@item C-h S @var{symbol} @key{RET} +Display the Info documentation on symbol @var{symbol} according to the +programming language you are editing (@code{info-lookup-symbol}). +@item C-h . +Display the help message for a special text area, if point is in one +(@code{display-local-help}). (These include, for example, links in +@samp{*Help*} buffers.) +@end table + +@node Key Help +@section Documentation for a Key + +@kindex C-h c +@findex describe-key-briefly + The help commands to get information about a key sequence are +@kbd{C-h c} and @w{@kbd{C-h k}}. @kbd{C-h c @var{key}} displays in +the echo area the name of the command that @var{key} is bound to. For +example, @kbd{C-h c C-f} displays @samp{forward-char}. Since command +names are chosen to describe what the commands do, this gives you 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. +It displays this information in a window, since it may not fit in the +echo area. + +@kindex C-h K +@findex Info-goto-emacs-key-command-node + To find the documentation of a key sequence @var{key}, type @kbd{C-h +K @var{key}}. This displays the appropriate manual section which +contains the documentation of @var{key}. + + @kbd{C-h c}, @kbd{C-h k} and @kbd{C-h K} work for any sort of key +sequences, including function keys, menus, and mouse events. For +instance, after @kbd{C-h k} you can select a menu item from the menu +bar, to view the documentation string of the command it runs. + +@kindex C-h w +@findex where-is + @kbd{C-h w @var{command} @key{RET}} lists the keys that are bound to +@var{command}. It displays the list in the echo area. If it says the +command is not on any key, that means you must use @kbd{M-x} to run +it. @kbd{C-h w} runs the command @code{where-is}. + +@node Name Help +@section Help by Command or Variable Name + +@kindex C-h f +@findex describe-function + @kbd{C-h f @var{function} @key{RET}} (@code{describe-function}) +displays the documentation of Lisp function @var{function}, in a +window. Since commands are Lisp functions, you can use this method to +view the documentation of any command whose name you know. 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 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 completion abbreviations that +work in @kbd{M-x} don't work in @kbd{C-h f}. An abbreviation that is +unique among command names may not be unique among all function names. + + If you type @kbd{C-h f @key{RET}}, it describes the function called +by the innermost Lisp expression in the buffer around point, +@emph{provided} that function name is a valid, defined Lisp function. +(That name appears as the default while you enter the argument.) 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 @kbd{C-h f @key{RET}} will describe the +function @code{make-vector}. + + @kbd{C-h f} is also useful just to verify that you spelled a +function name correctly. If the minibuffer prompt for @kbd{C-h f} +shows the function name from the buffer as the default, it means that +name is defined as a Lisp function. Type @kbd{C-g} to cancel the +@kbd{C-h f} command if you don't really want to view the +documentation. + +@kindex C-h v +@findex describe-variable + @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, if that is the name of a +defined Lisp variable. @xref{Variables}. + + Help buffers that describe Emacs variables and functions normally +have hyperlinks to the corresponding source definition, if you have +the source files installed. (@xref{Hyperlinking}.) If you know Lisp +(or C), this provides the ultimate documentation. If you don't know +Lisp, you should learn it. (The Introduction to Emacs Lisp +Programming, available from the FSF through fsf.org, is a good way to +get started.) If Emacs feels you are just @emph{using} it, treating +it as an object program, its feelings may be hurt. For real intimacy, +read the Emacs source code. + +@kindex C-h F +@findex Info-goto-emacs-command-node + To find a function's documentation in a manual, use @kbd{C-h F} +(@code{Info-goto-emacs-command-node}). This knows about various +manuals, not just the Emacs manual, and finds the right one. + +@node Apropos +@section Apropos + + The @dfn{apropos} commands answer questions like, ``What are the +commands for working with files?'' More precisely, you specify an +@dfn{apropos pattern}, which means either a word, a list of words, or +a regular expression. Each apropos command displays a list of items +that match the pattern, in a separate buffer. + +@table @kbd +@item C-h a @var{pattern} @key{RET} +Search for commands whose names match @var{pattern}. + +@item M-x apropos @key{RET} @var{pattern} @key{RET} +Search for functions and variables whose names match @var{pattern}. +Both interactive functions (commands) and noninteractive functions can +be found by this command. + +@item M-x apropos-variable @key{RET} @var{pattern} @key{RET} +Search for user-option variables whose names match @var{pattern}. + +@item M-x apropos-value @key{RET} @var{pattern} @key{RET} +Search for functions whose definitions @var{pattern}, and variables +whose values match @var{pattern}. + +@item C-h d @var{pattern} @key{RET} +Search for functions and variables whose @strong{documentation +strings} match @var{pattern}. +@end table + +@kindex C-h a +@findex apropos-command +@cindex apropos + The simplest kind of apropos pattern is one word. Anything which +contains that word matches the pattern. Thus, to find the commands +that work on files, type @kbd{C-h a file @key{RET}}. This displays a +list of all command names that contain @samp{file}, including +@code{copy-file}, @code{find-file}, and so on. Each command name +comes with a brief description and a list of keys you can currently +invoke it with. In our 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. + + For more information about a function definition, variable or symbol +property listed in the apropos buffer, you can click on it with +@kbd{Mouse-1} or @kbd{Mouse-2}, or move there and type @key{RET}. + + When you specify more than one word in the apropos pattern, a name +must contain at least two of the words in order to match. Thus, if +you are looking for commands to kill a chunk of text before point, you +could try @kbd{C-h a kill back backward behind before @key{RET}}. The +real command name @code{kill-backward} will match that; if there were +a command @code{kill-text-before}, it would also match, since it +contains two of the specified words. + + For even greater flexibility, you can specify a regular expression +(@pxref{Regexps}). An apropos pattern is interpreted as a regular +expression if it contains any of the regular expression special +characters, @samp{^$*+?.\[}. + + Following the conventions for naming Emacs commands, here are some +words that you'll find useful in apropos patterns. By using them in +@kbd{C-h a}, you will also get a feel for the naming conventions. + +@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 + Use @kbd{M-x apropos} instead of @kbd{C-h a} to list all the Lisp +symbols that match an apropos pattern, not just the symbols that are +commands. This command does not list key bindings by default; specify +a numeric argument if you want it to list them. + +@findex apropos-variable + Use @kbd{M-x apropos-variable} to list user-customizable variables +that match an apropos pattern. If you specify a prefix argument, it +lists all matching variables. + +@kindex C-h d +@findex apropos-documentation + The @code{apropos-documentation} command is like @code{apropos} +except that it searches documentation strings instead of symbol names +for matches. + +@findex apropos-value + The @code{apropos-value} command is like @code{apropos} except that +it searches variables' values for matches for the apropos pattern. +With a prefix argument, it also checks symbols' function definitions +and property lists. + +@vindex apropos-do-all + If the variable @code{apropos-do-all} is non-@code{nil}, the apropos +commands always behave as if they had been given a prefix argument. + +@vindex apropos-sort-by-scores +@cindex apropos search results, order by score + By default, apropos lists the search results in alphabetical order. +If the variable @code{apropos-sort-by-scores} is non-@code{nil}, the +apropos commands try to guess the relevance of each result, and +display the most relevant ones first. + +@vindex apropos-documentation-sort-by-scores + By default, apropos lists the search results for +@code{apropos-documentation} in order of relevance of the match. If +the variable @code{apropos-documentation-sort-by-scores} is +@code{nil}, apropos lists the symbols found in alphabetical order. + +@node Help Mode +@section Help Mode Commands + + Help buffers provide the same commands as 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-1 +@itemx Mouse-2 +Follow a cross reference that you click on. +@item C-c C-c +Show all documentation about the symbol at point. +@end table + + When a function name (@pxref{M-x,, Running Commands by Name}), +variable name (@pxref{Variables}), or face name (@pxref{Faces}) +appears in the documentation, it normally appears inside paired +single-quotes. To view the documentation of that command, variable or +face, you can click on the name with @kbd{Mouse-1} or @kbd{Mouse-2}, +or move point there and type @key{RET}. Use @kbd{C-c C-b} to retrace +your steps. + +@cindex URL, viewing in help +@cindex help, viewing web pages +@cindex viewing web pages in help +@cindex web pages, viewing in help +@findex browse-url + You can follow cross references to URLs (web pages) also. This uses +the @code{browse-url} command to view the page in the browser you +choose. @xref{Browse-URL}. + +@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 to move point to cross references in +the help text. @key{TAB} (@code{help-next-ref}) moves point down to +the next cross reference. @kbd{S-@key{TAB}} moves up to the previous +cross reference (@code{help-previous-ref}). + + To view all documentation about any symbol name that appears in the +text, move point to the symbol name and type @kbd{C-c C-c} +(@code{help-follow-symbol}). This shows all available documentation +about the symbol as a variable, function and/or face. As above, use +@kbd{C-c C-b} to retrace your steps. + +@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: + +@multitable {convenience} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@item abbrev@tab abbreviation handling, typing shortcuts, macros. +@item bib@tab code related to the @code{bib} bibliography processor. +@item c@tab support for the C language and related languages. +@item calendar@tab calendar and time management support. +@item comm@tab communications, networking, remote access to files. +@item convenience@tab convenience features for faster editing. +@item data@tab support for editing files of data. +@item docs@tab support for Emacs documentation. +@item emulations@tab emulations of other editors. +@item extensions@tab Emacs Lisp language extensions. +@item faces@tab support for multiple fonts. +@item files@tab support for editing and manipulating files. +@item frames@tab support for Emacs frames and window systems. +@item games@tab games, jokes and amusements. +@item hardware@tab support for interfacing with exotic hardware. +@item help@tab support for on-line help systems. +@item hypermedia@tab support for links between text or other media types. +@item i18n@tab internationalization and alternate character-set support. +@item internal@tab code for Emacs internals, build process, defaults. +@item languages@tab specialized modes for editing programming languages. +@item lisp@tab Lisp support, including Emacs Lisp. +@item local@tab code local to your site. +@item maint@tab maintenance aids for the Emacs development group. +@item mail@tab modes for electronic-mail handling. +@item matching@tab various sorts of searching and matching. +@item mouse@tab mouse support. +@item multimedia@tab images and sound support. +@item news@tab support for netnews reading and posting. +@item oop@tab support for object-oriented programming. +@item outlines@tab support for hierarchical outlining. +@item processes@tab process, subshell, compilation, and job control support. +@item terminals@tab support for terminal types. +@item tex@tab supporting code for the @TeX{} formatter. +@item tools@tab programming tools. +@item unix@tab front-ends/assistants for, or emulators of, UNIX-like features. +@item wp@tab word processing. +@end multitable + +@node Language Help +@section Help for International Language Support + + You can use the command @kbd{C-h L} +(@code{describe-language-environment}) to get information about a +specific language environment. @xref{Language Environments}. This +tells you which languages this language environment supports. It also +lists the character sets, coding systems, and input methods that work +with this language environment, and finally 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 an +input method---either a specified input method, or by default the +input method currently in use. @xref{Input Methods}. + + The command @kbd{C-h C} (@code{describe-coding-system}) describes +coding systems---either a specified coding system, or the ones +currently in use. @xref{Coding Systems}. + +@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 browses +structured documentation files. The entire Emacs manual is available +within Info, along with many other manuals for the GNU system. Type +@kbd{h} after entering Info to run a tutorial on using Info. + +@cindex find Info manual by its file name + With a numeric argument @var{n}, @kbd{C-h i} selects the Info buffer +@samp{*info*<@var{n}>}. This is useful if you want to browse multiple +Info manuals simultaneously. If you specify just @kbd{C-u} as the +prefix argument, @kbd{C-h i} prompts for the name of a documentation +file, so you can browse a file which doesn't have an entry in the +top-level Info menu. + + The help commands @kbd{C-h F @var{function} @key{RET}} and @kbd{C-h +K @var{key}}, described above, enter Info and go straight to the +documentation of @var{function} or @var{key}. + +@kindex C-h S +@findex info-lookup-symbol + When editing a program, if you have an Info version of the manual +for the programming language, you can use @kbd{C-h S} +(@code{info-lookup-symbol}) to find symbol (keyword, function or +variable) in the proper manual. 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 you +typed, use @kbd{C-h l} (@code{view-lossage}). @kbd{C-h l} displays +the last 100 characters you typed in Emacs. 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 e +@findex view-echo-area-messages + To review recent echo area messages, use @kbd{C-h e} +(@code{view-echo-area-messages}). This displays the buffer +@code{*Messages*}, where those messages are kept. + +@kindex C-h m +@findex describe-mode + Each Emacs major mode typically redefines a few keys and makes other +changes in how editing works. @kbd{C-h m} (@code{describe-mode}) +displays documentation on the current major mode, which normally +describes the commands and features 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}) show other information about the current +environment within Emacs. @kbd{C-h b} displays a list of all the key +bindings now in effect: first the local bindings of the current minor +modes, 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 list of subcommands 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.) + +@node Help Files +@section Help Files + + The Emacs help commands described above display dynamic help based +on the current state within Emacs, or refer to manuals. Other help +commands display pre-written, static help files. These commands all +have the form @kbd{C-h C-@var{char}}; that is, @kbd{C-h} followed by a +control character. + +@kindex C-h C-c +@findex describe-copying +@kindex C-h C-d +@findex describe-distribution +@kindex C-h C-e +@findex view-emacs-problems +@kindex C-h C-f +@findex view-emacs-FAQ +@kindex C-h C-n +@findex view-emacs-news +@kindex C-h C-p +@findex describe-project +@kindex C-h C-t +@findex view-emacs-todo +@kindex C-h C-w +@findex describe-no-warranty + +@table @kbd +@item C-h C-c +Display the Emacs copying conditions (@code{describe-copying}). +These are the rules under which you can copy and redistribute Emacs. +@item C-h C-d +Display how to download or order the latest version of +Emacs and other GNU software (@code{describe-distribution}). +@item C-h C-e +Display the list of known Emacs problems, sometimes with suggested +workarounds (@code{view-emacs-problems}). +@item C-h C-f +Display the Emacs frequently-answered-questions list (@code{view-emacs-FAQ}). +@item C-h C-n +Display the Emacs ``news'' file, which lists new features in the most +recent version of Emacs (@code{view-emacs-news}). +@item C-h C-p +Display general information about the GNU Project +(@code{describe-project}). +@item C-h C-t +Display the Emacs to-do list (@code{view-todo}). +@item C-h C-w +Display the full details on the complete absence of warranty for GNU +Emacs (@code{describe-no-warranty}). +@end table + +@node Help Echo +@section Help on Active Text and Tooltips + +@cindex tooltips +@cindex balloon help + When a region of text is ``active,'' so that you can select it with +the mouse or a key like @kbd{RET}, it often has associated help text. +For instance, most parts of the mode line have help text. On +graphical displays, the help text is displayed as a ``tooltip'' +(sometimes known as ``balloon help''), when you move the mouse over +the active text. @xref{Tooltips}. On some systems, it is shown in +the echo area. On text-only terminals, if Emacs cannot follow the +mouse, it cannot show the help text on mouse-over. + +@kindex C-h . +@findex display-local-help +@vindex help-at-pt-display-when-idle + You can also access text region help info using the keyboard. The +command @kbd{C-h .} (@code{display-local-help}) displays any help text +associated with the text at point, using the echo area. If you want +help text to be displayed automatically whenever it is available at +point, set the variable @code{help-at-pt-display-when-idle} to +@code{t}. + +@ignore + arch-tag: 6f33ab62-bc75-4367-8057-fd67cc15c3a1 +@end ignore diff --git a/doc/emacs/indent.texi b/doc/emacs/indent.texi new file mode 100644 index 00000000000..568b54897fa --- /dev/null +++ b/doc/emacs/indent.texi @@ -0,0 +1,244 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, +@c 2003, 2004, 2005, 2006, 2007 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. + +@table @kbd +@item @key{TAB} +Indent the 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 the previous and the current line (@code{delete-indentation}). +This would cancel the effect of a preceding @kbd{C-j}. +@item C-M-o +Split the current line at point; text on the line after point becomes a +new line indented to the same column where point is located +(@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 lines in the region to the same column (@code{indent-region}). +@item C-x @key{TAB} +Shift lines in the region 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 + + Emacs supports four general categories of operations that could all +be called `indentation': + +@enumerate +@item +Insert a tab character. You can type @kbd{C-q @key{TAB}} to do this. + +A tab character is displayed as a stretch of whitespace which extends +to the next display tab stop position, and the default width of a tab +stop is eight. @xref{Text Display}, for more details. + +@item +Insert whitespace up to the next tab stop. You can set tab stops at +your choice of column positions, then type @kbd{M-i} to advance to the +next tab stop. The default tab stop settings have a tab stop every +eight columns, which means by default @kbd{M-i} inserts a tab +character. To set the tab stops, use @kbd{M-x edit-tab-stops}. + +@item +Align a line with the previous line. More precisely, the command +@kbd{M-x indent-relative} indents the current line under the beginning +of some word in the previous line. In Fundamental mode and in Text +mode, @key{TAB} runs the command @code{indent-relative}. + +@item +The most sophisticated method is @dfn{syntax-driven indentation}. +Most programming languages have an indentation convention. For Lisp +code, lines are indented according to their nesting in parentheses. C +code uses the same general idea, but many details are different. + +@kindex TAB +Type @key{TAB} to do syntax-driven indentation, in a mode that +supports it. It realigns the current line according with the syntax +of the preceding lines. No matter where in the line you are when you +type @key{TAB}, it aligns the line as a whole. +@end enumerate + + Normally, most of the above methods insert an optimal mix of tabs and +spaces to align to the desired column. @xref{Just Spaces}, for how to +disable use of tabs. However, @kbd{C-q @key{TAB}} always inserts a +tab, even when tabs are disabled for the indentation commands. + +@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, if any, +or else at the end of 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. They apply to all the lines that begin in the region. +@kbd{C-M-\} (@code{indent-region}) 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. + +@cindex remove indentation + To remove all indentation from all of the lines in the region, +invoke @kbd{C-x @key{TAB}} with a large negative argument, such as +-1000. + +@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 the next 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, @code{indent-relative} runs @code{tab-to-tab-stop} +@ifnottex +(@pxref{Tab Stops}), +@end ifnottex +@iftex +(see next section), +@end iftex +unless it is called with a numeric argument, in which case it does +nothing. + + @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 @kbd{M-i} (@code{tab-to-tab-stop}). +This command inserts indentation before point, enough to reach the +next tab stop column. + +@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. The buffer uses Overwrite mode +(@pxref{Minor Modes}). @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{Text Display}, +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, so altering the variable affects only the current buffer, +but there is a default value which you can change as well. +@xref{Locals}. + + A tab is not always displayed in the same way. By default, tabs are +eight columns wide, but some people like to customize their tools to +use a different tab width. So by using spaces only, you can make sure +that your file looks the same regardless of the tab width setting. + +@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 two +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. + +@ignore + arch-tag: acc07de7-ae11-4ee8-a159-cb59c473f0fb +@end ignore diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi new file mode 100644 index 00000000000..b626bfab385 --- /dev/null +++ b/doc/emacs/killing.texi @@ -0,0 +1,699 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. + +@node Killing, Yanking, Mark, Top +@chapter Killing and Moving Text + +@ifnottex +@raisesections +@end ifnottex + + @dfn{Killing} means erasing text and copying it into the @dfn{kill +ring}, from which you can bring it back into the buffer by +@dfn{yanking} it. (Some systems use the terms ``cutting'' and +``pasting'' for these operations.) This is the most common way of +moving or copying text within Emacs. Killing and yanking 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. + +@iftex +@section Deletion and Killing +@end iftex + +@cindex killing text +@cindex cutting text +@cindex deletion + Most commands which erase text from the buffer save it in the kill +ring. These commands are known as @dfn{kill} commands. The commands +that erase text but do not save it in the kill ring are known as +@dfn{delete} commands. The @kbd{C-x u} (@code{undo}) command +(@pxref{Undo}) can undo both kill and delete commands; the importance +of the kill ring is that you can also yank the text in a different +place or places. Emacs has only one kill ring for all buffers, so you +can kill text in one buffer and yank it in another buffer. + + 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 erase significant amounts of nontrivial +data generally do a kill operation instead. The commands' names and +individual descriptions use the words @samp{kill} and @samp{delete} to +say which kind of operation they perform. + +@vindex kill-read-only-ok +@cindex read-only text, killing + You cannot kill read-only text, since such text does not allow any +kind of modification. But some users like to use the kill commands to +copy read-only text into the kill ring, without actually changing it. +Therefore, the kill commands work specially in a read-only buffer: +they move over text, and copy it to the kill ring, without actually +deleting it from the buffer. Normally, kill commands beep and display +an error message when this happens. But if you set the variable +@code{kill-read-only-ok} to a non-@code{nil} value, they just print a +message in the echo area to explain why the text has not been erased. + + You can also use the mouse to kill and yank. @xref{Cut and Paste}. + +@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 + +@need 1500 +@node Deletion +@subsection Deletion +@findex delete-backward-char +@findex delete-char + + Deletion means erasing text and not saving it in the kill ring. For +the most part, the Emacs commands that delete text are those that +erase just one character or only whitespace. + +@table @kbd +@item C-d +@itemx @key{DELETE} +Delete next character (@code{delete-char}). If your keyboard has a +@key{DELETE} function key (usually located in the edit keypad), Emacs +binds it to @code{delete-char} as well. +@item @key{DEL} +@itemx @key{BS} +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 + +@kindex DEL +@kindex C-d + 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 BACKSPACE +@kindex BS +@kindex DELETE + Every keyboard has a large key which is a short distance above the +@key{RET} or @key{ENTER} key and is normally used for erasing what you +have typed. It may be labeled @key{DEL}, @key{BACKSPACE}, @key{BS}, +@key{DELETE}, or even with a left arrow. Regardless of the label on +the key, in Emacs it called @key{DEL}, and it should delete one +character backwards. + + Many keyboards (including standard PC keyboards) have a +@key{BACKSPACE} key a short ways above @key{RET} or @key{ENTER}, and a +@key{DELETE} key elsewhere. In that case, the @key{BACKSPACE} key is +@key{DEL}, and the @key{DELETE} key is equivalent to @kbd{C-d}---or it +should be. + + Why do we say ``or it should be''? When Emacs starts up using a +graphical display, it determines automatically which key or keys should be +equivalent to @key{DEL}. As a result, @key{BACKSPACE} and/or @key{DELETE} +keys normally do the right things. But in some unusual cases Emacs +gets the wrong information from the system. If these keys don't do +what they ought to do, you need to tell Emacs which key to use for +@key{DEL}. @xref{DEL Does Not Delete}, for how to do this. + +@findex normal-erase-is-backspace-mode + On most text-only terminals, Emacs cannot tell which keys the +keyboard really has, so it follows a uniform plan which may or may not +fit your keyboard. The uniform plan is that the @acronym{ASCII} @key{DEL} +character deletes, and the @acronym{ASCII} @key{BS} (backspace) character asks +for help (it is the same as @kbd{C-h}). If this is not right for your +keyboard, such as if you find that the key which ought to delete backwards +enters Help instead, see @ref{DEL Does Not Delete}. + +@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. With a prefix argument, this only +deletes spaces and tab characters before 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 if there were none before). With a numeric argument @var{n}, it +leaves @var{n} spaces after point. + + @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). On a solitary blank line, it deletes that 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}). +@item C-S-backspace +Kill an entire line at once (@code{kill-whole-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 not killed). 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}. + +@kindex C-S-backspace +@findex kill-whole-line + @kbd{C-S-backspace} (@code{kill-whole-line}) will kill a whole line +including its newline regardless of the position of point within the +line. Note that many character terminals will prevent you from typing +the key sequence @kbd{C-S-backspace}. + +@node Other Kill Commands +@subsection Other Kill Commands +@findex kill-region +@kindex C-w + +@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 the following balanced expression (@code{kill-sexp}). @xref{Expressions}. +@item M-z @var{char} +Kill through the next occurrence of @var{char} (@code{zap-to-char}). +@end table + + The most general kill command 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}); balanced expressions, with @kbd{C-M-k} +(@pxref{Expressions}); and sentences, with @kbd{C-x @key{DEL}} and +@kbd{M-k} (@pxref{Sentences}).@refill + +@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. This is very safe +because Emacs remembers many recent kills, not just the last one. + +@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}). Some systems call this ``copying.'' +@item C-M-w +Append next kill to last batch of killed text (@code{append-next-kill}). +@end table + + On graphical displays with window systems, if there is a current +selection in some other application, and you selected it more recently +than you killed any text in Emacs, @kbd{C-y} copies the selection +instead of text killed within Emacs. + +@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}). + +@cindex yanking and text properties +@vindex yank-excluded-properties + The yank commands discard certain text properties from the text that +is yanked, those that might lead to annoying results. For instance, +they discard text properties that respond to the mouse or specify key +bindings. The variable @code{yank-excluded-properties} specifies the +properties to discard. Yanking of register contents and rectangles +also discard these properties. + +@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 between @samp{is} +and @samp{text}, 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} loops back around 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 from +the specified kill ring entry, counting back from the most recent as +1. 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 convenient methods 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 the contents of a specified buffer. +@item M-x prepend-to-buffer +Prepend region to the contents of a specified buffer. +@item M-x copy-to-buffer +Copy region into a specified buffer, deleting that buffer's old contents. +@item M-x insert-buffer +Insert the contents of a specified buffer into current buffer at point. +@item M-x append-to-file +Append region to the contents of a 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, +starting from wherever point happens to be at that moment. + + 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 whole text in buffer +@var{buffername} into the current buffer at point, and sets the mark +after the inserted text. Alternatively, you can select the other +buffer for editing, then copy 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, CUA Bindings, 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. + +@cindex mark rectangle + 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 much the same way as 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 C-x r c +Clear the region-rectangle by replacing all of its contents with spaces +(@code{clear-rectangle}). +@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 @var{string} @key{RET} +Replace rectangle contents with @var{string} on each line +(@code{string-rectangle}). +@item M-x string-insert-rectangle @key{RET} @var{string} @key{RET} +Insert @var{string} on each line of the rectangle. +@end table + + The rectangle operations fall into two classes: commands for +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 any following text 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. It is hard to define yank-popping for rectangles, +so we do not try. + +@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 the same horizontal position, but 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 +@kindex C-x r c +@findex clear-rectangle + There are two commands you can use for making blank rectangles: +@kbd{C-x r c} (@code{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{string-rectangle}) replaces the +contents of a region-rectangle with a string 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. + +@findex string-insert-rectangle + The command @kbd{M-x string-insert-rectangle} is similar to +@code{string-rectangle}, but inserts the string on each line, +shifting the original text to the right. + +@node CUA Bindings, Registers, Rectangles, Top +@section CUA Bindings +@findex cua-mode +@vindex cua-mode +@cindex CUA key bindings +@vindex cua-enable-cua-keys + The command @kbd{M-x cua-mode} sets up key bindings that are +compatible with the Common User Access (CUA) system used in many other +applications. @kbd{C-x} means cut (kill), @kbd{C-c} copy, @kbd{C-v} +paste (yank), and @kbd{C-z} undo. Standard Emacs commands like +@kbd{C-x C-c} still work, because @kbd{C-x} and @kbd{C-c} only take +effect when the mark is active (and the region is highlighted). +However, if you don't want to override these bindings in Emacs at all, +set @code{cua-enable-cua-keys} to @code{nil}. + + In CUA mode, using @kbd{Shift} together with the movement keys +activates and highlights the region over which they move. The +standard (unshifted) movement keys deactivate the mark, and typed text +replaces the active region as in Delete-Selection mode +(@pxref{Mouse Commands}). + + To enter an Emacs command like @kbd{C-x C-f} while the mark is +active, use one of the following methods: either hold @kbd{Shift} +together with the prefix key, e.g. @kbd{S-C-x C-f}, or quickly type +the prefix key twice, e.g. @kbd{C-x C-x C-f}. + +@cindex rectangle highlighting + CUA mode provides enhanced rectangle support with visible +rectangle highlighting. Use @kbd{C-RET} to start a rectangle, +extend it using the movement commands, and cut or copy it using +@kbd{C-x} or @kbd{C-c}. @kbd{RET} moves the cursor to the next +(clockwise) corner of the rectangle, so you can easily expand it in +any direction. Normal text you type is inserted to the left or right +of each line in the rectangle (on the same side as the cursor). + + With CUA you can easily copy text and rectangles into and out of +registers by providing a one-digit numeric prefix to the kill, copy, +and yank commands, e.g. @kbd{C-1 C-c} copies the region into register +@code{1}, and @kbd{C-2 C-v} yanks the contents of register @code{2}. + +@cindex global mark + CUA mode also has a global mark feature which allows easy moving and +copying of text between buffers. Use @kbd{C-S-SPC} to toggle the +global mark on and off. When the global mark is on, all text that you +kill or copy is automatically inserted at the global mark, and text +you type is inserted at the global mark rather than at the current +position. + + For example, to copy words from various buffers into a word list in +a given buffer, set the global mark in the target buffer, then +navigate to each of the words you want in the list, mark it (e.g. with +@kbd{S-M-f}), copy it to the list with @kbd{C-c} or @kbd{M-w}, and +insert a newline after the word in the target list by pressing +@key{RET}. + +@ifnottex +@lowersections +@end ifnottex + +@ignore + arch-tag: d8da8f96-0928-449a-816e-ff2d3497866c +@end ignore diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi new file mode 100644 index 00000000000..16526e1a2b8 --- /dev/null +++ b/doc/emacs/kmacro.texi @@ -0,0 +1,616 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Keyboard Macros, Files, Fixit, Top +@chapter Keyboard Macros +@cindex defining keyboard macros +@cindex keyboard macro + + In this chapter we describe how to record a sequence of editing +commands so you can repeat it conveniently later. + + A @dfn{keyboard macro} is a command defined by an Emacs user to stand for +another sequence of keys. For example, if you discover that you are +about to type @kbd{C-n M-d C-d} forty times, you can speed your work by +defining a keyboard macro to do @kbd{C-n M-d C-d}, and then executing +it 39 more times. + + You define a keyboard macro by executing and recording the commands +which are its definition. Put differently, as you define a keyboard +macro, the definition is being executed for the first time. This way, +you can see the effects of your commands, so that you don't have to +figure them out in your head. When you close the definition, 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. + + 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. + +@menu +* Basic Keyboard Macro:: Defining and running keyboard macros. +* Keyboard Macro Ring:: Where previous keyboard macros are saved. +* Keyboard Macro Counter:: Inserting incrementing numbers in macros. +* Keyboard Macro Query:: Making keyboard macros do different things each time. +* Save Keyboard Macro:: Giving keyboard macros names; saving them in files. +* Edit Keyboard Macro:: Editing keyboard macros. +* Keyboard Macro Step-Edit:: Interactively executing and editing a keyboard + macro. +@end menu + +@node Basic Keyboard Macro +@section Basic Use + +@table @kbd +@item @key{F3} +@itemx C-x ( +Start defining a keyboard macro (@code{kmacro-start-macro}). +@item @key{F4} +If a keyboard macro is being defined, end the definition; otherwise, +execute the most recent keyboard macro +(@code{kmacro-end-or-call-macro}). +@item C-x ) +End the definition of a keyboard macro (@code{kmacro-end-macro}). +@item C-x e +Execute the most recent keyboard macro (@code{kmacro-end-and-call-macro}). +First end the definition of the keyboard macro, if currently defining it. +To immediately execute the keyboard macro again, just repeat the @kbd{e}. +@item C-u C-x ( +Re-execute last keyboard macro, then add more keys to its definition. +@item C-u C-u C-x ( +Add more keys to the last keyboard macro without re-executing it. +@item C-x C-k r +Run the last keyboard macro on each line that begins in the region +(@code{apply-macro-to-region-lines}). +@end table + +@kindex F3 +@kindex F4 +@kindex C-x ( +@kindex C-x ) +@kindex C-x e +@findex kmacro-start-macro +@findex kmacro-end-macro +@findex kmacro-end-and-call-macro + To start defining a keyboard macro, type the @kbd{F3} or @kbd{C-x (} command +(@code{kmacro-start-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{F4} or @kbd{C-x )} command (@code{kmacro-end-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{kmacro-end-and-call-macro}), which may be given a +repeat count as a numeric argument to execute the macro many times. +If you enter @kbd{C-x e} while defining a macro, the macro is +terminated and executed immediately. + + After executing the macro with @kbd{C-x e}, you can use @kbd{e} +repeatedly to immediately repeat the macro one or more times. For example, + +@example +C-x ( xyz C-x e e e +@end example + +@noindent +inserts @samp{xyzxyzxyzxyz} in the current buffer. + + @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}}). + + The key @key{F4} is like a combination of @kbd{C-x )} and @kbd{C-x +e}. If you're defining a macro, @key{F4} ends the definition. +Otherwise it executes the last macro. For example, + +@example +F3 xyz F4 F4 F4 +@end example + +@noindent +inserts @samp{xyzxyzxyz} in the current buffer. + + 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. + + When a command reads an argument with the minibuffer, your +minibuffer input becomes part of the macro along with the command. So +when you replay the macro, the command gets the same argument as +when you entered the macro. For example, + +@example +C-x ( C-a C-@key{SPC} C-n M-w C-x b f o o @key{RET} C-y C-x b @key{RET} C-x ) +@end example + +@noindent +defines a macro that copies the current line into the buffer +@samp{foo}, then returns to the original buffer. + + 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 sometimes works badly 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. + + After you have terminated the definition of a keyboard macro, you can add +to the end of its definition by typing @kbd{C-u F3} or @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 also add to the end of the definition of the last keyboard +macro without re-executing it by typing @kbd{C-u C-u C-x (}. + + The variable @code{kmacro-execute-before-append} specifies whether +a single @kbd{C-u} prefix causes the existing macro to be re-executed +before appending to it. + +@findex apply-macro-to-region-lines +@kindex C-x C-k r + The command @kbd{C-x C-k r} (@code{apply-macro-to-region-lines}) +repeats the last defined keyboard macro on each line that begins in +the region. It does this line by line, by moving point to the +beginning of the line and then executing the macro. + +@node Keyboard Macro Ring +@section The Keyboard Macro Ring + + All defined keyboard macros are recorded in the ``keyboard macro ring,'' +a list of sequences of keys. There is only one keyboard macro ring, +shared by all buffers. + +@table @kbd +@item C-x C-k C-k +Execute the keyboard macro at the head of the ring (@code{kmacro-end-or-call-macro-repeat}). +@item C-x C-k C-n +Rotate the keyboard macro ring to the next macro (defined earlier) +(@code{kmacro-cycle-ring-next}). +@item C-x C-k C-p +Rotate the keyboard macro ring to the previous macro (defined later) +(@code{kmacro-cycle-ring-previous}). +@end table + + All commands which operate on the keyboard macro ring use the +same @kbd{C-x C-k} prefix. Most of these commands can be executed and +repeated immediately after each other without repeating the @kbd{C-x +C-k} prefix. For example, + +@example +C-x C-k C-p C-p C-k C-k C-k C-n C-n C-k C-p C-k C-d +@end example + +@noindent +will rotate the keyboard macro ring to the ``second previous'' macro, +execute the resulting head macro three times, rotate back to the +original head macro, execute that once, rotate to the ``previous'' +macro, execute that, and finally delete it from the macro ring. + +@findex kmacro-end-or-call-macro-repeat +@kindex C-x C-k C-k + The command @kbd{C-x C-k C-k} (@code{kmacro-end-or-call-macro-repeat}) +executes the keyboard macro at the head of the macro ring. You can +repeat the macro immediately by typing another @kbd{C-k}, or you can +rotate the macro ring immediately by typing @kbd{C-n} or @kbd{C-p}. + + When a keyboard macro is being defined, @kbd{C-x C-k C-k} behaves like +@kbd{C-x )} except that, immediately afterward, you can use most key +bindings of this section without the @kbd{C-x C-k} prefix. For +instance, another @kbd{C-k} will re-execute the macro. + +@findex kmacro-cycle-ring-next +@kindex C-x C-k C-n +@findex kmacro-cycle-ring-previous +@kindex C-x C-k C-p + The commands @kbd{C-x C-k C-n} (@code{kmacro-cycle-ring-next}) and +@kbd{C-x C-k C-p} (@code{kmacro-cycle-ring-previous}) rotate the +macro ring, bringing the next or previous keyboard macro to the head +of the macro ring. The definition of the new head macro is displayed +in the echo area. You can continue to rotate the macro ring +immediately by repeating just @kbd{C-n} and @kbd{C-p} until the +desired macro is at the head of the ring. To execute the new macro +ring head immediately, just type @kbd{C-k}. + + Note that Emacs treats the head of the macro ring as the ``last +defined keyboard macro.'' For instance, @kbd{C-x e} will execute that +macro, and @kbd{C-x C-k n} will give it a name. + +@ignore @c This interface is too kludgy + @c and the functionality duplicates the functionality above -- rms. +@findex kmacro-view-macro-repeat +@kindex C-x C-k C-v + The command @kbd{C-x C-k C-v} (@code{kmacro-view-macro-repeat}) +displays the last keyboard macro, or when repeated (with @kbd{C-v}), +it displays the previous macro on the macro ring, just like @kbd{C-x +C-k C-p}, but without actually rotating the macro ring. If you enter +@kbd{C-k} immediately after displaying a macro from the ring, that +macro is executed, but still without altering the macro ring. + + So while e.g. @kbd{C-x C-k C-p C-p C-p C-k C-k} makes the 3rd previous +macro the current macro and executes it twice, @kbd{C-x C-k C-v C-v +C-v C-k C-k} will display and execute the 3rd previous macro once and +then the current macro once. +@end ignore + +@ignore @c This is just too much feeping creaturism. + @c If you are reusing certain macros enough to want these, + @c you should give then names. -- rms +@findex kmacro-delete-ring-head +@kindex C-x C-k C-d + + The command @kbd{C-x C-k C-d} (@code{kmacro-delete-ring-head}) +removes and deletes the macro currently at the head of the macro +ring. You can use this to delete a macro that didn't work as +expected, or which you don't need anymore. + +@findex kmacro-swap-ring +@kindex C-x C-k C-t + + The command @kbd{C-x C-k C-t} (@code{kmacro-swap-ring}) +interchanges the head of the macro ring with the previous element on +the macro ring. + +@findex kmacro-call-ring-2nd-repeat +@kindex C-x C-k C-l + + The command @kbd{C-x C-k C-l} (@code{kmacro-call-ring-2nd-repeat}) +executes the previous (rather than the head) element on the macro ring. +@end ignore + +@vindex kmacro-ring-max + The maximum number of macros stored in the keyboard macro ring is +determined by the customizable variable @code{kmacro-ring-max}. + +@node Keyboard Macro Counter +@section The Keyboard Macro Counter + +@table @kbd +@item C-x C-k C-i +Insert the keyboard macro counter value in the buffer +(@code{kmacro-insert-counter}). +@item C-x C-k C-c +Set the keyboard macro counter (@code{kmacro-set-counter}). +@item C-x C-k C-a +Add the prefix arg to the keyboard macro counter (@code{kmacro-add-counter}). +@item C-x C-k C-f +Specify the format for inserting the keyboard macro counter +(@code{kmacro-set-format}). +@end table + + Each keyboard macro has an associated counter. Normally, the +macro counter is initialized to 0 when you start defining the macro, +and incremented by 1 after each insertion of the counter value; +that is, if you insert the macro counter twice while defining the +macro, the counter will increase by 2 on each repetition of the macro. + +@findex kmacro-insert-counter +@kindex C-x C-k C-i + The command @kbd{C-x C-k C-i} (@code{kmacro-insert-counter}) inserts +the current value of the current keyboard macro's counter, and +increments the counter by 1. You can use a numeric prefix argument to +specify a different increment. If you just specify a @kbd{C-u} +prefix, then the increment is zero, so it repeats the last inserted +counter value. For example, if you enter the following sequence while +defining a macro + +@example +C-x C-k C-i C-x C-k C-i C-u C-x C-k C-i C-x C-k C-i +@end example + +@noindent +it inserts @samp{0112} in the buffer. The next two iterations +of the macro will insert @samp{3445} and @samp{6778}. + + This command usually only makes sense while defining a keyboard +macro. But its behavior when no keyboard macro is being defined or +executed is predictable: it inserts and increments the counter of the +macro at the head of the keyboard macro ring. + +@findex kmacro-set-counter +@kindex C-x C-k C-c + The command @kbd{C-x C-k C-c} (@code{kmacro-set-counter}) sets the +current macro counter to the value of the numeric argument. If you use +it inside the macro, it operates on each repetition of the macro. If +you specify just @kbd{C-u} as the prefix, while executing the macro, +that resets the counter to the value it had at the beginning of the +current repetition of the macro (undoing any increments so far in this +repetition). + +@findex kmacro-add-counter +@kindex C-x C-k C-a + The command @kbd{C-x C-k C-a} (@code{kmacro-add-counter}) adds the +prefix argument to the current macro counter. With just @kbd{C-u} as +argument, it resets the counter to the last value inserted by any +keyboard macro. (Normally, when you use this, the last insertion +will be in the same macro and it will be the same counter.) + +@findex kmacro-set-format +@kindex C-x C-k C-f + The command @kbd{C-x C-k C-f} (@code{kmacro-set-format}) prompts for +the format to use when inserting the macro counter. The default +format is @samp{%d}, which means to insert the number in decimal +without any padding. You can exit with empty minibuffer to reset the +format to this default. You can specify any format string that the +@code{format} function accepts and that makes sense with a single +integer extra argument (@pxref{Formatting Strings,,, elisp, The Emacs +Lisp Reference Manual}). Do not put the format string inside double +quotes when you insert it in the minibuffer. + + If you use this command while no keyboard macro is being defined or +executed, the new format affects all subsequent macro definitions. +Existing macros continue to use the format in effect when they were +defined. If you set the format while defining a keyboard macro, this +affects the macro being defined from that point on, but it does not +affect subsequent macros. Execution of the macro will, at each step, +use the format in effect at that step during its definition. Changes +to the macro format during execution of a macro, like the +corresponding changes during its definition, have no effect on +subsequent macros. + + The format set by @kbd{C-x C-k C-f} does not affect insertion of +numbers stored in registers. + +@node Keyboard Macro Query +@section Executing Macros with Variations + +@table @kbd +@item C-x q +When this point is reached during macro execution, ask for confirmation +(@code{kbd-macro-query}). +@end table + +@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 Save Keyboard Macro +@section Naming and Saving Keyboard Macros + +@table @kbd +@item C-x C-k n +Give a command name (for the duration of the Emacs session) to the most +recently defined keyboard macro (@code{kmacro-name-last-macro}). +@item C-x C-k b +Bind the most recently defined keyboard macro to a key sequence (for +the duration of the session) (@code{kmacro-bind-to-key}). +@item M-x insert-kbd-macro +Insert in the buffer a keyboard macro's definition, as Lisp code. +@end table + +@cindex saving keyboard macros +@findex kmacro-name-last-macro +@kindex C-x C-k n + If you wish to save a keyboard macro for later use, you can give it +a name using @kbd{C-x C-k n} (@code{kmacro-name-last-macro}). +This reads a name as an argument using the minibuffer and defines that +name to execute the last keyboard macro, in its current form. (If you +later add to the definition of this macro, that does not alter the +name's definition as a 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 a keyboard macro, an error message is shown and nothing is +changed. + +@cindex binding keyboard macros +@findex kmacro-bind-to-key +@kindex C-x C-k b + You can also bind the last keyboard macro (in its current form) to a +key, using @kbd{C-x C-k b} (@code{kmacro-bind-to-key}) followed by the +key sequence you want to bind. You can bind to any key sequence in +the global keymap, but since most key sequences already have other +bindings, you should select the key sequence carefully. If you try to +bind to a key sequence with an existing binding (in any keymap), this +command asks you for confirmation before replacing the existing binding. + + To avoid problems caused by overriding existing bindings, the key +sequences @kbd{C-x C-k 0} through @kbd{C-x C-k 9} and @kbd{C-x C-k A} +through @kbd{C-x C-k Z} are reserved for your own keyboard macro +bindings. In fact, to bind to one of these key sequences, you only +need to type the digit or letter rather than the whole key sequences. +For example, + +@example +C-x C-k b 4 +@end example + +@noindent +will bind the last keyboard macro to the key sequence @kbd{C-x C-k 4}. + +@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 @var{macroname}, so that the macro will be reassigned the same keys +when you load the file. + +@node Edit Keyboard Macro +@section Editing a Keyboard Macro + +@table @kbd +@item C-x C-k C-e +Edit the last defined keyboard macro (@code{kmacro-edit-macro}). +@item C-x C-k e @var{name} @key{RET} +Edit a previously defined keyboard macro @var{name} (@code{edit-kbd-macro}). +@item C-x C-k l +Edit the last 100 keystrokes as a keyboard macro +(@code{kmacro-edit-lossage}). +@end table + +@findex kmacro-edit-macro +@kindex C-x C-k C-e +@kindex C-x C-k RET + You can edit the last keyboard macro by typing @kbd{C-x C-k C-e} or +@kbd{C-x C-k RET} (@code{kmacro-edit-macro}). 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 edit-kbd-macro +@kindex C-x C-k e + You can edit a named keyboard macro or a macro bound to a key by typing +@kbd{C-x C-k e} (@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. + +@findex kmacro-edit-lossage +@kindex C-x C-k l + You can edit the last 100 keystrokes as a macro by typing +@kbd{C-x C-k l} (@code{kmacro-edit-lossage}). + +@node Keyboard Macro Step-Edit +@section Stepwise Editing a Keyboard Macro + +@findex kmacro-step-edit-macro +@kindex C-x C-k SPC + You can interactively replay and edit the last keyboard +macro, one command at a time, by typing @kbd{C-x C-k SPC} +(@code{kmacro-step-edit-macro}). Unless you quit the macro using +@kbd{q} or @kbd{C-g}, the edited macro replaces the last macro on the +macro ring. + + This macro editing feature shows the last macro in the minibuffer +together with the first (or next) command to be executed, and prompts +you for an action. You can enter @kbd{?} to get a summary of your +options. These actions are available: + +@itemize @bullet{} +@item +@kbd{SPC} and @kbd{y} execute the current command, and advance to the +next command in the keyboard macro. +@item +@kbd{n}, @kbd{d}, and @kbd{DEL} skip and delete the current command. +@item +@kbd{f} skips the current command in this execution of the keyboard +macro, but doesn't delete it from the macro. +@item +@kbd{@key{TAB}} executes the current command, as well as all similar +commands immediately following the current command; for example, @key{TAB} +may be used to insert a sequence of characters (corresponding to a +sequence of @code{self-insert-command} commands). +@item +@kbd{c} continues execution (without further editing) until the end of +the keyboard macro. If execution terminates normally, the edited +macro replaces the original keyboard macro. +@item +@kbd{C-k} skips and deletes the rest of the keyboard macro, +terminates step-editing, and replaces the original keyboard macro +with the edited macro. +@item +@kbd{q} and @kbd{C-g} cancels the step-editing of the keyboard macro; +discarding any changes made to the keyboard macro. +@item +@kbd{i KEY... C-j} reads and executes a series of key sequences (not +including the final @kbd{C-j}), and inserts them before the current +command in the keyboard macro, without advancing over the current +command. +@item +@kbd{I KEY...} reads one key sequence, executes it, and inserts it +before the current command in the keyboard macro, without advancing +over the current command. +@item +@kbd{r KEY... C-j} reads and executes a series of key sequences (not +including the final @kbd{C-j}), and replaces the current command in +the keyboard macro with them, advancing over the inserted key +sequences. +@item +@kbd{R KEY...} reads one key sequence, executes it, and replaces the +current command in the keyboard macro with that key sequence, +advancing over the inserted key sequence. +@item +@kbd{a KEY... C-j} executes the current command, then reads and +executes a series of key sequences (not including the final +@kbd{C-j}), and inserts them after the current command in the keyboard +macro; it then advances over the current command and the inserted key +sequences. +@item +@kbd{A KEY... C-j} executes the rest of the commands in the keyboard +macro, then reads and executes a series of key sequences (not +including the final @kbd{C-j}), and appends them at the end of the +keyboard macro; it then terminates the step-editing and replaces the +original keyboard macro with the edited macro. +@end itemize + +@ignore + arch-tag: c1b0dd3b-3159-4c08-928f-52e763953e9c +@end ignore diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi new file mode 100644 index 00000000000..7a5b80fd348 --- /dev/null +++ b/doc/emacs/m-x.texi @@ -0,0 +1,75 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, +@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node M-x, Help, Minibuffer, Top +@chapter Running Commands by Name + + Every Emacs command has a name that you can use to run it. For +convenience, many commands also have key bindings. You can run those +commands by typing the keys, or run them by name. Most Emacs commands +have no key bindings, so the only way to run them is by name. +(@xref{Key Bindings}, for how to set up key bindings.) + + By convention, a command name consists of one or more words, +separated by hyphens; for example, @code{auto-fill-mode} or +@code{manual-entry}. Command names mostly use complete English words +to make them easier to remember. + +@kindex M-x + To run a command by name, start with @kbd{M-x}, type the command +name, then terminate it with @key{RET}. @kbd{M-x} uses the minibuffer +to read the command name. The string @samp{M-x} appears at the +beginning of the minibuffer as a @dfn{prompt} to remind you to enter a +command name to be run. @key{RET} exits the minibuffer and runs the +command. @xref{Minibuffer}, for more information on the minibuffer. + + You can use completion to enter the command name. For example, +to invoke the command @code{forward-char}, you can type + +@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}. The existence of a key binding does not stop you +from running the command by name. + + To cancel the @kbd{M-x} and not run a command, type @kbd{C-g} instead +of entering the command name. This takes you back to command level. + + To pass a numeric argument to the command you are invoking with +@kbd{M-x}, specify the numeric argument before @kbd{M-x}. The +argument value appears in the prompt while the command name is being +read, and finally @kbd{M-x} passes the argument to that command. + +@vindex suggest-key-bindings + When the command you run with @kbd{M-x} has a key binding, Emacs +mentions this in the echo area after running the command. For +example, if you type @kbd{M-x forward-word}, the message says that you +can run the same command by typing @kbd{M-f}. You can turn off these +messages by setting the variable @code{suggest-key-bindings} to +@code{nil}. + + In this manual, when we speak of running a command by name, we often +omit the @key{RET} that terminates the name. Thus we might say +@kbd{M-x auto-fill-mode} rather than @kbd{M-x auto-fill-mode +@key{RET}}. We mention the @key{RET} only for emphasis, such as when +the command is followed by 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. + +@ignore + arch-tag: b67bff53-9628-4666-b94e-eda972a7ba56 +@end ignore diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi new file mode 100644 index 00000000000..28d7f43df8e --- /dev/null +++ b/doc/emacs/macos.texi @@ -0,0 +1,429 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2000, 2001, 2002, 2003, 2004, +@c 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Mac OS, Microsoft Windows, Antinews, Top +@appendix Emacs and Mac OS +@cindex Mac OS +@cindex Macintosh + + This section briefly describes the peculiarities of using Emacs +under Mac OS with native window system support. For Mac OS X, Emacs +can be built either without window system support, with X11, or with +Carbon API. This section only applies to the Carbon build. For Mac +OS Classic, Emacs can be built with or without Carbon API, and this +section applies to either of them because they run on the native +window system. + + Emacs built on Mac OS X supports most of its major features except +display support of PostScript images. The following features of Emacs +are not supported on Mac OS Classic: unexec (@code{dump-emacs}), +asynchronous subprocesses (@code{start-process}), and networking +(@code{open-network-stream}). As a result, packages such as Gnus, +GUD, and Comint do not work. Synchronous subprocesses +(@code{call-process}) are supported on non-Carbon build, but +specially-crafted external programs are needed. Since external +programs to handle commands such as @code{print-buffer} and +@code{diff} are not available on Mac OS Classic, they are not +supported. Non-Carbon build on Mac OS Classic does not support some +features such as file dialogs, drag-and-drop, and Unicode menus. + +@menu +* Input: Mac Input. Keyboard and mouse input on Mac. +* Intl: Mac International. International character sets on Mac. +* Env: Mac Environment Variables. Setting environment variables for Emacs. +* Directories: Mac Directories. Volumes and directories on Mac. +* Font: Mac Font Specs. Specifying fonts on Mac. +* Functions: Mac Functions. Mac-specific Lisp functions. +@end menu + +@node Mac Input +@section Keyboard and Mouse Input on Mac +@cindex Meta (Mac OS) +@cindex keyboard coding (Mac OS) + +@vindex mac-control-modifier +@vindex mac-command-modifier +@vindex mac-option-modifier +@vindex mac-function-modifier + On Mac, Emacs can use @key{control}, @key{command}, @key{option}, and +laptop @key{function} keys as any of Emacs modifier keys except +@key{SHIFT} (i.e., @key{ALT}, @key{CTRL}, @key{HYPER}, @key{META}, and +@key{SUPER}). The assignment is controlled by the variables +@code{mac-control-modifier}, @code{mac-command-modifier}, +@code{mac-option-modifier}, and @code{mac-function-modifier}. The value +for each of these variables can be one of the following symbols: +@code{alt}, @code{control}, @code{hyper}, @code{meta}, @code{super}, and +@code{nil} (no particular assignment). By default, the @key{control} +key works as @key{CTRL}, and the @key{command} key as @key{META}. + + For the @key{option} key, if @code{mac-option-modifier} is set to +@code{nil}, which is the default, the key works as the normal +@key{option} key, i.e., dead-key processing will work. This is useful +for entering non-@acronym{ASCII} Latin characters directly from the +Mac keyboard, for example. + + Emacs recognizes the setting in the Keyboard control panel (Mac OS +Classic) or the International system preference pane (Mac OS X) and +supports international and alternative keyboard layouts (e.g., Dvorak). +Selecting one of the layouts from the keyboard layout pull-down menu +will affect how the keys typed on the keyboard are interpreted. + +@vindex mac-pass-command-to-system +@vindex mac-pass-control-to-system + Mac OS intercepts and handles certain key combinations (e.g., +@key{command}-@key{SPC} for switching input languages). These will not +be passed to Emacs. One can disable this interception by setting +@code{mac-pass-command-to-system} or @code{mac-pass-control-to-system} +to @code{nil}. + +@vindex mac-emulate-three-button-mouse + Especially for one-button mice, the multiple button feature can be +emulated by setting @code{mac-emulate-three-button-mouse} to @code{t} +or @code{reverse}. If set to @code{t} (@code{reverse}, respectively), +pressing the mouse button with the @key{option} key is recognized as +the second (third) button, and that with the @key{command} key is +recognized as the third (second) button. + +@vindex mac-wheel-button-is-mouse-2 + For multi-button mice, the wheel button and the secondary button are +recognized as the second and the third button, respectively. If +@code{mac-wheel-button-is-mouse-2} is set to @code{nil}, their roles +are exchanged. + +@node Mac International +@section International Character Set Support on Mac +@cindex Mac Roman coding system +@cindex clipboard support (Mac OS) + + Mac uses non-standard encodings for the upper 128 single-byte +characters. They also deviate from the ISO 2022 standard by using +character codes in the range 128-159. The coding systems +@code{mac-roman}, @code{mac-centraleurroman}, and @code{mac-cyrillic} +are used to represent these Mac encodings. + + You can use input methods provided either by LEIM (@pxref{Input +Methods}) or Mac OS to enter international characters. To use the +former, see the International Character Set Support section of the +manual (@pxref{International}). + + Emacs on Mac OS automatically changes the value of +@code{keyboard-coding-system} according to the current keyboard +layout. So users don't need to set it manually, and even if set, it +will be changed when the keyboard layout change is detected next time. + + The Mac clipboard and the Emacs kill ring (@pxref{Killing}) are +synchronized by default: you can yank a piece of text and paste it +into another Mac application, or cut or copy one in another Mac +application and yank it into a Emacs buffer. This feature can be +disabled by setting @code{x-select-enable-clipboard} to @code{nil}. +One can still do copy and paste with another application from the Edit +menu. + + On Mac, the role of the coding system for selection that is set by +@code{set-selection-coding-system} (@pxref{Communication Coding}) is +two-fold. First, it is used as a preferred coding system for the +traditional text flavor that does not specify any particular encodings +and is mainly used by applications on Mac OS Classic. Second, it +specifies the intermediate encoding for the UTF-16 text flavor that is +mainly used by applications on Mac OS X. + + When pasting UTF-16 text data from the clipboard, it is first +converted to the encoding specified by the selection coding system +using the converter in the Mac OS system, and then decoded into the +Emacs internal encoding using the converter in Emacs. If the first +conversion failed, then the UTF-16 data is directly converted to Emacs +internal encoding using the converter in Emacs. Copying UTF-16 text +to the clipboard goes through the inverse path. The reason for this +two-pass decoding is to avoid subtle differences in Unicode mappings +between the Mac OS system and Emacs such as various kinds of hyphens, +and to minimize users' customization. For example, users that mainly +use Latin characters would prefer Greek characters to be decoded into +the @code{mule-unicode-0100-24ff} charset, but Japanese users would +prefer them to be decoded into the @code{japanese-jisx0208} charset. +Since the coding system for selection is automatically set according +to the system locale setting, users usually don't have to set it +manually. + + The default language environment (@pxref{Language Environments}) is +set according to the locale setting at the startup time. On Mac OS, +the locale setting is consulted in the following order: + +@enumerate +@item +Environment variables @env{LC_ALL}, @env{LC_CTYPE} and @env{LANG} as +in other systems. + +@item +Preference @code{AppleLocale} that is set by default on Mac OS X 10.3 +and later. + +@item +Preference @code{AppleLanguages} that is set by default on Mac OS X +10.1 and later. + +@item +Variable @code{mac-system-locale} that is derived from the system +language and region codes. This variable is available on all +supported Mac OS versions including Mac OS Classic. +@end enumerate + + The default values of almost all variables about coding systems are +also set according to the language environment. So usually you don't +have to customize these variables manually. + +@node Mac Environment Variables +@section Environment Variables and Command Line Arguments. +@cindex environment variables (Mac OS) + + On Mac OS X, when Emacs is run in a terminal, it inherits the values +of environment variables from the shell from which it is invoked. +However, when it is run from the Finder as a GUI application, it only +inherits environment variable values defined in the file +@file{~/.MacOSX/environment.plist} that affects all the applications +invoked from the Finder or the @command{open} command. + + Command line arguments are specified like + +@example +/Applications/Emacs.app/Contents/MacOS/Emacs -g 80x25 & +@end example + +@noindent +if Emacs is installed at @file{/Applications/Emacs.app}. If Emacs is +invoked like this, then it also inherits the values of environment +variables from the shell from which it is invoked. + + On Mac OS Classic, environment variables and command line arguments +for Emacs can be set by modifying the @samp{STR#} resources 128 and +129, respectively. A common environment variable that one may want to +set is @samp{HOME}. + + The way to set an environment variable is by adding a string of the +form + +@example +ENV_VAR=VALUE +@end example + +@noindent +to resource @samp{STR#} number 128 using @code{ResEdit}. To set up the +program to use unibyte characters exclusively, for example, add the +string + +@example +EMACS_UNIBYTE=1 +@end example + +@cindex Mac Preferences + Although Emacs on Mac does not support X resources (@pxref{X +Resources}) directly, one can use the Preferences system in place of X +resources. For example, adding the line + +@example +Emacs.cursorType: bar +@end example + +@noindent +to @file{~/.Xresources} in X11 corresponds to the execution of + +@example +defaults write org.gnu.Emacs Emacs.cursorType bar +@end example + +@noindent +on Mac OS X. One can use boolean or numeric values as well as string +values as follows: + +@example +defaults write org.gnu.Emacs Emacs.toolBar -bool false +defaults write org.gnu.Emacs Emacs.lineSpacing -int 3 +@end example + +@noindent +Try @kbd{M-x man RET defaults RET} for the usage of the +@command{defaults} command. Alternatively, if you have Developer +Tools installed on Mac OS X, you can use Property List Editor to edit +the file @file{~/Library/Preferences/org.gnu.Emacs.plist}. + + +@node Mac Directories +@section Volumes and Directories on Mac +@cindex file names (Mac OS) + + This node applies to Mac OS Classic only. + + The directory structure in Mac OS Classic is seen by Emacs as + +@example +/@var{volumename}/@var{filename} +@end example + +So when Emacs requests a file name, doing file name completion on +@file{/} will display all volumes on the system. You can use @file{..} +to go up a directory level. + + On Mac OS Classic, to access files and folders on the desktop, look +in the folder @file{Desktop Folder} in your boot volume (this folder +is usually invisible in the Mac @code{Finder}). + + On Mac OS Classic, Emacs creates the Mac folder +@file{:Preferences:Emacs:} in the @file{System Folder} and uses it as +the temporary directory. Emacs maps the directory name @file{/tmp/} +to that. Therefore it is best to avoid naming a volume @file{tmp}. +If everything works correctly, the program should leave no files in it +when it exits. You should be able to set the environment variable +@code{TMPDIR} to use another directory but this folder will still be +created. + + +@node Mac Font Specs +@section Specifying Fonts on Mac +@cindex font names (Mac OS) + + It is rare that you need to specify a font name in Emacs; usually +you specify face attributes instead. For example, you can use 14pt +Courier by customizing the default face attributes for all frames: + +@lisp +(set-face-attribute 'default nil + :family "courier" :height 140) +@end lisp + +@noindent +Alternatively, an interactive one is also available +(@pxref{Face Customization}). + +But when you do need to specify a font name in Emacs on Mac, use a +standard X font name: + +@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 + +@noindent +@xref{Font X}. Wildcards are supported as they are on X. + + Emacs on Mac OS Classic uses QuickDraw Text routines for drawing texts +by default. Emacs on Mac OS X uses @acronym{ATSUI, Apple Type Services +for Unicode Imaging} as well as QuickDraw Text, and most of the +characters other than Chinese, Japanese, and Korean ones are drawn using +the former by default. + + @acronym{ATSUI}-compatible fonts have maker name @code{apple} and +charset @code{iso10646-1}. For example, 12-point Monaco can be specified +by the name: + +@example +-apple-monaco-medium-r-normal--12-*-*-*-*-*-iso10646-1 +@end example + +Note that these names must be specified using a format containing all +14 @samp{-}s (not by +@samp{-apple-monaco-medium-r-normal--12-*-iso10646-1}, for instance), +because every @acronym{ATSUI}-compatible font is a scalable one. + + QuickDraw Text fonts have maker name @code{apple} and various charset +names other than @code{iso10646-1}. Native Apple fonts in Mac Roman +encoding has charset @code{mac-roman}. You can specify a +@code{mac-roman} font for @acronym{ASCII} characters like + +@smalllisp +(add-to-list + 'default-frame-alist + '(font . "-apple-monaco-medium-r-normal--13-*-*-*-*-*-mac-roman")) +@end smalllisp + +@noindent +but that does not extend to ISO-8859-1: specifying a @code{mac-roman} +font for Latin-1 characters introduces wrong glyphs. + + Native Apple Traditional Chinese, Simplified Chinese, Japanese, +Korean, Central European, Cyrillic, Symbol, and Dingbats fonts have +the charsets @samp{big5-0}, @samp{gb2312.1980-0}, +@samp{jisx0208.1983-sjis} and @samp{jisx0201.1976-0}, +@samp{ksc5601.1989-0}, @samp{mac-centraleurroman}, +@samp{mac-cyrillic}, @samp{mac-symbol}, and @samp{mac-dingbats}, +respectively. + + The use of @code{create-fontset-from-fontset-spec} (@pxref{Defining +Fontsets}) for defining fontsets often results in wrong ones especially +when using only OS-bundled QuickDraw Text fonts. The recommended way to +use them is to create a fontset using +@code{create-fontset-from-mac-roman-font}: + +@lisp +(create-fontset-from-mac-roman-font + "-apple-courier-medium-r-normal--13-*-*-*-*-*-mac-roman" + nil "foo") +@end lisp + +@noindent +and then optionally specifying Chinese, Japanese, or Korean font +families using @code{set-fontset-font}: + +@lisp +(set-fontset-font "fontset-foo" + 'chinese-gb2312 '("song" . "gb2312.1980-0")) +@end lisp + + Single-byte fonts converted from GNU fonts in BDF format, which are not +in the Mac Roman encoding, have foundry, family, and character sets +encoded in the names of their font suitcases. E.g., the font suitcase +@samp{ETL-Fixed-ISO8859-1} contains fonts which can be referred to by +the name @samp{-ETL-fixed-*-iso8859-1}. + +@vindex mac-allow-anti-aliasing + Mac OS X 10.2 or later can use two types of text renderings: Quartz 2D +(aka Core Graphics) and QuickDraw. By default, Emacs uses the former on +such versions. It can be changed by setting +@code{mac-allow-anti-aliasing} to @code{t} (Quartz 2D) or @code{nil} +(QuickDraw). Both @acronym{ATSUI} and QuickDraw Text drawings are +affected by the value of this variable. + + Appearance of text in small sizes will also be affected by the ``Turn +off text smoothing for font sizes @var{n} and smaller'' setting in the +General pane (Mac OS X 10.1 or 10.2) or in the Appearance pane (10.3 or +later) of the System Preferences. This threshold can alternatively be +set just for Emacs (i.e., not as the system-wide setting) using the +@command{defaults} command: + +@example +defaults write org.gnu.Emacs AppleAntiAliasingThreshold @var{n} +@end example + + +@node Mac Functions +@section Mac-Specific Lisp Functions +@cindex Lisp functions specific to Mac OS + +@findex do-applescript + The function @code{do-applescript} takes a string argument, +executes it as an AppleScript command, and returns the result as a +string. + +@findex mac-file-name-to-posix +@findex posix-file-name-to-mac + The function @code{mac-file-name-to-posix} takes a Mac file name and +returns the GNU or Unix equivalent. The function +@code{posix-file-name-to-mac} performs the opposite conversion. They +are useful for constructing AppleScript commands to be passed to +@code{do-applescript}. + +@findex mac-set-file-creator +@findex mac-get-file-creator +@findex mac-set-file-type +@findex mac-get-file-type + The functions @code{mac-set-file-creator}, +@code{mac-get-file-creator}, @code{mac-set-file-type}, and +@code{mac-get-file-type} can be used to set and get creator and file +codes. + +@findex mac-get-preference + The function @code{mac-get-preference} returns the preferences value +converted to a Lisp object for a specified key and application. + +@ignore + arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6 +@end ignore diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi new file mode 100644 index 00000000000..988d5890b8c --- /dev/null +++ b/doc/emacs/maintaining.texi @@ -0,0 +1,862 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, +@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Maintaining, Abbrevs, Building, Top +@chapter Maintaining Large Programs + + This chapter describes Emacs features for maintaining large +programs. The version control features (@pxref{Version Control}) are +also particularly useful for this purpose. + +@menu +* Change Log:: Maintaining a change history for your program. +* Format of ChangeLog:: What the change log file looks like. +* Tags:: Go direct to any function in your program in one + command. Tags remembers which file it is in. +@ifnottex +* Emerge:: A convenient way of merging two versions of a program. +@end ifnottex +@end menu + +@node Change Log +@section Change Logs + + 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. + +@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}). If that file is actually +a backup file, it makes an entry appropriate for the file's +parent---that is useful for making log entries for functions that +have been deleted in the current version. + + @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. + +@vindex add-log-keep-changes-together + When the variable @code{add-log-keep-changes-together} is +non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file +rather than starting a new item. + +@vindex add-log-always-start-new-record + If @code{add-log-always-start-new-record} is non-@code{nil}, +@kbd{C-x 4 a} always makes a new entry, even if the last entry +was made by you and on the same date. + +@vindex change-log-version-info-enabled +@vindex change-log-version-number-regexp-list +@cindex file version in change log entries + If the value of the variable @code{change-log-version-info-enabled} +is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the +change log entry. It finds the version number by searching the first +ten percent of the file, using regular expressions from the variable +@code{change-log-version-number-regexp-list}. + +@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. + +@findex change-log-merge + You can use the command @kbd{M-x change-log-merge} to merge other +log files into a buffer in Change Log Mode, preserving the date +ordering of entries. + + Version control systems are another way to keep track of changes in your +program and keep a change log. @xref{Log Buffer}. + +@node Format of ChangeLog +@section Format of ChangeLog + + A change log entry starts with a header line that contains the current +date, your name, and your email address (taken from the variable +@code{add-log-mailing-address}). 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, with two items and one item respectively. + +@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 + + One entry can describe several changes; each change should have its +own item, or its own line in an 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. + + You should put a copyright notice and permission notice at the +end of the change log file. Here is an example: + +@smallexample +Copyright 1997, 1998 Free Software Foundation, Inc. +Copying and distribution of this file, with or without modification, are +permitted provided the copyright notice and this notice are preserved. +@end smallexample + +@noindent +Of course, you should substitute the proper years and copyright holder. + +@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. When a file parsed by @code{etags} is +generated from a different source file, like a C file generated from a +Cweb source file, the tags of the parsed file reference the source +file. + + 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 file names, functions and subroutines, and may +also include global variables, data types, and anything else +convenient. Each name recorded is called a @dfn{tag}. + +@cindex C++ class browser, tags +@cindex tags, C++ +@cindex class browser, C++ +@cindex Ebrowse + See also the Ebrowse facility, which is tailored for C++. +@xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}. + +@menu +* Tag Syntax:: Tag syntax for various types of code and text files. +* Create Tags Table:: Creating a tags table with @code{etags}. +* Etags Regexps:: Create arbitrary tags using regular expressions. +* 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, @code{#undef} 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}, and so are struct members, unless you specify +@samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines} +and @samp{--no-members} can make the tags table file much smaller. + +You can tag function declarations and external variables in addition +to function definitions by giving the @samp{--declarations} option to +@code{etags}. + +@item +In C++ code, in addition to all the tag constructs of C code, member +functions are also recognized; member variables are also recognized, +unless you use the @samp{--no-members} option. Tags for variables and +functions in classes are named @samp{@var{class}::@var{variable}} and +@samp{@var{class}::@var{function}}. @code{operator} definitions have +tag names like @samp{operator+}. + +@item +In Java code, tags include all the constructs recognized in C++, plus +the @code{interface}, @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}, +@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand}, +@code{\newenvironment} or @code{\renewenvironment} is a tag.@refill + +Other commands can make tags as well, if you specify them in the +environment variable @env{TEXTAGS} before invoking @code{etags}. The +value of this environment variable should be a colon-separated list of +command names. For example, + +@example +TEXTAGS="mycommand:myothercommand" +export TEXTAGS +@end example + +@noindent +specifies (using Bourne shell syntax) that the commands +@samp{\mycommand} and @samp{\myothercommand} 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 Ada code, functions, procedures, packages, tasks and types are +tags. Use the @samp{--packages-only} option to create tags for +packages only. + +In Ada, the same name can be used for different kinds of entity +(e.g.@:, for a procedure and for a function). Also, for things like +packages, procedures and functions, there is the spec (i.e.@: the +interface) and the body (i.e.@: the implementation). To make it +easier to pick the definition you want, Ada tag name have suffixes +indicating the type of entity: + +@table @samp +@item /b +package body. +@item /f +function. +@item /k +task. +@item /p +procedure. +@item /s +package spec. +@item /t +type. +@end table + + Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go +directly to the body of the package @code{bidule}, while @kbd{M-x +find-tag @key{RET} bidule @key{RET}} will just search for any tag +@code{bidule}. + +@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 block data are tags. + +@item +In HTML input files, the tags are the @code{title} and the @code{h1}, +@code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors +and all occurrences of @code{id=}. + +@item +In Lua input files, all functions are tags. + +@item +In makefiles, targets are tags; additionally, variables are tags +unless you specify @samp{--no-globals}. + +@item +In Objective C code, tags include Objective C definitions for classes, +class categories, methods and protocols. Tags for variables and +functions in classes are named @samp{@var{class}::@var{variable}} and +@samp{@var{class}::@var{function}}. + +@item +In Pascal code, the tags are the functions and procedures defined in +the file. + +@item +In Perl code, the tags are the packages, subroutines and variables +defined by the @code{package}, @code{sub}, @code{my} and @code{local} +keywords. Use @samp{--globals} if you want to tag global variables. +Tags for subroutines are named @samp{@var{package}::@var{sub}}. The +name for subroutines defined in the default package is +@samp{main::@var{sub}}. + +@item +In PHP code, tags are functions, classes and defines. Vars are tags +too, unless you use the @samp{--no-members} option. + +@item +In PostScript code, the tags are the functions. + +@item +In Prolog code, tags are predicates and rules at the beginning of +line. + +@item +In Python code, @code{def} or @code{class} at the beginning of a line +generate a tag. +@end itemize + + You can also generate tags based on regexp matching (@pxref{Etags +Regexps}) 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 +@ifnottex +@ref{Tag Syntax}. +@end ifnottex +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. + + If the specified files don't exist, @code{etags} looks for +compressed versions of them and uncompresses them to read them. Under +MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz} +if it is given @samp{mycode.c} on the command line and @file{mycode.c} +does not exist. + + @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. If the tags table fails to record +a tag, or records it for the wrong file, then Emacs cannot possibly +find its definition until you update the tags table. However, if the +position recorded in the tags table becomes a little bit wrong (due to +other editing), the worst consequence is a slight delay in finding the +tag. Even if the stored position is very far wrong, Emacs will still +find the tag, after searching most of the file for it. That delay is +hardly noticeable with today's computers. + + Thus, there is no need to update the tags table after each edit. +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. + + One tags table can virtually 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 covered all the source 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 the tags file is in @file{/dev}, however, the file names are +made relative to the current working directory. This is useful, for +example, when writing the tags to @file{/dev/stdout}. + + When using a relative file name, it should not be a symbolic link +pointing to a tags file in a different directory, because this would +generally render the file names invalid. + + 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: + +@smallexample +find . -name "*.[chCH]" -print | etags - +@end smallexample + + 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 +(@pxref{Etags Regexps}). + + The option @samp{--parse-stdin=@var{file}} is mostly useful when +calling @code{etags} from programs. It can be used (only once) in +place of a file name on the command line. @code{Etags} will read from +standard input and mark the produced tags as belonging to the file +@var{file}. + + @samp{etags --help} outputs the list of the languages @code{etags} +knows, and the file name rules for guessing the language. It also prints +a list of all the available @code{etags} options, together with a short +explanation. If followed by one or more @samp{--language=@var{lang}} +options, it outputs detailed information about how tags are generated for +@var{lang}. + +@node Etags Regexps +@subsection Etags Regexps + + The @samp{--regex} option provides a general way of recognizing tags +based on regexp matching. You can freely intermix this option with +file names, and each one applies to the source files that follow it. +If you specify multiple @samp{--regex} options, all of them are used +in parallel. The syntax is: + +@smallexample +--regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers} +@end smallexample + + The essential part of the option value is @var{tagregexp}, the +regexp for matching tags. It is always used anchored, that is, it +only matches at the beginning of a line. If you want to allow +indented tags, use a regexp that matches initial whitespace; start it +with @samp{[ \t]*}. + + In these regular expressions, @samp{\} quotes the next character, and +all the GCC character escape sequences are supported (@samp{\a} for +bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for +escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for +carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab). + + Ideally, @var{tagregexp} should not match more characters than are +needed to recognize what you want to tag. If the syntax requires you +to write @var{tagregexp} so it matches more characters beyond the tag +itself, you should add a @var{nameregexp}, to pick out just the tag. +This will enable Emacs to find tags more accurately and to do +completion on tag names more reliably. You can find some examples +below. + + The @var{modifiers} are a sequence of zero or more characters that +modify the way @code{etags} does the matching. A regexp with no +modifiers is applied sequentially to each line of the input file, in a +case-sensitive way. The modifiers and their meanings are: + +@table @samp +@item i +Ignore case when matching this regexp. +@item m +Match this regular expression against the whole file, so that +multi-line matches are possible. +@item s +Match this regular expression against the whole file, and allow +@samp{.} in @var{tagregexp} to match newlines. +@end table + + The @samp{-R} option cancels all the regexps defined by preceding +@samp{--regex} options. It too applies to the file names following +it. Here's an example: + +@smallexample +etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \ + bar.ber -R --lang=lisp los.er +@end smallexample + +@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}. @var{reg1} is checked against each line of +@file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while +@var{reg2} is checked against the whole @file{bar.ber} file, +permitting multi-line matches, in a case-sensitive way. @code{etags} +uses only the Lisp tags rules, with no user-specified regexp matching, +to recognize tags in @file{los.er}. + + You can restrict a @samp{--regex} option to match only files of a +given language by using the optional prefix @var{@{language@}}. +(@samp{etags --help} prints the list of languages recognized by +@code{etags}.) This is particularly useful when storing many +predefined regular expressions for @code{etags} in a file. The +following example tags the @code{DEFVAR} macros in the Emacs source +files, for the C language only: + +@smallexample +--regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' +@end smallexample + +@noindent +When you have complex regular expressions, you can store the list of +them in a file. The following option syntax instructs @code{etags} to +read two files of regular expressions. The regular expressions +contained in the second file are matched without regard to case. + +@smallexample +--regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file} +@end smallexample + +@noindent +A regex file for @code{etags} contains one regular expression per +line. Empty lines, and lines beginning with space or tab are ignored. +When the first character in a line is @samp{@@}, @code{etags} assumes +that the rest of the line is the name of another file of regular +expressions; thus, one such file can include another file. All the +other lines are taken to be regular expressions. If the first +non-whitespace text on the line is @samp{--}, that line is a comment. + + For example, we can create a file called @samp{emacs.tags} with the +following contents: + +@smallexample + -- This is for GNU Emacs C source files +@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ +@end smallexample + +@noindent +and then use it like this: + +@smallexample +etags --regex=@@emacs.tags *.[ch] */*.[ch] +@end smallexample + + Here are some more examples. The regexps are quoted to protect them +from shell interpretation. + +@itemize @bullet + +@item +Tag Octave files: + +@smallexample +etags --language=none \ + --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ + --regex='/###key \(.*\)/\1/' \ + --regex='/[ \t]*global[ \t].*/' \ + *.m +@end smallexample + +@noindent +Note that tags are not generated for scripts, so that you have to add +a line by yourself of the form @samp{###key @var{scriptname}} if you +want to jump to it. + +@item +Tag Tcl files: + +@smallexample +etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl +@end smallexample + +@item +Tag VHDL files: + +@smallexample +etags --language=none \ + --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ + --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ + \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' +@end smallexample +@end itemize + +@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, with @file{TAGS} in the default +directory as the default. + + Emacs does not actually read in the tags table contents until you +try to use them; all @code{visit-tags-table} does is store the file +name in the variable @code{tags-file-name}, and setting the variable +yourself is just as good. 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. + +@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 balanced +expression in the buffer before or around point is used as the +@var{tag} argument. @xref{Expressions}. + + 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 @w{@kbd{C-x 4 .}}, which invokes +the command @code{find-tag-other-window}. The latter is @w{@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. @w{@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 +@cindex search and replace in multiple files +@cindex multiple-file search and replace + + 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. These +commands scan the list of tags tables starting 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. + +@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. + +@vindex tags-case-fold-search +@cindex case-sensitivity and tags search + You can control the case-sensitivity of tags search commands by +customizing the value of the variable @code{tags-case-fold-search}. The +default is to use the same setting as the value of +@code{case-fold-search} (@pxref{Search Case}). + + 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. +@xref{Grep Searching}. + +@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 +@vindex tags-apropos-verbose + @kbd{M-x tags-apropos} is like @code{apropos} for tags +(@pxref{Apropos}). It finds all the tags in the selected tags table +whose entries match @var{regexp}, and displays them. If the variable +@code{tags-apropos-verbose} is non-@code{nil}, it displays the names +of the tags files together with the tag names. + +@vindex tags-tag-face +@vindex tags-apropos-additional-actions + You can customize the appearance of the output by setting the +variable @code{tags-tag-face} to a face. You can display additional +output with @kbd{M-x tags-apropos} by customizing the variable +@code{tags-apropos-additional-actions}---see its documentation for +details. + + You can also use the collection of tag names to complete a symbol +name in the buffer. @xref{Symbol Completion}. + +@ifnottex +@include emerge-xtra.texi +@end ifnottex + +@ignore + arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb +@end ignore diff --git a/doc/emacs/major.texi b/doc/emacs/major.texi new file mode 100644 index 00000000000..1cb76ee5fdf --- /dev/null +++ b/doc/emacs/major.texi @@ -0,0 +1,206 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 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 +user option variable 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. The first group +contains modes for normal text, either plain or with mark-up. It +includes Text mode, HTML mode, SGML mode, @TeX{} mode and Outline +mode. The second group contains modes for specific programming +languages. These include Lisp mode (which has several variants), C +mode, Fortran mode, and others. 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 +(@pxref{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. + + To explicitly select a new major, you use an @kbd{M-x} command. +Take the name of a major mode and add @code{-mode} to get the name of +the 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 must +be used 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{mode-function}, Emacs discards the suffix that matched +@var{regexp} and searches the list again for another match. + +@vindex magic-mode-alist + Sometimes the major mode is determined from the way the file's text +begins. The variable @code{magic-mode-alist} controls this. Its value +is a list of elements of these forms: + +@example +(@var{regexp} . @var{mode-function}) +(@var{match-function} . @var{mode-function}) +@end example + +@noindent +The first form looks like an element of @code{auto-mode-alist}, but it +doesn't work the same: this @var{regexp} is matched against the text +at the start of the buffer, not against the file name. Likewise, the +second form calls @var{match-function} at the beginning of the buffer, +and if the function returns non-@code{nil}, the @var{mode-function} is +called. @code{magic-mode-alist} takes priority over +@code{auto-mode-alist}. + + You can specify the major mode to use for editing a certain file by +special 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 defaults 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 auto-mode-case-fold + On systems with case-insensitive file names, only a single +case-insensitive search through the @code{auto-mode-alist} is made. +On other systems, Emacs normally performs a single case-sensitive +search through the alist, but if you set this variable to a +non-@code{nil} value, Emacs will perform a second case-insensitive +search if the first search fails. + +@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 current 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 @samp{-*-} line or local variables list (if any). +@xref{File Variables}. + +@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}). +(@kbd{C-x C-s} does this too, if the buffer wasn't visiting a file.) +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}. + +@ignore + arch-tag: f2558800-cf32-4839-8acb-7d3b4df2a155 +@end ignore diff --git a/doc/emacs/makefile.w32-in b/doc/emacs/makefile.w32-in new file mode 100644 index 00000000000..e7185cd9c03 --- /dev/null +++ b/doc/emacs/makefile.w32-in @@ -0,0 +1,144 @@ +#### -*- Makefile -*- for the Emacs Manual and other documentation. + +# Copyright (C) 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. + +# This file is part of GNU Emacs. + +# GNU Emacs 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 3, or (at your option) +# any later version. + +# GNU Emacs 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 GNU Emacs; see the file COPYING. If not, write to +# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, +# Boston, MA 02110-1301, USA. + +# Where to find the source code. The source code for Emacs's C kernel is +# expected to be in $(srcdir)/src, and the source code for Emacs's +# utility programs is expected to be in $(srcdir)/lib-src. This is +# set by the configure script's `--srcdir' option. +srcdir=. + +infodir = $(srcdir)/../info + +# The makeinfo program is part of the Texinfo distribution. +MAKEINFO = makeinfo --force +MULTI_INSTALL_INFO = $(srcdir)\..\..\nt\multi-install-info.bat +INFO_TARGETS = $(infodir)/emacs +DVI_TARGETS = emacs.dvi +INFOSOURCES = info.texi + +# The following rule does not work with all versions of `make'. +.SUFFIXES: .texi .dvi +.texi.dvi: + texi2dvi $< + +TEXI2DVI = texi2dvi +ENVADD = $(srcdir)\..\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" \ + "MAKEINFO=$(MAKEINFO) -I$(srcdir)" /C + +EMACS_XTRA=\ + $(srcdir)/arevert-xtra.texi \ + $(srcdir)/cal-xtra.texi \ + $(srcdir)/dired-xtra.texi \ + $(srcdir)/picture-xtra.texi \ + $(srcdir)/emerge-xtra.texi \ + $(srcdir)/vc-xtra.texi \ + $(srcdir)/vc1-xtra.texi \ + $(srcdir)/vc2-xtra.texi \ + $(srcdir)/fortran-xtra.texi \ + $(srcdir)/msdog-xtra.texi + +EMACSSOURCES= \ + $(srcdir)/emacs.texi \ + $(srcdir)/doclicense.texi \ + $(srcdir)/screen.texi \ + $(srcdir)/commands.texi \ + $(srcdir)/entering.texi \ + $(srcdir)/basic.texi \ + $(srcdir)/mini.texi \ + $(srcdir)/m-x.texi \ + $(srcdir)/help.texi \ + $(srcdir)/mark.texi \ + $(srcdir)/killing.texi \ + $(srcdir)/regs.texi \ + $(srcdir)/display.texi \ + $(srcdir)/search.texi \ + $(srcdir)/fixit.texi \ + $(srcdir)/files.texi \ + $(srcdir)/buffers.texi \ + $(srcdir)/windows.texi \ + $(srcdir)/frames.texi \ + $(srcdir)/mule.texi \ + $(srcdir)/major.texi \ + $(srcdir)/indent.texi \ + $(srcdir)/text.texi \ + $(srcdir)/programs.texi \ + $(srcdir)/building.texi \ + $(srcdir)/maintaining.texi \ + $(srcdir)/abbrevs.texi \ + $(srcdir)/sending.texi \ + $(srcdir)/rmail.texi \ + $(srcdir)/dired.texi \ + $(srcdir)/calendar.texi \ + $(srcdir)/misc.texi \ + $(srcdir)/custom.texi \ + $(srcdir)/trouble.texi \ + $(srcdir)/cmdargs.texi \ + $(srcdir)/xresources.texi \ + $(srcdir)/anti.texi \ + $(srcdir)/macos.texi \ + $(srcdir)/msdog.texi \ + $(srcdir)/gnu.texi \ + $(srcdir)/glossary.texi \ + $(srcdir)/ack.texi \ + $(srcdir)/kmacro.texi \ + $(EMACS_XTRA) + +info: $(INFO_TARGETS) + +dvi: $(DVI_TARGETS) + +# Note that all the Info targets build the Info files +# in srcdir. There is no provision for Info files +# to exist in the build directory. +# In a distribution of Emacs, the Info files should be up to date. + +$(infodir)/dir: + $(MULTI_INSTALL_INFO) --info-dir=$(infodir) $(INFO_TARGETS) + +$(infodir)/emacs: $(EMACSSOURCES) + $(MAKEINFO) emacs.texi + +emacs.dvi: $(EMACSSOURCES) + $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs.texi + +emacs-xtra.dvi: emacs-xtra.texi $(EMACS_XTRA) + $(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-xtra.texi + +mostlyclean: + - $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.* + +clean: mostlyclean + - $(DEL) *.dvi + - $(DEL) $(infodir)/emacs* + +distclean: clean + +maintainer-clean: distclean + - $(DEL) *.aux *.cps *.fns *.kys *.pgs *.vrs *.toc +# Don't delete these, because they are outside the current directory. +# for file in $(INFO_TARGETS); do rm -f $${file}*; done + + +# Formerly this directory had texindex.c and getopt.c in it +# and this makefile built them to make texindex. +# That caused trouble because this is run entirely in the source directory. +# Since we expect to get texi2dvi from elsewhere, +# it is ok to expect texindex from elsewhere also. diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi new file mode 100644 index 00000000000..be446ab6bfc --- /dev/null +++ b/doc/emacs/mark.texi @@ -0,0 +1,452 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, +@c 2003, 2004, 2005, 2006, 2007 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}). + + Certain Emacs commands set the mark; other editing commands do not +affect it, so the mark remains where you set it last. Each Emacs +buffer has its own mark, and setting the mark in one buffer has no +effect on other buffers' marks. When you return to a buffer that was +current earlier, its mark is at the same place as before. + + The ends of the region are always point and the mark. It doesn't +matter which of them was put in its current place first, or which one +comes earlier in the text---the region starts from point or the mark +(whichever comes first), and ends at point or the mark (whichever +comes last). Every time you move point, or set the mark in a new +place, the region changes. + + 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 consists of 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. +* Momentary Mark:: Enabling Transient Mark mode momentarily. +* 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: + +@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 where you clicked (like +@kbd{Mouse-1}). + + Using the mouse to mark a region copies the region into the kill +ring in addition to setting the mark; that gives behavior consistent +with other window-driven applications. 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 + When Emacs was developed, terminals had only one cursor, so Emacs +does not show where the mark is located--you have to remember. If you +enable Transient Mark mode (see below), then the region is highlighted +when it is active; you can tell mark is at the other end of the +highlighted region. But this only applies when the mark is active. + + 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 also 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. Using @kbd{C-x C-x} a second time, if necessary, puts the mark at +the new position with point back at its original position. + + For more facilities that allow you to go to previously set marks, see +@ref{Mark Ring}. + +@kindex C-@@ + There is no such character as @kbd{C-@key{SPC}} in @acronym{ASCII}; +when you type @key{SPC} while holding down @key{CTRL} on a text +terminal, what you get is the character @kbd{C-@@}. This key is also +bound to @code{set-mark-command}--so unless you are unlucky enough to +have a text 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}}. + +@node Transient Mark +@section Transient Mark Mode +@cindex mode, Transient Mark +@cindex Transient Mark mode +@cindex highlighting region +@cindex region highlighting + + On a terminal that supports colors, Emacs has the ability to +highlight the current region. But normally it does not. Why not? + + In the normal mode of use, every command that sets the mark also +activates it, and nothing ever deactivates it. Thus, once you have +set the mark in a buffer, there is @emph{always} a region in that +buffer. Highlighting the region all the time would be a nuisance. So +normally Emacs highlights the region only immediately after you have +selected one with the mouse. + + If you want region highlighting, you can use Transient Mark mode. +This is a more rigid mode of operation in which the region ``lasts'' +only until you use it; operating on the region text deactivates the +mark, so there is no region any more. Therefore, you must explicitly +set up a region for each command that uses one. + + When Transient Mark mode is enabled, Emacs highlights the region, +whenever there is a region. In Transient Mark mode, most of the time +there is no region; therefore, highlighting the region when it exists +is useful and not annoying. + +@findex transient-mark-mode + To enable Transient Mark mode, type @kbd{M-x transient-mark-mode}. +This command toggles the mode; you can use the same command to turn +the mode off again. + + 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 and thus begins highlighting of the region. +As you move point, you will see the highlighted region 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 +You can tell that the mark is active because the region is highlighted. + +@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 +If Delete Selection mode is also enabled, some commands delete the +region when used while the mark is active. @xref{Mouse Commands}. + +@item +Quitting with @kbd{C-g} deactivates the mark. + +@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 +Commands that normally set the mark before moving long distances (like +@kbd{M-<} and @kbd{C-s}) do not alter the mark in Transient Mark mode +when the mark is active. + +@item +Some commands operate on the region if a region is active. For +instance, @kbd{C-x u} in Transient Mark mode operates on the region, +when there is a region. (Outside Transient Mark mode, you must type +@kbd{C-u C-x u} if you want it to operate on the region.) +@xref{Undo}. Other commands that act this way are identified in their +own documentation. +@end itemize + + The highlighting of the region uses the @code{region} face; you can +customize the appearance of the highlighted region 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 mark in the window's buffer is active). + +@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, so you can still use +region commands. + +@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 Momentary Mark +@section Using Transient Mark Mode Momentarily + + If you don't like Transient Mark mode in general, you might still +want to use it once in a while. To do this, type @kbd{C-@key{SPC} +C-@key{SPC}} or @kbd{C-u C-x C-x}. These commands set or activate the +mark, and enable Transient Mark mode only until the mark is +deactivated. + +@table @kbd +@item C-@key{SPC} C-@key{SPC} +@kindex C-@key{SPC} C-@key{SPC} +Set the mark at point (like plain @kbd{C-@key{SPC}}), and enable +Transient Mark mode just once until the mark is deactivated. (This is +not really a separate command; you are using the @kbd{C-@key{SPC}} +command twice.) + +@item C-u C-x C-x +@kindex C-u C-x C-x +Activate the mark without changing it; enable Transient Mark mode just +once, until the mark is deactivated. (This is the @kbd{C-x C-x} +command, @code{exchange-point-and-mark}, with a prefix argument.) +@end table + + One of the secondary features of Transient Mark mode is that certain +commands operate only on the region, when there is an active region. +If you don't use Transient Mark mode, the region once set never +becomes inactive, so there is no way for these commands to make such a +distinction. Enabling Transient Mark mode momentarily gives you a way +to use these commands on the region. + + Momentary use of Transient Mark mode is also a way to highlight the +region for the time being. + +@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{Printing}). +@item +Evaluate it as Lisp code with @kbd{M-x eval-region} (@pxref{Lisp Eval}). +@item +Undo changes within it using @kbd{C-u C-x u} (@pxref{Undo}). +@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 following balanced expression (@code{mark-sexp}). +@item M-h +Put region around current paragraph (@code{mark-paragraph}). +@item C-M-h +Put region around current defun (@code{mark-defun}). +@item C-x h +Put region around the 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 balanced expression (@pxref{Expressions}). These commands handle +arguments just like @kbd{M-f} and @kbd{C-M-f}. Repeating these +commands extends the region. For example, you can type either +@kbd{C-u 2 M-@@} or @kbd{M-@@ M-@@} to mark the next two words. These +commands also extend the region in Transient Mark mode, regardless of +the last command. + +@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. With a prefix argument, if the argument's value is positive, +@kbd{M-h} marks that many paragraphs starting with the one surrounding +point. If the prefix argument is @minus{}@var{n}, @kbd{M-h} also +marks @var{n} paragraphs, running back form the one surrounding point. +In that last case, point moves forward to the end of that paragraph, +and the mark goes at the start of the region. Repeating the @kbd{M-h} +command extends the region to subsequent paragraphs. + + @kbd{C-M-h} (@code{mark-defun}) similarly puts point before, and the +mark after, the current (or following) major top-level definition, or +defun (@pxref{Moving by Defuns}). Repeating @kbd{C-M-h} extends +the region to subsequent 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 in the region), 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 some programs this is called ``select all.'') + + 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. + +@vindex set-mark-command-repeat-pop + If you set @code{set-mark-command-repeat-pop} to non-@code{nil}, +then when you repeat the character @kbd{C-@key{SPC}} after typing +@kbd{C-u C-@key{SPC}}, each repetition moves point to a previous mark +position from the ring. 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. However, in +Transient Mark mode, these commands do not set the mark when the mark +is already active. 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,, Saving Positions in +Registers}). + +@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 earliest 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. + +@ignore + arch-tag: f35e4d82-911b-4cfc-a3d7-3c87b2abba20 +@end ignore diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi new file mode 100644 index 00000000000..b57e79420b6 --- /dev/null +++ b/doc/emacs/mini.texi @@ -0,0 +1,580 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 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 where Emacs commands read complicated +arguments (anything more a single number). We call it the +``minibuffer'' because it's a special-purpose buffer with a small +amount of screen space. Minibuffer arguments can be file names, +buffer names, Lisp function names, Emacs command names, Lisp +expressions, and many other things---whatever the command wants to +read. 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, with a +cursor. The minibuffer display starts with a @dfn{prompt} in a +distinct color; it says what kind of input is expected and how it will +be used. Often the prompt is derived from the name of the command +that is reading the argument. The prompt normally ends with a colon. + +@cindex default argument + Sometimes a @dfn{default argument} appears in the prompt, inside +parentheses before the colon. The default will be used as the +argument value if you just type @key{RET}. For example, commands that +read buffer names show a buffer name as the default. You can type +@key{RET} to operate on that default buffer. + + The simplest way to enter a minibuffer argument is to type the text, +then @key{RET} to exit the minibuffer. You can cancel the minibuffer, +and the command that wants the argument, by typing @kbd{C-g}. + + Since the minibuffer appears in the echo area, it can conflict with +other uses of the echo area. Here is how Emacs handles such +conflicts: + +@itemize @bullet +@item +An error occurs while the minibuffer is active. + +The error message hides the minibuffer for a few seconds, or until you +type something. Then the minibuffer comes back. + +@item +A command such as @kbd{C-x =} needs to display a message in the echo +area. + +The message hides the minibuffer for a few seconds, or until you type +something. Then the minibuffer comes back. + +@item +Keystrokes don't echo 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 + + When you use the minibuffer to enter a file name, it starts out with +some initial text---the @dfn{default directory}, ending in a slash. +The file you specify will be in this directory unless you alter or +replace it. + +@c Separate paragraph to clean up ugly page break--rms +@need 1500 + For example, if the minibuffer starts out with these contents: + +@example +Find File: /u2/emacs/src/ +@end example + +@noindent +(where @samp{Find File:@: } is the prompt), and you type +@kbd{buffer.c} as input, that specifies the file +@file{/u2/emacs/src/buffer.c}. You can specify the parent directory +by adding @file{..}; thus, if you type @kbd{../lisp/simple.el}, you +will get @file{/u2/emacs/lisp/simple.el}. Alternatively, you can use +@kbd{M-@key{DEL}} to kill the directory names you don't want +(@pxref{Words}). + + You can kill the entire default with @kbd{C-a C-k}, but there's no +need to do that. It's easier to ignore the default, and enter an +absolute file name starting with a slash or a tilde after the default +directory. For example, to specify @file{/etc/termcap}, just type +that name: + +@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 +@findex file-name-shadow-mode +GNU Emacs interprets a double slash (which is not normally useful in +file names) as, ``ignore everything before the second slash in the +pair.'' In the example above. @samp{/u2/emacs/src/} is ignored, so +you get @file{/etc/termcap}. The ignored part of the file name is +dimmed if the terminal allows it; to disable this dimming, turn off +File Name Shadow mode (a minor mode) with the command +@kbd{M-x file-name-shadow-mode}. + + If the variable @code{insert-default-directory} is @code{nil}, the +default directory is never inserted in the minibuffer---so the +minibuffer starts out empty. Nonetheless, relative file name +arguments are still interpreted based on 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 argument text. + + 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}. (The newline character is really the +@acronym{ASCII} character control-J.) + + The minibuffer has its own window, which normally has space in the +frame at all times, but it only acts like an Emacs window when the +minibuffer is active. When active, this window is much like any other +Emacs window; for instance, you can switch to another window (with +@kbd{C-x o}), edit text there, then return to the minibuffer window to +finish the argument. You can even kill text in another window, return +to the minibuffer window, and then yank the text into the argument. +@xref{Windows}. + +@cindex height of minibuffer +@cindex size of minibuffer +@cindex growing minibuffer +@cindex resizing minibuffer + There are some restrictions on the minibuffer window, however: you +cannot kill it, or split it, or switch buffers in it---the minibuffer +and its window are permanently attached. + +@vindex resize-mini-windows + The minibuffer window expands vertically as necessary to hold the +text that you put in the minibuffer. If @code{resize-mini-windows} is +@code{t} (the default), the window always resizes as needed by its +contents. If its value is the symbol @code{grow-only}, the window +grows automatically as needed, but shrinks (back to the normal size) +only when the minibuffer becomes inactive. If its value is +@code{nil}, you have to adjust the height yourself. + +@vindex max-mini-window-height + The variable @code{max-mini-window-height} controls the maximum +height for resizing the minibuffer window: a floating-point number +specifies a fraction of the frame's height; an integer specifies the +maximum number of lines; @code{nil} means do not resize the minibuffer +window automatically. The default value is 0.25. + + The @kbd{C-M-v} command in the minibuffer scrolls the help text from +commands that display help text of any sort in another window. +@kbd{M-@key{PAGEUP}} and @kbd{M-@key{PAGEDOWN}} also operate on that +help text. This is especially useful with long lists of possible +completions. @xref{Other Window}. + +@vindex enable-recursive-minibuffers + Emacs normally disallows most commands that use the minibuffer while +the minibuffer is active. (Entering the minibuffer from the +minibuffer can be confusing.) To allow such commands in the +minibuffer, set the variable @code{enable-recursive-minibuffers} to +@code{t}. + +@node Completion +@section Completion +@cindex completion + + Some arguments allow @dfn{completion} to enter their value. This +means that after you type part of the argument, Emacs can fill in the +rest, or some of it, based on what you have typed so far. + + When completion is available, certain keys---@key{TAB}, @key{RET}, +and @key{SPC}---are rebound to complete the text in the minibuffer +before point into a longer string chosen from a set of @dfn{completion +alternatives} provided by the command that requested the argument. +(@key{SPC} does not do completion in reading file names, because it is +common to use spaces in file names on some systems.) @kbd{?} displays +a list of the possible completions at any time. + + For example, @kbd{M-x} uses the minibuffer to read the name of a +command, so it provides a list of all Emacs command names for +completion candidates. The completion keys match the minibuffer text +against these candidates, find any additional name characters implied +by the text already present in the minibuffer, and add those +characters. This 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 significant in completion when it is significant in the +argument you are entering (buffer names, file names, command names, +for instance). Thus, @samp{fo} does not complete to @samp{Foo}. +Completion ignores case distinctions for certain arguments in which +case does not matter. + + Completion acts only on the text before point. If there is text in +the minibuffer after point---i.e., if you move point backward after +typing some text into the minibuffer---it remains unchanged. + +@menu +* Example: Completion Example. Examples of using completion. +* Commands: Completion Commands. A list of completion commands. +* Strict Completion:: Different types of completion. +* Options: Completion Options. Options for completion. +@end menu + +@node Completion Example +@subsection Completion Example + +@kindex TAB @r{(completion)} + 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 +all begin with @code{auto-}, so the @samp{au} in the minibuffer +completes to @samp{auto-}. + + If you type @key{TAB} again immediately, it cannot determine the +next character; it could be any of @samp{cfilrs}. So it does not add +any characters; instead, @key{TAB} displays a list of all possible +completions in another window. + + Now type @kbd{f @key{TAB}}. This @key{TAB} sees @samp{auto-f}. The +only command name starting with that is @code{auto-fill-mode}, so +completion fills in the rest of that. You have been able to enter +@samp{auto-fill-mode} by typing just @kbd{au @key{TAB} f @key{TAB}}. + +@node Completion Commands +@subsection Completion Commands + + Here is a list of the completion commands defined in the minibuffer +when completion is allowed. + +@table @kbd +@item @key{TAB} +@findex minibuffer-complete +Complete the text before point in the minibuffer as much as possible +(@code{minibuffer-complete}). +@item @key{SPC} +Complete up to one word from the minibuffer text before point +(@code{minibuffer-complete-word}). @key{SPC} for completion is not +available when entering a file name, since file names often include +spaces. +@item @key{RET} +Submit the text in the minibuffer as the argument, possibly completing +first as described +@iftex +in the next subsection (@code{minibuffer-complete-and-exit}). +@end iftex +@ifnottex +in the next node (@code{minibuffer-complete-and-exit}). @xref{Strict +Completion}. +@end ifnottex +@item ? +Display a list of possible completions of the text before point +(@code{minibuffer-completion-help}). +@end table + +@kindex SPC +@findex minibuffer-complete-word + @key{SPC} completes like @key{TAB}, but only up to 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 only inserts @samp{ill-}, giving @samp{auto-fill-}. Another +@key{SPC} at this point completes all the way to +@samp{auto-fill-mode}. The command that implements this behavior is +called @code{minibuffer-complete-word}. + + When you display a list of possible completions, you can choose +one from it: + +@table @kbd +@findex mouse-choose-completion +@item Mouse-1 +@itemx Mouse-2 +Clicking mouse button 1 or 2 on a completion possibility chooses that +completion (@code{mouse-choose-completion}). You must click in the +list of completions, not in the minibuffer. + +@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 other ways has the same +effect.) + +@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 to the completion list window. + +@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 possibility +(@code{next-completion}). + +@findex previous-completion +@item @key{LEFT} +Typing the left-arrow key @key{LEFT} @emph{in the completion list +buffer} moves point to the previous completion possibility +(@code{previous-completion}). +@end table + +@node Strict Completion +@subsection Strict Completion + + There are three different ways that @key{RET} can do completion, +depending on how the argument will be used. + +@itemize @bullet +@item +@dfn{Strict} completion accepts only known completion candidates. For +example, when @kbd{C-x k} reads the name of a buffer to kill, only the +name of an existing buffer makes sense. 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 is an already exact match. +Otherwise, @key{RET} does not exit, but it does complete the text. If +that 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, for example. + +@item +@dfn{Permissive} completion allows any input; the completion +candidates are just suggestions. For example, when @kbd{C-x C-f} +reads the name of a file to visit, any file name is allowed, including +nonexistent file (in case you want to create a file). In permissive +completion, @key{RET} does not complete, it just submits the argument +as you have entered it. +@end itemize + + The completion commands display a list of all possible completions +whenever they can't determine even one more character by completion. +Also, typing @kbd{?} explicitly requests such a list. You can scroll +the list with @kbd{C-M-v} (@pxref{Other Window}). + +@node Completion Options +@subsection Completion Options + +@vindex completion-ignored-extensions +@cindex ignored file names, in completion + When completing file names, certain file names are usually ignored. +The variable @code{completion-ignored-extensions} contains a list of +strings; a file name ending in any of those strings is ignored as a +completion candidate. 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. Displaying a list of possible completions +disregards @code{completion-ignored-extensions}; it shows them all. + + If an element of @code{completion-ignored-extensions} ends in a +slash (@file{/}), it's a subdirectory name; then that directory and +its contents are ignored. Elements of +@code{completion-ignored-extensions} which do not end in a slash are +ordinary file names, and do not apply to names of directories. + +@vindex completion-auto-help + If @code{completion-auto-help} is set to @code{nil}, the completion +commands never display a list of possibilities; you must type @kbd{?} +to display the list. + +@cindex Partial Completion mode +@vindex partial-completion-mode +@findex partial-completion-mode + Partial Completion mode implements a more powerful kind of +completion that can complete multiple words in parallel. For example, +it can complete the command name abbreviation @code{p-b} into +@code{print-buffer} if no other command starts with two words whose +initials are @samp{p} and @samp{b}. + + To enable this mode, use @kbd{M-x partial-completion-mode}, or +customize the variable @code{partial-completion-mode}. This mode +binds special partial completion commands to @key{TAB}, @key{SPC}, +@key{RET}, and @kbd{?} in the minibuffer. The usual completion +commands are available on @kbd{M-@key{TAB}} (or @kbd{C-M-i}), +@kbd{M-@key{SPC}}, @kbd{M-@key{RET}} and @kbd{M-?}. + + Partial completion of directories in file names uses @samp{*} to +indicate the places for completion; thus, @file{/u*/b*/f*} might +complete to @file{/usr/bin/foo}. For remote files, partial completion +enables completion of methods, user names and host names. +@xref{Remote Files}. + +@vindex PC-include-file-path +@vindex PC-disable-includes + Partial Completion mode also extends @code{find-file} so that +@samp{<@var{include}>} looks for the file named @var{include} in the +directories in the path @code{PC-include-file-path}. If you set +@code{PC-disable-includes} to non-@code{nil}, this feature is +disabled. + +@cindex Icomplete mode +@findex 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 you can easily use it again later. +Special commands fetch the text of an earlier argument into the +minibuffer, replacing the old minibuffer contents. You can think of +them as moving through the history of previous arguments. + +@table @kbd +@item @key{UP} +@itemx M-p +Move to the previous item in the minibuffer history, an earlier argument +(@code{previous-history-element}). +@item @key{DOWN} +@itemx M-n +Move to the next item in the minibuffer history +(@code{next-history-element}). +@item M-r @var{regexp} @key{RET} +Move to an earlier item in the minibuffer history that +matches @var{regexp} (@code{previous-matching-history-element}). +@item M-s @var{regexp} @key{RET} +Move to a later item in the minibuffer history that matches +@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 + To move through the minibuffer history list one item at a time, use +@kbd{M-p} or up-arrow (@code{previous-history-element}) to fetch the +next earlier minibuffer input, and use @kbd{M-n} or down-arrow +(@code{next-history-element}) to fetch the next later input. These +commands don't move the cursor, they pull different saved strings into +the minibuffer. But you can think of them as ``moving'' through the +history list. + + The input that you fetch from the history entirely replaces the +contents of the minibuffer. To use it again unchanged, just type +@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. You can +insert the default value into the minibuffer as text by using +@kbd{M-n}. You can think of this as moving ``into the future'' in the +history. + +@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. @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. These +commands are unusual; they use the minibuffer to read the regular +expression even though they are invoked from the minibuffer. As with +incremental searching, an upper-case 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, even if the name you entered was not +absolute.) + + There are several other specific history lists, including one for +buffer names, one for arguments of commands like @code{query-replace}, +one used by @kbd{M-x} for command names, and one used by +@code{compile} for compilation commands. 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; adding a new element deletes the oldest +element if the list gets too long. If the value of +@code{history-length} is @code{t}, though, there is no maximum length. + +@vindex history-delete-duplicates + The variable @code{history-delete-duplicates} specifies whether to +delete duplicates in history. If it is @code{t}, adding a new element +deletes from the list all other elements that are equal to it. + +@node Repetition +@section Repeating Minibuffer Commands +@cindex command history +@cindex history of commands + + Every command that uses the minibuffer once is recorded on a special +history list, the @dfn{command history}, 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 +@table @kbd +@item C-x @key{ESC} @key{ESC} +Re-execute a recent minibuffer command from the command history + (@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 command +that used the minibuffer. With no argument, it repeats the last such +command. A numeric argument specifies which command to repeat; 1 +means the last one, 2 the previous, and so on. + + @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. Even if you don't understand Lisp +syntax, it will probably be obvious which command is displayed for +repetition. If you type just @key{RET}, that repeats the command +unchanged. You can also change the command by editing the Lisp +expression before you execute it. The repeated command is added to +the front of the command history unless it is identical to the most +recently item. + + 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 repeat it by typing +@key{RET}. + +@vindex isearch-resume-in-command-history + Incremental search does not, strictly speaking, use the minibuffer. +Therefore, although it behaves like a complex command, it normally +does not appear in the history list for @kbd{C-x @key{ESC} @key{ESC}}. +You can make incremental search commands appear in the history by +setting @code{isearch-resume-in-command-history} to a non-@code{nil} +value. @xref{Incremental Search}. + +@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. + +@ignore + arch-tag: ba913cfd-b70e-400f-b663-22b2c309227f +@end ignore diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi new file mode 100644 index 00000000000..c4cdea4359d --- /dev/null +++ b/doc/emacs/misc.texi @@ -0,0 +1,2559 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 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, following hyperlinks, +browsing images, emulating other editors, and various diversions and +amusements. + +@end iftex + +@ifnottex +@raisesections +@end ifnottex + +@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. +@ifnottex +For full details, see @ref{Top, Gnus,, gnus, The Gnus Manual}. +@end ifnottex +@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 + +Unlike most Emacs packages, Gnus uses several buffers to display +information and to receive commands. The three Gnus buffers users use +most are the @dfn{group buffer}, the @dfn{summary buffer} and the +@dfn{article buffer}. + +The @dfn{group buffer} contains a list of newsgroups. 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 see this buffer but you don't select it---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; 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 +@ifnottex +additional topics: + +@end ifnottex +@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 +@ifnottex +@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 ifnottex +@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*} or run a shell inside a terminal +emulator window. + +@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. +@item M-x term +Run a subshell with input and output through an Emacs buffer. +You can then give commands interactively. +Full terminal emulation is available. +@end table + + @kbd{M-x eshell} invokes a shell implemented entirely in Emacs. It +is documented in a separate manual. @xref{Top,Eshell,Eshell, eshell, +Eshell: The Emacs Shell}. + +@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. +* Shell Prompts:: Two ways to recognize shell prompts. +* History: Shell History. Repeating previous commands in a shell buffer. +* Directory Tracking:: Keeping track when the subshell changes directory. +* Options: Shell Options. Options for customizing Shell mode. +* Terminal emulator:: An Emacs window as a terminal emulator. +* Term Mode:: Special Emacs commands used in Term mode. +* Paging in Term:: Paging in the terminal emulator. +* 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 appears +either in the echo area (if it is short), or in an Emacs buffer named +@samp{*Shell Command Output*}, which is displayed in another window +but not selected (if the output is long). + + For instance, one way to decompress a file @file{foo.gz} from Emacs +is to type @kbd{M-! gunzip foo.gz @key{RET}}. That shell command +normally creates the file @file{foo} and produces no terminal output. + + A numeric argument, as in @kbd{M-1 M-!}, says to insert terminal +output into the current buffer instead of a separate buffer. It puts +point before the output, and sets the mark after the output. For +instance, @kbd{M-1 M-! gunzip < foo.gz @key{RET}} would insert the +uncompressed equivalent of @file{foo.gz} into the current buffer. + + 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. You do not get any status information for an asynchronous +command, since it hasn't finished yet when @code{shell-command} returns. + +@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. With a numeric argument, meaning insert +the output in the current buffer, it deletes the old region and the +output replaces it as the contents of the region. It returns the +command's exit status, like @kbd{M-!}. + + One use for @kbd{M-|} is to run @code{gpg} to see what keys are in +the buffer. For instance, if the buffer contains a GPG key, type +@kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents to +the @code{gpg} program. That program will ignore everything except +the encoded keys, and will output a list of the keys the buffer +contains. + +@vindex shell-file-name + Both @kbd{M-!} and @kbd{M-|} use @code{shell-file-name} to specify +the shell to use. This variable is initialized based on your +@env{SHELL} environment variable when Emacs is started. If the file +name is relative, Emacs searches the directories in the list +@code{exec-path}; this list is initialized based on the environment +variable @env{PATH} when Emacs is started. Your @file{.emacs} file +can override either or both of these default initializations. + + Both @kbd{M-!} and @kbd{M-|} wait for the shell command to complete, +unless you end the command with @samp{&} to make it asynchronous. 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 then 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. + + Asynchronous commands ending in @samp{&} feed their output into +the buffer @samp{*Async Shell Command*}. Output arrives in that +buffer regardless of whether it is visible in a window. + + To specify a coding system for @kbd{M-!} or @kbd{M-|}, use the command +@kbd{C-x @key{RET} c} immediately beforehand. @xref{Communication Coding}. + +@vindex shell-command-default-error-buffer + Error output from these commands is normally intermixed with the +regular output. But if the variable +@code{shell-command-default-error-buffer} has a string as value, and +it's the name of a buffer, @kbd{M-!} and @kbd{M-|} insert error output +before point in that buffer. + +@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. + +@cindex @code{comint-highlight-input} face +@cindex @code{comint-highlight-prompt} face + Input lines, once you submit them, are displayed using the face +@code{comint-highlight-input}, and prompts are displayed using the +face @code{comint-highlight-prompt}. This makes it easier to see +previous input lines in the buffer. @xref{Faces}. + + To make multiple subshells, you can invoke @kbd{M-x shell} with a +prefix argument (e.g. @kbd{C-u M-x shell}), which will read a buffer +name and create (or reuse) a subshell in that buffer. You can also +rename the @samp{*shell*} buffer using @kbd{M-x rename-uniquely}, then +create a new @samp{*shell*} buffer using plain @kbd{M-x shell}. +Subshells in different buffers run independently and in parallel. + +@vindex explicit-shell-file-name +@cindex environment variables for subshells +@cindex @env{ESHELL} environment variable +@cindex @env{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 @env{ESHELL} is used, or the environment +variable @env{SHELL} if there is no @env{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 +@env{PATH} when Emacs is started. Your @file{.emacs} file can override +either or both of these default initializations. + + Emacs sends the new shell the contents of the file +@file{~/.emacs_@var{shellname}} as input, if it 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}. If this file is not found, Emacs tries to fallback +on @file{~/.emacs.d/init_@var{shellname}.sh}. + + 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 change the coding system for a running subshell by typing +@kbd{C-x @key{RET} p} in the shell buffer. @xref{Communication +Coding}. + +@cindex @env{INSIDE_EMACS} environment variable + Emacs sets the envitonment variable @env{INSIDE_EMACS} to @code{t} +in the subshell. Programs can check this variable to determine +whether they are running inside an Emacs subshell. + +@cindex @env{EMACS} environment variable + Emacs also sets the @env{EMACS} environment variable to @code{t} if +it is not already defined. @strong{Warning:} This environment +variable is deprecated. Programs that check this variable should be +changed to check @env{INSIDE_EMACS} instead. + +@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}). Copying a line +in this way omits any prompt at the beginning of the line (text output +by programs preceding your input). @xref{Shell Prompts}, for how +Shell mode recognizes prompts. + +@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 is @code{nil}, but some users prefer @code{("~" "#" "%")} to +ignore 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 @acronym{EOF} +(@code{comint-delchar-or-maybe-eof}). Typed at the end of the shell +buffer, @kbd{C-d} sends @acronym{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-or-process-mark +Move to the beginning of the line, but after the prompt if any +(@code{comint-bol-or-process-mark}). 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}). If point is not at end of buffer, +this only kills the part of this text that precedes point. + +@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-delete-output +Delete the last batch of output from a shell command +(@code{comint-delete-output}). This is useful if a shell command spews +out lots of output that just gets in the way. This command used to be +called @code{comint-kill-output}. + +@item C-c C-s +@kindex C-c C-s @r{(Shell mode)} +@findex comint-write-output +Write the last batch of output from a shell command to a file +(@code{comint-write-output}). With a prefix argument, the file is +appended to instead. Any prompt at the end of the output is not +written. + +@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 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. + +Please note that Emacs will not echo passwords by default. If you +really want them to be echoed, evaluate the following Lisp +expression: + +@example +(remove-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 + +@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 include +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 Prompts +@subsection Shell Prompts + +@vindex shell-prompt-pattern +@vindex comint-prompt-regexp +@vindex comint-use-prompt-regexp +@cindex prompt, shell + A prompt is text output by a program to show that it is ready to +accept new user input. Normally, Comint mode (and thus Shell mode) +considers the prompt to be any text output by a program at the +beginning of an input line. However, if the variable +@code{comint-use-prompt-regexp} is non-@code{nil}, then Comint mode +uses a regular expression to recognize prompts. In Shell mode, +@code{shell-prompt-pattern} specifies the regular expression. + + The value of @code{comint-use-prompt-regexp} also affects many +motion and paragraph commands. If the value is non-@code{nil}, the +general Emacs motion commands behave as they normally do in buffers +without special text properties. However, if the value is @code{nil}, +the default, then Comint mode divides the buffer into two types of +``fields'' (ranges of consecutive characters having the same +@code{field} text property): input and output. Prompts are part of +the output. Most Emacs motion commands do not cross field boundaries, +unless they move over multiple lines. For instance, when point is in +input on the same line as a prompt, @kbd{C-a} puts point at the +beginning of the input if @code{comint-use-prompt-regexp} is +@code{nil} and at the beginning of the line otherwise. + + In Shell mode, only shell prompts start new paragraphs. Thus, a +paragraph consists of a prompt and the input and output that follow +it. However, if @code{comint-use-prompt-regexp} is @code{nil}, the +default, most paragraph commands do not cross field boundaries. This +means that prompts, ranges of input, and ranges of non-prompt output +behave mostly like separate paragraphs; with this setting, numeric +arguments to most paragraph commands yield essentially undefined +behavior. For the purpose of finding paragraph boundaries, Shell mode +uses @code{shell-prompt-pattern}, regardless of +@code{comint-use-prompt-regexp}. + +@node Shell History +@subsection Shell Command History + + Shell buffers support three ways of repeating earlier commands. You +can use keys like those used for the minibuffer history; 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 +@itemx C-@key{UP} +Fetch the next earlier old shell command. + +@kindex M-n @r{(Shell mode)} +@findex comint-next-input +@item M-n +@itemx C-@key{DOWN} +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 +@kindex C-c C-x @r{(Shell mode)} +@findex comint-get-next-from-history +Fetch the next subsequent command from the history. + +@item C-c . +@kindex C-c . @r{(Shell mode)} +@findex comint-input-previous-argument +Fetch one argument from an old shell 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}). +@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. +@kbd{C-@key{UP}} works like @kbd{M-p}, and @kbd{C-@key{DOWN}} like +@kbd{M-n}. + + 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-n}. 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. Any partial input you were composing before navigating the +history list is restored when you go to the beginning or end of the +history ring. + + 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. + + The command @kbd{C-c .}@: (@code{comint-input-previous-argument}) +copies an individual argument from a previous command, like @kbd{ESC +.} in Bash. The simplest use copies the last argument from the +previous shell command. With a prefix argument @var{n}, it copies the +@var{n}th argument instead. Repeating @kbd{C-c .} copies from an +earlier shell command instead, always using the same value of @var{n} +(don't give a prefix argument when you repeat the @kbd{C-c .} +command). + + 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 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. If you use this command on an +output line, it copies that line to the end of the buffer. + +@item Mouse-2 +If @code{comint-use-prompt-regexp} is @code{nil} (the default), copy +the old input command that you click on, inserting the copy at the end +of the buffer (@code{comint-insert-input}). If +@code{comint-use-prompt-regexp} is non-@code{nil}, or if the click is +not over old input, just yank as usual. +@end table + + Moving to a previous input and then copying it with @kbd{C-c +@key{RET}} or @kbd{Mouse-2} 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 +recognizes these constructs, and can 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 comint-input-autoexpand +@findex comint-magic-space + 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}. You can make +@key{SPC} perform history expansion by binding @key{SPC} to the +command @code{comint-magic-space}. + + Shell mode recognizes history references when they follow a prompt. +@xref{Shell Prompts}, for how Shell mode recognizes prompts. + +@node Directory Tracking +@subsection Directory Tracking +@cindex directory tracking + +@vindex shell-pushd-regexp +@vindex shell-popd-regexp +@vindex shell-cd-regexp + Shell mode keeps track of @samp{cd}, @samp{pushd} and @samp{popd} +commands given to the inferior shell, so it can keep the +@samp{*shell*} buffer's default directory the same as the shell's +working directory. It recognizes these commands 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. + +@ignore @c This seems to have been deleted long ago. +@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}). +@end ignore + +@findex dirs + If Emacs gets confused about 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. + +@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. The default is @code{nil}. + +@vindex comint-scroll-show-maximum-output + If @code{comint-scroll-show-maximum-output} is non-@code{nil}, then +arrival of output when point is at the end tries to scroll the last +line of text to the bottom line of the window, showing as much useful +text as possible. (This mimics the scrolling behavior of most +terminals.) The default is @code{t}. + +@vindex comint-move-point-for-output + By setting @code{comint-move-point-for-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-prompt-read-only + If you set @code{comint-prompt-read-only}, the prompts in the Comint +buffer are read-only. + +@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. + +@vindex shell-completion-execonly + Command completion normally considers only executable files. +If you set @code{shell-completion-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. + + If you want Shell mode to handle color output from shell commands, +you can enable ANSI Color mode. Here is how to do this: + +@example +(add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on) +@end example + +@node Terminal emulator +@subsection Emacs Terminal Emulator +@findex term + + To run a subshell in a terminal emulator, putting its typescript in +an Emacs buffer, use @kbd{M-x term}. This creates (or reuses) a +buffer named @samp{*terminal*}, and runs a subshell with input coming +from your keyboard, and output going to that buffer. + + The terminal emulator uses Term mode, which has two input modes. In +line mode, Term basically acts like Shell mode; see @ref{Shell Mode}. + + In char mode, each character is sent directly to the inferior +subshell, as ``terminal input.'' Any ``echoing'' of your input is the +responsibility of the subshell. The sole exception is the terminal +escape character, which by default is @kbd{C-c} (@pxref{Term Mode}). +Any ``terminal output'' from the subshell goes into the buffer, +advancing point. + + Some programs (such as Emacs itself) need to control the appearance +on the terminal screen in detail. They do this by sending special +control codes. The exact control codes needed vary from terminal to +terminal, but nowadays most terminals and terminal emulators +(including @code{xterm}) understand the ANSI-standard (VT100-style) +escape sequences. Term mode recognizes these escape sequences, and +handles each one appropriately, changing the buffer so that the +appearance of the window matches what it would be on a real terminal. +You can actually run Emacs inside an Emacs Term window. + + The file name used to load the subshell is determined the same way +as for Shell mode. To make multiple terminal emulators, rename the +buffer @samp{*terminal*} to something different using @kbd{M-x +rename-uniquely}, just as with Shell mode. + + Unlike Shell mode, Term mode does not track the current directory by +examining your input. But some shells can tell Term what the current +directory is. This is done automatically by @code{bash} version 1.15 +and later. + +@node Term Mode +@subsection Term Mode +@cindex Term mode +@cindex mode, Term + + The terminal emulator uses Term mode, which has two input modes. In +line mode, Term basically acts like Shell mode; see @ref{Shell Mode}. +In char mode, each character is sent directly to the inferior +subshell, except for the Term escape character, normally @kbd{C-c}. + + To switch between line and char mode, use these commands: + +@table @kbd +@kindex C-c C-j @r{(Term mode)} +@findex term-char-mode +@item C-c C-j +Switch to line mode. Do nothing if already in line mode. + +@kindex C-c C-k @r{(Term mode)} +@findex term-line-mode +@item C-c C-k +Switch to char mode. Do nothing if already in char mode. +@end table + + The following commands are only available in char mode: + +@table @kbd +@item C-c C-c +Send a literal @key{C-c} to the sub-shell. + +@item C-c @var{char} +This is equivalent to @kbd{C-x @var{char}} in normal Emacs. For +example, @kbd{C-c o} invokes the global binding of @kbd{C-x o}, which +is normally @samp{other-window}. +@end table + +@node Paging in Term +@subsection Page-At-A-Time Output +@cindex page-at-a-time + + Term mode has a page-at-a-time feature. When enabled it makes +output pause at the end of each screenful. + +@table @kbd +@kindex C-c C-q @r{(Term mode)} +@findex term-pager-toggle +@item C-c C-q +Toggle the page-at-a-time feature. This command works in both line +and char modes. When page-at-a-time is enabled, the mode-line +displays the word @samp{page}. +@end table + + With page-at-a-time enabled, whenever Term receives more than a +screenful of output since your last input, it pauses, displaying +@samp{**MORE**} in the mode-line. Type @key{SPC} to display the next +screenful of output. Type @kbd{?} to see your other options. The +interface is similar to the @code{more} program. + +@node Remote Host +@subsection Remote Host Shell +@cindex remote host +@cindex connecting to remote host +@cindex Telnet +@cindex Rlogin + + You can login to a remote computer, using whatever commands you +would from a regular terminal (e.g.@: using the @code{telnet} or +@code{rlogin} commands), from a Term window. + + A program that asks you for a password will normally suppress +echoing of the password, so the password will not show up in the +buffer. This will happen just as if you were using a real terminal, +if the buffer is in char mode. If it is in line mode, the password is +temporarily visible, but will be erased when you hit return. (This +happens automatically; there is no special password processing.) + + When you log in to a different machine, you need to specify the type +of terminal you're using, by setting the @env{TERM} environment +variable in the environment for the remote login command. (If you use +bash, you do that by writing the variable assignment before the remote +login command, without separating comma.) Terminal types @samp{ansi} +or @samp{vt100} will work on most systems. + +@c If you are talking to a Bourne-compatible +@c shell, and your system understands the @env{TERMCAP} variable, +@c you can use the command @kbd{M-x shell-send-termcap}, which +@c sends a string specifying the terminal type and size. +@c (This command is also useful after the window has changed size.) + +@c You can of course run @samp{gdb} on that remote computer. One useful +@c trick: If you invoke gdb with the @code{--fullname} option, +@c it will send special commands to Emacs that will cause Emacs to +@c pop up the source files you're debugging. This will work +@c whether or not gdb is running on a different computer than Emacs, +@c as long as Emacs can access the source files specified by gdb. + +@ignore + You cannot log in to a remote computer using the Shell mode. +@c (This will change when Shell is re-written to use Term.) +Instead, Emacs provides two commands for logging in to another computer +and communicating with it through an Emacs buffer using Comint mode: + +@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. + +@end ignore + +@node Emacs Server, Printing, Shell, Top +@section Using Emacs as a Server +@pindex emacsclient +@cindex Emacs as a server +@cindex server, using Emacs as +@cindex @env{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 @env{EDITOR} to specify which editor to run. If you set +@env{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 with any 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 program and the +server that is part of Emacs. Here is how. + +@cindex @env{TEXEDIT} environment variable +@findex server-start + First, the preparations. Within Emacs, call the function +@code{server-start}. (Your @file{.emacs} init file can do this +automatically if you add the expression @code{(server-start)} to it, +see @ref{Init File}.) Then, outside Emacs, set the @env{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 @env{TEXEDIT} environment +variable to @samp{emacsclient +%d %s}.) + +@pindex emacs.bash +@cindex Bash command to use Emacs server + As an alternative to using @code{emacsclient}, the file +@file{etc/emacs.bash} defines a Bash command @code{edit} which will +communicate with a running Emacs session, or start one if none exist. + +@kindex C-x # +@findex server-edit + Now, whenever any program invokes your specified @env{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 in the already running Emacs session. + + 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 @env{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 way to +say that you are finished with one. + +@vindex server-kill-new-buffers +@vindex server-temp-file-regexp + Finishing with a server buffer also kills the buffer, unless it +already existed in the Emacs session before the server asked to create +it. However, if you set @code{server-kill-new-buffers} to @code{nil}, +then a different criterion is used: finishing with a server buffer +kills it if the file name matches the regular expression +@code{server-temp-file-regexp}. This is set up to distinguish certain +``temporary'' files. + +@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. + +@vindex server-name + You can run multiple Emacs servers on the same machine by giving +each one a unique ``server name'', using the variable +@code{server-name}. For example, @kbd{M-x set-variable @key{RET} +server-name @key{RET} foo @key{RET}} sets the server name to +@samp{foo}. The @code{emacsclient} program can specify a server by +name using the @samp{-s} option. @xref{Invoking emacsclient}. + + 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 +three 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 +Using virtual terminals, run @code{mail} in one virtual terminal +and run Emacs in another. + +@item +Use Shell mode or Term 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 + + If you run @code{emacsclient} with the option @samp{--no-wait}, it +returns immediately without waiting for you to ``finish'' the buffer +in Emacs. Note that server buffers created in this way are not killed +automatically when you finish with them. + +@menu +* Invoking emacsclient:: Emacs client startup options. +@end menu + +@node Invoking emacsclient,, Emacs Server, Emacs Server +@subsection Invoking @code{emacsclient} +@cindex @code{emacsclient} invocation and options + + To run the @code{emacsclient} program, specify file names as arguments, +and optionally line numbers as well, like this: + +@example +emacsclient @r{@{}@r{[}+@var{line}@r{[}@var{column}@r{]}@r{]} @var{filename}@r{@}}@dots{} +@end example + +@noindent +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. +If you specify a column number as well, Emacs puts point on that column +in the line. + + 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. + + If you invoke @code{emacsclient} for more than one file, the +additional client buffers are buried at the bottom of the buffer list +(@pxref{Buffers}). If you call @kbd{C-x #} after you are done editing +a client buffer, the next client buffer is automatically selected. + + 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.) + + The option @samp{-a @var{command}} or +@samp{--alternate-editor=@var{command}} specifies a command to run if +@code{emacsclient} fails to contact Emacs. This is useful when +running @code{emacsclient} in a script. For example, the following +setting for the @env{EDITOR} environment variable will always give you +an editor, even if no Emacs server is running: + +@example +EDITOR="emacsclient --alternate-editor emacs +%d %s" +@end example + +@noindent +@cindex @env{ALTERNATE_EDITOR} environment variable +The environment variable @env{ALTERNATE_EDITOR} has the same effect, with +the value of the @samp{--alternate-editor} option taking precedence. + +If you use several displays, you can tell Emacs on which display to +open the given files with the @samp{-d @var{display}} or +@samp{--display=@var{display}} option to @code{emacsclient}. This is +handy when connecting from home to an Emacs session running on your +machine at your workplace. + +If there is more than one Emacs server running, you can specify a +server name with the @samp{-s @var{name}} or +@samp{--socket-name=@var{name}} option to @code{emacsclient}. (This +option is not supported on MS-Windows.) + +You can also use @code{emacsclient} to execute any piece of Emacs Lisp +code, using the @samp{-e} or @samp{--eval} option. When this option +is given, the rest of the arguments is interpreted as a list of +expressions to evaluate, not a list of files to visit. + +@cindex @env{EMACS_SERVER_FILE} environment variable +When you start the Emacs server (by calling @code{server-start}), +Emacs creates a file with information about TCP connection to the +server: the host where Emacs is running, the port where it is +listening, and an authentication string. @code{emacsclient} uses this +information if it needs to connect to the server via TCP. By default, +the file goes in the @file{~/.emacs.d/server/} directory@footnote{On +MS-Windows, if @env{HOME} is not set or the TCP configuration file +cannot be found there, Emacs also looks for the file in the +@file{.emacs.d/server/} subdirectory of the directory pointed to by +the @env{APPDATA} environment variable.}. You can specify the file +name to use with the @samp{-f @var{file}} or +@samp{--server-file=@var{file}} options, or by setting +@env{EMACS_SERVER_FILE} environment variable to the file name. + +@node Printing, Sorting, Emacs Server, Top +@section Printing Hard Copies +@cindex hardcopy +@cindex printing + + Emacs provides commands for printing hard copies of either an entire +buffer or just part of one, with or without page headers. You can +invoke the printing commands directly, as detailed in the following +section, or using the @samp{File} menu on the menu bar. See also the +hardcopy commands of Dired (@pxref{Misc File Ops}) and the diary +(@pxref{Displaying the Diary}). + +@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}. + +@menu +* PostScript:: Printing buffers or regions as PostScript. +* PostScript Variables:: Customizing the PostScript printing commands. +* Printing Package:: An optional advanced printing interface. +@end menu + +@node PostScript, PostScript Variables,, Printing +@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. +@item M-x handwrite +Generates/prints PostScript for the current buffer as if handwritten. +@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. + +@findex handwrite +@cindex handwriting +@kbd{M-x handwrite} is more frivolous. It generates a PostScript +rendition of the current buffer as a cursive handwritten document. It +can be customized in group @code{handwrite}. This function only +supports ISO 8859-1 characters. + +@ifnottex + The following section describes variables for customizing these commands. +@end ifnottex + +@node PostScript Variables, Printing Package, PostScript, Printing +@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 + 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. + +@cindex color emulation on black-and-white printers +@vindex ps-print-color-p + If your printer doesn't support colors, you should turn off color +processing by setting @code{ps-print-color-p} to @code{nil}. By +default, if the display supports colors, Emacs produces hardcopy output +with color information; on black-and-white printers, colors are emulated +with shades of gray. This might produce illegible output, even if your +screen colors only use shades of gray. + +@vindex ps-use-face-background + By default, PostScript printing ignores the background colors of the +faces, unless the variable @code{ps-use-face-background} is +non-@code{nil}. This is to avoid unwanted interference with the zebra +stripes and background image/text. + +@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. + +@vindex ps-multibyte-buffer +@cindex Intlfonts for PostScript printing +@cindex fonts for PostScript printing + Emacs supports more scripts and characters than a typical PostScript +printer. Thus, some of the characters in your buffer might not be +printable using the fonts built into your printer. You can augment +the fonts supplied with the printer with those from the GNU Intlfonts +package, or you can instruct Emacs to use Intlfonts exclusively. The +variable @code{ps-multibyte-buffer} controls this: the default value, +@code{nil}, is appropriate for printing @acronym{ASCII} and Latin-1 +characters; a value of @code{non-latin-printer} is for printers which +have the fonts for @acronym{ASCII}, Latin-1, Japanese, and Korean +characters built into them. A value of @code{bdf-font} arranges for +the BDF fonts from the Intlfonts package to be used for @emph{all} +characters. Finally, a value of @code{bdf-font-except-latin} +instructs the printer to use built-in fonts for @acronym{ASCII} and Latin-1 +characters, and Intlfonts BDF fonts for the rest. + +@vindex bdf-directory-list + To be able to use the BDF fonts, Emacs needs to know where to find +them. The variable @code{bdf-directory-list} holds the list of +directories where Emacs should look for the fonts; the default value +includes a single directory @file{/usr/local/share/emacs/fonts/bdf}. + + Many other customization variables for these commands are defined and +described in the Lisp files @file{ps-print.el} and @file{ps-mule.el}. + +@node Printing Package,, PostScript Variables, Printing +@section Printing Package +@cindex Printing package + + The basic Emacs facilities for printing hardcopy can be extended +using the Printing package. This provides an easy-to-use interface +for choosing what to print, previewing PostScript files before +printing, and setting various printing options such as print headers, +landscape or portrait modes, duplex modes, and so forth. On GNU/Linux +or Unix systems, the Printing package relies on the @file{gs} and +@file{gv} utilities, which are distributed as part of the GhostScript +program. On MS-Windows, the @file{gstools} port of Ghostscript can be +used. + +@findex pr-interface + To use the Printing package, add @code{(require 'printing)} to your +init file (@pxref{Init File}), followed by @code{(pr-update-menus)}. +This function replaces the usual printing commands in the menu bar +with a @samp{Printing} submenu that contains various printing options. +You can also type @kbd{M-x pr-interface RET}; this creates a +@samp{*Printing Interface*} buffer, similar to a customization buffer, +where you can set the printing options. After selecting what and how +to print, you start the print job using the @samp{Print} button (click +@kbd{mouse-2} on it, or move point over it and type @kbd{RET}). For +further information on the various options, use the @samp{Interface +Help} button. + +@node Sorting, Narrowing, Printing, Top +@section Sorting Text +@cindex sorting + + Emacs provides several commands for sorting text in the buffer. All +operate on the contents of the region. +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 @acronym{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 +@vindex sort-numeric-base +@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 the 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. By default, numbers are interpreted according +to @code{sort-numeric-base}, but numbers beginning with @samp{0x} or +@samp{0} are interpreted as hexadecimal and octal, respectively. + +@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 bounds of narrowing in effect in a buffer +are 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 limit the +range of operation of a replace command or repeating keyboard macro. + +@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 +@cindex hex editing + 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 + +@noindent +Other Hexl commands let you insert strings (sequences) of binary +bytes, move by @code{short}s or @code{int}s, etc.; type @kbd{C-h a +hexl-@key{RET}} for details. + + +@node Saving Emacs Sessions, Recursive Edit, Editing Binary Files, Top +@section Saving Emacs Sessions +@cindex saving sessions +@cindex restore session +@cindex remember editing session +@cindex reload files +@cindex desktop + + Use the desktop library to save the state of Emacs from one session +to another. Once you save the Emacs @dfn{desktop}---the buffers, +their file names, major modes, buffer positions, and so on---then +subsequent Emacs sessions reload the saved desktop. + +@findex desktop-save +@vindex desktop-save-mode + You can save the desktop manually with the command @kbd{M-x +desktop-save}. You can also enable automatic saving of the desktop +when you exit Emacs, and automatic restoration of the last saved +desktop when Emacs starts: use the Customization buffer (@pxref{Easy +Customization}) to set @code{desktop-save-mode} to @code{t} for future +sessions, or add this line in your @file{~/.emacs} file: + +@example +(desktop-save-mode 1) +@end example + +@findex desktop-change-dir +@findex desktop-revert + If you turn on @code{desktop-save-mode} in your @file{~/.emacs}, +then when Emacs starts, it looks for a saved desktop in the current +directory. Thus, you can have separate saved desktops in different +directories, and the starting directory determines which one Emacs +reloads. You can save the current desktop and reload one saved in +another directory by typing @kbd{M-x desktop-change-dir}. Typing +@kbd{M-x desktop-revert} reverts to the desktop previously reloaded. + + Specify the option @samp{--no-desktop} on the command line when you +don't want it to reload any saved desktop. This turns off +@code{desktop-save-mode} for the current session. Starting Emacs with +the @samp{--no-init-file} option also disables desktop reloading, +since it bypasses the @file{.emacs} init file, where +@code{desktop-save-mode} is usually turned on. + +@vindex desktop-restore-eager + By default, all the buffers in the desktop are restored at one go. +However, this may be slow if there are a lot of buffers in the +desktop. You can specify the maximum number of buffers to restore +immediately with the variable @code{desktop-restore-eager}; the +remaining buffers are restored ``lazily,'' when Emacs is idle. + +@findex desktop-clear +@vindex desktop-globals-to-clear +@vindex desktop-clear-preserve-buffers-regexp + Type @kbd{M-x desktop-clear} to empty the Emacs desktop. This kills +all buffers except for internal ones, and clears the global variables +listed in @code{desktop-globals-to-clear}. If you want this to +preserve certain buffers, customize the variable +@code{desktop-clear-preserve-buffers-regexp}, whose value is a regular +expression matching the names of buffers not to kill. + + If you want to save minibuffer history from one session to +another, use the @code{savehist} library. + +@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, Hyperlinking, Recursive Edit, Top +@section Emulation +@cindex emulating other editors +@cindex other editors +@cindex EDT +@cindex vi +@cindex PC key bindings +@cindex scrolling all windows +@cindex PC selection +@cindex Motif key bindings +@cindex Macintosh key bindings +@cindex WordStar + + GNU Emacs can be programmed to emulate (more or less) most other +editors. Standard facilities can emulate these: + +@table @asis +@item CRiSP/Brief (PC editor) +@findex crisp-mode +@vindex crisp-override-meta-x +@findex scroll-all-mode +@cindex CRiSP mode +@cindex Brief emulation +@cindex emulation of Brief +@cindex mode, CRiSP +You can turn on key bindings to emulate the CRiSP/Brief editor with +@kbd{M-x crisp-mode}. Note that this rebinds @kbd{M-x} to exit Emacs +unless you set the variable @code{crisp-override-meta-x}. You can +also use the command @kbd{M-x scroll-all-mode} or set the variable +@code{crisp-load-scroll-all} to emulate CRiSP's scroll-all feature +(scrolling all windows together). + +@item EDT (DEC VMS editor) +@findex edt-emulation-on +@findex edt-emulation-off +Turn on EDT emulation with the command @kbd{M-x edt-emulation-on}, +while @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 TPU (DEC VMS editor) +@findex tpu-edt-on +@cindex TPU +@kbd{M-x tpu-edt-on} turns on emulation of the TPU editor emulating EDT. + +@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. + +@item WordStar (old wordprocessor) +@findex wordstar-mode +@kbd{M-x wordstar-mode} provides a major mode with WordStar-like +key bindings. +@end table + +@node Hyperlinking, Dissociated Press, Emulation, Top +@section Hyperlinking and Navigation Features + +@cindex hyperlinking +@cindex navigation + Various modes documented elsewhere have hypertext features so that +you can follow links, usually by clicking @kbd{Mouse-2} on the link or +typing @key{RET} while point is on the link. Clicking @kbd{Mouse-1} +quickly on the link also follows it. (Hold @kbd{Mouse-1} for longer +if you want to set point instead.) + + Info mode, Help mode and the Dired-like modes are examples of modes +that have links in the buffer. The Tags facility links between uses +and definitions in source files, see @ref{Tags}. Imenu provides +navigation amongst items indexed in the current buffer, see +@ref{Imenu}. Info-lookup provides mode-specific lookup of definitions +in Info indexes, see @ref{Documentation}. Speedbar maintains a frame +in which links to files, and locations in files are displayed, see +@ref{Speedbar}. + + Other non-mode-specific facilities described in this section enable +following links from the current buffer in a context-sensitive +fashion. + +@menu +* Browse-URL:: Following URLs. +* Goto-address:: Activating URLs. +* FFAP:: Finding files etc. at point. +@end menu + +@node Browse-URL +@subsection Following URLs +@cindex World Wide Web +@cindex Web +@findex browse-url +@findex browse-url-at-point +@findex browse-url-at-mouse +@cindex Browse-URL +@cindex URLs + +@table @kbd +@item M-x browse-url @key{RET} @var{url} @key{RET} +Load a URL into a Web browser. +@end table + +The Browse-URL package provides facilities for following URLs specifying +links on the World Wide Web. Usually this works by invoking a web +browser, but you can, for instance, arrange to invoke @code{compose-mail} +from @samp{mailto:} URLs. + + The general way to use this feature is to type @kbd{M-x browse-url}, +which displays a specified URL. If point is located near a plausible +URL, that URL is used as the default. Other commands are available +which you might like to bind to keys, such as +@code{browse-url-at-point} and @code{browse-url-at-mouse}. + +@vindex browse-url-browser-function + You can customize Browse-URL's behavior via various options in the +@code{browse-url} Customize group, particularly +@code{browse-url-browser-function}. You can invoke actions dependent +on the type of URL by defining @code{browse-url-browser-function} as +an association list. The package's commentary available via @kbd{C-h +p} under the @samp{hypermedia} keyword provides more information. +Packages with facilities for following URLs should always go through +Browse-URL, so that the customization options for Browse-URL will +affect all browsing in Emacs. + +@node Goto-address +@subsection Activating URLs +@findex goto-address +@cindex Goto-address +@cindex URLs, activating + +@table @kbd +@item M-x goto-address +Activate URLs and e-mail addresses in the current buffer. +@end table + + You can make URLs in the current buffer active with @kbd{M-x +goto-address}. This finds all the URLs in the buffer, and establishes +bindings for @kbd{Mouse-2} and @kbd{C-c @key{RET}} on them. After +activation, if you click on a URL with @kbd{Mouse-2}, or move to a URL +and type @kbd{C-c @key{RET}}, that will display the web page that the URL +specifies. For a @samp{mailto} URL, it sends mail instead, using your +selected mail-composition method (@pxref{Mail Methods}). + + It can be useful to add @code{goto-address} to mode hooks and the +hooks used to display an incoming message. +@code{rmail-show-message-hook} is the appropriate hook for Rmail, and +@code{mh-show-mode-hook} for MH-E. This is not needed for Gnus, +which has a similar feature of its own. + + +@node FFAP +@subsection Finding Files and URLs at Point +@findex find-file-at-point +@findex ffap +@findex dired-at-point +@findex ffap-next +@findex ffap-menu +@cindex finding file at point + + FFAP mode replaces certain key bindings for finding files, including +@kbd{C-x C-f}, with commands that provide more sensitive defaults. +These commands behave like the ordinary ones when given a prefix +argument. Otherwise, they get the default file name or URL from the +text around point. If what is found in the buffer has the form of a +URL rather than a file name, the commands use @code{browse-url} to +view it. + + This feature is useful for following references in mail or news +buffers, @file{README} files, @file{MANIFEST} files, and so on. The +@samp{ffap} package's commentary available via @kbd{C-h p} under the +@samp{files} keyword and the @code{ffap} Custom group provide details. + +@cindex FFAP minor mode +@findex ffap-mode + You can turn on FFAP minor mode by calling @code{ffap-bindings} to +make the following key bindings and to install hooks for using +@code{ffap} in Rmail, Gnus and VM article buffers. + +@table @kbd +@item C-x C-f @var{filename} @key{RET} +@kindex C-x C-f @r{(FFAP)} +Find @var{filename}, guessing a default from text around point +(@code{find-file-at-point}). +@item C-x C-r +@kindex C-x C-r @r{(FFAP)} +@code{ffap-read-only}, analogous to @code{find-file-read-only}. +@item C-x C-v +@kindex C-x C-v @r{(FFAP)} +@code{ffap-alternate-file}, analogous to @code{find-alternate-file}. +@item C-x d @var{directory} @key{RET} +@kindex C-x d @r{(FFAP)} +Start Dired on @var{directory}, defaulting to the directory name at +point (@code{dired-at-point}). +@item C-x C-d +@code{ffap-list-directory}, analogous to @code{list-directory}. +@item C-x 4 f +@kindex C-x 4 f @r{(FFAP)} +@code{ffap-other-window}, analogous to @code{find-file-other-window}. +@item C-x 4 r +@code{ffap-read-only-other-window}, analogous to +@code{find-file-read-only-other-window}. +@item C-x 4 d +@code{ffap-dired-other-window}, analogous to @code{dired-other-window}. +@item C-x 5 f +@kindex C-x 5 f @r{(FFAP)} +@code{ffap-other-frame}, analogous to @code{find-file-other-frame}. +@item C-x 5 r +@code{ffap-read-only-other-frame}, analogous to +@code{find-file-read-only-other-frame}. +@item C-x 5 d +@code{ffap-dired-other-frame}, analogous to @code{dired-other-frame}. +@item M-x ffap-next +Search buffer for next file name or URL, then find that file or URL. +@item S-Mouse-3 +@kindex S-Mouse-3 @r{(FFAP)} +@code{ffap-at-mouse} finds the file guessed from text around the position +of a mouse click. +@item C-S-Mouse-3 +@kindex C-S-Mouse-3 @r{(FFAP)} +Display a menu of files and URLs mentioned in current buffer, then +find the one you select (@code{ffap-menu}). +@end table + +@node Dissociated Press, Amusements, Hyperlinking, 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 output `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. Bush has made it appropriate again.} 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 results fairly like those of 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 +@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 +@findex 5x5 +@cindex puzzles + @kbd{M-x blackbox}, @kbd{M-x mpuz} and @kbd{M-x 5x5} are 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. The aim of @code{5x5} is to fill in all the squares. + +@findex decipher +@cindex ciphers +@cindex cryptanalysis +@kbd{M-x decipher} helps you to cryptanalyze a buffer which is encrypted +in a simple monoalphabetic substitution cipher. + +@findex dunnet + @kbd{M-x dunnet} runs an adventure-style exploration game, which is +a bigger sort of puzzle. + +@findex lm +@cindex landmark game +@kbd{M-x lm} runs a relatively non-participatory game in which a robot +attempts to maneuver towards a tree at the center of the window based on +unique olfactory cues from each of the four directions. + +@findex life +@cindex Life +@kbd{M-x life} runs Conway's ``Life'' cellular automaton. + +@findex morse-region +@findex unmorse-region +@cindex Morse code +@cindex --/---/.-./.../. +@kbd{M-x morse-region} converts text in a region to Morse code and +@kbd{M-x unmorse-region} converts it back. No cause for remorse. + +@findex pong +@cindex Pong game +@kbd{M-x pong} plays a Pong-like game, bouncing the ball off opposing +bats. + +@findex solitaire +@cindex solitaire +@kbd{M-x solitaire} plays a game of solitaire in which you jump pegs +across other pegs. + +@findex studlify-region +@cindex StudlyCaps +@kbd{M-x studlify-region} studlify-cases the region, producing +text like this: + +@example +M-x stUdlIfY-RegioN stUdlIfY-CaSeS thE region. +@end example + +@findex tetris +@cindex Tetris +@findex snake +@cindex Snake +@kbd{M-x tetris} runs an implementation of the well-known Tetris game. +Likewise, @kbd{M-x snake} provides an implementation of Snake. + + 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}. + +@findex zone +The command @kbd{M-x zone} plays games with the display when Emacs is +idle. + +@ifnottex +@lowersections +@end ifnottex + +@ignore + arch-tag: 8f094220-c0d5-4e9e-af7d-3e0da8187474 +@end ignore diff --git a/doc/emacs/msdog-xtra.texi b/doc/emacs/msdog-xtra.texi new file mode 100644 index 00000000000..432f28888f6 --- /dev/null +++ b/doc/emacs/msdog-xtra.texi @@ -0,0 +1,687 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@c +@c This file is included either in emacs-xtra.texi (when producing the +@c printed version) or in the main Emacs manual (for the on-line version). +@node MS-DOS +@section Emacs and MS-DOS +@cindex MS-DOG +@cindex MS-DOS peculiarities + + This section briefly describes the peculiarities of using Emacs on +the MS-DOS ``operating system'' (also known as ``MS-DOG''). +@iftex +Information about Emacs and Microsoft's current operating system +Windows (also known as ``Losedows) is in the main Emacs manual +(@pxref{Microsoft Systems,,, emacs, the Emacs Manual}). +@end iftex +@ifnottex +Information about peculiarities common to MS-DOS and Microsoft's +current operating systems Windows (also known as ``Losedows) is in +@ref{Microsoft Windows}. +@end ifnottex + + If you build Emacs for MS-DOS, the binary will also run on Windows +3.X, Windows NT, Windows 9X/ME, Windows 2000/XP, or OS/2 as a DOS +application; all of this chapter applies for all of those systems, if +you use an Emacs that was built for MS-DOS. + +@iftex + @xref{Text and Binary,,,emacs, the Emacs Manual}, for information +@end iftex +@ifnottex + @xref{Text and Binary}, for information +@end ifnottex +about Emacs' special handling of text files under MS-DOS (and Windows). + +@menu +* Keyboard: MS-DOS Keyboard. Keyboard conventions on MS-DOS. +* Mouse: MS-DOS Mouse. Mouse conventions on MS-DOS. +* Display: MS-DOS Display. Fonts, frames and display size on MS-DOS. +* Files: MS-DOS File Names. File name conventions on MS-DOS. +* Printing: MS-DOS Printing. Printing specifics on MS-DOS. +* I18N: MS-DOS and MULE. Support for internationalization on MS-DOS. +* Processes: MS-DOS Processes. Running subprocesses on MS-DOS. +@end menu + +@node MS-DOS Keyboard +@subsection Keyboard Usage on MS-DOS + +@kindex DEL @r{(MS-DOS)} +@kindex BS @r{(MS-DOS)} + The key that is called @key{DEL} in Emacs (because that's how it is +designated on most workstations) is known as @key{BS} (backspace) on a +PC. That is why the PC-specific terminal initialization remaps the +@key{BS} key to act as @key{DEL}; the @key{DELETE} key is remapped to act +as @kbd{C-d} for the same reasons. + +@kindex C-g @r{(MS-DOS)} +@kindex C-BREAK @r{(MS-DOS)} +@cindex quitting on MS-DOS + Emacs built for MS-DOS recognizes @kbd{C-@key{BREAK}} as a quit +character, just like @kbd{C-g}. This is because Emacs cannot detect +that you have typed @kbd{C-g} until it is ready for more input. As a +consequence, you cannot use @kbd{C-g} to stop a running command +@iftex +(@pxref{Quitting,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Quitting}). +@end ifnottex +By contrast, @kbd{C-@key{BREAK}} @emph{is} detected as soon as you +type it (as @kbd{C-g} is on other systems), so it can be used to stop +a running command and for emergency escape +@iftex +(@pxref{Emergency Escape,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Emergency Escape}). +@end ifnottex + +@cindex Meta (under MS-DOS) +@cindex Hyper (under MS-DOS) +@cindex Super (under MS-DOS) +@vindex dos-super-key +@vindex dos-hyper-key + The PC keyboard maps use the left @key{ALT} key as the @key{META} key. +You have two choices for emulating the @key{SUPER} and @key{HYPER} keys: +choose either the right @key{CTRL} key or the right @key{ALT} key by +setting the variables @code{dos-hyper-key} and @code{dos-super-key} to 1 +or 2 respectively. If neither @code{dos-super-key} nor +@code{dos-hyper-key} is 1, then by default the right @key{ALT} key is +also mapped to the @key{META} key. However, if the MS-DOS international +keyboard support program @file{KEYB.COM} is installed, Emacs will +@emph{not} map the right @key{ALT} to @key{META}, since it is used for +accessing characters like @kbd{~} and @kbd{@@} on non-US keyboard +layouts; in this case, you may only use the left @key{ALT} as @key{META} +key. + +@kindex C-j @r{(MS-DOS)} +@vindex dos-keypad-mode + The variable @code{dos-keypad-mode} is a flag variable that controls +what key codes are returned by keys in the numeric keypad. You can also +define the keypad @key{ENTER} key to act like @kbd{C-j}, by putting the +following line into your @file{_emacs} file: + +@smallexample +;; @r{Make the @key{ENTER} key from the numeric keypad act as @kbd{C-j}.} +(define-key function-key-map [kp-enter] [?\C-j]) +@end smallexample + +@node MS-DOS Mouse +@subsection Mouse Usage on MS-DOS + +@cindex mouse support under MS-DOS + Emacs on MS-DOS supports a mouse (on the default terminal only). +The mouse commands work as documented, including those that use menus +and the menu bar +@iftex +(@pxref{Menu Bar,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Menu Bar}). +@end ifnottex + Scroll bars don't work in MS-DOS Emacs. PC mice usually have only +two buttons; these act as @kbd{Mouse-1} and @kbd{Mouse-2}, but if you +press both of them together, that has the effect of @kbd{Mouse-3}. If +the mouse does have 3 buttons, Emacs detects that at startup, and all +the 3 buttons function normally, as on X. + + Help strings for menu-bar and pop-up menus are displayed in the echo +area when the mouse pointer moves across the menu items. Highlighting +of mouse-sensitive text +@iftex +(@pxref{Mouse References,,,emacs, the Emacs Manual}) +@end iftex +@ifnottex +(@pxref{Mouse References}) +@end ifnottex +is also supported. + +@cindex mouse, set number of buttons +@findex msdos-set-mouse-buttons + Some versions of mouse drivers don't report the number of mouse +buttons correctly. For example, mice with a wheel report that they +have 3 buttons, but only 2 of them are passed to Emacs; the clicks on +the wheel, which serves as the middle button, are not passed. In +these cases, you can use the @kbd{M-x msdos-set-mouse-buttons} command +to tell Emacs how many mouse buttons to expect. You could make such a +setting permanent by adding this fragment to your @file{_emacs} init +file: + +@example +;; @r{Treat the mouse like a 2-button mouse.} +(msdos-set-mouse-buttons 2) +@end example + +@cindex Windows clipboard support + Emacs built for MS-DOS supports clipboard operations when it runs on +Windows. Commands that put text on the kill ring, or yank text from +the ring, check the Windows clipboard first, just as Emacs does on the +X Window System +@iftex +(@pxref{Mouse Commands,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Mouse Commands}). +@end ifnottex +Only the primary selection and the cut buffer are supported by MS-DOS +Emacs on Windows; the secondary selection always appears as empty. + + Due to the way clipboard access is implemented by Windows, the +length of text you can put into the clipboard is limited by the amount +of free DOS memory that is available to Emacs. Usually, up to 620KB of +text can be put into the clipboard, but this limit depends on the system +configuration and is lower if you run Emacs as a subprocess of +another program. If the killed text does not fit, Emacs outputs a +message saying so, and does not put the text into the clipboard. + + Null characters also cannot be put into the Windows clipboard. If the +killed text includes null characters, Emacs does not put such text into +the clipboard, and displays in the echo area a message to that effect. + +@vindex dos-display-scancodes + The variable @code{dos-display-scancodes}, when non-@code{nil}, +directs Emacs to display the @acronym{ASCII} value and the keyboard scan code of +each keystroke; this feature serves as a complement to the +@code{view-lossage} command, for debugging. + +@node MS-DOS Display +@subsection Display on MS-DOS +@cindex faces under MS-DOS +@cindex fonts, emulating under MS-DOS + + Display on MS-DOS cannot use font variants, like bold or italic, but +it does support multiple faces, each of which can specify a foreground +and a background color. Therefore, you can get the full functionality +of Emacs packages that use fonts (such as @code{font-lock}, Enriched +Text mode, and others) by defining the relevant faces to use different +colors. Use the @code{list-colors-display} command +@iftex +(@pxref{Frame Parameters,,,emacs, the Emacs Manual}) +@end iftex +@ifnottex +(@pxref{Frame Parameters}) +@end ifnottex +and the @code{list-faces-display} command +@iftex +(@pxref{Faces,,,emacs, the Emacs Manual}) +@end iftex +@ifnottex +(@pxref{Faces}) +@end ifnottex +to see what colors and faces are available and what they look like. + + @xref{MS-DOS and MULE}, later in this chapter, for information on +how Emacs displays glyphs and characters that aren't supported by the +native font built into the DOS display. + +@cindex cursor shape on MS-DOS + When Emacs starts, it changes the cursor shape to a solid box. This +is for compatibility with other systems, where the box cursor is the +default in Emacs. This default shape can be changed to a bar by +specifying the @code{cursor-type} parameter in the variable +@code{default-frame-alist} +@iftex +(@pxref{Creating Frames,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Creating Frames}). +@end ifnottex +The MS-DOS terminal doesn't support a vertical-bar cursor, +so the bar cursor is horizontal, and the @code{@var{width}} parameter, +if specified by the frame parameters, actually determines its height. +For this reason, the @code{bar} and @code{hbar} cursor types produce +the same effect on MS-DOS. As an extension, the bar cursor +specification can include the starting scan line of the cursor as well +as its width, like this: + +@example + '(cursor-type bar @var{width} . @var{start}) +@end example + +@noindent +In addition, if the @var{width} parameter is negative, the cursor bar +begins at the top of the character cell. + +@cindex frames on MS-DOS + The MS-DOS terminal can only display a single frame at a time. The +Emacs frame facilities work on MS-DOS much as they do on text-only +terminals +@iftex +(@pxref{Frames,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Frames}). +@end ifnottex +When you run Emacs from a DOS window on MS-Windows, you can make the +visible frame smaller than the full screen, but Emacs still cannot +display more than a single frame at a time. + +@cindex frame size under MS-DOS +@findex mode4350 +@findex mode25 + The @code{mode4350} command switches the display to 43 or 50 +lines, depending on your hardware; the @code{mode25} command switches +to the default 80x25 screen size. + + By default, Emacs only knows how to set screen sizes of 80 columns by +25, 28, 35, 40, 43 or 50 rows. However, if your video adapter has +special video modes that will switch the display to other sizes, you can +have Emacs support those too. When you ask Emacs to switch the frame to +@var{n} rows by @var{m} columns dimensions, it checks if there is a +variable called @code{screen-dimensions-@var{n}x@var{m}}, and if so, +uses its value (which must be an integer) as the video mode to switch +to. (Emacs switches to that video mode by calling the BIOS @code{Set +Video Mode} function with the value of +@code{screen-dimensions-@var{n}x@var{m}} in the @code{AL} register.) +For example, suppose your adapter will switch to 66x80 dimensions when +put into video mode 85. Then you can make Emacs support this screen +size by putting the following into your @file{_emacs} file: + +@example +(setq screen-dimensions-66x80 85) +@end example + + Since Emacs on MS-DOS can only set the frame size to specific +supported dimensions, it cannot honor every possible frame resizing +request. When an unsupported size is requested, Emacs chooses the next +larger supported size beyond the specified size. For example, if you +ask for 36x80 frame, you will get 40x80 instead. + + The variables @code{screen-dimensions-@var{n}x@var{m}} are used only +when they exactly match the specified size; the search for the next +larger supported size ignores them. In the above example, even if your +VGA supports 38x80 dimensions and you define a variable +@code{screen-dimensions-38x80} with a suitable value, you will still get +40x80 screen when you ask for a 36x80 frame. If you want to get the +38x80 size in this case, you can do it by setting the variable named +@code{screen-dimensions-36x80} with the same video mode value as +@code{screen-dimensions-38x80}. + + Changing frame dimensions on MS-DOS has the effect of changing all the +other frames to the new dimensions. + +@node MS-DOS File Names +@subsection File Names on MS-DOS +@cindex file names under MS-DOS +@cindex init file, default name under MS-DOS + + On MS-DOS, file names are case-insensitive and limited to eight +characters, plus optionally a period and three more characters. Emacs +knows enough about these limitations to handle file names that were +meant for other operating systems. For instance, leading dots +@samp{.} in file names are invalid in MS-DOS, so Emacs transparently +converts them to underscores @samp{_}; thus your default init file +@iftex +(@pxref{Init File,,,emacs, the Emacs Manual}) +@end iftex +@ifnottex +(@pxref{Init File}) +@end ifnottex +is called @file{_emacs} on MS-DOS. Excess characters before or after +the period are generally ignored by MS-DOS itself; thus, if you visit +the file @file{LongFileName.EvenLongerExtension}, you will silently +get @file{longfile.eve}, but Emacs will still display the long file +name on the mode line. Other than that, it's up to you to specify +file names which are valid under MS-DOS; the transparent conversion as +described above only works on file names built into Emacs. + +@cindex backup file names on MS-DOS + The above restrictions on the file names on MS-DOS make it almost +impossible to construct the name of a backup file +@iftex +(@pxref{Backup Names,,,emacs, the Emacs Manual}) +@end iftex +@ifnottex +(@pxref{Backup Names}) +@end ifnottex +without losing some of the original file name characters. For +example, the name of a backup file for @file{docs.txt} is +@file{docs.tx~} even if single backup is used. + +@cindex file names under Windows 95/NT +@cindex long file names in DOS box under Windows 95/NT + If you run Emacs as a DOS application under Windows 9X, Windows ME, or +Windows 2000/XP, you can turn on support for long file names. If you do +that, Emacs doesn't truncate file names or convert them to lower case; +instead, it uses the file names that you specify, verbatim. To enable +long file name support, set the environment variable @env{LFN} to +@samp{y} before starting Emacs. Unfortunately, Windows NT doesn't allow +DOS programs to access long file names, so Emacs built for MS-DOS will +only see their short 8+3 aliases. + +@cindex @env{HOME} directory under MS-DOS + MS-DOS has no notion of home directory, so Emacs on MS-DOS pretends +that the directory where it is installed is the value of the @env{HOME} +environment variable. That is, if your Emacs binary, +@file{emacs.exe}, is in the directory @file{c:/utils/emacs/bin}, then +Emacs acts as if @env{HOME} were set to @samp{c:/utils/emacs}. In +particular, that is where Emacs looks for the init file @file{_emacs}. +With this in mind, you can use @samp{~} in file names as an alias for +the home directory, as you would on GNU or Unix. You can also set +@env{HOME} variable in the environment before starting Emacs; its +value will then override the above default behavior. + + Emacs on MS-DOS handles the directory name @file{/dev} specially, +because of a feature in the emulator libraries of DJGPP that pretends +I/O devices have names in that directory. We recommend that you avoid +using an actual directory named @file{/dev} on any disk. + +@node MS-DOS Printing +@subsection Printing and MS-DOS + + Printing commands, such as @code{lpr-buffer} +@iftex +(@pxref{Printing,,,emacs, the Emacs Manual}) and @code{ps-print-buffer} +(@pxref{PostScript,,,emacs, the Emacs Manual}) +@end iftex +@ifnottex +(@pxref{Printing}) and @code{ps-print-buffer} (@pxref{PostScript}) +@end ifnottex +can work on MS-DOS by sending the output to one of the printer ports, +if a Posix-style @code{lpr} program is unavailable. The same Emacs +variables control printing on all systems, but in some cases they have +different default values on MS-DOS. + +@iftex +@xref{Windows Printing,,,emacs, the Emacs Manual}, +@end iftex +@ifnottex +@xref{Windows Printing}, +@end ifnottex +for details about setting up printing to a networked printer. + + Some printers expect DOS codepage encoding of non-@acronym{ASCII} text, even +though they are connected to a Windows machine which uses a different +encoding for the same locale. For example, in the Latin-1 locale, DOS +uses codepage 850 whereas Windows uses codepage 1252. @xref{MS-DOS and +MULE}. When you print to such printers from Windows, you can use the +@kbd{C-x RET c} (@code{universal-coding-system-argument}) command before +@kbd{M-x lpr-buffer}; Emacs will then convert the text to the DOS +codepage that you specify. For example, @kbd{C-x RET c cp850-dos RET +M-x lpr-region RET} will print the region while converting it to the +codepage 850 encoding. You may need to create the @code{cp@var{nnn}} +coding system with @kbd{M-x codepage-setup}. + +@vindex dos-printer +@vindex dos-ps-printer + For backwards compatibility, the value of @code{dos-printer} +(@code{dos-ps-printer}), if it has a value, overrides the value of +@code{printer-name} (@code{ps-printer-name}), on MS-DOS. + + +@node MS-DOS and MULE +@subsection International Support on MS-DOS +@cindex international support @r{(MS-DOS)} + + Emacs on MS-DOS supports the same international character sets as it +does on GNU, Unix and other platforms +@iftex +(@pxref{International,,,emacs, the Emacs Manual}), +@end iftex +@ifnottex +(@pxref{International}), +@end ifnottex +including coding systems for converting between the different +character sets. However, due to incompatibilities between +MS-DOS/MS-Windows and other systems, there are several DOS-specific +aspects of this support that you should be aware of. This section +describes these aspects. + + The description below is largely specific to the MS-DOS port of +Emacs, especially where it talks about practical implications for +Emacs users. For other operating systems, see the @file{code-pages.el} +package, which implements support for MS-DOS- and MS-Windows-specific +encodings for all platforms other than MS-DOS. + +@table @kbd +@item M-x dos-codepage-setup +Set up Emacs display and coding systems as appropriate for the current +DOS codepage. + +@item M-x codepage-setup +Create a coding system for a certain DOS codepage. +@end table + +@cindex codepage, MS-DOS +@cindex DOS codepages + MS-DOS is designed to support one character set of 256 characters at +any given time, but gives you a variety of character sets to choose +from. The alternative character sets are known as @dfn{DOS codepages}. +Each codepage includes all 128 @acronym{ASCII} characters, but the other 128 +characters (codes 128 through 255) vary from one codepage to another. +Each DOS codepage is identified by a 3-digit number, such as 850, 862, +etc. + + In contrast to X, which lets you use several fonts at the same time, +MS-DOS normally doesn't allow use of several codepages in a single +session. MS-DOS was designed to load a single codepage at system +startup, and require you to reboot in order to change +it@footnote{Normally, one particular codepage is burnt into the +display memory, while other codepages can be installed by modifying +system configuration files, such as @file{CONFIG.SYS}, and rebooting. +While there is third-party software that allows changing the codepage +without rebooting, we describe here how a stock MS-DOS system +behaves.}. Much the same limitation applies when you run DOS +executables on other systems such as MS-Windows. + +@cindex unibyte operation @r{(MS-DOS)} + If you invoke Emacs on MS-DOS with the @samp{--unibyte} option +@iftex +(@pxref{Initial Options,,,emacs, the Emacs Manual}), +@end iftex +@ifnottex +(@pxref{Initial Options}), +@end ifnottex +Emacs does not perform any conversion of non-@acronym{ASCII} +characters. Instead, it reads and writes any non-@acronym{ASCII} +characters verbatim, and sends their 8-bit codes to the display +verbatim. Thus, unibyte Emacs on MS-DOS supports the current +codepage, whatever it may be, but cannot even represent any other +characters. + +@vindex dos-codepage + For multibyte operation on MS-DOS, Emacs needs to know which +characters the chosen DOS codepage can display. So it queries the +system shortly after startup to get the chosen codepage number, and +stores the number in the variable @code{dos-codepage}. Some systems +return the default value 437 for the current codepage, even though the +actual codepage is different. (This typically happens when you use the +codepage built into the display hardware.) You can specify a different +codepage for Emacs to use by setting the variable @code{dos-codepage} in +your init file. + +@cindex language environment, automatic selection on @r{MS-DOS} + Multibyte Emacs supports only certain DOS codepages: those which can +display Far-Eastern scripts, like the Japanese codepage 932, and those +that encode a single ISO 8859 character set. + + The Far-Eastern codepages can directly display one of the MULE +character sets for these countries, so Emacs simply sets up to use the +appropriate terminal coding system that is supported by the codepage. +The special features described in the rest of this section mostly +pertain to codepages that encode ISO 8859 character sets. + + For the codepages which correspond to one of the ISO character sets, +Emacs knows the character set name based on the codepage number. Emacs +automatically creates a coding system to support reading and writing +files that use the current codepage, and uses this coding system by +default. The name of this coding system is @code{cp@var{nnn}}, where +@var{nnn} is the codepage number.@footnote{The standard Emacs coding +systems for ISO 8859 are not quite right for the purpose, because +typically the DOS codepage does not match the standard ISO character +codes. For example, the letter @samp{@,{c}} (@samp{c} with cedilla) has +code 231 in the standard Latin-1 character set, but the corresponding +DOS codepage 850 uses code 135 for this glyph.} + +@cindex mode line @r{(MS-DOS)} + All the @code{cp@var{nnn}} coding systems use the letter @samp{D} +(for ``DOS'') as their mode-line mnemonic. Since both the terminal +coding system and the default coding system for file I/O are set to +the proper @code{cp@var{nnn}} coding system at startup, it is normal +for the mode line on MS-DOS to begin with @samp{-DD\-}. +@iftex +@xref{Mode Line,,,emacs, the Emacs Manual}. +@end iftex +@ifnottex +@xref{Mode Line}. +@end ifnottex +Far-Eastern DOS terminals do not use the @code{cp@var{nnn}} coding +systems, and thus their initial mode line looks like the Emacs +default. + + Since the codepage number also indicates which script you are using, +Emacs automatically runs @code{set-language-environment} to select the +language environment for that script +@iftex +(@pxref{Language Environments,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Language Environments}). +@end ifnottex + + If a buffer contains a character belonging to some other ISO 8859 +character set, not the one that the chosen DOS codepage supports, Emacs +displays it using a sequence of @acronym{ASCII} characters. For example, if the +current codepage doesn't have a glyph for the letter @samp{@`o} (small +@samp{o} with a grave accent), it is displayed as @samp{@{`o@}}, where +the braces serve as a visual indication that this is a single character. +(This may look awkward for some non-Latin characters, such as those from +Greek or Hebrew alphabets, but it is still readable by a person who +knows the language.) Even though the character may occupy several +columns on the screen, it is really still just a single character, and +all Emacs commands treat it as one. + +@cindex IBM graphics characters (MS-DOS) +@cindex box-drawing characters (MS-DOS) +@cindex line-drawing characters (MS-DOS) + Not all characters in DOS codepages correspond to ISO 8859 +characters---some are used for other purposes, such as box-drawing +characters and other graphics. Emacs maps these characters to two +special character sets called @code{eight-bit-control} and +@code{eight-bit-graphic}, and displays them as their IBM glyphs. +However, you should be aware that other systems might display these +characters differently, so you should avoid them in text that might be +copied to a different operating system, or even to another DOS machine +that uses a different codepage. + +@vindex dos-unsupported-character-glyph + Emacs supports many other characters sets aside from ISO 8859, but it +cannot display them on MS-DOS. So if one of these multibyte characters +appears in a buffer, Emacs on MS-DOS displays them as specified by the +@code{dos-unsupported-character-glyph} variable; by default, this glyph +is an empty triangle. Use the @kbd{C-u C-x =} command to display the +actual code and character set of such characters. +@iftex +@xref{Position Info,,,emacs, the Emacs Manual}. +@end iftex +@ifnottex +@xref{Position Info}. +@end ifnottex + +@findex codepage-setup + By default, Emacs defines a coding system to support the current +codepage. To define a coding system for some other codepage (e.g., to +visit a file written on a DOS machine in another country), use the +@kbd{M-x codepage-setup} command. It prompts for the 3-digit code of +the codepage, with completion, then creates the coding system for the +specified codepage. You can then use the new coding system to read and +write files, but you must specify it explicitly for the file command +when you want to use it +@iftex +(@pxref{Text Coding,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Text Coding}). +@end ifnottex + + These coding systems are also useful for visiting a file encoded using +a DOS codepage, using Emacs running on some other operating system. + +@cindex MS-Windows codepages + MS-Windows provides its own codepages, which are different from the +DOS codepages for the same locale. For example, DOS codepage 850 +supports the same character set as Windows codepage 1252; DOS codepage +855 supports the same character set as Windows codepage 1251, etc. +The MS-Windows version of Emacs uses the current codepage for display +when invoked with the @samp{-nw} option. Support for codepages in the +Windows port of Emacs is part of the @file{code-pages.el} package. + +@node MS-DOS Processes +@subsection Subprocesses on MS-DOS + +@cindex compilation under MS-DOS +@cindex inferior processes under MS-DOS +@findex compile @r{(MS-DOS)} +@findex grep @r{(MS-DOS)} + Because MS-DOS is a single-process ``operating system,'' +asynchronous subprocesses are not available. In particular, Shell +mode and its variants do not work. Most Emacs features that use +asynchronous subprocesses also don't work on MS-DOS, including +Shell mode and GUD. When in doubt, try and see; commands that +don't work output an error message saying that asynchronous processes +aren't supported. + + Compilation under Emacs with @kbd{M-x compile}, searching files with +@kbd{M-x grep} and displaying differences between files with @kbd{M-x +diff} do work, by running the inferior processes synchronously. This +means you cannot do any more editing until the inferior process +finishes. + + Spell checking also works, by means of special support for synchronous +invocation of the @code{ispell} program. This is slower than the +asynchronous invocation on other platforms + + Instead of the Shell mode, which doesn't work on MS-DOS, you can use +the @kbd{M-x eshell} command. This invokes the Eshell package that +implements a Posix-like shell entirely in Emacs Lisp. + + By contrast, Emacs compiled as a native Windows application +@strong{does} support asynchronous subprocesses. +@iftex +@xref{Windows Processes,,,emacs, the Emacs Manual}. +@end iftex +@ifnottex +@xref{Windows Processes}. +@end ifnottex + +@cindex printing under MS-DOS + Printing commands, such as @code{lpr-buffer} +@iftex +(@pxref{Printing,,,emacs, the Emacs Manual}) and +@code{ps-print-buffer} (@pxref{PostScript,,,emacs, the Emacs Manual}), +work in MS-DOS by sending the output to one of the printer ports. +@xref{MS-DOS Printing,,,emacs, the Emacs Manual}. +@end iftex +@ifnottex +(@pxref{Printing}) and @code{ps-print-buffer} (@pxref{PostScript}), +work in MS-DOS by sending the output to one of the printer ports. +@xref{MS-DOS Printing}. +@end ifnottex + + When you run a subprocess synchronously on MS-DOS, make sure the +program terminates and does not try to read keyboard input. If the +program does not terminate on its own, you will be unable to terminate +it, because MS-DOS provides no general way to terminate a process. +Pressing @kbd{C-c} or @kbd{C-@key{BREAK}} might sometimes help in these +cases. + + Accessing files on other machines is not supported on MS-DOS. Other +network-oriented commands such as sending mail, Web browsing, remote +login, etc., don't work either, unless network access is built into +MS-DOS with some network redirector. + +@cindex directory listing on MS-DOS +@vindex dired-listing-switches @r{(MS-DOS)} + Dired on MS-DOS uses the @code{ls-lisp} package where other +platforms use the system @code{ls} command. Therefore, Dired on +MS-DOS supports only some of the possible options you can mention in +the @code{dired-listing-switches} variable. The options that work are +@samp{-A}, @samp{-a}, @samp{-c}, @samp{-i}, @samp{-r}, @samp{-S}, +@samp{-s}, @samp{-t}, and @samp{-u}. + +@ignore + arch-tag: 868d50ff-07f8-4a13-a807-dab6f1cdb431 +@end ignore diff --git a/doc/emacs/msdog.texi b/doc/emacs/msdog.texi new file mode 100644 index 00000000000..0ed15229b7c --- /dev/null +++ b/doc/emacs/msdog.texi @@ -0,0 +1,766 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Microsoft Windows, Manifesto, Mac OS, Top +@appendix Emacs and Microsoft Windows/MS-DOS +@cindex Microsoft Windows +@cindex MS-Windows, Emacs peculiarities + + This section describes peculiarities of using Emacs on Microsoft +Windows. Some of these peculiarities are also relevant to Microsoft's +older MS-DOS ``operating system'' (also known as ``MS-DOG''). +However, Emacs features that are relevant @emph{only} to MS-DOS are +described in a separate +@iftex +manual (@pxref{MS-DOS,,, emacs-xtra, Specialized Emacs Features}). +@end iftex +@ifnottex +section (@pxref{MS-DOS}). +@end ifnottex + + + The behavior of Emacs on MS-Windows is reasonably similar to what is +documented in the rest of the manual, including support for long file +names, multiple frames, scroll bars, mouse menus, and subprocesses. +However, a few special considerations apply, and they are described +here. + +@menu +* Text and Binary:: Text files use CRLF to terminate lines. +* Windows Files:: File-name conventions on Windows. +* ls in Lisp:: Emulation of @code{ls} for Dired. +* Windows HOME:: Where Emacs looks for your @file{.emacs}. +* Windows Keyboard:: Windows-specific keyboard features. +* Windows Mouse:: Windows-specific mouse features. +* Windows Processes:: Running subprocesses on Windows. +* Windows Printing:: How to specify the printer on MS-Windows. +* Windows Misc:: Miscellaneous Windows features. +@ifnottex +* MS-DOS:: Using Emacs on MS-DOS (otherwise known as @dfn{MS-DOG}). +@end ifnottex +@end menu + +@node Text and Binary +@section Text Files and Binary Files +@cindex text and binary files on MS-DOS/MS-Windows + + GNU Emacs uses newline characters to separate text lines. This is the +convention used on GNU, Unix, and other Posix-compliant systems. + +@cindex end-of-line conversion on MS-DOS/MS-Windows + By contrast, MS-DOS and MS-Windows normally use carriage-return linefeed, +a two-character sequence, to separate text lines. (Linefeed is the same +character as newline.) Therefore, convenient editing of typical files +with Emacs requires conversion of these end-of-line (EOL) sequences. +And that is what Emacs normally does: it converts carriage-return +linefeed into newline when reading files, and converts newline into +carriage-return linefeed when writing files. The same mechanism that +handles conversion of international character codes does this conversion +also (@pxref{Coding Systems}). + +@cindex cursor location, on MS-DOS +@cindex point location, on MS-DOS + One consequence of this special format-conversion of most files is +that character positions as reported by Emacs (@pxref{Position Info}) do +not agree with the file size information known to the operating system. + + In addition, if Emacs recognizes from a file's contents that it uses +newline rather than carriage-return linefeed as its line separator, it +does not perform EOL conversion when reading or writing that file. +Thus, you can read and edit files from GNU and Unix systems on MS-DOS +with no special effort, and they will retain their Unix-style +end-of-line convention after you edit them. + + The mode line indicates whether end-of-line translation was used for +the current buffer. If MS-DOS end-of-line translation is in use for the +buffer, the MS-Windows build of Emacs displays a backslash @samp{\} after +the coding system mnemonic near the beginning of the mode line +(@pxref{Mode Line}). If no EOL translation was performed, the string +@samp{(Unix)} is displayed instead of the backslash, to alert you that the +file's EOL format is not the usual carriage-return linefeed. + +@cindex DOS-to-Unix conversion of files + To visit a file and specify whether it uses DOS-style or Unix-style +end-of-line, specify a coding system (@pxref{Text Coding}). For +example, @kbd{C-x @key{RET} c unix @key{RET} C-x C-f foobar.txt} +visits the file @file{foobar.txt} without converting the EOLs; if some +line ends with a carriage-return linefeed pair, Emacs will display +@samp{^M} at the end of that line. Similarly, you can direct Emacs to +save a buffer in a specified EOL format with the @kbd{C-x @key{RET} f} +command. For example, to save a buffer with Unix EOL format, type +@kbd{C-x @key{RET} f unix @key{RET} C-x C-s}. If you visit a file +with DOS EOL conversion, then save it with Unix EOL format, that +effectively converts the file to Unix EOL style, like @code{dos2unix}. + +@cindex untranslated file system +@findex add-untranslated-filesystem + When you use NFS, Samba, or some other similar method to access file +systems that reside on computers using GNU or Unix systems, Emacs +should not perform end-of-line translation on any files in these file +systems---not even when you create a new file. To request this, +designate these file systems as @dfn{untranslated} file systems by +calling the function @code{add-untranslated-filesystem}. It takes one +argument: the file system name, including a drive letter and +optionally a directory. For example, + +@example +(add-untranslated-filesystem "Z:") +@end example + +@noindent +designates drive Z as an untranslated file system, and + +@example +(add-untranslated-filesystem "Z:\\foo") +@end example + +@noindent +designates directory @file{\foo} on drive Z as an untranslated file +system. + + Most often you would use @code{add-untranslated-filesystem} in your +@file{.emacs} file, or in @file{site-start.el} so that all the users at +your site get the benefit of it. + +@findex remove-untranslated-filesystem + To countermand the effect of @code{add-untranslated-filesystem}, use +the function @code{remove-untranslated-filesystem}. This function takes +one argument, which should be a string just like the one that was used +previously with @code{add-untranslated-filesystem}. + + Designating a file system as untranslated does not affect character +set conversion, only end-of-line conversion. Essentially, it directs +Emacs to create new files with the Unix-style convention of using +newline at the end of a line. @xref{Coding Systems}. + +@vindex file-name-buffer-file-type-alist +@cindex binary files, on MS-DOS/MS-Windows + Some kinds of files should not be converted at all, because their +contents are not really text. Therefore, Emacs on MS-Windows distinguishes +certain files as @dfn{binary files}. (This distinction is not part of +MS-Windows; it is made by Emacs only.) Binary files include executable +programs, compressed archives, etc. Emacs uses the file name to decide +whether to treat a file as binary: the variable +@code{file-name-buffer-file-type-alist} defines the file-name patterns +that indicate binary files. If a file name matches one of the patterns +for binary files (those whose associations are of the type +@code{(@var{pattern} . t)}, Emacs reads and writes that file using the +@code{no-conversion} coding system (@pxref{Coding Systems}) which turns +off @emph{all} coding-system conversions, not only the EOL conversion. +@code{file-name-buffer-file-type-alist} also includes file-name patterns +for files which are known to be Windows-style text files with +carriage-return linefeed EOL format, such as @file{CONFIG.SYS}; Emacs +always writes those files with Windows-style EOLs. + + If a file which belongs to an untranslated file system matches one of +the file-name patterns in @code{file-name-buffer-file-type-alist}, the +EOL conversion is determined by @code{file-name-buffer-file-type-alist}. + +@node Windows Files +@section File Names on MS-Windows +@cindex file names on MS-Windows + + MS-Windows and MS-DOS normally use a backslash, @samp{\}, to +separate name units within a file name, instead of the slash used on +other systems. Emacs on MS-DOS/MS-Windows permits use of either slash or +backslash, and also knows about drive letters in file names. + +@cindex file-name completion, on MS-Windows + On MS-DOS/MS-Windows, file names are case-insensitive, so Emacs by +default ignores letter-case in file names during completion. + +@vindex w32-get-true-file-attributes + If the variable @code{w32-get-true-file-attributes} is +non-@code{nil} (the default), Emacs tries to determine the accurate +link counts for files. This option is only useful on NTFS volumes, +and it considerably slows down Dired and other features, so use it +only on fast machines. + +@node ls in Lisp +@section Emulation of @code{ls} on MS-Windows +@cindex Dired, and MS-Windows/MS-DOS +@cindex @code{ls} emulation + + Dired normally uses the external program @code{ls} (or its close +work-alike) to produce the directory listing displayed in Dired +buffers (@pxref{Dired}). However, MS-Windows and MS-DOS systems don't +come with such a program, although several ports of @sc{gnu} @code{ls} +are available. Therefore, Emacs on those systems @emph{emulates} +@code{ls} in Lisp, by using the @file{ls-lisp.el} package. While +@file{ls-lisp.el} provides a reasonably full emulation of @code{ls}, +there are some options and features peculiar to that emulation; +@iftex +for more details, see the documentation of the variables whose names +begin with @code{ls-lisp}. +@end iftex +@ifnottex +they are described in this section. + + The @code{ls} emulation supports many of the @code{ls} switches, but +it doesn't support all of them. Here's the list of the switches it +does support: @option{-A}, @option{-a}, @option{-B}, @option{-C}, +@option{-c}, @option{-i}, @option{-G}, @option{-g}, @option{-R}, +@option{-r}, @option{-S}, @option{-s}, @option{-t}, @option{-U}, +@option{-u}, and @option{-X}. The @option{-F} switch is partially +supported (it appends the character that classifies the file, but does +not prevent symlink following). + +@vindex ls-lisp-use-insert-directory-program + On MS-Windows and MS-DOS, @file{ls-lisp.el} is preloaded when Emacs +is built, so the Lisp emulation of @code{ls} is always used on those +platforms. If you have a ported @code{ls}, setting +@code{ls-lisp-use-insert-directory-program} to a non-@code{nil} value +will revert to using an external program named by the variable +@code{insert-directory-program}. + +@vindex ls-lisp-ignore-case + By default, @file{ls-lisp.el} uses a case-sensitive sort order for +the directory listing it produces; this is so the listing looks the +same as on other platforms. If you wish that the files be sorted in +case-insensitive order, set the variable @code{ls-lisp-ignore-case} to +a non-@code{nil} value. + +@vindex ls-lisp-dirs-first + By default, files and subdirectories are sorted together, to emulate +the behavior of @code{ls}. However, native MS-Windows/MS-DOS file +managers list the directories before the files; if you want that +behavior, customize the option @code{ls-lisp-dirs-first} to a +non-@code{nil} value. + +@vindex ls-lisp-verbosity + The variable @code{ls-lisp-verbosity} controls the file attributes +that @file{ls-lisp.el} displays. The value should be a list that +contains one or more of the symbols @code{links}, @code{uid}, and +@code{gid}. @code{links} means display the count of different file +names that are associated with (a.k.a.@: @dfn{links to}) the file's +data; this is only useful on NTFS volumes. @code{uid} means display +the numerical identifier of the user who owns the file. @code{gid} +means display the numerical identifier of the file owner's group. The +default value is @code{(links uid gid)} i.e.@: all the 3 optional +attributes are displayed. + +@vindex ls-lisp-emulation + The variable @code{ls-lisp-emulation} controls the flavour of the +@code{ls} emulation by setting the defaults for the 3 options +described above: @code{ls-lisp-ignore-case}, +@code{ls-lisp-dirs-first}, and @code{ls-lisp-verbosity}. The value of +this option can be one of the following symbols: + +@table @code +@item GNU +@itemx nil +Emulate @sc{gnu} systems; this is the default. This sets +@code{ls-lisp-ignore-case} and @code{ls-lisp-dirs-first} to +@code{nil}, and @code{ls-lisp-verbosity} to @code{(links uid gid)}. +@item UNIX +Emulate Unix systems. Like @code{GNU}, but sets +@code{ls-lisp-verbosity} to @code{(links uid)}. +@item MacOS +Emulate MacOS. Sets @code{ls-lisp-ignore-case} to @code{t}, and +@code{ls-lisp-dirs-first} and @code{ls-lisp-verbosity} to @code{nil}. +@item MS-Windows +Emulate MS-Windows. Sets @code{ls-lisp-ignore-case} and +@code{ls-lisp-dirs-first} to @code{t}, and @code{ls-lisp-verbosity} to +@code{(links)} on Windows NT/2K/XP/2K3 and to @code{nil} on Windows 9X. +Note that the default emulation is @emph{not} @code{MS-Windows}, even +on Windows, since many users of Emacs on those platforms prefer the +@sc{gnu} defaults. +@end table + +@noindent +Any other value of @code{ls-lisp-emulation} means the same as +@code{GNU}. Note that this option needs to be set @emph{before} +@file{ls-lisp.el} is loaded, which means that on MS-Windows and MS-DOS +you will have to set the value from your @file{.emacs} file and then +restart Emacs, since @file{ls-lisp.el} is preloaded. + +@vindex ls-lisp-support-shell-wildcards + The variable @code{ls-lisp-support-shell-wildcards} controls how +file-name patterns are supported: if it is non-@code{nil} (the +default), they are treated as shell-style wildcards; otherwise they +are treated as Emacs regular expressions. + +@vindex ls-lisp-format-time-list + The variable @code{ls-lisp-format-time-list} defines how to format +the date and time of files. @emph{The value of this variable is +ignored}, unless Emacs cannot determine the current locale. (However, +if the value of @code{ls-lisp-use-localized-time-format} is +non-@code{nil}, Emacs obeys @code{ls-lisp-format-time-list} even if +the current locale is available; see below.) + +The value of @code{ls-lisp-format-time-list} is a list of 2 strings. +The first string is used if the file was modified within the current +year, while the second string is used for older files. In each of +these two strings you can use @samp{%}-sequences to substitute parts +of the time. For example: +@lisp +("%b %e %H:%M" "%b %e %Y") +@end lisp + +@noindent +Note that the strings substituted for these @samp{%}-sequences depend +on the current locale. @xref{Time Parsing,,, elisp, The Emacs Lisp +Reference Manual}, for more about format time specs. + +@vindex ls-lisp-use-localized-time-format + Normally, Emacs formats the file time stamps in either traditional +or ISO-style time format. However, if the value of the variable +@code{ls-lisp-use-localized-time-format} is non-@code{nil}, Emacs +formats file time stamps according to what +@code{ls-lisp-format-time-list} specifies. The @samp{%}-sequences in +@code{ls-lisp-format-time-list} produce locale-dependent month and day +names, which might cause misalignment of columns in Dired display. +@end ifnottex + +@node Windows HOME +@section HOME Directory on MS-Windows +@cindex @code{HOME} directory on MS-Windows + + The Windows equivalent of the @code{HOME} directory is the +@dfn{user-specific application data directory}. The actual location +depends on your Windows version and system configuration; typical values +are @file{C:\Documents and Settings\@var{username}\Application Data} on +Windows 2K/XP and later, and either @file{C:\WINDOWS\Application Data} +or @file{C:\WINDOWS\Profiles\@var{username}\Application Data} on the +older Windows 9X/ME systems. + +@cindex init file @file{.emacs} on MS-Windows + The home directory is where your init file @file{.emacs} is stored. +When Emacs starts, it first checks whether the environment variable +@env{HOME} is set. If it is, it looks for the init file in the +directory pointed by @env{HOME}. If @env{HOME} is not defined, Emacs +checks for an existing @file{.emacs} file in @file{C:\}, the root +directory of drive @file{C:}@footnote{ +The check in @file{C:\} is in preference to the application data +directory for compatibility with older versions of Emacs, which didn't +check the application data directory. +}. If there's no such file in @file{C:\}, Emacs next uses the Windows +system calls to find out the exact location of your application data +directory. If that fails as well, Emacs falls back to @file{C:\}. + + Whatever the final place is, Emacs sets the value of the @env{HOME} +environment variable to point to it, and it will use that location for +other files and directories it normally creates in the user's home +directory. + + You can always find out where Emacs thinks is your home directory's +location by typing @kbd{C-x d ~/ @key{RET}}. This should present the +list of files in the home directory, and show its full name on the +first line. Likewise, to visit your init file, type @kbd{C-x C-f +~/.emacs @key{RET}}. + +@cindex @file{_emacs} init file, MS-Windows + Because MS-DOS does not allow file names with leading dots, and +because older Windows systems made it hard to create files with such +names, the Windows port of Emacs supports an alternative name +@file{_emacs} as a fallback, if such a file exists in the home +directory, whereas @file{.emacs} does not. + +@node Windows Keyboard +@section Keyboard Usage on MS-Windows +@cindex keyboard, MS-Windows + + This section describes the Windows-specific features related to +keyboard input in Emacs. + +@cindex MS-Windows keyboard shortcuts + Many key combinations (known as ``keyboard shortcuts'') that have +conventional uses in MS-Windows programs conflict with traditional +Emacs key bindings. (These Emacs key bindings were established years +before Microsoft was founded.) Examples of conflicts include +@kbd{C-c}, @kbd{C-x}, @kbd{C-z}, @kbd{C-a}, and @kbd{W-@key{SPC}}. +You can redefine some of them with meanings more like the MS-Windows +meanings by enabling CUA Mode (@pxref{CUA Bindings}). + +@kindex F10 @r{(MS-Windows)} +@cindex menu bar access using keyboard @r{(MS-Windows)} + The @key{F10} key on Windows activates the menu bar in a way that +makes it possible to use the menus without a mouse. In this mode, the +arrow keys traverse the menus, @key{RET} selects a highlighted menu +item, and @key{ESC} closes the menu. + +@iftex +@inforef{Windows Keyboard, , emacs}, for information about additional +Windows-specific variables in this category. +@end iftex +@ifnottex +@vindex w32-alt-is-meta +@cindex @code{Alt} key (MS-Windows) + By default, the key labeled @key{Alt} is mapped as the @key{META} +key. If you wish it to produce the @code{Alt} modifier instead, set +the variable @code{w32-alt-is-meta} to a @code{nil} value. + +@vindex w32-capslock-is-shiftlock + By default, the @key{CapsLock} key only affects normal character +keys (it converts lower-case characters to their upper-case +variants). However, if you set the variable +@code{w32-capslock-is-shiftlock} to a non-@code{nil} value, the +@key{CapsLock} key will affect non-character keys as well, as if you +pressed the @key{Shift} key while typing the non-character key. + +@vindex w32-enable-caps-lock + If the variable @code{w32-enable-caps-lock} is set to a @code{nil} +value, the @key{CapsLock} key produces the symbol @code{capslock} +instead of the shifted version of they keys. The default value is +@code{t}. + +@vindex w32-enable-num-lock +@cindex keypad keys (MS-Windows) + Similarly, if @code{w32-enable-num-lock} is @code{nil}, the +@key{NumLock} key will produce the symbol @code{kp-numlock}. The +default is @code{t}, which causes @key{NumLock} to work as expected: +toggle the meaning of the keys on the numeric keypad. +@end ifnottex + +@vindex w32-apps-modifier + The variable @code{w32-apps-modifier} controls the effect of the +@key{Apps} key (usually located between the right @key{Alt} and the +right @key{Ctrl} keys). Its value can be one of the symbols +@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control}, +or @code{shift} for the respective modifier, or @code{nil} to appear +as the key @code{apps}. The default is @code{nil}. + +@vindex w32-lwindow-modifier +@vindex w32-rwindow-modifier +@vindex w32-scroll-lock-modifier + The variable @code{w32-lwindow-modifier} determines the effect of +the left Windows key (usually labeled with @key{start} and the Windows +logo). If its value is @code{nil} (the default), the key will produce +the symbol @code{lwindow}. Setting it to one of the symbols +@code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control}, +or @code{shift} will produce the respective modifier. A similar +variable @code{w32-rwindow-modifier} controls the effect of the right +Windows key, and @code{w32-scroll-lock-modifier} does the same for the +@key{ScrLock} key. If these variables are set to @code{nil}, the +right Windows key produces the symbol @code{rwindow} and @key{ScrLock} +produces the symbol @code{scroll}. + +@vindex w32-pass-alt-to-system +@cindex Windows system menu +@cindex @code{Alt} key invokes menu (Windows) + Emacs compiled as a native Windows application normally turns off +the Windows feature that tapping the @key{ALT} key invokes the Windows +menu. The reason is that the @key{ALT} serves as @key{META} in Emacs. +When using Emacs, users often press the @key{META} key temporarily and +then change their minds; if this has the effect of bringing up the +Windows menu, it alters the meaning of subsequent commands. Many +users find this frustrating. + + You can re-enable Windows' default handling of tapping the @key{ALT} +key by setting @code{w32-pass-alt-to-system} to a non-@code{nil} +value. + +@ifnottex +@vindex w32-pass-lwindow-to-system +@vindex w32-pass-rwindow-to-system + The variables @code{w32-pass-lwindow-to-system} and +@code{w32-pass-rwindow-to-system} determine whether the respective +keys are passed to Windows or swallowed by Emacs. If the value is +@code{nil}, the respective key is silently swallowed by Emacs, +otherwise it is passed to Windows. The default is @code{t} for both +of these variables. Passing each of these keys to Windows produces +its normal effect: for example, @kbd{@key{Lwindow}} opens the +@code{Start} menu, etc.@footnote{ +Some combinations of the ``Windows'' keys with other keys are caught +by Windows at low level in a way that Emacs currently cannot prevent. +For example, @kbd{@key{Lwindow} r} always pops up the Windows +@samp{Run} dialog. Customizing the value of +@code{w32-phantom-key-code} might help in some cases, though.} + +@vindex w32-recognize-altgr +@kindex AltGr @r{(MS-Windows)} +@cindex AltGr key (MS-Windows) + The variable @code{w32-recognize-altgr} controls whether the +@key{AltGr} key (if it exists on your keyboard), or its equivalent, +the combination of the right @key{Alt} and left @key{Ctrl} keys +pressed together, is recognized as the @key{AltGr} key. The default +is @code{t}, which means these keys produce @code{AltGr}; setting it +to @code{nil} causes @key{AltGr} or the equivalent key combination to +be interpreted as the combination of @key{CTRL} and @key{META} +modifiers. +@end ifnottex + +@node Windows Mouse +@section Mouse Usage on MS-Windows +@cindex mouse, and MS-Windows + + This section describes the Windows-specific variables related to +mouse. + +@vindex w32-mouse-button-tolerance +@cindex simulation of middle mouse button + The variable @code{w32-mouse-button-tolerance} specifies the +time interval, in milliseconds, for faking middle mouse button press +on 2-button mice. If both mouse buttons are depressed within this +time interval, Emacs generates a middle mouse button click event +instead of a double click on one of the buttons. + +@vindex w32-pass-extra-mouse-buttons-to-system + If the variable @code{w32-pass-extra-mouse-buttons-to-system} is +non-@code{nil}, Emacs passes the fourth and fifth mouse buttons to +Windows. + +@vindex w32-swap-mouse-buttons + The variable @code{w32-swap-mouse-buttons} controls which of the 3 +mouse buttons generates the @kbd{mouse-2} events. When it is +@code{nil} (the default), the middle button generates @kbd{mouse-2} +and the right button generates @kbd{mouse-3} events. If this variable +is non-@code{nil}, the roles of these two buttons are reversed. + +@node Windows Processes +@section Subprocesses on Windows 9X/ME and Windows NT/2K/XP +@cindex subprocesses on MS-Windows + +@cindex DOS applications, running from Emacs + Emacs compiled as a native Windows application (as opposed to the DOS +version) includes full support for asynchronous subprocesses. +In the Windows version, synchronous and asynchronous subprocesses work +fine on both +Windows 9X/ME and Windows NT/2K/XP as long as you run only 32-bit Windows +applications. However, when you run a DOS application in a subprocess, +you may encounter problems or be unable to run the application at all; +and if you run two DOS applications at the same time in two +subprocesses, you may have to reboot your system. + +Since the standard command interpreter (and most command line utilities) +on Windows 9X are DOS applications, these problems are significant when +using that system. But there's nothing we can do about them; only +Microsoft can fix them. + +If you run just one DOS application subprocess, the subprocess should +work as expected as long as it is ``well-behaved'' and does not perform +direct screen access or other unusual actions. If you have a CPU +monitor application, your machine will appear to be 100% busy even when +the DOS application is idle, but this is only an artifact of the way CPU +monitors measure processor load. + +You must terminate the DOS application before you start any other DOS +application in a different subprocess. Emacs is unable to interrupt or +terminate a DOS subprocess. The only way you can terminate such a +subprocess is by giving it a command that tells its program to exit. + +If you attempt to run two DOS applications at the same time in separate +subprocesses, the second one that is started will be suspended until the +first one finishes, even if either or both of them are asynchronous. + +@cindex kill DOS application +If you can go to the first subprocess, and tell it to exit, the second +subprocess should continue normally. However, if the second subprocess +is synchronous, Emacs itself will be hung until the first subprocess +finishes. If it will not finish without user input, then you have no +choice but to reboot if you are running on Windows 9X. If you are +running on Windows NT/2K/XP, you can use a process viewer application to kill +the appropriate instance of NTVDM instead (this will terminate both DOS +subprocesses). + +If you have to reboot Windows 9X in this situation, do not use the +@code{Shutdown} command on the @code{Start} menu; that usually hangs the +system. Instead, type @kbd{CTL-ALT-@key{DEL}} and then choose +@code{Shutdown}. That usually works, although it may take a few minutes +to do its job. + +@vindex w32-quote-process-args + The variable @code{w32-quote-process-args} controls how Emacs quotes +the process arguments. Non-@code{nil} means quote with the @code{"} +character. If the value is a character, use that character to escape +any quote characters that appear; otherwise chose a suitable escape +character based on the type of the program. + +@ifnottex +@findex w32-shell-execute + The function @code{w32-shell-execute} can be useful for writing +customized commands that run MS-Windows applications registered to +handle a certain standard Windows operation for a specific type of +document or file. This function is a wrapper around the Windows +@code{ShellExecute} API. See the MS-Windows API documentation for +more details. +@end ifnottex + +@node Windows Printing +@section Printing and MS-Windows + + Printing commands, such as @code{lpr-buffer} (@pxref{Printing}) and +@code{ps-print-buffer} (@pxref{PostScript}) work in MS-DOS and +MS-Windows by sending the output to one of the printer ports, if a +Posix-style @code{lpr} program is unavailable. The same Emacs +variables control printing on all systems, but in some cases they have +different default values on MS-DOS and MS-Windows. + + Emacs on Windows automatically determines your default printer and +sets the variable @var{printer-name} to that printer's name. But in +some rare cases this can fail, or you may wish to use a different +printer from within Emacs. The rest of this section explains how to +tell Emacs which printer to use. + +@vindex printer-name@r{, (MS-DOS/MW-Windows)} + If you want to use your local printer, then set the Lisp variable +@code{lpr-command} to @code{""} (its default value on Windows) and +@code{printer-name} to the name of the printer port---for example, +@code{"PRN"}, the usual local printer port or @code{"LPT2"}, or +@code{"COM1"} for a serial printer. You can also set +@code{printer-name} to a file name, in which case ``printed'' output +is actually appended to that file. If you set @code{printer-name} to +@code{"NUL"}, printed output is silently discarded (sent to the system +null device). + + You can also use a printer shared by another machine by setting +@code{printer-name} to the UNC share name for that printer---for +example, @code{"//joes_pc/hp4si"}. (It doesn't matter whether you use +forward slashes or backslashes here.) To find out the names of shared +printers, run the command @samp{net view} from the command prompt to +obtain a list of servers, and @samp{net view @var{server-name}} to see +the names of printers (and directories) shared by that server. +Alternatively, click the @samp{Network Neighborhood} icon on your +desktop, and look for machines which share their printers via the +network. + +@cindex @samp{net use}, and printing on MS-Windows +@cindex networked printers (MS-Windows) + If the printer doesn't appear in the output of @samp{net view}, or +if setting @code{printer-name} to the UNC share name doesn't produce a +hardcopy on that printer, you can use the @samp{net use} command to +connect a local print port such as @code{"LPT2"} to the networked +printer. For example, typing @kbd{net use LPT2: \\joes_pc\hp4si}@footnote{ +Note that the @samp{net use} command requires the UNC share name to be +typed with the Windows-style backslashes, while the value of +@code{printer-name} can be set with either forward- or backslashes.} +causes Windows to @dfn{capture} the @code{LPT2} port and redirect the +printed material to the printer connected to the machine @code{joes_pc}. +After this command, setting @code{printer-name} to @code{"LPT2"} +should produce the hardcopy on the networked printer. + + With some varieties of Windows network software, you can instruct +Windows to capture a specific printer port such as @code{"LPT2"}, and +redirect it to a networked printer via the @w{@code{Control +Panel->Printers}} applet instead of @samp{net use}. + + If you set @code{printer-name} to a file name, it's best to use an +absolute file name. Emacs changes the working directory according to +the default directory of the current buffer, so if the file name in +@code{printer-name} is relative, you will end up with several such +files, each one in the directory of the buffer from which the printing +was done. + + If the value of @code{printer-name} is correct, but printing does +not produce the hardcopy on your printer, it is possible that your +printer does not support printing plain text (some cheap printers omit +this functionality). In that case, try the PostScript print commands, +described below. + +@findex print-buffer @r{(MS-DOS)} +@findex print-region @r{(MS-DOS)} +@vindex lpr-headers-switches @r{(MS-DOS)} + The commands @code{print-buffer} and @code{print-region} call the +@code{pr} program, or use special switches to the @code{lpr} program, to +produce headers on each printed page. MS-DOS and MS-Windows don't +normally have these programs, so by default, the variable +@code{lpr-headers-switches} is set so that the requests to print page +headers are silently ignored. Thus, @code{print-buffer} and +@code{print-region} produce the same output as @code{lpr-buffer} and +@code{lpr-region}, respectively. If you do have a suitable @code{pr} +program (for example, from GNU Coreutils), set +@code{lpr-headers-switches} to @code{nil}; Emacs will then call +@code{pr} to produce the page headers, and print the resulting output as +specified by @code{printer-name}. + +@vindex print-region-function @r{(MS-DOS)} +@cindex lpr usage under MS-DOS +@vindex lpr-command @r{(MS-DOS)} +@vindex lpr-switches @r{(MS-DOS)} + Finally, if you do have an @code{lpr} work-alike, you can set the +variable @code{lpr-command} to @code{"lpr"}. Then Emacs will use +@code{lpr} for printing, as on other systems. (If the name of the +program isn't @code{lpr}, set @code{lpr-command} to specify where to +find it.) The variable @code{lpr-switches} has its standard meaning +when @code{lpr-command} is not @code{""}. If the variable +@code{printer-name} has a string value, it is used as the value for the +@code{-P} option to @code{lpr}, as on Unix. + +@findex ps-print-buffer @r{(MS-DOS)} +@findex ps-spool-buffer @r{(MS-DOS)} +@vindex ps-printer-name @r{(MS-DOS)} +@vindex ps-lpr-command @r{(MS-DOS)} +@vindex ps-lpr-switches @r{(MS-DOS)} + A parallel set of variables, @code{ps-lpr-command}, +@code{ps-lpr-switches}, and @code{ps-printer-name} (@pxref{PostScript +Variables}), defines how PostScript files should be printed. These +variables are used in the same way as the corresponding variables +described above for non-PostScript printing. Thus, the value of +@code{ps-printer-name} is used as the name of the device (or file) to +which PostScript output is sent, just as @code{printer-name} is used +for non-PostScript printing. (There are two distinct sets of +variables in case you have two printers attached to two different +ports, and only one of them is a PostScript printer.) + + The default value of the variable @code{ps-lpr-command} is @code{""}, +which causes PostScript output to be sent to the printer port specified +by @code{ps-printer-name}, but @code{ps-lpr-command} can also be set to +the name of a program which will accept PostScript files. Thus, if you +have a non-PostScript printer, you can set this variable to the name of +a PostScript interpreter program (such as Ghostscript). Any switches +that need to be passed to the interpreter program are specified using +@code{ps-lpr-switches}. (If the value of @code{ps-printer-name} is a +string, it will be added to the list of switches as the value for the +@code{-P} option. This is probably only useful if you are using +@code{lpr}, so when using an interpreter typically you would set +@code{ps-printer-name} to something other than a string so it is +ignored.) + + For example, to use Ghostscript for printing on the system's default +printer, put this in your @file{.emacs} file: + +@example +(setq ps-printer-name t) +(setq ps-lpr-command "D:/gs6.01/bin/gswin32c.exe") +(setq ps-lpr-switches '("-q" "-dNOPAUSE" "-dBATCH" + "-sDEVICE=mswinpr2" + "-sPAPERSIZE=a4")) +@end example + +@noindent +(This assumes that Ghostscript is installed in the +@file{D:/gs6.01} directory.) + +@node Windows Misc +@section Miscellaneous Windows-specific features + + This section describes miscellaneous Windows-specific features. + +@vindex w32-use-visible-system-caret +@cindex screen reader software, MS-Windows + The variable @code{w32-use-visible-system-caret} is a flag that +determines whether to make the system caret visible. The default is +@code{nil}, which means Emacs draws its own cursor to indicate the +position of point. A non-@code{nil} value means Emacs will indicate +point location by the system caret; this facilitates use of screen +reader software. When this variable is non-@code{nil}, other +variables affecting the cursor display have no effect. + +@iftex +@inforef{Windows Misc, , emacs}, for information about additional +Windows-specific variables in this category. +@end iftex + +@ifnottex +@vindex w32-grab-focus-on-raise +@cindex frame focus policy, MS-Windows + The variable @code{w32-grab-focus-on-raise}, if set to a +non-@code{nil} value causes a frame to grab focus when it is raised. +The default is @code{t}, which fits well with the Windows default +click-to-focus policy. + +@vindex w32-list-proportional-fonts + The variable @code{w32-list-proportional-fonts} controls whether +proportional fonts are included in the font selection dialog. If its +value is non-@code{nil}, these fonts will be included. The default is +@code{nil}. +@end ifnottex + +@ifnottex +@include msdog-xtra.texi +@end ifnottex + +@ignore + arch-tag: f39d2590-5dcc-4318-88d9-0eb73ca10fa2 +@end ignore diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi new file mode 100644 index 00000000000..c71c820dc27 --- /dev/null +++ b/doc/emacs/mule.texi @@ -0,0 +1,1535 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1997, 1999, 2000, 2001, 2002, 2003, 2004, +@c 2005, 2006, 2007 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 Celtic +@cindex Chinese +@cindex Cyrillic +@cindex Czech +@cindex Devanagari +@cindex Hindi +@cindex Marathi +@cindex Ethiopic +@cindex German +@cindex Greek +@cindex Hebrew +@cindex IPA +@cindex Japanese +@cindex Korean +@cindex Lao +@cindex Latin +@cindex Polish +@cindex Romanian +@cindex Slovak +@cindex Slovenian +@cindex Thai +@cindex Tibetan +@cindex Turkish +@cindex Vietnamese +@cindex Dutch +@cindex Spanish + Emacs supports a wide variety of international character sets, +including European and Vietnamese variants of the Latin alphabet, as +well as Cyrillic, Devanagari (for Hindi and Marathi), Ethiopic, Greek, +Han (for Chinese and Japanese), Hangul (for Korean), Hebrew, IPA, +Kannada, Lao, Malayalam, Tamil, Thai, Tibetan, and Vietnamese scripts. +Emacs also supports various encodings of these characters used by +other internationalized software, such as word processors and mailers. + + Emacs allows editing text with international characters by supporting +all the related activities: + +@itemize @bullet +@item +You can visit files with non-@acronym{ASCII} characters, save non-@acronym{ASCII} text, and +pass non-@acronym{ASCII} text between Emacs and programs it invokes (such as +compilers, spell-checkers, and mailers). Setting your language +environment (@pxref{Language Environments}) takes care of setting up the +coding systems and other options for a specific language or culture. +Alternatively, you can specify how Emacs should encode or decode text +for each command; see @ref{Text Coding}. + +@item +You can display non-@acronym{ASCII} characters encoded by the various +scripts. This works by using appropriate fonts on graphics displays +(@pxref{Defining Fontsets}), and by sending special codes to text-only +displays (@pxref{Terminal Coding}). If some characters are displayed +incorrectly, refer to @ref{Undisplayable Characters}, which describes +possible problems and explains how to solve them. + +@item +You can insert non-@acronym{ASCII} characters or search for them. To do that, +you can specify an input method (@pxref{Select Input Method}) suitable +for your language, or use the default input method set up when you set +your language environment. If +your keyboard can produce non-@acronym{ASCII} characters, you can select an +appropriate keyboard coding system (@pxref{Terminal Coding}), and Emacs +will accept those characters. Latin-1 characters can also be input by +using the @kbd{C-x 8} prefix, see @ref{Unibyte Mode}. + +On X Window systems, your locale should be set to an appropriate value +to make sure Emacs interprets keyboard input correctly; see +@ref{Language Environments, locales}. +@end itemize + + The rest of this chapter describes these issues in detail. + +@menu +* International Chars:: 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:: Specifying a file's coding system explicitly. +* Output Coding:: Choosing coding systems for output. +* Text Coding:: Choosing conversion to use for file text. +* Communication Coding:: Coding systems for interprocess communication. +* File Name Coding:: Coding systems for file @emph{names}. +* Terminal Coding:: Specifying coding systems for converting + terminal input and output. +* Fontsets:: Fontsets are collections of fonts + that cover the whole spectrum of characters. +* Defining Fontsets:: Defining a new fontset. +* Undisplayable Characters:: When characters don't display. +* Unibyte Mode:: You can pick one European character set + to use without multibyte characters. +* Charsets:: How Emacs groups its internal character codes. +@end menu + +@node International Chars +@section Introduction to International Character Sets + + The users of international character sets and 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-@acronym{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 +@cindex undisplayable characters +@cindex @samp{?} in display + 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. If some characters can't be +displayed on your terminal, they appear as @samp{?} or as hollow boxes +(@pxref{Undisplayable Characters}). + + 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 + + By default, Emacs starts in multibyte mode, because that allows you to +use all the supported languages and scripts without limitations. + +@cindex turn multibyte support on or off + 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, we call that @dfn{unibyte mode}. 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 in unibyte mode 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{Text +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 @env{EMACS_UNIBYTE}. You can also customize +@code{enable-multibyte-characters} or, equivalently, directly set the +variable @code{default-enable-multibyte-characters} to @code{nil} in +your init file to have basically the same effect as @samp{--unibyte}. + +@findex toggle-enable-multibyte-characters + To convert a unibyte session to a multibyte session, set +@code{default-enable-multibyte-characters} to @code{t}. Buffers which +were created in the unibyte session before you turn on multibyte support +will stay unibyte. You can turn on multibyte support in a specific +buffer by invoking the command @code{toggle-enable-multibyte-characters} +in that buffer. + +@cindex Lisp files, and multibyte operation +@cindex multibyte operation, and Lisp files +@cindex unibyte operation, and Lisp files +@cindex init file, and non-@acronym{ASCII} characters +@cindex environment variables, and non-@acronym{ASCII} characters + With @samp{--unibyte}, multibyte strings are not created during +initialization from the values of environment variables, +@file{/etc/passwd} entries etc.@: that contain non-@acronym{ASCII} 8-bit +characters. + + Emacs normally loads Lisp files as multibyte, regardless of whether +you used @samp{--unibyte}. This includes the Emacs initialization file, +@file{.emacs}, and the initialization files of Emacs packages such as +Gnus. However, you can specify unibyte loading for a particular Lisp +file, by putting @w{@samp{-*-unibyte: t;-*-}} in a comment on the first +line (@pxref{File Variables}). Then that file is always loaded as +unibyte text, even if you did not start Emacs with @samp{--unibyte}. +The motivation for these conventions is that it is more reliable to +always load any particular Lisp file in the same way. However, you can +load a Lisp file as unibyte, on any one occasion, by typing @kbd{C-x +@key{RET} c raw-text @key{RET}} immediately before loading it. + + 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) near the beginning of the mode +line, before the indication of the visited file's end-of-line +convention (colon, backslash, etc.). When multibyte characters +are not enabled, nothing precedes the colon except a single dash. +@xref{Mode Line}, for more details about this. + +@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 +@vindex current-language-environment + To select a language environment, you can customize the variable +@code{current-language-environment} or use 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: + +@cindex Euro sign +@cindex UTF-8 +@quotation +ASCII, Belarusian, Brazilian Portuguese, Bulgarian, Chinese-BIG5, +Chinese-CNS, Chinese-EUC-TW, Chinese-GB, Croatian, Cyrillic-ALT, +Cyrillic-ISO, Cyrillic-KOI8, Czech, Devanagari, Dutch, English, +Esperanto, Ethiopic, French, Georgian, German, Greek, Hebrew, IPA, +Italian, Japanese, Kannada, Korean, Lao, Latin-1, Latin-2, Latin-3, +Latin-4, Latin-5, Latin-6, Latin-7, Latin-8 (Celtic), Latin-9 (updated +Latin-1 with the Euro sign), Latvian, Lithuanian, Malayalam, Polish, +Romanian, Russian, Slovak, Slovenian, Spanish, Swedish, Tajik, Tamil, +Thai, Tibetan, Turkish, UTF-8 (for a setup which prefers Unicode +characters and files encoded in UTF-8), Ukrainian, Vietnamese, Welsh, +and Windows-1255 (for a setup which prefers Cyrillic characters and +files encoded in Windows-1255). +@tex +\hbadness=10000\par % just avoid underfull hbox warning +@end tex +@end quotation + +@cindex fonts for various scripts +@cindex Intlfonts package, installation + To display the script(s) used by your language environment on a +graphical display, you need to have a suitable font. If some of the +characters appear as empty boxes, you should install the GNU Intlfonts +package, which includes fonts for most supported scripts.@footnote{If +you run Emacs on X, you need to inform the X server about the location +of the newly installed fonts with the following commands: + +@example + xset fp+ /usr/local/share/emacs/fonts + xset fp rehash +@end example +} +@xref{Fontsets}, for more details about setting up your fonts. + +@findex set-locale-environment +@vindex locale-language-names +@vindex locale-charset-language-names +@cindex locales + Some operating systems let you specify the character-set locale you +are using by setting the locale environment variables @env{LC_ALL}, +@env{LC_CTYPE}, or @env{LANG}.@footnote{If more than one of these is +set, the first one that is nonempty specifies your locale for this +purpose.} During startup, Emacs looks up your character-set locale's +name in the system locale alias table, matches its canonical name +against entries in the value of the variables +@code{locale-charset-language-names} and @code{locale-language-names}, +and selects the corresponding language environment if a match is found. +(The former variable overrides the latter.) It also adjusts the display +table and terminal coding system, the locale coding system, the +preferred coding system as needed for the locale, and---last but not +least---the way Emacs decodes non-@acronym{ASCII} characters sent by your keyboard. + + If you modify the @env{LC_ALL}, @env{LC_CTYPE}, or @env{LANG} +environment variables while running Emacs, you may want to invoke the +@code{set-locale-environment} function afterwards to readjust the +language environment from the new locale. + +@vindex locale-preferred-coding-systems + The @code{set-locale-environment} function normally uses the preferred +coding system established by the language environment to decode system +messages. But if your locale matches an entry in the variable +@code{locale-preferred-coding-systems}, Emacs uses the corresponding +coding system instead. For example, if the locale @samp{ja_JP.PCK} +matches @code{japanese-shift-jis} in +@code{locale-preferred-coding-systems}, Emacs uses that encoding even +though it might normally use @code{japanese-iso-8bit}. + + You can override the language environment chosen at startup with +explicit use of the command @code{set-language-environment}, or with +customization of @code{current-language-environment} in your init +file. + +@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. If you give an empty input for @var{lang-env}, +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}. This hook is where you should +put non-default settings for specific language environment, such as +coding systems for keyboard input and terminal output, the default +input method, etc. + +@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 @acronym{ASCII} letters +into another alphabet; this allows you to use one other alphabet +instead of @acronym{ASCII}. The Greek and Russian input methods +work this way. + + A more powerful technique is composition: converting sequences of +characters into one letter. Many European input methods use composition +to produce a single non-@acronym{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). One input sequence typically +corresponds to many possible Chinese characters. You select the one +you mean using keys such as @kbd{C-f}, @kbd{C-b}, @kbd{C-n}, +@kbd{C-p}, and digits, which have special meanings in this situation. + + The possible characters are conceptually arranged in several rows, +with each row holding up to 10 alternatives. Normally, Emacs displays +just one row at a time, in the echo area; @code{(@var{i}/@var{j})} +appears at the beginning, to indicate that this is the @var{i}th row +out of a total of @var{j} rows. Type @kbd{C-n} or @kbd{C-p} to +display the next row or the previous row. + + Type @kbd{C-f} and @kbd{C-b} to move forward and backward among +the alternatives in the current row. As you do this, Emacs highlights +the current alternative with a special color; type @code{C-@key{SPC}} +to select the current alternative and use it as input. The +alternatives in the row are also numbered; the number appears before +the alternative. Typing a digit @var{n} selects the @var{n}th +alternative of the current row and uses it as input. + + @key{TAB} in these Chinese input methods displays a buffer showing +all the possible characters at once; then clicking @kbd{Mouse-2} on +one of them selects that alternative. The keys @kbd{C-f}, @kbd{C-b}, +@kbd{C-n}, @kbd{C-p}, and digits continue to work as usual, but they +do the highlighting in the buffer showing the possible characters, +rather than in the echo area. + + 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 a number of different Japanese words; +to 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; this 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. +@ifnottex +@xref{Select Input Method}. +@end ifnottex + +@cindex incremental search, input method interference + @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. + + To find out how to input the character after point using the current +input method, type @kbd{C-u C-x =}. @xref{Position Info}. + +@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 (for +most input methods---some disable this feature). 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 from 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 @acronym{ASCII} characters to +stand for non-@acronym{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. + + When invoked with a numeric argument, as in @kbd{C-u C-\}, +@code{toggle-input-method} always prompts you for an input method, +suggesting the most recently selected one as the default. + +@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). + + In some language environments, which support several different input +methods, you might want to use an input method different from the +default chosen by @code{set-language-environment}. You can instruct +Emacs to select a different default input method for a certain +language environment, if you wish, by using +@code{set-language-environment-hook} (@pxref{Language Environments, +set-language-environment-hook}). For example: + +@lisp +(defun my-chinese-setup () + "Set up my private Chinese environment." + (if (equal current-language-environment "Chinese-GB") + (setq default-input-method "chinese-tonepy"))) +(add-hook 'set-language-environment-hook 'my-chinese-setup) +@end lisp + +@noindent +This sets the default input method to be @code{chinese-tonepy} +whenever you choose a Chinese-GB language environment. + +@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 quail-show-key + You can use the command @kbd{M-x quail-show-key} to show what key (or +key sequence) to type in order to input the character following point, +using the selected keyboard layout. The command @kbd{C-u C-x =} also +shows that information in addition to the other information about the +character. + +@findex list-input-methods + To see 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-@acronym{ASCII} characters + + When multibyte characters are enabled, character codes 0240 (octal) +through 0377 (octal) are not really legitimate in the buffer. The valid +non-@acronym{ASCII} printing characters have codes that start from 0400. + + If you type a self-inserting character in the range 0240 through +0377, or if you use @kbd{C-q} to insert one, 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 +@ifnottex +(@pxref{Language Environments}). +@end ifnottex +If you do not specify a choice, the default is Latin-1. + + If you insert a character in the range 0200 through 0237, which +forms the @code{eight-bit-control} character set, it is inserted +literally. You should normally avoid doing this since buffers +containing such characters have to be written out in either the +@code{emacs-mule} or @code{raw-text} coding system, which is usually +not what you want. + +@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 international files from DOS/Windows systems + A special class of coding systems, collectively known as +@dfn{codepages}, is designed to support text encoded by MS-Windows and +MS-DOS software. The names of these coding systems are +@code{cp@var{nnnn}}, where @var{nnnn} is a 3- or 4-digit number of the +codepage. You can use these encodings just like any other coding +system; for example, to visit a file encoded in codepage 850, type +@kbd{C-x @key{RET} c cp850 @key{RET} C-x C-f @var{filename} +@key{RET}}@footnote{ +In the MS-DOS port of Emacs, you need to create a @code{cp@var{nnn}} +coding system with @kbd{M-x codepage-setup}, before you can use it. +@iftex +@xref{MS-DOS and MULE,,,emacs-extra,Specialized Emacs Features}. +@end iftex +@ifnottex +@xref{MS-DOS and MULE}. +@end ifnottex +}. + + In addition to converting various representations of non-@acronym{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, including the end-of-line +conversion specified by those coding systems. You can specify a coding +system name as the 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 line endings +@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 @samp{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}. + +@cindex @code{undecided}, coding system + The coding systems @code{unix}, @code{dos}, and @code{mac} are +aliases for @code{undecided-unix}, @code{undecided-dos}, and +@code{undecided-mac}, respectively. These coding systems specify only +the end-of-line conversion, and leave the character code conversion to +be deduced from the text itself. + + The coding system @code{raw-text} is good for a file which is mainly +@acronym{ASCII} text, but may contain byte values above 127 which are +not meant to encode non-@acronym{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-@acronym{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-@acronym{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. + +@findex unify-8859-on-decoding-mode +@anchor{Character Translation} + The @dfn{character translation} feature can modify the effect of +various coding systems, by changing the internal Emacs codes that +decoding produces. For instance, the command +@code{unify-8859-on-decoding-mode} enables a mode that ``unifies'' the +Latin alphabets when decoding text. This works by converting all +non-@acronym{ASCII} Latin-@var{n} characters to either Latin-1 or +Unicode characters. This way it is easier to use various +Latin-@var{n} alphabets together. (In a future Emacs version we hope +to move towards full Unicode support and complete unification of +character sets.) + +@vindex enable-character-translation + If you set the variable @code{enable-character-translation} to +@code{nil}, that disables all character translation (including +@code{unify-8859-on-decoding-mode}). + +@node Recognize Coding +@section Recognizing Coding Systems + + Emacs tries to recognize which coding system to use for a given text +as an integral part of reading that text. (This applies to files +being read, output from subprocesses, text from X selections, etc.) +Emacs can select the right coding system automatically most of the +time---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 coding system 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 this means is that Emacs +should attempt to recognize @code{iso-8859-1} with priority, and should +use DOS end-of-line conversion when it does recognize @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{chinese-iso-8bit}, you can execute this Lisp expression: + +@smallexample +(modify-coding-system-alist 'file "\\.txt\\'" 'chinese-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 +@cindex DOS-style end-of-line display + 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}. If you do that, DOS-style files will be displayed +with the @samp{^M} characters visible in the buffer; some people +prefer this to the more subtle @samp{(DOS)} end-of-line type +indication near the left edge of the mode line (@pxref{Mode Line, +eol-mnemonic}). + +@vindex inhibit-iso-escape-detection +@cindex escape sequences in files + By default, the automatic detection of coding system is sensitive to +escape sequences. If Emacs sees a sequence of characters that begin +with an escape character, and the sequence is valid as an ISO-2022 +code, that tells Emacs to use one of the ISO-2022 encodings to decode +the file. + + However, there may be cases that you want to read escape sequences +in a file as is. In such a case, you can set the variable +@code{inhibit-iso-escape-detection} to non-@code{nil}. Then the code +detection ignores any escape sequences, and never uses an ISO-2022 +encoding. The result is that all escape sequences become visible in +the buffer. + + The default value of @code{inhibit-iso-escape-detection} is +@code{nil}. We recommend that you not change it permanently, only for +one specific operation. That's because many Emacs Lisp source files +in the Emacs distribution contain non-@acronym{ASCII} characters encoded in the +coding system @code{iso-2022-7bit}, and they won't be +decoded correctly when you visit those files if you suppress the +escape sequence detection. + +@vindex auto-coding-alist +@vindex auto-coding-regexp-alist +@vindex auto-coding-functions + The variables @code{auto-coding-alist}, +@code{auto-coding-regexp-alist} and @code{auto-coding-functions} are +the strongest way to specify the coding system for certain patterns of +file names, or for files containing certain patterns; these variables +even override @samp{-*-coding:-*-} tags in the file itself. Emacs +uses @code{auto-coding-alist} for tar and archive files, to prevent it +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. +Likewise, Emacs uses @code{auto-coding-regexp-alist} to ensure that +RMAIL files, whose names in general don't match any particular +pattern, are decoded correctly. One of the builtin +@code{auto-coding-functions} detects the encoding for XML files. + +@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 File's Coding System + + If Emacs recognizes the encoding of a file incorrectly, you can +reread the file using the correct coding system by typing @kbd{C-x +@key{RET} r @var{coding-system} @key{RET}}. To see what coding system +Emacs actually used to decode the file, look at the coding system +mnemonic letter near the left edge of the mode line (@pxref{Mode +Line}), or type @kbd{C-h C @key{RET}}. + +@vindex coding + You can specify the coding system for a particular file in the file +itself, using the @w{@samp{-*-@dots{}-*-}} construct at the beginning, +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, this 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. When you specify +the coding explicitly in the file, that overrides +@code{file-coding-system-alist}. + + If you add the character @samp{!} at the end of the coding system +name in @code{coding}, it disables any character translation +(@pxref{Character Translation}) while decoding the file. This is +useful when you need to make sure that the character codes in the +Emacs buffer will not vary due to changes in user settings; for +instance, for the sake of strings in Emacs Lisp source files. + +@node Output Coding +@section Choosing Coding Systems for Output + +@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}. That makes it the +default for operations that write from this buffer into a file, such +as @code{save-buffer} and @code{write-region}. You can specify a +different coding system for further file output from the buffer using +@code{set-buffer-file-coding-system} (@pxref{Text Coding}). + + You can insert any character Emacs supports into any Emacs buffer, +but most coding systems can only handle a subset of these characters. +Therefore, you can insert characters that cannot be encoded with the +coding system that will be used to save the buffer. For example, you +could start with an @acronym{ASCII} file and insert a few Latin-1 +characters into it, or you could edit a text file in Polish encoded in +@code{iso-8859-2} and add some Russian words to it. When you save +that buffer, Emacs cannot use the current value of +@code{buffer-file-coding-system}, because the characters you added +cannot be encoded by that coding system. + + When that happens, Emacs tries the most-preferred coding system (set +by @kbd{M-x prefer-coding-system} or @kbd{M-x +set-language-environment}), and if that coding system can safely +encode all of the characters in the buffer, Emacs uses it, and stores +its value in @code{buffer-file-coding-system}. Otherwise, Emacs +displays a list of coding systems suitable for encoding the buffer's +contents, and asks you to choose one of those coding systems. + + If you insert the unsuitable characters in a mail message, Emacs +behaves a bit differently. It additionally checks whether the +most-preferred coding system is recommended for use in MIME messages; +if not, Emacs tells you that the most-preferred coding system is not +recommended and prompts you for another coding system. This is so you +won't inadvertently send a message encoded in a way that your +recipient's mail software will have difficulty decoding. (You can +still use an unsuitable coding system if you type its name in response +to the question.) + +@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. + +@node Text Coding +@section Specifying a Coding System for File Text + + In cases where Emacs does not automatically choose the right coding +system for a file's contents, 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 saving or revisiting 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} r @var{coding} @key{RET} +Revisit the current file using the coding system @var{coding}. + +@item M-x recode-region @key{RET} @var{right} @key{RET} @var{wrong} @key{RET} +Convert a region that was decoded using coding system @var{wrong}, +decoding it using coding system @var{right} instead. +@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}) sets the file coding system for +the current buffer---in other words, it says which coding system to +use when saving or reverting the visited file. You specify which +coding system using the minibuffer. If you specify a coding system +that cannot handle all of the characters in the buffer, Emacs warns +you about the troublesome characters when you actually save the +buffer. + +@cindex specify end-of-line conversion + You can also use this command to specify the end-of-line conversion +(@pxref{Coding Systems, end-of-line conversion}) for encoding the +current buffer. For example, @kbd{C-x @key{RET} f dos @key{RET}} will +cause Emacs to save the current buffer's text with DOS-style CRLF line +endings. + +@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 you later save the file). Or if the immediately following +command is @kbd{C-x C-w}, it writes the file using that coding system. +When you specify the coding system for saving in this way, instead +of with @kbd{C-x @key{RET} f}, there is no warning if the buffer +contains characters that the coding system cannot handle. + + Other file commands affected by a specified coding system include +@kbd{C-x 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}). 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 r +@findex revert-buffer-with-coding-system + If you visit a file with a wrong coding system, you can correct this +with @kbd{C-x @key{RET} r} (@code{revert-buffer-with-coding-system}). +This visits the current file again, using a coding system you specify. + +@findex recode-region + If a piece of text has already been inserted into a buffer using the +wrong coding system, you can redo the decoding of it using @kbd{M-x +recode-region}. This prompts you for the proper coding system, then +for the wrong coding system that was actually used, and does the +conversion. It first encodes the region using the wrong coding system, +then decodes it again using the proper coding system. + +@node Communication Coding +@section Coding Systems for Interprocess Communication + + This section explains how to specify coding systems for use +in communication with other processes. + +@table @kbd +@item C-x @key{RET} x @var{coding} @key{RET} +Use coding system @var{coding} for transferring selections to and from +other window-based applications. + +@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 another window-based application. + +@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} c @var{coding} @key{RET} +Specify coding system @var{coding} for the immediately following +command. +@end table + +@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 other windowing +applications, 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. + + You can also use @kbd{C-x @key{RET} c} just before the command that +runs or starts a subprocess, to specify the coding system to use for +communication with that subprocess. + + The default for translation of process input and output depends on the +current language environment. + +@vindex locale-coding-system +@cindex decoding non-@acronym{ASCII} keyboard input on X + The variable @code{locale-coding-system} specifies a coding system +to use when encoding and decoding system strings such as system error +messages and @code{format-time-string} formats and time stamps. That +coding system is also used for decoding non-@acronym{ASCII} keyboard input on X +Window systems. You should choose a coding system that is compatible +with the underlying system's text representation, which is normally +specified by one of the environment variables @env{LC_ALL}, +@env{LC_CTYPE}, and @env{LANG}. (The first one, in the order +specified above, whose value is nonempty is the one that determines +the text representation.) + +@node File Name Coding +@section Coding Systems for File Names + +@table @kbd +@item C-x @key{RET} F @var{coding} @key{RET} +Use coding system @var{coding} for encoding and decoding file +@emph{names}. +@end table + +@vindex file-name-coding-system +@cindex file names with non-@acronym{ASCII} characters + The variable @code{file-name-coding-system} specifies a coding +system to use for encoding file names. It has no effect on reading +and writing the @emph{contents} of files. + +@findex set-file-name-coding-system +@kindex C-x @key{RET} F + 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-@acronym{ASCII} +characters in file names---or, at least, those non-@acronym{ASCII} +characters which the specified coding system can encode. Use @kbd{C-x +@key{RET} F} (@code{set-file-name-coding-system}) to specify this +interactively. + + 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-@acronym{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. + +@findex recode-file-name + If a mistake occurs when encoding a file name, use the command +@kbd{M-x recode-file-name} to change the file name's coding +system. This prompts for an existing file name, its old coding +system, and the coding system to which you wish to convert. + +@node Terminal Coding +@section Coding Systems for Terminal I/O + +@table @kbd +@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. +@end table + +@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 or +your locale specification (@pxref{Language Environments}). + +@kindex C-x RET k +@findex set-keyboard-coding-system +@vindex keyboard-coding-system + The command @kbd{C-x @key{RET} k} (@code{set-keyboard-coding-system}) +or the variable @code{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-@acronym{ASCII} +graphic characters---for example, some terminals designed for ISO +Latin-1 or subsets of it. + + By default, keyboard input is translated based on your system locale +setting. If your terminal does not really support the encoding +implied by your locale (for example, if you find it inserts a +non-@acronym{ASCII} character if you type @kbd{M-i}), you will need to set +@code{keyboard-coding-system} to @code{nil} to turn off encoding. +You can do this by putting + +@lisp +(set-keyboard-coding-system nil) +@end lisp + +@noindent +in your @file{~/.emacs} file. + + 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 @acronym{ASCII} +printing characters. Coding systems typically translate sequences of +non-graphic characters. + +@node Fontsets +@section Fontsets +@cindex fontsets + + A font typically defines shapes for a single 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. However, while fonts are +stored in the system and the available font names are defined by the +system, fontsets 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 system 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.@footnote{The Emacs +installation instructions have information on additional font +support.} + + 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-@acronym{ASCII} characters; +however, this is not the default for Emacs to use. (By default, Emacs +tries to find a font that has bold and italic variants.) You can +specify use of the standard fontset with the @samp{-fn} option. For +example, + +@example +emacs -fn fontset-standard +@end example + +@noindent +You can also specify a fontset with the @samp{Font} resource (@pxref{X +Resources}). + + 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. + +@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 @acronym{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 matches various other resources, such as for 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{charset}:@var{font}@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 @acronym{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 is what Emacs +does. + + Thus if @var{fontpattern} is this, + +@example +-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24 +@end example + +@noindent +the font specification for @acronym{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 Undisplayable Characters +@section Undisplayable Characters + + There may be a some non-@acronym{ASCII} characters that your terminal cannot +display. Most text-only terminals support just a single character +set (use the variable @code{default-terminal-coding-system} +(@pxref{Terminal Coding}) to tell Emacs which one); characters which +can't be encoded in that coding system are displayed as @samp{?} by +default. + + Graphical displays can display a broader range of characters, but +you may not have fonts installed for all of them; characters that have +no font appear as a hollow box. + + If you use Latin-1 characters but your terminal can't display +Latin-1, you can arrange to display mnemonic @acronym{ASCII} sequences +instead, e.g.@: @samp{"o} for o-umlaut. Load the library +@file{iso-ascii} to do this. + +@vindex latin1-display + If your terminal can display Latin-1, you can display characters +from other European character sets using a mixture of equivalent +Latin-1 characters and @acronym{ASCII} mnemonics. Customize the variable +@code{latin1-display} to enable this. The mnemonic @acronym{ASCII} +sequences mostly correspond to those of the prefix input methods. + +@node Unibyte Mode +@section Unibyte Editing Mode + +@cindex European character sets +@cindex accented characters +@cindex ISO Latin character sets +@cindex Unibyte operation + The ISO 8859 Latin-@var{n} character sets define character codes in +the range 0240 to 0377 octal (160 to 255 decimal) to handle the +accented letters and punctuation needed by various European languages +(and some non-European ones). 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-@acronym{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, on a +graphical display, 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 @acronym{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 (decimal codes between 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 two ways to input single-byte non-@acronym{ASCII} +characters: + +@itemize @bullet +@cindex 8-bit input +@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-@acronym{ASCII} character you specify with it is converted to unibyte. + +@item +If your keyboard can generate character codes 128 (decimal) and up, +representing non-@acronym{ASCII} characters, you can type those character codes +directly. + +On a graphical display, you should not need to do anything special to use +these keys; they should simply work. On a text-only terminal, you +should use the command @code{M-x set-keyboard-coding-system} or the +variable @code{keyboard-coding-system} to specify which coding system +your keyboard uses (@pxref{Terminal Coding}). Enabling this feature +will probably require you to use @kbd{ESC} to type Meta characters; +however, on a console terminal or in @code{xterm}, you can arrange for +Meta to be converted to @kbd{ESC} and still be able type 8-bit +characters present directly on the keyboard or using @kbd{Compose} or +@kbd{AltGr} keys. @xref{User Input}. + +@kindex C-x 8 +@cindex @code{iso-transl} library +@cindex compose character +@cindex dead character +@item +For Latin-1 only, you can use the key @kbd{C-x 8} as a ``compose +character'' prefix for entry of non-@acronym{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 the keyboard has +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 the keyboard has keys for the Latin-1 ``dead accent characters,'' +they too are defined to compose with the following character, once +@code{iso-transl} is loaded. + +Use @kbd{C-x 8 C-h} to list all the available @kbd{C-x 8} translations. +@end itemize + +@node Charsets +@section Charsets +@cindex charsets + + Emacs groups all supported characters into disjoint @dfn{charsets}. +Each character code belongs to one and only one charset. For +historical reasons, Emacs typically divides an 8-bit character code +for an extended version of @acronym{ASCII} into two charsets: +@acronym{ASCII}, which covers the codes 0 through 127, plus another +charset which covers the ``right-hand part'' (the codes 128 and up). +For instance, the characters of Latin-1 include the Emacs charset +@code{ascii} plus the Emacs charset @code{latin-iso8859-1}. + + Emacs characters belonging to different charsets may look the same, +but they are still different characters. For example, the letter +@samp{o} with acute accent in charset @code{latin-iso8859-1}, used for +Latin-1, is different from the letter @samp{o} with acute accent in +charset @code{latin-iso8859-2}, used for Latin-2. + +@findex list-charset-chars +@cindex characters in a certain charset +@findex describe-character-set + There are two commands for obtaining information about Emacs +charsets. The command @kbd{M-x list-charset-chars} prompts for a name +of a character set, and displays all the characters in that character +set. The command @kbd{M-x describe-character-set} prompts for a +charset name and displays information about that charset, including +its internal representation within Emacs. + + To find out which charset a character in the buffer belongs to, +put point before it and type @kbd{C-u C-x =}. + +@ignore + arch-tag: 310ba60d-31ef-4ce7-91f1-f282dd57b6b3 +@end ignore diff --git a/doc/emacs/picture-xtra.texi b/doc/emacs/picture-xtra.texi new file mode 100644 index 00000000000..ad3b9f27cc5 --- /dev/null +++ b/doc/emacs/picture-xtra.texi @@ -0,0 +1,291 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@c +@c This file is included either in emacs-xtra.texi (when producing the +@c printed version) or in the main Emacs manual (for the on-line version). +@node Picture Mode +@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 particularly 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}. +Additional extensions to Picture mode can be found in +@file{artist.el}. + +@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 +@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 +@iftex +(@pxref{Minor Modes,,, emacs, the Emacs Manual}.) +@end iftex +@ifnottex +(@pxref{Minor Modes}.) +@end ifnottex +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 + In Picture mode, the commands that normally delete or kill text, +instead erase text (replacing it with spaces). @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 another line with the same +contents below the current line. + +@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 +@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 < +@itemx C-c @key{LEFT} +Move left after insertion (@code{picture-movement-left}). +@item C-c > +@itemx C-c @key{RIGHT} +Move right after insertion (@code{picture-movement-right}). +@item C-c ^ +@itemx C-c @key{UP} +Move up after insertion (@code{picture-movement-up}). +@item C-c . +@itemx C-c @key{DOWN} +Move down after insertion (@code{picture-movement-down}). +@item C-c ` +@itemx C-c @key{HOME} +Move up and left (``northwest'') after insertion (@code{picture-movement-nw}). +@item C-c ' +@itemx C-c @key{PAGEUP} +Move up and right (``northeast'') after insertion +(@code{picture-movement-ne}). +@item C-c / +@itemx C-c @key{END} +Move down and left (``southwest'') after insertion +@*(@code{picture-movement-sw}). +@item C-c \ +@itemx C-c @key{PAGEDOWN} +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 +@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}. + +@node Rectangles in 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. +@iftex +@xref{Rectangles,,, emacs, the Emacs Manual}. +@end iftex +@ifnottex +@xref{Rectangles}. +@end ifnottex + +@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 that they overwrite 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. + +@ignore + arch-tag: 10e423ad-d896-42f2-a7e8-7018adeaf8c2 +@end ignore diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi new file mode 100644 index 00000000000..2472d7daabe --- /dev/null +++ b/doc/emacs/programs.texi @@ -0,0 +1,1773 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, +@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 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 provides many features to facilitate editing programs. Some +of these features can + +@itemize @bullet +@item +Find or move over top-level definitions (@pxref{Defuns}). +@item +Apply the usual indentation conventions of the language +(@pxref{Program Indent}). +@item +Balance parentheses (@pxref{Parentheses}). +@item +Insert, kill or align comments (@pxref{Comments}). +@item +Highlight program syntax (@pxref{Font Lock}). +@end itemize + + This chapter describes these features and many more. + +@menu +* Program Modes:: Major modes for editing programs. +* Defuns:: Commands to operate on major top-level parts + of a program. +* Program Indent:: Adjusting indentation to show the nesting. +* Parentheses:: Commands that operate on parentheses. +* Comments:: Inserting, killing, and aligning comments. +* Documentation:: Getting documentation of functions you plan to call. +* Hideshow:: Displaying blocks selectively. +* Symbol Completion:: Completion on symbol names of your program or language. +* Glasses:: Making identifiersLikeThis more readable. +* Misc for Programs:: Other Emacs features useful for editing programs. +* C Modes:: Special commands of C, C++, Objective-C, + Java, and Pike modes. +* Asm Mode:: Asm mode and its special features. +@ifnottex +* Fortran:: Fortran mode and its special features. +@end ifnottex +@end menu + +@node Program Modes +@section Major Modes for Programming Languages +@cindex modes for programming languages + + Emacs has specialized major modes for various programming languages. +@xref{Major Modes}. A programming language major mode typically +specifies the syntax of expressions, the customary rules for +indentation, how to do syntax highlighting for the language, and how +to find the beginning of a function definition. It often customizes +or provides facilities for compiling and debugging programs as well. + + Ideally, Emacs should provide a major mode for each programming +language that you might want to edit; if it doesn't have a mode for +your favorite language, you can contribute one. But often the mode +for one language can serve for other syntactically similar languages. +The major mode for language @var{l} is called @code{@var{l}-mode}, +and you can select it by typing @kbd{M-x @var{l}-mode @key{RET}}. +@xref{Choosing Modes}. + +@cindex Perl mode +@cindex Icon mode +@cindex Makefile mode +@cindex Tcl mode +@cindex CPerl mode +@cindex DSSSL mode +@cindex Octave mode +@cindex Metafont mode +@cindex Modula2 mode +@cindex Prolog mode +@cindex Python mode +@cindex Simula mode +@cindex VHDL mode +@cindex M4 mode +@cindex Shell-script mode +@cindex Delphi mode +@cindex PostScript mode +@cindex Conf mode +@cindex DNS mode + The existing programming language major modes include Lisp, Scheme (a +variant of Lisp) and the Scheme-based DSSSL expression language, Ada, +ASM, AWK, C, C++, Delphi (Object Pascal), Fortran (free format and fixed +format), Icon, IDL (CORBA), IDLWAVE, Java, Metafont (@TeX{}'s +companion for font creation), Modula2, Objective-C, Octave, Pascal, +Perl, Pike, PostScript, Prolog, Python, Simula, Tcl, and VHDL. An +alternative mode for Perl is called CPerl mode. Modes are available for +the scripting languages of the common GNU and Unix shells, VMS DCL, and +MS-DOS/MS-Windows @samp{BAT} files. There are also major modes for +editing makefiles, DNS master files, and various sorts of configuration +files. + +@kindex DEL @r{(programming modes)} +@findex c-electric-backspace + In most programming languages, indentation should vary from line to +line to illustrate the structure of the program. So the major modes +for programming languages arrange for @key{TAB} to update the +indentation of the current line. They also rebind @key{DEL} to treat +a tab as if it were the equivalent number of spaces; this lets you +delete one column of indentation without worrying whether the +whitespace consists of spaces or tabs. Use @kbd{C-b C-d} to delete a +tab character before point, in these modes. + + Separate manuals are available for the modes for Ada (@pxref{Top, , Ada +Mode, ada-mode, Ada Mode}), C/C++/Objective C/Java/Corba IDL/Pike/AWK +(@pxref{Top, , CC Mode, ccmode, CC Mode}) and the IDLWAVE modes +(@pxref{Top, , IDLWAVE, idlwave, IDLWAVE User Manual}). For Fortran +mode, see +@iftex +@ref{Fortran,,, emacs-xtra, Specialized Emacs Features}. +@end iftex +@ifnottex +@ref{Fortran}. +@end ifnottex + + +@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 + 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}. The purpose of the mode hook is to give you a +place to set up customizations for that major mode. @xref{Hooks}. + +@node Defuns +@section Top-Level Definitions, or Defuns + + In Emacs, a major definition at the top level in the buffer, +something like a function, is called a @dfn{defun}. The name comes +from Lisp, but in Emacs we use it for all languages. + +@menu +* Left Margin Paren:: An open-paren or similar opening delimiter + starts a defun if it is at the left margin. +* Moving by Defuns:: Commands to move over or mark a major definition. +* Imenu:: Making buffer indexes as menus. +* Which Function:: Which Function mode shows which function you are in. +@end menu + +@node Left Margin Paren +@subsection Left Margin Convention + +@cindex open-parenthesis in leftmost column +@cindex ( in leftmost column + Emacs assumes by default that any opening delimiter found at the +left margin is the start of a top-level definition, or defun. +Therefore, @strong{don't put an opening delimiter at the left margin +unless it should have that significance}. For instance, never put an +open-parenthesis at the left margin in a Lisp file unless it is the +start of a top-level list. + + If you don't follow this convention, not only will you have trouble +when you explicitly use the commands for motion by defuns; other +features that use them will also give you trouble. This includes +the indentation commands (@pxref{Program Indent}) and Font Lock +mode (@pxref{Font Lock}). + + 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. This will not +affect the contents of the string, but will prevent that opening +delimiter from starting a defun. Here's an example: + +@example + (insert "Foo: +\(bar) +") +@end example + + To help you catch violations of this convention, Font Lock mode +highlights confusing opening delimiters (those that ought to be +quoted) in bold red. + +If you need to override this convention, you can so by setting this +user option: + +@defvar open-paren-in-column-0-is-defun-start +If this user option is set to @code{t} (the default), opening +parentheses or braces at column zero always start defuns. When it's +@code{nil}, defuns are found by searching for parens or braces at the +outermost level. +@end defvar + + Usually, you shouldn't need to set +@code{open-paren-in-column-0-is-defun-start} to @code{nil}. However, +if your buffer contains parentheses or braces in column zero which +don't start defuns and this confuses Emacs, it sometimes helps to set +the option to @code{nil}. Be aware, though, that this will make +scrolling and display in large buffers quite sluggish, and that +parentheses and braces must be correctly matched throughout the buffer +for it to work properly. + + In the earliest days, the original Emacs found defuns by moving +upward a level of parentheses or braces 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, we changed Emacs to assume that any opening delimiter +at the left margin is the start of a defun. This heuristic is nearly +always right, and avoids the need to scan back to the beginning of the +buffer. However, now that modern computers are so powerful, this +scanning is rarely slow enough to annoy, so we've provided a way to +disable the heuristic. + +@node Moving by Defuns +@subsection Moving by Defuns +@cindex defuns + + These commands move point or set up the region based on top-level +major definitions, also called @dfn{defuns}. + +@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 + +@cindex move to beginning or end of function +@cindex function, move to beginning or end +@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}). If you repeat one of these commands, or use a +positive numeric argument, each repetition moves to the next defun in +the direction of motion. + + @kbd{C-M-a} with a negative argument @minus{}@var{n} moves forward +@var{n} times to the next beginning of a defun. This is not exactly +the same place that @kbd{C-M-e} with argument @var{n} would move to; +the end of this defun is not usually exactly the same place as the +beginning of the following defun. (Whitespace, comments, and perhaps +declarations can separate them.) Likewise, @kbd{C-M-e} with a +negative argument moves back to an end of a defun, which is not quite +the same as @kbd{C-M-a} with a positive argument. + +@kindex C-M-h @r{(C mode)} +@findex c-mark-function + 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 +defun. This is the easiest way to get ready to kill the defun in +order to move it to a different place in the file. If you use the +command while point is between defuns, it uses the following defun. +Successive uses of @kbd{C-M-h}, or using it in Transient Mark mode +when the mark is active, extends the end of the region to include one +more defun each time. + + 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. This is +an example of how major modes adjust the standard key bindings so that +they do their standard jobs in a way better fitting a particular +language. Other major modes may replace any or all of these key +bindings for that purpose. + +@node Imenu +@subsection Imenu +@cindex index of buffer definitions +@cindex buffer definitions index +@cindex tags + + The Imenu facility offers a way to find the major definitions in +a file by name. It is also useful in text formatter major modes, +where it treats each chapter, section, etc., as a definition. +(@xref{Tags}, for a more powerful feature that handles multiple files +together.) + +@findex imenu + If you type @kbd{M-x imenu}, it reads the name of a definition using +the minibuffer, then moves point to that definition. You can use +completion to specify the name; the command always displays the whole +list of valid names. + +@findex imenu-add-menubar-index + Alternatively, you can bind the command @code{imenu} to a mouse +click. Then it displays mouse menus for you to select a definition +name. You can also add the buffer's index to the menu bar by calling +@code{imenu-add-menubar-index}. If you want to have this menu bar +item available for all buffers in a certain major mode, you can do +this by adding @code{imenu-add-menubar-index} to its mode hook. But +if you have done that, you will have to wait a little while each time +you visit a file in that mode, while Emacs finds all the definitions +in that buffer. + +@vindex imenu-auto-rescan + When you change the contents of a buffer, if you add or delete +definitions, you can update the buffer's index based on the +new contents by invoking the @samp{*Rescan*} item in the menu. +Rescanning happens automatically if you set @code{imenu-auto-rescan} to +a non-@code{nil} value. There is no need to rescan because of small +changes in the text. + +@vindex imenu-sort-function + You can customize the way the menus are sorted by setting the +variable @code{imenu-sort-function}. By default, names are ordered as +they occur in the buffer; if you want alphabetic sorting, use the +symbol @code{imenu--sort-by-name} as the value. You can also +define your own comparison function by writing Lisp code. + + Imenu provides the information to guide Which Function mode +@ifnottex +(@pxref{Which Function}). +@end ifnottex +@iftex +(see below). +@end iftex +The Speedbar can also use it (@pxref{Speedbar}). + +@node Which Function +@subsection Which Function Mode +@cindex current function name in mode line + + Which Function mode is a minor mode that displays the current +function name in the mode line, updating it as you move around in a +buffer. + +@findex which-function-mode +@vindex which-func-modes + To either 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, +it takes effect only in 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---in other words, all the major modes that support Imenu. + +@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 + +@cindex pretty-printer + 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 + + The basic indentation commands indent a single line according to the +usual conventions of the language you are editing. + +@need 1000 +@table @kbd +@item @key{TAB} +Adjust indentation of current line. +@item C-j +Insert a newline, then adjust indentation of following line +(@code{newline-and-indent}). +@end table + +@kindex TAB @r{(programming modes)} +@findex c-indent-command +@findex indent-line-function +@findex indent-for-tab-command + 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-command} in C mode, etc. These functions +understand the syntax and conventions of different languages, but they all do +conceptually the same job: @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 was inside the +whitespace at the beginning of the line, @key{TAB} puts it at the end of +that whitespace; otherwise, @key{TAB} keeps point fixed with respect to +the characters around it. + + Use @kbd{C-q @key{TAB}} to insert a tab character at point. + +@kindex C-j +@findex newline-and-indent + When entering lines of new code, use @kbd{C-j} +(@code{newline-and-indent}), which inserts a newline and then adjusts +indentation after it. (It also deletes any trailing whitespace which +remains before the new newline.) Thus, @kbd{C-j} at the end of a line +creates a blank line with appropriate indentation. In programming +language modes, it is equivalent to @key{RET} @key{TAB}. + + @key{TAB} indents a line that starts within a parenthetical grouping +under the preceding line within the grouping, or the text after the +parenthesis. Therefore, if you manually give one of these lines a +nonstandard indentation, 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. + + In some modes, 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. This speeds up +indentation commands. If you will be editing text which contains +opening delimiters in column zero that aren't the beginning of a +functions, even inside strings or comments, you must set +@code{open-paren-in-column-0-is-defun-start}. @xref{Left Margin +Paren}, for more information on this. + + Normally, lines are indented with tabs and spaces. If you want Emacs +to use spaces only, set @code{indent-tabs-mode} (@pxref{Just Spaces}). + +@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 parenthesis structure, +you have several commands available. + +@table @kbd +@item C-M-q +Reindent all the lines within one parenthetical grouping (@code{indent-pp-sexp}). +@item C-M-\ +Reindent all lines in the region (@code{indent-region}). +@item C-u @key{TAB} +Shift an entire parenthetical grouping rigidly sideways so that its +first line is properly indented. +@item M-x indent-code-rigidly +Shift all the lines in the region rigidly sideways, but do not alter +lines that start inside comments and strings. +@end table + +@kindex C-M-q +@findex indent-pp-sexp + You can reindent the contents of a single parenthetical grouping by +positioning point before the beginning of it and typing @kbd{C-M-q} +(@code{indent-pp-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 where the grouping starts is not changed; therefore this +changes only the relative indentation within the grouping, not its +overall indentation. To correct that as well, type @key{TAB} first. + + 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. + +@kindex C-u TAB + If you like the relative indentation within a grouping, but not the +indentation of its first line, you can type @kbd{C-u @key{TAB}} to +reindent the whole grouping as a rigid unit. (This works in Lisp +modes and C and related modes.) @key{TAB} with a numeric argument +reindents the current line as usual, then reindents by the same amount +all the lines in the parenthetical grouping starting on the current +line. It is clever, though, and does not alter lines that start +inside strings. Neither does it alter C preprocessor lines when in C +mode, but it does reindent any continuation lines that may be attached +to them. + +@findex indent-code-rigidly + You can also perform this operation on the region, using the command +@kbd{M-x indent-code-rigidly}. It rigidly shifts all the lines in the +region sideways, like @code{indent-rigidly} does (@pxref{Indentation +Commands}). It doesn't alter the indentation of lines that start +inside a string, unless the region also starts inside that string. +The prefix arg specifies the number of columns to indent. + +@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 + Certain functions override the standard pattern. Functions whose +names start with @code{def} treat the second lines as the start of +a @dfn{body}, by indenting the second line @code{lisp-body-indent} +additional columns beyond the open-parenthesis that starts the +expression. + +@cindex @code{lisp-indent-function} property + You can override the standard pattern in various ways for individual +functions, according to the @code{lisp-indent-function} property of +the function name. Normally you would use this for macro definitions +and specify it using the @code{declare} construct (@pxref{Defining +Macros,,, elisp, the Emacs Lisp Reference Manual}). + +@node C Indent +@subsection Commands for C Indentation + + Here are special features 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 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}). + +@vindex c-tab-always-indent +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 or a string. +@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 +@cindex style (for indentation) + + C mode and related modes use a flexible mechanism for customizing +indentation. C mode indents a source line in two steps: first it +classifies the line syntactically according to its contents and +context; second, it determines the indentation offset associated by +your selected @dfn{style} with the syntactic construct and adds this +onto the indentation of the @dfn{anchor statement}. + +@table @kbd +@item C-c . @key{RET} @var{style} @key{RET} +Select a predefined style @var{style} (@code{c-set-style}). +@end table + + A @dfn{style} is a named collection of customizations that can be +used in C mode and the related modes. @ref{Styles,,, ccmode, The CC +Mode Manual}, for a complete description. Emacs comes with several +predefined styles, including @code{gnu}, @code{k&r}, @code{bsd}, +@code{stroustrup}, @code{linux}, @code{python}, @code{java}, +@code{whitesmith}, @code{ellemtel}, and @code{awk}. Some of these +styles are primarily intended for one language, but any of them can be +used with any of the languages supported by these modes. To find out +what a style looks like, select it and reindent some code, e.g., by +typing @key{C-M-q} at the start of a function definition. + +@kindex C-c . @r{(C mode)} +@findex c-set-style + To choose a style for the current buffer, use the command @w{@kbd{C-c +.}}. Specify a style name as an argument (case is not significant). +This command affects the current buffer only, and it affects only +future invocations of the indentation commands; it does not reindent +the code already in the buffer. To reindent the whole buffer in the +new style, you can type @kbd{C-x h C-M-\}. + +@vindex c-default-style + You can also set the variable @code{c-default-style} to specify the +default style for various major modes. Its value should be either the +style's name (a string) or 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") (awk-mode . "awk") (other . "gnu"))) +@end example + +@noindent +specifies explicit choices for Java and AWK modes, and the default +@samp{gnu} style for the other C-like modes. (These settings are +actually the defaults.) This variable takes effect when you select +one of the C-like major modes; thus, if you specify a new default +style for Java mode, you can make it take effect in an existing Java +mode buffer by typing @kbd{M-x java-mode} there. + + The @code{gnu} style specifies the formatting recommended by the GNU +Project for C; it is the default, so as to encourage use of our +recommended style. + + @xref{Indentation Engine Basics,,, ccmode, the CC Mode Manual}, and +@ref{Customizing Indentation,,, ccmode, the CC Mode Manual}, for more +information on customizing indentation for C and related modes, +including how to override parts of an existing style and how to define +your own styles. + +@node Parentheses +@section Commands for Editing with Parentheses + +@findex check-parens +@cindex unbalanced parentheses and quotes + This section describes the commands and features that take advantage +of the parenthesis structure in a program, or help you keep it +balanced. + + When talking about these facilities, the term ``parenthesis'' also +includes braces, brackets, or whatever delimiters are defined to match +in pairs. The major mode controls which delimiters are significant, +through the syntax table (@pxref{Syntax}). In Lisp, only parentheses +count; in C, these commands apply to braces and brackets too. + + You can use @kbd{M-x check-parens} to find any unbalanced +parentheses and unbalanced string quotes in the buffer. + +@menu +* Expressions:: Expressions with balanced parentheses. +* Moving by Parens:: Commands for moving up, down and across + in the structure of parentheses. +* Matching:: Insertion of a close-delimiter flashes matching open. +@end menu + +@node Expressions +@subsection Expressions with Balanced Parentheses + +@cindex sexp +@cindex expression +@cindex balanced expression + These commands deal with balanced expressions, also called +@dfn{sexps}@footnote{The word ``sexp'' is used to refer to an +expression in Lisp.}. + +@table @kbd +@item C-M-f +Move forward over a balanced expression (@code{forward-sexp}). +@item C-M-b +Move backward over a balanced expression (@code{backward-sexp}). +@item C-M-k +Kill balanced expression forward (@code{kill-sexp}). +@item C-M-t +Transpose expressions (@code{transpose-sexps}). +@item C-M-@@ +@itemx C-M-@key{SPC} +Put mark after following expression (@code{mark-sexp}). +@end table + + Each programming language major mode customizes the definition of +balanced expressions to suit that language. Balanced expressions +typically include symbols, numbers, and string constants, as well as +any pair of matching delimiters and their contents. Some languages +have obscure forms of expression syntax that nobody has bothered to +implement in Emacs. + +@cindex Control-Meta + By convention, the keys for these commands are all Control-Meta +characters. They usually act on expressions just as the corresponding +Meta characters act on words. For instance, the command @kbd{C-M-b} +moves backward over a balanced expression, just as @kbd{M-b} moves +back over a word. + +@kindex C-M-f +@kindex C-M-b +@findex forward-sexp +@findex backward-sexp + To move forward over a balanced expression, 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 +balanced expression. The detailed rules are like those above for +@kbd{C-M-f}, but with directions reversed. If there are prefix +characters (single-quote, backquote and comma, in Lisp) preceding the +expression, @kbd{C-M-b} moves back over them as well. The balanced +expression 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. + +@cindex killing expressions +@kindex C-M-k +@findex kill-sexp + Killing a whole balanced expression can be done with @kbd{C-M-k} +(@code{kill-sexp}). @kbd{C-M-k} kills the characters that @kbd{C-M-f} +would move over. + +@cindex transposition of expressions +@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 +balanced expression across the next one. An argument serves as a +repeat count, moving the previous expression over that many following +ones. A negative argument drags the previous balanced expression +backwards across those before it (thus canceling out the effect of +@kbd{C-M-t} with a positive argument). An argument of zero, rather +than doing nothing, transposes the balanced expressions ending at or +after point and the mark. + +@kindex C-M-@@ +@kindex C-M-@key{SPC} +@findex mark-sexp + To set the region around the next balanced expression 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 balanced expression. The +alias @kbd{C-M-@key{SPC}} is equivalent to @kbd{C-M-@@}. When you +repeat this command, or use it in Transient Mark mode when the mark is +active, it extends the end of the region by one sexp each time. + + In languages that use infix operators, such as C, it is not possible +to recognize all balanced expressions as such because there can be +multiple possibilities at a given position. For example, C mode does +not treat @samp{foo + bar} as a single expression, even though it +@emph{is} one C expression; instead, it recognizes @samp{foo} as one +expression and @samp{bar} as another, with the @samp{+} as punctuation +between them. Both @samp{foo + bar} and @samp{foo} are legitimate +choices for ``the expression following point'' when point is at the +@samp{f}, so the expression commands must perforce choose one or the +other to operate on. Note that @samp{(foo + bar)} is recognized as a +single expression in C mode, because of the parentheses. + +@node Moving by Parens +@subsection Moving in the Parenthesis Structure + +@cindex parenthetical groupings +@cindex parentheses, moving across +@cindex matching parenthesis and braces, moving to +@cindex braces, moving across +@cindex list commands + The Emacs commands for handling parenthetical groupings see nothing +except parentheses (or whatever characters must balance in the +language you are working with), and the escape characters that might +be used to quote those. They are mainly intended for editing +programs, but can be useful for editing any text that has parentheses. +They are sometimes called ``list'' commands because in Lisp these +groupings are lists. + +@table @kbd +@item C-M-n +Move forward over a parenthetical group (@code{forward-list}). +@item C-M-p +Move backward over a parenthetical group (@code{backward-list}). +@item C-M-u +Move up in parenthesis structure (@code{backward-up-list}). +@item C-M-d +Move down in parenthesis structure (@code{down-list}). +@end table + +@kindex C-M-n +@kindex C-M-p +@findex forward-list +@findex backward-list + The ``list'' commands @kbd{C-M-n} (@code{forward-list}) and +@kbd{C-M-p} (@code{backward-list}) move over one (or @var{n}) +parenthetical groupings, skipping blithely over any amount of text +that doesn't include meaningful parentheses (symbols, strings, etc.). + +@kindex C-M-u +@findex backward-up-list + @kbd{C-M-n} and @kbd{C-M-p} try to stay at the same level in the +parenthesis structure. 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 the direction of motion, so +that the command moves forward and up one or more levels. + +@kindex C-M-d +@findex down-list + To move @emph{down} in the parenthesis 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 to go down. + +@node Matching +@subsection Automatic Display Of Matching Parentheses +@cindex matching parentheses +@cindex parentheses, displaying matches + + The Emacs parenthesis-matching feature is designed to show +automatically how parentheses (and other matching delimiters) 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, Emacs displays some of the text near it in the echo +area. Either way, you can tell which grouping you are closing off. + + If the opening delimiter and closing delimiter are mismatched---such +as in @samp{[x)}---a warning message is displayed in the echo area. + +@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} +disables it, but the default is @code{t} to enable match display. + + @code{blink-matching-delay} says how many seconds to leave the +cursor on the matching opening delimiter, before bringing it back to +the real location of point; 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 distance, scanning stops, and nothing is displayed. +This is to prevent the scan for the matching delimiter from wasting +lots of time when there is no match. The default is 25600. + +@cindex Show Paren mode +@cindex highlighting matching parentheses +@findex show-paren-mode + Show Paren mode provides a more powerful kind of automatic matching. +Whenever point is after a closing delimiter, that delimiter and its +matching opening delimiter are both highlighted; otherwise, if point +is before an opening delimiter, the matching closing delimiter is +highlighted. (There is no need to highlight the opening delimiter in +that case, because the cursor appears on top of that character.) Use +the command @kbd{M-x show-paren-mode} to enable or disable this mode. + + Show Paren mode uses the faces @code{show-paren-match} and +@code{show-paren-mismatch} to highlight parentheses; you can customize +them to control how highlighting looks. @xref{Face Customization}. + +@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. It can +also do spell checking on comments with Flyspell Prog mode +(@pxref{Spelling}). + +@menu +* Comment Commands:: Inserting, killing, and aligning comments. +* Multi-Line Comments:: Commands for adding and editing multi-line comments. +* Options for Comments::Customizing the comment features. +@end menu + +@node Comment Commands +@subsection Comment Commands +@cindex indentation for comments +@cindex alignment for comments + + The comment commands in this table insert, kill and align comments. +They are described in this section and following sections. + +@table @asis +@item @kbd{M-;} +Insert or realign comment on current line; alternatively, comment or +uncomment the region (@code{comment-dwim}). +@item @kbd{C-u M-;} +Kill comment on current line (@code{comment-kill}). +@item @kbd{C-x ;} +Set comment column (@code{comment-set-column}). +@item @kbd{C-M-j} +@itemx @kbd{M-j} +Like @key{RET} followed by inserting and aligning a comment +(@code{comment-indent-new-line}). @xref{Multi-Line Comments}. +@item @kbd{M-x comment-region} +@itemx @kbd{C-c C-c} (in C-like modes) +Add or remove comment delimiters on all the lines in the region. +@end table + +@kindex M-; +@findex comment-dwim + The command to create or align a comment is @kbd{M-;} +(@code{comment-dwim}). The word ``dwim'' is an acronym for ``Do What +I Mean''; it indicates that this command can be used for many +different jobs relating to comments, depending on the situation where +you use it. + + If there is no comment already on the line, @kbd{M-;} inserts a new +comment, aligned at a specific column called the @dfn{comment column}. +The new comment begins with the string Emacs thinks comments should +start with (the value of @code{comment-start}; see below). Point is +after that string, so you can insert the text of the comment right +away. If the major mode has specified a string to terminate comments, +@kbd{M-;} inserts that after point, to keep the syntax valid. + + If the text of the line extends past the comment column, this +command aligns the comment start string to a suitable boundary +(usually, at least one space is inserted). + + You can also use @kbd{M-;} to align an existing comment. If a line +already contains the comment-start string, @kbd{M-;} realigns it to +the conventional alignment and moves point after it. (Exception: +comments starting in column 0 are not moved.) Even when an existing +comment is properly aligned, @kbd{M-;} is still useful for moving +directly to the start of the text inside the comment. + +@findex comment-kill +@kindex C-u M-; + @kbd{C-u M-;} kills any comment on the current line, along with the +whitespace before it. 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 M-;} is not a distinct key; it is @kbd{M-;} +(@code{comment-dwim}) with a prefix argument. That command is +programmed so that when it receives a prefix argument it calls +@code{comment-kill}. However, @code{comment-kill} is a valid command +in its own right, and you can bind it directly to a key if you wish. + + @kbd{M-;} does two other jobs when used with an active region in +Transient Mark mode (@pxref{Transient Mark}). Then it either adds or +removes comment delimiters on each line of the region. (If every line +is a comment, it removes comment delimiters from each; otherwise, it +adds comment delimiters to each.) If you are not using Transient Mark +mode, then you should use the commands @code{comment-region} and +@code{uncomment-region} to do these jobs (@pxref{Multi-Line Comments}), +or else enable Transient Mark mode momentarily (@pxref{Momentary Mark}). +A prefix argument used in these circumstances specifies how many +comment delimiters to add or how many to delete. + + Some major modes have special rules for aligning 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 and are often used +for sectioning purposes. 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 + + For C-like modes, you can configure the exact effect of @kbd{M-;} +more flexibly than for most buffers by setting the variables +@code{c-indent-comment-alist} and +@code{c-indent-comments-syntactically-p}. For example, on a line +ending in a closing brace, @kbd{M-;} puts the comment one space after +the brace rather than at @code{comment-column}. For full details see +@ref{Comment Commands,,, ccmode, The CC Mode Manual}. + +@node Multi-Line Comments +@subsection Multiple Lines of Comments + +@kindex C-M-j +@kindex M-j +@cindex blank lines in programs +@findex comment-indent-new-line + + If you are typing a comment and wish to continue it on another line, +you can use the command @kbd{C-M-j} or @kbd{M-j} +(@code{comment-indent-new-line}). If @code{comment-multi-line} +(@pxref{Options for Comments}) is non-@code{nil}, it moves to a new +line within the comment. Otherwise it closes the comment and starts a +new comment on a new line. 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. + +@kindex C-c C-c (C mode) +@findex comment-region + To turn existing lines into comment lines, use the @kbd{M-x +comment-region} command (or type @kbd{C-c C-c} in C-like modes). 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 aligned or indented. +In Lisp, for proper indentation, you should use an argument of two or +three, if between defuns; if within a defun, it must be three. + + You can configure C Mode such that when you type a @samp{/} at the +start of a line in a multi-line block comment, this closes the +comment. Enable the @code{comment-close-slash} clean-up for this. +@xref{Clean-ups,,, ccmode, The CC Mode Manual}. + +@node Options for Comments +@subsection Options Controlling Comments + +@vindex comment-column +@kindex C-x ; +@findex comment-set-column + The @dfn{comment column}, the column at which Emacs tries to place +comments, is stored in the variable @code{comment-column}. You can +set it to a number explicitly. Alternatively, the command @kbd{C-x ;} +(@code{comment-set-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. + + 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 +@c This stops M-q from breaking the line inside that @code. +@code{@w{"/\\*+ *\\|//+ *"}}, which matches extra stars and spaces +after the @samp{/*} itself, and accepts C++ style comments also. +(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{Regexp Backslash}.) + +@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. When @code{comment-end} is non-empty, it +should start with a space. For example, in C mode, +@code{comment-start} has the value @w{@code{"/* "}} and +@code{comment-end} has the value @w{@code{" */"}}. + +@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, to insert +one space. @code{nil} means 0. Alternatively, @code{comment-padding} +can hold the actual string to insert. + +@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. +Specifically, when @code{comment-multi-line} is @code{nil}, the +command inserts a comment terminator, begins a new line, and finally +inserts a comment starter. Otherwise it does not insert the +terminator and starter, so it effectively continues the current +comment across multiple lines. In languages that allow multi-line +comments, the choice of value for this variable is a matter of taste. +The default for this variable depends on the major mode. + +@vindex comment-indent-function + The variable @code{comment-indent-function} should contain a function +that will be called to compute the alignment 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 Documentation +@section Documentation Lookup + + Emacs provides several features you can use to look up the +documentation of functions, variables and commands that you plan to +use in your program. + +@menu +* Info Lookup:: Looking up library functions and commands + in Info files. +* Man Page:: Looking up man pages of library functions and commands. +* Lisp Doc:: Looking up Emacs Lisp functions, etc. +@end menu + +@node Info Lookup +@subsection Info Documentation Lookup + +@findex info-lookup-symbol +@findex info-lookup-file +@kindex C-h S + For many major modes, that apply to languages that have +documentation in Info, you can use @kbd{C-h S} +(@code{info-lookup-symbol}) to view the Info documentation for a +symbol used in the program. You specify the symbol with the +minibuffer; the default is the symbol appearing in the buffer at +point. For example, in C mode this looks for the symbol in the C +Library Manual. The command only works if the appropriate manual's +Info files are installed. + + The major mode determines where to look for documentation for the +symbol---which Info files to look in, and which indices to search. +You can also use @kbd{M-x info-lookup-file} to look for documentation +for a file name. + + If you use @kbd{C-h S} in a major mode that does not support it, +it asks you to specify the ``symbol help mode.'' You should enter +a command such as @code{c-mode} that would select a major +mode which @kbd{C-h S} does support. + +@node Man Page +@subsection Man Page Lookup + +@cindex manual page + On Unix, the main form of on-line documentation was the @dfn{manual +page} or @dfn{man page}. In the GNU operating system, we aim to +replace man pages with better-organized manuals that you can browse +with Info (@pxref{Misc Help}). This process is not finished, so it is +still useful to read manual pages. + +@findex manual-entry + You can read the man page for an operating system command, library +function, or system call, with the @kbd{M-x man} command. It +runs the @code{man} program to format the man page; if the system +permits, it runs @code{man} asynchronously, so that you can keep on +editing while the page is being formatted. (On MS-DOS and MS-Windows +3, you cannot edit while Emacs waits for @code{man} to finish.) The +result goes in a buffer named @samp{*Man @var{topic}*}. These buffers +use a special major mode, Man mode, that facilitates scrolling and +jumping to other manual pages. For details, type @kbd{C-h m} while in +a man page buffer. + +@cindex sections of manual pages + Each man page belongs to one of ten or more @dfn{sections}, each +named by a digit or by a digit and a letter. Sometimes there are +multiple man pages with the same name in different sections. To read +a man page from a specific section, type +@samp{@var{topic}(@var{section})} or @samp{@var{section} @var{topic}} +when @kbd{M-x manual-entry} prompts for the topic. For example, to +read the man page for the C library function @code{chmod} (as opposed +to a command of the same name), type @kbd{M-x manual-entry @key{RET} +chmod(2) @key{RET}}. (@code{chmod} is a system call, so it is in +section @samp{2}.) + +@vindex Man-switches + If you do not specify a section, the results depend on how the +@code{man} program works on your system. Some of them display only +the first man page they find. Others display all man pages that have +the specified name, so you can move between them with the @kbd{M-n} +and @kbd{M-p} keys@footnote{On some systems, the @code{man} program +accepts a @samp{-a} command-line option which tells it to display all +the man pages for the specified topic. If you want this behavior, you +can add this option to the value of the variable @code{Man-switches}.}. +The mode line shows how many manual pages are present in the Man buffer. + +@vindex Man-fontify-manpage-flag + By default, Emacs highlights the text in man pages. For a long man +page, highlighting can take substantial time. You can turn off +highlighting of 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. + +@findex woman +@cindex manual pages, on MS-DOS/MS-Windows + An alternative way of reading manual pages is the @kbd{M-x woman} +command@footnote{The name of the command, @code{woman}, is an acronym +for ``w/o (without) man,'' since it doesn't use the @code{man} +program.}. Unlike @kbd{M-x man}, it does not run any external +programs to format and display the man pages; instead it does the job +in Emacs Lisp, so it works on systems such as MS-Windows, where the +@code{man} program (and other programs it uses) are not generally +available. + + @kbd{M-x woman} prompts for a name of a manual page, and provides +completion based on the list of manual pages that are installed on +your machine; the list of available manual pages is computed +automatically the first time you invoke @code{woman}. The word at +point in the current buffer is used to suggest the default for the +name the manual page. + + With a numeric argument, @kbd{M-x woman} recomputes the list of the +manual pages used for completion. This is useful if you add or delete +manual pages. + + If you type a name of a manual page and @kbd{M-x woman} finds that +several manual pages by the same name exist in different sections, it +pops up a window with possible candidates asking you to choose one of +them. + + For more information about setting up and using @kbd{M-x woman}, see +@ref{Top, WoMan, Browse UN*X Manual Pages WithOut Man, woman, The WoMan +Manual}. + +@node Lisp Doc +@subsection Emacs Lisp Documentation Lookup + + As you edit Lisp code to be run in Emacs, you can use the commands +@kbd{C-h f} (@code{describe-function}) and @kbd{C-h v} +(@code{describe-variable}) to view documentation of functions and +variables that you want to use. These commands use the minibuffer to +read the name of a function or variable to document, and display the +documentation in a window. Their default arguments are based on the +code in the neighborhood of point. For @kbd{C-h f}, the default is +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 + A more automatic but less powerful method is 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.) If point is over a documented variable, it +shows the first line of the variable's docstring. Eldoc mode applies +in Emacs Lisp and Lisp Interaction modes, and perhaps a few others +that provide special support for looking up doc strings. Use the +command @kbd{M-x eldoc-mode} to enable or disable this feature. + +@node Hideshow +@section Hideshow minor mode + +@findex hs-minor-mode + Hideshow minor mode provides selective display of portions of a +program, known as @dfn{blocks}. You can use @kbd{M-x hs-minor-mode} +to enable or disable this mode, or add @code{hs-minor-mode} to the +mode hook for certain major modes in order to enable it automatically +for those modes. + + Just what constitutes a block depends on the major mode. In C mode +or C++ mode, they are delimited by braces, while in Lisp mode and +similar modes they are delimited by parentheses. Multi-line comments +also count as blocks. + +@findex hs-hide-all +@findex hs-hide-block +@findex hs-show-all +@findex hs-show-block +@findex hs-show-region +@findex hs-hide-level +@findex hs-minor-mode +@kindex C-c @@ C-h +@kindex C-c @@ C-s +@kindex C-c @@ C-M-h +@kindex C-c @@ C-M-s +@kindex C-c @@ C-r +@kindex C-c @@ C-l +@kindex S-Mouse-2 +@table @kbd +@item C-c @@ C-h +Hide the current block (@code{hs-hide-block}). +@item C-c @@ C-s +Show the current block (@code{hs-show-block}). +@item C-c @@ C-c +Either hide or show the current block (@code{hs-toggle-hiding}). +@item S-Mouse-2 +Either hide or show the block you click on (@code{hs-mouse-toggle-hiding}). +@item C-c @@ C-M-h +Hide all top-level blocks (@code{hs-hide-all}). +@item C-c @@ C-M-s +Show everything in the buffer (@code{hs-show-all}). +@item C-c @@ C-l +Hide all blocks @var{n} levels below this block +(@code{hs-hide-level}). +@end table + +@vindex hs-hide-comments-when-hiding-all +@vindex hs-isearch-open +@vindex hs-special-modes-alist + These variables exist for customizing Hideshow mode. + +@table @code +@item hs-hide-comments-when-hiding-all +Non-@code{nil} says that @kbd{hs-hide-all} should hide comments too. + +@item hs-isearch-open +Specifies what kind of hidden blocks incremental search should make +visible. The value should be one of these four symbols: + +@table @code +@item code +Open only code blocks. +@item comment +Open only comments. +@item t +Open both code blocks and comments. +@item nil +Open neither code blocks nor comments. +@end table + +@item hs-special-modes-alist +A list of elements, each specifying how to initialize Hideshow +variables for one major mode. See the variable's documentation string +for more information. +@end table + +@node Symbol Completion +@section Completion for Symbol Names +@cindex completion (symbol names) + + In Emacs, completion is something you normally do 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. This command inserts at point any additional characters that +it can determine from the partial name. + + If your window manager defines @kbd{M-@key{TAB}} to switch windows, +you can type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i} instead. +However, most window managers let you customize these shortcuts, and +we recommend that you change any that get in the way of use of Emacs. + + If the partial name in the buffer has multiple possible completions +that differ in the very next character, so that it is impossible to +complete even one more character, @kbd{M-@key{TAB}} displays a list of +all possible completions in another window. + +@cindex tags-based 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 (Lisp symbols) +@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 Glasses +@section Glasses minor mode +@cindex Glasses mode +@cindex identifiers, making long ones readable +@cindex StudlyCaps, making them readable +@findex glasses-mode + + Glasses minor mode makes @samp{unreadableIdentifiersLikeThis} +readable by altering the way they display. It knows two different +ways to do this: by displaying underscores between a lower-case letter +and the following capital letter, and by emboldening the capital +letters. It does not alter the buffer text, only the way they +display, so you can use it even on read-only buffers. You can use the +command @kbd{M-x glasses-mode} to enable or disable the mode in the +current buffer; you can also add @code{glasses-mode} to the mode hook +of the programming language major modes in which you normally want +to use Glasses mode. + +@node Misc for Programs +@section Other Features Useful for Editing Programs + + A number of Emacs commands that aren't designed specifically for +editing programs are useful for that nonetheless. + + The Emacs commands that operate on words, sentences and paragraphs +are useful for editing code. Most symbols names contain words +(@pxref{Words}); sentences can be found in strings and comments +(@pxref{Sentences}). Paragraphs in the strict sense can be found in +program code (in long comments), but the paragraph commands are useful +in other places too, 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. +Auto Fill mode, if enabled in a programming language major mode, +indents the new lines which it creates. + + The selective display feature is useful for looking at the overall +structure of a function (@pxref{Selective Display}). This feature +hides the lines that are indented more than a specified amount. +Programming modes often support Outline minor mode (@pxref{Outline +Mode}). The Foldout package provides folding-editor features +(@pxref{Foldout}). + + The ``automatic typing'' features may be useful for writing programs. +@xref{Top,,Autotyping, autotype, Autotyping}. + +@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 AWK mode +@cindex mode, Java +@cindex mode, C +@cindex mode, C++ +@cindex mode, Objective C +@cindex mode, CORBA IDL +@cindex mode, Pike +@cindex mode, AWK + + This section gives a brief description of the special features +available in C, C++, Objective-C, Java, CORBA IDL, Pike and AWK modes. +(These are called ``C mode and related modes.'') @xref{Top, , CC Mode, +ccmode, CC Mode}, for a more extensive description of these modes +and their special features. + +@menu +* Motion in C:: Commands to move by C statements, etc. +* Electric C:: Colon and other chars can automatically reindent. +* Hungry Delete:: A more powerful DEL command. +* Other C Commands:: Filling comments, viewing expansion of macros, + and other neat features. +@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 M-x c-beginning-of-defun +@itemx M-x c-end-of-defun +@findex c-beginning-of-defun +@findex c-end-of-defun +Move point to the beginning or end of the current function or +top-level definition. These are found by searching for the least +enclosing braces. (By contrast, @code{beginning-of-defun} and +@code{end-of-defun} search for braces in column zero.) If you are +editing code where the opening brace of a function isn't placed in +column zero, you may wish to bind @code{C-M-a} and @code{C-M-e} to +these commands. @xref{Moving by Defuns}. + +@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. + +@samp{#elif} is equivalent to @samp{#else} followed by @samp{#if}, so +the function will stop at a @samp{#elif} when going backward, but not +when going forward. + +@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 M-a (C mode) +@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. + +In comments or in strings which span more than one line, this command +moves by sentences instead of statements. + +@item M-e +@kindex M-e (C mode) +@findex c-end-of-statement +Move point to the end of the innermost C statement or sentence; like +@kbd{M-a} except that it moves in the other direction +(@code{c-end-of-statement}). +@end table + +@node Electric C +@subsection Electric C Characters + + In C mode and related modes, certain printing characters are +@dfn{electric}---in addition to inserting themselves, they also +reindent the current line, and optionally also insert newlines. The +``electric'' characters are @kbd{@{}, @kbd{@}}, @kbd{:}, @kbd{#}, +@kbd{;}, @kbd{,}, @kbd{<}, @kbd{>}, @kbd{/}, @kbd{*}, @kbd{(}, and +@kbd{)}. + + You might find electric indentation inconvenient if you are editing +chaotically indented code. If you are new to CC Mode, you might find +it disconcerting. You can toggle electric action with the command +@kbd{C-c C-l}; when it is enabled, @samp{/l} appears in the mode line +after the mode name: + +@table @kbd +@item C-c C-l +@kindex C-c C-l @r{(C mode)} +@findex c-toggle-electric-state +Toggle electric action (@code{c-toggle-electric-state}). With a +prefix argument, this command enables electric action if the argument +is positive, disables it if it is negative. +@end table + + Electric characters insert newlines only when, in addition to the +electric state, the @dfn{auto-newline} feature is enabled (indicated +by @samp{/la} in the mode line after the mode name). 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-newline +Toggle the auto-newline feature (@code{c-toggle-auto-newline}). 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 + + Usually the CC Mode style configures the exact circumstances in +which Emacs inserts auto-newlines. You can also configure this +directly. @xref{Custom Auto-newlines,,, ccmode, The CC Mode Manual}. + +@node Hungry Delete +@subsection Hungry Delete Feature in C +@cindex hungry deletion (C Mode) + + If you want to delete an entire block of whitespace at point, you +can use @dfn{hungry deletion}. This deletes all the contiguous +whitespace either before point or after point in a single operation. +@dfn{Whitespace} here includes tabs and newlines, but not comments or +preprocessor commands. + +@table @kbd +@item C-c C-@key{DEL} +@itemx C-c @key{DEL} +@findex c-hungry-delete-backwards +@kindex C-c C-@key{DEL} (C Mode) +@kindex C-c @key{DEL} (C Mode) +@code{c-hungry-delete-backwards}---Delete the entire block of whitespace +preceding point. + +@item C-c C-d +@itemx C-c C-@key{DELETE} +@itemx C-c @key{DELETE} +@findex c-hungry-delete-forward +@kindex C-c C-d (C Mode) +@kindex C-c C-@key{DELETE} (C Mode) +@kindex C-c @key{DELETE} (C Mode) +@code{c-hungry-delete-forward}---Delete the entire block of whitespace +following point. +@end table + + As an alternative to the above commands, you can enable @dfn{hungry +delete mode}. When this feature is enabled (indicated by @samp{/h} in +the mode line after the mode name), a single @key{DEL} deletes all +preceding whitespace, not just one space, and a single @kbd{C-c C-d} +(but @emph{not} plain @key{DELETE}) deletes all following whitespace. + +@table @kbd +@item M-x c-toggle-hungry-state +@findex c-toggle-hungry-state +Toggle the hungry-delete feature +(@code{c-toggle-hungry-state})@footnote{This command had the binding +@kbd{C-c C-d} in earlier versions of Emacs. @kbd{C-c C-d} is now +bound to @code{c-hungry-delete-forward}.}. With a prefix argument, +this command turns the hungry-delete feature on if the argument is +positive, and off if it is negative. +@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-c C-w +@itemx M-x c-subword-mode +@findex c-subword-mode +Enable (or disable) @dfn{subword mode}. In subword mode, Emacs's word +commands recognize upper case letters in +@samp{StudlyCapsIdentifiers} as word boundaries. This is indicated by +the flag @samp{/w} on the mode line after the mode name +(e.g. @samp{C/law}). You can even use @kbd{M-x c-subword-mode} in +non-CC Mode buffers. + +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-context-line-break +@findex c-context-line-break +This command inserts a line break and indents the new line in a manner +appropriate to the context. In normal code, it does the work of +@kbd{C-j} (@code{newline-and-indent}), in a C preprocessor line it +additionally inserts a @samp{\} at the line break, and within comments +it's like @kbd{M-j} (@code{c-indent-new-comment-line}). + +@code{c-context-line-break} isn't bound to a key by default, but it +needs a binding to be useful. The following code will bind it to +@kbd{C-j}. We use @code{c-initialization-hook} here to make sure +the keymap is loaded before we try to change it. + +@smallexample +(defun my-bind-clb () + (define-key c-mode-base-map "\C-j" 'c-context-line-break)) +(add-hook 'c-initialization-hook 'my-bind-clb) +@end smallexample + +@item C-M-h +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 information directs how +the line is indented. + +@item M-x cwarn-mode +@itemx M-x global-cwarn-mode +@findex cwarn-mode +@findex global-cwarn-mode +@vindex global-cwarn-mode +@cindex CWarn mode +@cindex suspicious constructions in C, C++ +CWarn minor mode highlights certain suspicious C and C++ constructions: + +@itemize @bullet{} +@item +Assignments inside expressions. +@item +Semicolon following immediately after @samp{if}, @samp{for}, and @samp{while} +(except after a @samp{do @dots{} while} statement); +@item +C++ functions with reference parameters. +@end itemize + +@noindent +You can enable the mode for one buffer with the command @kbd{M-x +cwarn-mode}, or for all suitable buffers with the command @kbd{M-x +global-cwarn-mode} or by customizing the variable +@code{global-cwarn-mode}. You must also enable Font Lock mode to make +it work. + +@item M-x hide-ifdef-mode +@findex hide-ifdef-mode +@cindex Hide-ifdef mode +Hide-ifdef minor mode hides selected code within @samp{#if} and +@samp{#ifdef} preprocessor blocks. See the documentation string of +@code{hide-ifdef-mode} for more information. + +@item M-x ff-find-related-file +@cindex related files +@findex ff-find-related-file +@vindex ff-related-file-alist +Find a file ``related'' in a special way to the file visited by the +current buffer. Typically this will be the header file corresponding +to a C/C++ source file, or vice versa. The variable +@code{ff-related-file-alist} specifies how to compute related file +names. +@end table + +@node Asm Mode +@section Asm Mode + +@cindex Asm mode +@cindex assembler 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. + +@ifnottex +@include fortran-xtra.texi +@end ifnottex + +@ignore + arch-tag: c7ee7409-40a4-45c7-bfb7-ae7f2c74d0c0 +@end ignore diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi new file mode 100644 index 00000000000..475a3b7b1b5 --- /dev/null +++ b/doc/emacs/regs.texi @@ -0,0 +1,330 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, +@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Registers, Display, CUA Bindings, Top +@chapter Registers +@cindex registers + + Emacs @dfn{registers} are compartments where you can save text, +rectangles, positions, and other things 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 consists of a single character. A +register can store a number, 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 + + @dfn{Bookmarks} record files and positions in them, so you can +return to those positions when you look at the file again. +Bookmarks are similar enough in spirit to registers that they +seem to belong in this chapter. + +@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. +* Numbers: RegNumbers. Numbers in registers. +* Files: RegFiles. File names in registers. +* Bookmarks:: Bookmarks are like registers, but persistent. +@end menu + +@node RegPos +@section Saving Positions in Registers +@cindex saving position in a register + + 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 +hold 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 +@cindex saving text in a register + + 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}). +@item M-x append-to-register @key{RET} @var{r} +Append region to text in register @var{r}. +@item M-x prepend-to-register @key{RET} @var{r} +Prepend region to text in register @var{r}. +@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}. @kbd{C-u C-x r s @var{r}}, the same +command with a numeric argument, deletes the text from the buffer as +well; you can think of this as ``moving'' the region text into the register. + +@findex append-to-register +@findex prepend-to-register + @kbd{M-x append-to-register @key{RET} @var{r}} appends the copy of +the text in the region to the text already stored in the register +named @var{r}. If invoked with a numeric argument, it deletes the +region after appending it to the register. The command +@code{prepend-to-register} is similar, except that it @emph{prepends} +the region text to the text in the register, rather than +@emph{appending} it. + + @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 +@cindex saving rectangle in a register + + 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 +@cindex saving window configuration in a register + +@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 +@cindex saving number in a register + + 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{r} +@kindex C-x r n +@findex number-to-register +Store @var{number} into register @var{r} (@code{number-to-register}). +@item C-u @var{number} C-x r + @var{r} +@kindex C-x r + +@findex increment-register +Increment the number in register @var{r} by @var{number} +(@code{increment-register}). +@item C-x r i @var{r} +Insert the number from register @var{r} into the buffer. +@end table + + @kbd{C-x r i} is the same command used to insert any other sort of +register contents into the buffer. @kbd{C-x r +} with no numeric +argument increments the register value by 1; @kbd{C-x r n} with no +numeric argument stores zero in the register. + +@node RegFiles +@section Keeping File Names in Registers +@cindex saving file name in a register + + 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 the bookmark 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 + +@ignore + arch-tag: b00af991-ebc3-4b3a-8e82-a3ac81ff2e64 +@end ignore diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi new file mode 100644 index 00000000000..7c36a31ff18 --- /dev/null +++ b/doc/emacs/rmail.texi @@ -0,0 +1,1430 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, +@c 2003, 2004, 2005, 2006, 2007 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 +which use a special format. 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. +@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. +* Coding: Rmail Coding. How Rmail handles decoding character sets. +* 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:: More details of fetching new mail. +* Remote Mailboxes:: Retrieving Mail from Remote Mailboxes. +* Other Mailbox Formats:: Retrieving Mail from Local Mailboxes in + Various Formats +@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 +identified by consecutive integers which are 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-expunge-and-save + Following the usual conventions of Emacs, changes in an Rmail file +become permanent only when you save the file. You can save it with +@kbd{s} (@code{rmail-expunge-and-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, then buries the Rmail buffer as well as its +summary buffer, if present (@pxref{Rmail Summary}). But there is no +need to ``exit'' formally. If you switch from Rmail to editing in +other buffers, and never switch back, you have exited. Just make sure +to save the Rmail file eventually (like any other file you have +changed). @kbd{C-x s} is a suitable way to do this (@pxref{Save +Commands}). The Rmail command @kbd{b}, @code{rmail-bury}, buries the +Rmail buffer and its summary buffer without expunging and saving the +Rmail file. + +@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. + +@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}). +@item / +Scroll to end of message (@code{rmail-end-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)} +@kindex / @r{(Rmail)} +@findex rmail-beginning-of-message +@findex rmail-end-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. Similarly, +the command @kbd{/} (@code{rmail-end-of-message}) scrolls forward to the end +of the selected message. + +@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 re-examine 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. + + 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. @kbd{d} with a numeric argument is +equivalent to @kbd{C-d}. + +@vindex rmail-delete-message-hook + Whenever Rmail deletes a message, it runs the hook +@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 + + When you receive mail locally, 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 local 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 @env{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 @env{MAIL} +environment variable, or, as a last resort, set to @code{nil}, which +means to use the default inbox. The default inbox file depends on +your operating system; often it is @file{/var/mail/@var{username}}, +@file{/usr/spool/mail/@var{username}}, or +@file{/usr/mail/@var{username}}. + + 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 when their format is the same. + +@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 +clears out 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 does not clear out the inbox file when it gets new mail. 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. + + 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. + +@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 can 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, but it is easier to type @kbd{C-u M-x rmail}, which does the +same thing. + + 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. In 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 you specify a list of inboxes in an Rmail file, +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 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. + + 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. +In 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 with @kbd{o} or @kbd{C-o} 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. @kbd{w} +gives it the @samp{stored} attribute. 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}, +@kbd{C-o} and @kbd{w} 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}. +@ifnottex +(@xref{Rmail Attributes}.) +@end ifnottex +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 l @var{labels} @key{RET} +@itemx 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. + + 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 Rmail assigns them to 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 +@kbd{o} and @kbd{C-o} file output commands (@pxref{Rmail Output}). +@item stored +Assigned by the @kbd{w} file output command (@pxref{Rmail Output}). +@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 users, 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}---also work normally in Rmail mode. + +@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}, @samp{In-reply-to} and +@samp{References} 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}. +This means to reply only to the sender of the original message. + + 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 what you want. 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 +also 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. + +@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. + +@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. + +@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{Cancel} 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 and date, the sender, the line count, the labels, and +the subject. Moving point in the summary buffer selects messages as +you move to their summary lines. Almost all Rmail commands are valid +in the summary buffer also; when used there, they apply to the message +described by the current line of the summary. + + 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}). +@item C-M-s @var{regexp} +Summarize messages whose headers and the subject line match the +specified regular expression @var{regexp} +(@code{rmail-summary-by-regexp}). +@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. + +@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. + +@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}. + +@kindex C-M-s @r{(Rmail)} +@findex rmail-summary-by-regexp + @kbd{C-M-s @var{regexp} @key{RET}} (@code{rmail-summary-by-regexp}) +makes a partial summary which mentions only the messages whose headers +(including the date and the subject lines) match the regular +expression @var{regexp}. + + Note that there is only one summary buffer for any Rmail file; +making any kind of summary discards any previous 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. (However, in the +summary buffer, a numeric argument to @kbd{d}, @kbd{C-d} and @kbd{u} +serves as a repeat count. A negative argument reverses the meaning of +@kbd{d} and @kbd{C-d}.) @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 j +@itemx @key{RET} +Select the message on the current line (ensuring that the RMAIL buffer +appears on the screen). With argument @var{n}, select message number +@var{n} and move to its line in the summary buffer; this signals an +error if the message is not listed in the summary buffer. +@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 +@vindex rmail-nonignored-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. However, the variable +@code{rmail-nonignored-headers} provides a further override: a header +matching that regular expression is shown even if it matches +@code{rmail-ignored-headers} too. + +@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, which shows only the interesting headers according to the +current values of those variable. Selecting the message again also +reformats it if necessary. + + 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 the terminal supports multiple fonts or colors, 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 by setting the variable +@code{rmail-highlight-face} to a suitable face. To turn off +highlighting entirely in Rmail, set @code{rmail-highlighted-headers} +to @code{nil}. + + You can highlight and activate URLs in incoming messages by adding +the function @code{goto-address} to the hook +@code{rmail-show-message-hook}. Then you can browse these URLs by +clicking on them with @kbd{Mouse-2} (or @kbd{Mouse-1} quickly) or by +moving to one and typing @kbd{C-c @key{RET}}. @xref{Goto-address, +Activating URLs, Activating URLs}. + +@node Rmail Coding +@section Rmail and Coding Systems + +@cindex decoding mail messages (Rmail) + Rmail automatically decodes messages which contain non-@acronym{ASCII} +characters, just as Emacs does with files you visit and with subprocess +output. Rmail uses the standard @samp{charset=@var{charset}} header in +the message, if any, to determine how the message was encoded by the +sender. It maps @var{charset} into the corresponding Emacs coding +system (@pxref{Coding Systems}), and uses that coding system to decode +message text. If the message header doesn't have the @samp{charset} +specification, or if @var{charset} is not recognized, +Rmail chooses the coding system with the usual Emacs heuristics and +defaults (@pxref{Recognize Coding}). + +@cindex fixing incorrectly decoded mail messages + Occasionally, a message is decoded incorrectly, either because Emacs +guessed the wrong coding system in the absence of the @samp{charset} +specification, or because the specification was inaccurate. For +example, a misconfigured mailer could send a message with a +@samp{charset=iso-8859-1} header when the message is actually encoded +in @code{koi8-r}. When you see the message text garbled, or some of +its characters displayed as empty boxes, this may have happened. + +@findex rmail-redecode-body + You can correct the problem by decoding the message again using the +right coding system, if you can figure out or guess which one is +right. To do this, invoke the @kbd{M-x rmail-redecode-body} command. +It reads the name of a coding system, encodes the message body using +whichever coding system was used to decode it before, then redecodes +it using the coding system you specified. If you specified the right +coding system, the result should be readable. + + Decoding and encoding using the wrong coding system is lossless for +most encodings, in particular with 8-bit encodings such as iso-8859 or +koi8. So, if the initial attempt to redecode the message didn't +result in a legible text, you can try other coding systems until you +succeed. + + With some coding systems, notably those from the iso-2022 family, +information can be lost in decoding, so that encoding the message +again won't bring back the original incoming text. In such a case, +@code{rmail-redecode-body} cannot work. However, the problems that +call for use of @code{rmail-redecode-body} rarely occur with those +coding systems. So in practice the command works when you need it. + +@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 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 +@cindex Babyl format to Inbox format +@cindex converting Rmail file to mailbox format + +@findex unrmail + The command @kbd{M-x unrmail} converts a file in Rmail format to inbox +format (also known as the system mailbox, or mbox, 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. + +@pindex b2m + @kbd{M-x unrmail} is useful if you can run Emacs on the machine +where the Rmail file resides, or can access the Rmail file remotely +(@pxref{Remote Files}) from a machine where Emacs is installed. If +accessing Rmail files from Emacs is impossible, you can use the +@command{b2m} program instead. @command{b2m} is part of the Emacs +distribution, it is installed into the same directory where all the +other auxiliary programs (@command{etags} etc.) are installed, and its +source is available in the Emacs source distribution, so that you +could copy the source to the target machine and compile it there. + + To convert a file @file{@var{babyl-file}} into @file{@var{mbox-file}}, +invoke @command{b2m} like this: + +@example + b2m < @var{babyl-file} > @var{mbox-file} +@end example + +@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 +seeing the real text of the message. + +@findex rot13-other-window + To view a buffer which uses 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} program +@cindex @code{movemail} program + + When invoked for the first time, Rmail attempts to locate the +@code{movemail} program and determine its version. There are two +versions of @code{movemail} program: the native one, shipped with GNU +Emacs (the ``emacs version'') and the one included in GNU mailutils +(the ``mailutils version,'' @pxref{movemail,,,mailutils,GNU +mailutils}). They support the same command line syntax and the same +basic subset of options. However, the Mailutils version offers +additional features. + + The Emacs version of @code{movemail} is able to retrieve mail from +usual UNIX mailbox formats and from remote mailboxes using the POP3 +protocol. + + The Mailutils version is able to handle a wide set of mailbox +formats, such as plain UNIX mailboxes, @code{maildir} and @code{MH} +mailboxes, etc. It is able to retrieve remote mail using POP3 or +IMAP4 protocol, and can retrieve mail from them using a TLS encrypted +channel. It also accepts mailbox argument in the @acronym{URL} form. +The detailed description of mailbox @acronym{URL}s can be found in +@ref{URL,,,mailutils,Mailbox URL Formats}. In short, a @acronym{URL} +is: + +@smallexample +@var{proto}://[@var{user}[:@var{password}]@@]@var{host-or-file-name} +@end smallexample + +@noindent +where square brackets denote optional elements. + +@table @var +@item proto +Specifies the @dfn{mailbox protocol}, or @dfn{format} to +use. The exact semantics of the rest of @acronym{URL} elements depends +on the actual value of @var{proto} (see below). + +@item user +User name to access the remote mailbox. + +@item password +User password to access the remote mailbox. + +@item host-or-file-name +Hostname of the remote server for remote mailboxes or file name of a +local mailbox. +@end table + +@noindent +@var{Proto} can be one of: + +@table @code +@item mbox +Usual UNIX mailbox format. In this case, neither @var{user} nor +@var{pass} are used, and @var{host-or-file-name} denotes the file name of +the mailbox file, e.g., @code{mbox://var/spool/mail/smith}. + +@item mh +A local mailbox in the @acronym{MH} format. @var{User} and +@var{pass} are not used. @var{Host-or-file-name} denotes the name of +@acronym{MH} folder, e.g., @code{mh://Mail/inbox}. + +@item maildir +A local mailbox in the @acronym{maildir} format. @var{User} and +@var{pass} are not used, and @var{host-or-file-name} denotes the name of +@code{maildir} mailbox, e.g., @code{maildir://mail/inbox}. + +@item file +Any local mailbox format. Its actual format is detected automatically +by @code{movemail}. + +@item pop +A remote mailbox to be accessed via POP3 protocol. @var{User} +specifies the remote user name to use, @var{pass} may be used to +specify the user password, @var{host-or-file-name} is the name or IP +address of the remote mail server to connect to; e.g., +@code{pop://smith:guessme@@remote.server.net}. + +@item imap +A remote mailbox to be accessed via IMAP4 protocol. @var{User} +specifies the remote user name to use, @var{pass} may be used to +specify the user password, @var{host-or-file-name} is the name or IP +address of the remote mail server to connect to; +e.g., @code{imap://smith:guessme@@remote.server.net}. +@end table + + Alternatively, you can specify the file name of the mailbox to use. +This is equivalent to specifying the @samp{file} protocol: + +@smallexample +/var/spool/mail/@var{user} @equiv{} file://var/spool/mail/@var{user} +@end smallexample + +@vindex rmail-movemail-program +@vindex rmail-movemail-search-path + The variable @code{rmail-movemail-program} controls which version of +@code{movemail} to use. If that is a string, it specifies the +absolute file name of the @code{movemail} executable. If it is +@code{nil}, Rmail searches for @code{movemail} in the directories +listed in @code{rmail-movemail-search-path} and @code{exec-path}, then +in @code{exec-directory}. + +@node Remote Mailboxes +@section Retrieving Mail from Remote Mailboxes +@pindex movemail + + Some sites use a method called POP for accessing users' inbox data +instead of storing the data in inbox files. The @code{Emacs +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.) + +The Mailutils @code{movemail} by default supports POP, unless it was +configured with @samp{--disable-pop} option. + +Both versions of @code{movemail} only work with POP3, not with older +versions of POP. + +@cindex @env{MAILHOST} environment variable +@cindex POP mailboxes + No matter which flavor of @code{movemail} you use, you can specify +POP inbox by using POP @dfn{URL} (@pxref{Movemail}). A POP +@acronym{URL} is a ``file name'' of the form +@samp{pop://@var{username}@@@var{hostname}}, where +@var{hostname} is the host name or IP address of the remote mail +server and @var{username} is the user name on that server. +Additionally, you may specify the password in the mailbox @acronym{URL}: +@samp{pop://@var{username}:@var{password}@@@var{hostname}}. In this +case, @var{password} takes preference over the one set by +@code{rmail-remote-password}. This is especially useful if you have +several remote mailboxes with different passwords. + + For backward compatibility, Rmail also supports two alternative ways +of specifying remote POP mailboxes. First, specifying an inbox name +in the form @samp{po:@var{username}:@var{hostname}} is equivalent to +@samp{pop://@var{username}@@@var{hostname}}. Alternatively, you may +set a ``file name'' of @samp{po:@var{username}} in the inbox list of +an Rmail file. @code{movemail} will handle such a name by opening a +connection to the POP server. In this case, the @env{MAILHOST} +environment variable specifies the machine on which to look for the +POP server. + +@cindex IMAP mailboxes + Another method for accessing remote mailboxes is IMAP. This method is +supported only by the Mailutils @code{movemail}. To specify an IMAP +mailbox in the inbox list, use the following mailbox @acronym{URL}: +@samp{imap://@var{username}[:@var{password}]@@@var{hostname}}. The +@var{password} part is optional, as described above. + +@vindex rmail-remote-password +@vindex rmail-remote-password-required +@vindex rmail-pop-password +@vindex rmail-pop-password-required + Accessing a remote mailbox may require a password. Rmail uses the +following algorithm to retrieve it: + +@enumerate +@item +If the @var{password} is present in mailbox URL (see above), it is +used. +@item +If the variable @code{rmail-remote-password} is non-@code{nil}, its +value is used. +@item +Otherwise, if @code{rmail-remote-password-required} is non-@code{nil}, +then Rmail will ask you for the password to use. +@item +Otherwise, Rmail assumes no password is required. +@end enumerate + + For compatibility with previous versions, the variables +@code{rmail-pop-password} and @code{rmail-pop-password-required} may +be used instead of @code{rmail-remote-password} and +@code{rmail-remote-password-required}. + +@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 reverse order in POP inboxes + 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}. + +@cindex TLS encryption (Rmail) + Mailutils @code{movemail} supports TLS encryption. If you wish to +use it, add the @samp{--tls} flag to @code{rmail-movemail-flags}. + +@node Other Mailbox Formats +@section Retrieving Mail from Local Mailboxes in Various Formats + + If your incoming mail is stored on a local machine in a format other +than UNIX mailbox, you will need the Mailutils @code{movemail} to +retrieve it. @xref{Movemail}, for the detailed description of +@code{movemail} versions. For example, to access mail from a inbox in +@code{maildir} format located in @file{/var/spool/mail/in}, you would +include the following in the Rmail inbox list: + +@smallexample +maildir://var/spool/mail/in +@end smallexample + +@ignore + arch-tag: 034965f6-38df-47a2-a9f1-b8bc8ab37e23 +@end ignore diff --git a/doc/emacs/screen.texi b/doc/emacs/screen.texi new file mode 100644 index 00000000000..90ec645a26f --- /dev/null +++ b/doc/emacs/screen.texi @@ -0,0 +1,359 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, +@c 2003, 2004, 2005, 2006, 2007 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 + + On a text-only terminal, the Emacs display occupies the whole +screen. On a graphical display, such as on GNU/Linux using the X +Window System, Emacs creates its own windows to use. We use the term +@dfn{frame} to mean the entire text-only screen or an entire +system-level 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 main central area of the frame, all except +for the top and bottom and sides, displays the text you are editing. +This area is called @dfn{the window}. At the top there is normally a +@dfn{menu bar} where you can access a series of menus; then there may +be a @dfn{tool bar}, a row of icons that perform editing commands if +you click on them. Below this, the window begins, often with a +@dfn{scroll bar} on one side. Below the window comes the last line of +the frame, a special @dfn{echo area} or @dfn{minibuffer window}, where +prompts appear and you enter information when Emacs asks for it. See +following sections for more information about these special lines. + + You can subdivide the window horizontally or vertically to make +multiple text windows, each of which can independently display some +file or text (@pxref{Windows}). In this manual, the word ``window'' +refers to the initial large window if not subdivided, or any one of +the multiple windows you have subdivided it into. + + At any time, one window is the @dfn{selected window}. On graphical +displays, the selected window normally shows a more prominent cursor +(usually solid and blinking) while other windows show a weaker cursor +(such as a hollow box). Text terminals have just one cursor, so it +always appears in the selected window. + + Most Emacs commands implicitly apply to the text in the selected +window; the text in unselected windows is mostly visible for +reference. However, mouse commands generally operate on whatever +window you click them in, whether selected or not. If you use +multiple frames on a graphical display, 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 different color and/or a ``3D'' +box if the terminal supports them; its contents normally 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 active 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 (normally the left button). + + While the cursor appears to be @emph{on} 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. + + 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 its point location in case you display +it again later. When Emacs displays multiple windows, each window has +its own point location. If the same buffer appears in more than one +window, each window has its own point position in that buffer, and (when +possible) its own cursor. + + A text-only terminal has just one cursor, in the selected window. +The other windows do not show a cursor, even though they do have their +own position of point. When Emacs updates the screen on a text-only +terminal, it has to put the cursor temporarily at the place the output +goes. This doesn't mean point is there, though. Once display +updating finishes, Emacs puts the cursor where point is. + + On graphical displays, Emacs shows a cursor in each window; the +selected window's cursor is solid and blinking, and the other cursors +are just hollow. Thus, the most prominent cursor always shows you the +selected window, on all kinds of terminals. + + @xref{Cursor Display}, for customizable variables that control display +of the cursor or cursors. + + 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 + + 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 +various purposes. + + @dfn{Echoing} means displaying the characters that you type. At the +command line, 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 Custom}). + +@cindex error message in the echo area + If a command cannot do its job, it may display an @dfn{error +message} in the echo area. Error messages are accompanied by beeping +or by flashing the screen. The error also discards any input you have +typed ahead. + + Some commands display 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 show you a message giving you specific information---for example, +@kbd{C-x =} (hold down @key{CTRL} and type @kbd{x}, then let go of +@key{CTRL} and type @kbd{=}) displays 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. They may also indicate progress with +percentages. + +@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, adding lines at the end deletes lines +from the beginning, to keep the size constant. @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 +where you can input 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. The mode line starts and ends with +dashes. When there is only one text window, the mode line appears +right above the echo area; it is the next-to-last line in the frame. +On a text-only terminal, the mode line is in inverse video if the +terminal supports that; on a graphics display, the mode line has a 3D +box appearance to help it stand out. The mode line of the selected +window is highlighted if possible; see @ref{Optional Mode Line}, for +more information. + + Normally, the mode line looks like this: + +@example +-@var{cs}:@var{ch}@var{R}-@var{fr} @var{buf} @var{pos} @var{line} (@var{major} @var{minor})------ +@end example + +@noindent +This gives information about the window and the buffer it displays: 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{R} is @samp{@@} if the default-directory for the current buffer +is on a remote machine, or a hyphen otherwise. + + @var{fr} gives the selected frame name (@pxref{Frames}). It appears +only on text-only terminals. The initial frame's name is @samp{F1}. + + @var{buf} is the name of the window's @dfn{buffer}. Usually this is +the same as the name of a file you are editing. @xref{Buffers}. + + The buffer displayed in the selected window (the window with the +cursor) is the @dfn{current buffer}, where editing happens. When a +command's effect applies to ``the buffer,'' we mean it does those +things to the current buffer. + + @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. +With Size Indication mode, you can display the size of the buffer as +well. @xref{Optional Mode Line}. + + @var{line} is @samp{L} followed by the current line number of point. +This is present when Line Number mode is enabled (it normally is). +You can display the current column number too, by turning on Column +Number mode. It is not enabled by default because it is somewhat +slower. @xref{Optional Mode Line}. + + @var{major} is the name of the @dfn{major mode} in effect in the +buffer. A buffer can only be in one major mode at a time. 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 +them. + + 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 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 + + @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. + + On a text-only terminal, @var{cs} includes two additional characters +which describe the coding system for keyboard input and the coding +system for terminal output. They come right before the coding system +used for the file you are editing. + + 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 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} changes to another string in some cases. +Emacs uses newline characters 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 for files that use newline +as the line separator. + + @xref{Optional Mode Line}, to add other handy information to the +mode line, such as the size of the buffer, the current column number +of point, and whether new mail for you has arrived. + + The mode line is mouse-sensitive; when you move the mouse across +various parts of it, Emacs displays help text to say what a click in +that place will do. @xref{Mode Line Mouse}. + +@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 common operations. There's no need to list them +here, as you can more easily see them yourself. + +@kindex M-` +@kindex F10 +@findex tmm-menubar +@findex menu-bar-open + On a graphical display, you can use the mouse to choose a command +from the menu bar. A right-arrow at the end of the menu item means it +leads to a subsidiary menu; @samp{...} at the end means that the +command invoked will read arguments (further input from you) before it +actually does anything. + + You can also invoke the first menu bar item by pressing @key{F10} (to run +the command @code{menu-bar-open}). You can then navigate the menus with +the arrow keys. You select an item by pressing @key{RET} and cancel menu +navigation with @key{ESC}. + + 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 lets you select a menu item with the +keyboard. A provisional choice appears in the echo area. You can use +the up and down arrow keys to move through the menu to different +items, and then you can type @key{RET} to select the item. + + 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; one such binding is shown in parentheses after the item itself. + +@ignore + arch-tag: 104ba40e-d972-4866-a542-a98be94bdf2f +@end ignore diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi new file mode 100644 index 00000000000..1a8a6372ba2 --- /dev/null +++ b/doc/emacs/search.texi @@ -0,0 +1,1361 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 2002, +@c 2003, 2004, 2005, 2006, 2007 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 +more flexible replacement command called @code{query-replace}, which +asks interactively which occurrences to replace. There are also +commands to find and operate on all matches for a pattern. + + You can also search multiple files under control of a tags +table (@pxref{Tags Search}) or through the Dired @kbd{A} command +(@pxref{Operating on Files}), or ask the @code{grep} program to do it +(@pxref{Grep Searching}). + + +@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. +* Regexp Backslash:: Regular expression constructs starting with `\'. +* Regexp Example:: A complex regular expression explained. +* 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 +@section Incremental Search +@cindex incremental search +@cindex isearch + + 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}. + +@table @kbd +@item C-s +Incremental search forward (@code{isearch-forward}). +@item C-r +Incremental search backward (@code{isearch-backward}). +@end table + +@menu +* Basic Isearch:: Basic incremental search commands. +* Repeat Isearch:: Searching for the same string again. +* Error in Isearch:: When your string is not found. +* Special Isearch:: Special input in incremental search. +* Non-ASCII Isearch:: How to search for non-ASCII characters. +* Isearch Yank:: Commands that grab text into the search string + or else edit the search string. +* Highlight Isearch:: Isearch highlights the other possible matches. +* Isearch Scroll:: Scrolling during an incremental search. +* Slow Isearch:: Incremental search features for slow terminals. +@end menu + +@node Basic Isearch +@subsection Basics of Incremental Search + +@kindex C-s +@findex isearch-forward + @kbd{C-s} starts a forward incremental search. It reads characters +from the keyboard, and moves point past the next occurrence of those +characters. If you type @kbd{C-s} and then @kbd{F}, that puts the +cursor after the first @samp{F} (the first following the starting point, since +this is a forward search). Then if you type an @kbd{O}, you will see +the cursor move to just after the first @samp{FO} (the @samp{F} in that +@samp{FO} may or may not be the first @samp{F}). After another +@kbd{O}, the cursor moves to just 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; +the current search string is always displayed 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 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}, @kbd{M-c}, @kbd{M-e}, and some other +meta-characters). + + When you exit the incremental search, it sets the mark 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. + +@node Repeat Isearch +@subsection Repeating Incremental Search + + Sometimes you search for @samp{FOO} and find one, 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. +You can repeat this 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.'' + + 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}, and @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. + + 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. To edit the current search +string in the minibuffer without replacing it with items from the +search ring, type @kbd{M-e}. Type @kbd{C-s} or @kbd{C-r} +to terminate editing the string and search for it. + + You can change to searching backwards with @kbd{C-r}. For instance, +if you are searching forward but you realize you were looking for +something above the starting point, you can 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 end before the starting point, +just as a forward search finds matches that begin after it. + +@node Error in Isearch +@subsection Errors in Incremental Search + + 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 +remain there. 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. + +@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. + +@node Special Isearch +@subsection Special Input for Incremental Search + + 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}. + + 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. + + @kbd{M-%} typed in incremental search invokes @code{query-replace} +or @code{query-replace-regexp} (depending on search mode) with the +current search string used as the string to replace. @xref{Query +Replace}. + + Entering @key{RET} when the search string is empty launches +nonincremental search (@pxref{Nonincremental Search}). + +@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}}. + +@node Non-ASCII Isearch +@subsection Isearch for Non-@acronym{ASCII} Characters +@cindex searching for non-@acronym{ASCII} characters +@cindex input method, during incremental search + + To enter non-@acronym{ASCII} characters in an incremental search, +you can use @kbd{C-q} (see the previous section), but it is easier to +use an input method (@pxref{Input Methods}). If an input method is +enabled in the current buffer when you start the search, you can use +it in the search string also. Emacs indicates that by including the +input method mnemonic in its prompt, like this: + +@example +I-search [@var{im}]: +@end example + +@noindent +@findex isearch-toggle-input-method +@findex isearch-toggle-specified-input-method +where @var{im} is the mnemonic of the active input method. + + You can toggle (enable or disable) the input method while you type +the search string with @kbd{C-\} (@code{isearch-toggle-input-method}). +You can turn on a certain (non-default) input method with @kbd{C-^} +(@code{isearch-toggle-specified-input-method}), which prompts for the +name of the input method. The input method you enable during +incremental search remains enabled in the current buffer afterwards. + +@node Isearch Yank +@subsection Isearch Yanking + + The characters @kbd{C-w} and @kbd{C-y} 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 character or word after point as part of the +search string, advancing point over it. (The decision, whether to +copy a character or a word, is heuristic.) Another @kbd{C-s} to +repeat the search will then search for a string including that +character or word. + + @kbd{C-y} is similar to @kbd{C-w} but copies all the rest of the +current line into the search string. If point is already at the end +of a line, it grabs the entire next line. 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. + + @kbd{C-M-w} and @kbd{C-M-y} modify the search string by only one +character at a time: @kbd{C-M-w} deletes the last character from the +search string and @kbd{C-M-y} copies the character after point to the +end of the search string. An alternative method to add the character +after point into the search string is to enter the minibuffer by +@kbd{M-e} and to type @kbd{C-f} at the end of the search string in the +minibuffer. + + 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. +@kbd{Mouse-2} in the echo area does the same. +@xref{Yanking}. + +@node Highlight Isearch +@subsection Lazy Search Highlighting +@cindex lazy search highlighting +@vindex isearch-lazy-highlight + + When you pause for a little while during incremental search, it +highlights all other possible matches for the search string. This +makes it easier to anticipate where you can get to by typing @kbd{C-s} +or @kbd{C-r} to repeat the search. The short delay before highlighting +other matches helps indicate which match is the current one. +If you don't like this feature, you can turn it off by setting +@code{isearch-lazy-highlight} to @code{nil}. + +@cindex faces for highlighting search matches + You can control how this highlighting looks by customizing the faces +@code{isearch} (used for the current match) and @code{lazy-highlight} +(for all the other matches). + +@node Isearch Scroll +@subsection Scrolling During Incremental Search + + You can enable the use of vertical scrolling during incremental +search (without exiting the search) by setting the customizable +variable @code{isearch-allow-scroll} to a non-@code{nil} value. This +applies to using the vertical scroll-bar and to certain keyboard +commands such as @kbd{@key{PRIOR}} (@code{scroll-down}), +@kbd{@key{NEXT}} (@code{scroll-up}) and @kbd{C-l} (@code{recenter}). +You must run these commands via their key sequences to stay in the +search---typing @kbd{M-x} will terminate the search. You can give +prefix arguments to these commands in the usual way. + + This feature won't let you scroll the current match out of visibility, +however. + + The feature also affects some other commands, such as @kbd{C-x 2} +(@code{split-window-vertically}) and @kbd{C-x ^} +(@code{enlarge-window}) which don't exactly scroll but do affect where +the text appears on the screen. In general, it applies to any command +whose name has a non-@code{nil} @code{isearch-scroll} property. So you +can control which commands are affected by changing these properties. + + For example, to make @kbd{C-h l} usable within an incremental search +in all future Emacs sessions, use @kbd{C-h c} to find what command it +runs. (You type @kbd{C-h c C-h l}; it says @code{view-lossage}.) +Then you can put the following line in your @file{.emacs} file +(@pxref{Init File}): + +@example +(put 'view-lossage 'isearch-scroll t) +@end example + +@noindent +This feature can be applied to any command that doesn't permanently +change point, the buffer contents, the match data, the current buffer, +or the selected window and frame. The command must not itself attempt +an incremental search. + +@node Slow Isearch +@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 moves outside of the text that is already +on the screen. + + When you terminate the search, the single-line window is removed. +Emacs then redisplays the window in which the search was done, to show +its new position of point. + +@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. See also the discussion of the variable @code{baud-rate} +(@pxref{baud-rate,, Customization of Display}). + +@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 +@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 signals an error. + + When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental +search as usual. That command is specially programmed to invoke +nonincremental search, @code{search-forward}, if the string you +specify is empty. (Such an empty argument would otherwise be +useless.) But it does not call @code{search-forward} right away. First +it checks the next input character to see if is @kbd{C-w}, +which specifies a word search. +@ifnottex +@xref{Word Search}. +@end ifnottex +@kbd{C-r @key{RET}} does likewise, for a reverse incremental search. + +@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 separate key sequences +for them. + +@node Word 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 characters +between these 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 as a special case of nonincremental search 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. + + You can also invoke word search with @kbd{C-s M-e C-w} or @kbd{C-r +M-e C-w} followed by the search string and terminated with @key{RET}, +@kbd{C-s} or @kbd{C-r}. This puts word search into incremental mode +where you can use all keys available for incremental search. However, +when you type more words in incremental word search, it will fail +until you type complete words. + +@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. They are available +via the incremental search commands both for historical reasons and +to avoid the need to find separate key sequences for them. + +@node Regexp 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. GNU Emacs provides both incremental and +nonincremental ways to search for a match for a regexp. The syntax of +regular expressions is explained in the following section. + +@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}), by invoking @kbd{C-s} with a +prefix argument (whose value does not matter), or by typing @kbd{M-r} +within a forward incremental search. 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. To search backward for a regexp, use @kbd{C-M-r} +(@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument, +or @kbd{M-r} within a backward incremental search. + + 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}. + +@vindex search-whitespace-regexp + 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}}. You can control what a +bare space matches by setting the variable +@code{search-whitespace-regexp} to the desired regexp. + + In some cases, 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}. + + Forward and backward regexp search are not symmetrical, because +regexp matching in Emacs always operates forward, starting with the +beginning of the regexp. Thus, forward regexp search scans forward, +trying a forward match at each possible starting position. Backward +regexp search scans backward, trying a forward match at each possible +starting position. These search methods are not mirror images. + +@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 +@section Syntax of Regular Expressions +@cindex syntax of regexps + + This manual describes regular expression features that users +typically want to use. There are additional features that are +mainly used in Lisp programs; see @ref{Regular Expressions,,, +elisp, The Emacs Lisp Reference Manual}. + + 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{[}, and +@samp{\}. The character @samp{]} is special if it ends a character +alternative (see later). The character @samp{-} is special inside a +character alternative. Any other character appearing in a regular +expression is ordinary, unless a @samp{\} precedes it. (When you use +regular expressions in a Lisp program, each @samp{\} must be doubled, +see the example near the end of this section.) + + 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 @asis +@item @kbd{.}@: @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 @kbd{*} +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 @kbd{+} +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 @kbd{?} +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 @kbd{*?}, @kbd{+?}, @kbd{??} +@cindex non-greedy regexp matching +are non-greedy variants of the operators above. The normal operators +@samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as +much as they can, as long as the overall regexp can still match. With +a following @samp{?}, they are non-greedy: they will match as little +as possible. + +Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a} +and the string @samp{abbbb}; but if you try to match them both against +the text @samp{abbb}, @samp{ab*} will match it all (the longest valid +match), while @samp{ab*?} will match just @samp{a} (the shortest +valid match). + +Non-greedy operators match the shortest possible string starting at a +given starting point; in a forward search, though, the earliest +possible starting point for match is always the one chosen. Thus, if +you search for @samp{a.*?$} against the text @samp{abbab} followed by +a newline, it matches the whole string. Since it @emph{can} match +starting at the first @samp{a}, it does. + +@item @kbd{\@{@var{n}\@}} +is a postfix operator that specifies repetition @var{n} times---that +is, the preceding regular expression must match exactly @var{n} times +in a row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} +and nothing else. + +@item @kbd{\@{@var{n},@var{m}\@}} +is a postfix operator that specifies repetition between @var{n} and +@var{m} times---that is, the preceding regular expression must match +at least @var{n} times, but no more than @var{m} times. If @var{m} is +omitted, then there is no upper limit, but the preceding regular +expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is +equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to +@samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}. + +@item @kbd{[ @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 @acronym{ASCII} letter. Ranges may be +intermixed freely with individual characters, as in @samp{[a-z$%.]}, +which matches any lower-case @acronym{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. (At the beginning, it complements the set---see below.) + +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 @kbd{[^ @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} @acronym{ASCII} 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 @kbd{^} +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. + +For historical compatibility reasons, @samp{^} can be used with this +meaning only at the beginning of the regular expression, or after +@samp{\(} or @samp{\|}. + +@item @kbd{$} +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. + +For historical compatibility reasons, @samp{$} can be used with this +meaning only at the end of the regular expression, or before @samp{\)} +or @samp{\|}. + +@item @kbd{\} +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. + +See the following section for the special constructs that begin +with @samp{\}. +@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. + +As a @samp{\} is not special inside a character alternative, it can +never remove the special meaning of @samp{-} or @samp{]}. So you +should not quote these characters when they have no special meaning +either. This would not clarify anything, since backslashes can +legitimately precede these characters where they @emph{have} special +meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), +which matches any single character except a backslash. + +@node Regexp Backslash +@section Backslash in Regular Expressions + + 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 usually no conflict between the two meanings; when there is +a conflict, you can use a ``shy'' group. + +@item \(?: @dots{} \) +@cindex shy group, in regexp +specifies a ``shy'' group that does not record the matched substring; +you can't refer back to it with @samp{\@var{d}}. This is useful +in mechanically combining regular expressions, so that you +can add groups for syntactic purposes without interfering with +the numbering of the groups that are meant to be referred to. + +@item \@var{d} +@cindex back reference, in regexp +matches the same text that matched the @var{d}th occurrence of a +@samp{\( @dots{} \)} construct. This is called a @dfn{back +reference}. + +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 string or +buffer (or its accessible portion) being matched against. + +@item \' +matches the empty string, but only at the end of the string or buffer +(or its accessible portion) 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 \_< +matches the empty string, but only at the beginning of a symbol. +A symbol is a sequence of one or more symbol-constituent characters. +A symbol-constituent character is a character whose syntax is either +@samp{w} or @samp{_}. @samp{\_<} matches at the beginning of the +buffer only if a symbol-constituent character follows. + +@item \_> +matches the empty string, but only at the end of a symbol. @samp{\_>} +matches at the end of the buffer only if the contents end with a +symbol-constituent character. + +@item \s@var{c} +matches any character whose syntax is @var{c}. Here @var{c} is a +character that designates a particular syntax class: thus, @samp{w} +for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.} +for ordinary punctuation, etc. @xref{Syntax}. + +@item \S@var{c} +matches any character whose syntax is not @var{c}. + +@cindex categories of characters +@cindex characters which belong to a specific language +@findex describe-categories +@item \c@var{c} +matches any character that belongs to the category @var{c}. For +example, @samp{\cc} matches Chinese characters, @samp{\cg} matches +Greek characters, etc. For the description of the known categories, +type @kbd{M-x describe-categories @key{RET}}. + +@item \C@var{c} +matches any character that does @emph{not} belong to category +@var{c}. +@end table + + The constructs that pertain to words and syntax are controlled by the +setting of the syntax table (@pxref{Syntax}). + +@node Regexp Example +@section Regular Expression Example + + Here is a complicated regexp---a simplified version of the regexp +that Emacs uses, by default, to recognize the end of a sentence +together with any whitespace that follows. We show its Lisp syntax 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 zero or more times; a +set of alternatives within backslash-parentheses that matches either +end-of-line, a space at the end of a line, a tab, or two spaces; and a +character set matching whitespace characters, repeated any number of +times. + + To enter the same regexp in incremental search, 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. In commands that use ordinary minibuffer input to +read a regexp, you would quote the @kbd{C-j} by preceding it with a +@kbd{C-q} to prevent @kbd{C-j} from exiting the minibuffer. + +@node Search Case +@section Searching and Case + + 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. + + Typing @kbd{M-c} within an incremental search toggles the case +sensitivity of that search. The effect does not extend beyond the +current incremental search to the next one, but it does override the +effect of including an upper-case letter in the current search. + +@vindex case-fold-search +@vindex default-case-fold-search + 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 in @code{default-case-fold-search} that you +can also set. @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}). + + Several related variables control case-sensitivity of searching and +matching for specific commands or activities. For instance, +@code{tags-case-fold-search} controls case sensitivity for +@code{find-tag}. To find these variables, do @kbd{M-x +apropos-variable @key{RET} case-fold-search @key{RET}}. + +@node Replace +@section Replacement Commands +@cindex replacement +@cindex search-and-replace commands +@cindex string substitution +@cindex global substitution + + Global search-and-replace operations are not needed often in Emacs, +but they are available. In addition to the simple @kbd{M-x +replace-string} command which replaces all occurrences, +there is @kbd{M-%} (@code{query-replace}), which presents each occurrence +of the pattern and asks you 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 (@pxref{Transient +Mark}), when the mark is active, they operate on the region. The +basic replace commands 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 + +@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}. +@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. + + @xref{Replacement and Case}, for details about case-sensitivity in +replace commands. + + What if you want to exchange @samp{x} and @samp{y}: replace every @samp{x} with a @samp{y} and vice versa? You can do it this way: + +@example +M-x replace-string @key{RET} x @key{RET} @@TEMP@@ @key{RET} +M-< M-x replace-string @key{RET} y @key{RET} x @key{RET} +M-< M-x replace-string @key{RET} @@TEMP@@ @key{RET} y @key{RET} +@end example + +@noindent +This works provided the string @samp{@@TEMP@@} does not appear +in your text. + +@node Regexp Replace, Replacement and Case, Unconditional Replace, Replace +@subsection Regexp Replacement +@findex replace-regexp + + 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. + +@table @kbd +@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 + +@cindex back reference, in regexp replacement + 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}. (This is called a ``back reference.'') +@samp{\#} refers to the count of replacements already made in this +command, as a decimal number. In the first replacement, @samp{\#} +stands for @samp{0}; in the second, for @samp{1}; and so on. 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. To include a @samp{\} in the +text to replace with, you must enter @samp{\\}. + + If you want to enter part of the replacement string by hand each +time, use @samp{\?} in the replacement string. Each replacement will +ask you to edit the replacement string in the minibuffer, putting +point where the @samp{\?} was. + + The remainder of this subsection is intended for specialized tasks +and requires knowledge of Lisp. Most readers can skip it. + + You can use Lisp expressions to calculate parts of the +replacement string. To do this, write @samp{\,} followed by the +expression in the replacement string. Each replacement calculates the +value of the expression and converts it to text without quoting (if +it's a string, this means using the string's contents), and uses it in +the replacement string in place of the expression itself. If the +expression is a symbol, one space in the replacement string after the +symbol name goes with the symbol name, so the value replaces them +both. + + Inside such an expression, you can use some special sequences. +@samp{\&} and @samp{\@var{n}} refer here, as usual, to the entire +match as a string, and to a submatch as a string. @var{n} may be +multiple digits, and the value of @samp{\@var{n}} is @code{nil} if +subexpression @var{n} did not match. You can also use @samp{\#&} and +@samp{\#@var{n}} to refer to those matches as numbers (this is valid +when the match or submatch has the form of a numeral). @samp{\#} here +too stands for the number of already-completed replacements. + + Repeating our example to exchange @samp{x} and @samp{y}, we can thus +do it also this way: + +@example +M-x replace-regexp @key{RET} \(x\)\|y @key{RET} +\,(if \1 "y" "x") @key{RET} +@end example + + For computing replacement strings for @samp{\,}, the @code{format} +function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs +Lisp Reference Manual}). For example, to add consecutively numbered +strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are +already occupied), you can use + +@example +M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET} +\,(format "%-72sABC%05d" \& \#) @key{RET} +@end example + +@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 +command 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. Aside from querying, +@code{query-replace} works just like @code{replace-string}. It +preserves case, like @code{replace-string}, provided +@code{case-replace} is non-@code{nil}, as it normally is +(@pxref{Replacement and Case}). A numeric argument means consider +only occurrences that are bounded by word-delimiter characters. + +@kindex C-M-% +@findex query-replace-regexp + @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}). +It works like @code{replace-regexp} except that it queries +like @code{query-replace}. + +@cindex faces for highlighting query replace + These commands highlight the current match using the face +@code{query-replace}. They highlight other matches using +@code{lazy-highlight} just like incremental search (@pxref{Incremental +Search}). + + The characters you can type when you are shown a match for the string +or 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 or want to +reexamine it. + +@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 e +to edit the replacement string in the minibuffer. When you exit the +minibuffer by typing @key{RET}, the minibuffer contents replace the +current occurrence of the pattern. They also become the new +replacement string for any further occurrences. + +@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}. + + @xref{Operating on Files}, for the Dired @kbd{Q} command which +performs query replace on selected files. 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 +@section Other Search-and-Loop Commands + + Here are some other commands that find matches for a regular +expression. They all ignore case in matching, if the pattern contains +no upper-case letters and @code{case-fold-search} is non-@code{nil}. +Aside from @code{occur} and its variants, all operate on the text from +point to the end of the buffer, or on the active region in Transient +Mark mode. + +@findex list-matching-lines +@findex occur +@findex multi-occur +@findex multi-occur-in-matching-buffers +@findex how-many +@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}. To limit the search to part of the buffer, narrow +to that part (@pxref{Narrowing}). A numeric argument @var{n} +specifies that @var{n} lines of context are to be displayed before and +after each matching line. Currently, @code{occur} can not correctly +handle multiline matches. + +@kindex RET @r{(Occur mode)} +@kindex o @r{(Occur mode)} +@kindex C-o @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. +@kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o} +does not select it. + +After using @kbd{M-x occur}, you can use @code{next-error} to visit +the occurrences found, one by one. @ref{Compilation Mode}. + +@item M-x list-matching-lines +Synonym for @kbd{M-x occur}. + +@item M-x multi-occur @key{RET} @var{buffers} @key{RET} @var{regexp} @key{RET} +This function is just like @code{occur}, except it is able to search +through multiple buffers. It asks you to specify the buffer names one by one. + +@item M-x multi-occur-in-matching-buffers @key{RET} @var{bufregexp} @key{RET} @var{regexp} @key{RET} +This function is similar to @code{multi-occur}, except the buffers to +search are specified by a regular expression that matches visited +file names. With a prefix argument, it uses the regular expression to match +buffer names instead. + +@item M-x how-many @key{RET} @var{regexp} @key{RET} +Print the number of matches for @var{regexp} that exist in the buffer +after point. In Transient Mark mode, if the region is active, the +command operates on the region instead. + +@item M-x flush-lines @key{RET} @var{regexp} @key{RET} +This command deletes each line that contains a match for @var{regexp}, +operating on the text after point; it deletes the current line +if it contains a match starting after point. In Transient Mark mode, +if the region is active, the command operates on the region instead; +it deletes a line partially contained in the region if it contains a +match entirely contained in the region. + +If a match is split across lines, @code{flush-lines} deletes all those +lines. It deletes the lines before starting to look for the next +match; hence, it ignores a match starting on the same line at which +another match ended. + +@item M-x keep-lines @key{RET} @var{regexp} @key{RET} +This command deletes each line that @emph{does not} contain a match for +@var{regexp}, operating on the text after point; if point is not at the +beginning of a line, it always keeps the current line. In Transient +Mark mode, if the region is active, the command operates on the region +instead; it never deletes lines that are only partially contained in +the region (a newline that ends a line counts as part of that line). + +If a match is split across lines, this command keeps all those lines. +@end table + +@ignore + arch-tag: fd9d8e77-66af-491c-b212-d80999613e3e +@end ignore diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi new file mode 100644 index 00000000000..5d6a7c83f3e --- /dev/null +++ b/doc/emacs/sending.texi @@ -0,0 +1,724 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 2002, +@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node Sending Mail +@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 remains 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. + +@vindex mail-default-directory + The variable @code{mail-default-directory} controls the default +directory for mail buffers, and also says where to put their auto-save +files. + +@ignore +@c Commented out because it is not user-oriented; +@c it doesn't say how to do some job. -- rms. +@cindex directory servers +@cindex LDAP +@cindex PH/QI +@cindex names and addresses +There is an interface to directory servers using various protocols such +as LDAP or the CCSO white pages directory system (PH/QI), described in a +separate manual. It may be useful for looking up names and addresses. +@xref{Top,,EUDC, eudc, EUDC Manual}. +@end ignore + +@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. +* Amuse: Mail Amusements. Distracting the NSA; adding fortune messages. +* Methods: 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. + + In the mail buffer, you can insert and edit header fields using +ordinary editing commands. Mail mode provides a commands to help you +edit some header fields, and some are preinitialized in the buffer +automatically when appropriate. + + 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 +@cindex copy of every outgoing message +To send a blind carbon copy of every outgoing message to yourself, set +the variable @code{mail-self-blind} to @code{t}. To send a blind carbon +copy of every message to some other @var{address}, set the variable +@code{mail-default-headers} to @code{"Bcc: @var{address}\n"}. + +@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. To specify +more than one file, use several @samp{FCC} fields, with one file +name in each field. + +@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 @env{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 @env{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 the 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}, and @samp{BCC} 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. These fields 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: + +@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 + +@vindex mail-default-headers + You can direct Emacs to insert certain default headers into the +outgoing message by setting the variable @code{mail-default-headers} +to a string. Then @code{C-x m} inserts this string into the message +headers. If the default header fields are not appropriate for a +particular message, edit them as appropriate before sending the +message. + +@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 + +@noindent +Addresses specified in this way should use doublequotes around an +entire address when the address contains spaces. But you need not +include doublequotes around parts of the address, such as the person's +full name. Emacs puts them in if they are needed. For example, + +@example +alias chief-torturer "George W. Bush <bush@@whitehouse.gov>" +@end example + +@noindent +is correct in @samp{.mailrc}. Emacs will insert the address as +@samp{"George W. Bush" <bush@@whitehouse.gov>}. + + 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-mode-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-mode-hook + (lambda () + (define-key + mail-mode-map [remap next-line] 'mail-abbrev-next-line) + (define-key + mail-mode-map [remap end-of-buffer] 'mail-abbrev-end-of-buffer))) +@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. This is a useful thing to do if +you have saved the text of a draft message 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. Also, you +don't get a warning if you try to send the same message twice. + +@c This is indexed in mule.texi, node "Recognize Coding". +@c @vindex sendmail-coding-system + When you send a message that contains non-@acronym{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} (@pxref{Recognize Coding}). + + 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. + +@cindex SMTP +@cindex Feedmail +@cindex Sendmail +@vindex send-mail-function + The variable @code{send-mail-function} controls how the default mail +user agent sends mail. It should be set to a function. The default +is @code{sendmail-send-it}, which delivers mail using the Sendmail +installation on the local host. To send mail through a SMTP server, +set it to @code{smtpmail-send-it} and set up the Emacs SMTP library +(@pxref{Top,,Emacs SMTP Library, smtpmail, Sending mail via SMTP}). A +third option is @code{feedmail-send-it}, see the commentary section of +the @file{feedmail.el} package for more information. + +@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}). (If your window +manager defines @kbd{M-@key{TAB}} to switch windows, you can type +@kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}.) + + 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; see the customization +group @samp{mailalias} to see the variables for customizing this +feature (@pxref{Customization Groups}). + + If you type @kbd{M-@key{TAB}} in the body of the message, +@code{mail-complete} 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 +Perform 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}; after that, 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. Note that this is not a MIME +attachment. + +@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 inserts the default contents of the buffer. +After these default contents are inserted, @code{mail-setup-hook} runs. + +@node Mail Amusements +@section Mail Amusements + +@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@footnote{The US National Security Agency.} 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. + +@findex fortune-to-signature +@cindex fortune cookies + You can use the @code{fortune} program to put a ``fortune cookie'' +message into outgoing mail. To do this, add +@code{fortune-to-signature} to @code{mail-setup-hook}: + +@example +(add-hook 'mail-setup-hook 'fortune-to-signature) +@end example + +@node Mail Methods +@section Mail-Composition Methods +@cindex mail-composition methods + +@cindex MH mail interface +@cindex Message mode for sending mail + In this chapter we have described 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. +@xref{Top,,MH-E,mh-e, The Emacs Interface to MH}. @xref{Top,,Message,message, +Message 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, as do various other Emacs commands +and facilities that send mail. + +@vindex mail-user-agent + To specify your mail-composition method, customize the variable +@code{mail-user-agent}. Currently legitimate values include +@code{sendmail-user-agent} (Mail mode), @code{mh-e-user-agent}, +@code{message-user-agent} and @code{gnus-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; the other methods use a different format of text in a different +buffer, and their commands are different as well. + +@ignore + arch-tag: d8a3dfc3-5d87-45c5-a7f2-69871b8e4fd6 +@end ignore diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi new file mode 100644 index 00000000000..3a0e091ea40 --- /dev/null +++ b/doc/emacs/text.texi @@ -0,0 +1,2901 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 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 binary data. This chapter is concerned with +editing text in the narrower sense. + + 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 formatter. Thus, for +input to @TeX{}, you would use @TeX{} +@iftex +mode (@pxref{TeX Mode,,@TeX{} Mode}). +@end iftex +@ifnottex +mode. +@end ifnottex +For input to groff or 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 + +@cindex ASCII art + If you need to edit pictures made out of text characters (commonly +referred to as ``ASCII art''), use @kbd{M-x edit-picture} to enter +Picture mode, a special major mode for editing such pictures. +@iftex +@xref{Picture Mode,,, emacs-xtra, Specialized Emacs Features}. +@end iftex +@ifnottex +@xref{Picture Mode}. +@end ifnottex + + +@cindex skeletons +@cindex templates +@cindex autotyping +@cindex automatic typing + The ``automatic typing'' features may be useful when writing text. +@inforef{Top,, autotype}. + +@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. +* HTML Mode:: Editing HTML, SGML, and XML files. +* Nroff Mode:: Editing input to the formatter nroff. +* Formatted Text:: Editing formatted text directly in WYSIWYG fashion. +* Text Based Tables:: Editing text-based tables 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. + +@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 others +(@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. + +@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. For instance, if point is after the space in @w{@samp{FOO, +BAR}}, it kills @w{@samp{FOO, }}. 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}}. + +@c Don't index M-t and transpose-words here, they are indexed in +@c fixit.texi, in the node "Transpose". +@c @kindex M-t +@c @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. + +@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 word boundaries is 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} move over successive sentences if +repeated. + + 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. + + 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. +It is useful to follow this convention, because it makes a distinction +between periods that end a sentence and periods that indicate +abbreviations; that enables the Emacs sentence commands to distinguish, +too. These commands do not stop for periods that indicate abbreviations. + +@vindex sentence-end-double-space + If you want to use just one space between sentences, you can set the +variable @code{sentence-end-double-space} to @code{nil} to make the +sentence commands stop for single spaces. However, this mode has a +drawback: there is no way to distinguish between periods that end +sentences and those that indicate abbreviations. For convenient and +reliable editing, we therefore recommend you follow the two-space +convention. The variable @code{sentence-end-double-space} also +affects filling (@pxref{Fill Commands}) in related ways. + +@vindex sentence-end + The variable @code{sentence-end} controls how to recognize the end +of a sentence. If non-@code{nil}, it is a regexp that matches the +last few characters of a sentence, together with the whitespace +following the sentence. If the value is @code{nil}, the default, then +Emacs computes the regexp according to various criteria such as the +value of @code{sentence-end-double-space}. @xref{Regexp Example}, for +a detailed explanation of one of the regular expressions Emacs uses +for this purpose. + +@vindex sentence-end-without-period + Some languages do not use periods to indicate the end of a sentence. +For example, sentences in Thai end with a double space but without a +period. Set the variable @code{sentence-end-without-period} to +@code{t} in such cases. + +@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 on 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. If there is +a blank line before the paragraph, @kbd{M-@{} moves to the blank line, +because that is convenient in practice. + + In Text mode, an indented line is not a paragraph break. If you +want indented lines to have this effect, use Paragraph-Indent Text +mode instead. @xref{Text Mode}. + + In major modes for programs, paragraphs begin and end only at blank +lines. This makes the paragraph commands useful, even though there +are no paragraphs as such in a program. + + When you have set 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}. Each regular expression must match at the +left margin. For example, in Fundamental mode, @code{paragraph-start} +is @w{@code{"\f\\|[ \t]*$"}}, and @code{paragraph-separate} is +@w{@code{"[ \t\f]*$"}}. + + 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 (@acronym{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. + +@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). In Transient +Mark mode, this command activates the mark. + + @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 displays 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{"^\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. +* Refill:: Keeping paragraphs filled. +* Longlines:: Editing text with very long lines. +@end menu + +@node Auto Fill +@subsection Auto Fill Mode +@cindex Auto Fill mode +@cindex mode, Auto Fill + + @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 (@pxref{Adaptive Fill}) 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. +@ifnottex +@xref{Fill Commands}. +@end ifnottex + + 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 +finds the paragraphs in the region 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 as a single paragraph. This command +deletes any blank lines within the region, so separate blocks of text +end up combined into one block. + +@cindex justification + A numeric argument to @kbd{M-q} tells 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. This binding is +made by Text mode and is available only in that and related modes +(@pxref{Text Mode}). + +@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. + + 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. + +@vindex fill-nobreak-predicate + The variable @code{fill-nobreak-predicate} is a hook (an abnormal +hook, @pxref{Hooks}) specifying additional conditions where +line-breaking is not allowed. Each function is called with no +arguments, with point at a place where Emacs is considering breaking +the line. If a function returns a non-@code{nil} value, then that's +a bad place to break the line. Two standard functions you can use are +@code{fill-single-word-nobreak-p} (don't break after the first word of +a sentence or before the last) and @code{fill-french-nobreak-p} (don't +break after @samp{(} or before @samp{)}, @samp{:} or @samp{?}). + +@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 for the current buffer, move to a line that +starts with the desired prefix, put point at the end of the prefix, +and type @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. + + When a fill prefix is in effect, the fill commands remove the fill +prefix from each line of the paragraph before filling and insert it on +each line after filling. (The beginning of the first line of the +paragraph is left unchanged, since often that is intentionally +different.) 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}, @code{adaptive-fill-regexp} gets +a chance to find a prefix. + +@node Refill +@subsection Refill Mode +@cindex refilling text, word processor style +@cindex modes, Refill +@cindex Refill minor mode + + Refill minor mode provides support for keeping paragraphs filled as +you type or modify them in other ways. It provides an effect similar +to typical word processor behavior. This works by running a +paragraph-filling command at suitable times. + + To toggle the use of Refill mode in the current buffer, type +@kbd{M-x refill-mode}. When you are typing text, only characters +which normally trigger auto filling, like the space character, will +trigger refilling. This is to avoid making it too slow. Apart from +self-inserting characters, other commands which modify the text cause +refilling. + + The current implementation is preliminary and not robust. You can +get better ``line wrapping'' behavior using Longlines mode. +@xref{Longlines}. However, Longlines mode has an important +side-effect: the newlines that it inserts for you are not saved to +disk, so the files that you make with Longlines mode will appear to be +completely unfilled if you edit them without Longlines mode. + +@node Longlines +@subsection Long Lines Mode +@cindex refilling text, word processor style +@cindex modes, Long Lines +@cindex word wrap +@cindex Long Lines minor mode + + Long Lines mode is a minor mode for @dfn{word wrapping}; it lets you +edit ``unfilled'' text files, which Emacs would normally display as a +bunch of extremely long lines. Many text editors, such as those built +into many web browsers, normally do word wrapping. + +@findex longlines-mode + To enable Long Lines mode, type @kbd{M-x longlines-mode}. If the +text is full of long lines, this will ``wrap'' them +immediately---i.e., break up to fit in the window. As you edit the +text, Long Lines mode automatically re-wraps lines by inserting or +deleting @dfn{soft newlines} as necessary (@pxref{Hard and Soft +Newlines}.) These soft newlines won't show up when you save the +buffer into a file, or when you copy the text into the kill ring, +clipboard, or a register. + +@findex longlines-auto-wrap + Word wrapping is @emph{not} the same as ordinary filling +(@pxref{Fill Commands}). It does not contract multiple spaces into a +single space, recognize fill prefixes (@pxref{Fill Prefix}), or +perform adaptive filling (@pxref{Adaptive Fill}). The reason for this +is that a wrapped line is still, conceptually, a single line. Each +soft newline is equivalent to exactly one space in that long line, and +vice versa. However, you can still call filling functions such as +@kbd{M-q}, and these will work as expected, inserting soft newlines +that won't show up on disk or when the text is copied. You can even +rely entirely on the normal fill commands by turning off automatic +line wrapping, with @kbd{C-u M-x longlines-auto-wrap}. To turn +automatic line wrapping back on, type @kbd{M-x longlines-auto-wrap}. + +@findex longlines-show-hard-newlines + Type @kbd{RET} to insert a hard newline, one which automatic +refilling will not remove. If you want to see where all the hard +newlines are, type @kbd{M-x longlines-show-hard-newlines}. This will +mark each hard newline with a special symbol. The same command with a +prefix argument turns this display off. + + Long Lines mode does not change normal text files that are already +filled, since the existing newlines are considered hard newlines. +Before Long Lines can do anything, you need to transform each +paragraph into a long line. One way is to set @code{fill-column} to a +large number (e.g., @kbd{C-u 9999 C-x f}), re-fill all the paragraphs, +and then set @code{fill-column} back to its original value. + +@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. + +@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 +comparable to 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. + + Text mode turns off the features concerned with comments except when +you explicitly invoke them. It changes the syntax table so that +single-quotes are considered part of words. However, if a word starts +with single-quotes, these are treated as a prefix for purposes such as +capitalization. That is, @kbd{M-c} will convert @samp{'hello'} into +@samp{'Hello'}, as expected. + +@cindex Paragraph-Indent Text mode +@cindex mode, Paragraph-Indent Text +@findex paragraph-indent-text-mode +@findex paragraph-indent-minor-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. Use @kbd{M-x +paragraph-indent-minor-mode} to enable an equivalent minor mode in +situations where you can't change the major mode---in mail +composition, for instance. + +@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}. If your +window manager defines @kbd{M-@key{TAB}} to switch windows, you can +type @kbd{@key{ESC} @key{TAB}} or @kbd{C-M-i}. + +@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}. + +@ifnottex + 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,,@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 ifnottex + +@node Outline Mode +@section Outline Mode +@cindex Outline mode +@cindex mode, Outline +@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. (Multiple consecutive +invisible lines produce just one ellipsis.) + + 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 the ellipsis at the end of a visible line +really kills all the following invisible lines. + + 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. +* Foldout:: Folding means zooming in on outlines. +@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}. (The recommended ways to +do this are in a major mode function or with a file local variable.) +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 + You can explicitly specify a 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. The recommended ways to +set this variable are in a major mode command or with a file local +variable. + +@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. + +@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. + + Many of these commands act on the ``current'' heading line. If +point is on a heading line, that is the current heading line; if point +is on a body line, the current heading line is the nearest preceding +header line. + +@table @kbd +@item C-c C-c +Make the current heading line's body invisible (@code{hide-entry}). +@item C-c C-e +Make the current heading line's body visible (@code{show-entry}). +@item C-c C-d +Make everything under the current heading invisible, not including the +heading itself (@code{hide-subtree}). +@item C-c C-s +Make everything under the current heading visible, including body, +subheadings, and their bodies (@code{show-subtree}). +@item C-c C-l +Make the body of the current heading line, and of all its subheadings, +invisible (@code{hide-leaves}). +@item C-c C-k +Make all subheadings of the current heading line, at all levels, +visible (@code{show-branches}). +@item C-c C-i +Make immediate subheadings (one level down) of the current heading +line visible (@code{show-children}). +@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-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 apply +to the body lines directly following the current heading line. +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 apply to the current +heading line'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 the current heading line, up to +and not including the next heading of the same or higher rank. + +@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. + +@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 (as a special exception, it will not hide lines +at the top of the file, preceding the first header line, even though +these are technically body lines). @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 and body text that point is in, plus its parents (the headers +leading up from there to top level in the outline) and the top level +headings. + +@findex reveal-mode + 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. You can also +automatically make text visible as you navigate in it by using +@kbd{M-x reveal-mode}. + +@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 Foldout +@subsection Folding Editing + +@cindex folding editing + The Foldout package extends Outline mode and Outline minor mode with +``folding'' commands. The idea of folding is that you zoom in on a +nested portion of the outline, while hiding its relatives at higher +levels. + + Consider an Outline mode buffer with all the text and subheadings under +level-1 headings hidden. To look at what is hidden under one of these +headings, you could use @kbd{C-c C-e} (@kbd{M-x show-entry}) to expose +the body, or @kbd{C-c C-i} to expose the child (level-2) headings. + +@kindex C-c C-z +@findex foldout-zoom-subtree + With Foldout, you use @kbd{C-c C-z} (@kbd{M-x foldout-zoom-subtree}). +This exposes the body and child subheadings, and narrows the buffer so +that only the @w{level-1} heading, the body and the level-2 headings are +visible. Now to look under one of the level-2 headings, position the +cursor on it and use @kbd{C-c C-z} again. This exposes the level-2 body +and its level-3 child subheadings and narrows the buffer again. Zooming +in on successive subheadings can be done as much as you like. A string +in the mode line shows how deep you've gone. + + When zooming in on a heading, to see only the child subheadings specify +a numeric argument: @kbd{C-u C-c C-z}. The number of levels of children +can be specified too (compare @kbd{M-x show-children}), e.g.@: @kbd{M-2 +C-c C-z} exposes two levels of child subheadings. Alternatively, the +body can be specified with a negative argument: @kbd{M-- C-c C-z}. The +whole subtree can be expanded, similarly to @kbd{C-c C-s} (@kbd{M-x +show-subtree}), by specifying a zero argument: @kbd{M-0 C-c C-z}. + + While you're zoomed in, you can still use Outline mode's exposure and +hiding functions without disturbing Foldout. Also, since the buffer is +narrowed, ``global'' editing actions will only affect text under the +zoomed-in heading. This is useful for restricting changes to a +particular chapter or section of your document. + +@kindex C-c C-x +@findex foldout-exit-fold + To unzoom (exit) a fold, use @kbd{C-c C-x} (@kbd{M-x foldout-exit-fold}). +This hides all the text and subheadings under the top-level heading and +returns you to the previous view of the buffer. Specifying a numeric +argument exits that many levels of folds. Specifying a zero argument +exits all folds. + + To cancel the narrowing of a fold without hiding the text and +subheadings, specify a negative argument. For example, @kbd{M--2 C-c +C-x} exits two folds and leaves the text and subheadings exposed. + + Foldout mode also provides mouse commands for entering and exiting +folds, and for showing and hiding text: + +@table @asis +@item @kbd{C-M-Mouse-1} zooms in on the heading clicked on +@itemize @asis +@item +single click: expose body. +@item +double click: expose subheadings. +@item +triple click: expose body and subheadings. +@item +quad click: expose entire subtree. +@end itemize +@item @kbd{C-M-Mouse-2} exposes text under the heading clicked on +@itemize @asis +@item +single click: expose body. +@item +double click: expose subheadings. +@item +triple click: expose body and subheadings. +@item +quad click: expose entire subtree. +@end itemize +@item @kbd{C-M-Mouse-3} hides text under the heading clicked on or exits fold +@itemize @asis +@item +single click: hide subtree. +@item +double click: exit fold and hide text. +@item +triple click: exit fold without hiding text. +@item +quad click: exit all folds and hide text. +@end itemize +@end table + +@vindex foldout-mouse-modifiers + You can specify different modifier keys (instead of +@kbd{Control-Meta-}) by setting @code{foldout-mouse-modifiers}; but if +you have already loaded the @file{foldout.el} library, you must reload +it in order for this to take effect. + + To use the Foldout package, you can type @kbd{M-x load-library +@key{RET} foldout @key{RET}}; or you can arrange for to do that +automatically by putting this in your @file{.emacs} file: + +@example +(eval-after-load "outline" '(require 'foldout)) +@end example + +@node TeX Mode +@section @TeX{} Mode +@cindex @TeX{} mode +@cindex La@TeX{} mode +@cindex Sli@TeX{} mode +@cindex Doc@TeX{} mode +@cindex mode, @TeX{} +@cindex mode, La@TeX{} +@cindex mode, Sli@TeX{} +@cindex mode, Doc@TeX{} +@findex tex-mode +@findex plain-tex-mode +@findex latex-mode +@findex slitex-mode +@findex doctex-mode + + @TeX{} is a powerful text formatter written by Donald Knuth; it is +also free software, 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{}.@footnote{Sli@TeX{} is +obsoleted by the @samp{slides} document class and other alternative +packages in recent La@TeX{} versions.} Doc@TeX{} (@file{.dtx}) is a +special file format in which the La@TeX{} sources are written, +combining sources with documentation. + + 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 four variants: Plain @TeX{} mode, La@TeX{} mode, +Sli@TeX{} mode, and Doc@TeX{} mode (these distinct major modes differ +only slightly). They are designed for editing the four 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, Sli@TeX{}, or Doc@TeX{} input; if so, it selects the +appropriate mode. If the file contents do not appear to be La@TeX{}, +Sli@TeX{} or Doc@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}, @kbd{M-x slitex-mode}, +and @kbd{doctex-mode} to select explicitly the particular variants of +@TeX{} mode. + +@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. +* Misc: TeX Misc. Customization of TeX mode, and related features. +@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 outputs 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}). +@item C-c C-c +Invoke some other compilation command on the entire current buffer +(@code{tex-compile}). +@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 @env{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 @env{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}. The default values 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. + +@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 + The value of the variable @code{tex-start-options} specifies +options for the @TeX{} run. + +@vindex tex-start-commands + The value of the variable @code{tex-start-commands} specifies @TeX{} +commands for starting @TeX{}. The default value causes @TeX{} to run +in nonstop mode. 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 @key{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 @key{TAB}} (@code{tex-bibtex-file}), and then repeat @kbd{C-c C-f} +(@code{tex-file}) twice more to get the cross-references correct. + +@findex tex-compile +@kindex C-c C-c @r{(@TeX{} mode)} + To invoke some other compilation program on the current @TeX{} +buffer, type @kbd{C-c C-c} (@code{tex-compile}). This command knows +how to pass arguments to many common programs, including +@file{pdflatex}, @file{yap}, @file{xdvi}, and @file{dvips}. You can +select your desired compilation program using the standard completion +keys (@pxref{Completion}). + +@node TeX Misc +@subsection @TeX{} Mode Miscellany + +@vindex tex-shell-hook +@vindex tex-mode-hook +@vindex latex-mode-hook +@vindex slitex-mode-hook +@vindex plain-tex-mode-hook + Entering any variant of @TeX{} mode runs the hooks +@code{text-mode-hook} and @code{tex-mode-hook}. Then it runs either +@code{plain-tex-mode-hook}, @code{latex-mode-hook}, or +@code{slitex-mode-hook}, whichever is appropriate. Starting the +@TeX{} shell runs the hook @code{tex-shell-hook}. @xref{Hooks}. + +@findex iso-iso2tex +@findex iso-tex2iso +@findex iso-iso2gtex +@findex iso-gtex2iso +@cindex Latin-1 @TeX{} encoding +@cindex @TeX{} encoding + The commands @kbd{M-x iso-iso2tex}, @kbd{M-x iso-tex2iso}, @kbd{M-x +iso-iso2gtex} and @kbd{M-x iso-gtex2iso} can be used to convert +between Latin-1 encoded files and @TeX{}-encoded equivalents. +@ignore +@c Too cryptic to be useful, too cryptic for me to make it better -- rms. + They +are included by default in the @code{format-alist} variable, so they +can be used with @kbd{M-x format-find-file}, for instance. +@end ignore + +@ignore @c Not worth documenting if it is only for Czech -- rms. +@findex tildify-buffer +@findex tildify-region +@cindex ties, @TeX{}, inserting +@cindex hard spaces, @TeX{}, inserting + The commands @kbd{M-x tildify-buffer} and @kbd{M-x tildify-region} +insert @samp{~} (@dfn{tie}) characters where they are conventionally +required. This is set up for Czech---customize the group +@samp{tildify} for other languages or for other sorts of markup. +@end ignore + +@cindex Ref@TeX{} package +@cindex references, La@TeX{} +@cindex La@TeX{} references + For managing all kinds of references for La@TeX{}, you can use +Ref@TeX{}. @inforef{Top,, reftex}. + +@node HTML Mode +@section SGML, XML, and HTML Modes + + The major modes for SGML and HTML include indentation support and +commands to operate on tags. This section describes the special +commands of these modes. (HTML mode is a slightly customized variant +of SGML mode.) + +@table @kbd +@item C-c C-n +@kindex C-c C-n @r{(SGML mode)} +@findex sgml-name-char +Interactively specify a special character and insert the SGML +@samp{&}-command for that character. + +@item C-c C-t +@kindex C-c C-t @r{(SGML mode)} +@findex sgml-tag +Interactively specify a tag and its attributes (@code{sgml-tag}). +This command asks you for a tag name and for the attribute values, +then inserts both the opening tag and the closing tag, leaving point +between them. + +With a prefix argument @var{n}, the command puts the tag around the +@var{n} words already present in the buffer after point. With +@minus{}1 as argument, it puts the tag around the region. (In +Transient Mark mode, it does this whenever a region is active.) + +@item C-c C-a +@kindex C-c C-a @r{(SGML mode)} +@findex sgml-attributes +Interactively insert attribute values for the current tag +(@code{sgml-attributes}). + +@item C-c C-f +@kindex C-c C-f @r{(SGML mode)} +@findex sgml-skip-tag-forward +Skip across a balanced tag group (which extends from an opening tag +through its corresponding closing tag) (@code{sgml-skip-tag-forward}). +A numeric argument acts as a repeat count. + +@item C-c C-b +@kindex C-c C-b @r{(SGML mode)} +@findex sgml-skip-tag-backward +Skip backward across a balanced tag group (which extends from an +opening tag through its corresponding closing tag) +(@code{sgml-skip-tag-forward}). A numeric argument acts as a repeat +count. + +@item C-c C-d +@kindex C-c C-d @r{(SGML mode)} +@findex sgml-delete-tag +Delete the tag at or after point, and delete the matching tag too +(@code{sgml-delete-tag}). If the tag at or after point is an opening +tag, delete the closing tag too; if it is a closing tag, delete the +opening tag too. + +@item C-c ? @var{tag} @key{RET} +@kindex C-c ? @r{(SGML mode)} +@findex sgml-tag-help +Display a description of the meaning of tag @var{tag} +(@code{sgml-tag-help}). If the argument @var{tag} is empty, describe +the tag at point. + +@item C-c / +@kindex C-c / @r{(SGML mode)} +@findex sgml-close-tag +Insert a close tag for the innermost unterminated tag +(@code{sgml-close-tag}). If called from within a tag or a comment, +close this element instead of inserting a close tag. + +@item C-c 8 +@kindex C-c 8 @r{(SGML mode)} +@findex sgml-name-8bit-mode +Toggle a minor mode in which Latin-1 characters insert the +corresponding SGML commands that stand for them, instead of the +characters themselves (@code{sgml-name-8bit-mode}). + +@item C-c C-v +@kindex C-c C-v @r{(SGML mode)} +@findex sgml-validate +Run a shell command (which you must specify) to validate the current +buffer as SGML (@code{sgml-validate}). + +@item C-c TAB +@kindex C-c TAB @r{(SGML mode)} +@findex sgml-tags-invisible +Toggle the visibility of existing tags in the buffer. This can be +used as a cheap preview. +@end table + +@vindex sgml-xml-mode + SGML mode and HTML mode support XML also. In XML, every opening tag +must have an explicit closing tag. When @code{sgml-xml-mode} is +non-@code{nil}, SGML mode and HTML mode always insert explicit +closing tags. When you visit a file, these modes determine from the +file contents whether it is XML or not, and set @code{sgml-xml-mode} +accordingly, so that they do the right thing for the file in either +case. + +@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-? +Displays 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}). It is +typically used in conjunction with Text mode (@pxref{Text Mode}), but +you can also use it with other major modes such as Outline mode and +Paragraph-Indent Text mode. + +@cindex text/enriched MIME format + 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 (known as @dfn{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-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. + + @xref{Text Properties,,, elisp, the Emacs Lisp Reference Manual}, +for more information about text properties. + +@node Hard and Soft Newlines +@subsection Hard and Soft Newlines +@cindex hard newline +@cindex soft newline +@cindex newlines, hard and soft + +@cindex use-hard-newlines + In formatted text, Emacs distinguishes between two different kinds of +newlines, @dfn{hard} newlines and @dfn{soft} newlines. (You can enable +or disable this feature separately in any buffer with the command +@code{use-hard-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 with the Text +Properties menu. You can get to this menu in two ways: from the Edit +menu in the menu bar (use @kbd{@key{F10} e t} if you have no mouse), +or with @kbd{C-Mouse-2} (hold the @key{CTRL} key and press the middle +mouse button). There are also keyboard commands described in the +following section. + + 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-face-props +@item Remove Face Properties +Delete from the region all face and color text properties +(@code{facemenu-remove-face-props}). + +@findex facemenu-remove-all +@item Remove Text Properties +Delete @emph{all} text properties from the region +(@code{facemenu-remove-all}). + +@findex describe-text-properties +@cindex text properties of characters +@cindex overlays at character position +@cindex widgets at buffer position +@cindex buttons at buffer position +@item Describe Properties +List all the text properties, widgets, buttons, and overlays of the +character following point (@code{describe-text-properties}). + +@item Display Faces +Display a list of all the defined faces (@code{list-faces-display}). + +@item Display Colors +Display a list of all the defined colors (@code{list-colors-display}). +@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} (@pxref{Faces}). These menu items +operate on the region if it is active and nonempty. Otherwise, they +specify to use that face for an immediately following self-inserting +character. Instead of the menu, you can use these keyboard commands: + +@table @kbd +@kindex M-o d @r{(Enriched mode)} +@findex facemenu-set-default +@item M-o d +Remove all @code{face} properties from the region (which includes +specified colors), or force the following inserted character to have no +@code{face} property (@code{facemenu-set-default}). +@kindex M-o b @r{(Enriched mode)} +@findex facemenu-set-bold +@item M-o b +Add the face @code{bold} to the region or to the following inserted +character (@code{facemenu-set-bold}). +@kindex M-o i @r{(Enriched mode)} +@findex facemenu-set-italic +@item M-o i +Add the face @code{italic} to the region or to the following inserted +character (@code{facemenu-set-italic}). +@kindex M-o l @r{(Enriched mode)} +@findex facemenu-set-bold-italic +@item M-o l +Add the face @code{bold-italic} to the region or to the following +inserted character (@code{facemenu-set-bold-italic}). +@kindex M-o u @r{(Enriched mode)} +@findex facemenu-set-underline +@item M-o u +Add the face @code{underline} to the region or to the following inserted +character (@code{facemenu-set-underline}). +@kindex M-o o @r{(Enriched mode)} +@findex facemenu-set-face +@item M-o o @var{face} @key{RET} +Add the face @var{face} to the region or to the following inserted +character (@code{facemenu-set-face}). +@end table + + With a prefix argument, all these commands apply to an immediately +following self-inserting character, disregarding the region. + + A self-inserting character normally inherits the @code{face} +property (and most other text properties) from the preceding character +in the buffer. If you use the above commands to specify face for the +next self-inserting character, or the next section's commands to +specify a foreground or background color for it, then it does not +inherit the @code{face} property from the preceding character; instead +it uses whatever you specified. It will still inherit other text +properties, though. + + Strictly speaking, these commands apply only to the first following +self-inserting character that you type. But if you insert additional +characters after it, they will inherit from the first one. So it +appears that these commands apply to all of them. + + 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 means, ``Use a fixed-width font for this part +of the text.'' Applying the @code{fixed} face to a part of the text +will cause that part of the text to appear in a fixed-width font, even +if the default font is variable-width. This applies to Emacs and to +other systems that display text/enriched format. 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. + + By default, the @code{fixed} face looks the same as @code{bold}. +This is an attempt to distinguish it from @code{default}. You may +wish to customize @code{fixed} to some other fixed-width medium font. +@xref{Face Customization}. + + If your terminal cannot display different faces, you will not be +able to see them, but you can still edit documents containing faces, +and even add faces and colors to documents. The faces you specify +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 any +immediately following self-inserting input. 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 a 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 the corresponding +color menu for the duration of the Emacs session. + +@findex facemenu-set-foreground +@findex facemenu-set-background + There are no predefined 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 them is to change the indentation of an +entire paragraph. For other uses, the effects of refilling can be +hard to predict, except in some special cases like the one described +next. + + The most common other use is 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. + +@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. + +@kindex C-c [ @r{(Enriched mode)} +@kindex C-c ] @r{(Enriched mode)} +@findex set-left-margin +@findex set-right-margin + There are also two commands for setting the left or right margin of +the region absolutely: @code{set-left-margin} and +@code{set-right-margin}. Enriched mode binds these commands to +@kbd{C-c [} and @kbd{C-c ]}, respectively. You can specify the +margin width either with a numeric argument or in the minibuffer. + + 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. + + 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 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 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 Unfilled +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 b @r{(Enriched mode)} +@findex set-justification-full +@item M-j b +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}. +This is a per-buffer variable. Setting the variable directly affects +only the current buffer. However, customizing it in a Custom buffer +sets (as always) the default value for buffers that do not override it. +@xref{Locals}, and @ref{Easy Customization}. + +@node Format Properties +@subsection Setting Other Text Properties + + The Special 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, sometimes 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. This also automatically turns on Enriched mode. + +@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 a 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. + +@node Text Based Tables +@section Editing Text-based Tables +@cindex table mode +@cindex text-based tables + + Table mode provides an easy and intuitive way to create and edit WYSIWYG +text-based tables. Here is an example of such a table: + +@smallexample +@group ++-----------------+--------------------------------+-----------------+ +| Command | Description | Key Binding | ++-----------------+--------------------------------+-----------------+ +| forward-char |Move point right N characters | C-f | +| |(left if N is negative). | | +| | | | +| |On reaching end of buffer, stop | | +| |and signal error. | | ++-----------------+--------------------------------+-----------------+ +| backward-char |Move point left N characters | C-b | +| |(right if N is negative). | | +| | | | +| |On attempt to pass beginning or | | +| |end of buffer, stop and signal | | +| |error. | | ++-----------------+--------------------------------+-----------------+ +@end group +@end smallexample + + Table mode allows the contents of the table such as this one to be +easily manipulated by inserting or deleting characters inside a cell. +A cell is effectively a localized rectangular edit region and edits to +a cell do not affect the contents of the surrounding cells. If the +contents do not fit into a cell, then the cell is automatically +expanded in the vertical and/or horizontal directions and the rest of +the table is restructured and reformatted in accordance with the +growth of the cell. + +@menu +* Table Definition:: What is a text based table. +* Table Creation:: How to create a table. +* Table Recognition:: How to activate and deactivate tables. +* Cell Commands:: Cell-oriented commands in a table. +* Cell Justification:: Justifying cell contents. +* Row Commands:: Manipulating rows of table cell. +* Column Commands:: Manipulating columns of table cell. +* Fixed Width Mode:: Fixing cell width. +* Table Conversion:: Converting between plain text and tables. +* Measuring Tables:: Analyzing table dimension. +* Table Misc:: Table miscellany. +@end menu + +@node Table Definition +@subsection What is a Text-based Table? + + Keep the following examples of valid tables in mind as a reference +while you read this section: + +@example + +--+----+---+ +-+ +--+-----+ + | | | | | | | | | + +--+----+---+ +-+ | +--+--+ + | | | | | | | | + +--+----+---+ +--+--+ | + | | | + +-----+--+ +@end example + + A table consists of a rectangular frame whose inside is divided into +cells. Each cell must be at least one character wide and one +character high, not counting its border lines. A cell can be +subdivided into multiple rectangular cells, but cells cannot overlap. + + The table frame and cell border lines are made of three special +characters. These variables specify those characters: + +@table @code +@vindex table-cell-vertical-char +@item table-cell-vertical-char +Holds the character used for vertical lines. The default value is +@samp{|}. + +@vindex table-cell-horizontal-char +@item table-cell-horizontal-char +Holds the character used for horizontal lines. The default value is +@samp{-}. + +@vindex table-cell-intersection-char +@item table-cell-intersection-char +Holds the character used at where horizontal line and vertical line +meet. The default value is @samp{+}. +@end table + +@noindent +Based on this definition, the following five tables are examples of invalid +tables: + +@example + +-----+ +-----+ +--+ +-++--+ ++ + | | | | | | | || | ++ + | +-+ | | | | | | || | + | | | | +--+ | +--+--+ +-++--+ + | +-+ | | | | | | | +-++--+ + | | | | | | | | | || | + +-----+ +--+--+ +--+--+ +-++--+ + a b c d e +@end example + +From left to right: + +@enumerate a +@item +Overlapped cells or non-rectangular cells are not allowed. +@item +Same as a. +@item +The border must be rectangular. +@item +Cells must have a minimum width/height of one character. +@item +Same as d. +@end enumerate + +@node Table Creation +@subsection How to Create a Table? +@cindex create a text-based table +@cindex table creation + +@findex table-insert + The command to create a table is @code{table-insert}. When called +interactively, it asks for the number of columns, number of rows, cell +width and cell height. The number of columns is the number of cells +horizontally side by side. The number of rows is the number of cells +vertically within the table's height. The cell width is a number of +characters that each cell holds, left to right. The cell height is a +number of lines each cell holds. The cell width and the cell height +can be either an integer (when the value is constant across the table) +or a series of integer, separated by spaces or commas, where each +number corresponds to the next cell within a row from left to right, +or the next cell within a column from top to bottom. + +@node Table Recognition +@subsection Table Recognition +@cindex table recognition + +@findex table-recognize +@findex table-unrecognize + Table mode maintains special text properties in the buffer to allow +editing in a convenient fashion. When a buffer with tables is saved +to its file, these text properties are lost, so when you visit this +file again later, Emacs does not see a table, but just formatted text. +To resurrect the table text properties, issue the @kbd{M-x +table-recognize} command. It scans the current buffer, recognizes +valid table cells, and attaches appropriate text properties to allow +for table editing. The converse command, @code{table-unrecognize}, is +used to remove the special text properties and convert the buffer back +to plain text. + + Special commands exist to enable or disable tables within a region, +enable or disable individual tables, and enable/disable individual +cells. These commands are: + +@table @kbd +@findex table-recognize-region +@item M-x table-recognize-region +Recognize tables within the current region and activate them. +@findex table-unrecognize-region +@item M-x table-unrecognize-region +Deactivate tables within the current region. +@findex table-recognize-table +@item M-x table-recognize-table +Recognize the table under point and activate it. +@findex table-unrecognize-table +@item M-x table-unrecognize-table +Deactivate the table under point. +@findex table-recognize-cell +@item M-x table-recognize-cell +Recognize the cell under point and activate it. +@findex table-unrecognize-cell +@item M-x table-unrecognize-cell +Deactivate the cell under point. +@end table + + For another way of converting text into tables, see @ref{Table +Conversion}. + +@node Cell Commands +@subsection Commands for Table Cells + +@findex table-forward-cell +@findex table-backward-cell + The commands @code{table-forward-cell} and +@code{table-backward-cell} move point from the current cell to an +adjacent cell forward and backward respectively. The order of the +cells is cyclic: when point is in the last cell of a table, typing +@kbd{M-x table-forward-cell} moves to the first cell in the table. +Likewise @kbd{M-x table-backward-cell} from the first cell in a table +moves to the last cell. + +@findex table-span-cell + The command @code{table-span-cell} merges the current cell with the +adjacent cell in a specified direction---right, left, above or below. +You specify the direction with the minibuffer. It does not allow +merges which don't result in a legitimate cell layout. + +@findex table-split-cell +@cindex text-based tables, split a cell +@cindex split table cell + The command @code{table-split-cell} splits the current cell +vertically or horizontally. This command is a wrapper to the +direction specific commands @code{table-split-cell-vertically} and +@code{table-split-cell-horizontally}. You specify the direction with +a minibuffer argument. + +@findex table-split-cell-vertically + The command @code{table-split-cell-vertically} splits the current +cell vertically and creates a pair of cells above and below where +point is located. The content in the original cell is split as well. + +@findex table-split-cell-horizontally + The command @code{table-split-cell-horizontally} splits the current +cell horizontally and creates a pair of cells right and left of where +point is located. If the cell being split is not empty, this asks you +how to handle the cell contents. The three options are: @code{split}, +@code{left}, or @code{right}. @code{split} splits the contents at +point literally, while the @code{left} and @code{right} options move +the entire contents into the left or right cell respectively. + +@cindex enlarge a table cell +@cindex shrink a table cell + The next four commands enlarge or shrink a cell. They use numeric +arguments (@pxref{Arguments}) to specify how many columns or rows to +enlarge or shrink a particular table. + +@table @kbd +@findex table-heighten-cell +@item M-x table-heighten-cell +Enlarge the current cell vertically. +@findex table-shorten-cell +@item M-x table-shorten-cell +Shrink the current cell vertically. +@findex table-widen-cell +@item M-x table-widen-cell +Enlarge the current cell horizontally. +@findex table-narrow-cell +@item M-x table-narrow-cell +Shrink the current cell horizontally. +@end table + +@node Cell Justification +@subsection Cell Justification +@cindex cell text justification + + You can specify text justification for each cell. The justification +is remembered independently for each cell and the subsequent editing +of cell contents is subject to the specified justification. + +@findex table-justify + The command @code{table-justify} ask you to specify what to justify: +a cell, a column, or a row. If you select cell justification, this +command sets the justification only for the current cell. Selecting +column or row justification sets the justification for all the cells +within a column or row respectively. The command then ask you which +kind of justification to apply: @code{left}, @code{center}, +@code{right}, @code{top}, @code{middle}, @code{bottom}, or +@code{none}. Horizontal justification and vertical justification are +specified independently. The options @code{left}, @code{center}, and +@code{right} specify horizontal justification while the options +@code{top}, @code{middle}, @code{bottom}, and @code{none} specify +vertical justification. The vertical justification @code{none} +effectively removes vertical justification. Horizontal justification +must be one of @code{left}, @code{center}, or @code{right}. + +@vindex table-detect-cell-alignment + Justification information is stored in the buffer as a part of text +property. Therefore, this information is ephemeral and does not +survive through the loss of the buffer (closing the buffer and +revisiting the buffer erase any previous text properties). To +countermand for this, the command @code{table-recognize} and other +recognition commands (@pxref{Table Recognition}) are equipped with a +convenience feature (turned on by default). During table recognition, +the contents of a cell are examined to determine which justification +was originally applied to the cell and then applies this justification +to the cell. This is a speculative algorithm and is therefore not +perfect, however, the justification is deduced correctly most of the +time. To disable this feature, customize the variable +@code{table-detect-cell-alignment} and set it to @code{nil}. + +@node Row Commands +@subsection Commands for Table Rows +@cindex table row commands + +@cindex insert row in table +@findex table-insert-row + The command @code{table-insert-row} inserts a row of cells before +the current row in a table. The current row where point is located is +pushed down after the newly inserted row. A numeric prefix argument +specifies the number of rows to insert. Note that in order to insert +rows @emph{after} the last row at the bottom of a table, you must +place point below the table---that is, outside the table---prior to +invoking this command. + +@cindex delete row in table +@findex table-delete-row + The command @code{table-delete-row} deletes a row of cells at point. +A numeric prefix argument specifies the number of rows to delete. + +@node Column Commands +@subsection Commands for Table Columns +@cindex table column commands + +@cindex insert column in table +@findex table-insert-column + The command @code{table-insert-column} inserts a column of cells to +the left of the current row in a table. This pushes the current +column to the right. To insert a column to the right side of the +rightmost column, place point to the right of the rightmost column, +which is outside of the table, prior to invoking this command. A +numeric prefix argument specifies the number of columns to insert. + +@cindex delete column in table + A command @code{table-delete-column} deletes a column of cells at +point. A numeric prefix argument specifies the number of columns to +delete. + +@node Fixed Width Mode +@subsection Fix Width of Cells +@cindex fix width of table cells + +@findex table-fixed-width-mode + The command @code{table-fixed-width-mode} toggles fixed width mode +on and off. When fixed width mode is turned on, editing inside a +cell never changes the cell width; when it is off, the cell width +expands automatically in order to prevent a word from being folded +into multiple lines. By default, fixed width mode is disabled. + +@node Table Conversion +@subsection Conversion Between Plain Text and Tables +@cindex text to table +@cindex table to text + +@findex table-capture + The command @code{table-capture} captures plain text in a region and +turns it into a table. Unlike @code{table-recognize} (@pxref{Table +Recognition}), the original text does not have a table appearance but +may hold a logical table structure. For example, some elements +separated by known patterns form a two dimensional structure which can +be turned into a table. + + Here's an example of data that @code{table-capture} can operate on. +The numbers are horizontally separated by a comma and vertically +separated by a newline character. + +@example +1, 2, 3, 4 +5, 6, 7, 8 +, 9, 10 +@end example + +@noindent +Invoking @kbd{M-x table-capture} on that text produces this table: + +@example ++-----+-----+-----+-----+ +|1 |2 |3 |4 | ++-----+-----+-----+-----+ +|5 |6 |7 |8 | ++-----+-----+-----+-----+ +| |9 |10 | | ++-----+-----+-----+-----+ +@end example + +@noindent +The conversion uses @samp{,} for the column delimiter and newline for +a row delimiter, cells are left justified, and minimum cell width is +5. + +@findex table-release + The command @code{table-release} does the opposite of +@code{table-capture}. It releases a table by removing the table frame +and cell borders. This leaves the table contents as plain text. One +of the useful applications of @code{table-capture} and +@code{table-release} is to edit a text in layout. Look at the +following three paragraphs (the latter two are indented with header +lines): + +@example +@samp{table-capture} is a powerful command, but mastering its +power requires some practice. Here are some things it can do: + +Parse Cell Items By using column delimiter regular + expression and raw delimiter regular + expression, it parses the specified text + area and extracts cell items from + non-table text and then forms a table out + of them. + +Capture Text Area When no delimiters are specified it + creates a single cell table. The text in + the specified region is placed in that + cell. +@end example + +@noindent +Applying @code{table-capture} to a region containing the above three +paragraphs, with empty strings for column delimiter regexp and row +delimiter regexp, creates a table with a single cell like the +following one. + +@c The first line's right-hand frame in the following two examples +@c sticks out to accommodate for the removal of @samp in the +@c produced output!! +@smallexample +@group ++-----------------------------------------------------------------+ +|@samp{table-capture} is a powerful command, but mastering its | +|power requires some practice. Here are some things it can do: | +| | +|Parse Cell Items By using column delimiter regular | +| expression and raw delimiter regular | +| expression, it parses the specified text | +| area and extracts cell items from | +| non-table text and then forms a table out | +| of them. | +| | +|Capture Text Area When no delimiters are specified it | +| creates a single cell table. The text in | +| the specified region is placed in that | +| cell. | ++-----------------------------------------------------------------+ +@end group +@end smallexample + +@noindent +By splitting the cell appropriately we now have a table consisting of +paragraphs occupying its own cell. Each cell can now be edited +independently without affecting the layout of other cells. + +@smallexample ++-----------------------------------------------------------------+ +|@samp{table-capture} is a powerful command, but mastering its | +|power requires some practice. Here are some things it can do: | ++---------------------+-------------------------------------------+ +|Parse Cell Items |By using column delimiter regular | +| |expression and raw delimiter regular | +| |expression, it parses the specified text | +| |area and extracts cell items from | +| |non-table text and then forms a table out | +| |of them. | ++---------------------+-------------------------------------------+ +|Capture Text Area |When no delimiters are specified it | +| |creates a single cell table. The text in | +| |the specified region is placed in that | +| |cell. | ++---------------------+-------------------------------------------+ +@end smallexample + +@noindent +By applying @code{table-release}, which does the opposite process, the +contents become once again plain text. @code{table-release} works as +a companion command to @code{table-capture}. + +@node Measuring Tables +@subsection Analyzing Table Dimensions +@cindex table dimensions + +@findex table-query-dimension + The command @code{table-query-dimension} analyzes a table structure +and reports information regarding its dimensions. In case of the +above example table, the @code{table-query-dimension} command displays +in echo area: + +@smallexample +Cell: (21w, 6h), Table: (67w, 16h), Dim: (2c, 3r), Total Cells: 5 +@end smallexample + +@noindent +This indicates that the current cell is 21 character wide and 6 lines +high, the entire table is 67 characters wide and 16 lines high. The +table has 2 columns and 3 rows. It has a total of 5 cells, since the +first row has a spanned cell. + +@node Table Misc +@subsection Table Miscellany + +@cindex insert string into table cells +@findex table-insert-sequence + The command @code{table-insert-sequence} inserts a string into each +cell. Each string is a part of a sequence i.e.@: a series of +increasing integer numbers. + +@cindex table in language format +@cindex table for HTML and LaTeX +@findex table-generate-source + The command @code{table-generate-source} generates a table formatted +for a specific markup language. It asks for a language (which must be +one of @code{html}, @code{latex}, or @code{cals}), a destination +buffer where to put the result, and the table caption (a string), and +then inserts the generated table in the proper syntax into the +destination buffer. The default destination buffer is +@code{table.@var{lang}}, where @var{lang} is the language you +specified. + +@ignore + arch-tag: 8db54ed8-2036-49ca-b0df-23811d03dc70 +@end ignore diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi new file mode 100644 index 00000000000..ea494445a4e --- /dev/null +++ b/doc/emacs/trouble.texi @@ -0,0 +1,1066 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2001, 2002, +@c 2003, 2004, 2005, 2006, 2007 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 + +@ifnottex +@raisesections +@end ifnottex + +@node Quitting, Lossage, Customization, Top +@section Quitting and Aborting +@cindex quitting + +@table @kbd +@item C-g +@itemx C-@key{BREAK} @r{(MS-DOS only)} +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 a command before it has finished: +@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 still 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 the way to get 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 a kill command; 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; 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. +@iftex +@xref{MS-DOS Keyboard,,,emacs-xtra, Specialized Emacs Features}. +@end iftex +@ifnottex +@xref{MS-DOS Keyboard}. +@end ifnottex + + +@findex keyboard-quit + @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. In that case, the command it runs is @code{keyboard-quit}. + + On a text terminal, 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 are some situations where 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 a case not handled. In one very common +case---waiting for file input or output using NFS---Emacs itself knows +how to quit, but many 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 sequence @kbd{@key{ESC} @key{ESC} @key{ESC}} +(@code{keyboard-escape-quit}) can either quit or abort. (We defined +it this way because @key{ESC} means ``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, as with @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 the next 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}, for more information +about the undo facility. + +@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. For a list of +additional problems you might encounter, see @ref{Bugs and problems, , +Bugs and problems, efaq, GNU Emacs FAQ}, and the file @file{etc/PROBLEMS} +in the Emacs distribution. Type @kbd{C-h C-f} to read the FAQ; type +@kbd{C-h C-e} to read the @file{PROBLEMS} file. + +@menu +* DEL Does Not Delete:: 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. +* 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 Does Not Delete +@subsection If @key{DEL} Fails to Delete +@cindex @key{DEL} vs @key{BACKSPACE} +@cindex @key{BACKSPACE} vs @key{DEL} +@cindex usual erasure key + + Every keyboard has a large key, a little ways above the @key{RET} or +@key{ENTER} key, which you normally use outside Emacs to erase the +last character that you typed. We call this key @dfn{the usual +erasure key}. In Emacs, it is supposed to be equivalent to @key{DEL}, +and when Emacs is properly configured for your terminal, it translates +that key into the character @key{DEL}. + + When Emacs starts up on a graphical display, it determines +automatically which key should be @key{DEL}. In some unusual cases +Emacs gets the wrong information from the system. If the usual +erasure key deletes forwards instead of backwards, that is probably +what happened---Emacs ought to be treating the @key{DELETE} key as +@key{DEL}, but it isn't. + + On a graphical display, if the usual erasure key is labeled +@key{BACKSPACE} and there is a @key{DELETE} key elsewhere, but the +@key{DELETE} key deletes backward instead of forward, that too +suggests Emacs got the wrong information---but in the opposite sense. +It ought to be treating the @key{BACKSPACE} key as @key{DEL}, and +treating @key{DELETE} differently, but it isn't. + + On a text-only terminal, if you find the usual erasure key prompts +for a Help command, like @kbd{Control-h}, instead of deleting a +character, it means that key is actually sending the @key{BS} +character. Emacs ought to be treating @key{BS} as @key{DEL}, but it +isn't. + + In all of those cases, the immediate remedy is the same: use the +command @kbd{M-x normal-erase-is-backspace-mode}. This toggles +between the two modes that Emacs supports for handling @key{DEL}, so +if Emacs starts in the wrong mode, this should switch to the right +mode. On a text-only terminal, if you want to ask for help when +@key{BS} is treated as @key{DEL}, use @key{F1}; @kbd{C-?} may also +work, if it sends character code 127. + +@findex normal-erase-is-backspace-mode + To fix the problem automatically for every Emacs session, you can +put one of the following lines into your @file{.emacs} file +(@pxref{Init File}). For the first case above, where @key{DELETE} +deletes forwards instead of backwards, use this line to make +@key{DELETE} act as @key{DEL} (resulting in behavior compatible +with Emacs 20 and previous versions): + +@lisp +(normal-erase-is-backspace-mode 0) +@end lisp + +@noindent +For the other two cases, where @key{BACKSPACE} ought to act as +@key{DEL}, use this line: + +@lisp +(normal-erase-is-backspace-mode 1) +@end lisp + +@vindex normal-erase-is-backspace + Another way to fix the problem for every Emacs session is to +customize the variable @code{normal-erase-is-backspace}: the value +@code{t} specifies the mode where @key{BS} or @key{BACKSPACE} is +@key{DEL}, and @code{nil} specifies the other mode. @xref{Easy +Customization}. + + On a graphical display, it can also happen that the usual erasure key +is labeled @key{BACKSPACE}, there is a @key{DELETE} key elsewhere, and +both keys delete forward. This probably means that someone has +redefined your @key{BACKSPACE} key as a @key{DELETE} key. With X, +this is typically done with a command to the @code{xmodmap} program +when you start the server or log in. The most likely motive for this +customization was to support old versions of Emacs, so we recommend +you simply remove it now. + +@node Stuck Recursive +@subsection Recursive Editing Levels + + Recursive editing levels are important and useful features of Emacs, but +they can seem like malfunctions if you do 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 text on a text terminal looks wrong, the first thing to do is +see whether it is wrong in the buffer. 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 +the following section.) + + Display updating problems often result from an incorrect terminfo +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. 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 terminfo 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, first type @kbd{C-h l} to +see what commands you typed to produce the observed results. Then try +undoing the changes step by step using @kbd{C-x u}, until it gets back +to a state you consider correct. + + 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 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. When the +reserve has been used, @samp{!MEM FULL!} appears at the beginning of +the mode line, indicating there is no more reserve. + + Once you have saved your modified buffers, you can exit this Emacs +session and start another, or you can use @kbd{M-x kill-some-buffers} +to free space in the current Emacs job. If this frees up sufficient +space, Emacs will refill its memory reserve, and @samp{!MEM FULL!} +will disappear from the mode line. That means you can safely go on +editing in the same Emacs session. + + 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 of 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} considers each of the files that you +were editing during that session; for each such file, 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. + + As a last resort, if you had buffers with content which were not +associated with any files, or if the autosave was not recent enough to +have recorded important changes, you can use the +@file{etc/emacs-buffer.gdb} script with GDB (the GNU Debugger) to +retrieve them from a core dump--provided that a core dump was saved, +and that the Emacs executable was not stripped of its debugging +symbols. + + As soon as you get the core dump, rename it to another name such as +@file{core.emacs}, so that another crash won't overwrite it. + + To use this script, run @code{gdb} with the file name of your Emacs +executable and the file name of the core dump, e.g. @samp{gdb +/usr/bin/emacs core.emacs}. At the @code{(gdb)} prompt, load the +recovery script: @samp{source /usr/src/emacs/etc/emacs-buffer.gdb}. +Then type the command @code{ybuffer-list} to see which buffers are +available. For each buffer, it lists a buffer number. To save a +buffer, use @code{ysave-buffer}; you specify the buffer number, and +the file name to write that buffer into. You should use a file name +which does not already exist; if the file does exist, the script does +not make a backup of its old contents. + +@node Emergency Escape +@subsection Emergency Escape + + On text-only terminals, the @dfn{emergency escape} feature suspends +Emacs immediately if you type @kbd{C-g} a second time before Emacs can +actually respond to the first one by quitting. This is so you can +always get out of GNU Emacs no matter how badly it might be hung. +When things are working properly, Emacs recognizes and handles the +first @kbd{C-g} so fast that the second one won't trigger emergency +escape. However, if some problem prevents Emacs from handling the +first @kbd{C-g} properly, then the second one will get you back to the +shell. + + When you resume Emacs after a suspension caused by emergency escape, +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{n} +skips this. + + Saying @kbd{y} to @samp{Abort (and dump core)?} causes Emacs to +crash, 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 this question @kbd{n}, Emacs execution resumes. With +luck, Emacs will ultimately do the requested quit. If not, each +subsequent @kbd{C-g} invokes emergency escape 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 get back to the former +state. The quit you requested will happen by and by. + + Emergency escape is active only for text terminals. On graphical +displays, you can use the mouse to kill Emacs or switch to another +program. + + On MS-DOS, you must type @kbd{C-@key{BREAK}} (twice) to cause +emergency escape---but there are cases where it won't work, when +system call hangs or when Emacs is stuck in a tight loop in C 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 Emacs psychotherapist will help you feel better. Each time you +say something to the psychotherapist, you must end it by typing +@key{RET} @key{RET}. This indicates you are finished typing. + +@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. + + Before reporting a bug, it is a good idea to see if it is already +known. You can find the list of known problems in the file +@file{etc/PROBLEMS} in the Emacs distribution; type @kbd{C-h C-e} to read +it. Some additional user-level problems can be found in @ref{Bugs and +problems, , Bugs and problems, efaq, GNU Emacs FAQ}. Looking up your +problem in these two documents might provide you with a solution or a +work-around, or give you additional information about related issues. + +@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 accesses an invalid memory location (``segmentation +fault''), or exits 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 the best +possible definition 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. Ask other Emacs users, too. 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 displays @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. + + 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 @email{bug-gnu-emacs@@gnu.org}, or to +@email{emacs-pretest-bug@@gnu.org} if you are pretesting an Emacs beta +release. (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 fairly +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 your data is more than +500,000 bytes, please don't include it directly in the bug report; +instead, offer to send it on request, or make it available by ftp and +say where. + +@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 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 +@cindex logging keystrokes +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 @env{TERM} environment variable +For possible display bugs, the terminal type (the value of environment +variable @env{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. + +@item +If non-@acronym{ASCII} text or internationalization is relevant, the locale that +was current when you started Emacs. On GNU/Linux and Unix systems, or +if you use a Posix-style shell such as Bash, you can use this shell +command to view the relevant values: + +@smallexample +echo LC_ALL=$LC_ALL LC_COLLATE=$LC_COLLATE LC_CTYPE=$LC_CTYPE \ + LC_MESSAGES=$LC_MESSAGES LC_TIME=$LC_TIME LANG=$LANG +@end smallexample + +Alternatively, use the @command{locale} command, if your system has it, +to display your locale settings. + +You can use the @kbd{M-!} command to execute these commands from +Emacs, and then copy the output from the @samp{*Messages*} buffer into +the bug report. Alternatively, @kbd{M-x getenv @key{RET} LC_ALL +@key{RET}} will display the value of @code{LC_ALL} in the echo area, and +you can copy its output from the @samp{*Messages*} buffer. + +@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 bug is that the Emacs Manual or the Emacs Lisp Reference Manual +fails to describe the actual behavior of Emacs, or that the text is +confusing, copy in the text from the online manual which you think is +at fault. If the section is small, just the section name is enough. + +@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. + +@findex toggle-debug-on-error +@pindex Edebug +To make a backtrace for the error, use @kbd{M-x toggle-debug-on-error} +before the error happens (that is to say, you must give that command +and then make the bug happen). This causes the error to start the Lisp +debugger, which shows you a backtrace. Copy the text of the +debugger's backtrace into the bug report. @xref{Debugger,, The Lisp +Debugger, elisp, the Emacs Lisp Reference Manual}, for information on +debugging Emacs Lisp programs with the Edebug package. + +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}. + +For a short listing of Lisp functions running, type the GDB +command @code{xbacktrace}. + +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. + +@cindex debugging Emacs, tricks and techniques +More detailed advice and other useful techniques for debugging Emacs +are available in the file @file{etc/DEBUG} in the Emacs distribution. +That file also includes instructions for investigating problems +whereby Emacs stops responding (many people assume that Emacs is +``hung,'' whereas in fact it might be in an infinite loop). + +To find the file @file{etc/DEBUG} in your Emacs installation, use the +directory name stored in the variable @code{data-directory}. +@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. +It is better to send the bug report right away, go back to editing, +and find another bug to report. + +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 core dump file. + +Debugging the core dump might be useful, but it can only be done on +your machine, with your Emacs executable. Therefore, sending the core +dump file to the Emacs maintainers won't be useful. Above all, don't +include the core file in an email bug report! Such a large message +can be extremely inconvenient. + +@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. + +@ifnottex +@xref{Sending Patches}, for guidelines on how to make it easy for us to +understand and install your patches. +@end ifnottex + +@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. @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 @email{emacs-devel@@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 +@email{emacs-devel@@gnu.org} before you start; it might be +possible to suggest ways to make your extension fit in better with the +rest of Emacs. + +The development version of Emacs can be downloaded from the CVS +repository where it is actively maintained by a group of developers. +See the Emacs project page +@url{http://savannah.gnu.org/projects/emacs/} for details. + +@node Service, Copying, 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 +@email{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 + +@ifnottex +@lowersections +@end ifnottex + +@ignore + arch-tag: c9cba76d-b2cb-4e0c-ae3f-19d5ef35817c +@end ignore diff --git a/doc/emacs/vc-xtra.texi b/doc/emacs/vc-xtra.texi new file mode 100644 index 00000000000..6ec69d60896 --- /dev/null +++ b/doc/emacs/vc-xtra.texi @@ -0,0 +1,32 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@c +@c This file is included in emacs-xtra.texi when producing the printed +@c version. +@iftex +@node Advanced VC Usage +@section Advanced VC Usage + + Commonly used features of Emacs' version control (VC) support are +described in the main Emacs manual (@pxref{Version Control,,,emacs, +the Emacs Manual}). This chapter describes more advanced VC usage. + +@menu +* VC Dired Mode:: Listing files managed by version control. +* VC Dired Commands:: Commands to use in a VC Dired buffer. +* Remote Repositories:: Efficient access to remote CVS servers. +* 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 +@end iftex + +@iftex +@include vc1-xtra.texi +@include vc2-xtra.texi +@end iftex + +@ignore + arch-tag: 11a18d0e-1baf-49da-8e38-f61195ae4dc3 +@end ignore diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi new file mode 100644 index 00000000000..6d5df78848c --- /dev/null +++ b/doc/emacs/vc1-xtra.texi @@ -0,0 +1,151 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@c +@c This file is included either in vc-xtra.texi (when producing the +@c printed version) or in the main Emacs manual (for the on-line version). +@node VC Dired Mode +@subsection Dired under VC + +@cindex PCL-CVS +@pindex cvs +@cindex CVS Dired Mode + The VC Dired Mode described here works with all the version control +systems that VC supports. Another more powerful facility, designed +specifically for CVS, is called PCL-CVS. @xref{Top, , About PCL-CVS, +pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}. + +@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 +@iftex +(@pxref{Dired,,,emacs, the Emacs Manual}); +@end iftex +@ifnottex +(@pxref{Dired}); +@end ifnottex +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-stay-local +@vindex vc-cvs-stay-local + In the above, if the repository were on a remote machine, VC would +only contact it when the variable @code{vc-stay-local} (or +@code{vc-cvs-stay-local}) is nil (@pxref{CVS Options}). This is +because access to the repository may be slow, or you may be working +offline and not have access to the repository at all. As a +consequence, VC would not be able to tell you that @samp{file3.c} is +in the ``merge'' state; you would learn that only when you try to +check-in your modified copy of the file, or use a command such as +@kbd{C-x v m}. + + In practice, this is not a problem because CVS handles this case +consistently whenever it arises. In VC, you'll simply get prompted to +merge the remote changes into your work file first. The benefits of +less network communication usually outweigh the disadvantage of not +seeing remote changes immediately. + +@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 +@subsection 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 no +files are marked, @kbd{v v} operates on the file in the current line. + + 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. + +@ignore + arch-tag: 8e8c2a01-ad41-4e61-a89a-60131ad67263 +@end ignore diff --git a/doc/emacs/vc2-xtra.texi b/doc/emacs/vc2-xtra.texi new file mode 100644 index 00000000000..83f28088726 --- /dev/null +++ b/doc/emacs/vc2-xtra.texi @@ -0,0 +1,789 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@c +@c This file is included either in vc-xtra.texi (when producing the +@c printed version) or in the main Emacs manual (for the on-line version). +@node Remote Repositories +@subsection Remote Repositories +@cindex remote repositories (CVS) + + A common way of using CVS is to set up a central CVS repository on +some Internet host, then have each developer check out a personal +working copy of the files on his local machine. Committing changes to +the repository, and picking up changes from other users into one's own +working area, then works by direct interactions with the CVS server. + + One difficulty is that access to the CVS server is often slow, and +that developers might need to work off-line as well. VC is designed +to reduce the amount of network interaction necessary. + +@menu +* Version Backups:: Keeping local copies of repository versions. +* Local Version Control:: Using another version system for local editing. +@end menu + +@node Version Backups +@subsubsection Version Backups +@cindex version backups + +@cindex automatic version backups + When VC sees that the CVS repository for a file is on a remote +machine, it automatically makes local backups of unmodified versions +of the file---@dfn{automatic version backups}. This means that you +can compare the file to the repository version (@kbd{C-x v =}), or +revert to that version (@kbd{C-x v u}), without any network +interactions. + + The local copy of the unmodified file is called a @dfn{version +backup} to indicate that it corresponds exactly to a version that is +stored in the repository. Note that version backups are not the same +as ordinary Emacs backup files +@iftex +(@pxref{Backup,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Backup}). +@end ifnottex +But they follow a similar naming convention. + + For a file that comes from a remote CVS repository, VC makes a +version backup whenever you save the first changes to the file, and +removes it after you have committed your modified version to the +repository. You can disable the making of automatic version backups by +setting @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS Options}). + +@cindex manual version backups + The name of the automatic version backup for version @var{version} +of file @var{file} is @code{@var{file}.~@var{version}.~}. This is +almost the same as the name used by @kbd{C-x v ~} +@iftex +(@pxref{Old Versions,,,emacs, the Emacs Manual}), +@end iftex +@ifnottex +(@pxref{Old Versions}), +@end ifnottex +the only difference being the additional dot (@samp{.}) after the +version number. This similarity is intentional, because both kinds of +files store the same kind of information. The file made by @kbd{C-x v +~} acts as a @dfn{manual version backup}. + + All the VC commands that operate on old versions of a file can use +both kinds of version backups. For instance, @kbd{C-x v ~} uses +either an automatic or a manual version backup, if possible, to get +the contents of the version you request. Likewise, @kbd{C-x v =} and +@kbd{C-x v u} use either an automatic or a manual version backup, if +one of them exists, to get the contents of a version to compare or +revert to. If you changed a file outside of Emacs, so that no +automatic version backup was created for the previous text, you can +create a manual backup of that version using @kbd{C-x v ~}, and thus +obtain the benefit of the local copy for Emacs commands. + + The only difference in Emacs's handling of manual and automatic +version backups, once they exist, is that Emacs deletes automatic +version backups when you commit to the repository. By contrast, +manual version backups remain until you delete them. + +@node Local Version Control +@subsubsection Local Version Control +@cindex local version control +@cindex local back end (version control) + +When you make many changes to a file that comes from a remote +repository, it can be convenient to have version control on your local +machine as well. You can then record intermediate versions, revert to +a previous state, etc., before you actually commit your changes to the +remote server. + +VC lets you do this by putting a file under a second, local version +control system, so that the file is effectively registered in two +systems at the same time. For the description here, we will assume +that the remote system is CVS, and you use RCS locally, although the +mechanism works with any combination of version control systems +(@dfn{back ends}). + +To make it work with other back ends, you must make sure that the +``more local'' back end comes before the ``more remote'' back end in +the setting of @code{vc-handled-backends} (@pxref{Customizing VC}). By +default, this variable is set up so that you can use remote CVS and +local RCS as described here. + +To start using local RCS for a file that comes from a remote CVS +server, you must @emph{register the file in RCS}, by typing @kbd{C-u +C-x v v rcs @key{RET}}. (In other words, use @code{vc-next-action} with a +prefix argument, and specify RCS as the back end.) + +You can do this at any time; it does not matter whether you have +already modified the file with respect to the version in the CVS +repository. If possible, VC tries to make the RCS master start with +the unmodified repository version, then checks in any local changes +as a new version. This works if you have not made any changes yet, or +if the unmodified repository version exists locally as a version +backup (@pxref{Version Backups}). If the unmodified version is not +available locally, the RCS master starts with the modified version; +the only drawback to this is that you cannot compare your changes +locally to what is stored in the repository. + +The version number of the RCS master is derived from the current CVS +version, starting a branch from it. For example, if the current CVS +version is 1.23, the local RCS branch will be 1.23.1. Version 1.23 in +the RCS master will be identical to version 1.23 under CVS; your first +changes are checked in as 1.23.1.1. (If the unmodified file is not +available locally, VC will check in the modified file twice, both as +1.23 and 1.23.1.1, to make the revision numbers consistent.) + +If you do not use locking under CVS (the default), locking is also +disabled for RCS, so that editing under RCS works exactly as under +CVS. + +When you are done with local editing, you can commit the final version +back to the CVS repository by typing @kbd{C-u C-x v v cvs @key{RET}}. +This initializes the log entry buffer +@iftex +(@pxref{Log Buffer,,,emacs, the Emacs Manual}) +@end iftex +@ifnottex +(@pxref{Log Buffer}) +@end ifnottex +to contain all the log entries you have recorded in the RCS master; +you can edit them as you wish, and then commit in CVS by typing +@kbd{C-c C-c}. If the commit is successful, VC removes the RCS +master, so that the file is once again registered under CVS only. +(The RCS master is not actually deleted, just renamed by appending +@samp{~} to the name, so that you can refer to it later if you wish.) + +While using local RCS, you can pick up recent changes from the CVS +repository into your local file, or commit some of your changes back +to CVS, without terminating local RCS version control. To do this, +switch to the CVS back end temporarily, with the @kbd{C-x v b} command: + +@table @kbd +@item C-x v b +Switch to another back end that the current file is registered +under (@code{vc-switch-backend}). + +@item C-u C-x v b @var{backend} @key{RET} +Switch to @var{backend} for the current file. +@end table + +@kindex C-x v b +@findex vc-switch-backend +@kbd{C-x v b} does not change the buffer contents, or any files; it +only changes VC's perspective on how to handle the file. Any +subsequent VC commands for that file will operate on the back end that +is currently selected. + +If the current file is registered in more than one back end, typing +@kbd{C-x v b} ``cycles'' through all of these back ends. With a +prefix argument, it asks for the back end to use in the minibuffer. + +Thus, if you are using local RCS, and you want to pick up some recent +changes in the file from remote CVS, first visit the file, then type +@kbd{C-x v b} to switch to CVS, and finally use @kbd{C-x v m +@key{RET}} to merge the news +@iftex +(@pxref{Merging,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Merging}). +@end ifnottex +You can then switch back to RCS by typing @kbd{C-x v b} again, and +continue to edit locally. + +But if you do this, the revision numbers in the RCS master no longer +correspond to those of CVS. Technically, this is not a problem, but +it can become difficult to keep track of what is in the CVS repository +and what is not. So we suggest that you return from time to time to +CVS-only operation, by committing your local changes back to the +repository using @kbd{C-u C-x v v cvs @key{RET}}. + +@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 ~} +@iftex +(@pxref{Old Versions,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Old Versions}). +@end ifnottex +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 +snapshots made using RCS through VC are visible even when you bypass VC. + + With CVS, Meta-CVS, and Subversion, VC also uses the native +mechanism provided by that back end to make snapshots and retrieve them +(@dfn{tags} for CVS and Meta-CVS, @dfn{copies} for Subversion). + +@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. + + There is no support for VC snapshots using GNU Arch yet. + + 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 your 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 +@iftex +(@pxref{Change Log,,,emacs, the Emacs Manual}), +@end iftex +@ifnottex +(@pxref{Change Log}), +@end ifnottex +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 any of the other +back ends. + +@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. + + Some of the new change log entries 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}). + + Some back ends do not provide an explicit rename operation to their +repositories. After issuing @code{vc-rename-file}, use @kbd{C-x v v} +on the original and renamed buffers and provide the necessary edit +log. + + 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, the name of the user who created it, and other +relevant information. All of the back ends that VC supports have such +a mechanism, except GNU Arch. + + VC does not normally use the information contained in these headers. +The exception is RCS---with RCS, version headers are sometimes more +reliable than the master file to determine which version of the file +you are editing. Note that in a multi-branch environment, version +headers are necessary to make VC behave correctly +@iftex +(@pxref{Multi-User Branching,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Multi-User Branching}). +@end ifnottex + + Searching for RCS version headers is controlled by the variable +@code{vc-consult-headers}. If it is non-@code{nil} (the default), +Emacs searches for headers to determine the version number you are +editing. Setting it to @code{nil} disables this feature. + + Note that although CVS uses the same kind of version headers as RCS +does, VC never searches for these headers if you are using CVS, +regardless of the above setting. + +@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-@var{backend}-header + 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 variables @code{vc-@var{backend}-header} where +@var{backend} is @code{rcs} or @code{sccs}. + + 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 may be necessary to use apparently-superfluous backslashes when +writing the strings that you put in this variable. For instance, you +might write @code{"$Id\$"} rather than @code{"$Id@w{$}"}. The extra +backslash prevents the string constant from being interpreted as a +header, 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-@var{backend}-header}. The header line is made by processing the +string from @code{vc-@var{backend}-header} 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 + +@vindex vc-handled-backends +The variable @code{vc-handled-backends} determines which version +control systems VC should handle. The default value is @code{(RCS CVS +SVN SCCS BZR GIT HG Arch MCVS)}, so it contains all the version systems +that are currently supported. If you want VC to ignore one or more of +these systems, exclude its name from the list. To disable VC entirely, +set this variable to @code{nil}. + +The order of systems in the list is significant: when you visit a file +registered in more than one system (@pxref{Local Version Control}), VC +uses the system that comes first in @code{vc-handled-backends} by +default. The order is also significant when you register a file for +the first time, see +@iftex +@ref{Registering,,,emacs, the Emacs Manual}, +@end iftex +@ifnottex +@ref{Registering}, +@end ifnottex +for details. + +@menu +* General VC Options:: Options that apply to multiple back ends. +* RCS and SCCS:: Options for RCS and SCCS. +* CVS Options:: Options for CVS. +@end menu + +@node General VC Options +@subsubsection General Options + +@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 v v} 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. + +@vindex vc-suppress-confirm + If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x v v} +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. It is rarely necessary to +set this variable, because VC normally finds the proper files +automatically. + +@node RCS and SCCS +@subsubsection Options for RCS and SCCS + +@cindex non-strict locking (RCS) +@cindex locking, non-strict (RCS) + By default, RCS uses locking to coordinate the activities of several +users, 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 @code{rcs} manual page for details. + + When deducing the version control state of an RCS file, VC first +looks for an RCS version header string in the file (@pxref{Version +Headers}). If there is no header string, 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 the file +status by setting @code{vc-consult-headers} to @code{nil}. VC then +always uses the file permissions (if it is supposed to 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} 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. + + VC determines the version control state of files under SCCS much as +with RCS. It does not consider SCCS version headers, though. Thus, +the variable @code{vc-mistrust-permissions} affects SCCS use, but +@code{vc-consult-headers} does not. + +@node CVS Options +@subsubsection Options specific for CVS + +@cindex locking (CVS) + By default, CVS does not use locking to coordinate the activities of +several users; 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 @env{CVSREAD} environment variable +(the value you use makes no difference). If this variable is defined, +CVS makes your work files read-only by default. In Emacs, you must +type @kbd{C-x v v} to make the file writable, 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 writable +at the same time. When setting @env{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 v v} in Emacs to +make it writable. VC calls @code{cvs edit} to make the file writable, +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-stay-local +@vindex vc-cvs-stay-local +@cindex remote repositories (CVS) + When a file's repository is on a remote machine, VC tries to keep +network interactions to a minimum. This is controlled by the variable +@code{vc-cvs-stay-local}. There is another variable, +@code{vc-stay-local}, which enables the feature also for other back +ends that support it, including CVS. In the following, we will talk +only about @code{vc-cvs-stay-local}, but everything applies to +@code{vc-stay-local} as well. + +If @code{vc-cvs-stay-local} is @code{t} (the default), then VC uses +only the entry in the local CVS subdirectory to determine the file's +state (and possibly information returned by previous CVS commands). +One consequence of this is that when you have modified a file, and +somebody else has already checked in other changes to the file, you +are not notified of it until you actually try to commit. (But you can +try to pick up any recent changes from the repository first, using +@kbd{C-x v m @key{RET}}, +@iftex +@pxref{Merging,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +@pxref{Merging}). +@end ifnottex + + When @code{vc-cvs-stay-local} is @code{t}, VC also makes local +version backups, so that simple diff and revert operations are +completely local (@pxref{Version Backups}). + + On the other hand, if you set @code{vc-cvs-stay-local} to @code{nil}, +then VC queries the remote repository @emph{before} it decides what to +do in @code{vc-next-action} (@kbd{C-x v v}), just as it does for local +repositories. It also does not make any version backups. + + You can also set @code{vc-cvs-stay-local} to a regular expression +that is matched against the repository host name; VC then stays local +only for repositories from hosts that match the pattern. + +@vindex vc-cvs-global-switches + You can specify additional command line options to pass to all CVS +operations in the variable @code{vc-cvs-global-switches}. These +switches are inserted immediately after the @code{cvs} command, before +the name of the operation to invoke. + +@ignore + arch-tag: 140b8629-4339-4b5e-9e50-72453e51615e +@end ignore diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi new file mode 100644 index 00000000000..fa9cadc1351 --- /dev/null +++ b/doc/emacs/windows.texi @@ -0,0 +1,387 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007 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. +* Window Convenience:: Convenience functions for window handling. +@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 these +windows can show different parts of the buffer, because each window +has its own value of point. + +@cindex selected window + At any time, one Emacs window 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. On text-only terminals, there is no +way to show where those locations are, since the terminal has only one +cursor. On a graphical display, the location of point in a +non-selected window is indicated by a hollow box; the cursor in the +selected window is blinking or solid. + + Commands to move point affect the value of point for the selected Emacs +window only. They do not change the value of point in other Emacs +windows, even those showing the same buffer. The same is true for commands +such as @kbd{C-x b} to switch buffers 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. The selected window's mode line appears in a +different color. @xref{Mode Line}, for full details on the mode line. + +@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. If you are not using +scrollbars, a vertical line separates the two windows. +You can customize its color with the face @code{vertical-border}. +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, so +if the variable @code{truncate-partial-width-windows} is +non-@code{nil}, that forces 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{Line Truncation}. + + Horizontal scrolling is often used in side-by-side windows. +@xref{Horizontal Scrolling}. + +@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 scrolling the text currently visible on the screen, by putting +point in each window at a position already visible in the window. It +also selects whichever window contains the screen line that the cursor +was previously on. Some users prefer that 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. + +@vindex mouse-autoselect-window + If you set @code{mouse-autoselect-window} to a non-@code{nil} value, +moving the mouse into a different window selects that window. This +feature is off by default. + +@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}). +@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. + +@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 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 its peers. 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. + + Mouse clicks on the mode line provide another way to change window +heights and to delete windows. @xref{Mode Line Mouse}. + +@node Window Convenience +@section Window Handling Convenience Features and Customization + +@findex winner-mode +@cindex Winner mode +@cindex mode, Winner +@cindex undoing window configuration changes +@cindex window configuration changes, undoing + @kbd{M-x winner-mode} is a global minor mode that records the +changes in the window configuration (i.e. how the frames are +partitioned into windows), so that you can ``undo'' them. To undo, +use @kbd{C-c left} (@code{winner-undo}). If you change your mind +while undoing, you can redo the changes you had undone using @kbd{C-c +right} (@code{M-x winner-redo}). Another way to enable Winner mode is +by customizing the variable @code{winner-mode}. + +@cindex Windmove package +@cindex directional window selection +@findex windmove-right +@findex windmove-default-keybindings + The Windmove commands move directionally between neighboring windows in +a frame. @kbd{M-x windmove-right} selects the window immediately to the +right of the currently selected one, and similarly for the ``left,'' ``up,'' +and ``down'' counterparts. @kbd{M-x windmove-default-keybindings} binds +these commands to @kbd{S-right} etc. (Not all terminals support shifted +arrow keys, however.) + + Follow minor mode (@kbd{M-x follow-mode}) synchronizes several +windows on the same buffer so that they always display adjacent +sections of that buffer. @xref{Follow Mode}. + +@vindex scroll-all-mode +@cindex scrolling windows together +@cindex Scroll-all mode +@cindex mode, Scroll-all + @kbd{M-x scroll-all-mode} provides commands to scroll all visible +windows together. You can also turn it on by customizing the variable +@code{scroll-all-mode}. The commands provided are @kbd{M-x +scroll-all-scroll-down-all}, @kbd{M-x scroll-all-page-down-all} and +their corresponding ``up'' equivalents. To make this mode useful, +you should bind these commands to appropriate keys. + +@ignore + arch-tag: 8bea7453-d4b1-49b1-9bf4-cfe4383e1113 +@end ignore diff --git a/doc/emacs/xresources.texi b/doc/emacs/xresources.texi new file mode 100644 index 00000000000..c402ec89f88 --- /dev/null +++ b/doc/emacs/xresources.texi @@ -0,0 +1,1216 @@ +@c This is part of the Emacs manual. +@c Copyright (C) 1987, 1993, 1994, 1995, 1997, 2001, 2002, 2003, +@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc. +@c See file emacs.texi for copying conditions. +@node X Resources, Antinews, Emacs Invocation, Top +@appendix X Options and Resources + + You can customize some X-related aspects of Emacs behavior using X +resources, as is usual for programs that use X. On MS-Windows, you +can customize some of the same aspects using the system registry. +@xref{MS-Windows Registry}. Likewise, Emacs on MacOS Carbon emulates X +resources using the Preferences system. @xref{Mac Environment Variables}. + + When Emacs is built using an ``X toolkit'', such as Lucid or +LessTif, you need to use X resources to customize the appearance of +the widgets, including the menu-bar, scroll-bar, and dialog boxes. +This is because the libraries that implement these don't provide for +customization through Emacs. GTK+ widgets use a separate system of +@ifnottex +``GTK resources'', which we will also describe. +@end ifnottex +@iftex +``GTK resources.'' In this chapter we describe the most commonly used +resource specifications. For full documentation, see the online +manual. + +@c Add xref for LessTif/Motif menu resources. +@end iftex + + +@menu +* Resources:: Using X resources with Emacs (in general). +* Table of Resources:: Table of specific X resources that affect Emacs. +* Face Resources:: X resources for customizing faces. +* Lucid Resources:: X resources for Lucid menus. +* LessTif Resources:: X resources for LessTif and Motif menus. +* GTK resources:: Resources for GTK widgets. +@end menu + +@node Resources +@appendixsec X Resources +@cindex resources +@cindex X resources +@cindex @file{~/.Xdefaults} file +@cindex @file{~/.Xresources} file + + 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} or @file{~/.Xresources}. +If changes in @file{~/.Xdefaults} do not +take effect, it is because your X server stores its own list of +resources; to update them, use the shell command @command{xrdb}---for +instance, @samp{xrdb ~/.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). + +@cindex Registry (MS-Windows) + MS-Windows systems do not support @file{~/.Xdefaults} files, so +instead Emacs compiled for Windows looks for X resources in the +Windows Registry, first under the key +@samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} and then under the key +@samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}. The menu and scroll +bars are native widgets on MS-Windows, so they are only customizable +via the system-wide settings in the Display Control Panel. You can +also set resources using the @samp{-xrm} command line option (see +below.) + +@iftex + Applications such as Emacs look for resources with specific names +and their particular meanings. Case distinctions are significant in +these names. Each resource specification in @file{~/.Xdefaults} +states the name of the program and the name of the resource. For +Emacs, the program name is @samp{Emacs}. It looks like this: + +@example +Emacs.borderWidth: 2 +@end example +@end iftex +@ifnottex + 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. + + Every resource definition is associated with a specific program +name---the name of the executable file that you ran. For Emacs, that +is normally @samp{emacs}. To specify a definition for all instances +of Emacs, regardless of their names, use @samp{Emacs}. + + 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 +@end ifnottex + + The order in which the lines appear in the file does not matter. +Also, command-line options always override the X resources file. + +@ifnottex +Here is a list of X command-line options and their corresponding +resource names. + +@table @samp +@item -name @var{name} +@opindex --name +@itemx --name=@var{name} +@cindex resource name, command-line argument +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} +@opindex --xrm +@itemx --xrm=@var{resource-values} +@cindex resource values, command-line argument +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{resources}, 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. + + One way to experiment with the effect of different resource settings +is to use the @code{editres} program. Select @samp{Get Tree} from the +@end ifnottex +@iftex + You can experiment with the effect of different resource settings +with the @code{editres} program. Select @samp{Get Tree} from the +@end iftex +@samp{Commands} menu, then click on an Emacs frame. This will display +a tree showing the structure of X toolkit widgets used in an Emacs +frame. Select one of them, such as @samp{menubar}, then select +@samp{Show Resource Box} from the @samp{Commands} menu. This displays +a list of all the meaningful X resources for that widget, and allows +you to edit them. Changes take effect when you click on the +@samp{Apply} button. (See the @code{editres} man page for more +details.) + +@node Table of Resources +@appendixsec Table of X Resources for Emacs + + This table lists the resource names that designate options for +Emacs, not counting those for the appearance of the menu bar, each +with the class that it belongs to: + +@table @asis +@item @code{background} (class @code{Background}) +Background color name. + +@ifnottex +@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}. +@end ifnottex + +@item @code{borderColor} (class @code{BorderColor}) +Color name for the external border. + +@ifnottex +@item @code{borderWidth} (class @code{BorderWidth}) +Width in pixels of the external border. +@end ifnottex + +@item @code{cursorColor} (class @code{Foreground}) +Color name for text cursor (point). + +@ifnottex +@item @code{cursorBlink} (class @code{CursorBlink}) +Specifies whether to make the cursor blink. The default is @samp{on}. Use +@samp{off} or @samp{false} to turn cursor blinking off. +@end ifnottex + +@item @code{font} (class @code{Font}) +Font name (or fontset name, @pxref{Fontsets}) for @code{default} font. + +@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. + +@ifnottex +@item @code{fullscreen} (class @code{Fullscreen}) +The desired fullscreen size. The value can be one of @code{fullboth}, +@code{fullwidth} or @code{fullheight}, which correspond to +the command-line options @samp{-fs}, @samp{-fw}, and @samp{-fh} +(@pxref{Window Size X}). + +Note that this applies to the initial frame only. +@end ifnottex + +@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{lineSpacing} (class @code{LineSpacing}) +@cindex line spacing +@cindex leading +Additional space (@dfn{leading}) between lines, in pixels. + +@item @code{menuBar} (class @code{MenuBar}) +@cindex menu bar +Give frames menu bars if @samp{on}; don't have menu bars if @samp{off}. +@ifnottex +@xref{Lucid Resources}, and @ref{LessTif Resources}, +@end ifnottex +@iftex +@xref{Lucid Resources}, +@end iftex +for how to control the appearance of the menu bar if you have one. + +@ifnottex +@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}) +@cindex font for menus +Font name for menu pane titles, in non-toolkit versions of Emacs. +@end ifnottex + +@item @code{pointerColor} (class @code{Foreground}) +Color of the mouse cursor. + +@ifnottex +@item @code{privateColormap} (class @code{PrivateColormap}) +If @samp{on}, use a private color map, in the case where the ``default +visual'' of class PseudoColor and Emacs is using it. + +@item @code{reverseVideo} (class @code{ReverseVideo}) +Switch foreground and background default colors if @samp{on}, use colors as +specified if @samp{off}. +@end ifnottex + +@item @code{screenGamma} (class @code{ScreenGamma}) +@cindex gamma correction +Gamma correction for colors, equivalent to the frame parameter +@code{screen-gamma}. + +@item @code{scrollBarWidth} (class @code{ScrollBarWidth}) +@cindex scrollbar width +The scroll bar width in pixels, equivalent to the frame parameter +@code{scroll-bar-width}. + +@ifnottex +@item @code{selectionFont} (class @code{SelectionFont}) +Font name for pop-up menu items, in non-toolkit versions of Emacs. (For +toolkit versions, see @ref{Lucid Resources}, also see @ref{LessTif +Resources}.) + +@item @code{selectionTimeout} (class @code{SelectionTimeout}) +Number of milliseconds to wait for a selection reply. +If the selection owner doesn't reply in this time, we give up. +A value of 0 means wait as long as necessary. + +@item @code{synchronous} (class @code{Synchronous}) +@cindex debugging X problems +@cindex synchronous X mode +Run Emacs in synchronous mode if @samp{on}. Synchronous mode is +useful for debugging X problems. +@end ifnottex + +@item @code{title} (class @code{Title}) +Name to display in the title bar of the initial Emacs frame. + +@item @code{toolBar} (class @code{ToolBar}) +@cindex tool bar +Number of lines to reserve for the tool bar. A zero value suppresses +the tool bar. If the value is non-zero and +@code{auto-resize-tool-bars} is non-@code{nil}, the tool bar's size +will be changed automatically so that all tool bar items are visible. + If the value of @code{auto-resize-tool-bars} is @code{grow-only}, +the tool bar expands automatically, but does not contract automatically. +To contract the tool bar, you must redraw the frame by entering @kbd{C-l}. + +@item @code{useXIM} (class @code{UseXIM}) +@cindex XIM +@cindex X input methods +@cindex input methods, X +Turn off use of X input methods (XIM) if @samp{false} or @samp{off}. +This is only relevant if your Emacs is actually built with XIM +support. It is potentially useful to turn off XIM for efficiency, +especially slow X client/server links. + +@item @code{verticalScrollBars} (class @code{ScrollBars}) +Give frames scroll bars if @samp{on}; don't have scroll bars if +@samp{off}. + +@ifnottex +@item @code{visualClass} (class @code{VisualClass}) +Specify the ``visual'' that X should use. This tells X how to handle +colors. + +The value should start with one of @samp{TrueColor}, +@samp{PseudoColor}, @samp{DirectColor}, @samp{StaticColor}, +@samp{GrayScale}, and @samp{StaticGray}, followed by +@samp{-@var{depth}}, where @var{depth} is the number of color planes. +Most terminals only allow a few ``visuals,'' and the @samp{dpyinfo} +program outputs information saying which ones. +@end ifnottex +@end table + +@node Face Resources +@appendixsec X Resources for Faces + + You can use resources to customize the appearance of particular +faces (@pxref{Faces}): + +@table @code +@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. +@item @var{face}.attributeStrikeThrough +@itemx @var{face}.attributeOverline +@itemx @var{face}.attributeBox +@itemx @var{face}.attributeInverse +Likewise, for other boolean font attributes. +@item @var{face}.attributeStipple +The name of a pixmap data file to use for the stipple pattern, or +@code{false} to not use stipple for the face @var{face}. +@item @var{face}.attributeBackgroundPixmap +The background pixmap for the face @var{face}. Should be a name of a +pixmap file or @code{false}. +@item @var{face}.attributeFont +Font name (full XFD name or valid X abbreviation) for face @var{face}. +Instead of this, you can specify the font through separate attributes. +@end table + + Instead of using @code{attributeFont} to specify a font name, you can +select a font through these separate attributes: + +@table @code +@item @var{face}.attributeFamily +Font family for face @var{face}. +@item @var{face}.attributeHeight +Height of the font to use for face @var{face}: either an integer +specifying the height in units of 1/10@dmn{pt}, or a floating point +number that specifies a scale factor to scale the underlying face's +default font, or a function to be called with the default height which +will return a new height. +@item @var{face}.attributeWidth +@itemx @var{face}.attributeWeight +@itemx @var{face}.attributeSlant +Each of these resources corresponds to a like-named font attribute, +and you write the resource value the same as the symbol you would use +for the font attribute value. +@item @var{face}.attributeBold +Bold flag for face @var{face}---instead of @code{attributeWeight}. Use @samp{on} or @samp{true} for +yes. +@item @var{face}.attributeItalic +Italic flag for face @var{face}---instead of @code{attributeSlant}. +@end table + +@node Lucid Resources +@appendixsec Lucid Menu X Resources +@cindex Menu X Resources (Lucid widgets) +@cindex Lucid Widget X Resources + +@ifnottex + 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: +@end ifnottex +@iftex + 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 specifications start with +@samp{Emacs.pane.menubar}---for instance, to specify the font +@samp{8x16} for the menu-bar items, write this: +@end iftex + +@example +Emacs.pane.menubar.font: 8x16 +@end example + +@noindent +Resources for @emph{non-menubar} toolkit pop-up menus have +@samp{menu*} instead of @samp{pane.menubar}. 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*}: + +@example +Emacs.dialog*.font: 8x16 +@end example + +@noindent +The Lucid menus can display multilingual text in your locale. For +more information about fontsets see the man page for +@code{XCreateFontSet}. To enable multilingual menu text you specify a +@code{fontSet} resource instead of the font resource. If both +@code{font} and @code{fontSet} resources are specified, the +@code{fontSet} resource is used. + + Thus, to specify @samp{-*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,*} +for both the popup and menu bar menus, write this: + +@example +Emacs*menu*fontSet: -*-helvetica-medium-r-*--*-120-*-*-*-*-*-*,* +@end example + +@noindent +The @samp{*menu*} as a wildcard matches @samp{pane.menubar} and +@samp{menu@dots{}}. + +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.}. The generic wildcard +approach should work on both kinds of systems. + + 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 fontSet +Fontset 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. +@ifnottex +@item horizontalSpacing +Horizontal spacing in pixels between items. Default is 3. +@item verticalSpacing +Vertical spacing in pixels between items. Default is 2. +@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. Default is 1. + +Also determines the thickness of shadow lines around other objects, +for instance 3D buttons and arrows. If you have the impression that +the arrows in the menus do not stand out clearly enough or that the +difference between ``in'' and ``out'' buttons is difficult to see, set +this to 2. If you have no problems with visibility, the default +probably looks better. The background color may also have some effect +on the contrast. +@end ifnottex +@item margin +The margin of the menu bar, in characters. Default is 1. +@end table + +@ifnottex +@node LessTif Resources +@appendixsec LessTif Menu X Resources +@cindex Menu X Resources (LessTif widgets) +@cindex LessTif Widget X Resources + + If the Emacs installed at your site was built to use the X toolkit +with the LessTif or Motif widgets, then the menu bar, the dialog +boxes, the pop-up menus, and the file-selection box are separate +widgets and have their own resources. + + The resource names for the menu bar 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{File} in the menu bar is part of a subwidget named +@samp{emacs.pane.menubar.File}. 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{File} submenu has an item named +@samp{Save (current 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 (current +buffer)} item: + +@smallexample +Emacs.pane.menubar.popup_*.File.Save (current buffer).fontList: 8x16 +@end smallexample + +@noindent +For an item in a second-level submenu, such as @samp{Complete Word} +under @samp{Spell Checking} under @samp{Tools}, 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 Checking.Complete Word: @var{value} +@end smallexample + +@noindent +(This should be one long line.) + + 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 LessTif 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 + +@noindent +For LessTif dialog boxes, use @samp{dialog} instead of @samp{menu}: + +@example +Emacs.dialog*.fontList: 8x16 +Emacs.dialog*.foreground: hotpink +@end example + +To specify resources for the LessTif file-selection box, use +@samp{fsb*}, like this: + +@example +Emacs.fsb*.fontList: 8x16 +@end example + +@iftex +@medbreak +@end iftex + Here is a list of the specific resources for LessTif 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 the 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 +@end ifnottex + + +@node GTK resources +@appendixsec GTK resources +@iftex + The most common way to customize the GTK widgets Emacs uses (menus, dialogs +tool bars and scroll bars) is by choosing an appropriate theme, for example +with the GNOME theme selector. You can also do Emacs specific customization +by inserting GTK style directives in the file @file{~/.emacs.d/gtkrc}. Some GTK +themes ignore customizations in @file{~/.emacs.d/gtkrc} so not everything +works with all themes. To customize Emacs font, background, faces, etc., use +the normal X resources (@pxref{Resources}). We will present some examples of +customizations here, but for a more detailed description, see the online manual + + The first example is just one line. It changes the font on all GTK widgets +to courier with size 12: + +@smallexample +gtk-font-name = "courier 12" +@end smallexample + + The thing to note is that the font name is not an X font name, like +-*-helvetica-medium-r-*--*-120-*-*-*-*-*-*, but a Pango font name. A Pango +font name is basically of the format "family style size", where the style +is optional as in the case above. A name with a style could be for example: + +@smallexample +gtk-font-name = "helvetica bold 10" +@end smallexample + + To customize widgets you first define a style and then apply the style to +the widgets. Here is an example that sets the font for menus, but not +for other widgets: + +@smallexample +# @r{Define the style @samp{menufont}.} +style "menufont" +@{ + font_name = "helvetica bold 14" # This is a Pango font name +@} + +# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.} +widget "*emacs-menuitem*" style "menufont" +@end smallexample + +The widget name in this example contains wildcards, so the style will be +applied to all widgets that match "*emacs-menuitem*". The widgets are +named by the way they are contained, from the outer widget to the inner widget. +So to apply the style "my_style" (not shown) with the full, absolute name, for +the menubar and the scroll bar in Emacs we use: + +@smallexample +widget "Emacs.pane.menubar" style "my_style" +widget "Emacs.pane.emacs.verticalScrollBar" style "my_style" +@end smallexample + +But to avoid having to type it all, wildcards are often used. @samp{*} +matches zero or more characters and @samp{?} matches one character. So "*" +matches all widgets. + + Each widget has a class (for example GtkMenuItem) and a name (emacs-menuitem). +You can assign styles by name or by class. In this example we have used the +class: + +@smallexample +style "menufont" +@{ + font_name = "helvetica bold 14" +@} + +widget_class "*GtkMenuBar" style "menufont" +@end smallexample + +@noindent +The names and classes for the GTK widgets Emacs uses are: + +@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some} +@item @code{emacs-filedialog} +@tab @code{GtkFileSelection} +@item @code{emacs-dialog} +@tab @code{GtkDialog} +@item @code{Emacs} +@tab @code{GtkWindow} +@item @code{pane} +@tab @code{GtkVHbox} +@item @code{emacs} +@tab @code{GtkFixed} +@item @code{verticalScrollBar} +@tab @code{GtkVScrollbar} +@item @code{emacs-toolbar} +@tab @code{GtkToolbar} +@item @code{menubar} +@tab @code{GtkMenuBar} +@item @code{emacs-menuitem} +@tab anything in menus +@end multitable + + GTK absolute names are quite strange when it comes to menus +and dialogs. The names do not start with @samp{Emacs}, as they are +free-standing windows and not contained (in the GTK sense) by the +Emacs GtkWindow. To customize the dialogs and menus, use wildcards like this: + +@smallexample +widget "*emacs-dialog*" style "my_dialog_style" +widget "*emacs-filedialog* style "my_file_style" +widget "*emacs-menuitem* style "my_menu_style" +@end smallexample + + If you specify a customization in @file{~/.emacs.d/gtkrc}, then it +automatically applies only to Emacs, since other programs don't read +that file. For example, the drop down menu in the file dialog can not +be customized by any absolute widget name, only by an absolute class +name. This is because the widgets in the drop down menu do not +have names and the menu is not contained in the Emacs GtkWindow. To +have all menus in Emacs look the same, use this in +@file{~/.emacs.d/gtkrc}: + +@smallexample +widget_class "*Menu*" style "my_menu_style" +@end smallexample + + Here is a more elaborate example, showing how to change the parts of +the scroll bar: + +@smallexample +style "scroll" +@{ + fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.} + bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.} + bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.} + bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.} +@} + +widget "*verticalScrollBar*" style "scroll" +@end smallexample +@end iftex + +@ifnottex +@cindex GTK resources and customization +@cindex resource files for GTK +@cindex @file{~/.gtkrc-2.0} file +@cindex @file{~/.emacs.d/gtkrc} file + + If Emacs was built to use the GTK widget set, then the menu bar, tool bar, +scroll bar and the dialogs are customized with the standard GTK +customization file, @file{~/.gtkrc-2.0}, or with the Emacs specific +file @file{~/.emacs.d/gtkrc}. We recommend that you use +@file{~/.emacs.d/gtkrc} for customizations, since @file{~/.gtkrc-2.0} +seems to be ignored when running GConf with GNOME. These files apply +only to GTK widget features. To customize Emacs font, background, +faces, etc., use the normal X resources (@pxref{Resources}). + + Some GTK themes override these mechanisms, which means that using +these mechanisms will not work to customize them. + + In these files you first define a style and say what it means; then +you specify to apply the style to various widget types (@pxref{GTK +widget names}). Here is an example of how to change the font for +Emacs menus: + +@smallexample +# @r{Define the style @samp{menufont}.} +style "menufont" +@{ + font_name = "helvetica bold 14" # This is a Pango font name +@} + +# @r{Specify that widget type @samp{*emacs-menuitem*} uses @samp{menufont}.} +widget "*emacs-menuitem*" style "menufont" +@end smallexample + + Here is a more elaborate example, showing how to change the parts of +the scroll bar: + +@smallexample +style "scroll" +@{ + fg[NORMAL] = "red"@ @ @ @ @ # @r{The arrow color.} + bg[NORMAL] = "yellow"@ @ # @r{The thumb and background around the arrow.} + bg[ACTIVE] = "blue"@ @ @ @ # @r{The trough color.} + bg[PRELIGHT] = "white"@ # @r{The thumb color when the mouse is over it.} +@} + +widget "*verticalScrollBar*" style "scroll" +@end smallexample + + There are also parameters that affect GTK as a whole. For example, +the property @code{gtk-font-name} sets the default font for GTK. You +must use Pango font names (@pxref{GTK styles}). A GTK resources file +that just sets a default font looks like this: + +@smallexample +gtk-font-name = "courier 12" +@end smallexample + + The GTK resources file is fully described in the GTK API document. +This can be found in +@file{@var{prefix}/share/gtk-doc/html/gtk/gtk-resource-files.html}, +where @file{prefix} is the directory in which the GTK libraries were +installed (usually @file{/usr} or @file{/usr/local}). You can also +find the document online, at +@uref{http://developer.gnome.org/doc/API/2.0/gtk/gtk-Resource-Files.html}. + +@menu +* GTK widget names:: How widgets in GTK are named in general. +* GTK Names in Emacs:: GTK widget names in Emacs. +* GTK styles:: What can be customized in a GTK widget. +@end menu + +@node GTK widget names +@appendixsubsec GTK widget names +@cindex GTK widget names + + A GTK widget is specified by its @dfn{widget class} and +@dfn{widget name}. The widget class is the type of the widget: for +example, @code{GtkMenuBar}. The widget name is the name given to a +specific widget. A widget always has a class, but need not have a +name. + + @dfn{Absolute names} are sequences of widget names or widget +classes, corresponding to hierarchies of widgets embedded within +other widgets. For example, if a @code{GtkWindow} named @code{top} +contains a @code{GtkVBox} named @code{box}, which in turn contains +a @code{GtkMenuBar} called @code{menubar}, the absolute class name +of the menu-bar widget is @code{GtkWindow.GtkVBox.GtkMenuBar}, and +its absolute widget name is @code{top.box.menubar}. + + When assigning a style to a widget, you can use the absolute class +name or the absolute widget name. + + There are two commands to specify changes for widgets: + +@table @asis +@item @code{widget_class} +specifies a style for widgets based on the absolute class name. + +@item @code{widget} +specifies a style for widgets based on the absolute class name, +or just the class. +@end table + +@noindent +You must specify the class and the style in double-quotes, and put +these commands at the top level in the GTK customization file, like +this: + +@smallexample +style "menufont" +@{ + font_name = "helvetica bold 14" +@} + +widget "top.box.menubar" style "menufont" +widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "menufont" +@end smallexample + + Matching of absolute names uses shell wildcard syntax: @samp{*} +matches zero or more characters and @samp{?} matches one character. +This example assigns @code{base_style} to all widgets: + +@smallexample +widget "*" style "base_style" +@end smallexample + + Given the absolute class name @code{GtkWindow.GtkVBox.GtkMenuBar} +and the corresponding absolute widget name @code{top.box.menubar}, all +these examples specify @code{my_style} for the menu bar: + +@smallexample +widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style" +widget_class "GtkWindow.*.GtkMenuBar" style "my_style" +widget_class "*GtkMenuBar" style "my_style" +widget "top.box.menubar" style "my_style" +widget "*box*menubar" style "my_style" +widget "*menubar" style "my_style" +widget "*menu*" style "my_style" +@end smallexample + +@node GTK Names in Emacs +@appendixsubsec GTK Widget Names in Emacs +@cindex GTK widget names +@cindex GTK widget classes + + In Emacs, the top level widget for a frame is a @code{GtkWindow} +that contains a @code{GtkVBox}. The @code{GtkVBox} contains the +@code{GtkMenuBar} and a @code{GtkFixed} widget. The vertical scroll +bars, @code{GtkVScrollbar}, are contained in the @code{GtkFixed} +widget. The text you write in Emacs is drawn in the @code{GtkFixed} +widget. + + Dialogs in Emacs are @code{GtkDialog} widgets. The file dialog is a +@code{GtkFileSelection} widget. + +@noindent +To set a style for the menu bar using the absolute class name, use: + +@smallexample +widget_class "GtkWindow.GtkVBox.GtkMenuBar" style "my_style" +@end smallexample + +@noindent +For the scroll bar, the absolute class name is: + +@smallexample +widget_class + "GtkWindow.GtkVBox.GtkFixed.GtkVScrollbar" + style "my_style" +@end smallexample + +@noindent +The names for the emacs widgets, and their classes, are: + +@multitable {@code{verticalScrollbar plus}} {@code{GtkFileSelection} and some} +@item @code{emacs-filedialog} +@tab @code{GtkFileSelection} +@item @code{emacs-dialog} +@tab @code{GtkDialog} +@item @code{Emacs} +@tab @code{GtkWindow} +@item @code{pane} +@tab @code{GtkVHbox} +@item @code{emacs} +@tab @code{GtkFixed} +@item @code{verticalScrollBar} +@tab @code{GtkVScrollbar} +@item @code{emacs-toolbar} +@tab @code{GtkToolbar} +@item @code{menubar} +@tab @code{GtkMenuBar} +@item @code{emacs-menuitem} +@tab anything in menus +@end multitable + +@noindent +Thus, for Emacs you can write the two examples above as: + +@smallexample +widget "Emacs.pane.menubar" style "my_style" +widget "Emacs.pane.emacs.verticalScrollBar" style "my_style" +@end smallexample + + GTK absolute names are quite strange when it comes to menus +and dialogs. The names do not start with @samp{Emacs}, as they are +free-standing windows and not contained (in the GTK sense) by the +Emacs GtkWindow. To customize the dialogs and menus, use wildcards like this: + +@smallexample +widget "*emacs-dialog*" style "my_dialog_style" +widget "*emacs-filedialog* style "my_file_style" +widget "*emacs-menuitem* style "my_menu_style" +@end smallexample + + If you specify a customization in @file{~/.emacs.d/gtkrc}, then it +automatically applies only to Emacs, since other programs don't read +that file. For example, the drop down menu in the file dialog can not +be customized by any absolute widget name, only by an absolute class +name. This is because the widgets in the drop down menu do not +have names and the menu is not contained in the Emacs GtkWindow. To +have all menus in Emacs look the same, use this in +@file{~/.emacs.d/gtkrc}: + +@smallexample +widget_class "*Menu*" style "my_menu_style" +@end smallexample + +@node GTK styles +@appendixsubsec GTK styles +@cindex GTK styles + + In a GTK style you specify the appearance widgets shall have. You +can specify foreground and background color, background pixmap and +font. The edit widget (where you edit the text) in Emacs is a GTK +widget, but trying to specify a style for the edit widget will have no +effect. This is so that Emacs compiled for GTK is compatible with +Emacs compiled for other X toolkits. The settings for foreground, +background and font for the edit widget is taken from the X resources; +@pxref{Resources}. Here is an example of two style declarations, +@samp{default} and @samp{ruler}: + +@smallexample +pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" + +style "default" +@{ + font_name = "helvetica 12" + + bg[NORMAL] = @{ 0.83, 0.80, 0.73 @} + bg[SELECTED] = @{ 0.0, 0.55, 0.55 @} + bg[INSENSITIVE] = @{ 0.77, 0.77, 0.66 @} + bg[ACTIVE] = @{ 0.0, 0.55, 0.55 @} + bg[PRELIGHT] = @{ 0.0, 0.55, 0.55 @} + + fg[NORMAL] = "black" + fg[SELECTED] = @{ 0.9, 0.9, 0.9 @} + fg[ACTIVE] = "black" + fg[PRELIGHT] = @{ 0.9, 0.9, 0.9 @} + + base[INSENSITIVE] = "#777766" + text[INSENSITIVE] = @{ 0.60, 0.65, 0.57 @} + + bg_pixmap[NORMAL] = "background.xpm" + bg_pixmap[INSENSITIVE] = "background.xpm" + bg_pixmap[ACTIVE] = "background.xpm" + bg_pixmap[PRELIGHT] = "<none>" + +@} + +style "ruler" = "default" +@{ + font_name = "helvetica 8" +@} + +@end smallexample + + The style @samp{ruler} inherits from @samp{default}. This way you can build +on existing styles. The syntax for fonts and colors is described below. + + As this example shows, it is possible to specify several values for +foreground and background depending on the widget's @dfn{state}. The +possible states are: + +@table @code +@item NORMAL +This is the default state for widgets. +@item ACTIVE +This is the state for a widget that is ready to do something. It is +also for the trough of a scroll bar, i.e. @code{bg[ACTIVE] = "red"} +sets the scroll bar trough to red. Buttons that have been pressed but +not released yet (``armed'') are in this state. +@item PRELIGHT +This is the state for a widget that can be manipulated, when the mouse +pointer is over it---for example when the mouse is over the thumb in +the scroll bar or over a menu item. When the mouse is over a button +that is not pressed, the button is in this state. +@item SELECTED +This is the state for data that has been selected by the user. It can +be selected text or items selected in a list. This state is not used +in Emacs. +@item INSENSITIVE +This is the state for widgets that are visible, but they can not be +manipulated in the usual way---for example, buttons that can't be +pressed, and disabled menu items. To display disabled menu items in +yellow, use @code{fg[INSENSITIVE] = "yellow"}. +@end table + + Here are the things that can go in a style declaration: + +@table @code +@item bg[@var{state}] = @var{color} +This specifies the background color for the widget. Note that +editable text doesn't use @code{bg}; it uses @code{base} instead. + +@item base[@var{state}] = @var{color} +This specifies the background color for editable text. In Emacs, this +color is used for the background of the text fields in the file +dialog. + +@item bg_pixmap[@var{state}] = "@var{pixmap}" +This specifies an image background (instead of a background color). +@var{pixmap} should be the image file name. GTK can use a number of +image file formats, including XPM, XBM, GIF, JPEG and PNG. If you +want a widget to use the same image as its parent, use +@samp{<parent>}. If you don't want any image, use @samp{<none>}. +@samp{<none>} is the way to cancel a background image inherited from a +parent style. + +You can't specify the file by its absolute file name. GTK looks for +the pixmap file in directories specified in @code{pixmap_path}. +@code{pixmap_path} is a colon-separated list of directories within +double quotes, specified at the top level in a @file{gtkrc} file +(i.e. not inside a style definition; see example above): + +@smallexample +pixmap_path "/usr/share/pixmaps:/usr/include/X11/pixmaps" +@end smallexample + +@item fg[@var{state}] = @var{color} +This specifies the foreground color for widgets to use. It is the +color of text in menus and buttons, and the color for the arrows in +the scroll bar. For editable text, use @code{text}. + +@item text[@var{state}] = @var{color} +This is the color for editable text. In Emacs, this color is used for the +text fields in the file dialog. + +@item font_name = "@var{font}" +This specifies the font for text in the widget. @var{font} is a +Pango font name, for example @samp{Sans Italic 10}, @samp{Helvetica +Bold 12}, @samp{Courier 14}, @samp{Times 18}. See below for exact +syntax. The names are case insensitive. +@end table + + There are three ways to specify a color: by name, in hexadecimal +form, and with an RGB triplet. + +@noindent +A color name is written within double quotes, for example @code{"red"}. + +@noindent +Hexadecimal form is the same as in X: +@code{#@var{rrrr}@var{gggg}@var{bbbb}}, where all three color specs +must have the same number of hex digits (1, 2, 3 or 4). + +@noindent +An RGB triplet looks like @code{@{ @var{r}, @var{g}, @var{b} @}}, +where @var{r}, @var{g} and @var{b} are either integers in the range +0-65535 or floats in the range 0.0-1.0. + + Pango font names have the form ``@var{family-list} @var{style-options} +@var{size}.'' +@cindex Pango font name +@noindent +@var{family-list} is a comma separated list of font families optionally +terminated by a comma. This way you can specify several families and the +first one found will be used. @var{family} corresponds to the second part in +an X font name, for example in + +@smallexample +-adobe-times-medium-r-normal--12-120-75-75-p-64-iso10646-1 +@end smallexample + +@noindent +the family name is @samp{times}. + +@noindent +@var{style-options} is a whitespace separated list of words where each word +is a style, variant, weight, or stretch. The default value for all of +these is @code{normal}. + +@noindent +A `style' corresponds to the fourth part of an X font name. In X font +names it is the character @samp{r}, @samp{i} or @samp{o}; in Pango +font names the corresponding values are @code{normal}, @code{italic}, +or @code{oblique}. + +@noindent +A `variant' is either @code{normal} or @code{small-caps}. +Small caps is a font with the lower case characters replaced by +smaller variants of the capital characters. + +@noindent +Weight describes the ``boldness'' of a font. It corresponds to the third +part of an X font name. It is one of @code{ultra-light}, @code{light}, +@code{normal}, @code{bold}, @code{ultra-bold}, or @code{heavy}. + +@noindent +Stretch gives the width of the font relative to other designs within a +family. It corresponds to the fifth part of an X font name. It is one of +@code{ultra-condensed}, @code{extra-condensed}, @code{condensed}, +@code{semi-condensed}, @code{normal}, @code{semi-expanded}, +@code{expanded}, @code{extra-expanded}, or @code{ultra-expanded}. + +@noindent +@var{size} is a decimal number that describes the font size in points. +@end ifnottex + +@ignore + arch-tag: 9b6ff773-48b6-41f6-b2f9-f114b8bdd97f +@end ignore |