diff options
Diffstat (limited to 'doc/emacs')
56 files changed, 3385 insertions, 3274 deletions
diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog index c26f1a7e1ca..ad49224e0d3 100644 --- a/doc/emacs/ChangeLog +++ b/doc/emacs/ChangeLog @@ -1,3 +1,261 @@ +2012-01-09 Chong Yidong <cyd@gnu.org> + + * custom.texi (Custom Themes): Switched custom-safe-themes to use + SHA-256. + +2012-01-07 Chong Yidong <cyd@gnu.org> + + * display.texi (Useless Whitespace): Add Whitespace mode. + + * custom.texi (Hooks): Discuss how to disable minor modes. + + * files.texi (Diff Mode): Discuss diff-auto-refine-mode + (Bug#10309). Discuss use of Whitespace mode (Bug#10300). + + * trouble.texi (Lossage): Refer to Bugs node for problems. + (DEL Does Not Delete): Don't use "usual erasure key" teminology. + (Screen Garbled): Don't refer to terminal "manufacturers". + (Total Frustration): Node deleted. Eliza is documented in + Amusements now. + (Known Problems): More info about using the bug tracker. Mention + debbugs package. + (Bug Criteria): Copyedits. + (Understanding Bug Reporting): Mention emacs -Q. + +2012-01-06 Chong Yidong <cyd@gnu.org> + + * custom.texi (Specifying File Variables): The mode: keyword + doesn't have to be first anymore. Add example of specifying minor + modes. + (Directory Variables): Simplify example. Mention application to + non-file buffers. + (Disabling): Use "initialization file" terminology. + (Init Examples): Fix hook example. + +2012-01-06 Eli Zaretskii <eliz@gnu.org> + + * cmdargs.texi (MS-Windows Registry): Shorten the index entry. + (Bug#10422) + Move the stuff about resources to xresources.texi. + + * xresources.texi (Resources): Move information about setting X + resources in the Registry from cmdargs.texi. Make the index entry + be similar to the one in cmdargs.texi. + +2012-01-05 Chong Yidong <cyd@gnu.org> + + * custom.texi (Customization Groups): Update example. + (Browsing Custom): Document the new search field. + (Changing a Variable): Update example for Emacs 24 changes. + Document Custom-set and Custom-save commands. + (Face Customization): Document Emacs 24 changes. De-document + modify-face. + (Specific Customization): Mention customize-variable. + (Custom Themes): Add customize-themes, custom-theme-load-path, + custom-theme-directory, and describe-theme. + (Creating Custom Themes): New node. + (Examining): Mention M-:. + + * package.texi (Packages): Fix typo. + +2012-01-03 Chong Yidong <cyd@gnu.org> + + * misc.texi (Single Shell): Don't document Lisp usage of + shell-command. Tidy up discussion of synchronicity. Add index + entries for async-shell-command. + (Interactive Shell): Note that M-x shell uses shell-file-name. + Note change in behavior in Emacs 24. + (Shell Mode): Shell mode now uses completion-at-point. + (Shell Prompts): Emphasize that comint-use-prompt-regexp isn't the + default method for recognizing prompts nowadays. + (Shell Ring): Add xref to Minibuffer History. + (Directory Tracking): Explain Dirtrack mode in more detail. + (Term Mode): Fix index entries. + (Paging in Term): Merge into Term Mode. + (Serial Terminal, Emacs Server, emacsclient Options): Copyedits. + (Printing): Fix xref. State default of lpr-switches. + (PostScript): Remove obsolete sentence. Omit description of + non-interactive behaviors. + (Hyperlinking): Improve description. + (Browse-URL): Using compose-mail for mailto URLs is the default. + Document browse-url-mailto-function. + (Goto Address mode): Add index entries. Add xref to Browse-URL. + (FFAP): FFAP is not a minor mode. + (Amusements): M-x lm was renamed to M-x landmark. Document + nato-region. + +2012-01-01 Chong Yidong <cyd@gnu.org> + + * misc.texi (Gnus, Buffers of Gnus): Copyedits. + (Gnus Startup): Note that the system might not be set up for news. + Describe group levels more clearly. + (Gnus Group Buffer, Gnus Summary Buffer): New nodes, split from + Summary of Gnus. + (Document View): Copyedits. Move zoom commads to DocView + Navigation node. + (DocView Navigation, DocView Searching, DocView Slicing) + (DocView Conversion): Nodes renamed from Navigation, etc. + + * sending.texi (Mail Sending): Add message-kill-buffer-on-exit. + +2011-12-31 Eli Zaretskii <eliz@gnu.org> + + * basic.texi (Moving Point): Fix the description of C-n and C-p. + (Bug#10380) + +2011-12-30 Chong Yidong <cyd@gnu.org> + + * sending.texi (Sending Mail): Document initial mail buffer name, + and changed multiple mail buffer behavior. + (Mail Format): Put the example at the top of the section. + (Mail Headers): Move discussion of "From" to the top. + (Mail Sending): Document sendmail-query-once. + (Citing Mail): Make it less Rmail-specific. + +2011-12-29 Chong Yidong <cyd@gnu.org> + + * text.texi (Org Mode): Copyedits. Refer to Outline Format for + example. Add index entries. + (Org Organizer, Org Authoring): Nodes renamed. Copyedits. + +2011-12-26 Chong Yidong <cyd@gnu.org> + + * dired.texi (Dired Enter, Misc Dired Features): Document + dired-use-ls-dired changes. Mention quit-window. + (Dired Navigation): Add index entries. + (Dired Visiting): Fix View Mode xref. + (Marks vs Flags): Prefer C-/ binding for undo. + (Subdirectories in Dired): Add xrefs. + (Misc Dired Features): Document some Emacs 24 changes. Add index + entries. + + * abbrevs.texi (Abbrev Concepts): No need to mention abbrev-mode + variable, since it is explained in Minor Modes node. + (Defining Abbrevs): Copyedits. + (Expanding Abbrevs): State default of abbrev-all-caps. Prefer the + C-/ binding for undo. + (Dabbrev Customization): Add xrefs for case-fold-search and + case-replace. + + * dired-xtra.texi (Subdir Switches): Add xref. + + * maintaining.texi (VC Directory Commands): Mention quit-window. + +2011-12-25 Chong Yidong <cyd@gnu.org> + + * maintaining.texi (Tags): Mention Semantic. + (Create Tags Table, Etags Regexps): Copyedits. + (Find Tag): Mention minibuffer completion. + (List Tags): Mention completion-at-point. Completion is actually + available in M-x list-tags. + + * vc1-xtra.texi (VC Delete/Rename): Rename from Renaming and VC. + Document vc-delete-file. + + * files.texi (Misc File Ops): Mention vc-delete-file. + + * programs.texi (Symbol Completion): Mention completion-at-point + explicitly. + +2011-12-22 Chong Yidong <cyd@gnu.org> + + * maintaining.texi (Change Log Commands): Don't specially mention + vc-update-change-log which is CVS-only. + + * vc1-xtra.texi (Version Headers): Note that these are for + Subversion, CVS, etc. only. + (General VC Options): De-document vc-keep-workfiles. Fix + RCS-isms. + +2011-12-22 Eli Zaretskii <eliz@gnu.org> + + * building.texi (Debugger Operation): Fix a typo: "@end iftext" + should be @end iftex". + +2011-12-21 Chong Yidong <cyd@gnu.org> + + * maintaining.texi (Advanced C-x v v): Use fileset terminology. + (VC With A Merging VCS, VC Change Log): Add xref to VC Pull node. + (VC Pull): Mention vc-log-incoming. + (Log Buffer): Add CVS/RCS only disclaimer. + + * vc1-xtra.texi (Remote Repositories): Update introduction. + (Local Version Control): Node deleted (obsolete with DVCSes). + (Remote Repositories, Version Backups): Node deleted. Move + documentation of vc-cvs-stay-local to CVS Options. + (CVS Options): Reduce verbosity of description of obscure CVS + locking feature. + (Making Revision Tags, Revision Tag Caveats): Merge into Revision + Tags node. + (Revision Tags): Move under Miscellaneous VC subsection. + (Change Logs and VC): Note that this is wrong for DVCSs. + De-document log entry manipulating features. + (Renaming and VC): Describe how it works on modern VCSes. + + * files.texi (Misc File Ops): Mention vc-rename-file. + + * programs.texi (Custom C Indent): Add index entries. + +2011-12-20 Alan Mackenzie <acm@muc.de> + + * programs.texi (Motion in C): Update the description of C-M-a and + C-M-e, they now DTRT in enclosing scopes. + (Custom C Indent): Add @dfn{guessing} of the indentation style. + +2011-12-20 Chong Yidong <cyd@gnu.org> + + * maintaining.texi (VCS Concepts): Add "working tree" terminology. + (Old Revisions): Use it. + (VCS Repositories): Add "distributed" terminology. + (Log Buffer): Remove duplicate description + about changesets. Fix "current VC fileset" ambiguity. + (Multi-User Branching): Node deleted. + (Branches, Switching Branches): Discuss decentralized version + control systems. + (VC Pull): New node. + (Merging): Document merging on decentralized systems. + (Creating Branches): Note that this is specific to CVS and related + systems. + +2011-12-19 Chong Yidong <cyd@gnu.org> + + * maintaining.texi (VCS Merging, VCS Changesets): Index entries. + (VC Mode Line): Add index entry for "version control status". + (VC Undo): Use vc-revert instead of its vc-revert-buffer alias. + Document vc-revert-show-diff. De-document vc-rollback. + (VC Directory Mode): Rewrite introduction. Move prefix arg + documentation here from VC Directory Buffer node. + (VC Directory Buffer): Use a decentralized VCS example. + (VC Directory Commands): Use a table. Remove material duplicated + in previous nodes on multi-file VC filsets. + +2011-12-17 Chong Yidong <cyd@gnu.org> + + * maintaining.texi (VCS Concepts): Make "revision" terminology + less CVS-specific. + (VC With A Merging VCS, VC With A Locking VCS): Add xref to + Registering node. + (Secondary VC Commands): Deleted. Promote subnodes. + (Log Buffer): Add command name for C-c C-c. Fix the name of the + log buffer. Add index entries. + (VCS Changesets, Types of Log File, VC With A Merging VCS): Use + "commit" terminology. + (Old Revisions): Move it to just before VC Change Log. "Tag" here + doesn't refer to tags tables. Note other possible forms of the + revision ID. C-x v = does not save. + (Registering): Note similarity to C-x v v action. Fix description + of how backends are chosen. De-document vc-default-init-revision. + (VC Change Log): Document C-x v l in VC-Dir buffer. Document RET + in root log buffers. + +2011-12-16 Chong Yidong <cyd@gnu.org> + + * maintaining.texi (Version Control Systems): Drop Meta-CVS. + (Basic VC Editing): Remove redundant descriptions. + (VC With A Merging VCS): Make description more general instead of + CVS-specific. + (VC With A Locking VCS): Use VC fileset terminology. + 2011-12-12 Chong Yidong <cyd@gnu.org> * building.texi (Executing Lisp): Fix xref for C-M-x. diff --git a/doc/emacs/Makefile.in b/doc/emacs/Makefile.in index 66cd7f1d92e..2ed265ecd70 100644 --- a/doc/emacs/Makefile.in +++ b/doc/emacs/Makefile.in @@ -1,6 +1,6 @@ #### Makefile for the Emacs Manual -# Copyright (C) 1994, 1996-2011 Free Software Foundation, Inc. +# Copyright (C) 1994, 1996-2012 Free Software Foundation, Inc. # This file is part of GNU Emacs. diff --git a/doc/emacs/abbrevs.texi b/doc/emacs/abbrevs.texi index 2eafadf4841..2df1a6b8d5a 100644 --- a/doc/emacs/abbrevs.texi +++ b/doc/emacs/abbrevs.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Abbrevs @@ -45,17 +45,14 @@ 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 expand only when Abbrev mode, a buffer-local 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}. Abbrevs can have @dfn{mode-specific} definitions, active only in one major mode. Abbrevs can also have @dfn{global} definitions that are active in @@ -108,22 +105,18 @@ 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}. +defines a mode-specific abbrev for the current major mode. 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). + @kbd{C-x a i g} (@code{inverse-add-global-abbrev}) and @kbd{C-x a i +l} (@code{inverse-add-mode-abbrev}) perform the opposite task: if the +abbrev text is already in the buffer, you use these commands to define +an abbrev by specifying the expansion in the minibuffer. These +commands will expand the abbrev text used for the definition. @findex define-mode-abbrev @findex define-global-abbrev @@ -132,8 +125,8 @@ 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 + To change the definition of an abbrev, just make a new definition. +When an abbrev has a prior definition, the abbrev definition commands ask for confirmation before replacing it. @findex kill-all-abbrevs @@ -155,11 +148,11 @@ 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}). + Abbrev expansion preserves case: @samp{foo} expands to @samp{find +outer otter}, and @samp{Foo} to @samp{Find outer otter}. @samp{FOO} +expands to @samp{Find Outer Otter} by default, but if you change the +variable @code{abbrev-all-caps} to a non-@code{nil} value, it expands +to @samp{FIND OUTER OTTER}. These commands are used to control abbrev expansion: @@ -196,14 +189,14 @@ 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. + If you expand an abbrev by mistake, you can undo the expansion by +typing @kbd{C-/} (@code{undo}). @xref{Undo}. This undoes the +insertion of the abbrev expansion and brings back the abbrev text. 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 @@ -409,12 +402,11 @@ 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. +@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 is @code{case-fold-search} (the default), +then the variable @code{case-fold-search} controls whether to ignore +case while searching for expansions (@pxref{Search Case}). @vindex dabbrev-case-replace Normally, dynamic abbrev expansion preserves the case pattern @@ -425,10 +417,10 @@ expansion to that case pattern. 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. +@code{nil}, the expansion is always copied verbatim. If the value is +@code{case-replace} (the default), then the variable +@code{case-replace} controls whether to copy the expansion verbatim +(@pxref{Replacement and Case}). However, if the expansion contains a complex mixed case pattern, and the dynamic abbrev matches this pattern as far as it goes, then the diff --git a/doc/emacs/ack.texi b/doc/emacs/ack.texi index ae6338ce5a6..184f8272cab 100644 --- a/doc/emacs/ack.texi +++ b/doc/emacs/ack.texi @@ -1,6 +1,6 @@ @c -*- coding: iso-latin-1 -*- @c This is part of the Emacs manual. -@c Copyright (C) 1994-1997, 1999-2011 Free Software Foundation, Inc. +@c Copyright (C) 1994-1997, 1999-2012 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @c @node Acknowledgments, Screen, Concept Index, Top @@ -1183,7 +1183,7 @@ 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 +Steve Strassmann 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 diff --git a/doc/emacs/anti.texi b/doc/emacs/anti.texi index 1ee93362ae6..68f617d2cfd 100644 --- a/doc/emacs/anti.texi +++ b/doc/emacs/anti.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2005-2011 Free Software Foundation, Inc. +@c Copyright (C) 2005-2012 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Antinews, Mac OS / GNUstep, X Resources, Top diff --git a/doc/emacs/arevert-xtra.texi b/doc/emacs/arevert-xtra.texi index 6a24646b5f7..350f16f51dc 100644 --- a/doc/emacs/arevert-xtra.texi +++ b/doc/emacs/arevert-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2011 Free Software Foundation, Inc. +@c Copyright (C) 2004-2012 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 diff --git a/doc/emacs/basic.texi b/doc/emacs/basic.texi index abb65982873..3e768ab54d7 100644 --- a/doc/emacs/basic.texi +++ b/doc/emacs/basic.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Basic, Minibuffer, Exiting, Top @@ -130,11 +130,13 @@ specifies how many copies of the character to insert @cindex moving the cursor To do more than insert characters, you have to know how to move point (@pxref{Point}). The keyboard commands @kbd{C-f}, @kbd{C-b}, -@kbd{C-n}, and @kbd{C-p} move point to the right, left, up and down +@kbd{C-n}, and @kbd{C-p} move point to the right, left, down, and up, respectively. You can also move point using the @dfn{arrow keys} present on most keyboards: @kbd{@key{right}}, @kbd{@key{left}}, @kbd{@key{down}}, and @kbd{@key{up}}; however, many Emacs users find -that it is slower to use the arrow keys than the control keys. +that it is slower to use the arrow keys than the control keys, because +you need to move your hand to the area of the keyboard where those +keys are located. You can also click the left mouse button to move point to the position clicked. Emacs also provides a variety of additional diff --git a/doc/emacs/buffers.texi b/doc/emacs/buffers.texi index 302693aecef..fb71e04c184 100644 --- a/doc/emacs/buffers.texi +++ b/doc/emacs/buffers.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Buffers, Windows, Files, Top diff --git a/doc/emacs/building.texi b/doc/emacs/building.texi index ab4a485cb87..7a94ba56052 100644 --- a/doc/emacs/building.texi +++ b/doc/emacs/building.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Building, Maintaining, Programs, Top @@ -24,9 +24,9 @@ assist in the process of compiling and testing programs. * Executing Lisp:: Various modes for editing Lisp programs, with different facilities for running the Lisp programs. -* Lisp Libraries:: How Lisp programs are loaded into Emacs. -* Lisp Eval:: Executing a single Lisp expression in Emacs. -* Lisp Interaction:: Executing Lisp in an Emacs buffer. +* Libraries: Lisp Libraries. How Lisp programs are loaded into 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 @@ -550,7 +550,7 @@ This is the basic interface for interacting with a debugger, used by @kbd{M-x gud-gdb} and other commands listed in @iftex the preceding section. -@end iftext +@end iftex @ifnottex @ref{Starting GUD}. @end ifnottex @@ -565,7 +565,7 @@ Mode}). Completion is available for most debugger commands commands to repeat them. @iftex See the next section -@end iftext +@end iftex @ifnottex @xref{Commands of GUD}, @end ifnottex diff --git a/doc/emacs/cal-xtra.texi b/doc/emacs/cal-xtra.texi index 6d20c92a6d9..4d37672b6ca 100644 --- a/doc/emacs/cal-xtra.texi +++ b/doc/emacs/cal-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2011 Free Software Foundation, Inc. +@c Copyright (C) 2004-2012 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 @@ -41,12 +41,12 @@ customize the variables @code{calendar-intermonth-header} and @vindex calendar-holiday-marker @vindex diary-entry-marker -@vindex calenday-today-marker +@vindex calendar-today-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, and @code{calenday-today-marker} is used by +date that has diary entries, and @code{calendar-today-marker} is used by the function @code{calendar-mark-today} to mark today's date. By default, the calendar uses faces named @code{holiday}, @code{diary}, and @code{calendar-today} for these purposes. diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi index 4a09d6e3d9c..495828d6d8a 100644 --- a/doc/emacs/calendar.texi +++ b/doc/emacs/calendar.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Calendar/Diary diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index d9109045570..11cc4df8ce9 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Emacs Invocation, X Resources, GNU Free Documentation License, Top @@ -675,9 +675,9 @@ changing any environment or registry settings. @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 +@cindex registry, setting environment variables (MS-Windows) -Under MS-Windows, the installation program @command{addpm.exe} adds +On 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 @@ -704,10 +704,6 @@ 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 diff --git a/doc/emacs/commands.texi b/doc/emacs/commands.texi index 817cfc369d1..f2a71b045f8 100644 --- a/doc/emacs/commands.texi +++ b/doc/emacs/commands.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @iftex diff --git a/doc/emacs/custom.texi b/doc/emacs/custom.texi index e807aebdeee..82a63996a64 100644 --- a/doc/emacs/custom.texi +++ b/doc/emacs/custom.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Customization @@ -30,287 +30,291 @@ Reference Manual}. * Key Bindings:: The keymaps say what command each key runs. By changing them, you can "redefine keys". * Init File:: How to write common customizations in the - @file{.emacs} file. + initialization file. @end menu @node Easy Customization @section Easy Customization Interface @cindex settings - Emacs has many @dfn{settings} which have values that you can change. -Many are documented in this manual. Most settings are @dfn{user -options}---that is to say, Lisp variables (@pxref{Variables})---and -their names appear in the Variable Index (@pxref{Variable Index}). -The other settings are faces and their attributes (@pxref{Faces}). +@cindex user option +@cindex customizable variable + Emacs has many @dfn{settings} which you can change. Most settings +are @dfn{customizable variables} (@pxref{Variables}), which are also +called @dfn{user options}. There is a huge number of customizable +variables, controlling numerous aspects of Emacs behavior; the +variables documented in this manual are listed in @ref{Variable +Index}. A separate class of settings are the @dfn{faces}, which +determine the fonts, colors, and other attributes of text +(@pxref{Faces}). @findex customize @cindex customization buffer - You can browse settings and change them using @kbd{M-x customize}. -This creates a @dfn{customization buffer}, which lets you navigate -through a logically organized list of settings, edit and set their -values, and save them permanently in your initialization file -(@pxref{Init File}). + To browse and alter settings (both variables and faces), type +@kbd{M-x customize}. This creates a @dfn{customization buffer}, which +lets you navigate through a logically organized list of settings, edit +and set their values, and save them permanently. @menu -* Customization Groups:: How settings are classified in a structure. +* Customization Groups:: How settings are classified. * 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. +* Saving Customizations:: Saving customizations for future Emacs sessions. * 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. +* Specific Customization:: Customizing specific settings or groups. +* Custom Themes:: Collections of customization settings. +* Creating Custom Themes:: How to create a new custom theme. @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}. + Customization settings are organized into @dfn{customization +groups}. These 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: +top-level @code{Emacs} group. 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: Customization of the One True Editor. -------------\ - [State]: visible group members are all at standard values. +To apply changes, use the Save or Set buttons. +For details, see [Saving Customizations] in the [Emacs manual]. + +________________________________________ [ Search ] + + Operate on all settings in this buffer: + [ Set for current session ] [ Save for future sessions ] + [ Undo edits ] [ Reset to saved ] [ Erase customizations ] [ Exit ] - See also [Manual]. + +Emacs group: Customization of the One True Editor. + [State]: visible group members are all at standard values. + See also [Manual]. [Editing] : Basic text editing facilities. -[External] : Interfacing to external utilities. +[Convenience] : Convenience features for faster editing. @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. +The main part of this buffer shows the @samp{Emacs} customization +group, which contains several other groups (@samp{Editing}, +@samp{Convenience}, etc.). The contents of those groups are not +listed here, only one line of documentation each. + + The @dfn{state} of the group indicates whether setting in that group +has been edited, set or saved. @xref{Changing a Variable}. @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. Each group name, such as @samp{[Editing]}, is a hypertext -link to that group; invoking it creates a new customization buffer, -showing the group and its contents. - - The @code{Emacs} group only contains other groups. These groups, in -turn, can contain settings or still more groups. 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}. + Most of the customization buffer is read-only, but it includes some +@dfn{editable fields} that you can edit. For example, at the top of +the customization buffer is an editable field for searching for +settings (@pxref{Browsing Custom}). There are also @dfn{buttons} and +@dfn{links}, which you can activate by either clicking with the mouse, +or moving point there and typing @key{RET}. For example, the group +names like @samp{[Editing]} are links; activating one of these links +brings up the customization buffer for that group. + +@kindex TAB @r{(customization buffer)} +@kindex S-TAB @r{(customization buffer)} +@findex widget-forward +@findex widget-backward + In the customizable buffer, you can type @key{TAB} +(@code{widget-forward}) to move forward to the next button or editable +field. @kbd{S-@key{TAB}} (@code{widget-backward}) moves back to the +previous button or editable field. @node Browsing Custom -@subsection Browsing and Searching for Options and Faces +@subsection Browsing and Searching for Settings @findex customize-browse + From the top-level customization buffer created by @kbd{M-x +customize}, you can follow the links to the subgroups of the +@samp{Emacs} customization group. These subgroups may contain +settings for you to customize; they may also contain futher subgroups, +dealing with yet more specialized subsystems of Emacs. As you +navigate the hierarchy of customization groups, you should find some +settings that you want to customize. + + If you are interested in customizing a particular setting or +customization group, you can go straight there with the commands +@kbd{M-x customize-option}, @kbd{M-x customize-face}, or @kbd{M-x +customize-group}. @xref{Specific Customization}. + +@vindex custom-search-field + If you don't know exactly what groups or settings you want to +customize, you can search for them using the editable search field at +the top of each customization buffer. Here, you can type in a search +term---either one or more words separated by spaces, or a regular +expression (@pxref{Regexps}). Then type @key{RET} in the field, or +activate the @samp{Search} button next to it, to switch to a +customization buffer containing groups and settings that match those +terms. Note, however, that this feature only finds groups and +settings that are loaded in the current Emacs session. + + If you don't want customization buffers to show the search field, +change the variable @code{custom-search-field} to @code{nil}. + + The command @kbd{M-x customize-apropos} is similar to using the +search field, except that it reads the search term(s) using the +minibuffer. @xref{Specific Customization}. + @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}. +shows only the names of groups and settings, in a structured layout. +You can show the contents of a group, in the same buffer, by invoking +the @samp{[+]} button next to the group name. When the group contents +are shown, the 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, option, or face; this is the way to change settings that you +find with @kbd{M-x customize-browse}. @node Changing a Variable @subsection Changing a Variable - Here is an example of what a variable (a user option) looks like in + Here is an example of what a variable, or user option, looks like in the customization buffer: @smallexample -Kill Ring Max: [Hide Value] 60 +[Hide] Kill Ring Max: 60 [State]: STANDARD. -Maximum length of kill ring before oldest elements are thrown away. + 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 first line shows that the variable is named +@code{kill-ring-max}, formatted as @samp{Kill Ring Max} for easier +viewing. Its value is @samp{60}. The button labeled @samp{[Hide]}, +if activated, hides the variable's value and state; this is useful to +avoid cluttering up the customization buffer with very long values +(for this reason, variables that have very long values may start out +hidden). If you use the @samp{[Hide]} button, it changes to +@samp{[Show Value]}, which you can activate to reveal the value and +state. On a graphical display, the @samp{[Hide]} and @samp{[Show +Value]} buttons are replaced with graphical triangles pointing +downwards and rightwards respectively. 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 +state} of the variable: in this example, @samp{STANDARD} means you +have not changed the variable, so its value is the default one. The +@samp{[State]} button gives a menu of 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. + Below the customization state is the documentation for the variable. +This is the same documentation that would be shown by the @kbd{C-h v} +command (@pxref{Examining}). If the documentation is more than one +line long, only one line may be shown. If so, that line ends with a +@samp{[More]} button; activate this to see the full documentation. - 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: +@cindex user options, changing +@cindex customizing variables +@cindex variables, changing + To enter a new value for @samp{Kill Ring Max}, just move point to +the value and edit it. For example, type @kbd{M-d} to delete the +@samp{60} and type in another number. As you begin to alter the text, +the @samp{[State]} line will change: @smallexample -[State]: EDITED, shown value does not take effect until you set or @r{@dots{}} - save it. +[State]: EDITED, shown value does not take effect until you + set or 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: +@noindent +Editing the value does not make it take effect right away. To do +that, you must @dfn{set} the variable by activating the @samp{[State]} +button and choosing @samp{Set for Current Session}. Then the +variable's state becomes: @smallexample [State]: SET for current session only. @end smallexample - You don't have to worry about specifying a value that is not valid; +@noindent +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)} +@kindex C-M-i @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. + While editing certain kinds of values, such as file names, directory +names, and Emacs command names, you can perform completion with +@kbd{C-M-i} (@code{widget-complete}), or the equivalent keys +@kbd{M-@key{TAB}} or @kbd{@key{ESC} @key{TAB}}. This behaves much +like minibuffer completion (@pxref{Completion}). + + Typing @key{RET} on an editable value field moves point forward to +the next field or button, like @key{TAB}. You can thus type @key{RET} +when you are finished editing a field, to move on to the next button +or field. To insert a newline within an editable field, use @kbd{C-o} +or @kbd{C-q C-j}. + + For some variables, there is only a fixed set of legitimate values, +and you are not allowed to edit the value directly. Instead, a +@samp{[Value Menu]} button appears before the value; activating this +button presents a choice of values. For a boolean ``on or off'' +value, the button says @samp{[Toggle]}, and flips the value. After +using the @samp{[Value Menu]} or @samp{[Toggle]} button, you must +again set the variable to make the chosen value take effect. Some variables have values with complex structure. For example, the -value of @code{file-coding-system-alist} is an association list. Here +value of @code{minibuffer-frame-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 +[Hide] Minibuffer Frame Alist: +[INS] [DEL] Parameter: width + Value: 80 +[INS] [DEL] Parameter: height + Value: 2 [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{}]} + [ State ]: STANDARD. + Alist of parameters for the initial minibuffer frame. [Hide] + @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}. You can thus type @key{RET} when you are finished editing -a field, to move on to the next button or field. To insert a newline -within an editable field, use @kbd{C-o} or @kbd{C-q C-j}. +In this case, each association in the list consists of two items, one +labeled @samp{Parameter} and one labeled @samp{Value}; both are +editable fields. You can delete an association from the list with the +@samp{[DEL]} button next to it. To add an association, use the +@samp{[INS]} button at the position where you want to insert it; the +very last @samp{[INS]} button inserts at the end of the list. @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}). + When you set a variable, the new value takes effect only in the +current Emacs session. To @dfn{save} the value for future sessions, +use the @samp{[State]} button and select the @samp{Save for Future +Sessions} operation. @xref{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: + You can also restore the variable to its standard value by using the +@samp{[State]} button 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. +If you have modified but 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. +This sets the variable to its standard value. Any saved value that +you have is also eliminated. @item Set to Backup Value This sets the variable to a previous value that was set in the @@ -322,40 +326,51 @@ you can get the discarded value back again with this operation. @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. +@samp{[State]} menu to create a field for entering the comment. - 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: + Near the top of the customization buffer 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. +Each of the first five buttons performs the stated operation---set, +save, reset, etc.---on all the settings in the buffer that could +meaningfully be affected. They do not operate on settings that are +hidden, nor on subgroups that are hidden or not visible in the buffer. + +@kindex C-c C-c @r{(customization buffer)} +@kindex C-x C-c @r{(customization buffer)} +@findex Custom-set +@findex Custom-save + The command @kbd{C-c C-c} (@code{Custom-set}) is equivalent using to +the @samp{[Set for Current Session]} button. The command @kbd{C-x +C-s} (@code{Custom-save}) is like using the @samp{[Save for Future +Sessions]} button. + +@vindex custom-buffer-done-kill + The @samp{[Finish]} button switches out of the customization buffer, +and buries the buffer at the bottom of the buffer list. To make it +kill the customization buffer instead, change the variable +@code{custom-buffer-done-kill} to @code{t}. @node Saving Customizations @subsection Saving Customizations -@vindex custom-file - Saving customizations from the customization buffer works by writing -code to a file. By reading this code, future sessions can set up the -customizations again. Normally, the code is saved in your -initialization file (@pxref{Init File}). + In the customization buffer, you can @dfn{save} a customization +setting by choosing the @samp{Save for Future Sessions} choice from +its @samp{[State]} button. The @kbd{C-x C-s} (@code{Custom-save}) +command, or the @samp{[Save for Future Sessions]} button at the top of +the customization buffer, saves all applicable settings in the buffer. - You can choose to save your customizations in a file other than your + Saving works by writing code to a file, usually your initialization +file (@pxref{Init File}). Future Emacs sessions automatically read +this file at startup, which sets up the customizations again. + +@vindex custom-file + You can choose to save customizations somewhere other than your initialization file. To make this work, you must add a couple of lines of code to your initialization file, to set the variable @code{custom-file} to the name of the desired file, and to load that @@ -366,8 +381,8 @@ file. For example: (load custom-file) @end example - You can use @code{custom-file} to specify different customization -files for different Emacs versions, like this: + You can even specify different customization files for different +Emacs versions, like this: @example (cond ((< emacs-major-version 22) @@ -393,80 +408,92 @@ customizations you might have on your initialization file. @node Face Customization @subsection Customizing Faces @cindex customizing faces -@cindex bold font -@cindex italic font +@cindex faces, customizing @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: + You can customize faces (@pxref{Faces}), which determine how Emacs +displays different types of text. Customization groups can contain +both variables and faces. + + For example, in programming language modes, source code comments are +shown with @code{font-lock-comment-face} (@pxref{Font Lock}). In a +customization buffer, that face appears like this: @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: * +[Hide] Font Lock Comment Face:[sample] + [State] : STANDARD. + Font Lock mode face used to highlight comments. + [ ] Font Family: -- + [ ] Font Foundry: -- + [ ] Width: -- + [ ] Height: -- + [ ] Weight: -- + [ ] Slant: -- + [ ] Underline: -- + [ ] Overline: -- + [ ] Strike-through: -- + [ ] Box around text: -- + [ ] Inverse-video: -- + [X] Foreground: Firebrick [Choose] (sample) + [ ] Background: -- + [ ] Stipple: -- + [ ] Inherit: -- + [Hide Unused Attributes] @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. - - The foreground and background colors can be specified using color -names or RGB triplets. @xref{Colors}. +@noindent +The first three lines show the name, @samp{[State]} button, and +documentation for the face. Below that is a list of @dfn{face +attributes}. In front of each attribute is a checkbox. A filled +checkbox, @samp{[X]}, means that the face specifies a value for this +attribute; an empty checkbox, @samp{[ ]}, means that the face does not +specify any special value for the attribute. You can activate a +checkbox to specify or unspecify its attribute. + + Most faces only specify a few attributes (in the above example, +@code{font-lock-comment-face} only specifies the foreground color). +Emacs has a special face, @code{default}, whose attributes are all +specified; it determines the attributes left unspecified by other +faces. + + The @samp{Hide Unused Attributes} button, at the end of the +attribute list, hides the unspecified attributes of the face. When +attributes are being hidden, the button changes to @samp{[Show All +Attributes]}, which reveals the entire attribute list. The +customization buffer may start out with unspecified attributes hidden, +to avoid cluttering the interface. + + When an attribute is specified, you can change its value in the +usual ways. + + Foreground and background colors can be specified using either color +names or RGB triplets (@pxref{Colors}). You can also use the +@samp{[Choose]} button to switch to a list of color names; select a +color with @key{RET} in that buffer to put the color name in the value +field. 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 +displays. 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}. +@itemx M-x customize-variable @key{RET} @var{option} @key{RET} +Set up a customization buffer for just one user option, @var{option}. @item M-x customize-face @key{RET} @var{face} @key{RET} -Set up a customization buffer with just one face, @var{face}. +Set up a customization buffer for 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}. +Set up a customization buffer for 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 +Set up a customization buffer for 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 @@ -480,35 +507,24 @@ 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. + If you want to customize a particular user option, type @kbd{M-x +customize-option}. This reads the variable name, and sets up the +customization buffer with just that one user option. When entering +the variable name into the minibuffer, completion is available, but +only for the names of variables that have been loaded into Emacs. @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. + Likewise, you can customize a specific face using @kbd{M-x +customize-face}. You can set up a customization buffer for a specific +customization group using @kbd{M-x customize-group}. @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. + @kbd{M-x customize-apropos} prompts for a search term---either one +or more words separated by spaces, or a regular expression---and sets +up a customization buffer for all @emph{loaded} settings and groups +with matching names. This is like using the search field at the top +of the customization buffer (@pxref{Customization Groups}). @findex customize-changed When you upgrade to a new Emacs version, you might want to consider @@ -522,78 +538,159 @@ 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. +can use two commands to revisit your changes. Use @kbd{M-x +customize-saved} to customize settings that you have saved. Use +@kbd{M-x customize-unsaved} to customize settings that you have set +but not saved. @node Custom Themes -@subsection Customization Themes +@subsection Custom 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. +or disabled as a unit. You can use Custom themes to switch 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 labeled @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}. + A Custom theme is stored an Emacs Lisp source file. If the name of +the Custom theme is @var{name}, the theme file is named +@file{@var{name}-theme.el}. @xref{Creating Custom Themes}, for the +format of a theme file and how to make one. +@findex customize-themes @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. +@cindex color scheme + Type @kbd{M-x customize-themes} to switch to a buffer named +@samp{*Custom Themes*}, which lists the Custom themes that Emacs knows +about. By default, Emacs looks for theme files in two locations: the +directory specified by the variable @code{custom-theme-directory} +(which defaults to @file{~/.emacs.d/}), and a directory named +@file{etc/themes} in your Emacs installation (see the variable +@code{data-directory}). The latter contains several Custom themes +which are distributed with Emacs, which customize Emacs' faces to fit +various color schemes. (Note, however, that Custom themes need not be +restricted to this purpose; they can be used to customize variables +too). + +@vindex custom-theme-load-path + If you want Emacs to look for Custom themes in some other directory, +add the directory name to the list variable +@code{custom-theme-load-path}. Its default value is +@code{(custom-theme-directory t)}; here, the symbol +@code{custom-theme-directory} has the special meaning of the value of +the variable @code{custom-theme-directory}, while @code{t} stands for +the built-in theme directory @file{etc/themes}. The themes listed in +the @samp{*Custom Themes*} buffer are those found in the directories +specified by @code{custom-theme-load-path}. + +@kindex C-x C-s @r{(Custom Themes buffer)} + In the @samp{*Custom Themes*} buffer, you can activate the checkbox +next to a Custom theme to enable or disable the theme for the current +Emacs session. When a Custom theme is enabled, all of its settings +(variables and faces) take effect in the Emacs session. To apply the +choice of theme(s) to future Emacs sessions, type @kbd{C-x C-s} +(@code{custom-theme-save}) or use the @samp{[Save Theme Settings]} +button. + +@vindex custom-safe-themes + When you first enable a Custom theme, Emacs displays the contents of +the theme file and asks if you really want to load it. Because +loading a Custom theme can execute arbitrary Lisp code, you should +only say yes if you know that the theme is safe; in that case, Emacs +offers to remember in the future that the theme is safe (this is done +by saving the theme file's SHA-256 hash to the variable +@code{custom-safe-themes}; if you want to treat all themes as safe, +change its value to @code{t}). Themes that come with Emacs (in the +@file{etc/themes} directory) are exempt from this check, and are +always considered safe. @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. + Setting or saving Custom themes actually works by customizing the +variable @code{custom-enabled-themes}. The value of this variable is +a list of Custom theme names (as Lisp symbols, e.g.@: @code{tango}). +Instead of using the @samp{*Custom Themes*} buffer to set +@code{custom-enabled-themes}, you can customize the variable using the +usual customization interface, e.g.@: with @kbd{M-x customize-option}. +Note that Custom themes are not allowed to set +@code{custom-enabled-themes} themselves. + + Any customizations that you make through the customization buffer +take precedence over theme settings. This lets you easily override +individual theme settings that you disagree with. If settings from +two different themes overlap, the theme occurring earlier in +@code{custom-enabled-themes} takes precedence. In the customization +buffer, if a setting has been changed from its default by a Custom +theme, its @samp{State} display shows @samp{THEMED} instead of +@samp{STANDARD}. @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.) + You can enable a specific Custom theme in the current Emacs session +by typing @kbd{M-x load-theme}. This prompts for a theme name, loads +the theme from the theme file, and enables the theme. If a theme file +has been loaded before, you can enable the theme without loading its +file by typing @kbd{M-x enable-theme}. To disable a Custom theme, +type @kbd{M-x disable-theme}. + +@findex describe-theme + To see a description of a Custom theme, type @kbd{?} on its line in +the @samp{*Custom Themes*} buffer; or type @kbd{M-x describe-theme} +anywhere in Emacs and enter the theme name in the minibuffer. + +@node Creating Custom Themes +@subsection Creating Custom Themes +@cindex custom themes, creating + +@findex customize-create-theme + You can define a Custom theme using an interface similar to the +customization buffer, by typing @kbd{M-x customize-create-theme}. +This switches to a buffer named @samp{*Custom Theme*}. It also offers +to insert some common Emacs faces into the theme (a convenience, since +Custom themes are often used to customize faces). If you answer no, +the theme will initially contain no settings. + + Near the top of the @samp{*Custom Theme*} buffer are editable fields +where you can enter the theme's name and description. The name can be +anything except @samp{user}. The description is the one that will be +shown when you invoke @kbd{M-x describe-theme} for the theme. Its +first line should be a brief one-sentence summary; in the buffer made +by @kbd{M-x customize-themes}, this sentence is displayed next to the +theme name. + + To add a new setting to the theme, use the @samp{[Insert Additional +Face]} or @samp{[Insert Additional Variable]} buttons. Each button +reads a face or variable name using the minibuffer, with completion, +and inserts a customization entry for the face or variable. You can +edit the variable values or face attributes in the same way as in a +normal customization buffer. To remove a face or variable from the +theme, uncheck the checkbox next to its name. + +@vindex custom-theme-directory + After specifying the Custom theme's faces and variables, type +@kbd{C-x C-s} (@code{custom-theme-write}) or use the buffer's +@samp{[Save Theme]} button. This saves the theme file, named +@file{@var{name}-theme.el} where @var{name} is the theme name, in the +directory named by @code{custom-theme-directory}. + + From the @samp{*Custom Theme*} buffer, you can view and edit an +existing Custom theme by activating the @samp{[Visit Theme]} button +and specifying the theme name. You can also add the settings of +another theme into the buffer, using the @samp{[Merge Theme]} button. +You can import your non-theme settings into a Custom theme by using +the @samp{[Merge Theme]} button and specifying the special theme named +@samp{user}. + + A theme file is simply an Emacs Lisp source file, and loading the +Custom theme works by loading the Lisp file. Therefore, you can edit +a theme file directly instead of using the @samp{*Custom Theme*} +buffer. +@c Add link to the relevant Emacs Lisp Reference manual node, once +@c that is written. @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 @dfn{variable name}. A variable name can @@ -609,10 +706,10 @@ using the help command @kbd{C-h v} (@code{describe-variable}). 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}. @xref{Easy -Customization}, for information about using the Customize facility to -set user options. In the following sections, we will describe other -aspects of Emacs variables, such as how to set them outside Customize. +for users to change---these are called @dfn{customizable variables} or +@dfn{user options} (@pxref{Easy Customization}). In the following +sections, we will describe other aspects of Emacs variables, such as +how to set them outside Customize. Emacs Lisp allows any variable (with a few exceptions) to have any kind of value. However, many variables are meaningful only if @@ -654,9 +751,9 @@ Display the value and documentation of variable @var{var} 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 + To examine the value of a variable, use @kbd{C-h v} +(@code{describe-variable}). This reads a variable name using the +minibuffer, with completion, and displays both the value and the documentation of the variable. For example, @example @@ -686,10 +783,10 @@ You can customize this variable. @noindent The line that says ``You can customize the variable'' indicates that this variable is a user option. @kbd{C-h v} is not restricted to user -options; it allows any variable name. +options; it allows non-customizable variables too. @findex set-variable - The most convenient way to set a specific user option variable is + The most convenient way to set a specific customizable 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 @@ -702,22 +799,23 @@ M-x set-variable @key{RET} fill-column @key{RET} 75 @key{RET} @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}: + @kbd{M-x set-variable} is limited to customizable variables, but you +can set any variable with a Lisp expression like this: @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}. +@noindent +To execute such an expression, type @kbd{M-:} (@code{eval-expression}) +and enter the expression in the minibuffer (@pxref{Lisp Eval}). +Alternatively, go to the @samp{*scratch*} buffer, type in the +expression, and then type @kbd{C-j} (@pxref{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 -your initialization file to set it those sessions (@pxref{Init File}). +your initialization file (@pxref{Init File}). @node Hooks @subsection Hooks @@ -759,17 +857,34 @@ Manual}, for details. Most major modes run one or more @dfn{mode hooks} as the last step of initialization. Mode hooks are a convenient way to customize the behavior of individual modes; they are always normal. 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: +here's how to set up a hook to turn on Auto Fill mode in Text mode and +other modes based on Text mode: @example (add-hook 'text-mode-hook 'auto-fill-mode) @end example - Here is another example, showing how to use a hook to customize the -indentation of C code. The hook function uses an anonymous lambda -expression (@pxref{Lambda Expressions,,, elisp, The Emacs Lisp -Reference Manual}). +@noindent +This works by calling @code{auto-fill-mode}, which enables the minor +mode when no argument is supplied (@pxref{Minor Modes}). Next, +suppose you don't want Auto Fill mode turned on in La@TeX{} mode, +which is one of the modes based on Text mode. You can do this with +the following additional line: + +@example +(add-hook 'latex-mode-hook (lambda () (auto-fill-mode -1))) +@end example + +@noindent +Here we have used the special macro @code{lambda} to construct an +anonymous function (@pxref{Lambda Expressions,,, elisp, The Emacs Lisp +Reference Manual}), which calls @code{auto-fill-mode} with an argument +of @code{-1} to disable the minor mode. Because La@TeX{} mode runs +@code{latex-mode-hook} after running @code{text-mode-hook}, the result +leaves Auto Fill mode disabled. + + Here is a more complex example, showing how to use a hook to +customize the indentation of C code: @example @group @@ -792,8 +907,8 @@ Reference Manual}). @cindex program editing Major mode hooks also apply to other major modes @dfn{derived} from the original mode (@pxref{Derived Modes,,, elisp, The Emacs Lisp -Reference Manual}). For instance, HTML mode (@pxref{HTML Mode}) -inherits from Text mode; when HTML mode is enabled, it runs +Reference Manual}). For instance, HTML mode is derived from Text mode +(@pxref{HTML Mode}); when HTML mode is enabled, it runs @code{text-mode-hook} before running @code{html-mode-hook}. This provides a convenient way to use a single hook to affect several related modes. In particular, if you want to apply a hook function to @@ -910,7 +1025,7 @@ explicitly. For example, here's how to obtain the default value of @cindex local variables in files @cindex file local variables - A file can specify local variable values for use when you edit the + A file can specify local variable values to use when editing 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. @@ -933,21 +1048,20 @@ first line: @noindent You can specify any number of variable/value pairs in this way, each -pair with a colon and semicolon as shown above. The special -variable/value pair @code{mode: @var{modename};}, if present, -specifies a major mode, and should come first in the line. The +pair with a colon and semicolon. The special variable/value pair +@code{mode: @var{modename};}, if present, specifies a major mode. The @var{value}s are used literally, and not evaluated. @findex add-file-local-variable-prop-line @findex delete-file-local-variable-prop-line @findex copy-dir-locals-to-file-locals-prop-line - You can use the command @code{add-file-local-variable-prop-line} -instead of adding entries by hand. It prompts for a variable -and value, and adds them to the first line in the appropriate way. -The command @code{delete-file-local-variable-prop-line} deletes a -variable from the line. The command -@code{copy-dir-locals-to-file-locals-prop-line} copies directory-local -variables (@pxref{Directory Variables}) to the first line. + Instead of adding variable/value pairs by hand, you can use the +command @kbd{M-x add-file-local-variable-prop-line}. This prompts for +a variable and value, and adds them to the first line in the +appropriate way. @kbd{M-x delete-file-local-variable-prop-line} +prompts for a variable, and deletes its entry from the line. @kbd{M-x +copy-dir-locals-to-file-locals-prop-line} copies directory-local +variables to the first line (@pxref{Directory Variables}). Here is an example first line that specifies Lisp mode and sets two variables with numeric values: @@ -971,7 +1085,7 @@ same is true for man pages which start with the magic string @samp{'\"} to specify a list of troff preprocessors (not all do, however). - Instead of using a @samp{-*-} line, you can define file local + Apart from using a @samp{-*-} line, you can define file local variables using a @dfn{local variables list} near the end of the file. The start of the local variables list should be no more than 3000 characters from the end of the file, and must be on the last page if @@ -990,10 +1104,10 @@ part of their initialization. per line, like this: @example -/* Local Variables: */ -/* mode:c */ -/* comment-column:0 */ -/* End: */ +/* Local Variables: */ +/* mode: c */ +/* comment-column: 0 */ +/* End: */ @end example @noindent @@ -1004,23 +1118,23 @@ the first line of the list; it then 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 for. The -example above is for the C programming language, where comment lines -start with @samp{/*} and end with @samp{*/}. +example above is for the C programming language, where comments start +with @samp{/*} and end with @samp{*/}. @findex add-file-local-variable @findex delete-file-local-variable @findex copy-dir-locals-to-file-locals - You can construct the local variables list yourself, or use the -command @code{add-file-local-variable}. This prompts for a variable -and value, and adds them to the list. If necessary, it also adds the -start and end markers. The command @code{delete-file-local-variable} -deletes a variable from the list. The command -@code{copy-dir-locals-to-file-locals} copies directory-local variables -(@pxref{Directory Variables}) to the list. + Instead of typing in the local variables list directly, you can use +the command @kbd{M-x add-file-local-variable}. This prompts for a +variable and value, and adds them to the list, adding the @samp{Local +Variables:} string and start and end markers as necessary. The +command @kbd{M-x delete-file-local-variable} deletes a variable from +the list. @kbd{M-x copy-dir-locals-to-file-locals} copies +directory-local variables to the list (@pxref{Directory Variables}). As with the @samp{-*-} line, the variables in a local variables list are used literally, and are not evaluated first. If you want to split -a long string across multiple lines of the file, you can use +a long string value across multiple lines of the file, you can use backslash-newline, which is ignored in Lisp string constants; you should put the prefix and suffix on each line, even lines that start or end within the string, as they will be stripped off when processing @@ -1054,24 +1168,35 @@ value is @code{t}. @xref{Enabling Multibyte}. @end itemize @noindent -These four ``variables'' are not really variables; setting them in any +These four keywords are not really variables; setting them in any other context has no special meaning. - You can use the @code{mode} ``variable'' to enable 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 enable minor modes which are -specific to particular buffers. Using @code{mode} for minor modes -is deprecated, though---instead, use @code{eval: (minor-mode 1)}. - - Often, however, it is a mistake to enable minor modes in file local -variables. Most minor modes, like Auto Fill mode, represent individual user -preferences. If you want to use a minor mode, it is better to set up -major mode hooks with your init file to turn that minor mode on for -yourself alone (@pxref{Init File}), instead of using a local variable -list to impose your taste on everyone. - - Use the command @code{normal-mode} to reset the local variables and -major mode of a buffer according to the file name and contents, + Do not use the @code{mode} keyword for minor modes. To enable or +disable a minor mode in a local variables list, use the @code{eval} +keyword with a Lisp expression that runs the mode command +(@pxref{Minor Modes}). For example, the following local variables +list enables Eldoc mode (@pxref{Lisp Doc}) by calling +@code{eldoc-mode} with no argument (calling it with an argument of 1 +would do the same), and disables Font Lock mode (@pxref{Font Lock}) by +calling @code{font-lock-mode} with an argument of -1. + +@example +;; Local Variables: +;; eval: (eldoc-mode) +;; eval: (font-lock-mode -1) +;; End: +@end example + +@noindent +Note, however, that it is often a mistake to specify minor modes this +way. Minor modes represent individual user preferences, and it may be +inappropriate to impose your preferences on another user who might +edit the file. If you wish to automatically enable or disable a minor +mode in a situation-dependent way, it is often better to do it in a +major mode hook (@pxref{Hooks}). + + Use the command @kbd{M-x 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 @@ -1139,85 +1264,81 @@ confirmation about processing @code{eval} variables. @node Directory Variables @subsection Per-Directory Local Variables @cindex local variables, for all files in a directory -@cindex directory local variables +@cindex directory-local variables @cindex per-directory local variables - A @dfn{project} is a collection of files on which you work together. -Usually, the project's files are kept in one or more directories. -Occasionally, you may wish to define Emacs settings that are common to -all the files that belong to the project. - - Emacs provides two ways to specify settings that are applicable to -files in a specific directory: you can put a special file in that -directory, or you can define a @dfn{project class} for that directory. + Sometimes, you may wish to define the same set of local variables to +all the files in a certain directory and its subdirectories, such as +the directory tree of a large software project. This can be +accomplished with @dfn{directory-local variables}. @cindex @file{.dir-locals.el} file - If you put a file with a special name @file{.dir-locals.el}@footnote{ -On MS-DOS, the name of this file should be @file{_dir-locals.el}, due -to limitations of the DOS filesystems. If the filesystem is limited -to 8+3 file names, the name of the file will be truncated by the OS to -@file{_dir-loc.el}. -} in a directory, Emacs will read it when it visits any file in that -directory or any of its subdirectories, and apply the settings it -specifies to the file's buffer. Emacs searches for -@file{.dir-locals.el} starting in the directory of the visited file, -and moving up the directory tree. (To avoid slowdown, this search is -skipped for remote files.) + The usual way to define directory-local variables is to put a file +named @file{.dir-locals.el}@footnote{ On MS-DOS, the name of this file +should be @file{_dir-locals.el}, due to limitations of the DOS +filesystems. If the filesystem is limited to 8+3 file names, the name +of the file will be truncated by the OS to @file{_dir-loc.el}. } in a +directory. Whenever Emacs visits any file in that directory or any of +its subdirectories, it will apply the directory-local variables +specified in @file{.dir-locals.el}, as though they had been defined as +file-local variables for that file (@pxref{File Variables}). Emacs +searches for @file{.dir-locals.el} starting in the directory of the +visited file, and moving up the directory tree. To avoid slowdown, +this search is skipped for remote files. The @file{.dir-locals.el} file should hold a specially-constructed -list. This list maps Emacs mode names (symbols) to alists; each alist -specifies values for variables to use when the respective mode is -turned on. The special mode name @samp{nil} means that its alist -applies to any mode. Instead of a mode name, you can specify a string -that is a name of a subdirectory of the project's directory; then the -corresponding alist applies to all the files in that subdirectory. +list, which maps major mode names (symbols) to alists +(@pxref{Association Lists,,, elisp, The Emacs Lisp Reference Manual}). +Each alist entry consists of a variable name and the directory-local +value to assign to that variable, when the specified major mode is +enabled. Instead of a mode name, you can specify @samp{nil}, which +means that the alist applies to any mode; or you can specify a +subdirectory name (a string), in which case the alist applies to all +files in that subdirectory. Here's an example of a @file{.dir-locals.el} file: @example ((nil . ((indent-tabs-mode . t) - (tab-width . 4) (fill-column . 80))) (c-mode . ((c-file-style . "BSD"))) - (java-mode . ((c-file-style . "BSD") - (subdirs . nil))) + (subdirs . nil))) ("src/imported" - . ((nil . ((change-log-default-name . - "ChangeLog.local")))))) + . ((nil . ((change-log-default-name + . "ChangeLog.local")))))) @end example @noindent -This example shows some settings for a hypothetical project. It sets -@samp{indent-tabs-mode}, @code{tab-width}, and @code{fill-column} for -any file in the project's directory tree, and it sets the indentation -style for any C or Java source file. The special @code{subdirs} element -indicates that the Java mode settings are only to be applied in the -current directory, not in any subdirectories. Finally, it specifies a -different @file{ChangeLog} file name for any file in the @file{src/imported} -subdirectory of the directory where you put the @file{.dir-locals.el} -file. +This sets @samp{indent-tabs-mode} and @code{fill-column} for any file +in the directory tree, and the indentation style for any C source +file. The special @code{subdirs} element is not a variable, but a +special keyword which indicates that the C mode settings are only to +be applied in the current directory, not in any subdirectories. +Finally, it specifies a different @file{ChangeLog} file name for any +file in the @file{src/imported} subdirectory. @findex add-dir-local-variable @findex delete-dir-local-variable @findex copy-file-locals-to-dir-locals - You can edit the @file{.dir-locals.el} file by hand, or use the -command @code{add-dir-local-variable}. This prompts for a mode (or -subdirectory), variable and value, and adds an entry to the file. -The command @code{delete-dir-local-variable} deletes an entry. The -command @code{copy-file-locals-to-dir-locals} copies file local -variables (@pxref{File Variables}) to the @file{.dir-locals.el} file. + Instead of editing the @file{.dir-locals.el} file by hand, you can +use the command @kbd{M-x add-dir-local-variable}. This prompts for a +mode or subdirectory name, and for variable and value, and adds the +entry defining the directory-local variable. @kbd{M-x +delete-dir-local-variable} deletes an entry. @kbd{M-x +copy-file-locals-to-dir-locals} copies the file-local variables in the +current file into @file{.dir-locals.el}. @findex dir-locals-set-class-variables @findex dir-locals-set-directory-class - Another method of specifying directory-local variables is to explicitly -define a project class using @code{dir-locals-set-class-variables}, and -then tell Emacs which directories correspond to that class, using -@code{dir-locals-set-directory-class}. You can put calls to these functions -in your @file{~/.emacs} init file; this can be useful when you can't put -@file{.dir-locals.el} in the directory for some reason, or if you want -to keep in a single place settings for several directories that don't -have a common parent. For example, you could apply settings to an -unwritable directory this way: + Another method of specifying directory-local variables is to define +a group of variables/value pairs in a @dfn{directory class}, using the +@code{dir-locals-set-class-variables} function; then, tell Emacs which +directories correspond to the class by using the +@code{dir-locals-set-directory-class} function. These function calls +normally go in your initialization file (@pxref{Init File}). This +method is useful when you can't put @file{.dir-locals.el} in a +directory for some reason. For example, you could apply settings to +an unwritable directory this way: @example (dir-locals-set-class-variables 'unwritable-directory @@ -1227,8 +1348,14 @@ unwritable directory this way: "/usr/include/" 'unwritable-directory) @end example - Unsafe directory-local variables are handled in the same way as -unsafe file-local variables (@pxref{Safe File Variables}). + If a variable has both a directory-local and file-local value +specified, the file-local value takes effect. Unsafe directory-local +variables are handled in the same way as unsafe file-local variables +(@pxref{Safe File Variables}). + + Directory-local variables also take effect in certain buffers that +do not visit a file directly but perform work within a directory, such +as Dired buffers (@pxref{Dired}). @node Key Bindings @section Customizing Key Bindings @@ -1245,7 +1372,7 @@ init file (@pxref{Init Rebinding}). * 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}. +* Init Rebinding:: Rebinding keys with your initialization file. * Modifier Keys:: Using modifier keys in key bindings. * Function Keys:: Rebinding terminal function keys. * Named ASCII Chars:: Distinguishing @key{TAB} from @kbd{C-i}, and so on. @@ -1895,7 +2022,7 @@ 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 +automatically editing your initialization 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 @@ -1916,15 +2043,16 @@ is included in the message displayed when the command is used: @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}. + You can make a command disabled either by editing the initialization +file directly, or with the command @kbd{M-x disable-command}, which +edits the initialization file for you. Likewise, @kbd{M-x +enable-command} edits the initialization file 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. +initialization file. Doing so could lose information because Emacs +has not read your initialization 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 @@ -1932,7 +2060,7 @@ invoke it; disabling also applies if the command is invoked using as a function from Lisp programs. @node Init File -@section The Init File, @file{~/.emacs} +@section The Emacs Initialization File @cindex init file @cindex .emacs file @cindex ~/.emacs file @@ -2164,21 +2292,13 @@ Turn off Line Number mode, a global minor mode. @need 1500 @item -Turn on Auto Fill mode automatically in Text mode and related modes. +Turn on Auto Fill mode automatically in Text mode and related modes +(@pxref{Hooks}). @example (add-hook 'text-mode-hook 'auto-fill-mode) @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 -the @code{auto-fill-mode} function when Text mode is entered. - @item Load the installed Lisp library named @file{foo} (actually a file @file{foo.elc} or @file{foo.el} in a standard Emacs directory). @@ -2198,7 +2318,7 @@ Load the compiled Lisp file @file{foo.elc} from your home directory. (load "~/foo.elc") @end example -Here an absolute file name is used, so no searching is done. +Here a full file name is used, so no searching is done. @item @cindex loading Lisp libraries automatically diff --git a/doc/emacs/dired-xtra.texi b/doc/emacs/dired-xtra.texi index efb05226ba8..bc141650b4a 100644 --- a/doc/emacs/dired-xtra.texi +++ b/doc/emacs/dired-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2011 Free Software Foundation, Inc. +@c Copyright (C) 2004-2012 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 @@ -7,24 +7,24 @@ @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} +You can insert subdirectories with specified @command{ls} switches in +Dired buffers using @kbd{C-u i}. You can change the @command{ls} switches of an already inserted subdirectory using @kbd{C-u l}. Dired preserves the switches if you revert the buffer. 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. Reverting the buffer, however, 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}. +Using @code{dired-undo} (@pxref{Marks vs Flags}) 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. Reverting the +buffer, however, 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 to diff --git a/doc/emacs/dired.texi b/doc/emacs/dired.texi index b6ed47fdb3f..34ec0d2045c 100644 --- a/doc/emacs/dired.texi +++ b/doc/emacs/dired.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Dired @@ -73,32 +73,45 @@ completion commands can be used in the minibuffer; in particular, a directory name. 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 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{=}. +give to @command{ls} for listing the directory; this string +@emph{must} contain @samp{-l}. If you use a prefix argument with the +@code{dired} command, you can specify the @command{ls} switches with the +minibuffer before you enter the directory specification. No matter +how they are specified, the @command{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{=}. @vindex dired-use-ls-dired - Note that Dired automatically adds the option @samp{--dired}, if -your @code{ls} program supports it, unless you explicitly set -the variable @code{dired-use-ls-dired} to @code{nil}. Without this -option, Dired will have trouble parsing some @samp{unusual} file-names. -See the documentation of @code{dired-use-ls-dired} for more details. - - On MS-Windows and MS-DOS systems, Emacs @emph{emulates} @code{ls}; -see @ref{ls in Lisp}, for options and peculiarities of that emulation. + If your @command{ls} program supports the @samp{--dired} option, +Dired automatically passes it that option; this causes @command{ls} to +emit special escape sequences for certain unusual file names, without +which Dired will not be able to parse those names. The first time you +run Dired in an Emacs session, it checks whether @command{ls} supports +the @samp{--dired} option by calling it once with that option. If the +exit code is 0, Dired will subsequently use the @samp{--dired} option; +otherwise it will not. You can inhibit this check by customizing the +variable @code{dired-use-ls-dired}. The value @code{unspecified} (the +default) means to perform the check; any other non-@code{nil} value +means to use the @samp{--dired} option; and @code{nil} means not to +use the @samp{--dired} option. + + On MS-Windows and MS-DOS systems, Emacs emulates @command{ls}. +@xref{ls in Lisp}, for options and peculiarities of this 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. + To display the Dired buffer in another 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}) displays the Dired buffer in a separate +frame. + +@kindex q @r{(Dired)} +@findex quit-window + Typing @kbd{q} (@code{quit-window}) buries the Dired buffer, and +deletes its window if the window was created just for that buffer. @node Dired Navigation @section Navigation in the Dired Buffer @@ -124,7 +137,11 @@ minibuffer, and moves point to the line in the Dired buffer describing that file. @cindex searching Dired buffers +@findex dired-isearch-filenames @vindex dired-isearch-filenames +@findex dired-isearch-filenames-regexp +@kindex M-s f C-s @r{(Dired)} +@kindex M-s f M-C-s @r{(Dired)} @kbd{M-s f C-s} (@code{dired-isearch-filenames}) performs a forward incremental search in the Dired buffer, looking for matches only amongst the file names and ignoring the rest of the text in the @@ -331,18 +348,16 @@ 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 +Visit the file whose name you clicked 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}. +View the file described on the current line, with View mode +(@code{dired-view-file}). View mode provides convenient commands to +navigate the buffer but forbids changing it; @xref{View Mode}. @item ^ @kindex ^ @r{(Dired)} @@ -520,9 +535,9 @@ the regular expression @var{regexp} @kbd{% m}, except that it searches the file contents instead of the file name. -@item C-x u +@item C-/ +@itemx 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 @@ -615,7 +630,7 @@ Like the other commands in this section, this command operates on the 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}). +which to move the files (this is like the shell command @command{mv}). Dired automatically changes the visited file name of buffers associated with renamed files so that they refer to the new names. @@ -625,7 +640,7 @@ with renamed files so that they refer to the new names. @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 +This is like the shell command @command{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. @@ -642,9 +657,10 @@ link. @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}). @var{modespec} can be in octal or symbolic -notation like arguments handled by the @code{chmod} program. +Change the mode (also called @dfn{permission bits}) of the specified +files (@code{dired-do-chmod}). @var{modespec} can be in octal or +symbolic notation, like arguments handled by the @command{chmod} +program. @findex dired-do-chgrp @kindex G @r{(Dired)} @@ -663,8 +679,8 @@ 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). +program to use to do the work (different systems put @command{chown} +in different places). @findex dired-do-touch @kindex T @r{(Dired)} @@ -952,17 +968,17 @@ The backup file is the first file given to @code{diff}. @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. + A Dired buffer usually displays just one directory, 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 +to specify the options @samp{-lR} for running @command{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: +can do this with @kbd{i} (@code{dired-maybe-insert-subdir}): @table @kbd @findex dired-maybe-insert-subdir @@ -973,25 +989,27 @@ can do this with the @kbd{i} command: 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). You can also use @samp{^} to return -to the parent directory in the same Dired buffer. - -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 remove the subdirectory listing (@pxref{Dired Updating}). You -can also hide and show inserted subdirectories (@pxref{Hiding -Subdirectories}). +@noindent +If you use this 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}} returns to your previous position in the Dired +buffer (@pxref{Setting Mark}). You can also use @samp{^} to return to +the parent directory in the same Dired buffer (@pxref{Dired +Visiting}). + + Use the @kbd{l} command (@code{dired-do-redisplay}) to update the +subdirectory's contents, and use @kbd{C-u k} on the subdirectory +header line to remove the subdirectory listing (@pxref{Dired +Updating}). You can also hide and show inserted subdirectories +(@pxref{Hiding Subdirectories}). @ifnottex @include dired-xtra.texi @@ -1209,10 +1227,10 @@ tell @command{find} what condition to test. To use this command, you need to know how to use @command{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. + 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 @command{ls}. If your listings are +corrupted, you may need to change the value of this variable. @findex locate @findex locate-with-filter @@ -1338,10 +1356,14 @@ rotation is lossless, and uses an external utility called JpegTRAN. @kindex + @r{(Dired)} @findex dired-create-directory The command @kbd{+} (@code{dired-create-directory}) reads a -directory name, and creates the directory if it does not already -exist. +directory name, and creates that directory. It signals an error if +the directory already exists. @cindex searching multiple files via Dired +@kindex M-s a C-s @r{(Dired)} +@kindex M-s a M-C-s @r{(Dired)} +@findex dired-do-isearch +@findex dired-do-isearch-regexp The command @kbd{M-s a C-s} (@code{dired-do-isearch}) begins a ``multi-file'' incremental search on the marked files. If a search fails at the end of a file, typing @kbd{C-s} advances to the next diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi index ea9bd95b8ee..b098f26eea5 100644 --- a/doc/emacs/display.texi +++ b/doc/emacs/display.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @@ -1062,6 +1062,56 @@ can enable or disable this feature for all new buffers by setting the default value of this variable, e.g.@: @code{(setq-default indicate-empty-lines t)}. +@cindex Whitespace mode +@cindex mode, Whitespace +@findex whitespace-mode +@vindex whitespace-style + Whitespace mode is a buffer-local minor mode that lets you +``visualize'' many kinds of whitespace in the buffer, by either +drawing the whitespace characters with a special face or displaying +them as special glyphs. To toggle this mode, type @kbd{M-x +whitespace-mode}. The kinds of whitespace visualized are determined +by the list variable @code{whitespace-style}. Here is a partial list +of possible elements (see the variable's documentation for the full +list): + +@table @code +@item face +Enable all visualizations which use special faces. This element has a +special meaing: if it is absent from the list, none of the other +visualizations take effect except @code{space-mark}, @code{tab-mark}, +and @code{newline-mark}. + +@item trailing +Highlight trailing whitespace. + +@item tabs +Highlight tab characters. + +@item spaces +Highlight space and non-breaking space characters. + +@item lines +@vindex whitespace-line-column +Highlight lines longer than 80 lines. To change the column limit, +customize the variable @code{whitespace-line-column}. + +@item newline +Highlight newlines. + +@item empty +Highlight empty lines. + +@item space-mark +Draw space and non-breaking characters with a special glyph. + +@item tab-mark +Draw tab characters with a special glyph. + +@item newline-mark +Draw newline characters with a special glyph. +@end table + @node Selective Display @section Selective Display @cindex selective display diff --git a/doc/emacs/emacs-xtra.texi b/doc/emacs/emacs-xtra.texi index f9d1c27fe55..596cc13abf5 100644 --- a/doc/emacs/emacs-xtra.texi +++ b/doc/emacs/emacs-xtra.texi @@ -11,7 +11,7 @@ @copying This manual describes specialized features of Emacs. -Copyright @copyright{} 2004-2011 +Copyright @copyright{} 2004-2012 Free Software Foundation, Inc. @quotation diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index 2cb02feee60..b8722e9f850 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -11,7 +11,7 @@ This is the @value{EDITION} edition of the @cite{GNU Emacs Manual},@* updated for Emacs version @value{EMACSVER}. -Copyright @copyright{} 1985-1987, 1993-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1985-1987, 1993-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -548,6 +548,7 @@ Commands for Human Languages * Case:: Changing the case of text. * Text Mode:: The major modes for editing text files. * Outline Mode:: Editing outlines. +* Org Mode:: The Emacs organizer. * TeX Mode:: Editing input to the formatter TeX. * HTML Mode:: Editing HTML and SGML files. * Nroff Mode:: Editing input to the formatter nroff. @@ -741,15 +742,16 @@ Version Control * VC Mode Line:: How the mode line shows version control status. * Basic VC Editing:: How to edit a file under version control. * Log Buffer:: Features available in log entry buffers. +* Registering:: Putting a file under version control. * Old Revisions:: Examining and comparing old versions. -* Secondary VC Commands:: The commands used a little less frequently. +* VC Change Log:: Viewing the VC Change Log. +* VC Undo:: Canceling changes before or after committing. * VC Directory Mode:: Listing files managed by version control. * Branches:: Multiple lines of development. -* Remote Repositories:: Efficient access to remote CVS servers. * Revision Tags:: Symbolic names for revisions. * Miscellaneous VC:: Various other commands and features of VC. * Customizing VC:: Variables that change VC's behavior. - + Introduction to Version Control * Why Version Control?:: Understanding the problems it addresses. @@ -766,12 +768,6 @@ Basic Editing under Version Control * VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS. * Advanced C-x v v:: Advanced features available with a prefix argument. -The Secondary Commands of VC - -* Registering:: Putting a file under version control. -* VC Change Log:: Viewing the VC Change Log. -* VC Undo:: Canceling changes before or after check-in. - VC Directory Mode * VC Directory Buffer:: What the buffer looks like and means. @@ -780,26 +776,15 @@ VC Directory Mode Multiple Branches of a File * Switching Branches:: How to get to another existing branch. -* Creating Branches:: How to start a new branch. +* VC Pull:: Updating a branch from another branch. * Merging:: Transferring changes between branches. -* Multi-User Branching:: Multiple users working at multiple branches - in parallel. - -Remote Repositories - -* Version Backups:: Keeping local copies of repository versions. -* Local Version Control:: Using another version system for local editing. - -Revision Tags - -* Making Revision Tags:: The tag facilities. -* Revision Tag Caveats:: Things to be careful of when using tags. +* Creating Branches:: How to start a new branch. Miscellaneous Commands and Features of VC * 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. +* VC Delete/Rename:: Deleting and renaming version-controlled files. +* Revision Tags:: Symbolic names for revisions. * Version Headers:: Inserting version control headers into working files. Customizing VC @@ -934,10 +919,10 @@ Customizing the Calendar and Diary Document Viewing -* Navigation:: Navigation inside DocView buffers. -* Searching:: Searching inside documents. -* Slicing:: Specifying which part of pages should be displayed. -* Conversion:: Influencing and triggering conversion. +* DocView Navigation:: Navigating DocView buffers. +* DocView Searching:: Searching inside documents. +* DocView Slicing:: Specifying which part of a page is displayed. +* DocView Conversion:: Influencing and triggering conversion. Sending Mail @@ -989,7 +974,8 @@ 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. +* Gnus Group Buffer:: A short description of Gnus group commands. +* Gnus Summary Buffer:: A short description of Gnus summary commands. Running Shell Commands from Emacs @@ -1002,7 +988,6 @@ Running Shell Commands from Emacs * 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. * Serial Terminal:: Connecting to a serial port. @@ -1048,15 +1033,14 @@ Customization Easy Customization Interface -* Customization Groups:: How settings are classified in a structure. +* Customization Groups:: How settings are classified. * 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. +* Saving Customizations:: Saving customizations for future Emacs sessions. * 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. +* Specific Customization:: Customizing specific settings or groups. +* Custom Themes:: Collections of customization settings. +* Creating Custom Themes:: How to create a new custom theme. Variables @@ -1104,9 +1088,7 @@ Dealing with Emacs Trouble * 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. +* Emergency Escape:: What to do if Emacs stops responding. Reporting Bugs @@ -1386,7 +1368,7 @@ Shapiro, Richard Sharman, Olin Shivers, Espen Skoglund, Rick Sladkey, Lynn Slater, Chris Smith, David Smith, Paul D.@: Smith, William Sommerfeld, Andre Spiegel, Michael Staats, Ulf Stegemann, Reiner Steib, Sam Steingold, Ake Stenhoff, Peter Stephenson, Ken Stevens, Andy Stewart, -Jonathan Stigelman, Martin Stjernholm, Kim F.@: Storm, Steve Strassman, +Jonathan Stigelman, Martin Stjernholm, Kim F.@: Storm, Steve Strassmann, Olaf Sylvester, Naoto Takahashi, Steven Tamm, Jean-Philippe Theberge, Jens T.@: Berger Thielemann, Spencer Thomas, Jim Thompson, Luc Teirlinck, David O'Toole, Tom Tromey, Enami Tsugutomo, Eli Tziperman, diff --git a/doc/emacs/emerge-xtra.texi b/doc/emacs/emerge-xtra.texi index b46868cf52b..d9f0b4a2741 100644 --- a/doc/emacs/emerge-xtra.texi +++ b/doc/emacs/emerge-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2011 Free Software Foundation, Inc. +@c Copyright (C) 2004-2012 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 diff --git a/doc/emacs/entering.texi b/doc/emacs/entering.texi index 4a76f206aed..ba7f3132b6b 100644 --- a/doc/emacs/entering.texi +++ b/doc/emacs/entering.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 2001-2011 +@c Copyright (C) 1985-1987, 1993-1995, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @iftex diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index e3da0ca44e6..a522e055d2b 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Files, Buffers, Keyboard Macros, Top @@ -1352,9 +1352,25 @@ manipulate and apply parts of patches: @findex diff-hunk-next Move to the next hunk-start (@code{diff-hunk-next}). +@findex diff-auto-refine-mode +@cindex mode, Diff Auto-Refine +@cindex Diff Auto-Refine mode +This command has a side effect: it @dfn{refines} the hunk you move to, +highlighting its changes with better granularity. To disable this +feature, type @kbd{M-x diff-auto-refine-mode} to toggle off the minor +mode Diff Auto-Refine mode. To disable Diff Auto Refine mode by +default, add this to your init file (@pxref{Hooks}): + +@example +(add-hook 'diff-mode-hook + (lambda () (diff-auto-refine-mode -1))) +@end example + @item M-p @findex diff-hunk-prev -Move to the previous hunk-start (@code{diff-hunk-prev}). +Move to the previous hunk-start (@code{diff-hunk-prev}). Like +@kbd{M-n}, this has the side-effect of refining the hunk you move to, +unless you disable Diff Auto-Refine mode. @item M-@} @findex diff-file-next @@ -1447,13 +1463,13 @@ descriptions of the changes. @kbd{C-x 4 a} itself in Diff mode operates on behalf of the current hunk's file, but gets the function name from the patch itself. This is useful for making log entries for functions that are deleted by the patch. - -@item M-x diff-show-trailing-whitespaces RET -@findex diff-show-trailing-whitespaces -Highlight trailing whitespace characters, except for those used by the -patch syntax (@pxref{Useless Whitespace}). @end table + By default, Diff mode highlights trailing whitespace on modified +lines, so that they are more obvious. This is done by enabling +Whitespace mode in the Diff buffer (@pxref{Useless Whitespace}). Diff +mode buffers are set up so that Whitespace mode avoids highlighting +trailing whitespace occurring in the diff context. @node Misc File Ops @section Miscellaneous File Operations @@ -1485,6 +1501,12 @@ argument to @kbd{M-x delete-file} or @kbd{M-x delete-directory} makes them delete outright, instead of using the Trash, regardless of @code{delete-by-moving-to-trash}. +@ifnottex + If a file is under version control (@pxref{Version Control}), you +should delete it using @kbd{M-x vc-delete-file} instead of @kbd{M-x +delete-file}. @xref{VC Delete/Rename}. +@end ifnottex + @findex copy-file @cindex copying files @kbd{M-x copy-file} reads the file @var{old} and writes a new file @@ -1498,6 +1520,7 @@ it creates a copy of the @var{old} directory and puts it in @var{new}. If @var{new} is not an existing directory, it copies all the contents of @var{old} into a new directory named @var{new}. +@cindex renaming files @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 @@ -1512,6 +1535,12 @@ 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. +@ifnottex + If a file is under version control (@pxref{Version Control}), you +should rename it using @kbd{M-x vc-rename-file} instead of @kbd{M-x +rename-file}. @xref{VC Delete/Rename}. +@end ifnottex + @findex add-name-to-file @cindex hard links (creation) @kbd{M-x add-name-to-file} adds an additional name to an existing diff --git a/doc/emacs/fixit.texi b/doc/emacs/fixit.texi index bae78d94744..c4fbca6574b 100644 --- a/doc/emacs/fixit.texi +++ b/doc/emacs/fixit.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Fixit, Keyboard Macros, Search, Top diff --git a/doc/emacs/fortran-xtra.texi b/doc/emacs/fortran-xtra.texi index e5853a17dd0..5fc20fae8a3 100644 --- a/doc/emacs/fortran-xtra.texi +++ b/doc/emacs/fortran-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2011 Free Software Foundation, Inc. +@c Copyright (C) 2004-2012 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 @@ -22,7 +22,7 @@ extensions @samp{.f90}, @samp{.f95}, @samp{.f03} and @samp{.f08}. Customize @code{auto-mode-alist} to add more extensions. GNU Fortran supports both free and fixed form. This manual mainly documents Fortran mode, but the corresponding F90 mode features are mentioned when -revelant. +relevant. Fortran mode provides special motion commands for Fortran statements and subprograms, and indentation commands that understand Fortran diff --git a/doc/emacs/frames.texi b/doc/emacs/frames.texi index dec5aa771ea..1adeee480a6 100644 --- a/doc/emacs/frames.texi +++ b/doc/emacs/frames.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Frames, International, Windows, Top diff --git a/doc/emacs/glossary.texi b/doc/emacs/glossary.texi index 3af75245e69..c6f91cb7b56 100644 --- a/doc/emacs/glossary.texi +++ b/doc/emacs/glossary.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Glossary, Key Index, Intro, Top diff --git a/doc/emacs/gnu.texi b/doc/emacs/gnu.texi index dfdeedd65ec..ac9b9de6dcb 100644 --- a/doc/emacs/gnu.texi +++ b/doc/emacs/gnu.texi @@ -1,4 +1,4 @@ -@c Copyright (C) 1985-1987, 1993, 1995, 2001-2011 +@c Copyright (C) 1985-1987, 1993, 1995, 2001-2012 @c Free Software Foundation, Inc. @c @c Permission is granted to anyone to make or distribute verbatim copies diff --git a/doc/emacs/help.texi b/doc/emacs/help.texi index c024d428511..ed08aca5080 100644 --- a/doc/emacs/help.texi +++ b/doc/emacs/help.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Help, Mark, M-x, Top diff --git a/doc/emacs/indent.texi b/doc/emacs/indent.texi index f99e3519710..3892dc2ae99 100644 --- a/doc/emacs/indent.texi +++ b/doc/emacs/indent.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Indentation, Text, Modes, Top diff --git a/doc/emacs/killing.texi b/doc/emacs/killing.texi index 1443ad019bb..e76e2fafc55 100644 --- a/doc/emacs/killing.texi +++ b/doc/emacs/killing.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. diff --git a/doc/emacs/kmacro.texi b/doc/emacs/kmacro.texi index 4676983fc67..a767a312ed3 100644 --- a/doc/emacs/kmacro.texi +++ b/doc/emacs/kmacro.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Keyboard Macros, Files, Fixit, Top diff --git a/doc/emacs/m-x.texi b/doc/emacs/m-x.texi index cf55631e14e..81ceb1e3ac9 100644 --- a/doc/emacs/m-x.texi +++ b/doc/emacs/m-x.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node M-x, Help, Minibuffer, Top diff --git a/doc/emacs/macos.texi b/doc/emacs/macos.texi index 3e1e67fecd8..a36dc0cbcc5 100644 --- a/doc/emacs/macos.texi +++ b/doc/emacs/macos.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2000-2011 Free Software Foundation, Inc. +@c Copyright (C) 2000-2012 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Mac OS / GNUstep, Microsoft Windows, Antinews, Top @appendix Emacs and Mac OS / GNUstep diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi index 354812edc1f..2ec477031ca 100644 --- a/doc/emacs/maintaining.texi +++ b/doc/emacs/maintaining.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Maintaining, Abbrevs, Building, Top @@ -49,13 +49,13 @@ variable @code{vc-handled-backends} to @code{nil} * VC Mode Line:: How the mode line shows version control status. * Basic VC Editing:: How to edit a file under version control. * Log Buffer:: Features available in log entry buffers. +* Registering:: Putting a file under version control. * Old Revisions:: Examining and comparing old versions. -* Secondary VC Commands:: The commands used a little less frequently. +* VC Change Log:: Viewing the VC Change Log. +* VC Undo:: Canceling changes before or after committing. * VC Directory Mode:: Listing files managed by version control. * Branches:: Multiple lines of development. @ifnottex -* Remote Repositories:: Efficient access to remote CVS servers. -* Revision Tags:: Symbolic names for revisions. * Miscellaneous VC:: Various other commands and features of VC. * Customizing VC:: Variables that change VC's behavior. @end ifnottex @@ -71,7 +71,7 @@ control operations. Some uncommon or intricate version control operations, such as altering repository settings, are not supported in VC. You should -perform such tasks outside Emacs, e.g. via the command line. +perform such tasks outside Emacs, e.g.@: via the command line. This section provides a general overview of version control, and describes the version control systems that VC supports. You can skip @@ -125,7 +125,7 @@ which it refers to as @dfn{back ends}: @item SCCS was the first version control system ever built, and was long ago superseded by more advanced ones. VC compensates for certain features -missing in SCCS (e.g., tag names for releases) by implementing them +missing in SCCS (e.g.@: tag names for releases) by implementing them itself. Other VC features, such as multiple branches, are simply unavailable. Since SCCS is non-free, we recommend avoiding it. @@ -154,7 +154,7 @@ moving/renaming. VC supports all basic editing operations under CVS. @cindex SVN @cindex Subversion @item -Subversion (SVN) is a free version control system designed to be +Subversion (svn) is a free version control system designed to be similar to CVS but without its problems (e.g., it supports atomic commits of filesets, and versioning of directories, symbolic links, meta-data, renames, copies, and deletes). @@ -162,37 +162,33 @@ meta-data, renames, copies, and deletes). @cindex GNU Arch @cindex Arch @item -GNU Arch is one of the earliest @dfn{distributed} version control +GNU Arch is one of the earliest @dfn{decentralized} version control systems (the other being Monotone). @xref{VCS Concepts}, for a -description of distributed version control systems. It is no longer +description of decentralized version control systems. It is no longer under active development, and has been deprecated in favor of Bazaar. @cindex git @item -Git is a distributed version control system originally invented by +Git is a decentralized version control system originally invented by Linus Torvalds to support development of Linux (his kernel). VC -supports many common git operations, but others, such as repository +supports many common Git operations, but others, such as repository syncing, must be done from the command line. @cindex hg @cindex Mercurial @item -Mercurial (hg) is a distributed version control system broadly -resembling git. VC supports most Mercurial commands, with the +Mercurial (hg) is a decentralized version control system broadly +resembling Git. VC supports most Mercurial commands, with the exception of repository sync operations. @cindex bzr @cindex Bazaar @item -Bazaar (bzr) is a distributed version control system that supports -both repository-based and distributed versioning. VC supports most +Bazaar (bzr) is a decentralized version control system that supports +both repository-based and decentralized versioning. VC supports most basic editing operations under Bazaar. @end itemize - Previous versions of VC supported a version control system known as -Meta-CVS. This support was dropped due to limited interest from users -and developers. - @node VCS Concepts @subsubsection Concepts of Version Control @@ -210,16 +206,19 @@ as @dfn{log entries} that describe the changes made to each file. The copy of a version-controlled file that you actually edit is called the @dfn{work file}. You can change each work file as you would an ordinary file. After you are done with a set of changes, you -@dfn{commit} (or @dfn{check in}) the changes; this records the changes -in the repository, along with a descriptive log entry. +may @dfn{commit} (or @dfn{check in}) the changes; this records the +changes in the repository, along with a descriptive log entry. + +@cindex working tree + A directory tree of work files is called a @dfn{working tree}. @cindex revision @cindex revision ID - A copy of a file stored in a repository is called a @dfn{revision}. -The history of a file is a sequence of revisions. Each revision is -named by a @dfn{revision ID}. The format of the revision ID depends -on the version control system; in the simplest case, it is just an -integer. + Each commit creates a new @dfn{revision} in the repository. The +version control system keeps track of all past revisions and the +changes that were made in each revision. Each revision is named by a +@dfn{revision ID}, whose format depends on the version control system; +in the simplest case, it is just an integer. To go beyond these basic concepts, you will need to understand three aspects in which version control systems differ. As explained in the @@ -229,17 +228,18 @@ these modes of operation, but it cannot hide the differences. @node VCS Merging @subsubsection Merge-based vs lock-based Version Control -@cindex locking versus merging A version control system typically has some mechanism to coordinate between users who want to change the same file. There are two ways to do this: merging and locking. - In a version control system that uses merging, each user may check -out and modify a work file at any time. The system lets you -@dfn{merge} your work file, which may contain changes that have not -been committed, with the latest changes that others have committed. +@cindex merging-based version + In a version control system that uses merging, each user may modify +a work file at any time. The system lets you @dfn{merge} your work +file, which may contain changes that have not been committed, with the +latest changes that others have committed. +@cindex locking-based version Older version control systems use a @dfn{locking} scheme instead. Here, work files are normally read-only. To edit a file, you ask the version control system to make it writable for you by @dfn{locking} @@ -264,7 +264,7 @@ number and severity of conflicts that actually occur. SCCS always uses locking. RCS is lock-based by default but can be told to operate in a merging style. CVS and Subversion are merge-based by default but can be told to operate in a locking mode. -Distributed version control systems, such as GNU Arch, git, and +Decentralized version control systems, such as GNU Arch, Git, and Mercurial, are exclusively merging-based. VC mode supports both locking and merging version control. The @@ -276,15 +276,16 @@ possible. @node VCS Changesets @subsubsection Changeset-based vs File-based Version Control -@cindex changesets +@cindex file-based version control On SCCS, RCS, CVS, and other early version control systems, version control operations are @dfn{file-based}: each file has its own comment and revision history separate from that of all other files. Newer systems, beginning with Subversion, are @dfn{changeset-based}: a -checkin may include changes to several files, and the entire set of +commit may include changes to several files, and the entire set of changes is handled as a unit. Any comment associated with the change does not belong to a single file, but to the changeset itself. +@cindex changeset-based version control Changeset-based version control is more flexible and powerful than file-based version control; usually, when a change to multiple files has to be reversed, it's good to be able to easily identify and remove @@ -295,18 +296,20 @@ all of it. @cindex centralized version control @cindex decentralized version control +@cindex distributed version control 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. One of its drawbacks is that the repository is a choke point for reliability and efficiency. - GNU Arch pioneered the concept of @dfn{decentralized} version -control, later implemented in git, Mercurial, and Bazaar. 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. In effect, there is one repository for each -developer, and repository merges take the place of commit operations. + GNU Arch pioneered the concept of @dfn{distributed} or +@dfn{decentralized} version control, later implemented in Git, +Mercurial, and Bazaar. 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. In +effect, there is one repository for each developer, and repository +merges take the place of commit operations. VC helps you manage the traffic between your personal workfiles and a repository. Whether the repository is a single master, or one of a @@ -346,10 +349,9 @@ 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 with -@kbd{C-c C-a} when checking in the change (@pxref{Log Buffer}). 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} +@kbd{C-c C-a} when committing the change (@pxref{Log Buffer}). Or you +can write the entry in the log buffer while committing 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 @@ -359,20 +361,22 @@ change, and later use the @kbd{C-x v a} command to copy it to @node VC Mode Line @subsection Version Control and the Mode Line -@cindex VC, mode line indicator +@cindex VC mode line indicator When you visit a file that is under version control, Emacs indicates this on the mode line. For example, @samp{Bzr-1223} says that Bazaar is used for that file, and the current revision ID is 1223. +@cindex version control status The character between the back-end name and the revision ID -indicates the status of the work file. In a merge-based version -control system, a @samp{-} character indicates that the work file is -unmodified, and @samp{:} indicates that it has been modified. -@samp{!} indicates that the file contains conflicts as result of a -recent merge operation (@pxref{Merging}), or that the file was removed -from the version control. Finally, @samp{?} means that the file is -under version control, but is missing from the working tree. +indicates the @dfn{version control status} of the work file. In a +merge-based version control system, a @samp{-} character indicates +that the work file is unmodified, and @samp{:} indicates that it has +been modified. @samp{!} indicates that the file contains conflicts as +result of a recent merge operation (@pxref{Merging}), or that the file +was removed from the version control. Finally, @samp{?} means that +the file is under version control, but is missing from the working +tree. In a lock-based system, @samp{-} indicates an unlocked file, and @samp{:} a locked file; if the file is locked by another user (for @@ -402,6 +406,7 @@ system, but is usually not excessive. @subsection Basic Editing under Version Control @cindex filesets, VC +@cindex VC filesets Most VC commands operate on @dfn{VC filesets}. A VC fileset is a collection of one or more files that a VC operation acts on. When you type VC commands in a buffer visiting a version-controlled file, the @@ -409,37 +414,34 @@ VC fileset is simply that one file. When you type them in a VC Directory buffer, and some files in it are marked, the VC fileset consists of the marked files (@pxref{VC Directory Mode}). - The principal VC command is an all-purpose command, @kbd{C-x v v} -(@code{vc-next-action}), that performs either registration, locking, -merging or a check-in (depending on the situation) on the current VC -fileset. You can use @kbd{C-x v v} in a file-visiting buffer or in a -VC Directory buffer. + On modern changeset-based version control systems (@pxref{VCS +Changesets}), VC commands handle multi-file VC filesets as a group. +For example, committing a multi-file VC fileset generates a single +revision, containing the changes to all those files. On older +file-based version control systems like CVS, each file in a multi-file +VC fileset is handled individually; for example, a commit generates +one revision for each changed file. @table @kbd @itemx C-x v v -Perform the appropriate next version control operation on the VC fileset. +Perform the next appropriate version control operation on the current +VC fileset. @end table @findex vc-next-action @kindex C-x v v - The precise action of @kbd{C-x v v} depends on the state of the VC -fileset, and whether the version control system uses locking or -merging. This is described in detail in the subsequent sections. - - VC filesets are the way that VC mode bridges the gap between -file-based and changeset-based version control systems. They are, -essentially, a way to pass multiple file arguments as a group to -version control commands. For example, on Subversion, a checkin with -a multi-file VC fileset becomes a joint commit, as though you had -typed @command{svn commit} with those file arguments at the shell -command line. All files in a VC fileset must be under the same -version control system; if they are not, Emacs signals an error when -you attempt to execute a command on the fileset. - - VC filesets are distinct from the ``named filesets'' used for -viewing and visiting files in functional groups (@pxref{Filesets}). -Unlike named filesets, VC filesets are not named and don't persist -across sessions. + The principal VC command is a multi-purpose command, @kbd{C-x v v} +(@code{vc-next-action}), which performs the ``most appropriate'' +action on the current VC fileset: either registering it with a version +control system, or committing it, or unlocking it, or merging changes +into it. The precise actions are described in detail in the following +subsections. You can use @kbd{C-x v v} either in a file-visiting +buffer or in a VC Directory buffer. + + Note that VC filesets are distinct from the ``named filesets'' used +for viewing and visiting files in functional groups +(@pxref{Filesets}). Unlike named filesets, VC filesets are not named +and don't persist across sessions. @menu * VC With A Merging VCS:: Without locking: default mode for CVS. @@ -450,46 +452,44 @@ across sessions. @node VC With A Merging VCS @subsubsection Basic Version Control with Merging - When your version control system is merging-based (the default for -CVS and all newer version control systems), work files are always -writable; you need not do anything special to begin editing 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 -(@pxref{VC Mode Line}). - - Here is what @kbd{C-x v v} does when using a merging-based system: + On a merging-based version control system (i.e.@: most modern ones; +@pxref{VCS Merging}), @kbd{C-x v v} does the following: @itemize @bullet @item -If the work file is in a directory that is not controlled by any -version control system, prompt for a repository type. Then, create a -version control repository of that type and register the file with it. +If there is more than one file in the VC fileset and the files have +inconsistent version control statuses, signal an error. (Note, +however, that a fileset is allowed to include both ``newly-added'' +files and ``modified'' files; @pxref{Registering}.) @item -If the work file is in a directory that is controlled by a version -control system but not registered with it, register the file. +If none of the files in the VC fileset are registered with a version +control system, register the VC fileset, i.e.@: place it under version +control. @xref{Registering}. If Emacs cannot find a system to +register under, it prompts for a repository type, creates a new +repository, and registers the VC fileset with it. @item -If the work file is the same as in the repository, do nothing. +If every work file in the VC fileset is unchanged, do nothing. @item -If you have not changed the work file, but some other user has checked -in changes to the repository, merge those changes into the work file. +If every work file in the VC fileset has been modified, commit the +changes. To do this, Emacs pops up a @samp{*vc-log*} buffer; type the +desired log entry for the new revision, followed by @kbd{C-c C-c} to +commit. @xref{Log Buffer}. + +If committing to a shared repository, the commit may fail if the +repository that has been changed since your last update. In that +case, you must perform an update before trying again. On a +decentralized version control system, use @kbd{C-x v +} (@pxref{VC +Pull}) or @kbd{C-x v m} (@pxref{Merging}). On a centralized version +control system, type @kbd{C-x v v} again to merge in the repository +changes. @item -If you have made modifications to the work file, attempt to commit -the changes. To do this, Emacs first reads the log entry for the new -revision (@pxref{Log Buffer}). If some other user has committed -changes to the repository since you last checked it out, the checkin -fails. In that case, type @kbd{C-x v v} again to merge those changes -into your own work file; this puts the work file into a ``conflicted'' -state. Type @kbd{C-x v v} to clear the ``conflicted'' state; VC then -regards the file as up-to-date and modified, and you can try to check -it in again. - -To pick up any recent changes from the repository @emph{without} -trying to commit your own changes, type @kbd{C-x v m @key{RET}}. -@xref{Merging}. +Finally, if you are using a centralized version control system, check +if each work file in the VC fileset is up-to-date. If any file has +been changed in the repository, offer to update it. @end itemize These rules also apply when you use RCS in its ``non-locking'' mode, @@ -498,7 +498,7 @@ Nothing informs you if another user has committed changes in the same file since you began editing it; when you commit your revision, his changes are removed (however, they remain in the repository and are thus not irrevocably lost). Therefore, you must verify that the -current revision is unchanged before checking in your changes. In +current revision is unchanged before committing your changes. In addition, locking is possible with RCS even in this mode: @kbd{C-x v v} with an unmodified file locks the file, just as it does with RCS in its normal locking mode (@pxref{VC With A Locking VCS}). @@ -506,32 +506,44 @@ its normal locking mode (@pxref{VC With A Locking VCS}). @node VC With A Locking VCS @subsubsection Basic Version Control with Locking - Under a locking-based version control system (such as SCCS, and RCS -in its default mode), @kbd{C-x v v} does the following: + On a locking-based version control system (such as SCCS, and RCS in +its default mode), @kbd{C-x v v} does the following: @itemize @bullet @item -If the file is not locked, lock it and make it writable, so that you -can change it. +If there is more than one file in the VC fileset and the files have +inconsistent version control statuses, signal an error. + +@item +If each file in the VC fileset is not registered with a version +control system, register the VC fileset. @xref{Registering}. If +Emacs cannot find a system to register under, it prompts for a +repository type, creates a new repository, and registers the VC +fileset with it. + +@item +If each file is registered and unlocked, lock it and make it writable, +so that you can begin to edit it. @item -If the file is locked by you, and contains changes, commit the -changes. In order to do this, Emacs first reads the log entry for the -new revision. @xref{Log Buffer}. +If each file is locked by you and contains changes, commit the +changes. To do this, Emacs pops up a @samp{*vc-log*} buffer; type the +desired log entry for the new revision, followed by @kbd{C-c C-c} to +commit (@pxref{Log Buffer}). @item -If the file is locked by you, but you have not changed it since you -locked it, release the lock and makes the file read-only again. +If each file is locked by you, but you have not changed it, release +the lock and make the file read-only again. @item -If the file is locked by some other user, ask 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. +If each file is locked by another user, ask whether you want to +``steal the lock''. If you say yes, the file becomes locked by you, +and a warning message is sent to the user who had formerly locked the +file. @end itemize These rules also apply when you use CVS in locking mode, except -that CVS does not support stealing a lock. +that CVS does not support stealing locks. @node Advanced C-x v v @subsubsection Advanced Control in @kbd{C-x v v} @@ -544,49 +556,55 @@ to do the operation. @itemize @bullet @item -If the file is modified (or locked), you can specify the revision ID -to use for the new version that you commit. This is one way to create -a new branch (@pxref{Branches}). +@cindex specific version control system +You can specify the name of a version control system. This is useful +if the fileset can be managed by more than one version control system, +and Emacs fails to detect the correct one. @item -If the file is not modified (and unlocked), you can specify the -revision to select; this lets you start working from an older -revision, or on another branch. If you do not enter any revision, -that takes you to the highest (``head'') revision 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. +Otherwise, if using CVS or RCS, you can specify a revision ID. -@item -@cindex specific version control system -Instead of the revision ID, 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 +If the fileset is modified (or locked), this makes Emacs commit with +that revision ID. You can create a new branch by supplying an +appropriate revision ID (@pxref{Branches}). + +If the fileset is unmodified (and unlocked), this checks the specified +revision into the working tree. You can also specify a revision on +another branch by giving its revision or branch ID (@pxref{Switching +Branches}). An empty argument (i.e.@: @kbd{C-u C-x v v @key{RET}}) +checks out the latest (``head'') revision on the current branch. +This signals an error on a decentralized version control system. +Those systems do not let you specify your own revision IDs, nor do +they use the concept of ``checking out'' individual files. @end itemize @node Log Buffer @subsection Features of the Log Entry Buffer - When you tell VC to commit a change, it pops up a buffer called -@samp{*VC-Log*}. In this buffer, you should write a @dfn{log entry} +@cindex C-c C-c @r{(Log Edit mode)} +@findex log-edit-done + When you tell VC to commit a change, it pops up a buffer named +@samp{*vc-log*}. In this buffer, you should write a @dfn{log entry} describing the changes you have made (@pxref{Why Version Control?}). -After you are done, type @kbd{C-c C-c}; this exits the buffer and -commits the change, together with your log entry. +After you are done, type @kbd{C-c C-c} (@code{log-edit-done}) to exit +the buffer and commit the change, together with your log entry. - While in the @samp{*VC-Log*} buffer, you can write one or more -@dfn{header lines}, specifying additional information to be supplied -to the version control system. Each header line must occupy a single -line at the top of the buffer; the first line that is not a header -line is treated as the start of the log entry. For example, the -following header line states that the present change was not written -by you, but by another developer: +@cindex Log Edit mode +@cindex mode, Log Edit +@vindex vc-log-mode-hook + The major mode for the @samp{*vc-log*} buffer is Log Edit mode, a +variant of Text mode (@pxref{Text Mode}). On entering Log Edit mode, +Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook} +(@pxref{Hooks}). + + In the @samp{*vc-log*} buffer, you can write one or more @dfn{header +lines}, specifying additional information to be supplied to the +version control system. Each header line must occupy a single line at +the top of the buffer; the first line that is not a header line is +treated as the start of the log entry. For example, the following +header line states that the present change was not written by you, but +by another developer: @smallexample Author: J. R. Hacker <jrh@@example.com> @@ -597,196 +615,215 @@ Apart from the @samp{Author} header, Emacs recognizes the headers @samp{Date} (a manually-specified commit time) and @samp{Fixes} (a reference to a bug fixed by the change). Not all version control systems recognize all headers: Bazaar recognizes all three headers, -while git, Mercurial, and Monotone recognizes only @samp{Author} and -@samp{Summary}. If you specify a header for a version control that -does not support it, the header is treated as part of the log entry. +while Git, Mercurial, and Monotone recognize only @samp{Author} and +@samp{Date}. If you specify a header for a system that does not +support it, the header is treated as part of the log entry. +@kindex C-c C-f @r{(Log Edit mode)} @findex log-edit-show-files +@kindex C-c C-d @r{(Log Edit mode)} @findex log-edit-show-diff - Type @kbd{C-c C-f} (@code{log-edit-show-files}) to display a list of -files in the current VC fileset. If you called @kbd{C-x v v} directly -from a work file, the fileset consists of that single file; if you -called @kbd{C-x v v} from a VC directory buffer (@pxref{VC Directory -Mode}), the fileset may consist of multiple files. - + While in the @samp{*vc-log*} buffer, the ``current VC fileset'' is +considered to be the fileset that will be committed if you type +@w{@kbd{C-c C-c}}. To view a list of the files in the VC fileset, +type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}). To view a diff +of changes between the VC fileset and the version from which you +started editing (@pxref{Old Revisions}), type @kbd{C-c C-d} +(@code{log-edit-show-diff}). + +@kindex C-c C-a @r{(Log Edit mode)} @findex log-edit-insert-changelog - Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a @dfn{diff} -of the changes you have made (i.e., the differences between the work -file and the repository revision from which you started editing). -@xref{Old Revisions}. - - If the current VC fileset includes one or more @file{ChangeLog} -files (@pxref{Change Log}), type @kbd{C-c C-a} + If the VC fileset includes one or more @file{ChangeLog} files +(@pxref{Change Log}), type @kbd{C-c C-a} (@code{log-edit-insert-changelog}) to pull the relevant entries into -the @samp{*VC-Log*} buffer. If the topmost item in each +the @samp{*vc-log*} buffer. If the topmost item in each @file{ChangeLog} was made under your user name on the current date, -this command searches that item for entries that match the file(s) to -be committed; if found, these entries are inserted. -@iftex -@xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}, -@end iftex +this command searches that item for entries matching the file(s) to be +committed, and inserts them. @ifnottex -@xref{Change Logs and VC}, +If you are using CVS or RCS, see @ref{Change Logs and VC}, for the +opposite way of working---generating ChangeLog entries from the Log +Edit buffer. @end ifnottex -for the opposite way of working---generating ChangeLog entries from -the revision control log. - To abort a check-in, just @strong{don't} type @kbd{C-c C-c} in that + To abort a commit, 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 commit 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. (This -is the normal way to do things on a changeset-oriented system, where -comments are attached to changesets rather than the history of -individual files.) The most convenient way to do this is to mark all -the files in VC Directory Mode and commit from there; the log buffer -will carry the fileset information with it and do a group commit when -you type @kbd{C-c C-c}. - +don't try to make another commit, 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 commit. + +@kindex M-n @r{(Log Edit mode)} +@kindex M-p @r{(Log Edit mode)} +@kindex M-s @r{(Log Edit mode)} +@kindex M-r @r{(Log Edit mode)} You can also browse the history of previous log entries to duplicate -a checkin comment. This can be useful when you want several files to -have checkin comments that vary only slightly from each other. 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). +a commit comment. This can be useful when you want to make several +commits with similar comments. 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 (@pxref{Minibuffer History}), except that they are +used outside the minibuffer. -@vindex vc-log-mode-hook - Each time you commit a change, the log entry buffer is put into VC -Log Edit mode, which involves running two hooks: @code{text-mode-hook} -and @code{vc-log-mode-hook}. @xref{Hooks}. +@node Registering +@subsection Registering a File for Version Control + +@table @kbd +@item C-x v i +Register the visited file for version control. +@end table + +@kindex C-x v i +@findex vc-register + The command @kbd{C-x v i} (@code{vc-register}) @dfn{registers} each +file in the current VC fileset, placing it under version control. +This is essentially equivalent to the action of @kbd{C-x v v} on an +unregistered VC fileset (@pxref{Basic VC Editing}), except that if the +VC fileset is already registered, @kbd{C-x v i} signals an error +whereas @kbd{C-x v v} performs some other action. + + To register a file, Emacs must choose a version control system. For +a multi-file VC fileset, the VC Directory buffer specifies the system +to use (@pxref{VC Directory Mode}). For a single-file VC fileset, if +the file's directory already contains files registered in a version +control system, or if the directory is part of a directory tree +controlled by a version control system, Emacs chooses that system. In +the event that more than one version control system is applicable, +Emacs uses the one that appears first in the variable +@iftex +@code{vc-handled-backends}. +@end iftex +@ifnottex +@code{vc-handled-backends} (@pxref{Customizing VC}). +@end ifnottex +If Emacs cannot find a version control system to register the file +under, it prompts for a repository type, creates a new repository, and +registers the file into that repository. + + On most version control systems, registering a file with @kbd{C-x v +i} or @kbd{C-x v v} adds it to the ``working tree'' but not to the +repository. Such files are labeled as @samp{added} in the VC +Directory buffer, and show a revision ID of @samp{@@@@} in the mode +line. To make the registration take effect in the repository, you +must perform a commit (@pxref{Basic VC Editing}). Note that a single +commit can include both file additions and edits to existing files. + + On a locking-based version control system (@pxref{VCS Merging}), +registering a file leaves it unlocked and read-only. Type @kbd{C-x v +v} if you wish to start editing it. @node Old Revisions @subsection Examining And Comparing Old Revisions - One of the convenient features of version control is the ability -to examine any revision of a file, or compare two revisions. - @table @kbd -@item C-x v ~ -Prompt for a revision of the current file, and visit it in a buffer of -its own (@code{vc-revision-other-window}). - @item C-x v = -Compare the files in the current fileset with the working revision(s) -you started from (@code{vc-diff}). With a prefix argument, prompt for -two revisions of the current fileset and compare them. You can call -this command from a Dired buffer (@pxref{Dired}). +Compare the work files in the current VC fileset with the versions you +started from (@code{vc-diff}). With a prefix argument, prompt for two +revisions of the current VC fileset and compare them. You can also +call this command from a Dired buffer (@pxref{Dired}). + +@ifnottex +@item M-x vc-ediff +Like @kbd{C-x v =}, but using Ediff. @xref{Top, Ediff, ediff, The +Ediff Manual}. +@end ifnottex @item C-x v D -Compare the entire tree corresponding to the current fileset with the -tree you started from (@code{vc-root-diff}). With a prefix argument, -prompt for two revisions and compare their trees. +Compare the entire working tree to the revision you started from +(@code{vc-root-diff}). With a prefix argument, prompt for two +revisions and compare their trees. + +@item C-x v ~ +Prompt for a revision of the current file, and visit it in a separate +buffer (@code{vc-revision-other-window}). @item C-x v g -Display an annotated version of the file: for each line, show the -latest revision in which it was modified (@code{vc-annotate}). +Display an annotated version of the current file: for each line, show +the latest revision in which it was modified (@code{vc-annotate}). @end table -@findex vc-revision-other-window -@kindex C-x v ~ - To examine an old revision, visit the work file and type @kbd{C-x v -~ @var{revision} @key{RET}} (@code{vc-revision-other-window}). Here, -@var{revision} is either the desired revision ID (@pxref{VCS -Concepts}), or the name of a tag or branch -@iftex -(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Tags}). -@end ifnottex -This command puts the text of the old revision in a file named -@file{@var{filename}.~@var{revision}~}, and visits it in its own -buffer in a separate window. - @findex vc-diff @kindex C-x v = - @kbd{C-x v =} (@code{vc-diff}) compares each file in the current VC -fileset (saving them if necessary) with the repository revision(s) -from which you started editing. Note that the latter may or may not -be the latest revision of the file(s). - - The diff is displayed in another window, in a Diff mode buffer -(@pxref{Diff Mode}) named @file{*vc-diff*}. In this buffer, the -@kbd{g} (@code{revert-buffer}) command performs the file comparison -again, generating a new diff. + @kbd{C-x v =} (@code{vc-diff}) displays a @dfn{diff} which compares +each work file in the current VC fileset to the version(s) from which +you started editing. The diff is displayed in another window, in a +Diff mode buffer (@pxref{Diff Mode}) named @file{*vc-diff*}. The +usual Diff mode commands are available in this buffer. In particular, +the @kbd{g} (@code{revert-buffer}) command performs the file +comparison again, generating a new diff. -@findex vc-diff @kindex C-u C-x v = To compare two arbitrary revisions of the current VC fileset, call @code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}. This -prompts for two revision IDs, using the minibuffer, and displays the -diff in a special buffer in another window. Instead of providing a -revision ID, you can give an empty input, which specifies the current -contents of the work file; or a tag or branch name -@iftex -(@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}). -@end iftex +prompts for two revision IDs (@pxref{VCS Concepts}), and displays a +diff between those versions of the fileset. This will not work +reliably for multi-file VC filesets, if the version control system is +file-based rather than changeset-based (e.g.@: CVS), since then +revision IDs for different files would not be related in any +meaningful way. + + Instead of the revision ID, some version control systems let you +specify revisions in other formats. For instance, under Bazaar you +can enter @samp{date:yesterday} for the argument to @kbd{C-u C-x v =} +(and related commands) to specify the first revision committed after +yesterday. See the documentation of the version control system for +details. + + If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a Dired buffer +(@pxref{Dired}), the file listed on the current line is treated as the +current VC fileset. + @ifnottex -(@pxref{Tags}). +@findex vc-ediff + @kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an +Ediff session. @xref{Top, Ediff, ediff, The Ediff Manual}. @end ifnottex -If your version control system is file-based (e.g. CVS) rather than -changeset-based (Subversion, GNU Arch, git, Mercurial), supplying a -revision ID for a multi-file fileset (as opposed to a symbolic tag -name) is unlikely to return diffs that are connected in any meaningful -way. - - The command @kbd{C-x v D} (@code{vc-root-diff}) is similar to -@kbd{C-x v =}, but it compares the entire tree associated with the -current VC fileset with the tree you started with. This means all the -files controlled by the current version control repository, even those -that are not part of the current VC fileset. - - If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a buffer that -is neither visiting a version-controlled file nor a VC directory -buffer, these commands generate a diff of all registered files in the -current directory and its subdirectories. -@findex vc-ediff -The function @code{vc-ediff} works like @code{vc-diff} and provides a way to -visually compare two revisions of a file in an Ediff session, @pxref{Top, -Ediff, ediff, The Ediff Manual}. It compares the file associated with the -current buffer with the last repository revision. To compare two arbitrary -revisions of the current file, call @code{vc-ediff} with a prefix argument. +@findex vc-root-diff +@kindex C-x v D + @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but +it displays the changes in the entire current working tree (i.e.@: the +working tree containing the current VC fileset). If you invoke this +command from a Dired buffer, it applies to the working tree containing +the directory. @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. The options -to pass to the @code{diff} command are taken from the first non-@code{nil} -value of @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, -and @code{diff-switches} (@pxref{Comparing Files}), in that order. -Since @code{nil} means to check the next variable in the sequence, -either of the first two may use the value @code{t} to mean no switches at all. -Most of the @samp{vc@dots{}diff-switches} variables default to -@code{nil}, but some default to @code{t}. These are for those version -control systems (e.g. SVN) whose @code{diff} implementations do not -accept common options (e.g. @samp{-c}) likely to be in -@code{diff-switches}. - - 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 -revisions are not, in general, present as files on your disk.) + You can customize the @command{diff} options that @kbd{C-x v =} and +@kbd{C-x v D} use for generating diffs. The options used are taken +from the first non-@code{nil} value amongst the variables +@code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and +@code{diff-switches} (@pxref{Comparing Files}), in that order. Here, +@var{backend} stands for the relevant version control system, +e.g.@: @code{bzr} for Bazaar. Since @code{nil} means to check the +next variable in the sequence, either of the first two may use the +value @code{t} to mean no switches at all. Most of the +@code{vc-@var{backend}-diff-switches} variables default to @code{nil}, +but some default to @code{t}; these are for version control systems +whose @code{diff} implementations do not accept common diff options, +such as Subversion. + +@findex vc-revision-other-window +@kindex C-x v ~ + To directly examine an older version of a file, visit the work file +and type @kbd{C-x v ~ @var{revision} @key{RET}} +(@code{vc-revision-other-window}). This retrieves the file version +corresponding to @var{revision}, saves it to +@file{@var{filename}.~@var{revision}~}, and visits it in a separate +window. @findex vc-annotate @kindex C-x v g - For some back ends, you can display the file @dfn{annotated} with -per-line revision information, by typing @kbd{C-x v g} + Many version control systems allow you to view files @dfn{annotated} +with per-line revision information, by typing @kbd{C-x v g} (@code{vc-annotate}). This 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. +buffer'') displaying the file's text, with each line colored to show +how old it is. Red text is new, blue is 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, Emacs reads two -arguments using the minibuffer: the ID of which revision to display and -annotate (instead of the current file contents), and the time span in -days the color range should cover. +arguments using the minibuffer: the revision 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 @@ -795,13 +832,13 @@ 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. +Annotate the previous revision, i.e.@: 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. +Annotate the next revision, i.e.@: the revision after the one +currently annotated. A numeric prefix argument is a repeat count. @item j Annotate the revision indicated by the current line. @@ -840,76 +877,12 @@ Toggle the annotation visibility. This is useful for looking just at the file contents without distraction from the annotations. @end table -@node Secondary VC Commands -@subsection The Secondary Commands of VC - - This section explains the secondary commands of VC. - -@menu -* Registering:: Putting a file under version control. -* VC Change Log:: Viewing the VC Change Log. -* VC Undo:: Canceling changes before or after check-in. -@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 -revision by typing @kbd{C-x v v}. Until you do that, the revision ID -appears as @samp{@@@@} in the mode line. - -@vindex vc-default-init-revision -@cindex initial revision ID to register - The default initial revision ID for a newly registered file -varies by what VCS you are using; normally it will be 1.1 on VCSes -that use dot-pair revision IDs and 1 on VCSes that use monotonic IDs. -You can specify a different default by setting the variable -@code{vc-default-init-revision}, or you can give @kbd{C-x v i} a -numeric argument; then it reads the initial revision ID for this -particular file using the minibuffer. - -@c See http://debbugs.gnu.org/9745 -@c @vindex vc-initial-comment -@c If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an -@c initial comment to describe the purpose of this source file. Reading -@c the initial comment works like reading a log entry (@pxref{Log Buffer}). - @node VC Change Log -@subsubsection VC Change Log +@subsection VC Change Log @table @kbd @item C-x v l -Display revision control state and change history +Display the change history for the current fileset (@code{vc-print-log}). @item C-x v L @@ -928,85 +901,91 @@ Display the changes that will be sent by the next push operation @kindex C-x v l @findex vc-print-log The command @kbd{C-x v l} (@code{vc-print-log}) displays a buffer -named @samp{*vc-change-log*} in a new window. This buffer lists the -changes to the current file, including the associated log entries. -(These are the log entries associated with the version control system, -i.e. the ones you enter via the @samp{*VC-Log*} buffer. @xref{Log -Buffer}.) Point is centered at the revision of the file currently -being visited. With a prefix argument, the command prompts for the -revision to center on, and the maximum number of revisions to display. -You can call this command from a Dired buffer (@pxref{Dired}). +named @samp{*vc-change-log*}, showing the history of changes made to +the current file, including who made the changes, the dates, and the +log entry for each change (these are the same log entries you would +enter via the @samp{*vc-log*} buffer; @pxref{Log Buffer}). Point is +centered at the revision of the file currently being visited. With a +prefix argument, the command prompts for the revision to center on, +and the maximum number of revisions to display. + + If you call @kbd{C-x v l} from a VC Directory buffer (@pxref{VC +Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the +file listed on the current line. @findex vc-print-root-log - Type @kbd{C-x v L} (@code{vc-print-root-log}) to display a -@samp{*vc-change-log*} buffer showing the history of the -version-controlled directory tree as a whole. With a prefix argument, -the command prompts for the maximum number of revisions to display. -RCS, SCCS, and CVS do not support this feature. - - On a distributed version control system, the @kbd{C-x v I} +@findex log-view-toggle-entry-display + @kbd{C-x v L} (@code{vc-print-root-log}) displays a +@samp{*vc-change-log*} buffer showing the history of the entire +version-controlled directory tree (RCS, SCCS, and CVS do not support +this feature). With a prefix argument, the command prompts for the +maximum number of revisions to display. + + The @kbd{C-x v L} history is shown in a compact form, usually +showing only the first line of each log entry. However, you can type +@key{RET} (@code{log-view-toggle-entry-display}) in the +@samp{*vc-change-log*} buffer to reveal the entire log entry for the +revision at point. A second @key{RET} hides it again. + + On a decentralized version control system, the @kbd{C-x v I} (@code{vc-log-incoming}) command displays a log buffer showing the changes that will be applied, the next time you run the version control system's ``pull'' command to get new revisions from another -repository. This other repository is the default one from which -changes are pulled, as defined by the version control system; with a -prefix argument, @code{vc-log-incoming} prompts for a specific -repository from which changes would be pulled, and lists the changes -accordingly. Similarly, @kbd{C-x v O} (@code{vc-log-outgoing}) shows -the changes that will be sent to another repository, the next time you -run the ``push'' command; with a prefix argument, it prompts for a -specific repository to which changes would be pushed. +repository (@pxref{VC Pull}). This other repository is the default +one from which changes are pulled, as defined by the version control +system; with a prefix argument, @code{vc-log-incoming} prompts for a +specific repository. Similarly, @kbd{C-x v O} +(@code{vc-log-outgoing}) shows the changes that will be sent to +another repository, the next time you run the ``push'' command; with a +prefix argument, it prompts for a specific destination repository. In the @samp{*vc-change-log*} buffer, you can use the following keys -to move between the logs of revisions and of files, to view past -revisions, to modify change comments, to view annotations and to view -diffs: +to move between the logs of revisions and of files, and to examine and +compare past revisions (@pxref{Old Revisions}): @table @kbd @item p -Move to the previous revision-item in the buffer. (Revision entries in the log +Move to the previous revision entry. (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. +Move to the next revision entry. 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 (@pxref{VC Directory Mode}). 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. +Move to the log of the previous file, if showing logs for a multi-file +VC fileset. Otherwise, just move to the beginning of the log. A +numeric prefix argument is a repeat count. @item N -Move to the log of the next file, when the logs of multiple files are -in the log buffer (@pxref{VC Directory Mode}). It also takes a -numeric prefix argument as a repeat count. +Move to the log of the next file, if showing logs for a multi-file VC +fileset. A numeric prefix argument is a repeat count. @item a -Annotate the revision indicated by the current line. +Annotate the revision on the current line (@pxref{Old Revisions}). @item e Modify the change comment displayed at point. Note that not all VC systems support modifying change comments. @item f -Visit the revision indicated at the current line, like typing @kbd{C-x -v ~} and specifying this revision's ID (@pxref{Old Revisions}). +Visit the revision indicated at the current line. @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 in the file when the revision -indicated on the current line was committed. +Display a diff between the revision at point and the next earlier +revision, for the specific file. @item D -Display the changeset diff (@pxref{Comparing Files}) between the -revision indicated at the current line and the next earlier revision. -This is useful to see all the changes to all files that the revision -indicated on the current line did when it was committed. +Display the changeset diff between the revision at point and the next +earlier revision. This shows the changes to all files made in that +revision. + +@item @key{RET} +In a compact-style log buffer (e.g.@: the one created by @kbd{C-x v +L}), toggle between showing and hiding the full log entry for the +revision at point. @end table @vindex vc-log-show-limit @@ -1020,62 +999,71 @@ entries} or @samp{Show unlimited entries} buttons at the end of the buffer. However, RCS, SCCS, and CVS do not support this feature. @node VC Undo -@subsubsection Undoing Version Control Actions +@subsection Undoing Version Control Actions @table @kbd @item C-x v u -Revert the buffer and the file to the working revision 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. +Revert the work file(s) in the current VC fileset to the last revision +(@code{vc-revert}). @end table +@c `C-x v c' (vc-rollback) was removed, since it's RCS/SCCS specific. + @kindex C-x v u -@findex vc-revert-buffer - If you want to discard your current set of changes and revert to the -working revision from which you started editing the file, use @kbd{C-x -v u} (@code{vc-revert-buffer}). If the version control system is -locking-based, this leaves the file unlocked, and you must lock it -again before making new changes. @kbd{C-x v u} requires confirmation, -unless it sees that you haven't made any changes with respect to the -master copy of the working revision. - - @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-rollback - To cancel a change that you already committed, use @kbd{C-x v c} -(@code{vc-rollback}). This command discards all record of the most -recent checked-in revision, but only if your work file corresponds to -that revision---you cannot use @kbd{C-x v c} to cancel a revision that -is not the latest on its branch. Note that many version control -systems do not support rollback at all; this command is something of a -historical relic. +@findex vc-revert +@vindex vc-revert-show-diff + If you want to discard all the changes you have made to the current +VC fileset, type @kbd{C-x v u} (@code{vc-revert-buffer}). This shows +you a diff between the work file(s) and the revision from which you +started editing, and asks for confirmation for discarding the changes. +If you agree, the fileset is reverted. If you don't want @kbd{C-x v +u} to show a diff, set the variable @code{vc-revert-show-diff} to +@code{nil} (you can still view the diff directly with @kbd{C-x v =}; +@pxref{Old Revisions}). Note that @kbd{C-x v u} cannot be reversed +with the usual undo commands (@pxref{Undo}), so use it with care. + + On locking-based version control systems, @kbd{C-x v u} leaves files +unlocked; you must lock again to resume editing. You can also use +@kbd{C-x v u} to unlock a file if you lock it and then decide not to +change it. @node VC Directory Mode @subsection VC Directory Mode +@cindex VC Directory buffer + The @dfn{VC Directory buffer} is a specialized buffer for viewing +the version control statuses of the files in a directory tree, and +performing version control operations on those files. In particular, +it is used to specify multi-file VC filesets for commands like +@w{@kbd{C-x v v}} to act on (@pxref{VC Directory Commands}). + @kindex C-x v d @findex vc-dir - 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-dir}) to make a directory -listing that includes only files relevant for version control. This -creates a @dfn{VC Directory buffer} and displays it in a separate -window. + To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}). +This reads a directory name using the minibuffer, and switches to a VC +Directory buffer for that directory. By default, the buffer is named +@samp{*vc-dir*}. Its contents are described +@iftex +below. +@end iftex +@ifnottex +in @ref{VC Directory Buffer}. +@end ifnottex + + The @code{vc-dir} command automatically detects the version control +system to be used in the specified directory. In the event that more +than one system is being used in the directory, you should invoke the +command with a prefix argument, @kbd{C-u C-x v d}; this prompts for +the version control system which the VC Directory buffer should use. +@ifnottex @cindex PCL-CVS @pindex cvs @cindex CVS directory mode - The VC Directory buffer works with all the version control systems -that VC supports. For CVS, Emacs also offers a more powerful facility -called PCL-CVS. @xref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The -Emacs Front-End to CVS}. + In addition to the VC Directory buffer, Emacs has a similar facility +called PCL-CVS which is specialized for CVS. @xref{Top, , About +PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}. +@end ifnottex @menu * Buffer: VC Directory Buffer. What the buffer looks like and means. @@ -1086,369 +1074,367 @@ Emacs Front-End to CVS}. @subsubsection The VC Directory Buffer The VC Directory buffer contains a list of version-controlled files -in the current directory and its subdirectories. Files which are -up-to-date (have no local differences from the repository copy) are -usually hidden; if all files in a subdirectory are up-to-date, the -subdirectory is hidden as well. There is an exception to this rule: -if VC mode detects that a file has changed to an up-to-date state -since you last looked at it, that file and its state are shown. - - If a directory uses more that one version control system, you can -select which system to use for the @code{vc-dir} command by invoking -@code{vc-dir} with a prefix argument: @kbd{C-u C-x v d}. - - The line for an individual file shows the version control state of -the file. 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 CVS: +and their version control statuses. It lists files in the current +directory (the one specified when you called @kbd{C-x v d}) and its +subdirectories, but only those with a ``noteworthy'' status. Files +that are up-to-date (i.e.@: the same as in the repository) are +omitted. If all the files in a subdirectory are up-to-date, the +subdirectory is not listed either. As an exception, if a file has +become up-to-date as a direct result of a VC command, it is listed. + + Here is an example of a VC Directory buffer listing: @smallexample @group - ./ - modified file1.c - needs-update file2.c - needs-merge file3.c + ./ + edited configure.ac +* added README + unregistered temp.txt + src/ +* edited src/main.c @end group @end smallexample @noindent -In this example, @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 committed---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 only -contacts it when the variable @code{vc-stay-local} (or -@code{vc-cvs-stay-local}) is @code{nil} +Two work files have been modified but not committed: +@file{configure.ac} in the current directory, and @file{foo.c} in the +@file{src/} subdirectory. The file named @file{README} has been added +but is not yet committed, while @file{temp.txt} is not under version +control (@pxref{Registering}). + +The @samp{*} characters next to the entries for @file{README} and +@file{src/main.c} indicate that the user has marked out these files as +the current VC fileset @iftex -(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}). +(see below). @end iftex @ifnottex -(@pxref{CVS Options}). +(@pxref{VC Directory Commands}). +@end ifnottex + + The above example is typical for a decentralized version control +system like Bazaar, Git, or Mercurial. Other systems can show other +statuses. For instance, CVS shows the @samp{needs-update} status if +the repository has changes that have not been applied to the work +file. RCS and SCCS show the name of the user locking a file as its +status. + +@ifnottex +@vindex vc-stay-local +@vindex vc-cvs-stay-local + On CVS and Subversion, the @code{vc-dir} command normally contacts +the repository, which may be on a remote machine, to check for +updates. If you change the variable @code{vc-stay-local} or +@code{vc-cvs-stay-local} (for CVS) to @code{nil} (@pxref{CVS +Options}), then Emacs avoids contacting a remote repository when +generating the VC Directory buffer (it will still contact it when +necessary, e.g.@: when doing a commit). This may be desirable if you +are working offline or the network is slow. @end ifnottex -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 a VC directory displays subdirectories 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}. + The VC Directory buffer omits subdirectories listed in the variable +@code{vc-directory-exclusion-list}. Its default value contains +directories that are used internally by version control systems. @node VC Directory Commands @subsubsection VC Directory Commands - VC Directory mode has a full set of navigation and marking commands -for picking out filesets. Some of these are also available in a -context menu invoked by @kbd{mouse-2}. + Emacs provides several commands for navigating the VC Directory +buffer, and for ``marking'' files as belonging to the current VC +fileset. - Up- and down-arrow keys move in the buffer; @kbd{n} and @kbd{p} also -move vertically as in other list-browsing modes. @key{SPC} and -@key{TAB} behave like down-arrow, and @key{BackTab} behaves like -up-arrow. +@table @kbd +@item n +@itemx @key{SPC} +Move point to the next entry (@code{vc-dir-next-line}). - Both @kbd{C-m} and @kbd{f} visit the file on the current -line. @kbd{o} visits that file in another window. @kbd{q} dismisses -the directory buffer. +@item p +Move point to the previous entry (@code{vc-dir-previous-line}). - @kbd{x} hides up-to-date files. +@item @key{TAB} +Move to the next directory entry (@code{vc-dir-next-directory}). - @kbd{m} marks the file or directory on the current line. If the -region is active, @kbd{m} marks all the files in the region. There -are some restrictions when marking: a file cannot be marked if any of -its parent directories are marked, and a directory cannot be marked if -any files in it or in its child directories are marked. +@item S-@key{TAB} +Move to the previous directory entry +(@code{vc-dir-previous-directory}). - @kbd{M} marks all the files with the same VC state as the current -file if the cursor is on a file. If the cursor is on a directory, it -marks all child files. With a prefix argument: marks all files and -directories. +@item @key{RET} +@itemx f +Visit the file or directory listed on the current line +(@code{vc-dir-find-file}). - @kbd{u} unmarks the file or directory on the current line. If the -region is active, it unmarks all the files in the region. +@item o +Visit the file or directory on the current line, in a separate window +(@code{vc-dir-find-file-other-window}). - @kbd{U} marks all the files with the same VC state as the current file -if the cursor is on a file. If the cursor is on a directory, it -unmarks all child files. With a prefix argument: unmarks all marked +@item m +Mark the file or directory on the current line (@code{vc-dir-mark}), +putting it in the current VC fileset. If the region is active, mark +all files in the region. + +A file cannot be marked with this command if it is already in a marked +directory, or one of its subdirectories. Similarly, a directory +cannot be marked with this command if any file in its tree is marked. + +@item M +If point is on a file entry, mark all files with the same status; if +point is on a directory entry, mark all files in that directory tree +(@code{vc-dir-mark-all-files}). With a prefix argument, mark all +listed files and directories. + +@kindex q @r{(VC Directory)} +@findex quit-window +@item q +Bury the VC Directory buffer, and delete its window if the window was +created just for that buffer. + +@item u +Unmark the file or directory on the current line. If the region is +active, unmark all the files in the region (@code{vc-dir-unmark}). + +@item U +If point is on a file entry, unmark all files with the same status; if +point is on a directory entry, unmark all files in that directory tree +(@code{vc-dir-unmark-all-files}). With a prefix argument, unmark all files and directories. - It is possible to do search, search and replace, incremental search, -and incremental regexp search on multiple files. These commands will -work on all the marked files or the current file if nothing is marked. -If a directory is marked, the files in that directory shown in the VC -directory buffer will be used. +@item x +Hide files with @samp{up-to-date} status +(@code{vc-dir-hide-up-to-date}). - @kbd{S} searches the marked files. +@item q +Quit the VC Directory buffer, and bury it (@code{quit-window}). +@end table - @kbd{Q} does a query replace on the marked files. +@findex vc-dir-mark +@findex vc-dir-mark-all-files + While in the VC Directory buffer, all the files that you mark with +@kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark}) are in +the current VC fileset. If you mark a directory entry with @kbd{m}, +all the listed files in that directory tree are in the current VC +fileset. The files and directories that belong to the current VC +fileset are indicated with a @samp{*} character in the VC Directory +buffer, next to their VC status. In this way, you can set up a +multi-file VC fileset to be acted on by VC commands like @w{@kbd{C-x v +v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}} (@pxref{Old +Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}). + + The VC Directory buffer also defines some single-key shortcuts for +VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l}, +@kbd{i}, and @kbd{v}. + + For example, you can commit a set of edited files by opening a VC +Directory buffer, where the files are listed with the @samp{edited} +status; marking the files; and typing @kbd{v} or @kbd{C-x v v} +(@code{vc-next-action}). If the version control system is +changeset-based, Emacs will commit the files in a single revision. + + While in the VC Directory buffer, you can also perform search and +replace on the current VC fileset, with the following commands: - @kbd{M-s a C-s} does an incremental search on the marked files. +@table @kbd +@item S +Search the fileset (@code{vc-dir-search}). - @kbd{M-s a C-M-s} does an incremental regular expression search -on the marked files. +@item Q +Do a regular expression query replace on the fileset +(@code{vc-dir-query-replace-regexp}). + +@item M-s a C-s +Do an incremental search on the fileset (@code{vc-dir-isearch}). + +@item M-s a C-M-s +Do an incremental regular expression search on the fileset +(@code{vc-dir-isearch-regexp}). +@end table + +@noindent +Apart from acting on multiple files, these commands behave much like +their single-buffer counterparts (@pxref{Search}). @cindex stashes in version control @cindex shelves in version control - Commands are also accessible from the VC-dir menu. Note that some -VC backends use the VC-dir menu to make available extra, -backend-specific, commands. For example, Git and Bazaar allow you to -manipulate @dfn{stashes} and @dfn{shelves}. (These provide a -mechanism to temporarily store uncommitted changes somewhere out of -the way, and bring them back at a later time.) - - Normal VC commands with the @kbd{C-x v} prefix work in VC directory -buffers. Some single-key shortcuts are available as well; @kbd{=}, -@kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with -@kbd{C-x v}. - - The command @kbd{C-x v v} (@code{vc-next-action}) operates on all -the marked files, so that you can commit several files at once. If -the underlying VC supports atomic commits of multiple-file changesets, -@kbd{C-x v v} with a selected set of modified but not committed files -will commit all of them at once as a single changeset. - - When @kbd{C-x v v} (@code{vc-next-action}) operates on multiple -files, all of those files must be either in the same state or in -compatible states (added, modified and removed states are considered -compatible). Otherwise it signals an error. This differs from the -behavior of older versions of VC, which did not have fileset -operations and simply did @code{vc-next-action} on each file -individually. - - If any files are in a state that calls for commit, @kbd{C-x v v} reads a -single log entry and uses it for the changeset as a whole. If the -underling VCS is file- rather than changeset-oriented, the log entry -will be replicated into the history of each file. + The above commands are also available via the menu bar, and via a +context menu invoked by @kbd{Mouse-2}. Furthermore, some VC backends +use the menu to provide extra backend-specific commands. For example, +Git and Bazaar allow you to manipulate @dfn{stashes} and @dfn{shelves} +(where are a way to temporarily put aside uncommitted changes, and +bring them back at a later time). @node Branches -@subsection Multiple Branches of a File +@subsection Version Control Branches @cindex branch (version control) -@cindex trunk (version control) - - One use of version control is to maintain multiple ``current'' -revisions of a file. For example, you might have different revisions 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}. -You can create multiple branches from the trunk. How the difference -between trunk and branch is made visible is dependent on whether the -VCS uses dot-pair or monotonic version IDs. - - In VCSes with dot-pair revision IDs, the revisions on the trunk are -normally IDed 1.1, 1.2, 1.3, etc. At any such revision, you can -start an independent branch. A branch starting at revision 1.2 would -have revision ID 1.2.1.1, and consecutive revisions on this branch -would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is -a second branch also starting at revision 1.2, it would consist of -revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. - - In VCSes with monotonic revision IDs, trunk revisions are IDed as -1, 2, 3, etc. A branch from (say) revision 2 might start with 2.1 and -continue through 2.2, 2.3, etc. But naming conventions for branches -and subbranches vary widely on these systems, and some (like -Mercurial) never depart from the monotonic integer sequence at all. -Consult the documentation of the VCS you are using. - -@cindex head revision - If you omit the final component of a dot-pair revision ID, that is called a -@dfn{branch ID}. It refers to the highest existing revision on that -branch---the @dfn{head revision} of that branch. The branches in the -dot-pair example above have branch IDs 1.2.1 and 1.2.2. + + One use of version control is to support multiple independent lines +of development, which are called @dfn{branches}. Branches are used +for maintaining separate ``stable'' and ``development'' versions of a +program, and for developing unrelated features in isolation from one +another. + + VC's support for branch operations is currently fairly limited. For +decentralized version control systems, it provides commands for +@dfn{updating} one branch with the contents of another, and for +@dfn{merging} the changes made to two different branches +(@pxref{Merging}). For centralized version control systems, it +supports checking out different branches and committing into new or +different branches. @menu * Switching Branches:: How to get to another existing branch. -* Creating Branches:: How to start a new branch. +* VC Pull:: Updating the contents of a branch. * Merging:: Transferring changes between branches. -* Multi-User Branching:: Multiple users working at multiple branches - in parallel. +* Creating Branches:: How to start a new branch. @end menu @node Switching Branches @subsubsection Switching between Branches - To switch between branches, type @kbd{C-u C-x v v} and specify the -revision ID you want to select. On a locking-based system, 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. - - On a VCS with dot-pair IDs, you can omit the minor part, thus giving -only the branch ID; 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. + The various version control systems differ in how branches are +implemented, and these differences cannot be entirely concealed by VC. + + On some decentralized version control systems, including Bazaar and +Mercurial in its normal mode of operation, each branch has its own +working directory tree, so switching between branches just involves +switching directories. On Git, switching between branches is done +using the @command{git branch} command, which changes the contents of +the working tree itself. + + On centralized version control systems, you can switch between +branches by typing @kbd{C-u C-x v v} in an up-to-date work file +(@pxref{Advanced C-x v v}), and entering the revision ID for a +revision on another branch. On CVS, for instance, revisions on the +@dfn{trunk} (the main line of development) normally have IDs of the +form 1.1, 1.2, 1.3, @dots{}, while the first branch created from (say) +revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, @dots{}, the second +branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2, +@dots{}, and so forth. You can also specify the @dfn{branch ID}, +which is a branch revision ID omitting its final component +(e.g.@: 1.2.1), to switch to the latest revision on that branch. + + On a locking-based system, switching to a different branch also +unlocks (write-protects) the working tree. + + Once you have switched to a branch, VC commands will apply to that +branch until you switch away; for instance, any VC filesets that you +commit will be committed to that specific branch. + +@node VC Pull +@subsubsection Pulling Changes into a Branch - 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. +@table @kbd +@itemx C-x v + +On a decentralized version control system, update the current branch +by ``pulling in'' changes from another location. -@node Creating Branches -@subsubsection Creating New Branches +On a centralized version control system, update the current VC +fileset. +@end table - To create a new branch from a head revision (one that is the latest -in the branch that contains it), first select that revision if -necessary, lock it with @kbd{C-x v v}, and make whatever changes you -want. Then, when you commit the changes, use @kbd{C-u C-x v v}. This -lets you specify the revision ID for the new revision. You should -specify a suitable branch ID for a branch starting at the current -revision. For example, if the current revision is 2.5, the branch ID -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 revision (one that is no longer the -head of a branch), first select that revision (@pxref{Switching -Branches}). Your procedure will then differ depending on whether you -are using a locking or merging-based VCS. +@kindex C-x v + +@findex vc-pull + On a decentralized version control system, the command @kbd{C-x v +} +(@code{vc-pull}) updates the current branch and working tree. It is +typically used to update a copy of a remote branch. If you supply a +prefix argument, the command prompts for the exact version control +command to use, which lets you specify where to pull changes from. +Otherwise, it pulls from a default location determined by the version +control system. - On a locking VCS, you will need to lock the old revision branch with -@kbd{C-x v v}. You'll be asked to confirm, when you lock the old -revision, that you really mean to create a new branch---if you say no, -you'll be offered a chance to lock the latest revision instead. On -a merging-based VCS you will skip this step. + Amongst decentralized version control systems, @kbd{C-x v +} is +currently supported only by Bazaar, Git, and Mercurial. On Bazaar, it +calls @command{bzr pull} for ordinary branches (to pull from a master +branch into a mirroring branch), and @command{bzr update} for a bound +branch (to pull from a central repository). On Git, it calls +@command{git pull} to fetch changes from a remote repository and merge +it into the current branch. On Mercurial, it calls @command{hg pull +-u} to fetch changesets from the default remote repository and update +the working directory. - Then make your changes and type @kbd{C-x v v} again to commit a new -revision. This automatically creates a new branch starting from the -selected revision. You need not specially request a new branch, -because that's the only way to add a new revision at a point that is -not the head of a branch. + Prior to pulling, you can use @kbd{C-x v I} (@code{vc-log-incoming}) +to view a log buffer of the changes to be applied. @xref{VC Change +Log}. - After the branch is created, you ``stay'' on it. That means that -subsequent check-ins create new revisions on that branch. To leave the -branch, you must explicitly select a different revision 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. + On a centralized version control system like CVS, @kbd{C-x v +} +updates the current VC fileset from the repository. @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. +@itemx C-x v m +On a decentralized version control system, merge changes from another +branch into the current one. + +On a centralized version control system, merge changes from another +branch into the current VC fileset. @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 ID or a pair of revision IDs in -the minibuffer. Then @kbd{C-x v m} finds the changes from that -branch, or the differences between the two revisions you specified, and -merges them into the current revision 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 revision 1.5. To merge the changes from the branch to the trunk, -first go to the head revision of the trunk, by typing @kbd{C-u C-x v v -@key{RET}}. Revision 1.5 is now current. If locking is used for the file, -type @kbd{C-x v v} to lock revision 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 revision 1.3, where the branch started, up to -the last revision on the branch) and merges it into the current revision -of the work file. You can now commit the changed file, thus creating -revision 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 commit the merged -revision, then lock it and make the further changes. This will keep -a better record of the history of changes. + While developing a branch, you may sometimes need to @dfn{merge} in +changes that have already been made in another branch. This is not a +trivial operation, as overlapping changes may have been made to the +two branches. + + On a decentralized version control system, merging is done with the +command @kbd{C-x v m} (@code{vc-merge}). On Bazaar, this prompts for +the exact arguments to pass to @command{bzr merge}, offering a +sensible default if possible. On Git, this prompts for the name of a +branch to merge from, with completion (based on the branch names known +to the current repository). The output from running the merge command +is shown in a separate buffer. + + On a centralized version control system like CVS, @kbd{C-x v m} +prompts for a branch ID, or a pair of revision IDs (@pxref{Switching +Branches}); then it finds the changes from that branch, or the changes +between the two revisions you specified, and merges those changes into +the current VC fileset. If you just type @key{RET}, Emacs simply +merges any changes that were made on the same branch since you checked +the file out. @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 revision 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 + Immediately after performing a merge, only the working tree is +modified, and you can review the changes produced by the merge with +@kbd{C-x v D} and related commands (@pxref{Old Revisions}). If the +two branches contained overlapping changes, merging produces a +@dfn{conflict}; a warning appears in the output of the merge command, +and @dfn{conflict markers} are inserted into each affected work file, +surrounding the two sets of conflicting changes. You must then +resolve the conflict by editing the conflicted files. Once you are +done, the modified files must be committed in the usual way for the +merge to take effect (@pxref{Basic VC Editing}). -@findex 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 -commit the merged version afterwards. - -@findex vc-find-conflicted-file - If there is more than one conflicted file in a merge, type @kbd{M-x -vc-find-conflicted-file} after resolving the conflicts in each file. -This command visits the next conflicted file, and moves point to the -first conflict marker in that file. - -@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 and later systems allow 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 -revisions, 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 revision -ID is present in the work file. +@node Creating Branches +@subsubsection Creating New Branches + + On centralized version control systems like CVS, Emacs supports +creating new branches as part of a commit operation. When committing +a modified VC fileset, type @kbd{C-u C-x v v} (@code{vc-next-action} +with a prefix argument; @pxref{Advanced C-x v v}). Then Emacs prompts +for a revision ID for the new revision. You should specify a suitable +branch ID for a branch starting at the current revision. For example, +if the current revision is 2.5, the branch ID 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 revision (one that is no longer +the head of a branch), first select that revision (@pxref{Switching +Branches}). Your procedure will then differ depending on whether you +are using a locking or merging-based VCS. + + On a locking VCS, you will need to lock the old revision branch with +@kbd{C-x v v}. You'll be asked to confirm, when you lock the old +revision, that you really mean to create a new branch---if you say no, +you'll be offered a chance to lock the latest revision instead. On a +merging-based VCS you will skip this step. + + Then make your changes and type @kbd{C-x v v} again to commit a new +revision. This creates a new branch starting from the selected +revision. - 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 ID. This ensures that Emacs knows which branch it is using -during this particular editing session. + After the branch is created, subsequent commits create new revisions +on that branch. To leave the branch, you must explicitly select a +different revision with @kbd{C-u C-x v v}. @ifnottex @include vc1-xtra.texi @@ -1458,13 +1444,11 @@ during this particular editing session. @section Change Logs @cindex change log - 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. + Many software projects keep a @dfn{change log}. This is a file, +normally named @file{ChangeLog}, containing a chronological record of +when and how the program was changed. Sometimes, there are several +change log files, each recording the changes in one directory or +directory tree. @menu * Change Log Commands:: Commands for editing change log files. @@ -1496,7 +1480,7 @@ rather than starting a new item. You can combine multiple changes of the same nature. If you don't enter any text after the initial @kbd{C-x 4 a}, any subsequent -@kbd{C-x 4 a} adds another symbol to the change. +@kbd{C-x 4 a} adds another symbol to the change log entry. @vindex add-log-always-start-new-record If @code{add-log-always-start-new-record} is non-@code{nil}, @@ -1534,15 +1518,7 @@ ordering of entries. Version control systems are another way to keep track of changes in your program and keep a change log. In the VC log buffer, typing @kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant -Change Log entry, if one exists (@pxref{Log Buffer}). You can also -insert a VC log entry into a Change Log buffer by typing @kbd{C-x v a} -(@code{vc-update-change-log}) in the Change Log buffer -@iftex -(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). -@end iftex -@ifnottex -(@pxref{Change Logs and VC}). -@end ifnottex +Change Log entry, if one exists. @xref{Log Buffer}. @node Format of ChangeLog @subsection Format of ChangeLog @@ -1597,8 +1573,8 @@ Of course, you should substitute the proper years and copyright holder. @cindex tags and tag tables A @dfn{tag} is a reference to a subunit in a program or in a -document. In program source code, tags reference syntactic elements -of the program: functions, subroutines, data types, macros, etc. In a +document. In source code, tags reference syntactic elements of the +program: functions, subroutines, data types, macros, etc. In a document, tags reference chapters, sections, appendices, etc. Each tag specifies the name of the file where the corresponding subunit is defined, and the position of the subunit's definition in that file. @@ -1612,34 +1588,36 @@ a Yacc parser, or from Lex scanner definitions; @file{.i} preprocessed C files; and Fortran files produced by preprocessing @file{.fpp} source files. - To produce a tags table, you use the @samp{etags} command, -submitting it a document or the source code of a program. -@samp{etags} writes the tags to a @dfn{tags table file}, or @dfn{tags -file} in short. The conventional name for a tags file is @file{TAGS}. +@cindex etags + To produce a tags table, you run the @command{etags} shell command +on a document or the source code file. The @samp{etags} program +writes the tags to a @dfn{tags table file}, or @dfn{tags file} in +short. The conventional name for a tags file is @file{TAGS}. +@xref{Create Tags Table}. - Emacs uses the information recorded in tags tables in commands that -search or replace through multiple source files: these commands use -the names of the source files recorded in the tags table to know which -files to search. Other commands, such as @kbd{M-.}, which finds the -definition of a function, use the recorded information about the -function names and positions to find the source file and the position -within that file where the function is defined. + Emacs provides many commands for searching and replacing using the +information recorded in tags tables. For instance, the @kbd{M-.} +(@code{find-tag}) jumps to the location of a specified function +definition in its source file. @xref{Find 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}. + The Ebrowse facility is similar to @command{etags} but specifically +tailored for C++. @xref{Top,, Ebrowse, ebrowse, Ebrowse User's +Manual}. The Semantic package provides another way to generate and +use tags, separate from the @command{etags} facility. +@xref{Semantic}. @menu * Tag Syntax:: Tag syntax for various types of code and text files. -* Create Tags Table:: Creating a tags table with @code{etags}. +* Create Tags Table:: Creating a tags table with @command{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. +* List Tags:: Using tags for completion, and listing them. @end menu @node Tag Syntax @@ -1661,7 +1639,7 @@ 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}. +@command{etags}. @item In C++ code, in addition to all the tag constructs of C code, member @@ -1678,15 +1656,15 @@ 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}, +In La@TeX{} documents, the arguments for @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 +@code{\newenvironment} and @code{\renewenvironment} are tags. Other commands can make tags as well, if you specify them in the -environment variable @env{TEXTAGS} before invoking @code{etags}. The +environment variable @env{TEXTAGS} before invoking @command{etags}. The value of this environment variable should be a colon-separated list of command names. For example, @@ -1818,9 +1796,9 @@ Regexps}) to handle other formats and languages. @node Create Tags Table @subsection Creating Tags Tables -@cindex @code{etags} program +@cindex @command{etags} program - The @code{etags} program is used to create a tags table file. It knows + The @command{etags} program is used to create a tags table file. It knows the syntax of several languages, as described in @iftex the previous section. @@ -1828,58 +1806,51 @@ the previous section. @ifnottex @ref{Tag Syntax}. @end ifnottex -Here is how to run @code{etags}: +Here is how to run @command{etags}: @example etags @var{inputfiles}@dots{} @end example @noindent -The @code{etags} program reads the specified files, and writes a tags +The @command{etags} program reads the specified files, and writes a tags table named @file{TAGS} in the current working directory. You can optionally specify a different file name for the tags table by using the @samp{--output=@var{file}} option; specifying @file{-} as a file name prints the tags table to standard output. - If the specified files don't exist, @code{etags} looks for + If the specified files don't exist, @command{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} +MS-DOS, @command{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. + If the tags table becomes outdated due to changes in the files +described in it, you can update it by running the @command{etags} +program again. If the tags table does not record a tag, or records it +for the wrong file, then Emacs will not be able to find that +definition until you update the tags table. But if the position +recorded in the tags table becomes a little bit wrong (due to other +editing), Emacs will still be able to find the right position, with a +slight delay. 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. + You can make a tags table @dfn{include} another tags table, by +passing the @samp{--include=@var{file}} option to @command{etags}. It +then covers all the files covered by the included tags file, as well +as its own. 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 +@command{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 @file{-} or is in the @file{/dev} directory, -however, the file names are +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}. @@ -1887,40 +1858,41 @@ example, when writing the tags to @file{/dev/stdout}. 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 + If you specify absolute file names as arguments to @command{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: + 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. You can circumvent this limit by +telling @command{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}). + @command{etags} recognizes the language used in an input file based +on its file name and contents. You can specify the language +explicitly with the @samp{--language=@var{name}} option. You can +intermix these options with file names; each one applies to the file +names that follow it. Specify @samp{--language=auto} to tell +@command{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 @command{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 +calling @command{etags} from programs. It can be used (only once) in +place of a file name on the command line. @command{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} + @samp{etags --help} outputs the list of the languages @command{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 +a list of all the available @command{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}. @@ -1928,21 +1900,22 @@ options, it outputs detailed information about how tags are generated for @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: + The @samp{--regex} option to @command{etags} allows tags to be +recognized by regular expression matching. You can intermix this +option with file names; 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]*}. +@noindent +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 @@ -1959,7 +1932,7 @@ 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 +modify the way @command{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: @@ -1984,22 +1957,22 @@ etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \ @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 +Here @command{etags} chooses the parsing language for @file{voo.doo} and +@file{bar.ber} according to their contents. @command{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} +permitting multi-line matches, in a case-sensitive way. @command{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 +@command{etags}.) This is particularly useful when storing many +predefined regular expressions for @command{etags} in a file. The following example tags the @code{DEFVAR} macros in the Emacs source files, for the C language only: @@ -2009,7 +1982,7 @@ files, for the C language only: @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 +them in a file. The following option syntax instructs @command{etags} to read two files of regular expressions. The regular expressions contained in the second file are matched without regard to case. @@ -2018,9 +1991,9 @@ contained in the second file are matched without regard to case. @end smallexample @noindent -A regex file for @code{etags} contains one regular expression per +A regex file for @command{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 +When the first character in a line is @samp{@@}, @command{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 @@ -2083,14 +2056,14 @@ etags --language=none \ @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 + Emacs has at any time one @dfn{selected} tags table. 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. +@vindex tags-file-name 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 @@ -2154,27 +2127,25 @@ Pop back to where you previously invoked @kbd{M-.} and friends. @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}. + @kbd{M-.}@: (@code{find-tag}) prompts for a tag name and jumps to +its source definition. It works by searching through the tags table +for that tag's file and approximate character position, visiting that +file, and searching for the tag definition at ever-increasing +distances away from the recorded approximate position. + + When entering the tag argument to @kbd{M-.}, the usual minibuffer +completion commands can be used (@pxref{Completion}), with the tag +names in the selected tags table as completion candidates. If you +specify an empty argument, the balanced expression in the buffer +before or around point is the default 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-.}. +will do. @kbd{M-.} finds tags which contain that argument 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-.} or @kbd{M-0 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. @kindex C-x 4 . @findex find-tag-other-window @@ -2182,23 +2153,23 @@ alternative to @kbd{C-u M-.}. @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}. +makes a new frame for it. The former is @w{@kbd{C-x 4 .}} +(@code{find-tag-other-window}), and the latter is @w{@kbd{C-x 5 .}} +(@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. + To move back to previous tag definitions, use @kbd{C-u - M-.}; more +generally, @kbd{M-.} with a negative numeric argument. Similarly, +@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-*}. + As well as going back to places you've found tags recently, you can +go back to places @emph{from where} you found them, using @kbd{M-*} +(@code{pop-tag-mark}). Thus you can find and examine 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}. @@ -2242,10 +2213,10 @@ can follow its progress. As soon as it finds an occurrence, @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 + Having found one match, you probably want to find all the rest. +Type @kbd{M-,} (@code{tags-loop-continue}) to resume the +@code{tags-search}, finding one more match. This searches the rest of +the current buffer, followed by the remaining files of the tags table. @findex tags-query-replace @kbd{M-x tags-query-replace} performs a single @@ -2282,56 +2253,56 @@ 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. + As an alternative to @code{tags-search}, you can run @command{grep} +as a subprocess and have Emacs show you the matching lines one by one. @xref{Grep Searching}. @node List Tags @subsection Tags Table Inquiries @table @kbd +@item C-M-i +@itemx M-@key{TAB} +Perform completion on the text around point, using the selected tags +table if one is loaded (@code{completion-at-point}). @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 +@cindex completion (symbol names) + In most programming language modes, you can type @kbd{C-M-i} or +@kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol +at point. If there is a selected tags table, this command can use it +to generate completion candidates. @xref{Symbol Completion}. + @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. + @kbd{M-x list-tags} reads the name of one of the files covered by +the selected tags table, and displays a list of tags defined in that +file. 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}. - - You can use @kbd{M-x next-file} to visit the files in the selected -tags table. The first time this command is called, it visits the -first file in the tags table. Each subsequent call visits the next -file in the table, unless a prefix argument is supplied, in which case -it returns to the first file. + @kbd{M-x tags-apropos} is like @code{apropos} for tags +(@pxref{Apropos}). It displays a list of tags in the selected tags +table whose entries match @var{regexp}. If the variable +@code{tags-apropos-verbose} is non-@code{nil}, it displays the names +of the tags files together with the tag names. You can customize the +appearance of the output by setting the variable @code{tags-tag-face} +to a face. You can display additional output by customizing the +variable @code{tags-apropos-additional-actions}; see its documentation +for details. + +@findex next-file + @kbd{M-x next-file} visits files covered by the selected tags table. +The first time it is called, it visits the first file covered by the +table. Each subsequent call visits the next covered file, unless a +prefix argument is supplied, in which case it returns to the first +file. @node EDE @section Emacs Development Environment diff --git a/doc/emacs/makefile.w32-in b/doc/emacs/makefile.w32-in index e128a50ebd3..488ccbaaf52 100644 --- a/doc/emacs/makefile.w32-in +++ b/doc/emacs/makefile.w32-in @@ -1,6 +1,6 @@ #### -*- Makefile -*- for the Emacs Manual -# Copyright (C) 2003-2011 Free Software Foundation, Inc. +# Copyright (C) 2003-2012 Free Software Foundation, Inc. # This file is part of GNU Emacs. diff --git a/doc/emacs/mark.texi b/doc/emacs/mark.texi index 7d65719e5f0..9a15f9454dd 100644 --- a/doc/emacs/mark.texi +++ b/doc/emacs/mark.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Mark, Killing, Help, Top diff --git a/doc/emacs/mini.texi b/doc/emacs/mini.texi index bbe42551345..b7c63171c56 100644 --- a/doc/emacs/mini.texi +++ b/doc/emacs/mini.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Minibuffer, M-x, Basic, Top diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi index 714e7f3441c..69e141efb0f 100644 --- a/doc/emacs/misc.texi +++ b/doc/emacs/misc.texi @@ -1,12 +1,12 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c 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: viewing ``document files'', reading netnews, running shell +else: viewing ``document files'', reading Usenet news, 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, @@ -23,12 +23,13 @@ various diversions and amusements. @node Gnus @section Gnus @cindex Gnus -@cindex reading netnews +@cindex Usenet news +@cindex newsreader -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. + 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---email, 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 @@ -37,198 +38,216 @@ For full details on Gnus, type @kbd{C-h i} 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. +* Gnus Group Buffer:: A short description of Gnus group commands. +* Gnus Summary Buffer:: A short description of Gnus summary 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. + Gnus uses several buffers to display information and to receive +commands. The three most commonly-used Gnus buffers are the +@dfn{group buffer}, the @dfn{summary buffer} and the @dfn{article +buffer}. + + The @dfn{group buffer} contains a list of article sources (e.g.@: +newsgroups and email inboxes), which are collectively referred to as +@dfn{groups}. This is the first buffer Gnus displays when it starts +up. It normally displays only the groups to which you subscribe and +that contain unread articles. From this buffer, you can select a +group to read. + + The @dfn{summary buffer} lists the articles in a single group, +showing one article per line. By default, it displays each article's +author, subject, and line +@iftex +number. +@end iftex +@ifnottex +number, but this is customizable; @xref{Summary Buffer Format,,, gnus, +The Gnus Manual}. +@end ifnottex +The summary buffer is created when you select a group in the group +buffer, and is killed when you exit the group. + + From the summary buffer, you can choose an article to view. The +article is displayed in the @dfn{article buffer}. In normal Gnus +usage, you view this buffer but do not select it---all useful Gnus +commands can be invoked from the summary buffer. But you can select +the article buffer, and execute Gnus commands from it, if you wish. @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. +@findex gnus +@cindex @file{.newsrc} file + If your system has been set up for reading Usenet news, getting +started with Gnus is easy---just type @kbd{M-x gnus}. + + On starting up, Gnus reads your @dfn{news initialization file}: a +file named @file{.newsrc} in your home directory which lists your +Usenet newsgroups and subscriptions (this file is not unique to Gnus; +it is used by many other newsreader programs). It then tries to +contact the system's default news server, which is typically specified +by the @samp{NNTPSERVER} environment variable. + + If your system does not have a default news server, or if you wish +to use Gnus for reading email, then before invoking @kbd{M-x gnus} you +need to tell Gnus where to get news and/or mail. To do this, +customize the variables @code{gnus-select-method} and/or +@code{gnus-secondary-select-methods}. +@iftex +See the Gnus manual for details. +@end iftex +@ifnottex +@xref{Finding the News,,, gnus, The Gnus Manual}. +@end ifnottex -@node Summary of Gnus -@subsection Summary of Gnus Commands + Once Gnus has started up, it displays the group buffer. By default, +the group buffer shows only a small number of @dfn{subscribed groups}. +Groups with other statuses---@dfn{unsubscribed}, @dfn{killed}, or +@dfn{zombie}---are hidden. The first time you start Gnus, any group +to which you are not subscribed is made into a killed group; any group +that subsequently appears on the news server becomes a zombie group. -Reading news is a two-step process: + To proceed, you must select a group in the group buffer to open the +summary buffer for that group; then, select an article in the summary +buffer to view its article buffer in a separate window. The following +sections explain how to use the group and summary buffers to do this. -@enumerate -@item -Choose a group in the group buffer. + To quit Gnus, type @kbd{q} in the group buffer. This automatically +records your group statuses in the files @file{.newsrc} and +@file{.newsrc.eld}, so that they take effect in subsequent Gnus +sessions. -@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 +@node Gnus Group Buffer +@subsection Using the Gnus Group Buffer - 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: + The following commands are available in the Gnus group buffer: @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. +@kindex SPC @r{(Gnus Group mode)} +@findex gnus-group-read-group +@item @key{SPC} +Switch to the summary buffer for the group on the current line. -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)} +@kindex A s @r{(Gnus Group mode)} +@findex gnus-group-list-groups +@item l +@itemx A s +In the group buffer, list only the groups to which you subscribe and +which contain unread articles (this is the default listing). @kindex L @r{(Gnus Group mode)} +@kindex A u @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! +@itemx A u +List all subscribed and unsubscribed groups, but not killed or zombie +groups. -@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 A k @r{(Gnus Group mode)} +@findex gnus-group-list-all-groups +@item A k +List killed groups. + +@kindex A z @r{(Gnus Group mode)} +@findex gnus-group-list-all-groups +@item A z +List zombie groups. @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. +Toggle the subscription status of the group on the current line +(i.e.@: turn a subscribed group into an unsubscribed group, or vice +versa). Invoking this on a killed or zombie group turns it into an +unsubscribed group. -@kindex C-k @r{(Gnus)} +@kindex C-k @r{(Gnus Group mode)} @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. +Kill the group on the current line. Killed groups are not recorded in +the @file{.newsrc} file, and they are not shown in the @kbd{l} or +@kbd{L} listings. -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 DEL @r{(Gnus Group mode)} +@item @key{DEL} +Move point to the previous group containing unread articles. -@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. +@kindex n @r{(Gnus Group mode)} +@findex gnus-group-next-unread-group +@findex gnus-summary-next-unread-article +@item n +Move point to the next unread group. -@need 1000 -In the summary buffer, +@kindex p @r{(Gnus Group mode)} +@findex gnus-group-prev-unread-group +@findex gnus-summary-prev-unread-article +@item p +Move point to the previous unread group. -@itemize @bullet -@item -Select the article on the line under the cursor if none is selected. +@kindex q @r{(Gnus Group mode)} +@findex gnus-group-exit +@item q +Update your Gnus settings, and quit Gnus. +@end table -@item -Scroll the text of the selected article (if there is one). +@node Gnus Summary Buffer +@subsection Using the Gnus Summary Buffer -@item -Select the next unread article if at the end of the current article. -@end itemize + The following commands are available in the Gnus summary buffer: -Thus, you can move through all the articles by repeatedly typing @key{SPC}. +@table @kbd +@kindex SPC @r{(Gnus Summary mode)} +@findex gnus-group-read-group +@item @key{SPC} +If there is no article selected, select the article on the current +line and display its article buffer. Otherwise, try scrolling the +selected article buffer in its window; on reaching the end of the +buffer, select the next unread article. -@kindex DEL @r{(Gnus)} -@item @key{DEL} -In the group buffer, move point to the previous group containing -unread articles. +Thus, you can read through all articles by repeatedly typing +@key{SPC}. +@kindex DEL @r{(Gnus Summary mode)} @findex gnus-summary-prev-page -In the summary buffer, scroll the text of the article backwards. +@item @key{DEL} +Scroll the text of the article backwards. -@kindex n @r{(Gnus)} +@kindex n @r{(Gnus Summary mode)} @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. +Select the next unread article. -@kindex p @r{(Gnus)} +@kindex p @r{(Gnus Summary mode)} @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. +Select the previous unread article. @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}. +Do an incremental search on the selected article buffer, as if you +switched to the buffer and typed @kbd{C-s} (@pxref{Incremental +Search}). @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}. +Search forward for articles containing a match for @var{regexp}. +@kindex q @r{(Gnus Summary mode)} +@item q +Exit the summary buffer and return to the group buffer. @end table @node Document View @@ -244,64 +263,54 @@ for @var{regexp}. @cindex document viewer (DocView) @findex doc-view-mode -DocView mode (@code{doc-view-mode}) is a viewer for DVI, PostScript -(PS), PDF, OpenDocument, and Microsoft Office documents. It provides -features such as slicing, zooming, and searching inside documents. It -works by converting the document to a set of images using the -@command{gs} (GhostScript) command and other external tools -@footnote{@code{gs} is a hard requirement. For DVI files, -@code{dvipdf} or @code{dvipdfm} is needed. For OpenDocument and -Microsoft Office documents, the @code{unoconv} tool is needed.}, and -displaying those images. + DocView mode is a major mode for viewing DVI, PostScript (PS), PDF, +OpenDocument, and Microsoft Office documents. It provides features +such as slicing, zooming, and searching inside documents. It works by +converting the document to a set of images using the @command{gs} +(GhostScript) command and other external tools @footnote{@code{gs} is +a hard requirement. For DVI files, @code{dvipdf} or @code{dvipdfm} is +needed. For OpenDocument and Microsoft Office documents, the +@code{unoconv} tool is needed.}, and displaying those images. @findex doc-view-toggle-display @findex doc-view-toggle-display @cindex doc-view-minor-mode - When you visit a document file with the exception of PostScript -files, Emacs automatically switches to DocView mode if possible -@footnote{The needed external tools for this document type have to be -available, emacs needs to run in a graphical frame, and PNG image -support has to be compiled into emacs. If any of these requirements -is not fulfilled, DocView falls back to an appropriate mode.}. When -you visit a PostScript file, Emacs switches to PS mode, a major mode -for editing PostScript files as text; however, it also enables DocView -minor mode, so you can type @kbd{C-c C-c} to view the document with -DocView. (PDF and DVI files, unlike PostScript files, are not usually -human-editable.) In either case, repeating @kbd{C-c C-c} -(@code{doc-view-toggle-display}) toggles between DocView and the file -text. - - You can explicitly toggle DocView mode with the command @code{M-x -doc-view-mode}, and DocView minor mode with the command @code{M-x + When you visit a document file that can be displayed with DocView +mode, Emacs automatically uses DocView mode @footnote{The needed +external tools for the document type must be available, and Emacs must +be running in a graphical frame and have PNG image support. If any of +these requirements is not fulfilled, Emacs falls back to another major +mode.}. As an exception, when you visit a PostScript file, Emacs +switches to PS mode, a major mode for editing PostScript files as +text; however, it also enables DocView minor mode, so you can type +@kbd{C-c C-c} to view the document with DocView. In either DocView +mode or DocView minor mode, repeating @kbd{C-c C-c} +(@code{doc-view-toggle-display}) toggles between DocView and the +underlying file contents. + + You can explicitly enable DocView mode with the command @code{M-x +doc-view-mode}. You can toggle DocView minor mode with @code{M-x doc-view-minor-mode}. When DocView mode starts, it displays a welcome screen and begins formatting the file, page by page. It displays the first page once that has been formatted. -@findex doc-view-enlarge -@findex doc-view-shrink -@vindex doc-view-resolution - When in DocView mode, you can enlarge or shrink the document with -@kbd{+} (@code{doc-view-enlarge}) and @kbd{-} -(@code{doc-view-shrink}). To specify the default size for DocView, -set or customize the variable @code{doc-view-resolution}. - To kill the DocView buffer, type @kbd{k} (@code{doc-view-kill-proc-and-buffer}). To bury it, type @kbd{q} (@code{quit-window}). @menu -* Navigation:: Navigation inside DocView buffers. -* Searching:: Searching inside documents. -* Slicing:: Specifying which part of pages should be displayed. -* Conversion:: Influencing and triggering conversion. +* Navigation: DocView Navigation. Navigating DocView buffers. +* Searching: DocView Searching. Searching inside documents. +* Slicing: DocView Slicing. Specifying which part of a page is displayed. +* Conversion: DocView Conversion. Influencing and triggering conversion. @end menu -@node Navigation -@subsection Navigation +@node DocView Navigation +@subsection DocView Navigation -When in DocView mode, you can scroll the current page using the usual + In DocView mode, you can scroll the current page using the usual Emacs movement keys: @kbd{C-p}, @kbd{C-n}, @kbd{C-b}, @kbd{C-f}, and the arrow keys. @@ -315,6 +324,10 @@ displays the next page if you are at the end of the current page. @findex doc-view-next-page @findex doc-view-previous-page +@kindex n @r{(DocView mode)} +@kindex p @r{(DocView mode)} +@kindex C-x ] @r{(DocView mode)} +@kindex C-x [ @r{(DocView mode)} You can also display the next page by typing @kbd{n}, @key{next} or @kbd{C-x ]} (@code{doc-view-next-page}). To display the previous page, type @kbd{p}, @key{prior} or @kbd{C-x [} @@ -322,23 +335,38 @@ page, type @kbd{p}, @key{prior} or @kbd{C-x [} @findex doc-view-scroll-up-or-next-page @findex doc-view-scroll-down-or-previous-page - The @key{SPC} (@code{doc-view-scroll-up-or-next-page}) key is a -convenient way to advance through the document. It scrolls within the -current page or advances to the next. @key{DEL} moves backwards in a -similar way (@code{doc-view-scroll-down-or-previous-page}). +@kindex SPC @r{(DocView mode)} +@kindex DEL @r{(DocView mode)} + @key{SPC} (@code{doc-view-scroll-up-or-next-page}) is a convenient +way to advance through the document. It scrolls within the current +page or advances to the next. @key{DEL} moves backwards in a similar +way (@code{doc-view-scroll-down-or-previous-page}). @findex doc-view-first-page @findex doc-view-last-page @findex doc-view-goto-page +@kindex M-< @r{(DocView mode)} +@kindex M-> @r{(DocView mode)} To go to the first page, type @kbd{M-<} (@code{doc-view-first-page}); to go to the last one, type @kbd{M->} (@code{doc-view-last-page}). To jump to a page by its number, type @kbd{M-g M-g} or @kbd{M-g g} (@code{doc-view-goto-page}). -@node Searching -@subsection Searching - -While in DocView mode, you can search the file's text for a regular +@findex doc-view-enlarge +@findex doc-view-shrink +@vindex doc-view-resolution +@kindex + @r{(DocView mode)} +@kindex - @r{(DocView mode)} + You can enlarge or shrink the document with @kbd{+} +(@code{doc-view-enlarge}) and @kbd{-} (@code{doc-view-shrink}). These +commands work by reconverting the document at the new size. To +specify the default size for DocView, customize the variable +@code{doc-view-resolution}. + +@node DocView Searching +@subsection DocView Searching + + In DocView mode, you can search the file's text for a regular expression (@pxref{Regexps}). The interface for searching is inspired by @code{isearch} (@pxref{Incremental Search}). @@ -359,8 +387,8 @@ To force display of this tooltip, type @kbd{C-t} argument; i.e., @kbd{C-u C-s} for a forward search or @kbd{C-u C-r} for a backward search. -@node Slicing -@subsection Slicing +@node DocView Slicing +@subsection DocView Slicing Documents often have wide margins for printing. They are annoying when reading the document on the screen, because they use up screen @@ -388,62 +416,63 @@ select the slice. (@code{doc-view-reset-slice}). Then DocView shows the entire page including its entire margins. -@node Conversion -@subsection Conversion +@node DocView Conversion +@subsection DocView Conversion @vindex doc-view-cache-directory @findex doc-view-clear-cache -For efficiency, DocView caches the images produced by @command{gs}. + For efficiency, DocView caches the images produced by @command{gs}. The name of this directory is given by the variable @code{doc-view-cache-directory}. You can clear the cache directory by typing @code{M-x doc-view-clear-cache}. @findex doc-view-kill-proc @findex doc-view-kill-proc-and-buffer - To force a reconversion of the currently viewed document, type -@kbd{r} or @kbd{g} (@code{revert-buffer}). To kill the converter -process associated with the current buffer, type @kbd{K} + To force reconversion of the currently viewed document, type @kbd{r} +or @kbd{g} (@code{revert-buffer}). To kill the converter process +associated with the current buffer, type @kbd{K} (@code{doc-view-kill-proc}). The command @kbd{k} (@code{doc-view-kill-proc-and-buffer}) kills the converter process and the DocView buffer. - The zoom commands @kbd{+} (@code{doc-view-enlarge}) and @kbd{-} -(@code{doc-view-shrink}) need to reconvert the document at the new -size. The current page is converted first. - @node Shell @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 + Emacs has commands for passing single command lines to shell +subprocesses, and for running a shell interactively with input and +output to an Emacs buffer, and for running a shell in a terminal emulator window. @table @kbd @item M-! @var{cmd} @key{RET} -Run the shell command line @var{cmd} and display the output +Run the shell command @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; +Run the shell command @var{cmd} with region contents as input; optionally replace the region with the output (@code{shell-command-on-region}). @item M-& @var{cmd} @key{RET} -Run the shell command line @var{cmd} asynchronously, and display the -output (@code{async-shell-command}). +Run the shell command @var{cmd} asynchronously, and display the output +(@code{async-shell-command}). @item M-x shell -Run a subshell with input and output through an Emacs buffer. -You can then give commands interactively. +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. +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}. +is documented in its own manual. +@ifnottex +@xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}. +@end ifnottex +@iftex +See the Eshell Info manual, which is distributed with Emacs. +@end iftex @menu * Single Shell:: How to run one shell command and return. @@ -455,7 +484,6 @@ Eshell: The Emacs Shell}. * 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. * Serial Terminal:: Connecting to a serial port. @end menu @@ -466,53 +494,62 @@ Eshell: The Emacs Shell}. @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 +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. - - You can also type @kbd{M-&} (@code{async-shell-command}) to execute -a shell command asynchronously. This behaves exactly like calling -@code{shell-command} with @samp{&}, except that you do not need to add -the @samp{&} to the shell command line. +@samp{*Shell Command Output*}, displayed in another window (if the +output is long). + + For instance, one way to decompress a file named @file{foo.gz} 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 to @code{shell-command}, e.g.@: @kbd{M-1 M-!}, +causes it 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 form of the file +@file{foo.gz} into the current buffer. + + Provided the specified shell command does not end with @samp{&}, it +runs @dfn{synchronously}, and you must wait for it to exit before +continuing to use Emacs. To stop waiting, type @kbd{C-g} to quit; +this sends a @code{SIGINT} signal to terminate the shell command (this +is 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. + +@kindex M-& +@findex async-shell-command + A shell command that ends in @samp{&} is executed +@dfn{asynchronously}, and you can continue to use Emacs as it runs. +You can also type @kbd{M-&} (@code{async-shell-command}) to execute a +shell command asynchronously; this is exactly like calling @kbd{M-!} +with a trailing @samp{&}, except that you do not need the @samp{&}. +The output buffer for asynchronous shell commands is named +@samp{*Async Shell Command*}. Emacs inserts the output into this +buffer as it comes in, whether or not the buffer is visible in a +window. @kindex M-| @findex shell-command-on-region - @kbd{M-|} (@code{shell-command-on-region}) is like @kbd{M-!} but + @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. +command, instead of no input. With a numeric argument, it deletes the +old region and replaces it with the output from the shell command. + + For example, you can use @kbd{M-|} with the @command{gpg} program to +see what keys are in the buffer. If the buffer contains a GnuPG key, +type @kbd{C-x h M-| gpg @key{RET}} to feed the entire buffer contents +to @command{gpg}. This will output the list of keys to the +@samp{*Shell Command Output*} buffer. @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 + The above commands use the shell specified by the variable +@code{shell-file-name}. Its default value is determined by the @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 @@ -520,81 +557,65 @@ variable @env{PATH} when Emacs is started. Your init file can override either or both of these default initializations (@pxref{Init File}). - 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. + By default, error output is intermixed with the regular output in +the output buffer. But if you change the value of the variable +@code{shell-command-default-error-buffer} to a string, error output is +inserted into a buffer of that name. @node Interactive Shell -@subsection Interactive Inferior Shell +@subsection Interactive Subshell @findex shell - To run a subshell interactively, use @kbd{M-x shell}. This creates -(or reuses) a buffer named @samp{*shell*} and runs a subshell with -input coming from and output going to that buffer. That is to say, -any ``terminal output'' from the subshell goes into the buffer, -advancing point, and any ``terminal input'' for the subshell comes -from text in the buffer. To give input to the subshell, go to the end -of the buffer and type the input, terminated by @key{RET}. - - Emacs does not wait for the subshell to do anything. You can switch -windows or buffers and edit them while the shell is waiting, or while it is -running a command. Output from the subshell waits until Emacs has time to -process it; this happens whenever Emacs is waiting for keyboard input or -for time to elapse. + To run a subshell interactively, type @kbd{M-x shell}. This creates +(or reuses) a buffer named @samp{*shell*}, and runs a shell subprocess +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}. + + While the subshell is waiting or running a command, you can switch +windows or buffers and perform other editing in Emacs. Emacs inserts +the output from the subshell into the Shell buffer whenever it has +time to process it (e.g.@: while waiting for keyboard input). @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}. + In the Shell buffer, prompts are displayed with the face +@code{comint-highlight-prompt}, and submitted input lines are +displayed with the face @code{comint-highlight-input}. This makes it +easier to distinguish input lines from the shell output. +@xref{Faces}. + + To make multiple subshells, invoke @kbd{M-x shell} with a prefix +argument (e.g. @kbd{C-u M-x shell}). Then the command 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 init file -can override either or both of these default initializations. -(@pxref{Init File}). + To specify the shell file name used by @kbd{M-x shell}, customize +the variable @code{explicit-shell-file-name}. If this is @code{nil} +(the default), Emacs uses the environment variable @env{ESHELL} if it +exists. Otherwise, it usually uses the variable +@code{shell-file-name} (@pxref{Single Shell}); but if the default +directory is remote (@pxref{Remote Files}), it prompts you for the +shell file name. 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}. +@file{~/.emacs_bash}. If this file is not found, Emacs tries with +@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 @@ -603,44 +624,46 @@ also change the coding system for a running subshell by typing Coding}. @cindex @env{INSIDE_EMACS} environment variable - Emacs sets the environment variable @env{INSIDE_EMACS} in the -subshell to a comma-separated list including the Emacs version. -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. + Emacs sets the environment variable @env{INSIDE_EMACS} in the +subshell to @samp{@var{version},comint}, where @var{version} is the +Emacs version (e.g.@: @samp{24.1}). Programs can check this variable +to determine whether they are running inside an Emacs subshell. (It +also sets the @env{EMACS} environment variable to @code{t}, if that +environment variable is not already defined. However, this +environment variable is deprecated; programs that use it should switch +to using @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: + The major mode for Shell buffers is Shell mode. Many of its special +commands are bound to the @kbd{C-c} prefix, and resemble the usual +editing and job control characters present in ordinary shells, except +that you must type @kbd{C-c} first. Here is a list of Shell mode +commands: @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. +Send the current line as input to the subshell +(@code{comint-send-input}). Any shell prompt at the beginning of the +line is omitted (@pxref{Shell Prompts}). If point is at the end of +buffer, this is like submitting the command line in an ordinary +interactive shell. However, you can also invoke @key{RET} elsewhere +in the shell buffer to submit the current line as input. @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. +@findex completion-at-point +Complete the command name or file name before point in the shell +buffer (@code{completion-at-point}). This uses the usual Emacs +completion rules (@pxref{Completion}), with the completion +alternatives being file names, environment variable names, the shell +command history, and history references (@pxref{History References}). @vindex shell-completion-fignore @vindex comint-completion-fignore @@ -654,17 +677,16 @@ 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}). +Display temporarily a list of the possible completions of the file +name before point (@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. +buffer, this sends @acronym{EOF} to the subshell. Typed at any other +position in the buffer, this deletes a character as usual. @item C-c C-a @kindex C-c C-a @r{(Shell mode)} @@ -760,8 +782,8 @@ 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. +Ask the shell for its working directory, and update the Shell buffer's +default directory. @xref{Directory Tracking}. @item M-x send-invisible @key{RET} @var{text} @key{RET} @findex send-invisible @@ -830,41 +852,38 @@ 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}. +automatically figures out part of the buffer is a prompt, based on the +output of the subprocess. (Specifically, it assumes that any received +output line which doesn't end with a newline is a prompt.) + + Comint mode divides the buffer into two types of @dfn{fields}: input +fields (where user input is typed) and output fields (everywhere +else). Prompts are part of the output fields. Most Emacs motion +commands do not cross field boundaries, unless they move over multiple +lines. For instance, when point is in the input field on a shell +command line, @kbd{C-a} puts point at the beginning of the input +field, after the prompt. Internally, the fields are implemented using +the @code{field} text property (@pxref{Text Properties,,, elisp, the +Emacs Lisp Reference Manual}). + +@vindex comint-use-prompt-regexp +@vindex shell-prompt-pattern + If you change the variable @code{comint-use-prompt-regexp} to a +non-@code{nil} value, then Comint mode recognize prompts using a +regular expression (@pxref{Regexps}). In Shell mode, the regular +expression is specified by the variable @code{shell-prompt-pattern}. +The default value of @code{comint-use-prompt-regexp} is @code{nil}, +because this method for recognizing prompts is unreliable, but you may +want to set it to a non-@code{nil} value in unusual circumstances. In +that case, Emacs does not divide the Comint buffer into fields, so the +general motion commands behave as they normally do in buffers without +special text properties. However, you can use the paragraph motion +commands to conveniently navigate the buffer (@pxref{Paragraphs}); in +Shell mode, Emacs uses @code{shell-prompt-pattern} as paragraph +boundaries. @node Shell History @subsection Shell Command History @@ -921,11 +940,12 @@ 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. + 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 (@pxref{Minibuffer +History}), except that they operate within the Shell buffer rather +than the minibuffer. @kbd{M-p} fetches an earlier shell command to the end of the shell buffer. Successive use of @kbd{M-p} fetches successively earlier @@ -1052,39 +1072,40 @@ command @code{comint-magic-space}. @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. +commands given to the subshell, in order to keep the Shell buffer's +default directory (@pxref{File Names}) the same as the shell's working +directory. It recognizes these commands by examining lines of input +that you send. 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 +recognize them also, by setting the variables +@code{shell-pushd-regexp}, @code{shell-popd-regexp}, and +@code{shell-cd-regexp} to the appropriate regular expressions +(@pxref{Regexps}). For example, if @code{shell-pushd-regexp} matches +the beginning of a shell command line, that line is regarded as a +@code{pushd} command. These commands are recognized only at the +beginning of a shell command line. @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. + If Emacs gets confused about changes in the working directory of the +subshell, type @kbd{M-x dirs}. This command asks the shell for its +working directory and updates the default directory accordingly. It +works for shells that support the most common command syntax, but may +not work for unusual shells. @findex dirtrack-mode - You can also use @kbd{M-x dirtrack-mode} to enable (or disable) an -alternative method of tracking changes in the current directory. This -method relies on your shell prompt containing the full current working -directory at all times. +@cindex Dirtrack mode +@cindex mode, Dirtrack +@vindex dirtrack-list + You can also use Dirtrack mode, a buffer-local minor mode that +implements an alternative method of tracking the shell's working +directory. To use this method, your shell prompt must contain the +working directory at all times, and you must supply a regular +expression for recognizing which part of the prompt contains the +working directory; see the documentation of the variable +@code{dirtrack-list} for details. To use Dirtrack mode, type @kbd{M-x +dirtrack-mode} in the Shell buffer, or add @code{dirtrack-mode} to +@code{shell-mode-hook} (@pxref{Hooks}). @node Shell Options @subsection Shell Mode Options @@ -1161,10 +1182,10 @@ 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}. +line mode, Term basically acts like Shell mode (@pxref{Shell Mode}). - In char mode, each character is sent directly to the inferior -subshell, as ``terminal input.'' Any ``echoing'' of your input is the + In char mode, each character is sent directly to the 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, @@ -1180,8 +1201,8 @@ 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. - You can use Term mode to communicate with a device connected to a -serial port of your computer. @xref{Serial Terminal}. + You can also Term mode to communicate with a device connected to a +serial port. @xref{Serial Terminal}. The file name used to load the subshell is determined the same way as for Shell mode. To make multiple terminal emulators, rename the @@ -1199,22 +1220,24 @@ and later. @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}. +line mode, Term basically acts like Shell mode (@pxref{Shell Mode}). +In char mode, each character is sent directly to the 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 +@findex term-line-mode @item C-c C-j -Switch to line mode. Do nothing if already in line mode. +Switch to line mode (@code{term-line-mode}). Do nothing if already in +line mode. @kindex C-c C-k @r{(Term mode)} -@findex term-line-mode +@findex term-char-mode @item C-c C-k -Switch to char mode. Do nothing if already in char mode. +Switch to char mode (@code{term-char-mode}). Do nothing if already in +char mode. @end table The following commands are only available in char mode: @@ -1229,28 +1252,23 @@ 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. +@cindex paging in Term mode + 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}. +and char modes. When the feature is enabled, the mode-line displays +the word @samp{page}, and each time Term receives more than a +screenful of output, it pauses and displays @samp{**MORE**} in the +mode-line. Type @key{SPC} to display the next screenful of output, or +@kbd{?} to see your other options. The interface is similar to the +@code{more} program. @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 @@ -1273,71 +1291,8 @@ happens automatically; there is no special password processing.) 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 +login command, without a separating comma.) Terminal types +@samp{ansi} or @samp{vt100} will work on most systems. @node Serial Terminal @subsection Serial Terminal @@ -1345,9 +1300,10 @@ off directory tracking. @findex serial-term If you have a device connected to a serial port of your computer, -you can use Emacs to communicate with it. @kbd{M-x serial-term} will -ask you for a serial port name and speed and will then open a new -window in @ref{Term Mode}. +you can communicate with it by typing @kbd{M-x serial-term}. This +command asks for a serial port name and speed, and switches to a new +Term mode buffer. Emacs communicates with the serial device through +this buffer just like it does with a terminal in ordinary Term mode. The speed of the serial port is measured in bits per second. The most common speed is 9600 bits per second. You can change the speed @@ -1358,10 +1314,6 @@ the mode line. By default, a serial port is configured as ``8N1'', which means that each byte consists of 8 data bits, No parity check bit, and 1 stopbit. - When you have opened the serial port connection, you will see output -from the device in the window. Also, what you type in the window is -sent to the device. - If the speed or the configuration is wrong, you cannot communicate with your device and will probably only see garbage output in the window. @@ -1373,12 +1325,14 @@ window. @cindex server, using Emacs as @cindex @env{EDITOR} environment variable - Various programs such as @command{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 way, by starting a new Emacs process. This is + Various programs can invoke your choice of editor to edit a +particular piece of text. For instance, version control programs +invoke an editor to enter version control logs (@pxref{Version +Control}), and the Unix @command{mail} utility invokes an editor to +enter a message to send. By convention, your choice of editor is +specified by the environment variable @env{EDITOR}. If you set +@env{EDITOR} to @samp{emacs}, Emacs would be invoked, but in an +inconvenient way---by starting a new Emacs process. This is inconvenient because the new Emacs process doesn't share buffers, a command history, or other kinds of information with any existing Emacs process. @@ -1387,30 +1341,33 @@ process. server}, so that it ``listens'' for external edit requests and acts accordingly. There are two ways to start an Emacs server: +@itemize @findex server-start - The first is to run the command @code{server-start} in an existing -Emacs process: either type @kbd{M-x server-start}, or put the -expression @code{(server-start)} in your initialization file -(@pxref{Init File}). The existing Emacs process is the server; when -you exit Emacs, the server dies with the Emacs process. +@item +Run the command @code{server-start} in an existing Emacs process: +either type @kbd{M-x server-start}, or put the expression +@code{(server-start)} in your init file (@pxref{Init File}). The +existing Emacs process is the server; when you exit Emacs, the server +dies with the Emacs process. @cindex daemon, Emacs - The second way to start an Emacs server is to run Emacs as a -@dfn{daemon}, using the @samp{--daemon} command-line option. -@xref{Initial Options}. When Emacs is started this way, it calls -@code{server-start} after initialization, and returns control to the -calling terminal instead of opening an initial frame; it then waits in -the background, listening for edit requests. +@item +Run Emacs as a @dfn{daemon}, using the @samp{--daemon} command-line +option. @xref{Initial Options}. When Emacs is started this way, it +calls @code{server-start} after initialization, and returns control to +the calling terminal instead of opening an initial frame; it then +waits in the background, listening for edit requests. +@end itemize @cindex @env{TEXEDIT} environment variable - Once an Emacs server is set up, you can use a shell command called -@command{emacsclient} to connect to the existing Emacs process and -tell it to visit a file. If you set the @env{EDITOR} environment -variable to @samp{emacsclient}, programs such as @command{mail} will -use the existing Emacs process for editing.@footnote{Some programs use -a different environment variable; for example, to make @TeX{} use -@samp{emacsclient}, set the @env{TEXEDIT} environment variable to -@samp{emacsclient +%d %s}.} + Either way, once an Emacs server is started, you can use a shell +command called @command{emacsclient} to connect to the Emacs process +and tell it to visit a file. You can then set the @env{EDITOR} +environment variable to @samp{emacsclient}, so that external programs +will use the existing Emacs process for editing.@footnote{Some +programs use a different environment variable; for example, to make +@TeX{} use @samp{emacsclient}, set the @env{TEXEDIT} environment +variable to @samp{emacsclient +%d %s}.} @vindex server-name You can run multiple Emacs servers on the same machine by giving @@ -1421,13 +1378,13 @@ server-name @key{RET} foo @key{RET}} sets the server name to name, using the @samp{-s} option (@pxref{emacsclient Options}). @findex server-eval-at - If you have defined a server by a unique server name, you can -connect to this server from other Emacs instances and evaluate forms -on it by using the @code{server-eval-at} function. - -@code{(server-eval-at "foo" '(+ 1 2))} gives the result @code{3}, if -there's a server with that name that is listening. If not, an error -will be signaled. + If you have defined a server by a unique server name, it is possible +to connect to the server from another Emacs instance and evaluate Lisp +expressions on the server, using the @code{server-eval-at} function. +For instance, @code{(server-eval-at "foo" '(+ 1 2))} evaluates the +expression @code{(+ 1 2)} on the @samp{foo} server, and returns +@code{3}. (If there is no server with that name, an error is +signaled.) Currently, this feature is mainly useful for developers. @menu * Invoking emacsclient:: Connecting to the Emacs server. @@ -1541,14 +1498,14 @@ precedence. @item -c Create a new graphical frame, instead of using an existing Emacs -frame. Emacs 23 can create a graphical frame even if it was started -in a text-only terminal, provided it is able to connect to a graphical +frame. Emacs can create a graphical frame even if it was started in a +text-only terminal, provided it is able to connect to a graphical display. If no graphical display is available, Emacs creates a new text-only terminal frame (@pxref{Frames}). If you omit a filename argument while supplying the @samp{-c} option, the new frame displays the @samp{*scratch*} buffer (@pxref{Buffers}). -@item -F +@item -F @var{alist} @itemx --frame-parameters=@var{alist} Set the parameters for a newly-created graphical frame (@pxref{Frame Parameters}). @@ -1629,7 +1586,7 @@ server it finds. (This option is not supported on MS-Windows.) @itemx --tty @itemx -nw Create a new Emacs frame on the current text-only terminal, instead of -using an existing Emacs frame. Emacs 23 can open a text-only terminal +using an existing Emacs frame. Emacs can open a text-only terminal even if it was started in another text-only terminal, or on a graphical display. If you omit a filename argument while supplying this option, the new frame displays the @samp{*scratch*} buffer. @@ -1653,23 +1610,23 @@ process, type @kbd{M-x kill-emacs}. @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. + Emacs provides commands for printing hardcopies of either an entire +buffer or part of one. You can invoke the printing commands directly, +as detailed below, or using the @samp{File} menu on the menu bar. @findex htmlfontify-buffer Aside from the commands described in this section, you can also -``print'' an Emacs buffer to HTML with @kbd{M-x htmlfontify-buffer}. -This command converts the current buffer to a HTML file, replacing -Emacs faces with CSS-based markup. In addition, see the hardcopy -commands of Dired (@pxref{Misc File Ops}) and the diary -(@pxref{Displaying the Diary}). +print hardcopies from Dired (@pxref{Operating on Files}) and the diary +(@pxref{Displaying the Diary}). You can also ``print'' an Emacs +buffer to HTML with the command @kbd{M-x htmlfontify-buffer}, which +converts the current buffer to a HTML file, replacing Emacs faces with +CSS-based markup. Furthermore, Org mode allows you to ``print'' Org +files to a variety of formats, such as PDF (@pxref{Org Mode}). @table @kbd @item M-x print-buffer -Print hardcopy of current buffer with page headings containing the file -name and page number. +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 @@ -1683,33 +1640,32 @@ Like @code{lpr-buffer} but print only the current 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 lpr-commands + On most operating system, the above hardcopy commands submit files +for printing by calling the @command{lpr} program. To change the +printer program, customize the variable @code{lpr-command}. To +specify extra switches to give the printer program, customize the list +variable @code{lpr-switches}. Its value should be a list of option +strings, each of which should start with @samp{-} (e.g.@: the option +string @code{"-w80"} specifies a line width of 80 columns). The +default is the empty list, @code{nil}. @vindex printer-name - You can specify the printer to use by setting the variable -@code{printer-name}. +@vindex lpr-printer-switch + To specify the printer to use, set the variable @code{printer-name}. +The default, @code{nil}, specifies the default printer. If you set it +to a printer name (a string), that name is passed to @command{lpr} +with the @samp{-P} switch; if you are not using @command{lpr}, you +should specify the switch with @code{lpr-printer-switch}. @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}. + 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 @command{lpr}) to the printer program: +@code{nil} means don't add them (this should be the value if your +printer program is not compatible with @command{lpr}). @menu * PostScript:: Printing buffers or regions as PostScript. @@ -1752,28 +1708,17 @@ Generate/print PostScript for the current buffer as if handwritten. @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. The @samp{-with-faces} commands only -work if they are used in a window system, so it has a way to determine color -values. + The @code{ps-print-buffer} and @code{ps-print-region} commands print +buffer contents in PostScript form. One command prints the entire +buffer; the other, just the region. The commands +@code{ps-print-buffer-with-faces} and +@code{ps-print-region-with-faces} behave similarly, but use PostScript +features to show the faces (fonts and colors) of the buffer text. Interactively, when you use a prefix argument (@kbd{C-u}), the command prompts the user for a file name, and saves the PostScript image in that file instead of sending it to the printer. - Noninteractively, the argument @var{filename} is treated as follows: if it is -@code{nil}, send the image to the printer. If @var{filename} is a string, save -the PostScript image in a file with that name. - - 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 @@ -1782,31 +1727,21 @@ buffer, and using @code{ps-print-buffer-with-faces}. generate the PostScript output in an Emacs buffer instead of sending it to the printer. - Use the command @code{ps-despool} to send the spooled images to the printer. - @findex ps-despool - This command sends the PostScript generated by @samp{-spool-} commands (see -commands above) to the printer. - - Interactively, when you use a prefix argument (@kbd{C-u}), the command -prompts the user for a file name, and saves the spooled PostScript image in -that file instead of sending it to the printer. - - Noninteractively, the argument @var{filename} is treated as follows: if it is -@code{nil}, send the image to the printer. If @var{filename} is a string, save -the PostScript image in a file with that name. + Use the command @code{ps-despool} to send the spooled images to the +printer. This command sends the PostScript generated by +@samp{-spool-} commands (see commands above) to the printer. With a +prefix argument (@kbd{C-u}), it prompts for a file name, and saves the +spooled PostScript image in that file instead of sending it to the +printer. @findex handwrite @cindex handwriting -@kbd{M-x handwrite} is more frivolous. It generates a PostScript + @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 @subsection Variables for PostScript Hardcopy @@ -2355,26 +2290,8 @@ key bindings. @node Hyperlinking, Amusements, 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. + The following subsections describe convenience features for handling +URLs and other types of links occurring in Emacs buffer text. @menu * Browse-URL:: Following URLs. @@ -2397,31 +2314,31 @@ fashion. 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 Browse-URL package allows you to easily follow URLs from within +Emacs. Most URLs are followed by invoking a web browser; +@samp{mailto:} URLs are followed by invoking the @code{compose-mail} +Emacs command to send mail to the specified address (@pxref{Sending +Mail}). - 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}. + The command @kbd{M-x browse-url} prompts for a URL, and follows it. +If point is located near a plausible URL, that URL is offered as the +default. The Browse-URL package also provides other commands which +you might like to bind to keys, such as @code{browse-url-at-point} and +@code{browse-url-at-mouse}. +@vindex browse-url-mailto-function @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. +@code{browse-url} Customize group. In particular, the option +@code{browse-url-mailto-function} lets you define how to follow +@samp{mailto:} URLs, while @code{browse-url-browser-function} lets you +define how to follow other types of URLs. For more information, view +the package commentary by typing @kbd{C-h P browse-url @key{RET}}. @node Goto Address mode @subsection Activating URLs @findex goto-address-mode +@cindex mode, Goto Address @cindex Goto Address mode @cindex URLs, activating @@ -2430,20 +2347,23 @@ affect all browsing in Emacs. 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-mode}. This minor mode finds all the URLs in the buffer, -highlights them, and turns them into @dfn{buttons}: if you click on a -URL with @kbd{Mouse-1} or @kbd{Mouse-2} (@pxref{Mouse References}), or -move to the URL and type @kbd{C-c @key{RET}}, that displays 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}). +@kindex C-c RET @r{(Goto Address mode)} +@findex goto-address-at-point + You can make Emacs mark out URLs specially in the current buffer, by +typing @kbd{M-x goto-address-mode}. When this buffer-local minor mode +is enabled, it finds all the URLs in the buffer, highlights them, and +turns them into clickable buttons. You can follow the URL by typing +@kbd{C-c @key{RET}} (@code{goto-address-at-point}) while point is on +its text; or by clicking with @kbd{Mouse-2}, or by clicking +@kbd{Mouse-1} quickly (@pxref{Mouse References}). Following a URL is +done by calling @code{browse-url} as a subroutine +(@pxref{Browse-URL}). It can be useful to add @code{goto-address-mode} to mode hooks and -the hooks used to display an incoming message (e.g., -@code{rmail-show-message-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. +hooks for displaying an incoming message +(e.g.@: @code{rmail-show-message-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 @@ -2454,24 +2374,24 @@ of its own. @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. + The FFAP package replaces certain key bindings for finding files, +such as @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 (@pxref{Browse-URL}). 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. +buffers, @file{README} files, @file{MANIFEST} files, and so on. For +more information, view the package commentary by typing @kbd{C-h P +ffap @key{RET}}. @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. + To enable FFAP, type @kbd{M-x ffap-bindings}. This makes the +following key bindings, and also installs hooks for additional FFAP +functionality in Rmail, Gnus and VM article buffers. @table @kbd @item C-x C-f @var{filename} @key{RET} @@ -2580,18 +2500,22 @@ bored, try an argument of 9. Sit back and watch. @cindex Life @kbd{M-x life} runs Conway's ``Life'' cellular automaton. -@findex lm +@findex landmark @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. + @kbd{M-x landmark} 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 morse-region @findex unmorse-region +@findex nato-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. + @kbd{M-x morse-region} converts the text in the region to Morse +code; @kbd{M-x unmorse-region} converts it back. @kbd{M-x +nato-region} converts the text in the region to NATO phonetic +alphabet; @kbd{M-x denato-region} converts it back. @findex pong @cindex Pong game @@ -2611,9 +2535,11 @@ across other pegs. The command @kbd{M-x zone} plays games with the display when Emacs is idle. - Finally, if you find yourself frustrated, try the famous Eliza -program. Just do @kbd{M-x doctor}. End each input by typing -@key{RET} twice. +@findex doctor +@cindex Eliza + Finally, if you find yourself frustrated, try describing your +problems to the famous psychotherapist Eliza. Just do @kbd{M-x +doctor}. End each input by typing @key{RET} twice. @ifnottex @lowersections diff --git a/doc/emacs/modes.texi b/doc/emacs/modes.texi index 4d574242c8d..52ecd37fcf2 100644 --- a/doc/emacs/modes.texi +++ b/doc/emacs/modes.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Modes, Indentation, International, Top @@ -96,7 +96,7 @@ the rules of the language (@pxref{Indentation}). The keys that are commonly changed are @key{TAB}, @key{DEL}, and @kbd{C-j}. Many modes also define special commands of their own, usually bound in the prefix key @kbd{C-c}. Major modes can also alter user options and variables; -for instance, programming language modes typicaly set a buffer-local +for instance, programming language modes typically set a buffer-local value for the variable @code{comment-start}, which determines how source code comments are delimited (@pxref{Comments}). diff --git a/doc/emacs/msdog-xtra.texi b/doc/emacs/msdog-xtra.texi index 095a0cdacbf..dc50b3d248f 100644 --- a/doc/emacs/msdog-xtra.texi +++ b/doc/emacs/msdog-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2011 Free Software Foundation, Inc. +@c Copyright (C) 2004-2012 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 diff --git a/doc/emacs/msdog.texi b/doc/emacs/msdog.texi index 547d8cbadd9..d31906d9b04 100644 --- a/doc/emacs/msdog.texi +++ b/doc/emacs/msdog.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Microsoft Windows, Manifesto, Mac OS / GNUstep, Top diff --git a/doc/emacs/mule.texi b/doc/emacs/mule.texi index f676f0b96ce..aebff1e463a 100644 --- a/doc/emacs/mule.texi +++ b/doc/emacs/mule.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1997, 1999-2011 Free Software Foundation, Inc. +@c Copyright (C) 1997, 1999-2012 Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node International, Modes, Frames, Top @chapter International Character Set Support diff --git a/doc/emacs/package.texi b/doc/emacs/package.texi index b342cbbf18c..7e2aa20d52e 100644 --- a/doc/emacs/package.texi +++ b/doc/emacs/package.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Packages @@ -20,7 +20,7 @@ via this buffer. @xref{Package Menu}. @findex describe-package The command @kbd{C-h P} (@code{describe-package}) prompts for the -name of a package, and displays a help buffer describing that +name of a package, and displays a help buffer describing the attributes of the package and the features that it implements. By default, Emacs downloads packages from a @dfn{package archive} @@ -119,9 +119,9 @@ dependencies; also, delete all packages marked with @kbd{d} (@code{package-menu-execute}). This also removes the marks. @item r -Refresh the package list (@code{package-menu-refresh}). This also -retrieves the list of available packages from the package archive -again. +Refresh the package list (@code{package-menu-refresh}). This fetches +the list of available packages from the package archive again, and +recomputes the package list. @end table @noindent diff --git a/doc/emacs/picture-xtra.texi b/doc/emacs/picture-xtra.texi index 43a2dbc4704..629baaf9c52 100644 --- a/doc/emacs/picture-xtra.texi +++ b/doc/emacs/picture-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2011 Free Software Foundation, Inc. +@c Copyright (C) 2004-2012 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 diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi index bb62ad67b2a..7fef7fb1e22 100644 --- a/doc/emacs/programs.texi +++ b/doc/emacs/programs.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Programs, Building, Text, Top @@ -38,8 +38,8 @@ Highlight program syntax (@pxref{Font Lock}). * Glasses:: Making identifiersLikeThis more readable. * Semantic:: Suite of editing tools based on source code parsing. * Misc for Programs:: Other Emacs features useful for editing programs. -* C Modes:: Special commands of C, C++, Objective-C, - Java, and Pike modes. +* C Modes:: Special commands of C, C++, Objective-C, Java, + IDL, Pike and AWK modes. * Asm Mode:: Asm mode and its special features. @ifnottex * Fortran:: Fortran mode and its special features. @@ -606,6 +606,14 @@ 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. +@findex c-guess +@findex c-guess-install + As an alternative to specifying a style, you can tell Emacs to guess +a style by typing @kbd{M-x c-guess} in a sample code buffer. You can +then apply the guessed style to other buffers with @kbd{M-x +c-guess-install}. @xref{Guessing the Style,,, ccmode, the CC Mode +Manual}, for details. + @node Parentheses @section Commands for Editing with Parentheses @@ -1283,18 +1291,18 @@ for switching graphical windows, so you should type @kbd{C-M-i} or @kbd{@key{ESC} @key{TAB}} instead. @cindex tags-based completion - In-buffer symbol completion generates its completion list in a -number of different ways. If Semantic mode is enabled, Emacs tries to -use the Semantic parser data for completion (@pxref{Semantic}). If -Semantic mode is not enabled or it fails at performing completion, -Emacs normally tries to complete using a tags table (@pxref{Tags}). - +@findex completion-at-point @cindex Lisp symbol completion @cindex completion (Lisp symbols) - In Emacs Lisp mode, completion is performed using the function, -variable, and property names defined in the current Emacs session. If -there is an open parenthesis immediately before the beginning of the -partial symbol, only symbols with function definitions are considered. + In most programming language modes, @kbd{C-M-i} (or +@kbd{M-@key{TAB}}) invokes the command @code{completion-at-point}, +which generates its completion list in a flexible way. If Semantic +mode is enabled, it tries to use the Semantic parser data for +completion (@pxref{Semantic}). If Semantic mode is not enabled or +fails at performing completion, it tries to complete using the +selected tags table (@pxref{Tags}). If in Emacs Lisp mode, it +performs completion using the function, variable, or property names +defined in the current Emacs session. In all other respects, in-buffer symbol completion behaves like minibuffer completion. For instance, if Emacs cannot complete to a @@ -1462,17 +1470,17 @@ with Emacs. related modes. @table @code -@item M-x c-beginning-of-defun -@itemx M-x c-end-of-defun +@item C-M-a +@itemx C-M-e @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 +top-level definition. In languages with enclosing scopes (such as +C++'s classes) the @dfn{current function} is the immediate one, +possibly inside a scope. Otherwise it is the one defined by 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}. +@code{end-of-defun} search for braces in column zero.) @xref{Moving +by Defuns}. @item C-c C-u @kindex C-c C-u @r{(C mode)} diff --git a/doc/emacs/regs.texi b/doc/emacs/regs.texi index f7fd52bd28d..d02ddd64b49 100644 --- a/doc/emacs/regs.texi +++ b/doc/emacs/regs.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Registers, Display, Killing, Top diff --git a/doc/emacs/rmail.texi b/doc/emacs/rmail.texi index d05af468fa1..9713b825ee8 100644 --- a/doc/emacs/rmail.texi +++ b/doc/emacs/rmail.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Rmail diff --git a/doc/emacs/screen.texi b/doc/emacs/screen.texi index fcc31e30988..fe3222e198f 100644 --- a/doc/emacs/screen.texi +++ b/doc/emacs/screen.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Screen, User Input, Acknowledgments, Top diff --git a/doc/emacs/search.texi b/doc/emacs/search.texi index c6747042df5..877e291ff36 100644 --- a/doc/emacs/search.texi +++ b/doc/emacs/search.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Search, Fixit, Display, Top diff --git a/doc/emacs/sending.texi b/doc/emacs/sending.texi index 50ec852d740..6f154ce2af6 100644 --- a/doc/emacs/sending.texi +++ b/doc/emacs/sending.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Sending Mail @@ -11,10 +11,10 @@ @kindex C-x m @findex compose-mail - To send an @dfn{e-mail} message in Emacs, type @kbd{C-x m}. This -selects and initializes a buffer named @samp{*mail*}, where you can -edit the text and headers of the message. Finally, type @kbd{C-c C-s} -or @kbd{C-c C-c} to send the message. + To send an email message from Emacs, type @kbd{C-x m}. This +switches to a buffer named @samp{*unsent mail*}, where you can edit +the text and headers of the message. When done, type @kbd{C-c C-s} or +@kbd{C-c C-c} to send it. @table @kbd @item C-x m @@ -30,37 +30,28 @@ In the mail buffer, send the message and bury the buffer (@code{message-send-and-exit}). @end table + The mail buffer is an ordinary Emacs buffer, so you can switch to +other buffers while composing the mail. If you want to send another +mail before finishing the current one, type @kbd{C-x m} again to open +a new mail buffer whose name has a different numeric suffix +(@pxref{Misc Buffer}). If you invoke the command with a prefix +argument, @w{@kbd{C-u C-x m}}, Emacs switches back to the last mail +buffer, and asks if you want to erase the message in that buffer; if +you answer no, this lets you pick up editing the message where you +left off. + @kindex C-x 4 m @findex compose-mail-other-window @kindex C-x 5 m @findex compose-mail-other-frame -@noindent -The command @kbd{C-x 4 m} (@code{compose-mail-other-window}) does the -same as @kbd{C-x m}, except it displays the mail buffer in a different -window. The command @kbd{C-x 5 m} (@code{compose-mail-other-frame}) -creates a new frame for the mail buffer. - - Because the mail 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 type @kbd{C-x m} again when you have -been composing another message but have not sent it, Emacs asks for -confirmation before erasing the old message. If you answer @kbd{n}, -Emacs selects the mail buffer 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 mail buffer ``unmodified,'' which -avoids the need for confirmation when @kbd{C-x m} is next used. - - If you want to send another message before finishing the current -message, use the command @kbd{M-x rename-uniquely} to rename the -current mail buffer (@pxref{Misc Buffer}). Then you can use @kbd{C-x -m} to make a new mail buffer, and work with each mail buffer -independently. - - Before using Emacs to send mail, you may need to customize the -variable @code{send-mail-function} if your system is not set up to -deliver mail directly via SMTP (@pxref{Mail Sending}). In addition, -you may need to customize @code{user-mail-address} if the system -cannot receive mail via SMTP (@pxref{Mail Headers}). + The command @kbd{C-x 4 m} (@code{compose-mail-other-window}) does +the same as @kbd{C-x m}, except it displays the mail buffer in a +different window. The command @kbd{C-x 5 m} +(@code{compose-mail-other-frame}) does it in a new frame. + + When you type @kbd{C-c C-c} or @kbd{C-c C-s} to send the mail, Emacs +may ask you how it should deliver the mail---either directly via SMTP, +or using some other method. @xref{Mail Sending}, for details. @menu * Format: Mail Format. Format of a mail message. @@ -75,77 +66,91 @@ cannot receive mail via SMTP (@pxref{Mail Headers}). @node Mail Format @section The Format of the Mail Buffer - An email message must contain certain pieces of information, called -@dfn{headers}, which specify the message's sender, recipient(s), and -so on. - - At the top of the mail buffer is a set of @dfn{header fields}, where -you can enter this information. You can insert and edit header fields -using ordinary editing commands. @xref{Header Editing}, for commands -specific to editing header fields. - - Some header fields are automatically pre-initialized in the buffer, -when appropriate; other headers, such as @samp{Date} and -@samp{Message-Id}, are normally omitted from the mail buffer and -created automatically when the message is sent. - -@vindex mail-header-separator - The line in the buffer that says - -@smallexample ---text follows this line-- -@end smallexample - -@noindent -separates the header fields from the @dfn{body} (or @dfn{text}) of the -message. Everything above this line is treated as part of the -headers; everything below it is treated as the body. 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. + Here is an example of the contents of a mail buffer: @example -To: gnu@@example.org -CC: lungfish@@example.com, byob@@example.net -Subject: The Emacs Manual +To: subotai@@example.org +CC: mongol.soldier@@example.net, rms@@gnu.org +Subject: Re: What is best in life? +From: conan@@example.org --text follows this line-- -Please ignore this message. +To crush your enemies, see them driven before you, and to hear the +lamentation of their women. @end example +@noindent +At the top of the mail buffer is a set of @dfn{header fields}, which +are used for specifying information about the email's recipient(s), +subject, and so on. The above buffer contains header fields for +@samp{To}, @samp{Cc}, @samp{Subject}, and @samp{From}. Some header +fields are automatically pre-initialized in the mail buffer, when +appropriate. + + The line that says @samp{--text follows this line--} separates the +header fields from the @dfn{body} (or @dfn{text}) of the message. +Everything above that line is treated as part of the headers; +everything below it is treated as the body. The delimiter line itself +does not appear in the message actually sent. + + You can insert and edit header fields using ordinary editing +commands. @xref{Header Editing}, for commands specific to editing +header fields. Certain headers, such as @samp{Date} and +@samp{Message-Id}, are normally omitted from the mail buffer and are +created automatically when the message is sent. + @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. +equivalent in field names. 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 commonly-used fields. Emacs pre-initializes some of these, -depending on various options you can set. You can delete or alter any -header field before you send the message, if you wish. +people use only standard field names with accepted meanings. -@table @samp -@item From +@vindex user-full-name @vindex user-mail-address -The address of the sender (you). This should be a valid mailing -address, as replies will normally go there. Emacs initializes this -field using the variables @code{user-full-name} and -@code{user-mail-address}; see below. + The @samp{From} header field identifies the person sending the email +(i.e.@: you). This should be a valid mailing address, as replies are +normally sent there. The default contents of this header field are +computed from the variables @code{user-full-name} (which specifies +your full name) and @code{user-mail-address} (your email address). On +some operating systems, Emacs initializes these two variables using +environment variables (@pxref{General Variables}). If this +information is unavailable or wrong, you should customize the +variables yourself (@pxref{Easy Customization}). + +@vindex mail-from-style + The value of the variable @code{mail-from-style} specifies how to +format the contents of the @samp{From} field: + +@table @asis +@item @code{nil} +Use just the address, as in @samp{king@@grassland.com}. +@item @code{parens} +Use both address and full name, as in:@* +@samp{king@@grassland.com (Elvis Parsley)}. +@item @code{angles} +Use both address and full name, as in:@* +@samp{Elvis Parsley <king@@grassland.com>}. +@item any other value +Use @code{angles} normally. But if the address must be ``quoted'' to +remain syntactically valid under the @code{angles} format but not +under the @code{parens} format, use @code{parens} instead. This is +the default. +@end table + + Apart from @samp{From}, here is a table of commonly-used fields: +@table @samp @item To The mailing address(es) to which the message is addressed. To list -more than one address, use commas (not spaces) to separate them. +more than one address, use commas to separate them. @item Subject -A piece of text saying what the message is about. Most mail-reading -programs can display a summary of messages, listing the subject of -each message but not its text. +The subject of the message. @item CC Additional mailing address(es) to send the message to. This is like @@ -158,47 +163,38 @@ not appear in the header of the message actually sent. ``BCC'' stands for @dfn{blind carbon copies}. @item FCC -The name of one file, to which a copy of the sent message should be +The name of a file, to which a copy of the sent message should be appended. Emacs writes the message in mbox format, unless the file is in Babyl format (used by Rmail before Emacs 23), in which case Emacs -writes Babyl. If an Rmail buffer is visiting the file, Emacs updates -it accordingly. To specify more than one file, use several @samp{FCC} -fields, with one file name in each field. +writes in Babyl format. If an Rmail buffer is visiting the file, +Emacs updates it accordingly. To specify more than one file, use +several @samp{FCC} fields, with one file name in each field. @item Reply-to An address to which replies should be sent, instead of @samp{From}. -You can use this header if, for some reason, your @samp{From} address -is unable to receive replies. +This is used if, for some reason, your @samp{From} address cannot +receive replies. @item Mail-reply-to - This field takes precedence over @samp{Reply-to}. It is used because -some mailing lists set the @samp{Reply-to} field for their own purposes -(a somewhat controversial practice). +This field takes precedence over @samp{Reply-to}. It is used because +some mailing lists set the @samp{Reply-to} field for their own +purposes (a somewhat controversial practice). @item Mail-followup-to - This field contains one or more addresses. It is typically used when -you reply to a message from a mailing list that you are subscribed to. -It usually indicates that you want replies to go to the list, and that -you do not need an extra copy sent directly to you. - -@c Message mode handles this differently... -@c @vindex mail-mailing-lists -@c The variable @code{mail-mailing-lists} holds a list of mailing list -@c addresses that you are subscribed to. If it is non-@code{nil}, Emacs -@c inserts an appropriate @samp{Mail-followup-to} header when sending mail -@c to a mailing list. +One of more address(es) to use as default recipient(s) for follow-up +messages. This is typically used when you reply to a message from a +mailing list that you are subscribed to, and want replies to go to the +list without sending an extra copy to you. @item In-reply-to -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, you never need to think about this, because it is filled in -automatically when you reply to a message in Rmail (or any other mail -program built into Emacs). +An identifier for the message you are replying to. Most mail readers +use this information to group related messages together. Normally, +this header is filled in automatically when you reply to a message in +any mail program built into Emacs. @item References -The Message-Ids of previous related messages (a Message-Id is a unique -identifier generated when a message is sent). Like -@samp{In-reply-to}, this is normally set up automatically for you. +Identifiers for previous related messages. Like @samp{In-reply-to}, +this is normally filled in automatically for you. @end table @noindent @@ -217,35 +213,6 @@ To: foo@@example.net, this@@example.net, @end group @end example -@vindex user-full-name -@vindex user-mail-address - The default contents of the @samp{From} header field are computed -from the variables @code{user-full-name} and @code{user-mail-address}. -On some operating systems, Emacs initializes these two variables using -environment variables (@pxref{General Variables}). If this -information is unavailable or wrong, you can customize the variables -yourself (@pxref{Easy Customization}). - -@vindex mail-from-style - The value of the variable @code{mail-from-style} specifies how to -format the address in the @samp{From} field: - -@table @asis -@item @code{nil} -Use just the address, as in @samp{king@@grassland.com}. -@item @code{parens} -Use both address and full name, as in:@* -@samp{king@@grassland.com (Elvis Parsley)}. -@item @code{angles} -Use both address and full name, as in:@* -@samp{Elvis Parsley <king@@grassland.com>}. -@item any other value -Use @code{angles} for most addresses. However, if the address must be -``quoted'' to remain syntactically-valid under the @code{angles} -format but not under the @code{parens} format, use @code{parens} -instead. This is the default. -@end table - @c There is also mail-specify-envelope-from and mail-envelope-from, but @c these are probably not topics for the Emacs manual. @@ -273,13 +240,12 @@ particular message, edit them as necessary before sending the message. @vindex mail-personal-alias-file You can define @dfn{mail aliases}, which are short mnemonic names -that stand for mail addresses or groups of mail addresses. By -default, mail aliases are defined in the file @file{~/.mailrc}. You -can specify a different file name to use, by setting the variable +that stand for one or more mailing addresses. By default, mail +aliases are defined in the file @file{~/.mailrc}. You can specify a +different file name to use, by setting the variable @code{mail-personal-alias-file}. - To define an alias in @file{.mailrc}, write a line in the following -format: + To define an alias in @file{.mailrc}, write a line like this: @example alias @var{nick} @var{fulladdresses} @@ -362,11 +328,9 @@ in greater detail. @xref{Top,,Message, message, Message}. @node Mail Sending @subsection Mail Sending - There are two commands to send a message you have been editing: - @table @kbd @item C-c C-c -Send the message, and deselect the mail buffer (@code{message-send-and-exit}). +Send the message, and bury the mail buffer (@code{message-send-and-exit}). @item C-c C-s Send the message, and leave the mail buffer selected (@code{message-send}). @end table @@ -374,70 +338,75 @@ Send the message, and leave the mail buffer selected (@code{message-send}). @kindex C-c C-s @r{(Message mode)} @kindex C-c C-c @r{(Message mode)} @findex message-send - If you want to send a message and be done with it, type @kbd{C-c -C-c} (@code{mail-send-and-exit}). This sends the message and then -either deletes the window or switches to another buffer. It also +@vindex message-kill-buffer-on-exit + The usual command to send a message is @kbd{C-c C-c} +(@code{mail-send-and-exit}). This sends the message and then ``buries'' the mail buffer, putting it at the lowest priority for -reselection. This is the usual command for sending a message. +reselection. If you want it to kill the mail buffer instead, change +the variable @code{message-kill-buffer-on-exit} to @code{t}. @findex message-send-and-exit The command @kbd{C-c C-s} (@code{message-send}) sends the message -and marks the mail buffer unmodified, but leaves the buffer selected. -Use this command if you want to modify the message (perhaps with new -recipients) and send it again. +and leaves the buffer selected. Use this command if you want to +modify the message (perhaps with new recipients) and send it again. @vindex message-send-hook - Sending a message runs the hook @code{message-send-hook}. - - 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. - -@vindex sendmail-coding-system - When you send a message containing 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. + Sending a message runs the hook @code{message-send-hook}. It also +marks the mail buffer as unmodified, except if the mail buffer is also +a file-visiting buffer (in that case, only saving the file does that, +and you don't get a warning if you try to send the same message +twice). @cindex SMTP @cindex Feedmail @cindex Sendmail @cindex Mailclient @vindex send-mail-function - The variable @code{send-mail-function} controls how the default mail -user agent sends mail. Its value should be a function, which can be -one of the following: + The variable @code{send-mail-function} controls how the message is +delivered. Its value should be one of the following functions: @table @code -@item sendmail-send-it -Send mail using the system's default @command{sendmail} (or -@command{sendmail}-compatible) program. This is the default on Unix -and GNU, and works provided the system is a valid @dfn{mail host} -(that is, provided it can deliver mail via SMTP). - -@item mailclient-send-it -Pass the mail buffer on to the system's designated mail client (see -@file{mailclient.el}). This is the default on Mac OS X and -MS-Windows. +@item sendmail-query-once +Query for a delivery method (one of the other entries in this list), +and use that method for this message; then save the method to +@code{send-mail-function}, so that it is used for future deliveries. +This is the default, unless you have already set the variables for +sending mail via @code{smtpmail-send-it} (see below). @item smtpmail-send-it -Send mail through an external mail host (e.g., your Internet service -provider's SMTP server). You will need to tell Emacs how to contact -the SMTP server, by customizing the variables +Send mail using the through an external mail host, such as your +Internet service provider's outgoing SMTP mail server. If you have +not told Emacs how to contact the SMTP server, it prompts for this +information, which is saved in the variables @code{smtpmail-smtp-server} and @code{smtpmail-auth-credentials}. @xref{Top,,Emacs SMTP Library, smtpmail, Sending mail via SMTP}. +@item sendmail-send-it +Send mail using the system's default @command{sendmail} program, or +equivalent. This requires the system to be set up for delivering mail +directly via SMTP. + +@item mailclient-send-it +Pass the mail buffer on to the system's designated mail client. See +the commentary section in the file @file{mailclient.el} for details. + @item feedmail-send-it This is similar to @code{sendmail-send-it}, but allows you to queue messages for later sending. See the commentary section in the file -@file{feedmail.el} for more information. +@file{feedmail.el} for details. @end table +@vindex sendmail-coding-system + When you send a message containing 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. + @node Header Editing @subsection Mail Header Editing @@ -511,7 +480,8 @@ just inserts a tab character. @table @kbd @item C-c C-y -Yank the selected message from Rmail (@code{message-yank-original}). +Yank the selected message from the mail reader, as a citation +(@code{message-yank-original}). @item C-c C-q Fill each paragraph cited from another message (@code{message-fill-yanked-message}). @@ -522,9 +492,9 @@ Fill each paragraph cited from another message @findex message-yank-prefix You can use the command @kbd{C-c C-y} (@code{message-yank-original}) to @dfn{cite} a message that you are replying to. This inserts the -text of that message into the mail buffer. This command is active -only when the mail buffer is invoked from a mail program running in -Emacs, such as Rmail. +text of that message into the mail buffer. This command works only if +the mail buffer is invoked from a mail reader running in Emacs, such +as Rmail. By default, Emacs inserts the string @samp{>} in front of each line of the cited text; this prefix string is specified by the variable diff --git a/doc/emacs/text.texi b/doc/emacs/text.texi index c27a2c2936d..ccc546fb0a1 100644 --- a/doc/emacs/text.texi +++ b/doc/emacs/text.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Text, Programs, Indentation, Top @@ -21,7 +21,10 @@ are also often useful for editing programs. the file contains ordinary text, 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. +structure. Org mode extends Outline mode and turn Emacs into a +full-fledged organizer: you can manage TODO lists, store notes and +publish them in many formats. + @iftex @xref{Outline Mode}. @end iftex @@ -70,6 +73,7 @@ for editing such pictures. * Case:: Changing the case of text. * Text Mode:: The major modes for editing text files. * Outline Mode:: Editing outlines. +* Org Mode:: The Emacs organizer. * TeX Mode:: Editing input to the formatter TeX. * HTML Mode:: Editing HTML and SGML files. * Nroff Mode:: Editing input to the formatter nroff. @@ -1250,6 +1254,153 @@ automatically by putting this in your init file (@pxref{Init File}): (eval-after-load "outline" '(require 'foldout)) @end example +@node Org Mode +@section Org Mode +@cindex organizer +@cindex planner +@findex Org mode +@findex mode, Org + +@findex org-mode + Org mode is a variant of Outline mode for using Emacs as an +organizer and/or authoring system. Files with names ending in the +extension @file{.org} are opened in Org mode (@pxref{Choosing Modes}). +To explicitly switch to Org mode, type @kbd{M-x org-mode}. + + In Org mode, as in Outline mode, each entry has a heading line that +starts with one or more @samp{*} characters. @xref{Outline Format}. +In addition, any line that begins with the @samp{#} character is +treated as a comment. + +@kindex TAB @r{(Org Mode)} +@findex org-cycle + Org mode provides commands for easily viewing and manipulating the +outline structure. The simplest of these commands is @key{TAB} +(@code{org-cycle}). If invoked on a heading line, it cycles through +the different visibility states of the subtree: (i) showing only that +heading line, (ii) showing only the heading line and the heading lines +of its direct children, if any, and (iii) showing the entire subtree. +If invoked in a body line, the global binding for @key{TAB} is +executed. + +@kindex S-TAB @r{(Org Mode)} +@findex org-shifttab + Typing @key{S-TAB} (@code{org-shifttab}) anywhere in an Org mode +buffer cycles the visibility of the entire outline structure, between +(i) showing only top-level heading lines, (ii) showing all heading +lines but no body lines, and (iii) showing everything. + +@kindex M-<up> @r{(Org Mode)} +@kindex M-<down> @r{(Org Mode)} +@kindex M-<left> @r{(Org Mode)} +@kindex M-<right> @r{(Org Mode)} +@findex org-metaup +@findex org-metadown +@findex org-metaleft +@findex org-metaright + You can move an entire entry up or down in the buffer, including its +body lines and subtree (if any), by typing @kbd{M-<up>} +(@code{org-metaup}) or @kbd{M-<down>} (@code{org-metadown}) on the +heading line. Similarly, you can promote or demote a heading line +with @kbd{M-<left>} (@code{org-metaleft}) and @kbd{M-<left>} +(@code{org-metaright}). These commands execute their global bindings +if invoked on a body line. + + The following subsections give basic instructions for using Org mode +as an organizer and as an authoring system. @xref{Top,The Org Mode +Manual,,org, The Org Manual}, for details. + +@menu +* Org Organizer:: Managing TODO lists and agendas. +* Org Authoring:: Exporting Org buffers to various formats. +@end menu + +@node Org Organizer +@subsection Org as an organizer +@cindex TODO item +@cindex Org agenda + +@kindex C-c C-t @r{(Org Mode)} +@findex org-todo +@vindex org-todo-keywords + You can tag an Org entry as a @dfn{TODO} item by typing @kbd{C-c +C-t} (@code{org-todo}) anywhere in the entry. This adds the keyword +@samp{TODO} to the heading line. Typing @kbd{C-c C-t} again switches +the keyword to @samp{DONE}; another @kbd{C-c C-t} removes the keyword +entirely, and so forth. You can customize the keywords used by +@kbd{C-c C-t} via the variable @code{org-todo-keywords}. + +@kindex C-c C-s @r{(Org Mode)} +@kindex C-c C-d @r{(Org Mode)} +@findex org-schedule +@findex org-deadline + Apart from marking an entry as TODO, you can attach a date to it, by +typing @kbd{C-c C-s} (@code{org-schedule}) in the entry. This prompts +for a date by popping up the Emacs Calendar (@pxref{Calendar/Diary}), +and then adds the tag @samp{SCHEDULED}, together with the selected +date, beneath the heading line. The command @kbd{C-c C-d} +(@code{org-deadline}) has the same effect, except that it uses the tag +@code{DEADLINE}. + +@kindex C-c [ @r{(Org Mode)} +@findex org-agenda-file-to-front +@vindex org-agenda-files + Once you have some TODO items planned in an Org file, you can add +that file to the list of @dfn{agenda files} by typing @kbd{C-c [} +(@code{org-agenda-file-to-front}). Org mode is designed to let you +easily maintain multiple agenda files, e.g.@: for organizing different +aspects of your life. The list of agenda files is stored in the +variable @code{org-agenda-files}. + +@findex org-agenda + To view items coming from your agenda files, type @kbd{M-x +org-agenda}. This command prompts for what you want to see: a list of +things to do this week, a list of TODO items with specific keywords, +etc. +@ifnottex +@xref{Agenda Views,,,org, The Org Manual}, for details. +@end ifnottex + +@node Org Authoring +@subsection Org as an authoring system +@cindex Org exporting + +@findex org-export +@kindex C-c C-e @r{(Org mode)} + You may want to format your Org notes nicely and to prepare them for +export and publication. To export the current buffer, type @kbd{C-c +C-e} (@code{org-export}) anywhere in an Org buffer. This command +prompts for an export format; currently supported formats include +HTML, La@TeX{}, OpenDocument (@file{.odt}), and PDF. Some formats, +such as PDF, require certain system tools to be installed. + +@vindex org-publish-project-alist + To export several files at once to a specific directory, either +locally or over the network, you must define a list of projects +through the variable @code{org-publish-project-alist}. See its +documentation for details. + + Org supports a simple markup scheme for applying text formatting to +exported documents: + +@example +- This text is /emphasized/ +- This text is *in bold* +- This text is _underlined_ +- This text uses =a teletype font= + +#+begin_quote +``This is a quote.'' +#+end_quote + +#+begin_example +This is an example. +#+end_example +@end example + + For further details, see @ref{Exporting,,,org, The Org Manual} and +@ref{Publishing,,,org, The Org Manual}. + @node TeX Mode @section @TeX{} Mode @cindex @TeX{} mode diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi index ae7550d0fae..8cb5ab44a2e 100644 --- a/doc/emacs/trouble.texi +++ b/doc/emacs/trouble.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @iftex @@ -40,8 +40,8 @@ Cancel a previously made change in the buffer contents (@code{undo}). @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}.) +and cancels the command that invoked the recursive edit +(@pxref{Recursive Edit}). @cindex quitting @kindex C-g @@ -54,7 +54,7 @@ a kill command that is taking a long time, either your text will kill ring, or maybe both. If the region is active, @kbd{C-g} deactivates the mark, unless Transient Mark mode is off (@pxref{Disabled Transient Mark}). If you are in the middle of an -incremental search, @kbd{C-g} does special things; it may take two +incremental search, @kbd{C-g} behaves specially; it may take two successive @kbd{C-g} characters to get out of a search. @xref{Incremental Search}, for details. @@ -136,12 +136,12 @@ 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-p} to read the @file{PROBLEMS} file. + This section describes how to recognize and deal with situations in +which Emacs does not work as you expect, such as keyboard code mixups, +garbled displays, running out of memory, and crashes and hangs. + + @xref{Bugs}, for what to do when you think you have found a bug in +Emacs. @menu * DEL Does Not Delete:: What to do if @key{DEL} doesn't delete. @@ -150,40 +150,35 @@ in the Emacs distribution. Type @kbd{C-h C-f} to read the FAQ; type * 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. +* Emergency Escape:: What to do if Emacs stops responding. @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, usually labeled @key{Backspace}, which is ordinarily used 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}. +In Emacs, this key is supposed to be equivalent to @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{Backspace} key as -@key{DEL}, but it isn't. +Emacs gets the wrong information from the system, and @key{Backspace} +ends up deleting forwards instead of backwards. Some keyboards also have a @key{Delete} key, which is ordinarily used to delete forwards. If this key deletes backward in Emacs, that too suggests Emacs got the wrong information---but in the opposite sense. - On a text-only terminal, if you find the usual erasure key prompts + On a text-only terminal, if you find that @key{Backspace} 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. +@findex normal-erase-is-backspace-mode 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 @@ -192,13 +187,10 @@ 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{Backspace} -deletes forwards instead of backwards, use this line to make -@key{Backspace} act as @key{DEL} (resulting in behavior compatible -with Emacs 20 and previous versions): + To fix the problem in every Emacs session, put one of the following +lines into your initialization file (@pxref{Init File}). For the +first case above, where @key{Backspace} deletes forwards instead of +backwards, use this line to make @key{Backspace} act as @key{DEL}: @lisp (normal-erase-is-backspace-mode 0) @@ -224,12 +216,12 @@ Customization}. 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}. + 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}. @xref{Recursive Edit}. @node Screen Garbled @subsection Garbage on the Screen @@ -244,12 +236,9 @@ the following section.) 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. +one of its sections. If you seem to be using the right terminfo +entry, it is possible that there is a bug in the terminfo entry, or a +bug in Emacs that appears for certain terminal types. @node Text Garbled @subsection Garbage in the Text @@ -385,25 +374,6 @@ program. 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 @@ -432,41 +402,51 @@ of the main places you can read about known issues: @itemize @item -The @file{etc/PROBLEMS} file in the Emacs distribution; type @kbd{C-h -C-p} to read it. This file contains a list of particularly well-known -issues that have been encountered in compiling, installing and running -Emacs. Often, there are suggestions for workarounds and solutions. +The @file{etc/PROBLEMS} file; type @kbd{C-h C-p} to read it. This +file contains a list of particularly well-known issues that have been +encountered in compiling, installing and running Emacs. Often, there +are suggestions for workarounds and solutions. @item Some additional user-level problems can be found in @ref{Bugs and problems, , Bugs and problems, efaq, GNU Emacs FAQ}. +@cindex bug tracker +@item +The GNU Bug Tracker at @url{http://debbugs.gnu.org}. Emacs bugs are +filed in the tracker under the @samp{emacs} package. The tracker +records information about the status of each bug, the initial bug +report, and the follow-up messages by the bug reporter and Emacs +developers. You can search for bugs by subject, severity, and other +criteria. + +@cindex debbugs package +Instead of browsing the bug tracker as a webpage, you can browse it +from Emacs using the @code{debbugs} package, which can be downloaded +via the Package Menu (@pxref{Packages}). This package provides the +command @kbd{M-x debbugs-gnu} to list bugs, and @kbd{M-x +debbugs-gnu-search} to search for a specific bug. + @item The @samp{bug-gnu-emacs} mailing list (also available as the newsgroup @samp{gnu.emacs.bug}). You can read the list archives at -@url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs}. If you -like, you can also subscribe to the list. Be aware that the sole -purpose of this list is to provide the Emacs maintainers with -information about bugs and feature requests. Reports may contain -fairly large amounts of data; spectators should not complain about -this. +@url{http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs}. This list +works as a ``mirror'' of the Emacs bug reports and follow-up messages +which are sent to the bug tracker. It also contains old bug reports +from before the bug tracker was introduced (in early 2008). -@item -The bug tracker at @url{http://debbugs.gnu.org}. From early 2008, -reports from the @samp{bug-gnu-emacs} list have also been sent here. -The tracker contains the same information as the mailing list, just in -a different format. You may prefer to browse and read reports using -the tracker. +If you like, you can subscribe to the list. Be aware that its purpose +is to provide the Emacs maintainers with information about bugs and +feature requests, so reports may contain fairly large amounts of data; +spectators should not complain about this. @item The @samp{emacs-pretest-bug} mailing list. This list is no longer used, and is mainly of historical interest. At one time, it was used for bug reports in development (i.e., not yet released) versions of Emacs. You can read the archives for 2003 to mid 2007 at -@url{http://lists.gnu.org/archive/html/emacs-pretest-bug/}. From -late 2007 to mid 2008, the address was an alias for the -@samp{emacs-devel} mailing list. From mid 2008 onwards, it has been -an alias for @samp{bug-gnu-emacs}. +@url{http://lists.gnu.org/archive/html/emacs-pretest-bug/}. Nowadays, +it is an alias for @samp{bug-gnu-emacs}. @item The @samp{emacs-devel} mailing list. Sometimes people report bugs to @@ -485,33 +465,32 @@ 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. + If the Emacs display does not correspond properly to the contents of +the buffer, then it is a bug. But you should check that features like +buffer narrowing (@pxref{Narrowing}), which can hide parts of the +buffer or change how it is displayed, are not responsible. 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. +sure that it is 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. + 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, it might actually be working right. If in doubt, +read the command's documentation (@pxref{Name Help}). - 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 + 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 @@ -527,59 +506,61 @@ 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 + If the built-in documentation for 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. + 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. +@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. If you want to +actually @emph{debug} the problem, and report explanations that are +more than guesses, that is useful---but please include the raw facts +as well. 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 +large, and Emacs displays @samp{I feel pretty today}. The bug report +would need to provide all that information. You should not 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 might 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 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. + You should not even say ``visit a file'' instead of @kbd{C-x C-f}. +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. + + If possible, try quickly to reproduce the bug by invoking Emacs with +@command{emacs -Q} (so that Emacs starts with no initial +customizations; @pxref{Initial Options}), and repeating the steps that +you took to trigger the bug. If you can reproduce the bug this way, +that rules out bugs in your personal customizations. Then your bug +report should begin by stating that you started Emacs with +@command{emacs -Q}, followed by the exact sequence of steps for +reproducing the bug. If possible, inform us of the exact contents of +any file that is needed to reproduce the bug. + + Some bugs are not reproducible from @command{emacs -Q}; some are not +easily reproducible at all. In that case, you should report what you +have---but, as before, please stick to the raw facts about what you +did to trigger the bug the first time. @node Checklist @subsection Checklist for Bug Reports @@ -616,15 +597,14 @@ address. Or you can simply send an email to that address describing the problem. Your report will be sent to the @samp{bug-gnu-emacs} mailing list, and -stored in the tracker at @url{http://debbugs.gnu.org}. Please try to +stored in the GNU Bug Tracker at @url{http://debbugs.gnu.org}. Please include a valid reply email address, in case we need to ask you for more information about your report. Submissions are moderated, so there may be a delay before your report appears. -You do not need to know how the @url{http://debbugs.gnu.org} bug -tracker works in order to report a bug, but if you want to, you can -read the tracker's online documentation to see the various features -you can use. +You do not need to know how the Gnu Bug Tracker works in order to +report a bug, but if you want to, you can read the tracker's online +documentation to see the various features you can use. All mail sent to the @samp{bug-gnu-emacs} mailing list is also gatewayed to the @samp{gnu.emacs.bug} newsgroup. The reverse is also @@ -689,10 +669,10 @@ 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. -If at all possible, give a full recipe for an Emacs started with the -@samp{-Q} option (@pxref{Initial Options}). This bypasses your -@file{.emacs} customizations. +The precise commands we need to type to reproduce the bug. If at all +possible, give a full recipe for an Emacs started with the @samp{-Q} +option (@pxref{Initial Options}). This bypasses your personal +customizations. @findex open-dribble-file @cindex dribble file @@ -722,8 +702,8 @@ 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. +your Emacs initialization 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 @@ -806,13 +786,13 @@ produce it, copy it into the bug report. @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 files). 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. +including your initialization 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 initialization file (start +Emacs with the @code{-Q} switch to prevent loading the init files). +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 @@ -983,8 +963,8 @@ your best to help. Send an explanation with your changes of what problem they fix or what improvement they bring about. For a fix for an existing bug, it is best to reply to the relevant discussion on the @samp{bug-gnu-emacs} -list, or item in the @url{http://debbugs.gnu.org} tracker. Explain -why your change fixes the bug. +list, or the bug entry in the GNU Bug Tracker at +@url{http://debbugs.gnu.org}. Explain why your change fixes the bug. @item Always include a proper bug report for the problem you think you have diff --git a/doc/emacs/vc-xtra.texi b/doc/emacs/vc-xtra.texi index 978a2a31a2e..51137a273d3 100644 --- a/doc/emacs/vc-xtra.texi +++ b/doc/emacs/vc-xtra.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2011 Free Software Foundation, Inc. +@c Copyright (C) 2004-2012 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 diff --git a/doc/emacs/vc1-xtra.texi b/doc/emacs/vc1-xtra.texi index 05e89e69f0e..48b902f18c1 100644 --- a/doc/emacs/vc1-xtra.texi +++ b/doc/emacs/vc1-xtra.texi @@ -1,305 +1,10 @@ @c This is part of the Emacs manual. -@c Copyright (C) 2004-2011 Free Software Foundation, Inc. +@c Copyright (C) 2004-2012 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 - - A common way of using CVS and other more advanced VCSes is to set up -a central 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 repository server. - - One difficulty is that access to a repository server is often slow, -and that developers might need to work off-line as well. While only -third-generation decentralized VCses such as GNU Arch or Mercurial -really solve this problem, VC is designed to reduce the amount of -network interaction necessary. - - If you are using a truly decentralized VCS you can skip the rest of -this section. It describes backup and local-repository techniques -that are only useful for Subversion and earlier VCSes. - -@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 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 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 Revisions,,,emacs, the Emacs Manual}), -@end iftex -@ifnottex -(@pxref{Old Revisions}), -@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 Revision Tags -@subsection Revision Tags -@cindex tags and version control - - In a VCS with per-file revision numbers (such as SCCS, RCS, or CVS) -@dfn{tag} is a named set of file versions (one for each registered -file) that you can treat as a unit. In a VCS with per-repository -version numbers (Subversion and most later ones) a tag is simply -a symbolic name for a revision. - - One important kind of tag is a @dfn{release}, a (theoretically) -stable version of the system that is ready for distribution to users. - -@menu -* Making Revision Tags:: The tag facilities. -* Revision Tag Caveats:: Things to be careful of when using tags. -@end menu - -@node Making Revision Tags -@subsubsection Making and Using Revision Tags - - There are two basic commands for tags; one makes a -tag with a given name, the other retrieves a named tag. - -@table @code -@kindex C-x v s -@findex vc-create-tag -@item C-x v s @var{name} @key{RET} -Define the working revision of every registered file in or under the -current directory as a tag named @var{name} -(@code{vc-create-tag}). - -@kindex C-x v r -@findex vc-retrieve-tag -@item C-x v r @var{name} @key{RET} -For all registered files at or below the current directory level, -retrieve the tagged revision @var{name}. This command will -switch to a branch if @var{name} is a branch name and your VCS -distinguishes branches from tags. -(@code{vc-retrieve-tag}). - -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 - -Tags are inexpensive, so you need not hesitate to create them whenever -they are useful. Branches vary in cost depending on your VCS; in -older ones they may be expensive. - - You can give a tag or branch name as an argument to @kbd{C-x v =} or -@kbd{C-x v ~} -@iftex -(@pxref{Old Revisions,,,emacs, the Emacs Manual}). -@end iftex -@ifnottex -(@pxref{Old Revisions}). -@end ifnottex -Thus, you can use it to compare a tagged version against the current files, -or two tagged versions against each other. - -@node Revision Tag Caveats -@subsubsection Revision Tag Caveats - - For SCCS, VC implements tags itself; these tags are visible only -through VC. Most later systems (including CVS, Subversion, bzr, git, -and hg) have a native tag facility, and VC uses it where -available; those tags will be visible even when you bypass VC. - - There is no support for VC tags using GNU Arch yet. - - Under older VCSes (SCCS, RCS, CVS, early versions of Subversion), -renaming and deletion could create some difficulties with tags. This is -not a VC-specific problem, but a general design issue in version -control systems that was not solved effectively until the earliest -third-generation systems. - - In a file-oriented VCS, when you rename a registered file you need -to rename its master along with it; the command @code{vc-rename-file} -will do this automatically. If you are using SCCS, you must also -update the records of the tag, to mention the file by its new name -(@code{vc-rename-file} does this, too). An old tag 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 tags by hand. - - Using @code{vc-rename-file} makes the tag 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 tag, 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 @@ -307,52 +12,55 @@ won't really work as retrieved. @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. +* VC Delete/Rename:: Deleting and renaming version-controlled files. +* Revision Tags:: Symbolic names for revisions. * 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 + If you use RCS or CVS for a program with a @file{ChangeLog} file @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: +you can generate change log entries from the version control log +entries of previous commits. + + Note that this only works with RCS or CVS. This procedure would be +particularly incorrect on a modern changeset-based version control +system, where changes to the @file{ChangeLog} file would normally be +committed as part of a changeset. In that case, you should write the +change log entries first, then pull them into the @samp{*vc-log*} +buffer when you commit +@iftex +(@pxref{Log Buffer,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Log Buffer}). +@end ifnottex @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. +Visit the current directory's @file{ChangeLog} file and, for +registered files in that directory, create new entries for versions +committed since the most recent change log entry (@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: +Bowditch to @file{rcs2log} on 1999-05-22 with log entry @samp{Ignore +log messages that start with `#'.}. Then @kbd{C-x v a} inserts this +@file{ChangeLog} entry: @iftex @medbreak @@ -369,17 +77,11 @@ messages that start with `#'.}. Then @kbd{C-x v a} visits @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: +If the version control log entry specifies a function name (in +parenthesis at the beginning of a line), that is reflected in the +@file{ChangeLog} entry. For example, if a log entry for @file{vc.el} +is @samp{(vc-do-command): Check call-process status.}, the +@file{ChangeLog} entry is: @iftex @medbreak @@ -395,221 +97,184 @@ if the text of the log entry starts with @w{@samp{(@var{functionname}): @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 + 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. -@noindent -They appear like this in @file{ChangeLog}: +@node VC Delete/Rename +@subsubsection Deleting and Renaming Version-Controlled Files +@cindex renaming version-controlled files -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-04-01 Nathaniel Bowditch <nat@@apn.org> +@table @kbd +@item M-x vc-delete-file +Prompt for a file name, delete the file from the working tree, and +schedule the deletion for committing. - * vc.texinfo: Fix expansion typos. +@item M-x vc-rename-file +Prompt for two file names, @var{VAR} and @var{OLD}, rename them in the +working tree, and schedule the renaming for committing. +@end table - * vc.el, vc-hooks.el: Don't call expand-file-name. -@end group -@end smallexample +@findex vc-delete-file + If you wish to delete a version-controlled file, use the command +@kbd{M-x vc-delete-file}. This prompts for the file name, and deletes +it via the version control system. The file is removed from the +working tree, and in the VC Directory buffer @iftex -@medbreak +(@pxref{VC Directory Mode}), @end iftex +@ifnottex +(@pxref{VC Directory Mode}), +@end ifnottex +it is displayed with the @samp{removed} status. When you commit it, +the deletion takes effect in the repository. - 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: +@findex vc-rename-file + To rename a version-controlled file, type @kbd{M-x vc-rename-file}. +This prompts for two arguments: the name of the file you wish to +rename, and the new name; then it performs the renaming via the +version control system. The renaming takes effect immediately in the +working tree, and takes effect in the repository when you commit the +renamed file. + + On modern version control systems that have built-in support for +renaming, the renamed file retains the full change history of the +original file. On CVS and older version control systems, the +@code{vc-rename-file} command actually works by creating a copy of the +old file under the new name, registering it, and deleting the old +file. In this case, the change history is not preserved. -@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 +@node Revision Tags +@subsubsection Revision Tags +@cindex revision tag +@cindex tags for version control -@noindent -Then the text in @file{ChangeLog} looks like this: + Most version control systems allow you to apply a @dfn{revision tag} +to a specific version of a version-controlled tree. On modern +changeset-based version control systems, a revision tag is simply a +symbolic name for a particular revision. On older file-based systems +like CVS, each tag is added to the entire set of version-controlled +files, allowing them to be handled as a unit. Revision tags are +commonly used to identify releases that are distributed to users. -@iftex -@medbreak -@end iftex -@smallexample -@group -1999-04-01 Nathaniel Bowditch <nat@@apn.org> + There are two basic commands for tags; one makes a tag with a given +name, the other retrieves a named tag. - * vc.texinfo: Fix expansion typos. - * vc.el, vc-hooks.el: Don't call expand-file-name. -@end group -@end smallexample -@iftex -@medbreak -@end iftex +@table @code +@kindex C-x v s +@findex vc-create-tag +@item C-x v s @var{name} @key{RET} +Define the working revision of every registered file in or under the +current directory as a tag named @var{name} +(@code{vc-create-tag}). - 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}. +@kindex C-x v r +@findex vc-retrieve-tag +@item C-x v r @var{name} @key{RET} +For all registered files at or below the current directory level, +retrieve the tagged revision @var{name}. This command will switch to a +branch if @var{name} is a branch name and your VCS distinguishes +branches from tags. (@code{vc-retrieve-tag}). -@node Renaming and VC -@subsubsection Renaming VC Work Files and Master Files +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 -@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 tags (@pxref{Revision Tags}) that -mention the file, so that they use the new name; despite this, the -tag thus modified may not completely work (@pxref{Revision Tag Caveats}). + You can give a tag or branch name as an argument to @kbd{C-x v =} or +@kbd{C-x v ~} +@iftex +(@pxref{Old Revisions,,,emacs, the Emacs Manual}). +@end iftex +@ifnottex +(@pxref{Old Revisions}). +@end ifnottex +Thus, you can use it to compare a tagged version against the current files, +or two tagged versions against each other. - 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. + On SCCS, VC implements tags itself; these tags are visible only +through VC. Most later systems (including CVS, Subversion, bzr, git, +and hg) have a native tag facility, and VC uses it where available; +those tags will be visible even when you bypass VC. - You cannot use @code{vc-rename-file} on a file that is locked by -someone else. + In a file-oriented VCS, when you rename a registered file you need +to rename its master along with it; the command @code{vc-rename-file} +will do this automatically. If you are using SCCS, you must also +update the records of the tag, to mention the file by its new name +(@code{vc-rename-file} does this, too). An old tag 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 tags by hand. Using @code{vc-rename-file} makes the tag 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 tag, 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 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 + On Subversion, CVS, RCS, and SCCS, you can put certain special +strings called @dfn{version headers} into a work file. When the file +is committed, the version control system automatically puts the +revision number, the name of the user who made the commit, and other +relevant information into the version header. - 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. +@vindex vc-consult-headers + VC does not normally use the information in the version headers. As +an exception, when using RCS, Emacs uses the version header, if there +is one, to determine the file version, since it is often more reliable +than the RCS master file. To inhibit using the version header this +way, change the variable @code{vc-consult-headers} to @code{nil}. @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})}. + To insert a suitable header string into the current buffer, type +@kbd{C-x v h} (@code{vc-insert-headers}). This command works only on +Subversion, CVS, RCS, and SCCS. The variable +@code{vc-@var{backend}-header} contains the list of keywords to insert +into the version header; for instance, CVS uses @code{vc-cvs-header}, +whose default value is @code{'("\$Id\$")}. (The extra backslashes +prevent the string constant from being interpreted as a header, if the +Emacs Lisp file defining it is maintained with version control.) The +@kbd{C-x v h} command inserts each keyword in the list on a new line +at point, surrounded by tabs, and inside comment delimiters if +necessary. @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. +@var{regexp} matches the buffer name, @var{format} is also inserted as +part of the version header. A @samp{%s} in @var{format} is replaced +with the file's version control type. @node Customizing VC @subsection Customizing VC @vindex vc-handled-backends -The variable @code{vc-handled-backends} determines which version + 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 Mtn Arch)}, 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 +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, 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 @iftex -@ref{Registering,,,emacs, the Emacs Manual}, +(@pxref{Registering,,,emacs, the Emacs Manual}). @end iftex @ifnottex -@ref{Registering}, +(@pxref{Registering}). @end ifnottex -for details. @menu * General VC Options:: Options that apply to multiple back ends. @@ -626,40 +291,27 @@ 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. +@cindex symbolic links (and version control) + Editing a version-controlled file through a symbolic link may cause +unexpected results, if you are unaware that the underlying file is +version-controlled. The variable @code{vc-follow-symlinks} controls +what Emacs does if you try to visit a symbolic link pointing to a +version-controlled file. If the value is @code{ask} (the default), +Emacs asks for confirmation. If it is @code{nil}, Emacs just displays +a warning message. If it is @code{t}, Emacs automatically follows the +link and visits the real file instead. @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.) +@kbd{C-x v u} also operates without asking for confirmation. @vindex vc-command-messages VC mode does much of its work by running the shell commands for the -appropriate backend. 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. +appropriate version control system. 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 @@ -715,37 +367,16 @@ the variable @code{vc-mistrust-permissions} affects SCCS use, but @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-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. @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 + When using a CVS repository on a remote machine, VC can try keeping 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 @@ -753,36 +384,58 @@ 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}}, + If @code{vc-cvs-stay-local} is @code{t} (the default), VC determines +the version control status of each file using only the entry in the +local CVS subdirectory and the information returned by previous CVS +commands. As a consequence, if you have modified a file and somebody +else has checked in other changes, you will not be notified of the +conflict until you try to commit. + + If you change @code{vc-cvs-stay-local} to @code{nil}, 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. + + 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. + +@cindex automatic version backups + When using a remote repository, Emacs normally makes @dfn{automatic +version backups} of the original versions of each edited file. These +local backups are made whenever you save the first changes to a file, +and they are removed after you commit your changes to the repository. +(Note that these are not the same as ordinary Emacs backup files; @iftex -@pxref{Merging,,,emacs, the Emacs Manual}). +@pxref{Backup,,,emacs, the Emacs Manual}.) @end iftex @ifnottex -@pxref{Merging}). +@pxref{Backup}.) @end ifnottex +Commands like @kbd{C-x v =} and @kbd{C-x v u} make use of automatic +version backups, if possible, to avoid having to access the network. - 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. + Setting @code{vc-cvs-stay-local} to @code{nil} disables the making +of automatic 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. +@cindex manual version backups + Automatic version backups have names of the form +@w{@code{@var{file}.~@var{version}.~}}. This is similar to the name +that @kbd{C-x v ~} saves old versions to +@iftex +(@pxref{Old Revisions,,,emacs, the Emacs Manual}), +@end iftex +@ifnottex +(@pxref{Old Revisions}), +@end ifnottex +except for the additional dot (@samp{.}) after the version. The +relevant VC commands can use both kinds of version backups. The main +difference is that the ``manual'' version backups made by @kbd{C-x v +~} are not deleted automatically when you commit. -@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. +@cindex locking (CVS) + CVS does not use locking by default, but there are ways to enable +locking-like behavior using its @env{CVSREAD} or @dfn{watch} feature; +see the CVS documentation for details. If that case, you can use +@kbd{C-x v v} in Emacs to toggle locking, as you would for a +locking-based version control system (@pxref{VC With A Locking VCS}). diff --git a/doc/emacs/windows.texi b/doc/emacs/windows.texi index 6a6f7b1a4d7..76ab79361e4 100644 --- a/doc/emacs/windows.texi +++ b/doc/emacs/windows.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011 +@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node Windows, Frames, Buffers, Top diff --git a/doc/emacs/xresources.texi b/doc/emacs/xresources.texi index b32b3d905e4..7a4e4798061 100644 --- a/doc/emacs/xresources.texi +++ b/doc/emacs/xresources.texi @@ -1,5 +1,5 @@ @c This is part of the Emacs manual. -@c Copyright (C) 1987, 1993-1995, 1997, 2001-2011 +@c Copyright (C) 1987, 1993-1995, 1997, 2001-2012 @c Free Software Foundation, Inc. @c See file emacs.texi for copying conditions. @node X Resources, Antinews, Emacs Invocation, Top @@ -51,15 +51,16 @@ this file do not take effect immediately, because the X server stores its own list of resources; to update it, use the command @command{xrdb}---for instance, @samp{xrdb ~/.Xdefaults}. -@cindex Registry (MS-Windows) +@cindex registry, setting resources (MS-Windows) (MS-Windows systems do not support X resource files; on Windows, Emacs 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, as -explained below.) +key @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs}, which affects only +the current user and override the system-wide settings, and then under +the key @samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs}, which affects +all users of the system. 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, as explained below.) Each line in the X resource file specifies a value for one option or for a collection of related options. Each resource specification |