diff options
| author | Paul Eggert <eggert@cs.ucla.edu> | 2012-01-09 09:36:10 -0800 |
|---|---|---|
| committer | Paul Eggert <eggert@cs.ucla.edu> | 2012-01-09 09:36:10 -0800 |
| commit | 35cf62d95cdcd5323dcea4a5385942c342ff1d9c (patch) | |
| tree | 90358cbb033a126c4d48793a80fd804b7baaca24 /doc | |
| parent | 59815c02506eb39b61e672528ed03885749ba529 (diff) | |
| parent | 7655cb66d86564e792b825f1a0e1a4de7d6e6db5 (diff) | |
| download | emacs-35cf62d95cdcd5323dcea4a5385942c342ff1d9c.tar.gz | |
Merge from trunk.
Diffstat (limited to 'doc')
198 files changed, 5423 insertions, 4192 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 diff --git a/doc/lispintro/ChangeLog b/doc/lispintro/ChangeLog index 6cede6375f2..0365a3ca174 100644 --- a/doc/lispintro/ChangeLog +++ b/doc/lispintro/ChangeLog @@ -471,7 +471,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 2001-2011 Free Software Foundation, Inc. + Copyright (C) 2001-2012 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/lispintro/Makefile.in b/doc/lispintro/Makefile.in index df356f1b132..fa9a0a4037c 100644 --- a/doc/lispintro/Makefile.in +++ b/doc/lispintro/Makefile.in @@ -1,6 +1,6 @@ #### Makefile for the Emacs Lisp Introduction manual -# Copyright (C) 1994-1999, 2001-2011 Free Software Foundation, Inc. +# Copyright (C) 1994-1999, 2001-2012 Free Software Foundation, Inc. # This file is part of GNU Emacs. diff --git a/doc/lispintro/README b/doc/lispintro/README index ba4e727cc8e..d81a6bc2a3a 100644 --- a/doc/lispintro/README +++ b/doc/lispintro/README @@ -1,4 +1,4 @@ -Copyright (C) 2001-2011 Free Software Foundation, Inc. +Copyright (C) 2001-2012 Free Software Foundation, Inc. See the end of the file for license conditions. diff --git a/doc/lispintro/cons-1.eps b/doc/lispintro/cons-1.eps index a1fb08463b4..d17082f5ac7 100644 --- a/doc/lispintro/cons-1.eps +++ b/doc/lispintro/cons-1.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:26:58 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2011 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2012 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-2.eps b/doc/lispintro/cons-2.eps index a711b66ca2e..bd227a14c03 100644 --- a/doc/lispintro/cons-2.eps +++ b/doc/lispintro/cons-2.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:26:39 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2011 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2012 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-2a.eps b/doc/lispintro/cons-2a.eps index 5612caa0717..676030d780f 100644 --- a/doc/lispintro/cons-2a.eps +++ b/doc/lispintro/cons-2a.eps @@ -4,7 +4,7 @@ %%CreationDate: Tue Mar 14 15:09:30 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2011 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2012 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-3.eps b/doc/lispintro/cons-3.eps index a1de449373f..329c751b856 100644 --- a/doc/lispintro/cons-3.eps +++ b/doc/lispintro/cons-3.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:25:41 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2011 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2012 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-4.eps b/doc/lispintro/cons-4.eps index 45882e815a7..fe28852a872 100644 --- a/doc/lispintro/cons-4.eps +++ b/doc/lispintro/cons-4.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:25:06 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2011 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2012 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/cons-5.eps b/doc/lispintro/cons-5.eps index b8bff1da573..214c4059e32 100644 --- a/doc/lispintro/cons-5.eps +++ b/doc/lispintro/cons-5.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:27:28 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2011 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2012 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/drawers.eps b/doc/lispintro/drawers.eps index 99e3581f38e..2c066fc708a 100644 --- a/doc/lispintro/drawers.eps +++ b/doc/lispintro/drawers.eps @@ -9,7 +9,7 @@ %%EndComments %%BeginProlog -% Copyright (C) 2001-2011 Free Software Foundation, Inc. +% Copyright (C) 2001-2012 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 23d0d5a8f34..0f9b6b906aa 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -228,7 +228,7 @@ people who are not programmers. @sp 1 Edition @value{edition-number}, @value{update-date} @sp 1 -Copyright @copyright{} 1990-1995, 1997, 2001-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1990-1995, 1997, 2001-2012 Free Software Foundation, Inc. @sp 1 @iftex diff --git a/doc/lispintro/lambda-1.eps b/doc/lispintro/lambda-1.eps index a9c3c530646..42f8d54264c 100644 --- a/doc/lispintro/lambda-1.eps +++ b/doc/lispintro/lambda-1.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:31:53 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2011 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2012 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/lambda-2.eps b/doc/lispintro/lambda-2.eps index 44238a1ad7d..ab9e8a85820 100644 --- a/doc/lispintro/lambda-2.eps +++ b/doc/lispintro/lambda-2.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:33:09 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2011 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2012 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/lambda-3.eps b/doc/lispintro/lambda-3.eps index 1c5cda046e0..8269650e0ec 100644 --- a/doc/lispintro/lambda-3.eps +++ b/doc/lispintro/lambda-3.eps @@ -4,7 +4,7 @@ %%CreationDate: Wed Mar 8 14:33:49 1995 %%Creator: Tgif-2.16-p4 by William Chia-Wei Cheng (william@cs.UCLA.edu) -% Copyright (C) 1995, 1997, 2001-2011 Free Software Foundation, Inc. +% Copyright (C) 1995, 1997, 2001-2012 Free Software Foundation, Inc. % % This file is part of GNU Emacs. % diff --git a/doc/lispintro/makefile.w32-in b/doc/lispintro/makefile.w32-in index 06641cc2222..a8aaf43096e 100644 --- a/doc/lispintro/makefile.w32-in +++ b/doc/lispintro/makefile.w32-in @@ -1,6 +1,6 @@ #### -*- Makefile -*- for the Emacs Lisp Introduction 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/lispref/ChangeLog b/doc/lispref/ChangeLog index a03521d449b..f69eeeaadd4 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,41 @@ +2011-12-27 Stefan Monnier <monnier@iro.umontreal.ca> + + * variables.texi (Creating Buffer-Local): Warn against misuses of + make-variable-buffer-local (bug#10258). + +2012-01-07 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * macros.texi (Defining Macros): Document `doc-string' (bug#9668). + +2012-01-06 Chong Yidong <cyd@gnu.org> + + * variables.texi (Directory Local Variables): Document + hack-dir-local-variables-non-file-buffer. + +2012-01-06 Glenn Morris <rgm@gnu.org> + + * maps.texi (Standard Keymaps): Refer to Info-edit by name + rather than by keybinding. + +2011-12-29 Juanma Barranquero <lekktu@gmail.com> + + * frames.texi (Font and Color Parameters): Add @pxref. + +2011-12-29 Daniel Colascione <dan.colascione@gmail.com> + + * frames.texi (Font and Color Parameters): + Document w32 font backends (bug#10399). + +2011-12-28 Paul Eggert <eggert@cs.ucla.edu> + + * files.texi (File Attributes, Changing Files): + Use a more-natural notation for octal numbers. + +2011-12-23 Juanma Barranquero <lekktu@gmail.com> + + * variables.texi (Variables with Restricted Values): + Change reference to variable (bug#10354). + 2011-12-13 Martin Rudalics <rudalics@gmx.at> * windows.texi (Splitting Windows): Use t instead of non-nil @@ -9789,7 +9827,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 1998-2011 Free Software Foundation, Inc. + Copyright (C) 1998-2012 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/lispref/Makefile.in b/doc/lispref/Makefile.in index 75fa884224b..0b616884ff2 100644 --- a/doc/lispref/Makefile.in +++ b/doc/lispref/Makefile.in @@ -1,6 +1,6 @@ # Makefile for the GNU Emacs Lisp Reference Manual. -# Copyright (C) 1990-1996, 1998-2011 Free Software Foundation, Inc. +# Copyright (C) 1990-1996, 1998-2012 Free Software Foundation, Inc. # This file is part of GNU Emacs. diff --git a/doc/lispref/README b/doc/lispref/README index a9c0922640b..df808e4bcab 100644 --- a/doc/lispref/README +++ b/doc/lispref/README @@ -1,4 +1,4 @@ -Copyright (C) 2001-2011 Free Software Foundation, Inc. +Copyright (C) 2001-2012 Free Software Foundation, Inc. See the end of the file for license conditions. diff --git a/doc/lispref/abbrevs.texi b/doc/lispref/abbrevs.texi index 57030559d0b..f7fd8b541ed 100644 --- a/doc/lispref/abbrevs.texi +++ b/doc/lispref/abbrevs.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/abbrevs @node Abbrevs, Processes, Syntax Tables, Top diff --git a/doc/lispref/advice.texi b/doc/lispref/advice.texi index 29356381229..ee1950a589a 100644 --- a/doc/lispref/advice.texi +++ b/doc/lispref/advice.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998-1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1998-1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/advising @node Advising Functions, Debugging, Byte Compilation, Top diff --git a/doc/lispref/anti.texi b/doc/lispref/anti.texi index bb1e42c9309..6b9473e99d4 100644 --- a/doc/lispref/anti.texi +++ b/doc/lispref/anti.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2002-2011 Free Software Foundation, Inc. +@c Copyright (C) 1999, 2002-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @c This node must have no pointers. diff --git a/doc/lispref/back.texi b/doc/lispref/back.texi index 3add7b174d2..75c244ae1dd 100644 --- a/doc/lispref/back.texi +++ b/doc/lispref/back.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @c @c %**start of header diff --git a/doc/lispref/backups.texi b/doc/lispref/backups.texi index aad0cbc146a..969220845d0 100644 --- a/doc/lispref/backups.texi +++ b/doc/lispref/backups.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/backups @node Backups and Auto-Saving, Buffers, Files, Top diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi index ee2ce2e2001..c2e792cd585 100644 --- a/doc/lispref/buffers.texi +++ b/doc/lispref/buffers.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/buffers diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 41392273fbd..4a0bc8a6b24 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/commands diff --git a/doc/lispref/compile.texi b/doc/lispref/compile.texi index 372c041ab7a..4e21df78430 100644 --- a/doc/lispref/compile.texi +++ b/doc/lispref/compile.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/compile @node Byte Compilation, Advising Functions, Loading, Top diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 875c23658b9..e74f3e198bf 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/control @node Control Structures, Variables, Evaluation, Top diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index 868edaa5bd4..f8495513be4 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1997-2011 Free Software Foundation, Inc. +@c Copyright (C) 1997-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/customize @node Customization, Loading, Macros, Top diff --git a/doc/lispref/debugging.texi b/doc/lispref/debugging.texi index 757906f286e..9466f21a563 100644 --- a/doc/lispref/debugging.texi +++ b/doc/lispref/debugging.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 1998-1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/debugging @node Debugging, Read and Print, Advising Functions, Top diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index a9921d7443d..381eaf66c12 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/display @node Display, System Interface, Processes, Top diff --git a/doc/lispref/edebug.texi b/doc/lispref/edebug.texi index 391c22ba098..669a5d0edcd 100644 --- a/doc/lispref/edebug.texi +++ b/doc/lispref/edebug.texi @@ -1,6 +1,6 @@ @comment -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1992-1994, 1998-1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1992-1994, 1998-1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @c This file can also be used by an independent Edebug User diff --git a/doc/lispref/elisp-covers.texi b/doc/lispref/elisp-covers.texi index 92dfb7a074f..b2cc5a9adf2 100644 --- a/doc/lispref/elisp-covers.texi +++ b/doc/lispref/elisp-covers.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @c @comment %**start of header diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 98eaf1f8ade..0b8d972c1d5 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -44,7 +44,7 @@ This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@* corresponding to Emacs version @value{EMACSVER}. -Copyright @copyright{} 1990-1996, 1998-2011 Free Software +Copyright @copyright{} 1990-1996, 1998-2012 Free Software Foundation, Inc. @quotation diff --git a/doc/lispref/errors.texi b/doc/lispref/errors.texi index 98967b708b3..56ff3636750 100644 --- a/doc/lispref/errors.texi +++ b/doc/lispref/errors.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1993, 1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/errors @node Standard Errors, Standard Buffer-Local Variables, GNU Emacs Internals, Top diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index 74f3d9c48b9..adb4841a82d 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 1998, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/eval @node Evaluation, Control Structures, Symbols, Top diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 86ecfd122ef..614bd827489 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/files @@ -1115,16 +1115,11 @@ This function recursively follows symbolic links at all levels. @end group @group -(set-file-modes "~/junk/diffs" 438) +(set-file-modes "~/junk/diffs" #o666) @result{} nil @end group @group -(format "%o" 438) - @result{} "666" ; @r{Convert to octal.} -@end group - -@group % ls -l diffs -rw-rw-rw- 1 lewis 0 3063 Oct 30 16:00 diffs @end group @@ -1570,10 +1565,10 @@ the bitwise complement of the ``umask'' value. The argument @var{mode} must be an integer. On most systems, only the low 9 bits of @var{mode} are meaningful. You can use the Lisp construct -for octal character codes to enter @var{mode}; for example, +for octal numbers to enter @var{mode}; for example, @example -(set-default-file-modes ?\644) +(set-default-file-modes #o644) @end example Saving a modified version of an existing file does not count as creating diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index dad1f28026e..4835a5b3da2 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/frames @@ -888,9 +888,11 @@ and bar becomes a narrower bar). A list of symbols, specifying the @dfn{font backends} to use for drawing fonts in the frame, in order of priority. On X, there are currently two available font backends: @code{x} (the X core font -driver) and @code{xft} (the Xft font driver). On other systems, there -is only one available font backend, so it does not make sense to -modify this frame parameter. +driver) and @code{xft} (the Xft font driver). On Windows, there are +currently two available font backends: @code{gdi} and +@code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs +Manual}). On other systems, there is only one available font backend, +so it does not make sense to modify this frame parameter. @vindex background-mode, a frame parameter @item background-mode diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index f3b2375b61d..ada00867bd0 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/functions diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi index 0d77cba6fa6..0a2783b6f16 100644 --- a/doc/lispref/hash.texi +++ b/doc/lispref/hash.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/hash @node Hash Tables, Symbols, Sequences Arrays Vectors, Top diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 3426e81cdb3..678ea83465f 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/help diff --git a/doc/lispref/hooks.texi b/doc/lispref/hooks.texi index 6e2cac9c065..95655324ab4 100644 --- a/doc/lispref/hooks.texi +++ b/doc/lispref/hooks.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1998, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1993, 1998, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/hooks @node Standard Hooks, Index, Standard Keymaps, Top diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi index 9ef4646b50b..df6193cf13b 100644 --- a/doc/lispref/internals.texi +++ b/doc/lispref/internals.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1998-1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1993, 1998-1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/internals @node GNU Emacs Internals, Standard Errors, Tips, Top diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi index 44ac947fa99..64c856d3ed4 100644 --- a/doc/lispref/intro.texi +++ b/doc/lispref/intro.texi @@ -1,6 +1,6 @@ @c -*-coding: iso-latin-1-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/intro diff --git a/doc/lispref/keymaps.texi b/doc/lispref/keymaps.texi index e5cca0622a9..8e03ade285f 100644 --- a/doc/lispref/keymaps.texi +++ b/doc/lispref/keymaps.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 1998-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/keymaps @node Keymaps, Modes, Command Loop, Top diff --git a/doc/lispref/lay-flat.texi b/doc/lispref/lay-flat.texi index 55973adac59..73e2adbc03a 100644 --- a/doc/lispref/lay-flat.texi +++ b/doc/lispref/lay-flat.texi @@ -1,6 +1,6 @@ \input texinfo @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @c @comment %**start of header diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi index 056c924e72c..eb9ddf58603 100644 --- a/doc/lispref/lists.texi +++ b/doc/lispref/lists.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/lists @node Lists, Sequences Arrays Vectors, Strings and Characters, Top diff --git a/doc/lispref/loading.texi b/doc/lispref/loading.texi index ca233ac5f21..8d8fec62e2c 100644 --- a/doc/lispref/loading.texi +++ b/doc/lispref/loading.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/loading diff --git a/doc/lispref/locals.texi b/doc/lispref/locals.texi index a196efc9734..a075d955add 100644 --- a/doc/lispref/locals.texi +++ b/doc/lispref/locals.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1993, 1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/locals @node Standard Buffer-Local Variables, Standard Keymaps, Standard Errors, Top diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi index c66feec08b7..a8b941bba89 100644 --- a/doc/lispref/macros.texi +++ b/doc/lispref/macros.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/macros @node Macros, Customization, Functions, Top @@ -239,6 +239,9 @@ Specify how to step through macro calls for Edebug. @item (indent @var{indent-spec}) Specify how to indent calls to this macro. @xref{Indenting Macros}, for more details. + +@item (doc-string @var{number}) +Specify which element of the macro is the doc string, if any. @end table A @code{declare} form only has its special effect in the body of a diff --git a/doc/lispref/makefile.w32-in b/doc/lispref/makefile.w32-in index 7b88e861d67..08b176b7593 100644 --- a/doc/lispref/makefile.w32-in +++ b/doc/lispref/makefile.w32-in @@ -1,6 +1,6 @@ # -*- Makefile -*- for the GNU Emacs Lisp Reference 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/lispref/maps.texi b/doc/lispref/maps.texi index d235fee90ee..24cd64a6b35 100644 --- a/doc/lispref/maps.texi +++ b/doc/lispref/maps.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1993, 1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/maps @node Standard Keymaps, Standard Hooks, Standard Buffer-Local Variables, Top @@ -144,7 +144,7 @@ cell. @item Info-edit-map @vindex Info-edit-map -A sparse keymap used by the @kbd{e} command of Info. +A sparse keymap used by the @code{Info-edit} command. @item Info-mode-map @vindex Info-mode-map diff --git a/doc/lispref/markers.texi b/doc/lispref/markers.texi index 7b73c454c87..e8a009de401 100644 --- a/doc/lispref/markers.texi +++ b/doc/lispref/markers.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/markers @node Markers, Text, Positions, Top diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index aa22e6c92ff..e3008470233 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/minibuf diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 9d652901e53..5d09b79748e 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/modes @node Modes, Documentation, Keymaps, Top @@ -701,7 +701,7 @@ init file.) @cindex help for major mode @cindex documentation for major mode - The @code{describe-mode} function is provides information about major + The @code{describe-mode} function provides information about major modes. It is normally bound to @kbd{C-h m}. It uses the value of the variable @code{major-mode} (@pxref{Major Modes}), which is why every major mode command needs to set that variable. diff --git a/doc/lispref/nonascii.texi b/doc/lispref/nonascii.texi index 46dbbb08e57..19c72981174 100644 --- a/doc/lispref/nonascii.texi +++ b/doc/lispref/nonascii.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1998-1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1998-1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/characters @node Non-ASCII Characters, Searching and Matching, Text, Top diff --git a/doc/lispref/numbers.texi b/doc/lispref/numbers.texi index 3efddebffb4..6768ecece9c 100644 --- a/doc/lispref/numbers.texi +++ b/doc/lispref/numbers.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/numbers diff --git a/doc/lispref/objects.texi b/doc/lispref/objects.texi index 26def7858b7..3fb676edcd4 100644 --- a/doc/lispref/objects.texi +++ b/doc/lispref/objects.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/objects diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index 7d05f8f3468..e63300cfac4 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/os diff --git a/doc/lispref/package.texi b/doc/lispref/package.texi index 5533f8ab5fa..eb3612dc868 100644 --- a/doc/lispref/package.texi +++ b/doc/lispref/package.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 2010-2011 Free Software Foundation, Inc. +@c Copyright (C) 2010-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/package @node Packaging, Antinews, System Interface, Top diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index 74444c7ad60..29b338369e5 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/positions @node Positions, Markers, Frames, Top diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index 51d91572d0e..38eb5a86471 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/processes diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi index a601ed0c2c0..21481568276 100644 --- a/doc/lispref/searching.texi +++ b/doc/lispref/searching.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/searching diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 825dd976eac..0ea32f99e12 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/sequences diff --git a/doc/lispref/spellfile b/doc/lispref/spellfile index e0d77ee0541..18fb633acfd 100644 --- a/doc/lispref/spellfile +++ b/doc/lispref/spellfile @@ -337,7 +337,6 @@ fset fstab ftp fu -funtions garbles gc gcpro diff --git a/doc/lispref/streams.texi b/doc/lispref/streams.texi index 4d3a66d8852..36691624405 100644 --- a/doc/lispref/streams.texi +++ b/doc/lispref/streams.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1994, 1998-1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1994, 1998-1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/streams @node Read and Print, Minibuffers, Debugging, Top diff --git a/doc/lispref/strings.texi b/doc/lispref/strings.texi index 2b8911277cd..49199d3e32f 100644 --- a/doc/lispref/strings.texi +++ b/doc/lispref/strings.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/strings diff --git a/doc/lispref/symbols.texi b/doc/lispref/symbols.texi index 79b3249d760..866a63c4cd9 100644 --- a/doc/lispref/symbols.texi +++ b/doc/lispref/symbols.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/symbols @node Symbols, Evaluation, Hash Tables, Top diff --git a/doc/lispref/syntax.texi b/doc/lispref/syntax.texi index 0d7a0c0bed4..dc215b1e0e6 100644 --- a/doc/lispref/syntax.texi +++ b/doc/lispref/syntax.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/syntax diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index f7f9c716162..b75c013298f 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/text @node Text, Non-ASCII Characters, Markers, Top diff --git a/doc/lispref/tindex.pl b/doc/lispref/tindex.pl index 5c9b88f57b2..a8765716e71 100755 --- a/doc/lispref/tindex.pl +++ b/doc/lispref/tindex.pl @@ -1,6 +1,6 @@ #! /usr/bin/perl -# Copyright (C) 2000-2011 Free Software Foundation, Inc. +# Copyright (C) 2000-2012 Free Software Foundation, Inc. # This file is part of GNU Emacs. diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi index fd875b45be9..c0f6c0355e5 100644 --- a/doc/lispref/tips.texi +++ b/doc/lispref/tips.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1993, 1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1993, 1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/tips diff --git a/doc/lispref/two-volume-cross-refs.txt b/doc/lispref/two-volume-cross-refs.txt index 6eb11a92f47..67b5dbf89a3 100644 --- a/doc/lispref/two-volume-cross-refs.txt +++ b/doc/lispref/two-volume-cross-refs.txt @@ -1,4 +1,4 @@ -Copyright (C) 2001-2011 Free Software Foundation, Inc. +Copyright (C) 2001-2012 Free Software Foundation, Inc. See end for copying conditions. Two Volume Cross References diff --git a/doc/lispref/two-volume.make b/doc/lispref/two-volume.make index 8949bfe0157..4acbb193f82 100644 --- a/doc/lispref/two-volume.make +++ b/doc/lispref/two-volume.make @@ -1,4 +1,4 @@ -# Copyright (C) 2007-2011 Free Software Foundation, Inc. +# Copyright (C) 2007-2012 Free Software Foundation, Inc. # See end for copying conditions. # although it would be nice to use tex rather than pdftex to avoid diff --git a/doc/lispref/two.el b/doc/lispref/two.el index b3a8666bcf2..39dee62d45d 100644 --- a/doc/lispref/two.el +++ b/doc/lispref/two.el @@ -1,6 +1,6 @@ ;; Auxiliary functions for preparing a two volume manual. -;; Copyright (C) 2001-2011 Free Software Foundation, Inc. +;; Copyright (C) 2001-2012 Free Software Foundation, Inc. ;; --rjc 30mar92 diff --git a/doc/lispref/variables.texi b/doc/lispref/variables.texi index 091765043e3..b0a6795021b 100644 --- a/doc/lispref/variables.texi +++ b/doc/lispref/variables.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-2011 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-2012 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/variables @node Variables, Functions, Control Structures, Top @@ -1351,7 +1351,10 @@ needed if you use the @var{local} argument to @code{add-hook} or @deffn Command make-variable-buffer-local variable This function marks @var{variable} (a symbol) automatically buffer-local, so that any subsequent attempt to set it will make it -local to the current buffer at the time. +local to the current buffer at the time. Unlike +@code{make-local-variable}, with which it is often confused, this +cannot be undone, and affects the behavior of the variable in all +buffers. A peculiar wrinkle of this feature is that binding the variable (with @code{let} or other binding constructs) does not create a buffer-local @@ -1829,6 +1832,15 @@ function works by calling @code{dir-locals-set-class-variables} and @code{dir-locals-set-directory-class}, described below. @end defun +@defun hack-dir-local-variables-non-file-buffer +This function looks for directory-local variables, and immediately +applies them in the current buffer. It is intended to be called in +the mode commands for non-file buffers, such as Dired buffers, to let +them obey directory-local variable settings. For non-file buffers, +Emacs looks for directory-local variables in @code{default-directory} +and its parent directories. +@end defun + @defun dir-locals-set-class-variables class variables This function defines a set of variable settings for the named @var{class}, which is a symbol. You can later assign the class to one @@ -1998,6 +2010,6 @@ This variable holds a list of all variables of type @code{DEFVAR_BOOL}. Attempting to assign them any other value will result in an error: @example -(setq window-min-height 5.0) -@error{} Wrong type argument: integerp, 5.0 +(setq undo-limit 1000.0) +@error{} Wrong type argument: integerp, 1000.0 @end example diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi index c89447fc139..95f9f7f4d29 100644 --- a/doc/lispref/vol1.texi +++ b/doc/lispref/vol1.texi @@ -1,7 +1,7 @@ \input texinfo @c -*-texinfo-*- @c This file is used for printing the GNU Emacs Lisp Reference Manual @c in two volumes. It is a modified version of elisp.texi. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c %**start of header @setfilename elisp @@ -67,9 +67,7 @@ This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@* corresponding to Emacs version @value{EMACSVER}. -Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, -1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software -Foundation, Inc. +Copyright @copyright{} 1990-1996, 1998-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi index d45d23da365..08ea022f6a7 100644 --- a/doc/lispref/vol2.texi +++ b/doc/lispref/vol2.texi @@ -1,7 +1,7 @@ \input texinfo @c -*-texinfo-*- @c This file is used for printing the GNU Emacs Lisp Reference Manual @c in two volumes. It is a modified version of elisp.texi. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c %**start of header @setfilename elisp @@ -67,9 +67,7 @@ This is edition @value{VERSION} of the GNU Emacs Lisp Reference Manual,@* corresponding to Emacs version @value{EMACSVER}. -Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, -1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Free Software -Foundation, Inc. +Copyright @copyright{} 1990-1996, 1998-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index df631158689..85e1b9340fc 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Emacs Lisp Reference Manual. -@c Copyright (C) 1990-1995, 1998-1999, 2001-2011 +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 @c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/windows diff --git a/doc/man/ChangeLog b/doc/man/ChangeLog index 758cdde1dea..b6def1a7d8c 100644 --- a/doc/man/ChangeLog +++ b/doc/man/ChangeLog @@ -134,7 +134,7 @@ ;; add-log-time-zone-rule: t ;; End: - Copyright (C) 2007-2011 Free Software Foundation, Inc. + Copyright (C) 2007-2012 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/man/ebrowse.1 b/doc/man/ebrowse.1 index 5afe59d6bc1..84f1ef1dd9b 100644 --- a/doc/man/ebrowse.1 +++ b/doc/man/ebrowse.1 @@ -85,7 +85,7 @@ was written by Gerd Moellmann. Copyright .if t \(co .if n (C) -2008, 2009, 2010, 2011 Free Software Foundation, Inc. +2008-2012 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are diff --git a/doc/man/emacs.1 b/doc/man/emacs.1 index 1acdcf5ebd2..437d8cbad3b 100644 --- a/doc/man/emacs.1 +++ b/doc/man/emacs.1 @@ -642,9 +642,7 @@ For detailed credits and acknowledgements, see the GNU Emacs manual. Copyright .if t \(co .if n (C) -1995, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, -2009, 2010, 2011 -Free Software Foundation, Inc. +1995, 1999-2012 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are diff --git a/doc/man/etags.1 b/doc/man/etags.1 index f7ffa112f3c..a1291829665 100644 --- a/doc/man/etags.1 +++ b/doc/man/etags.1 @@ -267,8 +267,7 @@ Stallman. Copyright .if t \(co .if n (C) -1992, 1999, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, -2010, 2011 Free Software Foundation, Inc. +1992, 1999, 2001-2012 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are diff --git a/doc/man/grep-changelog.1 b/doc/man/grep-changelog.1 index 45a6abfd579..397e6493343 100644 --- a/doc/man/grep-changelog.1 +++ b/doc/man/grep-changelog.1 @@ -62,7 +62,7 @@ Display basic usage information. Copyright .if t \(co .if n (C) -2008, 2009, 2010, 2011 Free Software Foundation, Inc. +2008-2012 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are diff --git a/doc/man/rcs-checkin.1 b/doc/man/rcs-checkin.1 index 545b128b40d..a17c28a4d58 100644 --- a/doc/man/rcs-checkin.1 +++ b/doc/man/rcs-checkin.1 @@ -69,7 +69,7 @@ by Eric S. Raymond. Copyright .if t \(co .if n (C) -2008, 2009, 2010, 2011 Free Software Foundation, Inc. +2008-2012 Free Software Foundation, Inc. .PP Permission is granted to make and distribute verbatim copies of this document provided the copyright notice and this permission notice are diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog index 5d8e05806e0..adb5bbbd669 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,176 @@ +2012-01-06 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * gnus.texi (Group Parameters): Really note precedence. + +2012-01-04 Lars Magne Ingebrigtsen <larsi@gnus.org> + + * gnus.texi (Group Parameters): Note precedence. + +2012-01-03 Eric Schulte <eric.schulte@gmx.com> + + * org.texi (Noweb reference syntax): Adding documentation of + the `*org-babel-use-quick-and-dirty-noweb-expansion*' + variable. + +2012-01-03 Bastien Guerry <bzg@gnu.org> + + * org.texi (Plain lists): Split the table to fix the display + of items. + +2012-01-03 Bastien Guerry <bzg@gnu.org> + + * org.texi (Plain lists): Fix misplaced explanation. + +2012-01-03 Bastien Guerry <bzg@gnu.org> + + * org.texi (Plain lists, Agenda files): Add index entries. + +2012-01-03 Julian Gehring <julian.gehring@googlemail.com> + + * org.texi: Use "Org mode" instead of alternatives like + "Org-mode" or "org-mode". + +2012-01-03 Bernt Hansen <bernt@norang.ca> + + * org.texi (Agenda commands): Document + `org-clock-report-include-clocking-task'. + +2012-01-03 Bastien Guerry <bzg@gnu.org> + + * org.texi (Checkboxes): Document the new behavior of `C-u C-c + C-c' on checkboxes. + +2012-01-03 Julian Gehring <julian.gehring@googlemail.com> + + * org.texi: End sentences with two spaces. + +2012-01-03 Michael Brand <michael.ch.brand@gmail.com> + + * org.texi (External links): Document the link types file+sys + and file+emacs, slightly narrow used page width. + +2012-01-03 Eric Schulte <eric.schulte@gmx.com> + + * org.texi (colnames): Note that colnames behavior may differ + across languages. + +2012-01-03 Bastien Guerry <bzg@gnu.org> + + * org.texi (Weekly/daily agenda, Agenda commands): Fix typos. + +2012-01-03 Thomas Dye <dk@poto.westell.com> + + * org.texi: Augmented discussion of babel property + inheritance. Put footnote outside sentence ending period. + +2012-01-03 Eric Schulte <schulte.eric@gmail.com> + + * org.texi (eval): Documenting the full range of :eval header + argument values. + +2012-01-03 Eric Schulte <schulte.eric@gmail.com> + + * org.texi (eval): Documentation of the new :eval option. + +2012-01-03 Thomas Dye <dk@poto.local> + + * org.texi: Add accumulated properties. + +2012-01-03 Thomas Dye <dk@poto.local> + + * org.texi: Documented no spaces in name=assign, another + correction to :var table. + +2012-01-03 Thomas Dye <dk@poto.local> + + * org.texi: Changed DATA to NAME in Working With Source Code + section. + +2012-01-03 Tom Dye <tsd@tsdye.com> + + * org.texi: Minor change to :var table. + +2012-01-03 Tom Dye <tsd@tsdye.com> + + * org.texi: More changes to :var table (some examples were wrong). + +2012-01-03 Tom Dye <tsd@tsdye.com> + + * org.texi: Cleaned up :var table. + +2012-01-03 Bastien Guerry <bzg@gnu.org> + + * org.texi (Timestamps, Weekly/daily agenda) + (Weekly/daily agenda): Add @cindex for "appointment". + +2012-01-03 Eric Schulte <schulte.eric@gmail.com> + + * org.texi (Literal examples): A new link to the template for + inserting empty code blocks. + (Structure of code blocks): A new link to the template for + inserting empty code blocks. + +2012-01-03 Rafael Laboissiere <rafael@laboissiere.net> (tiny change) + + * org.texi (External links): Add footnote on how the behavior + of the text search in Org files are controled by the variable + `org-link-search-must-match-exact-headline'. + +2012-01-03 Eric Schulte <schulte.eric@gmail.com> + + * org.texi (Buffer-wide header arguments): Update + documentation to reflect removal of #+PROPERTIES. + +2012-01-03 Carsten Dominik <carsten.dominik@gmail.com> + + * org.texi (The clock table): Mention that ACHIVED trees + contribute to the clock table. + +2012-01-03 Carsten Dominik <carsten.dominik@gmail.com> (tiny change) + + * org.texi (Conflicts): Better yasnippet config info. + +2012-01-03 Bastien Guerry <bzg@gnu.org> (tiny change) + + * org.texi (Selective export): Explicitely mention the default + values for `org-export-select-tags', + `org-export-exclude-tags'. + +2012-01-03 Tom Dye <tsd@tsdye.com> + + * org.texi: Added a line to specify that header arguments are + lowercase. + +2012-01-03 Tom Dye <tsd@tsdye.com> + + * org.texi: :var requires default value when declared. + +2012-01-03 Bastien Guerry <bzg@gnu.org> + + * org.texi (Handling links): Add a note about the + `org-link-frame-setup' option. + +2012-01-03 David Maus <dmaus@ictsoc.de> + + * org.texi (Exporting Agenda Views, Extracting agenda + information): Fix command line syntax, quote symbol parameter + values. + +2012-01-03 David Maus <dmaus@ictsoc.de> + + * org.texi (Exporting Agenda Views): Fix command line syntax. + +2011-12-28 Paul Eggert <eggert@cs.ucla.edu> + + * gnus.texi (Mail Source Customization, Mail Back End Variables): + Use octal notation for file permissions, which are normally + thought of in octal. + (Mail Back End Variables): Use more-plausible modes in example. + +2011-12-20 Alan Mackenzie <acm@muc.de> + + * cc-mode.texi: Update version string 5.31 -> 5.32. + 2011-12-06 Juanma Barranquero <lekktu@gmail.com> * gnus-faq.texi (FAQ 2-1, FAQ 3-8, FAQ 4-14, FAQ 9-1): Fix typos. @@ -8493,7 +8666,7 @@ ;; coding: utf-8 ;; End: - Copyright (C) 1993-1999, 2001-2011 Free Software Foundation, Inc. + Copyright (C) 1993-1999, 2001-2012 Free Software Foundation, Inc. This file is part of GNU Emacs. diff --git a/doc/misc/Makefile.in b/doc/misc/Makefile.in index 34f136b09ff..6fd0b983b87 100644 --- a/doc/misc/Makefile.in +++ b/doc/misc/Makefile.in @@ -1,6 +1,6 @@ #### Makefile for documentation other than 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/misc/ada-mode.texi b/doc/misc/ada-mode.texi index 0eb20d01324..8d06ae0de22 100644 --- a/doc/misc/ada-mode.texi +++ b/doc/misc/ada-mode.texi @@ -3,7 +3,7 @@ @settitle Ada Mode @copying -Copyright @copyright{} 1999-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1999-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi index b64562f6875..b6368cf0517 100644 --- a/doc/misc/auth.texi +++ b/doc/misc/auth.texi @@ -10,7 +10,7 @@ @copying This file describes the Emacs auth-source library. -Copyright @copyright{} 2008-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2008-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -281,7 +281,7 @@ for any of the prompts. Note that the password needs to be evaluated if it's a function. It's wrapped in a function to provide some security. -Later, after a successful login, @code{nnimal.el} calls the +Later, after a successful login, @code{nnimap.el} calls the @code{:save-function} like so: @example diff --git a/doc/misc/autotype.texi b/doc/misc/autotype.texi index 289c08eb00e..9d7a51233ff 100644 --- a/doc/misc/autotype.texi +++ b/doc/misc/autotype.texi @@ -10,7 +10,7 @@ @c @cindex autotypist @copying -Copyright @copyright{} 1994-1995, 1999, 2001-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1994-1995, 1999, 2001-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/calc.texi b/doc/misc/calc.texi index d0c15c1940e..c42e8e6b9c0 100644 --- a/doc/misc/calc.texi +++ b/doc/misc/calc.texi @@ -94,7 +94,7 @@ This file documents Calc, the GNU Emacs calculator, included with GNU Emacs @value{EMACSVER}. @end ifnotinfo -Copyright @copyright{} 1990-1991, 2001-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1990-1991, 2001-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -11100,7 +11100,7 @@ pairwise relatively prime) is @texline @math{15\times 19\times 28 = 7980} years. @infoline 15*19*28 = 7980 years. This is the length of a Julian cycle. Working backwards, the previous -year in which all three cycles began was 4713 BC, and so Scalinger +year in which all three cycles began was 4713 BC, and so Scaliger chose that year as the beginning of a Julian cycle. Since at the time there were no historical records from before 4713 BC, using this year as a starting point had the advantage of avoiding negative year diff --git a/doc/misc/cc-mode.texi b/doc/misc/cc-mode.texi index c36e45e60f7..e2730cc8b3b 100644 --- a/doc/misc/cc-mode.texi +++ b/doc/misc/cc-mode.texi @@ -159,7 +159,7 @@ CC Mode @copying This manual is for CC Mode in Emacs. -Copyright @copyright{} 1995-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1995-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -190,7 +190,7 @@ developing GNU and promoting software freedom.'' @titlepage @sp 10 -@center @titlefont{CC Mode 5.31} +@center @titlefont{CC Mode 5.32} @sp 2 @center @subtitlefont{A GNU Emacs mode for editing C and C-like languages} @sp 2 @@ -378,7 +378,7 @@ was added in version 5.30. This manual describes @ccmode{} @comment The following line must appear on its own, so that the -version 5.31. +version 5.32. @comment Release.py script can update the version number automatically @ccmode{} supports the editing of K&R and ANSI C, C++, Objective-C, diff --git a/doc/misc/cl.texi b/doc/misc/cl.texi index 3f3d616e343..594253e2c0a 100644 --- a/doc/misc/cl.texi +++ b/doc/misc/cl.texi @@ -5,7 +5,7 @@ @copying This file documents the GNU Emacs Common Lisp emulation package. -Copyright @copyright{} 1993, 2001-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1993, 2001-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/dbus.texi b/doc/misc/dbus.texi index 06a52107d71..71f60af530b 100644 --- a/doc/misc/dbus.texi +++ b/doc/misc/dbus.texi @@ -9,7 +9,7 @@ @syncodeindex fn cp @copying -Copyright @copyright{} 2007-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2007-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1677,7 +1677,7 @@ Establish the connection to D-Bus @var{bus}. @var{bus} can be either the symbol @code{:system} or the symbol @code{:session}, or it can be a string denoting the address of the -corresponding bus. For the system and session busses, this function +corresponding bus. For the system and session buses, this function is called when loading @file{dbus.el}, there is no need to call it again. diff --git a/doc/misc/dired-x.texi b/doc/misc/dired-x.texi index a026c63e25b..95c129f411d 100644 --- a/doc/misc/dired-x.texi +++ b/doc/misc/dired-x.texi @@ -19,7 +19,7 @@ @comment %**end of header (This is for running Texinfo on a region.) @copying -Copyright @copyright{} 1994-1995, 1999, 2001-2011 +Copyright @copyright{} 1994-1995, 1999, 2001-2012 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/ebrowse.texi b/doc/misc/ebrowse.texi index a2a4017eb64..cf716f4e031 100644 --- a/doc/misc/ebrowse.texi +++ b/doc/misc/ebrowse.texi @@ -10,7 +10,7 @@ @copying This file documents Ebrowse, a C++ class browser for GNU Emacs. -Copyright @copyright{} 2000-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2000-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/ede.texi b/doc/misc/ede.texi index cc566086f44..bc6e3281bb7 100644 --- a/doc/misc/ede.texi +++ b/doc/misc/ede.texi @@ -5,7 +5,7 @@ @copying This file describes EDE, the Emacs Development Environment. -Copyright @copyright{} 1998-2001, 2004-2005, 2008-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1998-2001, 2004-2005, 2008-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -705,11 +705,11 @@ A brief description of the project or target. This is currently used by the @samp{ede-speedbar} interface. @item ede-want-file-p Return non-nil if a target will accept a given file. -It is generally unecessary to override this. See the section on source +It is generally unnecessary to override this. See the section on source code. @item ede-buffer-mine Return non-nil if a buffer belongs to this target. Used during -association when a file is loaded. It is generally unecessary to +association when a file is loaded. It is generally unnecessary to override this unless you keep auxiliary files. @end table @@ -2483,7 +2483,7 @@ Create the make rule needed to create an archive for @var{THIS}. @deffn Method ede-proj-makefile-insert-source-variables :PRIMARY this Insert bin_PROGRAMS variables needed by target @var{THIS}. -We aren't acutally inserting SOURCE details, but this is used by the +We aren't actually inserting SOURCE details, but this is used by the Makefile.am generator, so use it to add this important bin program. @end deffn @@ -2624,7 +2624,7 @@ Return the name of the main target for @var{THIS} target. @deffn Method ede-proj-makefile-insert-automake-pre-variables :AFTER this Insert bin_PROGRAMS variables needed by target @var{THIS}. -We aren't acutally inserting SOURCE details, but this is used by the +We aren't actually inserting SOURCE details, but this is used by the Makefile.am generator, so use it to add this important bin program. @end deffn diff --git a/doc/misc/ediff.texi b/doc/misc/ediff.texi index 62cd684b57b..1e9ecf07a14 100644 --- a/doc/misc/ediff.texi +++ b/doc/misc/ediff.texi @@ -25,7 +25,7 @@ This file documents Ediff, a comprehensive visual interface to Unix diff and patch utilities. -Copyright @copyright{} 1995-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1995-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/edt.texi b/doc/misc/edt.texi index 8f9f8fc03a2..af0069fb1bc 100644 --- a/doc/misc/edt.texi +++ b/doc/misc/edt.texi @@ -5,7 +5,7 @@ @copying This file documents the EDT emulation package for Emacs. -Copyright @copyright{} 1986, 1992, 1994-1995, 1999-2011 +Copyright @copyright{} 1986, 1992, 1994-1995, 1999-2012 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi index d65c7a15f7b..c006e635a78 100644 --- a/doc/misc/eieio.texi +++ b/doc/misc/eieio.texi @@ -11,7 +11,7 @@ @copying This manual documents EIEIO, an object framework for Emacs Lisp. -Copyright @copyright{} 2007-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2007-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1893,7 +1893,7 @@ better in the Emacs environment. @enumerate @item -Allow subclasing of Emacs built-in types, such as faces, markers, and +Allow subclassing of Emacs built-in types, such as faces, markers, and buffers. @item Allow method overloading of method-like functions in Emacs. diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi index 91440dcfe8f..896eba2f1bb 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -11,7 +11,7 @@ @copying This file documents the Emacs MIME interface functionality. -Copyright @copyright{} 1998-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1998-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/epa.texi b/doc/misc/epa.texi index b4137a7dac6..bb5e18f1c8b 100644 --- a/doc/misc/epa.texi +++ b/doc/misc/epa.texi @@ -9,7 +9,7 @@ @copying This file describes EasyPG Assistant @value{VERSION}. -Copyright @copyright{} 2007-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2007-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/erc.texi b/doc/misc/erc.texi index b46748a08f9..6d791d7c5f6 100644 --- a/doc/misc/erc.texi +++ b/doc/misc/erc.texi @@ -8,7 +8,7 @@ @copying This manual is for ERC version 5.3. -Copyright @copyright{} 2005-2011 +Copyright @copyright{} 2005-2012 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index 00755262075..6002e678ff1 100644 --- a/doc/misc/ert.texi +++ b/doc/misc/ert.texi @@ -10,7 +10,7 @@ @end direntry @copying -Copyright @copyright{} 2008, 2010-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2008, 2010-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index 7c178757927..99fbf1a4fcf 100644 --- a/doc/misc/eshell.texi +++ b/doc/misc/eshell.texi @@ -8,7 +8,7 @@ @copying This manual is for Eshell, the Emacs shell. -Copyright @copyright{} 1999-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1999-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/eudc.texi b/doc/misc/eudc.texi index a68eda50025..dec178c5258 100644 --- a/doc/misc/eudc.texi +++ b/doc/misc/eudc.texi @@ -12,7 +12,7 @@ EUDC is the Emacs Unified Directory Client, a common interface to directory servers using various protocols such as LDAP or the CCSO white pages directory system (PH/QI) -Copyright @copyright{} 1998, 2000-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1998, 2000-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/faq.texi b/doc/misc/faq.texi index 15c9232d4b6..5b7bb7ec9ce 100644 --- a/doc/misc/faq.texi +++ b/doc/misc/faq.texi @@ -11,7 +11,7 @@ @c appreciate a notice if you do). @copying -Copyright @copyright{} 2001-2011 Free Software Foundation, Inc.@* +Copyright @copyright{} 2001-2012 Free Software Foundation, Inc.@* Copyright @copyright{} 1994, 1995, 1996, 1997, 1998, 1999, 2000 Reuven M. Lerner@* Copyright @copyright{} 1992, 1993 Steven Byrnes@* diff --git a/doc/misc/flymake.texi b/doc/misc/flymake.texi index 625e9549444..687a2f7b4d4 100644 --- a/doc/misc/flymake.texi +++ b/doc/misc/flymake.texi @@ -11,7 +11,7 @@ This manual is for GNU Flymake (version @value{VERSION}, @value{UPDATED}), which is a universal on-the-fly syntax checker for GNU Emacs. -Copyright @copyright{} 2004-2011 +Copyright @copyright{} 2004-2012 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/forms.texi b/doc/misc/forms.texi index 17c1d7feaf0..34c418c14fd 100644 --- a/doc/misc/forms.texi +++ b/doc/misc/forms.texi @@ -18,7 +18,7 @@ @copying This file documents Forms mode, a form-editing major mode for GNU Emacs. -Copyright @copyright{} 1989, 1997, 2001-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1989, 1997, 2001-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/gnus-coding.texi b/doc/misc/gnus-coding.texi index a79c68f0123..bbaf2c068da 100644 --- a/doc/misc/gnus-coding.texi +++ b/doc/misc/gnus-coding.texi @@ -7,7 +7,7 @@ @syncodeindex pg cp @copying -Copyright @copyright{} 2004-2005, 2007-2011 Free Software +Copyright @copyright{} 2004-2005, 2007-2012 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/gnus-faq.texi b/doc/misc/gnus-faq.texi index 7bd3e4ac7fa..ae6373e9a6e 100644 --- a/doc/misc/gnus-faq.texi +++ b/doc/misc/gnus-faq.texi @@ -1,7 +1,7 @@ @c \input texinfo @c -*-texinfo-*- @c Uncomment 1st line before texing this file alone. @c %**start of header -@c Copyright (C) 1995, 2001-2011 Free Software Foundation, Inc. +@c Copyright (C) 1995, 2001-2012 Free Software Foundation, Inc. @c @setfilename gnus-faq.info @settitle Frequently Asked Questions diff --git a/doc/misc/gnus-news.el b/doc/misc/gnus-news.el index 485e7ce4646..0c083c85a4d 100644 --- a/doc/misc/gnus-news.el +++ b/doc/misc/gnus-news.el @@ -1,5 +1,5 @@ ;;; gnus-news.el --- a hack to create GNUS-NEWS from texinfo source -;; Copyright (C) 2004-2011 Free Software Foundation, Inc. +;; Copyright (C) 2004-2012 Free Software Foundation, Inc. ;; Author: Reiner Steib <Reiner.Steib@gmx.de> ;; Keywords: tools @@ -26,7 +26,7 @@ (defvar gnus-news-header-disclaimer "GNUS NEWS -- history of user-visible changes. -Copyright (C) 1999-2011 Free Software Foundation, Inc. +Copyright (C) 1999-2012 Free Software Foundation, Inc. See the end of the file for license conditions. Please send Gnus bug reports to bugs@gnus.org. diff --git a/doc/misc/gnus-news.texi b/doc/misc/gnus-news.texi index 612ea14e2cf..5421e64625a 100644 --- a/doc/misc/gnus-news.texi +++ b/doc/misc/gnus-news.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- -@c Copyright (C) 2004-2011 Free Software Foundation, Inc. +@c Copyright (C) 2004-2012 Free Software Foundation, Inc. @c Permission is granted to anyone to make or distribute verbatim copies @c of this document as received, in any medium, provided that the diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index 68c7e8bbdbc..7728041c83b 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -11,7 +11,7 @@ @documentencoding ISO-8859-1 @copying -Copyright @copyright{} 1995-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1995-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -1328,7 +1328,7 @@ variable to @code{nil}. @vindex gnus-auto-subscribed-categories As if that wasn't enough, @code{gnus-auto-subscribed-categories} also -allows you to specify that new groups should be subcribed based on the +allows you to specify that new groups should be subscribed based on the category their select methods belong to. The default is @samp{(mail post-mail)}, meaning that all new groups from mail-like backends should be subscribed automatically. @@ -3180,15 +3180,20 @@ For example: (to-group . "\\1")) ("mail\\.me" - (gnus-use-scoring t)) + (gnus-use-scoring t)) ("list\\..*" (total-expire . t) (broken-reply-to . t)))) @end lisp -String value of parameters will be subjected to regexp substitution, as -the @code{to-group} example shows. +All clauses that matches the group name will be used, but the last +setting ``wins''. So if you have two clauses that both match the +group name, and both set, say @code{display}, the last setting will +override the first. + +Parameters that are strings will be subjected to regexp substitution, +as the @code{to-group} example shows. @vindex gnus-parameters-case-fold-search By default, whether comparing the group name and one of those regexps @@ -11634,7 +11639,7 @@ message/external-body @acronym{MIME} type. @item r (Article) @kindex r (Article) Prompt for a file name, replace the @acronym{MIME} object with an -external body refering to the file via the message/external-body +external body referring to the file via the message/external-body @acronym{MIME} type. (@code{gnus-mime-replace-part}). @findex gnus-mime-delete-part @@ -15033,7 +15038,7 @@ number. @item mail-source-default-file-modes @vindex mail-source-default-file-modes -All new mail files will get this file mode. The default is 384. +All new mail files will get this file mode. The default is @code{#o600}. @item mail-source-movemail-program @vindex mail-source-movemail-program @@ -15123,10 +15128,10 @@ default file modes the new mail files get: @lisp (add-hook 'nnmail-pre-get-new-mail-hook - (lambda () (set-default-file-modes 511))) + (lambda () (set-default-file-modes #o700))) (add-hook 'nnmail-post-get-new-mail-hook - (lambda () (set-default-file-modes 551))) + (lambda () (set-default-file-modes #o775))) @end lisp @item nnmail-use-long-file-names @@ -20043,7 +20048,7 @@ matches will use the @code{Message-ID}s of these matching articles.) This will ensure that you can raise/lower the score of an entire thread, even though some articles in the thread may not have complete @code{References} headers. Note that using this may lead to -undeterministic scores of the articles in the thread. (Using this match +nondeterministic scores of the articles in the thread. (Using this match key will lead to creation of @file{ADAPT} files.) @end table @end enumerate @@ -30012,7 +30017,7 @@ this: @node Score File Syntax @subsection Score File Syntax -Score files are meant to be easily parseable, but yet extremely +Score files are meant to be easily parsable, but yet extremely malleable. It was decided that something that had the same read syntax as an Emacs Lisp list would fit that spec. diff --git a/doc/misc/idlwave.texi b/doc/misc/idlwave.texi index 5149eb91651..5423ff2e74f 100644 --- a/doc/misc/idlwave.texi +++ b/doc/misc/idlwave.texi @@ -22,7 +22,7 @@ Emacs, and interacting with an IDL shell run as a subprocess. This is edition @value{EDITION} of the IDLWAVE User Manual for IDLWAVE @value{VERSION}. -Copyright @copyright{} 1999-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1999-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -669,7 +669,7 @@ We have already used the routine info display in the first part of this tutorial. This was the invoked using @kbd{C-c ?}, and displays information about the IDL routine near the cursor position. Wouldn't it be nice to have the same kind of information available for your own -routines and for the huge amount of code in major libraries like JHUPL +routines and for the huge amount of code in major libraries like JHUAPL or the IDL-Astro library? In many cases, you may already have this information. Files named @file{.idlwave_catalog} in library directories contain scanned information on the routines in that directory; many diff --git a/doc/misc/info.texi b/doc/misc/info.texi index 68390a2f0cc..7ce874d2941 100644 --- a/doc/misc/info.texi +++ b/doc/misc/info.texi @@ -14,7 +14,7 @@ This file describes how to use Info, the on-line, menu-driven GNU documentation system. -Copyright @copyright{} 1989, 1992, 1996-2011 +Copyright @copyright{} 1989, 1992, 1996-2012 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/mairix-el.texi b/doc/misc/mairix-el.texi index d64f316cb7b..468283ffd93 100644 --- a/doc/misc/mairix-el.texi +++ b/doc/misc/mairix-el.texi @@ -6,7 +6,7 @@ @documentencoding ISO-8859-1 @copying -Copyright @copyright{} 2008-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2008-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/makefile.w32-in b/doc/misc/makefile.w32-in index 0edaf3db3d6..6e4a65c292c 100644 --- a/doc/misc/makefile.w32-in +++ b/doc/misc/makefile.w32-in @@ -1,6 +1,6 @@ #### -*- Makefile -*- for documentation other than 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/misc/message.texi b/doc/misc/message.texi index 774bf180266..7ed5f6a92a5 100644 --- a/doc/misc/message.texi +++ b/doc/misc/message.texi @@ -10,7 +10,7 @@ @copying This file documents Message, the Emacs message composition mode. -Copyright @copyright{} 1996-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1996-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/mh-e.texi b/doc/misc/mh-e.texi index 4e63410f4a0..538c3f1ba82 100644 --- a/doc/misc/mh-e.texi +++ b/doc/misc/mh-e.texi @@ -24,7 +24,7 @@ This is version @value{VERSION}@value{EDITION} of @cite{The MH-E Manual}, last updated @value{UPDATED}. -Copyright @copyright{} 1995, 2001-2003, 2005-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1995, 2001-2003, 2005-2012 Free Software Foundation, Inc. @c This dual license has been agreed upon by the FSF. diff --git a/doc/misc/newsticker.texi b/doc/misc/newsticker.texi index 18e11aeeeb3..9b61e8f6f3a 100644 --- a/doc/misc/newsticker.texi +++ b/doc/misc/newsticker.texi @@ -13,7 +13,7 @@ This manual is for Newsticker (version @value{VERSION}, @value{UPDATED}). @noindent -Copyright @copyright{} 2004-2011 +Copyright @copyright{} 2004-2012 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/nxml-mode.texi b/doc/misc/nxml-mode.texi index 27603440413..5141ed0e93d 100644 --- a/doc/misc/nxml-mode.texi +++ b/doc/misc/nxml-mode.texi @@ -8,7 +8,7 @@ This manual documents nxml-mode, an Emacs major mode for editing XML with RELAX NG support. -Copyright @copyright{} 2007-2011 +Copyright @copyright{} 2007-2012 Free Software Foundation, Inc. @quotation @@ -878,7 +878,7 @@ the document in different ways, since the XML Recommendation does not require XML parsers to read the DTD. With DTDs, it was impractical to get validation without using an external DTD or reference to an parameter entity. With RELAX NG and other schema languages, you can -simulataneously get the benefits of validation and standalone XML +simultaneously get the benefits of validation and standalone XML documents. Therefore, I recommend that you do not reference an external DOCTYPE in your XML documents. @@ -908,4 +908,3 @@ specification are not enforced. @end itemize @bye - diff --git a/doc/misc/org.texi b/doc/misc/org.texi index a6fae5e216f..bc82e0ba7fe 100644 --- a/doc/misc/org.texi +++ b/doc/misc/org.texi @@ -4,8 +4,8 @@ @setfilename ../../info/org @settitle The Org Manual -@set VERSION 7.7 -@set DATE July 2011 +@set VERSION 7.8.03 +@set DATE January 2012 @c Use proper quote and backtick for code sections in PDF output @c Cf. Texinfo manual 14.2 @@ -36,7 +36,7 @@ @c orgkey{key} A key item @c orgcmd{key,cmd} Key with command name -@c xorgcmd{key,command} Key with command name as @itemx +@c xorgcmd{key,cmmand} Key with command name as @itemx @c orgcmdnki{key,cmd} Like orgcmd, but do not index the key @c orgcmdtkc{text,key,cmd} Like orgcmd,special text instead of key @c orgcmdkkc{key1,key2,cmd} Two keys with one command name, use "or" @@ -265,7 +265,7 @@ @copying This manual is for Org version @value{VERSION}. -Copyright @copyright{} 2004-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2004-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -296,7 +296,7 @@ license to the document, as described in section 6 of the license. @subtitle Release @value{VERSION} @author by Carsten Dominik -with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, and Thomas Dye +with contributions by David O'Toole, Bastien Guerry, Philip Rooke, Dan Davison, Eric Schulte, Thomas Dye and Jambunathan K. @c The following two commands start the copyright page. @page @@ -382,7 +382,7 @@ The spreadsheet * Column formulas:: Formulas valid for an entire column * Editing and debugging formulas:: Fixing formulas * Updating the table:: Recomputing all dependent fields -* Advanced features:: Field names, parameters and automatic recalc +* Advanced features:: Field and column names, parameters and automatic recalc Hyperlinks @@ -433,7 +433,7 @@ Tags Properties and columns * Property syntax:: How properties are spelled out -* Special properties:: Access to other Org-mode features +* Special properties:: Access to other Org mode features * Property searches:: Matching property values * Property inheritance:: Passing values down the tree * Column view:: Tabular viewing and editing @@ -462,7 +462,7 @@ Dates and times Creating timestamps -* The date/time prompt:: How Org-mode helps you entering date and time +* The date/time prompt:: How Org mode helps you entering date and time * Custom time format:: Making dates look different Deadlines and scheduling @@ -541,7 +541,7 @@ Markup for rich export * Include files:: Include additional files into a document * Index entries:: Making an index * Macro replacement:: Use macros to create complex output -* Embedded LaTeX:: LaTeX can be freely used inside Org documents +* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents Structural markup elements @@ -560,8 +560,8 @@ Embedded @LaTeX{} * Special symbols:: Greek letters and other symbols * Subscripts and superscripts:: Simple syntax for raising/lowering text -* LaTeX fragments:: Complex formulas made easy -* Previewing LaTeX fragments:: What will this snippet look like? +* @LaTeX{} fragments:: Complex formulas made easy +* Previewing @LaTeX{} fragments:: What will this snippet look like? * CDLaTeX mode:: Speed up entering of formulas Exporting @@ -571,9 +571,9 @@ Exporting * The export dispatcher:: How to access exporter commands * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding * HTML export:: Exporting to HTML -* LaTeX and PDF export:: Exporting to @LaTeX{}, and processing to PDF +* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF * DocBook export:: Exporting to DocBook -* OpenDocumentText export:: Exporting to OpenDocumentText +* OpenDocument Text export:: Exporting to OpenDocument Text * TaskJuggler export:: Exporting to TaskJuggler * Freemind export:: Exporting to Freemind mind maps * XOXO export:: Exporting to XOXO @@ -583,7 +583,7 @@ HTML export * HTML Export commands:: How to invoke HTML export * HTML preamble and postamble:: How to insert a preamble and a postamble -* Quoting HTML tags:: Using direct HTML in Org-mode +* Quoting HTML tags:: Using direct HTML in Org mode * Links in HTML export:: How links will be interpreted and formatted * Tables in HTML export:: How to modify the formatting of tables * Images in HTML export:: How to insert figures into HTML output @@ -594,11 +594,11 @@ HTML export @LaTeX{} and PDF export -* LaTeX/PDF export commands:: Which key invokes which commands +* @LaTeX{}/PDF export commands:: * Header and sectioning:: Setting up the export file structure -* Quoting LaTeX code:: Incorporating literal @LaTeX{} code -* Tables in LaTeX export:: Options for exporting tables to @LaTeX{} -* Images in LaTeX export:: How to insert figures into @LaTeX{} output +* Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code +* Tables in @LaTeX{} export:: Options for exporting tables to @LaTeX{} +* Images in @LaTeX{} export:: How to insert figures into @LaTeX{} output * Beamer class export:: Turning the file into a presentation DocBook export @@ -610,15 +610,30 @@ DocBook export * Images in DocBook export:: How to insert figures into DocBook output * Special characters:: How to handle special characters -OpenDocument export +OpenDocument Text export -* OpenDocumentText export commands:: How to invoke OpenDocumentText export -* Applying Custom Styles:: How to apply custom styles to the output -* Converting to Other formats:: How to convert to formats like doc, docx etc -* Links in OpenDocumentText export:: How links will be interpreted and formatted -* Tables in OpenDocumentText export:: How Tables are handled -* Images in OpenDocumentText export:: How to insert figures -* Additional Documentation:: How to handle special characters +* Pre-requisites for @acronym{ODT} export:: What packages @acronym{ODT} exporter relies on +* @acronym{ODT} export commands:: How to invoke @acronym{ODT} export +* Applying custom styles:: How to apply custom styles to the output +* Links in @acronym{ODT} export:: How links will be interpreted and formatted +* Tables in @acronym{ODT} export:: How Tables are exported +* Images in @acronym{ODT} export:: How to insert images +* Math formatting in @acronym{ODT} export:: How @LaTeX{} fragments are formatted +* Literal examples in @acronym{ODT} export:: How source and example blocks are formatted +* Advanced topics in @acronym{ODT} export:: Read this if you are a power user + +Math formatting in @acronym{ODT} export + +* Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments +* Working with MathML or OpenDocument formula files:: How to embed equations in native format + +Advanced topics in @acronym{ODT} export + +* Exporting and converting to other formats:: How to produce @samp{pdf} and other formats +* Working with OpenDocument style files:: Explore the internals +* Creating one-off styles:: How to produce custom highlighting etc +* Customizing tables in @acronym{ODT} export:: How to define and use Table templates +* Validating OpenDocument XML:: How to debug corrupt OpenDocument files Publishing @@ -649,12 +664,12 @@ Working with source code * Editing source code:: Language major-mode editing * Exporting code blocks:: Export contents and/or results * Extracting source code:: Create pure source code files -* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer +* Evaluating code blocks:: Place results of evaluation in the Org mode buffer * Library of Babel:: Use and contribute to a library of useful code blocks * Languages:: List of supported code block languages * Header arguments:: Configure code block functionality * Results of evaluation:: How evaluation results are handled -* Noweb reference syntax:: Literate programming in Org-mode +* Noweb reference syntax:: Literate programming in Org mode * Key bindings and useful functions:: Work quickly with code blocks * Batch execution:: Call functions from the command line @@ -668,7 +683,7 @@ Using header arguments * System-wide header arguments:: Set global default values * Language-specific header arguments:: Set default values by language * Buffer-wide header arguments:: Set default values for a specific buffer -* Header arguments in Org-mode properties:: Set default values for a buffer or heading +* Header arguments in Org mode properties:: Set default values for a buffer or heading * Code block specific header arguments:: The most common way to set values * Header arguments in function calls:: The most specific level @@ -736,7 +751,7 @@ Hacking Tables and lists in arbitrary syntax * Radio tables:: Sending and receiving radio tables -* A LaTeX example:: Step by step, almost a tutorial +* A @LaTeX{} example:: Step by step, almost a tutorial * Translator functions:: Copy and modify * Radio lists:: Doing the same for lists @@ -898,7 +913,7 @@ make install-info Then add the following line to @file{.emacs}. It is needed so that Emacs can autoload functions that are located in files not immediately loaded -when Org-mode starts. +when Org mode starts. @lisp (require 'org-install) @end lisp @@ -934,9 +949,9 @@ liking. (global-set-key "\C-cb" 'org-iswitchb) @end lisp -@cindex Org-mode, turning on +@cindex Org mode, turning on With this setup, all files with extension @samp{.org} will be put -into Org-mode. As an alternative, make the first line of a file look +into Org mode. As an alternative, make the first line of a file look like this: @example @@ -944,7 +959,7 @@ MY PROJECTS -*- mode: org; -*- @end example @vindex org-insert-mode-line-in-empty-file -@noindent which will select Org-mode for this buffer no matter what +@noindent which will select Org mode for this buffer no matter what the file's name is. See also the variable @code{org-insert-mode-line-in-empty-file}. @@ -987,6 +1002,36 @@ version information of Emacs (@kbd{M-x emacs-version @key{RET}}) and Org that you only need to add your description. If you re not sending the Email from within Emacs, please copy and paste the content into your Email program. +Sometimes you might face a problem due to an error in your Emacs or Org mode +setup. Before reporting a bug, it is very helpful to start Emacs with minimal +customisations and reproduce the problem. Doing so often helps you determine +if the problem is with your customisation or with Org mode itself. You can +start a typical minimal session with a command like the example below. + +@example +$ emacs -Q -l /path/to/minimal-org.el +@end example + +However if you are using Org mode as distributed with Emacs, a minimal setup +is not necessary. In that case it is sufficient to start Emacs as @code{emacs +-Q}. The @code{minimal-org.el} setup file can have contents as shown below. + +@example +;;; Minimal setup to load latest `org-mode' + +;; activate debugging +(setq debug-on-error t + debug-on-signal nil + debug-on-quit nil) + +;; add latest org-mode to load path +(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp")) +(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp")) + +;; activate org +(require 'org-install) +@end example + If an error occurs, a backtrace can be very useful (see below on how to create one). Often a small example file helps, along with clear information about: @@ -1009,7 +1054,7 @@ error occurred. Here is how to produce a useful backtrace: @enumerate @item -Reload uncompiled versions of all Org-mode Lisp files. The backtrace +Reload uncompiled versions of all Org mode Lisp files. The backtrace contains much more information if it is produced with uncompiled code. To do this, use @example @@ -1196,8 +1241,8 @@ Reveal context around point, showing the current entry, the following heading and the hierarchy above. Useful for working near a location that has been exposed by a sparse tree command (@pxref{Sparse trees}) or an agenda command (@pxref{Agenda commands}). With a prefix argument show, on each -level, all sibling headings. With double prefix arg, also show the entire -subtree of the parent. +level, all sibling headings. With a double prefix argument, also show the +entire subtree of the parent. @orgcmd{C-c C-k,show-branches} Expose all the headings of the subtree, CONTENT view for just one subtree. @orgcmd{C-c C-x b,org-tree-to-indirect-buffer} @@ -1430,7 +1475,7 @@ functionality. @vindex org-show-following-heading @vindex org-show-siblings @vindex org-show-entry-below -An important feature of Org-mode is the ability to construct @emph{sparse +An important feature of Org mode is the ability to construct @emph{sparse trees} for selected information in an outline tree, so that the entire document is folded as much as possible, but the selected information is made visible along with the headline structure above it@footnote{See also the @@ -1439,7 +1484,7 @@ variables @code{org-show-hierarchy-above}, @code{org-show-following-heading}, control on how much context is shown around each match.}. Just try it out and you will see immediately how it works. -Org-mode contains several commands creating such trees, all these +Org mode contains several commands creating such trees, all these commands can be accessed through a dispatcher: @table @asis @@ -1597,14 +1642,18 @@ to disable them individually. @table @asis @orgcmd{@key{TAB},org-cycle} +@cindex cycling, in plain lists @vindex org-cycle-include-plain-lists Items can be folded just like headline levels. Normally this works only if the cursor is on a plain list item. For more details, see the variable @code{org-cycle-include-plain-lists}. If this variable is set to @code{integrate}, plain list items will be treated like low-level -headlines. The level of an item is then given by the -indentation of the bullet/number. Items are always subordinate to real -headlines, however; the hierarchies remain completely separated. +headlines. The level of an item is then given by the indentation of the +bullet/number. Items are always subordinate to real headlines, however; the +hierarchies remain completely separated. In a new item with no text yet, the +first @key{TAB} demotes the item to become a child of the previous +one. Subsequent @key{TAB}s move the item to meaningful levels in the list +and eventually get it back to its initial position. @orgcmd{M-@key{RET},org-insert-heading} @vindex org-M-RET-may-split-line @vindex org-list-automatic-rules @@ -1615,17 +1664,15 @@ new item@footnote{If you do not want the item to be split, customize the variable @code{org-M-RET-may-split-line}.}. If this command is executed @emph{before item's body}, the new item is created @emph{before} the current one. +@end table + +@table @kbd @kindex M-S-@key{RET} -@item M-S-@key{RET} +@item M-S-RET Insert a new item with a checkbox (@pxref{Checkboxes}). -@orgcmd{@key{TAB},org-cycle} -In a new item with no text yet, the first @key{TAB} demotes the item to -become a child of the previous one. Subsequent @key{TAB}s move the item to -meaningful levels in the list and eventually get it back to its initial -position. @kindex S-@key{down} -@item S-@key{up} -@itemx S-@key{down} +@item S-up +@itemx S-down @cindex shift-selection-mode @vindex org-support-shift-select @vindex org-list-use-circular-motion @@ -1637,21 +1684,21 @@ jumping commands like @kbd{C-@key{up}} and @kbd{C-@key{down}} to quite similar effect. @kindex M-@key{up} @kindex M-@key{down} -@item M-@key{up} -@itemx M-@key{down} +@item M-up +@itemx M-down Move the item including subitems up/down@footnote{See @code{org-liste-use-circular-motion} for a cyclic behavior.} (swap with previous/next item of same indentation). If the list is ordered, renumbering is automatic. @kindex M-@key{left} @kindex M-@key{right} -@item M-@key{left} -@itemx M-@key{right} +@item M-left +@itemx M-right Decrease/increase the indentation of an item, leaving children alone. @kindex M-S-@key{left} @kindex M-S-@key{right} -@item M-S-@key{left} -@itemx M-S-@key{right} +@item M-S-left +@itemx M-S-right Decrease/increase the indentation of the item, including subitems. Initially, the item tree is selected based on current indentation. When these commands are executed several times in direct succession, the initially @@ -1694,7 +1741,7 @@ Turn the whole plain list into a subtree of the current heading. Checkboxes (resp. checked). @kindex S-@key{left} @kindex S-@key{right} -@item S-@key{left}/@key{right} +@item S-left/right @vindex org-support-shift-select This command also cycles bullet styles when the cursor in on the bullet or anywhere in an item line, details depending on @@ -1713,7 +1760,7 @@ numerically, alphabetically, by time, or by custom function. @vindex org-drawers Sometimes you want to keep information associated with an entry, but you -normally don't want to see it. For this, Org-mode has @emph{drawers}. +normally don't want to see it. For this, Org mode has @emph{drawers}. Drawers need to be configured with the variable @code{org-drawers}@footnote{You can define drawers on a per-file basis with a line like @code{#+DRAWERS: HIDDEN PROPERTIES STATE}}. Drawers @@ -1731,7 +1778,7 @@ look like this: Visibility cycling (@pxref{Visibility cycling}) on the headline will hide and show the entry, but keep the drawer collapsed to a single line. In order to look inside the drawer, you need to move the cursor to the drawer line and -press @key{TAB} there. Org-mode uses the @code{PROPERTIES} drawer for +press @key{TAB} there. Org mode uses the @code{PROPERTIES} drawer for storing properties (@pxref{Properties and Columns}), and you can also arrange for state change notes (@pxref{Tracking TODO state changes}) and clock times (@pxref{Clocking work time}) to be stored in a drawer @code{LOGBOOK}. If you @@ -1748,7 +1795,7 @@ Add a time-stamped note to the LOGBOOK drawer. @vindex org-hide-block-startup @cindex blocks, folding -Org-mode uses begin...end blocks for various purposes from including source +Org mode uses begin...end blocks for various purposes from including source code examples (@pxref{Literal examples}) to capturing time logging information (@pxref{Clocking work time}). These blocks can be folded and unfolded by pressing TAB in the begin line. You can also get all blocks @@ -1766,8 +1813,8 @@ or on a per-file basis by using @section Footnotes @cindex footnotes -Org-mode supports the creation of footnotes. In contrast to the -@file{footnote.el} package, Org-mode's footnotes are designed for work on a +Org mode supports the creation of footnotes. In contrast to the +@file{footnote.el} package, Org mode's footnotes are designed for work on a larger document, not only for one-off documents like emails. The basic syntax is similar to the one used by @file{footnote.el}, i.e.@: a footnote is defined in a paragraph that is started by a footnote marker in square @@ -1781,11 +1828,11 @@ The Org homepage[fn:1] now looks a lot better than it used to. [fn:1] The link is: http://orgmode.org @end example -Org-mode extends the number-based syntax to @emph{named} footnotes and +Org mode extends the number-based syntax to @emph{named} footnotes and optional inline definition. Using plain numbers as markers (as @file{footnote.el} does) is supported for backward compatibility, but not encouraged because of possible conflicts with @LaTeX{} snippets (@pxref{Embedded -LaTeX}). Here are the valid references: +@LaTeX{}}). Here are the valid references: @table @code @item [1] @@ -1875,7 +1922,7 @@ you can use the usual commands to follow these links. @cindex Orgstruct mode @cindex minor mode for structure editing -If you like the intuitive way the Org-mode structure editing and list +If you like the intuitive way the Org mode structure editing and list formatting works, you might want to use these commands in other modes like Text mode or Mail mode as well. The minor mode @code{orgstruct-mode} makes this possible. Toggle the mode with @kbd{M-x orgstruct-mode}, or @@ -2276,7 +2323,7 @@ formula, moving these references by arrow keys * Column formulas:: Formulas valid for an entire column * Editing and debugging formulas:: Fixing formulas * Updating the table:: Recomputing all dependent fields -* Advanced features:: Field names, parameters and automatic recalc +* Advanced features:: Field and column names, parameters and automatic recalc @end menu @node References, Formula syntax for Calc, The spreadsheet, The spreadsheet @@ -2833,9 +2880,11 @@ dependencies. @node Advanced features, , Updating the table, The spreadsheet @subsection Advanced features -If you want the recalculation of fields to happen automatically, or if -you want to be able to assign @i{names} to fields and columns, you need -to reserve the first column of the table for special marking characters. +If you want the recalculation of fields to happen automatically, or if you +want to be able to assign @i{names}@footnote{Such names must start by an +alphabetic character and use only alphanumeric/underscore characters.} to +fields and columns, you need to reserve the first column of the table for +special marking characters. @table @kbd @orgcmd{C-#,org-table-rotate-recalc-marks} @@ -3005,7 +3054,7 @@ When plotting @code{3d} or @code{grid} types, set this to @code{t} to graph a flat mapping rather than a @code{3d} slope. @item timefmt -Specify format of Org-mode timestamps as they will be parsed by Gnuplot. +Specify format of Org mode timestamps as they will be parsed by Gnuplot. Defaults to @samp{%Y-%m-%d-%H:%M:%S}. @item script @@ -3168,11 +3217,19 @@ file:papers/last.pdf @r{file, relative path} ./papers/last.pdf @r{same as above} file:/myself@@some.where:papers/last.pdf @r{file, path on remote machine} /myself@@some.where:papers/last.pdf @r{same as above} -file:sometextfile::NNN @r{file with line number to jump to} +file:sometextfile::NNN @r{file, jump to line number} file:projects.org @r{another Org file} -file:projects.org::some words @r{text search in Org file} +file:projects.org::some words @r{text search in Org file}@footnote{ +The actual behavior of the search will depend on the value of +the variable @code{org-link-search-must-match-exact-headline}. If its value +is nil, then a fuzzy text search will be done. If it is t, then only the +exact headline will be matched. If the value is @code{'query-to-create}, +then an exact headline will be searched; if it is not found, then the user +will be queried to create it.} file:projects.org::*task title @r{heading search in Org file} -docview:papers/last.pdf::NNN @r{open file in doc-view mode at page NNN} +file+sys:/path/to/file @r{open via OS, like double-click} +file+emacs:/path/to/file @r{force opening by Emacs} +docview:papers/last.pdf::NNN @r{open in doc-view mode at page} id:B7423F4D-2E8A-471B-8810-C40F074717E9 @r{Link to heading by ID} news:comp.emacs @r{Usenet link} mailto:adent@@galaxy.net @r{Mail link} @@ -3189,7 +3246,7 @@ gnus:group @r{Gnus group link} gnus:group#id @r{Gnus article link} bbdb:R.*Stallman @r{BBDB link (with regexp)} irc:/irc.com/#emacs/bob @r{IRC link} -info:org#External%20links @r{Info node link (with encoded space)} +info:org#External links @r{Info node link} shell:ls *.org @r{A shell command} elisp:org-agenda @r{Interactive Elisp command} elisp:(find-file-other-frame "Elisp.org") @r{Elisp form to evaluate} @@ -3235,7 +3292,7 @@ create a link. The link will be stored for later insertion into an Org buffer (see below). What kind of link will be created depends on the current buffer: -@b{Org-mode buffers}@* +@b{Org mode buffers}@* For Org files, if there is a @samp{<<target>>} at the cursor, the link points to the target. Otherwise it points to the current headline, which will also be the description@footnote{If the headline contains a timestamp, it will be @@ -3338,6 +3395,7 @@ link and description parts of the link. @cindex following links @orgcmd{C-c C-o,org-open-at-point} @vindex org-file-apps +@vindex org-link-frame-setup Open link at point. This will launch a web browser for URLs (using @command{browse-url-at-point}), run VM/MH-E/Wanderlust/Rmail/Gnus/BBDB for the corresponding links, and execute the command in a shell link. When the @@ -3351,7 +3409,9 @@ Classification of files is based on file extension only. See option visit the file with Emacs, use a @kbd{C-u} prefix. If you want to avoid opening in Emacs, use a @kbd{C-u C-u} prefix.@* If the cursor is on a headline, but not on a link, offer all links in the -headline and entry text. +headline and entry text. If you want to setup the frame configuration for +following links, customize @code{org-link-frame-setup}. + @orgkey @key{RET} @vindex org-return-follows-link When @code{org-return-follows-link} is set, @kbd{@key{RET}} will also follow @@ -3525,7 +3585,7 @@ Link to a heading with a @code{CUSTOM_ID} property @item /regexp/ Do a regular expression search for @code{regexp}. This uses the Emacs command @code{occur} to list all matches in a separate window. If the -target file is in Org-mode, @code{org-occur} is used to create a +target file is in Org mode, @code{org-occur} is used to create a sparse tree with the matches. @c If the target file is a directory, @c @code{grep} will be used to search all files in the directory. @@ -3564,7 +3624,7 @@ an implementation example. See the file @file{org-bibtex.el}. @chapter TODO items @cindex TODO items -Org-mode does not maintain TODO lists as separate documents@footnote{Of +Org mode does not maintain TODO lists as separate documents@footnote{Of course, you can make a document that contains only long lists of TODO items, but this is not required.}. Instead, TODO items are an integral part of the notes file, because TODO items usually come up while taking notes! With Org @@ -3573,7 +3633,7 @@ information is not duplicated, and the entire context from which the TODO item emerged is always present. Of course, this technique for managing TODO items scatters them -throughout your notes file. Org-mode compensates for this by providing +throughout your notes file. Org mode compensates for this by providing methods to give you an overview of all the things that you have to do. @menu @@ -3659,7 +3719,7 @@ option @code{org-todo-state-tags-triggers} for details. @vindex org-todo-keywords By default, marked TODO entries have one of only two states: TODO and -DONE. Org-mode allows you to classify TODO items in more complex ways +DONE. Org mode allows you to classify TODO items in more complex ways with @emph{TODO keywords} (stored in @code{org-todo-keywords}). With special setup, the TODO keyword system can work differently in different files. @@ -3684,7 +3744,7 @@ TODO items in particular (@pxref{Tags}). You can use TODO keywords to indicate different @emph{sequential} states in the process of working on an item, for example@footnote{Changing -this variable only becomes effective after restarting Org-mode in a +this variable only becomes effective after restarting Org mode in a buffer.}: @lisp @@ -3727,7 +3787,7 @@ be set up like this: In this case, different keywords do not indicate a sequence, but rather different types. So the normal work flow would be to assign a task to a -person, and later to mark it DONE. Org-mode supports this style by adapting +person, and later to mark it DONE. Org mode supports this style by adapting the workings of the command @kbd{C-c C-t}@footnote{This is also true for the @kbd{t} command in the timeline and agenda buffers.}. When used several times in succession, it will still cycle through all names, in order to first @@ -3758,7 +3818,7 @@ like this: (sequence "|" "CANCELED"))) @end lisp -The keywords should all be different, this helps Org-mode to keep track +The keywords should all be different, this helps Org mode to keep track of which subsequence should be used for a given entry. In this setup, @kbd{C-c C-t} only operates within a subsequence, so it switches from @code{DONE} to (nothing) to @code{TODO}, and from @code{FIXED} to @@ -3855,9 +3915,9 @@ Remember that the keywords after the vertical bar (or the last keyword if no bar is there) must always mean that the item is DONE (although you may use a different word). After changing one of these lines, use @kbd{C-c C-c} with the cursor still in the line to make the changes -known to Org-mode@footnote{Org-mode parses these lines only when -Org-mode is activated after visiting a file. @kbd{C-c C-c} with the -cursor in a line starting with @samp{#+} is simply restarting Org-mode +known to Org mode@footnote{Org mode parses these lines only when +Org mode is activated after visiting a file. @kbd{C-c C-c} with the +cursor in a line starting with @samp{#+} is simply restarting Org mode for the current buffer.}. @node Faces for TODO keywords, TODO dependencies, Per-file keywords, TODO extensions @@ -3867,7 +3927,7 @@ for the current buffer.}. @vindex org-todo @r{(face)} @vindex org-done @r{(face)} @vindex org-todo-keyword-faces -Org-mode highlights TODO keywords with special faces: @code{org-todo} +Org mode highlights TODO keywords with special faces: @code{org-todo} for keywords indicating that an item still has to be acted upon, and @code{org-done} for keywords indicating that an item is finished. If you are using more than 2 different states, you might want to use @@ -3883,7 +3943,7 @@ special faces for some of them. This can be done using the variable @end lisp While using a list with face properties as shown for CANCELED @emph{should} -work, this does not always seem to be the case. If necessary, define a +work, this does not aways seem to be the case. If necessary, define a special face and use that. A string is interpreted as a color. The variable @code{org-faces-easy-properties} determines if that color is interpreted as a foreground or a background color. @@ -3955,7 +4015,7 @@ module @file{org-depend.el}. @cindex progress logging @cindex logging, of progress -Org-mode can automatically record a timestamp and possibly a note when +Org mode can automatically record a timestamp and possibly a note when you mark a TODO item as DONE, or even each time you change the state of a TODO item. This system is highly configurable, settings can be on a per-keyword basis and can be localized to a file or even a subtree. For @@ -4019,21 +4079,25 @@ behavior---the recommended drawer for this is called @code{LOGBOOK}. You can also overrule the setting of this variable for a subtree by setting a @code{LOG_INTO_DRAWER} property. -Since it is normally too much to record a note for every state, Org-mode +Since it is normally too much to record a note for every state, Org mode expects configuration on a per-keyword basis for this. This is achieved by -adding special markers @samp{!} (for a timestamp) and @samp{@@} (for a note) -in parentheses after each keyword. For example, with the setting +adding special markers @samp{!} (for a timestamp) or @samp{@@} (for a note +with timestamp) in parentheses after each keyword. For example, with the +setting @lisp (setq org-todo-keywords '((sequence "TODO(t)" "WAIT(w@@/!)" "|" "DONE(d!)" "CANCELED(c@@)"))) @end lisp +To record a timestamp without a note for TODO keywords configured with +@samp{@@}, just type @kbd{C-c C-c} to enter a blank note when prompted. + @noindent @vindex org-log-done you not only define global TODO keywords and fast access keys, but also request that a time is recorded when the entry is set to -DONE@footnote{It is possible that Org-mode will record two timestamps +DONE@footnote{It is possible that Org mode will record two timestamps when you are using both @code{org-log-done} and state change logging. However, it will never prompt for two notes---if you have configured both, the state change recording note will take precedence and cancel @@ -4182,7 +4246,7 @@ which should only be done in certain contexts, for example. @section Priorities @cindex priorities -If you use Org-mode extensively, you may end up with enough TODO items that +If you use Org mode extensively, you may end up with enough TODO items that it starts to make sense to prioritize them. Prioritizing can be done by placing a @emph{priority cookie} into the headline of a TODO item, like this @@ -4192,11 +4256,11 @@ placing a @emph{priority cookie} into the headline of a TODO item, like this @noindent @vindex org-priority-faces -By default, Org-mode supports three priorities: @samp{A}, @samp{B}, and +By default, Org mode supports three priorities: @samp{A}, @samp{B}, and @samp{C}. @samp{A} is the highest priority. An entry without a cookie is treated just like priority @samp{B}. Priorities make a difference only for sorting in the agenda (@pxref{Weekly/daily agenda}); outside the agenda, they -have no inherent meaning to Org-mode. The cookies can be highlighted with +have no inherent meaning to Org mode. The cookies can be highlighted with special faces by customizing the variable @code{org-priority-faces}. Priorities can be attached to any outline node; they do not need to be TODO @@ -4363,9 +4427,11 @@ off a box while there are unchecked boxes above it. @table @kbd @orgcmd{C-c C-c,org-toggle-checkbox} -Toggle checkbox status or (with prefix arg) checkbox presence at point. With -double prefix argument, set it to @samp{[-]}, which is considered to be an -intermediate state. +Toggle checkbox status or (with prefix arg) checkbox presence at point. +With a single prefix argument, add an empty checkbox or remove the current +one@footnote{`C-u C-c C-c' on the @emph{first} item of a list with no checkbox +will add checkboxes to the rest of the list.}. With a double prefix argument, set it to @samp{[-]}, which is +considered to be an intermediate state. @orgcmd{C-c C-x C-b,org-toggle-checkbox} Toggle checkbox status or (with prefix arg) checkbox presence at point. With double prefix argument, set it to @samp{[-]}, which is considered to be an @@ -4410,7 +4476,7 @@ hand, use this command to get things back into sync. @cindex sparse tree, tag based An excellent way to implement labels and contexts for cross-correlating -information is to assign @i{tags} to headlines. Org-mode has extensive +information is to assign @i{tags} to headlines. Org mode has extensive support for tags. @vindex org-tag-faces @@ -4489,7 +4555,7 @@ also a special command for inserting tags: @orgcmd{C-c C-q,org-set-tags-command} @cindex completion, of tags @vindex org-tags-column -Enter new tags for the current headline. Org-mode will either offer +Enter new tags for the current headline. Org mode will either offer completion or a special single-key interface for setting tags, see below. After pressing @key{RET}, the tags will be inserted and aligned to @code{org-tags-column}. When called with a @kbd{C-u} prefix, all @@ -4532,7 +4598,7 @@ by adding a STARTUP option line to that file: #+STARTUP: noptag @end example -By default Org-mode uses the standard minibuffer completion facilities for +By default Org mode uses the standard minibuffer completion facilities for entering tags. However, it also implements another, quicker, tag selection method called @emph{fast tag selection}. This allows you to select and deselect tags with just a single key press. For this to work well you should @@ -4691,25 +4757,26 @@ and properties. For a complete description with many examples, see @chapter Properties and columns @cindex properties -Properties are a set of key-value pairs associated with an entry. There -are two main applications for properties in Org-mode. First, properties -are like tags, but with a value. Second, you can use properties to -implement (very basic) database capabilities in an Org buffer. For -an example of the first application, imagine maintaining a file where +A property is a key-value pair associated with an entry. Properties can be +set so they are associated with a single entry, with every entry in a tree, +or with every entry in an Org mode file. + +There are two main applications for properties in Org mode. First, +properties are like tags, but with a value. Imagine maintaining a file where you document bugs and plan releases for a piece of software. Instead of -using tags like @code{:release_1:}, @code{:release_2:}, one can use a +using tags like @code{:release_1:}, @code{:release_2:}, you can use a property, say @code{:Release:}, that in different subtrees has different -values, such as @code{1.0} or @code{2.0}. For an example of the second -application of properties, imagine keeping track of your music CDs, -where properties could be things such as the album, artist, date of -release, number of tracks, and so on. +values, such as @code{1.0} or @code{2.0}. Second, you can use properties to +implement (very basic) database capabilities in an Org buffer. Imagine +keeping track of your music CDs, where properties could be things such as the +album, artist, date of release, number of tracks, and so on. Properties can be conveniently edited and viewed in column view (@pxref{Column view}). @menu * Property syntax:: How properties are spelled out -* Special properties:: Access to other Org-mode features +* Special properties:: Access to other Org mode features * Property searches:: Matching property values * Property inheritance:: Passing values down the tree * Column view:: Tabular viewing and editing @@ -4721,7 +4788,8 @@ Properties can be conveniently edited and viewed in column view @cindex property syntax @cindex drawer, for properties -Properties are key-value pairs. They need to be inserted into a special +Properties are key-value pairs. When they are associated with a single entry +or with a tree they need to be inserted into a special drawer (@pxref{Drawers}) with the name @code{PROPERTIES}. Each property is specified on a single line, with the key (surrounded by colons) first, and the value after it. Here is an example: @@ -4739,6 +4807,10 @@ first, and the value after it. Here is an example: :END: @end example +Depending on the value of @code{org-use-property-inheritance}, a property set +this way will either be associated with a single entry, or the sub-tree +defined by the entry, see @ref{Property inheritance}. + You may define the allowed values for a particular property @samp{:Xyz:} by setting a property @samp{:Xyz_ALL:}. This special property is @emph{inherited}, so if you set it in a level 1 entry, it will apply to @@ -4763,6 +4835,37 @@ file, use a line like #+PROPERTY: NDisks_ALL 1 2 3 4 @end example +If you want to add to the value of an existing property, append a @code{+} to +the property name. The following results in the property @code{var} having +the value ``foo=1 bar=2''. +@cindex property, + +@example +#+PROPERTY: var foo=1 +#+PROPERTY: var+ bar=2 +@end example + +It is also possible to add to the values of inherited properties. The +following results in the @code{genres} property having the value ``Classic +Baroque'' under the @code{Goldberg Variations} subtree. +@cindex property, + +@example +* CD collection +** Classic + :PROPERTIES: + :GENRES: Classic + :END: +*** Goldberg Variations + :PROPERTIES: + :Title: Goldberg Variations + :Composer: J.S. Bach + :Artist: Glen Gould + :Publisher: Deutsche Grammophon + :NDisks: 1 + :GENRES+: Baroque + :END: +@end example +Note that a property can only have one entry per Drawer. + @vindex org-global-properties Property values set with the global variable @code{org-global-properties} can be inherited by all entries in all @@ -4803,7 +4906,7 @@ nearest column format definition. @section Special properties @cindex properties, special -Special properties provide an alternative access method to Org-mode features, +Special properties provide an alternative access method to Org mode features, like the TODO state or the priority of an entry, discussed in the previous chapters. This interface exists so that you can include these states in a column view (@pxref{Column view}), or to use them in queries. The following @@ -4885,9 +4988,9 @@ a regular expression and matched against the property values. @cindex inheritance, of properties @vindex org-use-property-inheritance -The outline structure of Org-mode documents lends itself to an +The outline structure of Org mode documents lends itself to an inheritance model of properties: if the parent in a tree has a certain -property, the children can inherit this property. Org-mode does not +property, the children can inherit this property. Org mode does not turn this on by default, because it can slow down property searches significantly and is often not needed. However, if you find inheritance useful, you can turn it on by setting the variable @@ -4898,7 +5001,7 @@ inherited properties. If a property has the value @samp{nil}, this is interpreted as an explicit undefine of the property, so that inheritance search will stop at this value and return @code{nil}. -Org-mode has a few properties for which inheritance is hard-coded, at +Org mode has a few properties for which inheritance is hard-coded, at least for the special applications for which they are used: @cindex property, COLUMNS @@ -4929,7 +5032,7 @@ subtree (@pxref{Tracking TODO state changes}). A great way to view and edit properties in an outline tree is @emph{column view}. In column view, each outline node is turned into a table row. Columns in this table provide access to properties of the -entries. Org-mode implements columns by overlaying a tabular structure +entries. Org mode implements columns by overlaying a tabular structure over the headline of each item. While the headlines have been turned into a table row, you can still change the visibility of the outline tree. For example, you get a compact table by switching to CONTENTS @@ -5231,9 +5334,9 @@ property API}. To assist project planning, TODO items can be labeled with a date and/or a time. The specially formatted string carrying the date and time -information is called a @emph{timestamp} in Org-mode. This may be a +information is called a @emph{timestamp} in Org mode. This may be a little confusing because timestamp is often used as indicating when -something was created or last changed. However, in Org-mode this term +something was created or last changed. However, in Org mode this term is used in a much wider sense. @menu @@ -5256,17 +5359,20 @@ is used in a much wider sense. @cindex scheduling A timestamp is a specification of a date (possibly with a time or a range of -times) in a special format, either @samp{<2003-09-16 Tue>} or -@samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 Tue -12:00-12:30>}@footnote{This is inspired by the standard ISO 8601 date/time -format. To use an alternative format, see @ref{Custom time format}.}. A -timestamp can appear anywhere in the headline or body of an Org tree entry. -Its presence causes entries to be shown on specific dates in the agenda -(@pxref{Weekly/daily agenda}). We distinguish: +times) in a special format, either @samp{<2003-09-16 Tue>}@footnote{In this +simplest form, the day name is optional when you type the date yourself. +However, any dates inserted or modified by Org will add that day name, for +reading convenience.} or @samp{<2003-09-16 Tue 09:39>} or @samp{<2003-09-16 +Tue 12:00-12:30>}@footnote{This is inspired by the standard ISO 8601 +date/time format. To use an alternative format, see @ref{Custom time +format}.}. A timestamp can appear anywhere in the headline or body of an Org +tree entry. Its presence causes entries to be shown on specific dates in the +agenda (@pxref{Weekly/daily agenda}). We distinguish: @table @var @item Plain timestamp; Event; Appointment @cindex timestamp +@cindex appointment A simple timestamp just assigns a date/time to an item. This is just like writing down an appointment or event in a paper agenda. In the timeline and agenda displays, the headline of an entry associated with a @@ -5289,7 +5395,7 @@ following will show up in the agenda every Wednesday: @end example @item Diary-style sexp entries -For more complex date specifications, Org-mode supports using the special +For more complex date specifications, Org mode supports using the special sexp diary entries implemented in the Emacs calendar/diary package@footnote{When working with the standard diary sexp functions, you need to be very careful with the order of the arguments. That order depend @@ -5297,7 +5403,7 @@ evilly on the variable @code{calendar-date-style} (or, for older Emacs versions, @code{european-calendar-style}). For example, to specify a date December 12, 2005, the call might look like @code{(diary-date 12 1 2005)} or @code{(diary-date 1 12 2005)} or @code{(diary-date 2005 12 1)}, depending on -the settings. This has been the source of much confusion. Org-mode users +the settings. This has been the source of much confusion. Org mode users can resort to special versions of these functions like @code{org-date} or @code{org-anniversary}. These work just like the corresponding @code{diary-} functions, but with stable ISO order of arguments (year, month, day) wherever @@ -5338,7 +5444,7 @@ angular ones. These timestamps are inactive in the sense that they do @cindex creating timestamps @cindex timestamps, creating -For Org-mode to recognize timestamps, they need to be in the specific +For Org mode to recognize timestamps, they need to be in the specific format. All commands listed below produce timestamps in the correct format. @@ -5362,6 +5468,9 @@ Like @kbd{C-c .} and @kbd{C-c !}, but use the alternative format which contains date and time. The default time can be rounded to multiples of 5 minutes, see the option @code{org-time-stamp-rounding-minutes}. @c +@orgkey{C-c C-c} +Normalize timestamp, insert/fix day name if missing or wrong. +@c @orgcmd{C-c <,org-date-from-calendar} Insert a timestamp corresponding to the cursor date in the Calendar. @c @@ -5397,7 +5506,7 @@ the following column). @menu -* The date/time prompt:: How Org-mode helps you entering date and time +* The date/time prompt:: How Org mode helps you entering date and time * Custom time format:: Making dates look different @end menu @@ -5407,17 +5516,17 @@ the following column). @cindex time, reading in minibuffer @vindex org-read-date-prefer-future -When Org-mode prompts for a date/time, the default is shown in default +When Org mode prompts for a date/time, the default is shown in default date/time format, and the prompt therefore seems to ask for a specific format. But it will in fact accept any string containing some date and/or time information, and it is really smart about interpreting your input. You can, for example, use @kbd{C-y} to paste a (possibly multi-line) string -copied from an email message. Org-mode will find whatever information is in +copied from an email message. Org mode will find whatever information is in there and derive anything you have not specified from the @emph{default date and time}. The default is usually the current date and time, but when modifying an existing timestamp, or when entering the second stamp of a range, it is taken from the stamp in the buffer. When filling in -information, Org-mode assumes that most of the time you will want to enter a +information, Org mode assumes that most of the time you will want to enter a date in the future: if you omit the month/year and the given day/month is @i{before} today, it will assume that you mean a future date@footnote{See the variable @code{org-read-date-prefer-future}. You may set that variable to @@ -5426,7 +5535,7 @@ tomorrow.}. If the date has been automatically shifted into the future, the time prompt will show this with @samp{(=>F).} For example, let's assume that today is @b{June 13, 2006}. Here is how -various inputs will be interpreted, the items filled in by Org-mode are +various inputs will be interpreted, the items filled in by Org mode are in @b{bold}. @example @@ -5536,7 +5645,7 @@ minibuffer@footnote{If you find this distracting, turn the display of with @vindex org-display-custom-times @vindex org-time-stamp-custom-formats -Org-mode uses the standard ISO notation for dates and times as it is +Org mode uses the standard ISO notation for dates and times as it is defined in ISO 8601. If you cannot get used to this and require another representation of date and time to keep you happy, you can get it by customizing the variables @code{org-display-custom-times} and @@ -5548,7 +5657,7 @@ Toggle the display of custom formats for dates and times. @end table @noindent -Org-mode needs the default format for scanning, so the custom date/time +Org mode needs the default format for scanning, so the custom date/time format does not @emph{replace} the default format---instead it is put @emph{over} the default format using text properties. This has the following consequences: @@ -5625,23 +5734,23 @@ the task will automatically be forwarded until completed. @end example @noindent -@b{Important:} Scheduling an item in Org-mode should @i{not} be +@b{Important:} Scheduling an item in Org mode should @i{not} be understood in the same way that we understand @i{scheduling a meeting}. Setting a date for a meeting is just a simple appointment, you should mark this entry with a simple plain timestamp, to get this item shown on the date where it applies. This is a frequent misunderstanding by -Org users. In Org-mode, @i{scheduling} means setting a date when you +Org users. In Org mode, @i{scheduling} means setting a date when you want to start working on an action item. @end table You may use timestamps with repeaters in scheduling and deadline -entries. Org-mode will issue early and late warnings based on the +entries. Org mode will issue early and late warnings based on the assumption that the timestamp represents the @i{nearest instance} of the repeater. However, the use of diary sexp entries like @c @code{<%%(org-float t 42)>} @c -in scheduling and deadline timestamps is limited. Org-mode does not +in scheduling and deadline timestamps is limited. Org mode does not know enough about the internals of each sexp function to issue early and late warnings. However, it will show the item on each day where the sexp entry matches. @@ -5714,7 +5823,7 @@ to the previous week before any current timestamp. @cindex tasks, repeated @cindex repeated tasks -Some tasks need to be repeated again and again. Org-mode helps to +Some tasks need to be repeated again and again. Org mode helps to organize such tasks using a so-called repeater in a DEADLINE, SCHEDULED, or plain timestamp. In the following example @example @@ -5734,7 +5843,7 @@ over-due, so it is important to be able to mark such an entry as completed once you have done so. When you mark a DEADLINE or a SCHEDULE with the TODO keyword DONE, it will no longer produce entries in the agenda. The problem with this is, however, that then also the @emph{next} instance of the -repeated entry will not be active. Org-mode deals with this in the following +repeated entry will not be active. Org mode deals with this in the following way: When you try to mark such an entry DONE (using @kbd{C-c C-t}), it will shift the base date of the repeating timestamp by the repeater interval, and immediately set the entry state back to TODO@footnote{In fact, the target @@ -5767,7 +5876,7 @@ task, this may not be the best way to handle it. For example, if you forgot to call your father for 3 weeks, it does not make sense to call him 3 times in a single day to make up for it. Finally, there are tasks like changing batteries which should always repeat a certain time -@i{after} the last time you did it. For these tasks, Org-mode has +@i{after} the last time you did it. For these tasks, Org mode has special repeaters @samp{++} and @samp{.+}. For example: @example @@ -5796,7 +5905,7 @@ created for this purpose, it is described in @ref{Structure editing}. @cindex clocking time @cindex time clocking -Org-mode allows you to clock the time you spend on specific tasks in a +Org mode allows you to clock the time you spend on specific tasks in a project. When you start working on an item, you can start the clock. When you stop working on that task, or when you mark the task done, the clock is stopped and the corresponding time interval is recorded. It @@ -5915,10 +6024,11 @@ formatted as one or several Org tables. @table @kbd @orgcmd{C-c C-x C-r,org-clock-report} Insert a dynamic block (@pxref{Dynamic blocks}) containing a clock -report as an Org-mode table into the current file. When the cursor is +report as an Org mode table into the current file. When the cursor is at an existing clock table, just update it. When called with a prefix argument, jump to the first clock report in the current document and -update it. +update it. The clock table always includes also trees with +@code{:ARCHIVE:} tag. @orgcmdkkc{C-c C-c,C-c C-x C-u,org-dblock-update} Update dynamic block at point. The cursor needs to be in the @code{#+BEGIN} line of the dynamic block. @@ -6215,8 +6325,8 @@ not started at exactly the right moment. @kindex C-c C-x ; @kindex ; -Calling @code{org-timer-set-timer} from an Org-mode buffer runs a countdown -timer. Use @kbd{;} from agenda buffers, @key{C-c C-x ;} everywhere else. +Calling @code{org-timer-set-timer} from an Org mode buffer runs a countdown +timer. Use @kbd{;} from agenda buffers, @key{C-c C-x ;} everwhere else. @code{org-timer-set-timer} prompts the user for a duration and displays a countdown timer in the modeline. @code{org-timer-default-timer} sets the @@ -6249,7 +6359,7 @@ trees to an archive file keeps the system compact and fast. Org's method for capturing new items is heavily inspired by John Wiegley excellent remember package. Up to version 6.36 Org used a special setup -for @file{remember.el}. @file{org-remember.el} is still part of Org-mode for +for @file{remember.el}. @file{org-remember.el} is still part of Org mode for backward compatibility with existing setups. You can find the documentation for org-remember at @url{http://orgmode.org/org-remember.pdf}. @@ -6393,7 +6503,7 @@ like this: @node Template elements, Template expansion, Capture templates, Capture templates @subsubsection Template elements -Now let's look at the elements of a template definition. Each entry in +Now lets look at the elements of a template definition. Each entry in @code{org-capture-templates} is a list with the following items: @table @var @@ -6418,8 +6528,8 @@ selection. The type of entry, a symbol. Valid values are: @table @code @item entry -An Org-mode node, with a headline. Will be filed as the child of the target -entry or as a top-level entry. The target file should be an Org-mode file. +An Org mode node, with a headline. Will be filed as the child of the target +entry or as a top-level entry. The target file should be an Org mode file. @item item A plain list item, placed in the first plain list at the target location. Again the target file should be an Org file. @@ -6436,7 +6546,7 @@ Text to be inserted as it is. @item target @vindex org-default-notes-file -Specification of where the captured item should be placed. In Org-mode +Specification of where the captured item should be placed. In Org mode files, targets usually define a node. Entries will become children of this node. Other types will be added to the table or list in the body of this node. Most target specifications contain a file name. If that file name is @@ -6536,7 +6646,7 @@ buffer again after capture is completed. In the template itself, special @kbd{%}-escapes@footnote{If you need one of these sequences literally, escape the @kbd{%} with a backslash.} allow -dynamic insertion of content. The templates are expanded in the order given here: +dynamic insertion of content. The templates are expanded in the order given here: @smallexample %[@var{file}] @r{insert the contents of the file given by @var{file}.} @@ -7032,6 +7142,7 @@ the front. With a prefix argument, file is added/moved to the end. @orgcmd{C-c ],org-remove-file} Remove current file from the list of agenda files. @kindex C-, +@cindex cycling, of agenda files @orgcmd{C-',org-cycle-agenda-files} @itemx C-, Cycle through agenda file list, visiting one file after the other. @@ -7187,7 +7298,7 @@ anniversaries, lunar phases, sunrise/set, recurrent appointments Org. It can be very useful to combine output from Org with the diary. -In order to include entries from the Emacs diary into Org-mode's +In order to include entries from the Emacs diary into Org mode's agenda, you only need to customize the variable @lisp @@ -7196,7 +7307,7 @@ agenda, you only need to customize the variable @noindent After that, everything will happen automatically. All diary entries including holidays, anniversaries, etc., will be included in the -agenda buffer created by Org-mode. @key{SPC}, @key{TAB}, and +agenda buffer created by Org mode. @key{SPC}, @key{TAB}, and @key{RET} can be used from the agenda buffer to jump to the diary file in order to edit existing diary entries. The @kbd{i} command to insert new entries for the current date works in the agenda buffer, as @@ -7207,7 +7318,7 @@ between calendar and agenda. If you are using the diary only for sexp entries and holidays, it is faster to not use the above setting, but instead to copy or even move -the entries into an Org file. Org-mode evaluates diary-style sexp +the entries into an Org file. Org mode evaluates diary-style sexp entries, and does it faster because there is no overhead for first creating the diary display. Note that the sexp entries must start at the left margin, no whitespace is allowed before them. For example, @@ -7253,7 +7364,7 @@ followed by a space and the class of the anniversary (@samp{birthday} or 1973-06-22 06-22 1955-08-02 wedding -2008-04-14 %s released version 6.01 of org-mode, %d years ago +2008-04-14 %s released version 6.01 of org mode, %d years ago @end example After a change to BBDB, or for the first agenda display during an Emacs @@ -7265,6 +7376,8 @@ in an Org or Diary file. @subsubheading Appointment reminders @cindex @file{appt.el} @cindex appointment reminders +@cindex appointment +@cindex reminders Org can interact with Emacs appointments notification facility. To add all the appointments of your agenda files, use the command @@ -7466,7 +7579,7 @@ other properties will slow down the search. However, once you have paid the price by accessing one property, testing additional properties is cheap again. -You can configure Org-mode to use property inheritance during a search, but +You can configure Org mode to use property inheritance during a search, but beware that this can slow down searches considerably. See @ref{Property inheritance}, for details. @@ -7499,7 +7612,7 @@ Select @samp{:work:}-tagged TODO lines that are either @samp{WAITING} or @cindex timeline, single file @cindex time-sorted view -The timeline summarizes all time-stamped items from a single Org-mode +The timeline summarizes all time-stamped items from a single Org mode file in a @emph{time-sorted view}. The main purpose of this command is to give an overview over events in a project. @@ -7520,7 +7633,7 @@ The commands available in the timeline buffer are listed in @cindex text search @cindex searching, for text -This agenda view is a general text search facility for Org-mode entries. +This agenda view is a general text search facility for Org mode entries. It is particularly useful to find notes. @table @kbd @@ -7552,7 +7665,7 @@ If you are following a system like David Allen's GTD to organize your work, one of the ``duties'' you have is a regular review to make sure that all projects move along. A @emph{stuck} project is a project that has no defined next actions, so it will never show up in the TODO lists -Org-mode produces. During the review, you need to identify such +Org mode produces. During the review, you need to identify such projects and define next actions for them. @table @kbd @@ -7570,7 +7683,7 @@ work for you. The built-in default assumes that all your projects are level-2 headlines, and that a project is not stuck if it has at least one entry marked with a TODO keyword TODO or NEXT or NEXTACTION. -Let's assume that you, in your own way of using Org-mode, identify +Let's assume that you, in your own way of using Org mode, identify projects with a tag PROJECT, and that you use a TODO keyword MAYBE to indicate a project that should not be considered yet. Let's further assume that the TODO keyword DONE marks finished projects, and that NEXT @@ -7598,7 +7711,7 @@ will still be searched for stuck projects. @vindex org-agenda-prefix-format @vindex org-agenda-tags-column -Before displaying items in an agenda view, Org-mode visually prepares the +Before displaying items in an agenda view, Org mode visually prepares the items and sorts them. Each item occupies a single line. The line starts with a @emph{prefix} that contains the @emph{category} (@pxref{Categories}) of the item and other important information. You can customize in which @@ -7651,7 +7764,7 @@ You can set up icons for category by customizing the @subsection Time-of-day specifications @cindex time-of-day specification -Org-mode checks each agenda item for a time-of-day specification. The +Org mode checks each agenda item for a time-of-day specification. The time can be part of the timestamp that triggered inclusion into the agenda, for example as in @w{@samp{<2005-05-10 Tue 19:00>}}. Time ranges can be specified with two timestamps, like @@ -7663,7 +7776,7 @@ plain text (like @samp{12:45} or a @samp{8:30-1pm}). If the agenda integrates the Emacs diary (@pxref{Weekly/daily agenda}), time specifications in diary entries are recognized as well. -For agenda display, Org-mode extracts the time and displays it in a +For agenda display, Org mode extracts the time and displays it in a standard 24 hour format as part of the prefix. The example times in the previous paragraphs would end up in the agenda like this: @@ -7861,6 +7974,7 @@ press @kbd{v a} again. @c @orgcmdkskc{v R,R,org-agenda-clockreport-mode} @vindex org-agenda-start-with-clockreport-mode +@vindex org-clock-report-include-clocking-task Toggle Clockreport mode. In Clockreport mode, the daily/weekly agenda will always show a table with the clocked times for the timespan and file scope covered by the current agenda view. The initial setting for this mode in new @@ -7868,7 +7982,8 @@ agenda buffers can be set with the variable @code{org-agenda-start-with-clockreport-mode}. By using a prefix argument when toggling this mode (i.e.@: @kbd{C-u R}), the clock table will not show contributions from entries that are hidden by agenda filtering@footnote{Only -tags filtering will be respected here, effort filtering is ignored.}. +tags filtering will be respected here, effort filtering is ignored.}. See +also the variable @code{org-clock-report-include-clocking-task}. @c @orgkey{v c} @vindex org-agenda-clock-consistency-checks @@ -7921,18 +8036,27 @@ Remove the restriction lock on the agenda, if it is currently restricted to a file or subtree (@pxref{Agenda files}). @tsubheading{Secondary filtering and query editing} -@cindex filtering, by tag and effort, in agenda +@cindex filtering, by tag category and effort, in agenda @cindex tag filtering, in agenda +@cindex category filtering, in agenda @cindex effort filtering, in agenda @cindex query editing, in agenda +@orgcmd{<,org-agenda-filter-by-category} +@vindex org-agenda-category-filter-preset + +Filter the current agenda view with respect to the category of the item at +point. Pressing @code{<} another time will remove this filter. You can add +a filter preset through the option @code{org-agenda-category-filter-preset} +(see below.) + @orgcmd{/,org-agenda-filter-by-tag} -@vindex org-agenda-filter-preset +@vindex org-agenda-tag-filter-preset Filter the current agenda view with respect to a tag and/or effort estimates. The difference between this and a custom agenda command is that filtering is very fast, so that you can switch quickly between different filters without having to recreate the agenda.@footnote{Custom commands can preset a filter by -binding the variable @code{org-agenda-filter-preset} as an option. This +binding the variable @code{org-agenda-tag-filter-preset} as an option. This filter will then be applied to the view and persist as a basic filter through refreshes and more secondary filtering. The filter is a global property of the entire agenda view---in a block agenda, you should only set this in the @@ -8076,7 +8200,7 @@ agenda, change a tag for all headings in the region. @kindex , @item , Set the priority for the current item (@command{org-agenda-priority}). -Org-mode prompts for the priority character. If you reply with @key{SPC}, +Org mode prompts for the priority character. If you reply with @key{SPC}, the priority cookie is removed from the entry. @c @orgcmd{P,org-agenda-show-priority} @@ -8122,13 +8246,15 @@ command. @c @orgcmd{S-@key{right},org-agenda-do-date-later} Change the timestamp associated with the current line by one day into the -future. With a numeric prefix argument, change it by that many days. For -example, @kbd{3 6 5 S-@key{right}} will change it by a year. With a -@kbd{C-u} prefix, change the time by one hour. If you immediately repeat the -command, it will continue to change hours even without the prefix arg. With -a double @kbd{C-u C-u} prefix, do the same for changing minutes. The stamp -is changed in the original Org file, but the change is not directly reflected -in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer. +future. If the date is in the past, the first call to this command will move +it to today.@* +With a numeric prefix argument, change it by that many days. For example, +@kbd{3 6 5 S-@key{right}} will change it by a year. With a @kbd{C-u} prefix, +change the time by one hour. If you immediately repeat the command, it will +continue to change hours even without the prefix arg. With a double @kbd{C-u +C-u} prefix, do the same for changing minutes.@* +The stamp is changed in the original Org file, but the change is not directly +reflected in the agenda buffer. Use @kbd{r} or @kbd{g} to update the buffer. @c @orgcmd{S-@key{left},org-agenda-do-date-earlier} Change the timestamp associated with the current line by one day @@ -8213,7 +8339,7 @@ f @r{Apply a function to marked entries.} Open the Emacs calendar and move to the date at the agenda cursor. @c @orgcmd{c,org-calendar-goto-agenda} -When in the calendar, compute and show the Org-mode agenda for the +When in the calendar, compute and show the Org mode agenda for the date at the cursor. @c @cindex diary entries, creating from agenda @@ -8226,8 +8352,8 @@ file@footnote{This file is parsed for the agenda when command in the calendar. The diary file will pop up in another window, where you can add the entry. -If you configure @code{org-agenda-diary-file} to point to an Org-mode file, -Org will create entries (in org-mode syntax) in that file instead. Most +If you configure @code{org-agenda-diary-file} to point to an Org mode file, +Org will create entries (in Org mode syntax) in that file instead. Most entries will be stored in a date-based outline tree that will later make it easy to archive appointments from previous months/years. The tree will be built under an entry with a @code{DATE_TREE} property, or else with years as @@ -8262,7 +8388,7 @@ This is a globally available command, and also available in the agenda menu. @vindex org-agenda-exporter-settings Write the agenda view to a file. Depending on the extension of the selected file name, the view will be exported as HTML (extension @file{.html} or -@file{.htm}), PostScript (extension @file{.ps}), PDF (extension @file{.pdf}), +@file{.htm}), Postscript (extension @file{.ps}), PDF (extension @file{.pdf}), and plain text (any other extension). When called with a @kbd{C-u} prefix argument, immediately open the newly created file. Use the variable @code{org-agenda-exporter-settings} to set options for @file{ps-print} and @@ -8403,7 +8529,7 @@ command @kbd{C-c a o} provides a similar view for office tasks. @cindex options, for custom agenda views @vindex org-agenda-custom-commands -Org-mode contains a number of variables regulating agenda construction +Org mode contains a number of variables regulating agenda construction and display. The global variables define the behavior for all agenda commands, including the custom commands. However, if you want to change some settings just for a single custom view, you can do so. Setting @@ -8475,11 +8601,11 @@ yourself. @cindex agenda views, exporting If you are away from your computer, it can be very useful to have a printed -version of some agenda views to carry around. Org-mode can export custom +version of some agenda views to carry around. Org mode can export custom agenda views as plain text, HTML@footnote{You need to install Hrvoje Niksic's -@file{htmlize.el}.}, PostScript, PDF@footnote{To create PDF output, the +@file{htmlize.el}.}, Postscript, PDF@footnote{To create PDF output, the ghostscript @file{ps2pdf} utility must be installed on the system. Selecting -a PDF file will also create the PostScript file.}, and iCalendar files. If +a PDF file will also create the postscript file.}, and iCalendar files. If you want to do this only occasionally, use the command @table @kbd @@ -8489,7 +8615,7 @@ you want to do this only occasionally, use the command @vindex org-agenda-exporter-settings Write the agenda view to a file. Depending on the extension of the selected file name, the view will be exported as HTML (extension @file{.html} or -@file{.htm}), PostScript (extension @file{.ps}), iCalendar (extension +@file{.htm}), Postscript (extension @file{.ps}), iCalendar (extension @file{.ics}), or plain text (any other extension). Use the variable @code{org-agenda-exporter-settings} to set options for @file{ps-print} and for @file{htmlize} to be used during export, for example @@ -8539,10 +8665,10 @@ or absolute. @end lisp The extension of the file name determines the type of export. If it is -@file{.html}, Org-mode will use the @file{htmlize.el} package to convert +@file{.html}, Org mode will use the @file{htmlize.el} package to convert the buffer to HTML and save it to this file name. If the extension is @file{.ps}, @code{ps-print-buffer-with-faces} is used to produce -PostScript output. If the extension is @file{.ics}, iCalendar export is +Postscript output. If the extension is @file{.ics}, iCalendar export is run export over all files that were used to construct the agenda, and limit the export to entries listed in the agenda. Any other extension produces a plain ASCII file. @@ -8573,7 +8699,7 @@ set options for the export commands. For example: @end lisp @noindent -This command sets two options for the PostScript exporter, to make it +This command sets two options for the Postscript exporter, to make it print in two columns in landscape format---the resulting page can be cut in two and then used in a paper agenda. The remaining settings modify the agenda prefix to omit category and scheduling information, and @@ -8586,14 +8712,14 @@ in @code{org-agenda-custom-commands} take precedence. @noindent From the command line you may also use @example -emacs -f org-batch-store-agenda-views -kill +emacs -eval (org-batch-store-agenda-views) -kill @end example @noindent or, if you need to modify some parameters@footnote{Quoting depends on the system you use, please check the FAQ for examples.} @example emacs -eval '(org-batch-store-agenda-views \ - org-agenda-span month \ + org-agenda-span (quote month) \ org-agenda-start-day "2007-11-01" \ org-agenda-include-diary nil \ org-agenda-files (quote ("~/org/project.org")))' \ @@ -8668,11 +8794,11 @@ the agenda). @node Markup, Exporting, Agenda Views, Top @chapter Markup for rich export -When exporting Org-mode documents, the exporter tries to reflect the +When exporting Org mode documents, the exporter tries to reflect the structure of the document as accurately as possible in the backend. Since export targets like HTML, @LaTeX{}, or DocBook allow much richer formatting, -Org-mode has rules on how to prepare text for rich export. This section -summarizes the markup rules used in an Org-mode buffer. +Org mode has rules on how to prepare text for rich export. This section +summarizes the markup rules used in an Org mode buffer. @menu * Structural markup elements:: The basic structure as seen by the exporter @@ -8681,7 +8807,7 @@ summarizes the markup rules used in an Org-mode buffer. * Include files:: Include additional files into a document * Index entries:: Making an index * Macro replacement:: Use macros to create complex output -* Embedded LaTeX:: LaTeX can be freely used inside Org documents +* Embedded @LaTeX{}:: LaTeX can be freely used inside Org documents @end menu @node Structural markup elements, Images and tables, Markup, Markup @@ -8764,7 +8890,7 @@ the table of contents entirely, by configuring the variable @cindex text before first headline, markup rules @cindex #+TEXT -Org-mode normally exports the text before the first headline, and even uses +Org mode normally exports the text before the first headline, and even uses the first line as the document title. The text will be fully marked up. If you need to include literal HTML, @LaTeX{}, or DocBook code, use the special constructs described below in the sections for the individual exporters. @@ -8818,7 +8944,7 @@ can use this construct, which can also be used to format poetry. When quoting a passage from another document, it is customary to format this as a paragraph that is indented on both the left and the right margin. You -can include quotations in Org-mode documents like this: +can include quotations in Org mode documents like this: @cindex #+BEGIN_QUOTE @example @@ -8858,7 +8984,7 @@ multiple footnotes side by side. @cindex strike-through text, markup rules You can make words @b{*bold*}, @i{/italic/}, _underlined_, @code{=code=} and @code{~verbatim~}, and, if you must, @samp{+strike-through+}. Text -in the code and verbatim string is not processed for Org-mode specific +in the code and verbatim string is not processed for Org mode specific syntax; it is exported verbatim. @node Horizontal rules, Comment lines, Emphasis and monospace, Structural markup elements @@ -8892,8 +9018,8 @@ Toggle the COMMENT keyword at the beginning of an entry. @cindex tables, markup rules @cindex #+CAPTION @cindex #+LABEL -Both the native Org-mode tables (@pxref{Tables}) and tables formatted with -the @file{table.el} package will be exported properly. For Org-mode tables, +Both the native Org mode tables (@pxref{Tables}) and tables formatted with +the @file{table.el} package will be exported properly. For Org mode tables, the lines before the first horizontal separator line will become table header lines. You can use the following lines somewhere before the table to assign a caption and a label for cross references, and in the text you can refer to @@ -8963,16 +9089,16 @@ If the example is source code from a programming language, or any other text that can be marked up by font-lock in Emacs, you can ask for the example to look like the fontified Emacs buffer@footnote{This works automatically for the HTML backend (it requires version 1.34 of the @file{htmlize.el} package, -which is distributed with Org). Fontified code chunks in LaTeX can be +which is distributed with Org). Fontified code chunks in @LaTeX{} can be achieved using either the listings or the @url{http://code.google.com/p/minted, minted,} package. To use listings, turn on the variable @code{org-export-latex-listings} and ensure that the listings -package is included by the LaTeX header (e.g.@: by configuring +package is included by the @LaTeX{} header (e.g.@: by configuring @code{org-export-latex-packages-alist}). See the listings documentation for configuration options, including obtaining colored output. For minted it is necessary to install the program @url{http://pygments.org, pygments}, in addition to setting @code{org-export-latex-minted}, ensuring that the minted -package is included by the LaTeX header, and ensuring that the +package is included by the @LaTeX{} header, and ensuring that the @code{-shell-escape} option is passed to @file{pdflatex} (see @code{org-latex-to-pdf-process}). See the documentation of the variables @code{org-export-latex-listings} and @code{org-export-latex-minted} for @@ -8980,7 +9106,8 @@ further details.}. This is done with the @samp{src} block, where you also need to specify the name of the major mode that should be used to fontify the example@footnote{Code in @samp{src} blocks may also be evaluated either interactively or on export. See @pxref{Working With Source Code} for more -information on evaluating code blocks.}: +information on evaluating code blocks.}, see @ref{Easy Templates} for +shortcuts to easily insert code blocks. @cindex #+BEGIN_SRC @example @@ -9004,7 +9131,7 @@ cool. You can also add a @code{-r} switch which @i{removes} the labels from the source code@footnote{Adding @code{-k} to @code{-n -r} will @i{keep} the labels in the source code while using line numbers for the links, which might -be useful to explain those in an org-mode example code.}. With the @code{-n} +be useful to explain those in an Org mode example code.}. With the @code{-n} switch, links to these references will be labeled by the line numbers from the code listing, otherwise links will use the labels with no parentheses. Here is an example: @@ -9070,11 +9197,11 @@ include your @file{.emacs} file, you could use: The optional second and third parameter are the markup (e.g.@: @samp{quote}, @samp{example}, or @samp{src}), and, if the markup is @samp{src}, the language for formatting the contents. The markup is optional; if it is not -given, the text will be assumed to be in Org-mode format and will be +given, the text will be assumed to be in Org mode format and will be processed normally. The include line will also allow additional keyword parameters @code{:prefix1} and @code{:prefix} to specify prefixes for the first line and for each following line, @code{:minlevel} in order to get -org-mode content demoted to a specified level, as well as any options +Org mode content demoted to a specified level, as well as any options accepted by the selected markup. For example, to include a file as an item, use @@ -9117,7 +9244,7 @@ an index} for more information. -@node Macro replacement, Embedded LaTeX, Index entries, Markup +@node Macro replacement, Embedded @LaTeX{}, Index entries, Markup @section Macro replacement @cindex macro replacement, during export @cindex #+MACRO @@ -9142,7 +9269,7 @@ Macro expansion takes place during export, and some people use it to construct complex HTML code. -@node Embedded LaTeX, , Macro replacement, Markup +@node Embedded @LaTeX{}, , Macro replacement, Markup @section Embedded @LaTeX{} @cindex @TeX{} interpretation @cindex @LaTeX{} interpretation @@ -9152,7 +9279,7 @@ include scientific notes, which often require mathematical symbols and the occasional formula. @LaTeX{}@footnote{@LaTeX{} is a macro system based on Donald E. Knuth's @TeX{} system. Many of the features described here as ``@LaTeX{}'' are really from @TeX{}, but for simplicity I am blurring this -distinction.} is widely used to typeset scientific documents. Org-mode +distinction.} is widely used to typeset scientific documents. Org mode supports embedding @LaTeX{} code into its files, because many academics are used to writing and reading @LaTeX{} source code, and because it can be readily processed to produce pretty output for a number of export backends. @@ -9160,12 +9287,12 @@ readily processed to produce pretty output for a number of export backends. @menu * Special symbols:: Greek letters and other symbols * Subscripts and superscripts:: Simple syntax for raising/lowering text -* LaTeX fragments:: Complex formulas made easy -* Previewing LaTeX fragments:: What will this snippet look like? +* @LaTeX{} fragments:: Complex formulas made easy +* Previewing @LaTeX{} fragments:: What will this snippet look like? * CDLaTeX mode:: Speed up entering of formulas @end menu -@node Special symbols, Subscripts and superscripts, Embedded LaTeX, Embedded LaTeX +@node Special symbols, Subscripts and superscripts, Embedded @LaTeX{}, Embedded @LaTeX{} @subsection Special symbols @cindex math symbols @cindex special symbols @@ -9178,7 +9305,7 @@ You can use @LaTeX{} macros to insert special symbols like @samp{\alpha} to indicate the Greek letter, or @samp{\to} to indicate an arrow. Completion for these macros is available, just type @samp{\} and maybe a few letters, and press @kbd{M-@key{TAB}} to see possible completions. Unlike @LaTeX{} -code, Org-mode allows these macros to be present without surrounding math +code, Org mode allows these macros to be present without surrounding math delimiters, for example: @example @@ -9212,7 +9339,7 @@ buffer content which remains plain ASCII, but it overlays the UTF-8 character for display purposes only. @end table -@node Subscripts and superscripts, LaTeX fragments, Special symbols, Embedded LaTeX +@node Subscripts and superscripts, @LaTeX{} fragments, Special symbols, Embedded @LaTeX{} @subsection Subscripts and superscripts @cindex subscript @cindex superscript @@ -9250,13 +9377,13 @@ In addition to showing entities as UTF-8 characters, this command will also format sub- and superscripts in a WYSIWYM way. @end table -@node LaTeX fragments, Previewing LaTeX fragments, Subscripts and superscripts, Embedded LaTeX +@node @LaTeX{} fragments, Previewing @LaTeX{} fragments, Subscripts and superscripts, Embedded @LaTeX{} @subsection @LaTeX{} fragments @cindex @LaTeX{} fragments @vindex org-format-latex-header Going beyond symbols and sub- and superscripts, a full formula language is -needed. Org-mode can contain @LaTeX{} math fragments, and it supports ways +needed. Org mode can contain @LaTeX{} math fragments, and it supports ways to process these for several export backends. When exporting to @LaTeX{}, the code is obviously left as it is. When exporting to HTML, Org invokes the @uref{http://www.mathjax.org, MathJax library} (@pxref{Math formatting in @@ -9309,10 +9436,10 @@ can configure the option @code{org-format-latex-options} to deselect the ones you do not wish to have interpreted by the @LaTeX{} converter. @vindex org-export-with-LaTeX-fragments -LaTeX processing can be configured with the variable +@LaTeX{} processing can be configured with the variable @code{org-export-with-LaTeX-fragments}. The default setting is @code{t} which means @file{MathJax} for HTML, and no processing for DocBook, ASCII and -LaTeX backends. You can also set this variable on a per-file basis using one +@LaTeX{} backends. You can also set this variable on a per-file basis using one of these lines: @example @@ -9322,9 +9449,9 @@ of these lines: #+OPTIONS: LaTeX:verbatim @r{Verbatim export, for jsMath or so} @end example -@node Previewing LaTeX fragments, CDLaTeX mode, LaTeX fragments, Embedded LaTeX -@subsection Previewing LaTeX fragments -@cindex LaTeX fragments, preview +@node Previewing @LaTeX{} fragments, CDLaTeX mode, @LaTeX{} fragments, Embedded @LaTeX{} +@subsection Previewing @LaTeX{} fragments +@cindex @LaTeX{} fragments, preview If you have @file{dvipng} installed, @LaTeX{} fragments can be processed to produce preview images of the typeset expressions: @@ -9349,18 +9476,18 @@ some aspects of the preview. In particular, the @code{:scale} (and for HTML export, @code{:html-scale}) property can be used to adjust the size of the preview images. -@node CDLaTeX mode, , Previewing LaTeX fragments, Embedded LaTeX -@subsection Using CDLa@TeX{} to enter math -@cindex CDLa@TeX{} +@node CDLaTeX mode, , Previewing @LaTeX{} fragments, Embedded @LaTeX{} +@subsection Using CD@LaTeX{} to enter math +@cindex CD@LaTeX{} -CDLa@TeX{} mode is a minor mode that is normally used in combination with a +CD@LaTeX{} mode is a minor mode that is normally used in combination with a major @LaTeX{} mode like AUC@TeX{} in order to speed-up insertion of -environments and math templates. Inside Org-mode, you can make use of -some of the features of CDLa@TeX{} mode. You need to install +environments and math templates. Inside Org mode, you can make use of +some of the features of CD@LaTeX{} mode. You need to install @file{cdlatex.el} and @file{texmathp.el} (the latter comes also with AUC@TeX{}) from @url{http://www.astro.uva.nl/~dominik/Tools/cdlatex}. -Don't use CDLa@TeX{} mode itself under Org-mode, but use the light -version @code{org-cdlatex-mode} that comes as part of Org-mode. Turn it +Don't use CD@LaTeX{} mode itself under Org mode, but use the light +version @code{org-cdlatex-mode} that comes as part of Org mode. Turn it on for the current buffer with @code{M-x org-cdlatex-mode}, or for all Org files with @@ -9369,7 +9496,7 @@ Org files with @end lisp When this mode is enabled, the following features are present (for more -details see the documentation of CDLa@TeX{} mode): +details see the documentation of CD@LaTeX{} mode): @itemize @bullet @kindex C-c @{ @item @@ -9377,7 +9504,7 @@ Environment templates can be inserted with @kbd{C-c @{}. @item @kindex @key{TAB} The @key{TAB} key will do template expansion if the cursor is inside a -@LaTeX{} fragment@footnote{Org-mode has a method to test if the cursor is +@LaTeX{} fragment@footnote{Org mode has a method to test if the cursor is inside such a fragment, see the documentation of the function @code{org-inside-LaTeX-fragment-p}.}. For example, @key{TAB} will expand @code{fr} to @code{\frac@{@}@{@}} and position the cursor @@ -9414,20 +9541,20 @@ is normal. @chapter Exporting @cindex exporting -Org-mode documents can be exported into a variety of other formats. For +Org mode documents can be exported into a variety of other formats. For printing and sharing of notes, ASCII export produces a readable and simple version of an Org file. HTML export allows you to publish a notes file on the web, while the XOXO format provides a solid base for exchange with a -broad range of other applications. @LaTeX{} export lets you use Org-mode and +broad range of other applications. @LaTeX{} export lets you use Org mode and its structured editing functions to easily create @LaTeX{} files. DocBook export makes it possible to convert Org files to many other formats using -DocBook tools. OpenDocumentText export allows seamless collaboration across -organizational boundaries. For project management you can create gantt and -resource charts by using TaskJuggler export. To incorporate entries with -associated times like deadlines or appointments into a desktop calendar -program like iCal, Org-mode can also produce extracts in the iCalendar -format. Currently Org-mode only supports export, not import of these -different formats. +DocBook tools. OpenDocument Text(@acronym{ODT}) export allows seamless +colloboration across organizational boundaries. For project management you +can create gantt and resource charts by using TaskJuggler export. To +incorporate entries with associated times like deadlines or appointments into +a desktop calendar program like iCal, Org mode can also produce extracts in +the iCalendar format. Currently Org mode only supports export, not import of +these different formats. Org supports export of selected regions when @code{transient-mark-mode} is enabled (default in Emacs 23). @@ -9438,9 +9565,9 @@ enabled (default in Emacs 23). * The export dispatcher:: How to access exporter commands * ASCII/Latin-1/UTF-8 export:: Exporting to flat files with encoding * HTML export:: Exporting to HTML -* LaTeX and PDF export:: Exporting to @LaTeX{}, and processing to PDF +* @LaTeX{} and PDF export:: Exporting to @LaTeX{}, and processing to PDF * DocBook export:: Exporting to DocBook -* OpenDocumentText export:: Exporting to OpenDocumentText +* OpenDocument Text export:: Exporting to OpenDocument Text * TaskJuggler export:: Exporting to TaskJuggler * Freemind export:: Exporting to Freemind mind maps * XOXO export:: Exporting to XOXO @@ -9456,7 +9583,8 @@ enabled (default in Emacs 23). @cindex org-export-with-tasks You may use tags to select the parts of a document that should be exported, or to exclude parts from export. This behavior is governed by two variables: -@code{org-export-select-tags} and @code{org-export-exclude-tags}. +@code{org-export-select-tags} and @code{org-export-exclude-tags}, +respectively defaulting to @code{'(:export:)} and @code{'(:noexport:)}. @enumerate @item @@ -9517,10 +9645,11 @@ Insert template with export options, see example below. @vindex user-full-name @vindex user-mail-address @vindex org-export-default-language +@vindex org-export-date-timestamp-format @example #+TITLE: the title to be shown (default is the buffer name) #+AUTHOR: the author (default taken from @code{user-full-name}) -#+DATE: a date, fixed, or a format string for @code{format-time-string} +#+DATE: a date, an Org timestamp@footnote{@code{org-export-date-timestamp-format} defines how this timestamp will be exported.}, or a format string for @code{format-time-string} #+EMAIL: his/her email address (default from @code{user-mail-address}) #+DESCRIPTION: the page description, e.g.@: for the XHTML meta tag #+KEYWORDS: the page keywords, e.g.@: for the XHTML meta tag @@ -9528,19 +9657,19 @@ Insert template with export options, see example below. #+TEXT: Some descriptive text to be inserted at the beginning. #+TEXT: Several lines may be given. #+OPTIONS: H:2 num:t toc:t \n:nil @@:t ::t |:t ^:t f:t TeX:t ... -#+BIND: lisp-var lisp-val, e.g.@:: org-export-latex-low-levels itemize +#+BIND: lisp-var lisp-val, e.g.@:: @code{org-export-latex-low-levels itemize} @r{You need to confirm using these, or configure @code{org-export-allow-BIND}} #+LINK_UP: the ``up'' link of an exported page #+LINK_HOME: the ``home'' link of an exported page -#+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage@{xyz@} +#+LATEX_HEADER: extra line(s) for the @LaTeX{} header, like \usepackage@{xyz@} #+EXPORT_SELECT_TAGS: Tags that select a tree for export #+EXPORT_EXCLUDE_TAGS: Tags that exclude a tree from export #+XSLT: the XSLT stylesheet used by DocBook exporter to generate FO file @end example @noindent -The OPTIONS line is a compact@footnote{If you want to configure many options -this way, you can use several OPTIONS lines.} form to specify export +The @code{#+OPTIONS} line is a compact@footnote{If you want to configure many options +this way, you can use several @code{#+OPTIONS} lines.} form to specify export settings. Here you can: @cindex headline levels @cindex section-numbers @@ -9642,7 +9771,7 @@ not set, or force processing in the current Emacs process if set. @cindex Latin-1 export @cindex UTF-8 export -ASCII export produces a simple and very readable version of an Org-mode +ASCII export produces a simple and very readable version of an Org mode file, containing only plain ASCII. Latin-1 and UTF-8 export augment the file with special characters and symbols available in these encodings. @@ -9697,18 +9826,18 @@ Links will be exported in a footnote-like style, with the descriptive part in the text and the link in a note before the next heading. See the variable @code{org-export-ascii-links-to-notes} for details and other options. -@node HTML export, LaTeX and PDF export, ASCII/Latin-1/UTF-8 export, Exporting +@node HTML export, @LaTeX{} and PDF export, ASCII/Latin-1/UTF-8 export, Exporting @section HTML export @cindex HTML export -Org-mode contains an HTML (XHTML 1.0 strict) exporter with extensive +Org mode contains an HTML (XHTML 1.0 strict) exporter with extensive HTML formatting, in ways similar to John Gruber's @emph{markdown} language, but with additional support for tables. @menu * HTML Export commands:: How to invoke HTML export * HTML preamble and postamble:: How to insert a preamble and a postamble -* Quoting HTML tags:: Using direct HTML in Org-mode +* Quoting HTML tags:: Using direct HTML in Org mode * Links in HTML export:: How links will be interpreted and formatted * Tables in HTML export:: How to modify the formatting of tables * Images in HTML export:: How to insert figures into HTML output @@ -9746,11 +9875,11 @@ the region. This is good for cut-and-paste operations. @item C-c C-e v h/b/H/R Export only the visible part of the document. @item M-x org-export-region-as-html -Convert the region to HTML under the assumption that it was Org-mode +Convert the region to HTML under the assumption that it was Org mode syntax before. This is a global command that can be invoked in any buffer. @item M-x org-replace-region-by-HTML -Replace the active region (assumed to be in Org-mode syntax) by HTML +Replace the active region (assumed to be in Org mode syntax) by HTML code. @end table @@ -9852,7 +9981,7 @@ and @code{style} attributes for a link: @cindex #+ATTR_HTML @example -#+ATTR_HTML: title="The Org-mode homepage" style="color:red;" +#+ATTR_HTML: title="The Org mode homepage" style="color:red;" [[http://orgmode.org]] @end example @@ -9861,7 +9990,7 @@ and @code{style} attributes for a link: @cindex tables, in HTML @vindex org-export-html-table-tag -Org-mode tables are exported to HTML using the table tag defined in +Org mode tables are exported to HTML using the table tag defined in @code{org-export-html-table-tag}. The default setting makes tables without cell borders and frame. If you would like to change this for individual tables, place something like the following before the table: @@ -9870,7 +9999,7 @@ tables, place something like the following before the table: @cindex #+ATTR_HTML @example #+CAPTION: This is a table with lines around and between cells -#+ATTR_HTML: border="2" rules="all" frame="all" +#+ATTR_HTML: border="2" rules="all" frame="border" @end example @node Images in HTML export, Math formatting in HTML export, Tables in HTML export, HTML export @@ -9915,11 +10044,11 @@ You could use @code{http} addresses just as well. @cindex MathJax @cindex dvipng -@LaTeX{} math snippets (@pxref{LaTeX fragments}) can be displayed in two +@LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be displayed in two different ways on HTML pages. The default is to use the @uref{http://www.mathjax.org, MathJax system} which should work out of the box with Org mode installation because @code{http://orgmode.org} serves -@file{MathJax} for Org-mode users for small applications and for testing +@file{MathJax} for Org mode users for small applications and for testing purposes. @b{If you plan to use this regularly or on pages with significant page views, you should install@footnote{Installation instructions can be found on the MathJax website, see @@ -9985,7 +10114,7 @@ addition to any of the standard classes like for headlines, tables, etc. @example p.author @r{author information, including email} p.date @r{publishing date} -p.creator @r{creator info, about org-mode version} +p.creator @r{creator info, about org mode version} .title @r{document title} .todo @r{TODO keywords, all not-done states} .done @r{the DONE keywords, all states that count as done} @@ -10111,16 +10240,16 @@ You can choose default values for these options by customizing the variable @code{org-infojs-options}. If you always want to apply the script to your pages, configure the variable @code{org-export-html-use-infojs}. -@node LaTeX and PDF export, DocBook export, HTML export, Exporting +@node @LaTeX{} and PDF export, DocBook export, HTML export, Exporting @section @LaTeX{} and PDF export @cindex @LaTeX{} export @cindex PDF export @cindex Guerry, Bastien -Org-mode contains a @LaTeX{} exporter written by Bastien Guerry. With -further processing@footnote{The default LaTeX output is designed for -processing with pdftex or latex. It includes packages that are not -compatible with xetex and possibly luatex. See the variables +Org mode contains a @LaTeX{} exporter written by Bastien Guerry. With +further processing@footnote{The default @LaTeX{} output is designed for +processing with @code{pdftex} or @LaTeX{}. It includes packages that are not +compatible with @code{xetex} and possibly @code{luatex}. See the variables @code{org-export-latex-default-packages-alist} and @code{org-export-latex-packages-alist}.}, this backend is also used to produce PDF output. Since the @LaTeX{} output uses @file{hyperref} to @@ -10130,15 +10259,15 @@ structured in order to be correctly exported: respect the hierarchy of sections. @menu -* LaTeX/PDF export commands:: Which key invokes which commands +* @LaTeX{}/PDF export commands:: * Header and sectioning:: Setting up the export file structure -* Quoting LaTeX code:: Incorporating literal @LaTeX{} code -* Tables in LaTeX export:: Options for exporting tables to @LaTeX{} -* Images in LaTeX export:: How to insert figures into @LaTeX{} output +* Quoting @LaTeX{} code:: Incorporating literal @LaTeX{} code +* Tables in @LaTeX{} export:: Options for exporting tables to @LaTeX{} +* Images in @LaTeX{} export:: How to insert figures into @LaTeX{} output * Beamer class export:: Turning the file into a presentation @end menu -@node LaTeX/PDF export commands, Header and sectioning, LaTeX and PDF export, LaTeX and PDF export +@node @LaTeX{}/PDF export commands, Header and sectioning, @LaTeX{} and PDF export, @LaTeX{} and PDF export @subsection @LaTeX{} export commands @cindex region, active @@ -10160,11 +10289,11 @@ Export to a temporary buffer. Do not create a file. @item C-c C-e v l/L Export only the visible part of the document. @item M-x org-export-region-as-latex -Convert the region to @LaTeX{} under the assumption that it was Org-mode +Convert the region to @LaTeX{} under the assumption that it was Org mode syntax before. This is a global command that can be invoked in any buffer. @item M-x org-replace-region-by-latex -Replace the active region (assumed to be in Org-mode syntax) by @LaTeX{} +Replace the active region (assumed to be in Org mode syntax) by @LaTeX{} code. @orgcmd{C-c C-e p,org-export-as-pdf} Export as @LaTeX{} and then process to PDF. @@ -10190,13 +10319,13 @@ with a numeric prefix argument. For example, @noindent creates two levels of headings and does the rest as items. -@node Header and sectioning, Quoting LaTeX code, LaTeX/PDF export commands, LaTeX and PDF export +@node Header and sectioning, Quoting @LaTeX{} code, @LaTeX{}/PDF export commands, @LaTeX{} and PDF export @subsection Header and sectioning structure @cindex @LaTeX{} class @cindex @LaTeX{} sectioning structure @cindex @LaTeX{} header -@cindex header, for LaTeX files -@cindex sectioning structure, for LaTeX export +@cindex header, for @LaTeX{} files +@cindex sectioning structure, for @LaTeX{} export By default, the @LaTeX{} output uses the class @code{article}. @@ -10224,10 +10353,10 @@ can also use @code{#+LATEX_HEADER: \usepackage@{xyz@}} to add lines to the header. See the docstring of @code{org-export-latex-classes} for more information. -@node Quoting LaTeX code, Tables in LaTeX export, Header and sectioning, LaTeX and PDF export +@node Quoting @LaTeX{} code, Tables in @LaTeX{} export, Header and sectioning, @LaTeX{} and PDF export @subsection Quoting @LaTeX{} code -Embedded @LaTeX{} as described in @ref{Embedded LaTeX}, will be correctly +Embedded @LaTeX{} as described in @ref{Embedded @LaTeX{}}, will be correctly inserted into the @LaTeX{} file. This includes simple macros like @samp{\ref@{LABEL@}} to create a cross reference to a figure. Furthermore, you can add special code that should only be present in @LaTeX{} export with @@ -10236,7 +10365,7 @@ the following constructs: @cindex #+LaTeX @cindex #+BEGIN_LaTeX @example -#+LaTeX: Literal LaTeX code for export +#+LaTeX: Literal @LaTeX{} code for export @end example @noindent or @@ -10249,7 +10378,7 @@ All lines between these markers are exported literally @end example -@node Tables in LaTeX export, Images in LaTeX export, Quoting LaTeX code, LaTeX and PDF export +@node Tables in @LaTeX{} export, Images in @LaTeX{} export, Quoting @LaTeX{} code, @LaTeX{} and PDF export @subsection Tables in @LaTeX{} export @cindex tables, in @LaTeX{} export @@ -10286,7 +10415,7 @@ or to specify a multicolumn table with @code{tabulary} | ..... | ..... | @end example -@node Images in LaTeX export, Beamer class export, Tables in LaTeX export, LaTeX and PDF export +@node Images in @LaTeX{} export, Beamer class export, Tables in @LaTeX{} export, @LaTeX{} and PDF export @subsection Images in @LaTeX{} export @cindex images, inline in @LaTeX{} @cindex inlining images in @LaTeX{} @@ -10337,14 +10466,14 @@ will export the image wrapped in a @code{figure*} environment. If you need references to a label created in this way, write @samp{\ref@{fig:SED-HR4049@}} just like in @LaTeX{}. -@node Beamer class export, , Images in LaTeX export, LaTeX and PDF export +@node Beamer class export, , Images in @LaTeX{} export, @LaTeX{} and PDF export @subsection Beamer class export -The LaTeX class @file{beamer} allows production of high quality presentations -using LaTeX and pdf processing. Org-mode has special support for turning an -Org-mode file or tree into a @file{beamer} presentation. +The @LaTeX{} class @file{beamer} allows production of high quality presentations +using @LaTeX{} and pdf processing. Org mode has special support for turning an +Org mode file or tree into a @file{beamer} presentation. -When the LaTeX class for the current buffer (as set with @code{#+LaTeX_CLASS: +When the @LaTeX{} class for the current buffer (as set with @code{#+LaTeX_CLASS: beamer}) or subtree (set with a @code{LaTeX_CLASS} property) is @code{beamer}, a special export mode will turn the file or tree into a beamer presentation. Any tree with not-too-deep level nesting should in principle be @@ -10464,7 +10593,7 @@ Here is a simple example Org document that is intended for beamer export. For more information, see the documentation on Worg. -@node DocBook export, OpenDocumentText export, LaTeX and PDF export, Exporting +@node DocBook export, OpenDocument Text export, @LaTeX{} and PDF export, Exporting @section DocBook export @cindex DocBook export @cindex PDF export @@ -10620,7 +10749,7 @@ set: @cindex #+LABEL @cindex #+ATTR_DOCBOOK @example -#+CAPTION: The logo of Org-mode +#+CAPTION: The logo of Org mode #+LABEL: unicorn-svg #+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%" [[./img/org-mode-unicorn.svg]] @@ -10663,39 +10792,46 @@ special characters included in XHTML entities: @c begin opendocument -@node OpenDocumentText export, TaskJuggler export, DocBook export, Exporting -@section OpenDocumentText export -@cindex OpenDocumentText export +@node OpenDocument Text export, TaskJuggler export, DocBook export, Exporting +@section OpenDocument Text export @cindex K, Jambunathan - -Org-mode 7.6 supports export to OpenDocumentText format using -@file{org-odt.el} module contributed by Jambunathan K. This module can be -enabled in one of the following ways based on your mode of installation. - -@enumerate -@item -If you have downloaded the Org from the Web, either as a distribution -@file{.zip} or @file{.tar} file, or as a Git archive, enable the @code{odt} -option in variable @code{org-modules}. -@item -If you are using Org that comes bundled with Emacs, then you can install the -OpenDocumentText exporter using the package manager. To do this, customize -the variable @code{package-archives} to include -@uref{http://orgmode.org/pkg/releases/} as one of the package archives. -@end enumerate +@cindex ODT +@cindex OpenDocument +@cindex export, OpenDocument +@cindex LibreOffice +@cindex org-odt.el +@cindex org-modules + +Orgmode@footnote{Versions 7.8 or later} supports export to OpenDocument Text +(@acronym{ODT}) format using the @file{org-odt.el} module. Documents created +by this exporter use the @cite{OpenDocument-v1.2 +specification}@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, +Open Document Format for Office Applications (OpenDocument) Version 1.2}} and +are compatible with LibreOffice 3.4. @menu -* OpenDocumentText export commands::How to invoke OpenDocumentText export -* Applying Custom Styles:: How to apply custom styles to the output -* Converting to Other formats:: How to convert to formats like doc, docx etc -* Links in OpenDocumentText export:: How links will be interpreted and formatted -* Tables in OpenDocumentText export:: Tables are exported as HTML tables -* Images in OpenDocumentText export:: How to insert figures into DocBook output -* Additional Documentation:: Where to find more information +* Pre-requisites for @acronym{ODT} export:: What packages @acronym{ODT} exporter relies on +* @acronym{ODT} export commands:: How to invoke @acronym{ODT} export +* Applying custom styles:: How to apply custom styles to the output +* Links in @acronym{ODT} export:: How links will be interpreted and formatted +* Tables in @acronym{ODT} export:: How Tables are exported +* Images in @acronym{ODT} export:: How to insert images +* Math formatting in @acronym{ODT} export:: How @LaTeX{} fragments are formatted +* Literal examples in @acronym{ODT} export:: How source and example blocks are formatted +* Advanced topics in @acronym{ODT} export:: Read this if you are a power user @end menu -@node OpenDocumentText export commands, Applying Custom Styles, OpenDocumentText export, OpenDocumentText export -@subsection OpenDocumentText export commands +@node Pre-requisites for @acronym{ODT} export, @acronym{ODT} export commands, OpenDocument Text export, OpenDocument Text export +@subsection Pre-requisites for @acronym{ODT} export +@cindex zip +The @acronym{ODT} exporter relies on the @file{zip} program to create the final +output. Check the availability of this program before proceeding further. + +@node @acronym{ODT} export commands, Applying custom styles, Pre-requisites for @acronym{ODT} export, OpenDocument Text export +@subsection @acronym{ODT} export commands + +@subsubheading Exporting to @acronym{ODT} +@anchor{x-export-to-odt} @cindex region, active @cindex active region @@ -10703,113 +10839,791 @@ the variable @code{package-archives} to include @table @kbd @orgcmd{C-c C-e o,org-export-as-odt} @cindex property EXPORT_FILE_NAME -Export as OpenDocumentText file. For an Org file, @file{myfile.org}, the -OpenDocumentText file will be @file{myfile.odt}. The file will be -overwritten without warning. If there is an active region@footnote{This -requires @code{transient-mark-mode} to be turned on}, only the region will be -exported. If the selected region is a single tree@footnote{To select the -current subtree, use @kbd{C-c @@}.}, the tree head will become the document -title. If the tree head entry has, or inherits, an @code{EXPORT_FILE_NAME} -property, that name will be used for the export. + +Export as OpenDocument Text file. +@vindex org-export-odt-preferred-output-format +If @code{org-export-odt-preferred-output-format} is specified, automatically +convert the exported file to that format. +@xref{x-export-to-other-formats,,Automatically exporting to other formats}. + +For an Org file @file{myfile.org}, the @acronym{ODT} file will be +@file{myfile.odt}. The file will be overwritten without warning. If there +is an active region,@footnote{This requires @code{transient-mark-mode} to be +turned on} only the region will be exported. If the selected region is a +single tree,@footnote{To select the current subtree, use @kbd{C-c @@}} the +tree head will become the document title. If the tree head entry has, or +inherits, an @code{EXPORT_FILE_NAME} property, that name will be used for the +export. + @orgcmd{C-c C-e O,org-export-as-odt-and-open} -Export as OpenDocumentText file and open the resulting file. +Export as OpenDocument Text file and open the resulting file. +@vindex org-export-odt-preferred-output-format +If @code{org-export-odt-preferred-output-format} is specified, open the +converted file instead. +@xref{x-export-to-other-formats,,Automatically exporting to other formats}. @end table -@node Applying Custom Styles, Converting to Other formats, OpenDocumentText export commands, OpenDocumentText export -@subsection Applying Custom Styles +@subsubheading Automatically exporting to other formats +@anchor{x-export-to-other-formats} +@vindex org-export-odt-preferred-output-format +Very often, you will find yourself exporting to @acronym{ODT} format, only to +immediately save the exported document to a different format like @samp{pdf}. +In such cases, you will find it convenient to configure a converter +(@pxref{Exporting and converting to other formats}) and specify your +preferred output format by customizing the variable +@code{org-export-odt-preferred-output-format}. This way, the export commands +(@pxref{x-export-to-odt,,Exporting to ODT}) can be extended to also export to +the preferred format. + +@node Applying custom styles, Links in @acronym{ODT} export, @acronym{ODT} export commands, OpenDocument Text export +@subsection Applying custom styles @cindex styles, custom @cindex template, custom -@vindex org-export-odt-styles-file +The @acronym{ODT} exporter ships with a set of OpenDocument styles +(@pxref{Working with OpenDocument style files}) that ensure a well-formatted +output. These factory styles, however, may not cater to your specific +tastes. To customize the output, you can either modify the above styles +files directly, or generate the required styles using an application like +LibreOffice. The latter method is suitable for expert and non-expert +users alike, and is described here. -OpenDocumentExporter ships with a custom @file{styles.xml} for formatting of -the exported file. To customize the output to suit your needs you can use -one of the following methods: +@subsubsection Applying custom styles - the easy way @enumerate @item -Customize the variable @code{org-export-odt-styles-file} to point to either a -@file{styles.xml} file, a OpenDocument Text Template file @code{.ott} or a -combination of Text or Template Document together with a set of member files. -Use the first two options if the styles.xml has no references to additional -set of files and use the last option if the @file{styles.xml} references -additional files like header and footer images. +Create a sample @file{example.org} file with the below settings and export it +to @acronym{ODT} format. + +@example +#+OPTIONS: H:10 num:t +@end example + +@item +Open the above @file{example.odt} using LibreOffice. Use the @file{Stylist} +to locate the target styles - these typically have the @samp{Org} prefix - +and modify those to your taste. Save the modified file either as an +OpenDocument Text (@file{.odt}) or OpenDocument Template (@file{.ott}) file. + @item -Use an external tool like unoconv to apply custom templates. +@cindex #+ODT_STYLES_FILE +@vindex org-export-odt-styles-file +Customize the variable @code{org-export-odt-styles-file} and point it to the +newly created file. For additional configuration options +@pxref{x-overriding-factory-styles,,Overriding factory styles}. + +If you would like to choose a style on a per-file basis, you can use the +@code{#+ODT_STYLES_FILE} option. A typical setting will look like + +@example +#+ODT_STYLES_FILE: "/path/to/example.ott" +@end example + +or + +@example +#+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png")) +@end example + @end enumerate -For best results, it is necessary that the style names used by -OpenDocumentText exporter match that used in the @file{styles.xml}. +@subsubsection Using third-party styles and templates + +You can use third-party styles and templates for customizing your output. +This will produce the desired output only if the template provides all +style names that the @samp{ODT} exporter relies on. Unless this condition is +met, the output is going to be less than satisfactory. So it is highly +recommended that you only work with templates that are directly derived from +the factory settings. + +@node Links in @acronym{ODT} export, Tables in @acronym{ODT} export, Applying custom styles, OpenDocument Text export +@subsection Links in @acronym{ODT} export +@cindex tables, in DocBook export + +The @acronym{ODT} exporter creates cross-references (aka bookmarks) for +internal links. It creates Internet-style links for all other links. + +@node Tables in @acronym{ODT} export, Images in @acronym{ODT} export, Links in @acronym{ODT} export, OpenDocument Text export +@subsection Tables in @acronym{ODT} export +@cindex tables, in DocBook export -@node Converting to Other formats, Links in OpenDocumentText export, Applying Custom Styles, OpenDocumentText export -@subsection Converting to Other formats +Export of native Org mode tables (@pxref{Tables}) and simple @file{table.el} +tables is supported. However, export of complex @file{table.el} tables - +tables that have column or row spans - is not supported. Such tables are +stripped from the exported document. +By default, a table is exported with top and bottom frames and with +rules separating row and column groups (@pxref{Column groups}). If the table +specifies alignment and relative width for its columns (@pxref{Column width +and alignment}) then these are honored on export.@footnote{The column widths +are interpreted as weighted ratios with the default weight being 1} + +@cindex #+ATTR_ODT +If you are not satisfied with the default formatting of tables, you can +create custom table styles and associate them with a table using +the @code{#+ATTR_ODT} line. @xref{Customizing tables in @acronym{ODT} export}. + +@node Images in @acronym{ODT} export, Math formatting in @acronym{ODT} export, Tables in @acronym{ODT} export, OpenDocument Text export +@subsection Images in @acronym{ODT} export +@cindex images, embedding in @acronym{ODT} +@cindex embedding images in @acronym{ODT} + +@subsubheading Embedding images +You can embed images within the exported document by providing a link to the +desired image file with no link description. For example, to embed +@samp{img.png} do either of the following: + +@example +[[file:img.png]] +@end example + +@example +[[./img.png]] +@end example + +@subsubheading Embedding clickable images +You can create clickable images by providing a link whose description is a +link to an image file. For example, to embed a image +@file{org-mode-unicorn.png} which when clicked jumps to +@uref{http://Orgmode.org} website, do the following + +@example +[[http://orgmode.org][./org-mode-unicorn.png]] +@end example + +@subsubheading Sizing and scaling of embedded images + +You can control the size and scale of the embedded images using the +@code{#+ATTR_ODT} attribute. + +@vindex org-export-odt-pixels-per-inch +Note that the exporter specifies the desired size of the image in the final +document in units of centimetres. In order to scale the embedded images, the +exporter needs to compute the size of the image. This is done by retrieving +the image size in pixels and converting the pixel units to centimetres using +@code{org-export-odt-pixels-per-inch}. The default value of this variable is +set to @code{display-pixels-per-inch}. You can tweak this variable to +achieve the best results. + +The examples below illustrate the various possibilities. + +@table @asis + +@item Explicitly size the image +To embed @file{img.png} as a 10 cm x 10 cm image, do the following: + +@example +#+ATTR_ODT: :width 10 :height 10 +[[./img.png]] +@end example + +@item Scale the image +To embed @file{img.png} at half its size, do the following: + +@example +#+ATTR_ODT: :scale 0.5 +[[./img.png]] +@end example + +@item Scale the image to a specific width +To embed @file{img.png} with a width of 10 cm while retaining the original +height:width ratio, do the following: + +@example +#+ATTR_ODT: :width 10 +[[./img.png]] +@end example + +@item Scale the image to a specific height +To embed @file{img.png} with a height of 10 cm while retaining the original +height:width ratio, do the following + +@example +#+ATTR_ODT: :height 10 +[[./img.png]] +@end example +@end table + +@node Math formatting in @acronym{ODT} export, Literal examples in @acronym{ODT} export, Images in @acronym{ODT} export, OpenDocument Text export +@subsection Math formatting in @acronym{ODT} export + +The @acronym{ODT} exporter has special support for handling math. + +@menu +* Working with @LaTeX{} math snippets:: How to embed @LaTeX{} math fragments +* Working with MathML or OpenDocument formula files:: How to embed equations in native format +@end menu + +@node Working with @LaTeX{} math snippets, Working with MathML or OpenDocument formula files, Math formatting in @acronym{ODT} export, Math formatting in @acronym{ODT} export +@subsubsection Working with @LaTeX{} math snippets + +@LaTeX{} math snippets (@pxref{@LaTeX{} fragments}) can be embedded in the ODT +document in one of the following ways: + +@cindex MathML +@enumerate +@item MathML + +This option is activated on a per-file basis with + +@example +#+OPTIONS: LaTeX:t +@end example + +With this option, @LaTeX{} fragments are first converted into MathML +fragments using an external @LaTeX{}-to-MathML converter program. The +resulting MathML fragments are then embedded as an OpenDocument Formula in +the exported document. + +@vindex org-latex-to-mathml-convert-command +@vindex org-latex-to-mathml-jar-file + +You can specify the @LaTeX{}-to-MathML converter by customizing the variables +@code{org-latex-to-mathml-convert-command} and +@code{org-latex-to-mathml-jar-file}. + +If you prefer to use @file{MathToWeb}@footnote{See +@uref{http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl, MathToWeb}} as your +converter, you can configure the above variables as shown below. + +@lisp +(setq org-latex-to-mathml-convert-command + "java -jar %j -unicode -force -df %o %I" + org-latex-to-mathml-jar-file + "/path/to/mathtoweb.jar") +@end lisp + +You can use the following commands to quickly verify the reliability of +the @LaTeX{}-to-MathML converter. + +@table @kbd + +@item M-x org-export-as-odf +Convert a @LaTeX{} math snippet to OpenDocument formula (@file{.odf}) file. + +@item M-x org-export-as-odf-and-open +Convert a @LaTeX{} math snippet to OpenDocument formula (@file{.odf}) file and +open the formula file with the system-registered application. +@end table + +@cindex dvipng +@item PNG images + +This option is activated on a per-file basis with + +@example +#+OPTIONS: LaTeX:dvipng +@end example + +With this option, @LaTeX{} fragments are processed into PNG images and the +resulting images are embedded in the exported document. This method requires +that the @file{dvipng} program be available on your system. +@end enumerate + +@node Working with MathML or OpenDocument formula files, , Working with @LaTeX{} math snippets, Math formatting in @acronym{ODT} export +@subsubsection Working with MathML or OpenDocument formula files + +For various reasons, you may find embedding @LaTeX{} math snippets in an +@acronym{ODT} document less than reliable. In that case, you can embed a +math equation by linking to its MathML(@file{.mml}) source or its +OpenDocument formula (@file{.odf}) file as shown below: + +@example +[[./equation.mml]] +@end example + +or + +@example +[[./equation.odf]] +@end example + +@node Literal examples in @acronym{ODT} export, Advanced topics in @acronym{ODT} export, Math formatting in @acronym{ODT} export, OpenDocument Text export +@subsection Literal examples in @acronym{ODT} export + +Export of literal examples (@pxref{Literal examples}) with full fontification +is supported. This feature is enabled by default and is activated +automatically if an enhanced version of @file{htmlfontify.el} is available in +the @code{load-path}.@footnote{The @file{htmlfontify.el} that ships with +standard Emacs <= 24.1 has no support for @acronym{ODT} fontification. A +copy of the proposed version is available as an attachment to +@url{http://debbugs.gnu.org/cgi/bugreport.cgi?msg=5;filename=htmlfontify.el;att=9;bug=9914, +Emacs Bug #9914}.} + +@vindex org-export-odt-fontify-srcblocks + +The character styles used for fontification of the literal blocks are +auto-generated by the exporter in conjunction with @file{htmlfontify.el} +library and need not be included in the default @file{styles.xml} file. +These auto-generated styles have the @samp{OrgSrc} prefix and inherit their color +based on the face used by Emacs @code{font-lock} library. + +@vindex org-export-odt-create-custom-styles-for-srcblocks +If you prefer to use your own custom styles for fontification and disable +their auto-generation altogether, you can do so by customizing the variable +@code{org-export-odt-create-custom-styles-for-srcblocks}. + +You can turn off fontification support for literal examples by customizing +the variable @code{org-export-odt-fontify-srcblocks}. + + +@node Advanced topics in @acronym{ODT} export, , Literal examples in @acronym{ODT} export, OpenDocument Text export +@subsection Advanced topics in @acronym{ODT} export + +If you rely heavily on @acronym{ODT} export, you may want to exploit the full +set of features that the exporter offers. This section describes features +that would be of interest to power users. + +@menu +* Exporting and converting to other formats:: How to produce @samp{pdf} and other formats +* Working with OpenDocument style files:: Explore the internals +* Creating one-off styles:: How to produce custom highlighting etc +* Customizing tables in @acronym{ODT} export:: How to define and use Table templates +* Validating OpenDocument XML:: How to debug corrupt OpenDocument files +@end menu + +@node Exporting and converting to other formats, Working with OpenDocument style files, Advanced topics in @acronym{ODT} export, Advanced topics in @acronym{ODT} export +@subsubsection Exporting and converting to other formats @cindex convert @cindex doc, docx -@vindex org-export-odt-styles-file - -Often times there is a need to convert OpenDocumentText files to other -formats like doc, docx or pdf. You can accomplish this by one of the -following methods: +The @acronym{ODT} exporter adds support for exporting Org outlines to formats +that are not supported natively by Org. It also adds support to convert +document from one format to another. To use these features, you need to +configure a command-line converter. Once a command-line converter is +configured you can use it to extend the list of formats to which Org can +export. @xref{x-export-to-other-formats,,Automatically exporting to other +formats}. You can also use it to perform one-off document conversion as +detailed below. +@vindex org-export-odt-convert @table @kbd -@item M-x org-lparse -Export the outline first to one of the native formats (like OpenDocumentText) -and immediately post-process it to other formats using an external converter. -@item M-x org-lparse-convert -Export an existing document to other formats using an external converter. +@item M-x org-export-odt-convert +Convert an existing document from one format to another as determined by the +variable @code{org-export-odt-convert-capabilities} +(@pxref{x-odt-converter-capabilities,,Configure converter +capabilities}). @strong{Please note} that you can use this command to even +convert documents that are produced outside of Org and in other formats than +@acronym{ODT} format. @end table -You can choose the converter used for conversion by customizing the variable -@code{org-lparse-convert-process}. +@subsubheading Pre-configured converters -@node Links in OpenDocumentText export, Tables in OpenDocumentText export, Converting to Other formats, OpenDocumentText export -@subsection Links in OpenDocumentText export -@cindex tables, in DocBook export +@cindex converter +The @acronym{ODT} exporter supports two converters out of the box: -OpenDocumentExporter creates cross-references (aka bookmarks) for links that -are destined locally. It creates internet style links for all other links. +@enumerate -@node Tables in OpenDocumentText export, Images in OpenDocumentText export, Links in OpenDocumentText export, OpenDocumentText export -@subsection Tables in OpenDocumentText export -@cindex tables, in DocBook export +@cindex @file{unoconv} +@item @file{unoconv} -Export of @file{table.el} tables with row or column spanning is not -supported. Such tables are stripped from the exported document. +This converter is available as an installable package in your favorite +distribution. -@node Images in OpenDocumentText export, Additional Documentation, Tables in OpenDocumentText export, OpenDocumentText export -@subsection Images in OpenDocumentText export -@cindex images, embedding in OpenDocumentText -@cindex embedding images in OpenDocumentText +@cindex @file{BasicODConverter} +@item @file{BasicODConverter} -OpenDocumentText exporter can embed images within the exported document. To -embed images, provide a link to the desired image file with no link -description. For example, the following links @samp{[[file:img.jpg]]} or -@samp{[[./img.jpg]]}, will result in embedding of @samp{img.jpg} in the -exported file. +@vindex org-odt-data-dir +This converter is distributed as a LibreOffice extension and can be found in +your Org distribution. See the subdirectory pointed to by the variable +@code{org-odt-data-dir}. -The exporter can also embed scaled and explicitly sized images within the -exported document. The markup of the scale and size specifications has not -been standardized yet and is hence conveniently skipped in this document. +@end enumerate + +@subsubheading Installing a new converter +If you prefer to use a converter other than the two mentioned above, then you +may have to do additional configuration. You can proceed as follows: + +@enumerate +@item Register the converter + +@vindex org-export-odt-convert-processes +Name your converter and add it to the list of known converters by customizing +the variable @code{org-export-odt-convert-processes}. Also specify how the +converter can be invoked via command-line to effect the conversion. + +@item Configure its capabilities +@vindex org-export-odt-convert-capabilities -The exporter can also make an image the clickable part of a link. To create -clickable images, provide a link whose description is a link to an image -file. For example, the following link -@samp{[[http://orgmode.org][./img.jpg]]}, will result in a clickable image -that links to @uref{http://Orgmode.org} website. +@anchor{x-odt-converter-capabilities} -@node Additional Documentation, , Images in OpenDocumentText export, OpenDocumentText export -@subsection Additional documentation +Specify the set of formats the converter can handle by customizing the +variable @code{org-export-odt-convert-capabilities}. Use the default value +for this variable as a guide for configuring your converter. As suggested by +the default setting, you can specify the full set of formats supported by the +converter and not limit yourself to specifying formats that are related to +just the OpenDocument Text format. + +@item Choose the converter + +@vindex org-export-odt-convert-process +Select the newly added converter as the preferred one by customizing the +variable @code{org-export-odt-convert-process}. +@end enumerate + +@node Working with OpenDocument style files, Creating one-off styles, Exporting and converting to other formats, Advanced topics in @acronym{ODT} export +@subsubsection Working with OpenDocument style files +@cindex styles, custom +@cindex template, custom -The OpenDocumentText exporter is still in development. For up to date -information, please follow Org mailing list @email{emacs-orgmode@@gnu.org} -closely. +This section explores the internals of the @acronym{ODT} exporter and the +means by which it produces styled documents. Read this section if you are +interested in exploring the automatic and custom OpenDocument styles used by +the exporter. + +@anchor{x-factory-styles} +@subsubheading Factory styles + +The @acronym{ODT} exporter relies on two files for generating its output. +These files are bundled with the distribution under the directory pointed to +by the variable @code{org-odt-styles-dir}. The two files are: + +@itemize +@anchor{x-orgodtstyles-xml} +@item +@file{OrgOdtStyles.xml} + +This file contributes to the @file{styles.xml} file of the final @samp{ODT} +document. This file gets modified for the following purposes: +@enumerate + +@item +To control outline numbering based on user settings. + +@item +To add styles generated by @file{htmlfontify.el} for fontification of code +blocks. +@end enumerate + +@anchor{x-orgodtcontenttemplate-xml} +@item +@file{OrgOdtContentTemplate.xml} + +This file contributes to the @file{content.xml} file of the final @samp{ODT} +document. The contents of the Org outline are inserted between the +@samp{<office:text>}@dots{}@samp{</office:text>} elements of this file. + +Apart from serving as a template file for the final @file{content.xml}, the +file serves the following purposes: +@enumerate + +@item +It contains automatic styles for formatting of tables which are referenced by +the exporter. + +@item +It contains @samp{<text:sequence-decl>}@dots{}@samp{</text:sequence-decl>} +elements that control how various entities - tables, images, equations etc - +are numbered. +@end enumerate +@end itemize + +@anchor{x-overriding-factory-styles} +@subsubheading Overriding factory styles +The following two variables control the location from which the @acronym{ODT} +exporter picks up the custom styles and content template files. You can +customize these variables to override the factory styles used by the +exporter. + +@itemize +@anchor{x-org-export-odt-styles-file} +@item +@code{org-export-odt-styles-file} + +Use this variable to specify the @file{styles.xml} that will be used in the +final output. You can specify one of the following values: + +@enumerate +@item A @file{styles.xml} file + +Use this file instead of the default @file{styles.xml} + +@item A @file{.odt} or @file{.ott} file + +Use the @file{styles.xml} contained in the specified OpenDocument Text or +Template file + +@item A @file{.odt} or @file{.ott} file and a subset of files contained within them + +Use the @file{styles.xml} contained in the specified OpenDocument Text or +Template file. Additionally extract the specified member files and embed +those within the final @samp{ODT} document. + +Use this option if the @file{styles.xml} file references additional files +like header and footer images. + +@item @code{nil} + +Use the default @file{styles.xml} +@end enumerate + +@anchor{x-org-export-odt-content-template-file} +@item +@code{org-export-odt-content-template-file} + +Use this variable to specify the blank @file{content.xml} that will be used +in the final output. +@end itemize + +@node Creating one-off styles, Customizing tables in @acronym{ODT} export, Working with OpenDocument style files, Advanced topics in @acronym{ODT} export +@subsubsection Creating one-off styles + +There are times when you would want one-off formatting in the exported +document. You can achieve this by embedding raw OpenDocument XML in the Org +file. The use of this feature is better illustrated with couple of examples. + +@enumerate +@item Embedding ODT tags as part of regular text + +You can include simple OpenDocument tags by prefixing them with +@samp{@@}. For example, to highlight a region of text do the following: + +@example +@@<text:span text:style-name="Highlight">This is a +highlighted text@@</text:span>. But this is a +regular text. +@end example + +@strong{Hint:} To see the above example in action, edit your +@file{styles.xml}(@pxref{x-orgodtstyles-xml,,Factory styles}) and add a +custom @samp{Highlight} style as shown below. + +@example +<style:style style:name="Highlight" style:family="text"> + <style:text-properties fo:background-color="#ff0000"/> +</style:style> +@end example + +@item Embedding a one-line OpenDocument XML + +You can add a simple OpenDocument one-liner using the @code{#+ODT:} +directive. For example, to force a page break do the following: + +@example +#+ODT: <text:p text:style-name="PageBreak"/> +@end example + +@strong{Hint:} To see the above example in action, edit your +@file{styles.xml}(@pxref{x-orgodtstyles-xml,,Factory styles}) and add a +custom @samp{PageBreak} style as shown below. + +@example +<style:style style:name="PageBreak" style:family="paragraph" + style:parent-style-name="Text_20_body"> + <style:paragraph-properties fo:break-before="page"/> +</style:style> +@end example + +@item Embedding a block of OpenDocument XML + +You can add a large block of OpenDocument XML using the +@code{#+BEGIN_ODT}@dots{}@code{#+END_ODT} construct. + +For example, to create a one-off paragraph that uses bold text, do the +following: + +@example +#+BEGIN_ODT +<text:p text:style-name="Text_20_body_20_bold"> +This paragraph is specially formatted and uses bold text. +</text:p> +#+END_ODT +@end example + +@end enumerate + +@node Customizing tables in @acronym{ODT} export, Validating OpenDocument XML, Creating one-off styles, Advanced topics in @acronym{ODT} export +@subsubsection Customizing tables in @acronym{ODT} export +@cindex tables, in ODT export + +@cindex #+ATTR_ODT +You can override the default formatting of the table by specifying a custom +table style with the @code{#+ATTR_ODT} line. For a discussion on default +formatting of tables @pxref{Tables in @acronym{ODT} export}. + +This feature closely mimics the way table templates are defined in the +OpenDocument-v1.2 +specification.@footnote{@url{http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html, +OpenDocument-v1.2 Specification}} + + + +@subsubheading Custom table styles - an illustration + +To have a quick preview of this feature, install the below setting and export +the table that follows. + +@lisp +(setq org-export-odt-table-styles + (append org-export-odt-table-styles + '(("TableWithHeaderRowAndColumn" "Custom" + ((use-first-row-styles . t) + (use-first-column-styles . t))) + ("TableWithFirstRowandLastRow" "Custom" + ((use-first-row-styles . t) + (use-last-row-styles . t)))))) +@end lisp + +@example +#+ATTR_ODT: TableWithHeaderRowAndColumn +| Name | Phone | Age | +| Peter | 1234 | 17 | +| Anna | 4321 | 25 | +@end example + +In the above example, you used a template named @samp{Custom} and installed +two table styles with the names @samp{TableWithHeaderRowAndColumn} and +@samp{TableWithFirstRowandLastRow}. (@strong{Important:} The OpenDocument +styles needed for producing the above template have been pre-defined for you. +These styles are available under the section marked @samp{Custom Table +Template} in @file{OrgOdtContentTemplate.xml} +(@pxref{x-orgodtcontenttemplate-xml,,Factory styles}). If you need +additional templates you have to define these styles yourselves. + +@subsubheading Custom table styles - the nitty-gritty +To use this feature proceed as follows: + +@enumerate +@item +Create a table template@footnote{See the @code{<table:table-template>} +element of the OpenDocument-v1.2 specification} + +A table template is nothing but a set of @samp{table-cell} and +@samp{paragraph} styles for each of the following table cell categories: + +@itemize @minus +@item Body +@item First column +@item Last column +@item First row +@item Last row +@item Even row +@item Odd row +@item Even column +@item Odd Column +@end itemize + +The names for the above styles must be chosen based on the name of the table +template using a well-defined convention. + +The naming convention is better illustrated with an example. For a table +template with the name @samp{Custom}, the needed style names are listed in +the following table. + +@multitable {Table cell type} {CustomEvenColumnTableCell} {CustomEvenColumnTableParagraph} +@headitem Table cell type +@tab @code{table-cell} style +@tab @code{paragraph} style +@item +@tab +@tab +@item Body +@tab @samp{CustomTableCell} +@tab @samp{CustomTableParagraph} +@item First column +@tab @samp{CustomFirstColumnTableCell} +@tab @samp{CustomFirstColumnTableParagraph} +@item Last column +@tab @samp{CustomLastColumnTableCell} +@tab @samp{CustomLastColumnTableParagraph} +@item First row +@tab @samp{CustomFirstRowTableCell} +@tab @samp{CustomFirstRowTableParagraph} +@item Last row +@tab @samp{CustomLastRowTableCell} +@tab @samp{CustomLastRowTableParagraph} +@item Even row +@tab @samp{CustomEvenRowTableCell} +@tab @samp{CustomEvenRowTableParagraph} +@item Odd row +@tab @samp{CustomOddRowTableCell} +@tab @samp{CustomOddRowTableParagraph} +@item Even column +@tab @samp{CustomEvenColumnTableCell} +@tab @samp{CustomEvenColumnTableParagraph} +@item Odd column +@tab @samp{CustomOddColumnTableCell} +@tab @samp{CustomOddColumnTableParagraph} +@end multitable + +To create a table template with the name @samp{Custom}, define the above +styles in the +@code{<office:automatic-styles>}...@code{</office:automatic-styles>} element +of the content template file (@pxref{x-orgodtcontenttemplate-xml,,Factory +styles}). + +@item +Define a table style@footnote{See the attributes @code{table:template-name}, +@code{table:use-first-row-styles}, @code{table:use-last-row-styles}, +@code{table:use-first-column-styles}, @code{table:use-last-column-styles}, +@code{table:use-banding-rows-styles}, and +@code{table:use-banding-column-styles} of the @code{<table:table>} element in +the OpenDocument-v1.2 specification} + +@vindex org-export-odt-table-styles +To define a table style, create an entry for the style in the variable +@code{org-export-odt-table-styles} and specify the following: + +@itemize @minus +@item the name of the table template created in step (1) +@item the set of cell styles in that template that are to be activated +@end itemize + +For example, the entry below defines two different table styles +@samp{TableWithHeaderRowsAndColumns} and @samp{TableWithHeaderColumns} based +on the same template @samp{Custom}. The styles achieve their intended effect +by selectively activating the individual cell styles in that template. + +@lisp +(setq org-export-odt-table-styles + (append org-export-odt-table-styles + '(("TableWithHeaderRowAndColumn" "Custom" + ((use-first-row-styles . t) + (use-first-column-styles . t))) + ("TableWithFirstRowandLastRow" "Custom" + ((use-first-row-styles . t) + (use-last-row-styles . t)))))) +@end lisp + +@item +Associate a table with the table style + +To do this, specify the table style created in step (2) as part of +the @code{ATTR_ODT} line as shown below. + +@example +#+ATTR_ODT: TableWithHeaderRowAndColumn +| Name | Phone | Age | +| Peter | 1234 | 17 | +| Anna | 4321 | 25 | +@end example +@end enumerate + +@node Validating OpenDocument XML, , Customizing tables in @acronym{ODT} export, Advanced topics in @acronym{ODT} export +@subsubsection Validating OpenDocument XML + +Occasionally, you will discover that the document created by the +@acronym{ODT} exporter cannot be opened by your favorite application. One of +the common reasons for this is that the @file{.odt} file is corrupt. In such +cases, you may want to validate the document against the OpenDocument RELAX +NG Compact Syntax (RNC) schema. + +For de-compressing the @file{.odt} file@footnote{@file{.odt} files are +nothing but @samp{zip} archives}: @inforef{File Archives,,emacs}. For +general help with validation (and schema-sensitive editing) of XML files: +@inforef{Introduction,,nxml-mode}. + +@vindex org-export-odt-schema-dir +If you have ready access to OpenDocument @file{.rnc} files and the needed +schema-locating rules in a single folder, you can customize the variable +@code{org-export-odt-schema-dir} to point to that directory. The +@acronym{ODT} exporter will take care of updating the +@code{rng-schema-locating-files} for you. @c end opendocument -@node TaskJuggler export, Freemind export, OpenDocumentText export, Exporting +@node TaskJuggler export, Freemind export, OpenDocument Text export, Exporting @section TaskJuggler export @cindex TaskJuggler export @cindex Project management @@ -10820,7 +11634,7 @@ resource assignments based on the project outline and the constraints that you have provided. The TaskJuggler exporter is a bit different from other exporters, such as the -HTML and LaTeX exporters for example, in that it does not export all the +@code{HTML} and @LaTeX{} exporters for example, in that it does not export all the nodes of a document or strictly follow the order of the nodes in the document. @@ -10842,7 +11656,7 @@ Export as TaskJuggler file and then open the file with TaskJugglerUI. @subsection Tasks @vindex org-export-taskjuggler-project-tag -Create your tasks as you usually do with Org-mode. Assign efforts to each +Create your tasks as you usually do with Org mode. Assign efforts to each task using properties (it is easiest to do this in the column view). You should end up with something similar to the example by Peter Jones in @url{http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org}. @@ -10954,9 +11768,9 @@ file will be @file{myfile.mm}. @section XOXO export @cindex XOXO export -Org-mode contains an exporter that produces XOXO-style output. +Org mode contains an exporter that produces XOXO-style output. Currently, this exporter only handles the general outline structure and -does not interpret any additional Org-mode features. +does not interpret any additional Org mode features. @table @kbd @orgcmd{C-c C-e x,org-export-as-xoxo} @@ -10975,10 +11789,10 @@ Export only the visible part of the document. @vindex org-icalendar-use-scheduled @vindex org-icalendar-categories @vindex org-icalendar-alarm-time -Some people use Org-mode for keeping track of projects, but still prefer a +Some people use Org mode for keeping track of projects, but still prefer a standard calendar application for anniversaries and appointments. In this case it can be useful to show deadlines and other time-stamped items in Org -files in the calendar application. Org-mode can export calendar information +files in the calendar application. Org mode can export calendar information in the standard iCalendar format. If you also want to have TODO entries included in the export, configure the variable @code{org-icalendar-include-todo}. Plain timestamps are exported as VEVENT, @@ -11422,7 +12236,7 @@ Defaults to @code{nil}. @subsection Generating an index @cindex index, in a publishing project -Org-mode can generate an index across the files of a publishing project. +Org mode can generate an index across the files of a publishing project. @multitable @columnfractions 0.25 0.75 @item @code{:makeindex} @@ -11442,7 +12256,7 @@ a title, style information, etc. For those people already utilizing third party sync tools such as @command{rsync} or @command{unison}, it might be preferable not to use the built in -@i{remote} publishing facilities of Org-mode which rely heavily on +@i{remote} publishing facilities of Org mode which rely heavily on Tramp. Tramp, while very useful and powerful, tends not to be so efficient for multiple file transfer and has been known to cause problems under heavy usage. @@ -11581,7 +12395,7 @@ This may be necessary in particular if files include other files via @cindex Davison, Dan @cindex source code, working with -Source code can be included in Org-mode documents using a @samp{src} block, +Source code can be included in Org mode documents using a @samp{src} block, e.g.@: @example @@ -11592,26 +12406,26 @@ e.g.@: #+END_SRC @end example -Org-mode provides a number of features for working with live source code, +Org mode provides a number of features for working with live source code, including editing of code blocks in their native major-mode, evaluation of code blocks, converting code blocks into source files (known as @dfn{tangling} in literate programming), and exporting code blocks and their results in several formats. This functionality was contributed by Eric Schulte and Dan Davison, and was originally named Org-babel. -The following sections describe Org-mode's code block handling facilities. +The following sections describe Org mode's code block handling facilities. @menu * Structure of code blocks:: Code block syntax described * Editing source code:: Language major-mode editing * Exporting code blocks:: Export contents and/or results * Extracting source code:: Create pure source code files -* Evaluating code blocks:: Place results of evaluation in the Org-mode buffer +* Evaluating code blocks:: Place results of evaluation in the Org mode buffer * Library of Babel:: Use and contribute to a library of useful code blocks * Languages:: List of supported code block languages * Header arguments:: Configure code block functionality * Results of evaluation:: How evaluation results are handled -* Noweb reference syntax:: Literate programming in Org-mode +* Noweb reference syntax:: Literate programming in Org mode * Key bindings and useful functions:: Work quickly with code blocks * Batch execution:: Call functions from the command line @end menu @@ -11623,18 +12437,26 @@ The following sections describe Org-mode's code block handling facilities. @section Structure of code blocks @cindex code block, structure @cindex source code, block structure +@cindex #+NAME +@cindex #+BEGIN_SRC -The structure of code blocks is as follows: +Live code blocks can be specified with a @samp{src} block or +inline.@footnote{Note that @samp{src} blocks may be inserted using Org mode's +@ref{Easy Templates} system} The structure of a @samp{src} block is @example -#+srcname: <name> -#+begin_src <language> <switches> <header arguments> +#+NAME: <name> +#+BEGIN_SRC <language> <switches> <header arguments> <body> -#+end_src +#+END_SRC @end example -Switches and header arguments are optional. Code can also be embedded in text -inline using +The @code{#+NAME:} line is optional, and can be used to name the code +block. Live code blocks require that a language be specified on the +@code{#+BEGIN_SRC} line. Switches and header arguments are optional. +@cindex source code, inline + +Live code blocks can also be specified inline using @example src_<language>@{<body>@} @@ -11647,26 +12469,30 @@ src_<language>[<header arguments>]@{<body>@} @end example @table @code -@item <name> -This name is associated with the code block. This is similar to the -@samp{#+tblname} lines that can be used to name tables in Org-mode files. -Referencing the name of a code block makes it possible to evaluate the -block from other places in the file, other files, or from Org-mode table -formulas (see @ref{The spreadsheet}). Names are assumed to be unique by -evaluation functions and the behavior of multiple blocks of the same name is +@item <#+NAME: name> +This line associates a name with the code block. This is similar to the +@code{#+TBLNAME: NAME} lines that can be used to name tables in Org mode +files. Referencing the name of a code block makes it possible to evaluate +the block from other places in the file, from other files, or from Org mode +table formulas (see @ref{The spreadsheet}). Names are assumed to be unique +and the behavior of Org mode when two or more blocks share the same name is undefined. +@cindex #+NAME @item <language> -The language of the code in the block. +The language of the code in the block (see @ref{Languages}). +@cindex source code, language @item <switches> -Optional switches controlling exportation of the code block (see switches discussion in +Optional switches control code block export (see the discussion of switches in @ref{Literal examples}) +@cindex source code, switches @item <header arguments> Optional header arguments control many aspects of evaluation, export and -tangling of code blocks. See the @ref{Header arguments}. +tangling of code blocks (see @ref{Header arguments}). Header arguments can also be set on a per-buffer or per-subtree basis using properties. +@item source code, header arguments @item <body> -The source code. +Source code in the specified language. @end table @comment node-name, next, previous, up @@ -11715,12 +12541,12 @@ variable @code{org-src-fontify-natively}. @cindex code block, exporting @cindex source code, exporting -It is possible to export the @emph{contents} of code blocks, the -@emph{results} of code block evaluation, @emph{neither}, or @emph{both}. For -most languages, the default exports the contents of code blocks. However, for -some languages (e.g.@: @code{ditaa}) the default exports the results of code -block evaluation. For information on exporting code block bodies, see -@ref{Literal examples}. +It is possible to export the @emph{code} of code blocks, the @emph{results} +of code block evaluation, @emph{both} the code and the results of code block +evaluation, or @emph{none}. For most languages, the default exports code. +However, for some languages (e.g.@: @code{ditaa}) the default exports the +results of code block evaluation. For information on exporting code block +bodies, see @ref{Literal examples}. The @code{:exports} header argument can be used to specify export behavior: @@ -11732,7 +12558,7 @@ The default in most languages. The body of the code block is exported, as described in @ref{Literal examples}. @item :exports results The code block will be evaluated and the results will be placed in the -Org-mode buffer for export, either updating previous results of the code +Org mode buffer for export, either updating previous results of the code block located anywhere in the buffer or, if no previous results exist, placing the results immediately after the code block. The body of the code block will not be exported. @@ -11745,8 +12571,8 @@ Neither the code block nor its results will be exported. It is possible to inhibit the evaluation of code blocks during export. Setting the @code{org-export-babel-evaluate} variable to @code{nil} will ensure that no code blocks are evaluated as part of the export process. This -can be useful in situations where potentially untrusted Org-mode files are -exported in an automated fashion, for example when Org-mode is used as the +can be useful in situations where potentially untrusted Org mode files are +exported in an automated fashion, for example when Org mode is used as the markup language for a wiki. @comment node-name, next, previous, up @@ -11798,14 +12624,15 @@ of tangled code files. @cindex source code, evaluating Code blocks can be evaluated@footnote{Whenever code is evaluated there is a -potential for that code to do harm. Org-mode provides a number of safeguards -to ensure that it only evaluates code with explicit confirmation from the -user. For information on these safeguards (and on how to disable them) see -@ref{Code evaluation security}.} and the results placed in the Org-mode -buffer. By default, evaluation is only turned on for @code{emacs-lisp} code -blocks, however support exists for evaluating blocks in many languages. See -@ref{Languages} for a list of supported languages. See @ref{Structure of -code blocks} for information on the syntax used to define a code block. +potential for that code to do harm. Org mode provides safeguards to ensure +that code is only evaluated after explicit confirmation from the user. For +information on these safeguards (and on how to disable them) see @ref{Code +evaluation security}.} and the results of evaluation optionally placed in the +Org mode buffer. By default, the evaluation facility is only enabled for +Lisp code blocks specified as @code{emacs-lisp}. However, souce code blocks +in many languages can be evaluated within Org mode (see @ref{Languages} for a +list of supported languages and @ref{Structure of code blocks} for +information on the syntax used to define a code block). @kindex C-c C-c There are a number of ways to evaluate code blocks. The simplest is to press @@ -11813,64 +12640,52 @@ There are a number of ways to evaluate code blocks. The simplest is to press @code{org-babel-no-eval-on-ctrl-c-ctrl-c} variable can be used to remove code evaluation from the @kbd{C-c C-c} key binding.}. This will call the @code{org-babel-execute-src-block} function to evaluate the block and insert -its results into the Org-mode buffer. +its results into the Org mode buffer. +@cindex #+CALL It is also possible to evaluate named code blocks from anywhere in an -Org-mode buffer or an Org-mode table. @code{#+call} (or synonymously -@code{#+function} or @code{#+lob}) lines can be used to remotely execute code -blocks located in the current Org-mode buffer or in the ``Library of Babel'' -(see @ref{Library of Babel}). These lines use the following syntax to place -a call on a line by itself. +Org mode buffer or an Org mode table. Live code blocks located in the current +Org mode buffer or in the ``Library of Babel'' (see @ref{Library of Babel}) +can be executed. Named code blocks can be executed with a separate +@code{#+CALL:} line or inline within a block of text. + +The syntax of the @code{#+CALL:} line is @example -#+call: <name>(<arguments>) -#+call: <name>[<header args>](<arguments>) <header args> +#+CALL: <name>(<arguments>) +#+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments> @end example -The following syntax can be used to place these calls within a block of -prose. +The syntax for inline evaluation of named code blocks is @example -...prose... call_<name>(<arguments>) ...prose... -...prose... call_<name>[<header args>](<arguments>)[<header args>] ...prose... +... call_<name>(<arguments>) ... +... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ... @end example @table @code @item <name> -The name of the code block to be evaluated. +The name of the code block to be evaluated (see @ref{Structure of code blocks}). @item <arguments> Arguments specified in this section will be passed to the code block. These -arguments should relate to @code{:var} header arguments in the called code -block expressed using standard function call syntax. For example if the -original code block named @code{double} has the header argument @code{:var -n=2}, then the call line passing the number four to that block would be -written as @code{#+call: double(n=2)}. -@item <header args> -Header arguments can be placed either inside the call to the code block or at -the end of the line as shown below. - -@example -#+call: code_bloc_name[XXXX](arguments) YYYY -@end example - -Header arguments located in these two locations are treated differently. - -@table @code -@item XXXX -Those placed in the @code{XXXX} location are passed through and applied to -the code block being called. These header arguments affect how the code -block is evaluated, for example @code{[:results output]} will collect the -results from @code{STDOUT} of the called code block. -@item YYYY -Those placed in the @code{YYYY} location are applied to the call line and do -not affect the code block being called. These header arguments affect how -the results are incorporated into the Org-mode buffer when the call line is -evaluated, and how the call line is exported. For example @code{:results -org} at the end of the call line will insert the results of the call line -inside of an Org-mode block. -@end table - -For more examples of passing header arguments to @code{#+call:} lines see +arguments use standard function call syntax, rather than +header argument syntax. For example, a @code{#+CALL:} line that passes the +number four to a code block named @code{double}, which declares the header +argument @code{:var n=2}, would be written as @code{#+CALL: double(n=4)}. +@item <inside header arguments> +Inside header arguments are passed through and applied to the named code +block. These arguments use header argument syntax rather than standard +function call syntax. Inside header arguments affect how the code block is +evaluated. For example, @code{[:results output]} will collect the results of +everything printed to @code{STDOUT} during execution of the code block. +@item <end header arguments> +End header arguments are applied to the calling instance and do not affect +evaluation of the named code block. They affect how the results are +incorporated into the Org mode buffer and how the call line is exported. For +example, @code{:results html} will insert the results of the call line +evaluation in the Org buffer, wrapped in a @code{BEGIN_HTML:} block. + +For more examples of passing header arguments to @code{#+CALL:} lines see @ref{Header arguments in function calls}. @end table @@ -11880,18 +12695,22 @@ For more examples of passing header arguments to @code{#+call:} lines see @cindex source code, library @cindex code block, library -The ``Library of Babel'' is a library of code blocks -that can be called from any Org-mode file. The library is housed in an -Org-mode file located in the @samp{contrib} directory of Org-mode. -Org-mode users can deposit functions they believe to be generally -useful in the library. +The ``Library of Babel'' consists of code blocks that can be called from any +Org mode file. Code blocks defined in the ``Library of Babel'' can be called +remotely as if they were in the current Org mode buffer (see @ref{Evaluating +code blocks} for information on the syntax of remote code block evaluation). + + +The central repository of code blocks in the ``Library of Babel'' is housed +in an Org mode file located in the @samp{contrib} directory of Org mode. + +Users can add code blocks they believe to be generally useful to their +``Library of Babel.'' The code blocks can be stored in any Org mode file and +then loaded into the library with @code{org-babel-lob-ingest}. -Code blocks defined in the ``Library of Babel'' can be called remotely as if -they were in the current Org-mode buffer (see @ref{Evaluating code blocks} -for information on the syntax of remote code block evaluation). @kindex C-c C-v i -Code blocks located in any Org-mode file can be loaded into the ``Library of +Code blocks located in any Org mode file can be loaded into the ``Library of Babel'' with the @code{org-babel-lob-ingest} function, bound to @kbd{C-c C-v i}. @@ -11916,7 +12735,7 @@ Code blocks in the following languages are supported. @item Ledger @tab ledger @tab Lisp @tab lisp @item Lilypond @tab lilypond @tab MATLAB @tab matlab @item Mscgen @tab mscgen @tab Objective Caml @tab ocaml -@item Octave @tab octave @tab Org-mode @tab org +@item Octave @tab octave @tab Org mode @tab org @item Oz @tab oz @tab Perl @tab perl @item Plantuml @tab plantuml @tab Python @tab python @item R @tab R @tab Ruby @tab ruby @@ -11980,7 +12799,7 @@ specific (and having higher priority) than the last. * System-wide header arguments:: Set global default values * Language-specific header arguments:: Set default values by language * Buffer-wide header arguments:: Set default values for a specific buffer -* Header arguments in Org-mode properties:: Set default values for a buffer or heading +* Header arguments in Org mode properties:: Set default values for a buffer or heading * Code block specific header arguments:: The most common way to set values * Header arguments in function calls:: The most specific level @end menu @@ -12031,12 +12850,11 @@ Each language can define its own set of default header arguments. See the language-specific documentation available online at @uref{http://orgmode.org/worg/org-contrib/babel}. -@node Buffer-wide header arguments, Header arguments in Org-mode properties, Language-specific header arguments, Using header arguments +@node Buffer-wide header arguments, Header arguments in Org mode properties, Language-specific header arguments, Using header arguments @subsubheading Buffer-wide header arguments -Buffer-wide header arguments may be specified through the use of a special -line placed anywhere in an Org-mode file. The line consists of the -@code{#+BABEL:} keyword followed by a series of header arguments which may be -specified using the standard header argument syntax. +Buffer-wide header arguments may be specified as properties through the use +of @code{#+PROPERTY:} lines placed anywhere in an Org mode file (see +@ref{Property syntax}). For example the following would set @code{session} to @code{*R*}, and @code{results} to @code{silent} for every code block in the buffer, ensuring @@ -12044,24 +12862,27 @@ that all execution took place in the same session, and no results would be inserted into the buffer. @example -#+BABEL: :session *R* :results silent +#+PROPERTY: session *R* +#+PROPERTY: results silent @end example -@node Header arguments in Org-mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments -@subsubheading Header arguments in Org-mode properties +@node Header arguments in Org mode properties, Code block specific header arguments, Buffer-wide header arguments, Using header arguments +@subsubheading Header arguments in Org mode properties -Header arguments are also read from Org-mode properties (see @ref{Property +Header arguments are also read from Org mode properties (see @ref{Property syntax}), which can be set on a buffer-wide or per-heading basis. An example of setting a header argument for all code blocks in a buffer is @example -#+property: tangle yes +#+PROPERTY: tangle yes @end example +@vindex org-use-property-inheritance When properties are used to set default header arguments, they are looked up -with inheritance, so the value of the @code{:cache} header argument will default -to @code{yes} in all code blocks in the subtree rooted at the following -heading: +with inheritance, regardless of the value of +@code{org-use-property-inheritance}. In the following example the value of +the @code{:cache} header argument will default to @code{yes} in all code +blocks in the subtree rooted at the following heading: @example * outline header @@ -12075,45 +12896,47 @@ heading: Properties defined in this way override the properties set in @code{org-babel-default-header-args}. It is convenient to use the @code{org-set-property} function bound to @kbd{C-c C-x p} to set properties -in Org-mode documents. +in Org mode documents. -@node Code block specific header arguments, Header arguments in function calls, Header arguments in Org-mode properties, Using header arguments +@node Code block specific header arguments, Header arguments in function calls, Header arguments in Org mode properties, Using header arguments @subsubheading Code block specific header arguments The most common way to assign values to header arguments is at the code block level. This can be done by listing a sequence of header -arguments and their values as part of the @code{#+begin_src} line. +arguments and their values as part of the @code{#+BEGIN_SRC} line. Properties set in this way override both the values of @code{org-babel-default-header-args} and header arguments specified as properties. In the following example, the @code{:results} header argument is set to @code{silent}, meaning the results of execution will not be inserted in the buffer, and the @code{:exports} header argument is set to @code{code}, meaning only the body of the code block will be -preserved on export to HTML or LaTeX. +preserved on export to HTML or @LaTeX{}. @example -#+source: factorial -#+begin_src haskell :results silent :exports code :var n=0 +#+NAME: factorial +#+BEGIN_SRC haskell :results silent :exports code :var n=0 fac 0 = 1 fac n = n * fac (n-1) -#+end_src +#+END_SRC @end example -Similarly, it is possible to set header arguments for inline code blocks: +Similarly, it is possible to set header arguments for inline code blocks @example src_haskell[:exports both]@{fac 5@} @end example -Code block header arguments can span multiple lines using =#+header:= or -=#+headers:= lines preceding a code block or nested in between the name and -body of a named code block. +Code block header arguments can span multiple lines using @code{#+HEADER:} or +@code{#+HEADERS:} lines preceding a code block or nested between the +@code{#+NAME:} line and the @code{#+BEGIN_SRC} line of a named code block. +@cindex #+HEADER: +@cindex #+HEADERS: Multi-line header arguments on an un-named code block: @example - #+headers: :var data1=1 - #+begin_src emacs-lisp :var data2=2 + #+HEADERS: :var data1=1 + #+BEGIN_SRC emacs-lisp :var data2=2 (message "data1:%S, data2:%S" data1 data2) - #+end_src + #+END_SRC #+results: : data1:1, data2:2 @@ -12121,11 +12944,11 @@ Multi-line header arguments on an un-named code block: Multi-line header arguments on a named code block: @example - #+source: named-block - #+header: :var data=2 - #+begin_src emacs-lisp + #+NAME: named-block + #+HEADER: :var data=2 + #+BEGIN_SRC emacs-lisp (message "data:%S" data) - #+end_src + #+END_SRC #+results: named-block : data:2 @@ -12136,25 +12959,26 @@ Multi-line header arguments on a named code block: @subsubheading Header arguments in function calls At the most specific level, header arguments for ``Library of Babel'' or -function call lines can be set as shown in the two examples below. For more -information on the structure of @code{#+call:} lines see @ref{Evaluating code +@code{#+CALL:} lines can be set as shown in the two examples below. For more +information on the structure of @code{#+CALL:} lines see @ref{Evaluating code blocks}. The following will apply the @code{:exports results} header argument to the -evaluation of the @code{#+call:} line. +evaluation of the @code{#+CALL:} line. @example -#+call: factorial(n=5) :exports results +#+CALL: factorial(n=5) :exports results @end example The following will apply the @code{:session special} header argument to the evaluation of the @code{factorial} code block. @example -#+call: factorial[:session special](n=5) +#+CALL: factorial[:session special](n=5) @end example @node Specific header arguments, , Using header arguments, Header arguments @subsection Specific header arguments -The following header arguments are defined: +Header arguments consist of an initial colon followed by the name of the +argument in lowercase letters. The following header arguments are defined: @menu * var:: Pass arguments to code blocks @@ -12193,13 +13017,18 @@ Additional header arguments are defined on a language-specific basis, see The @code{:var} header argument is used to pass arguments to code blocks. The specifics of how arguments are included in a code block vary by language; these are addressed in the language-specific documentation. However, the -syntax used to specify arguments is the same across all languages. The -values passed to arguments can be literal values, values from org-mode tables -and literal example blocks, the results of other code blocks, or Emacs Lisp -code---see the ``Emacs Lisp evaluation of variables'' heading below. +syntax used to specify arguments is the same across all languages. In every +case, variables require a default value when they are declared. + +The values passed to arguments can either be literal values, references, or +Emacs Lisp code (see @ref{var, Emacs Lisp evaluation of variables}). References +include anything in the Org mode file that takes a @code{#+NAME:}, +@code{#+TBLNAME:}, or @code{#+RESULTS:} line. This includes tables, lists, +@code{#+BEGIN_EXAMPLE} blocks, other code blocks, and the results of other +code blocks. -These values can be indexed in a manner similar to arrays---see the -``indexable variable values'' heading below. +Argument values can be indexed in a manner similar to arrays (see @ref{var, +Indexable variable values}). The following syntax is used to pass arguments to code blocks using the @code{:var} header argument. @@ -12208,76 +13037,122 @@ The following syntax is used to pass arguments to code blocks using the :var name=assign @end example -where @code{assign} can take one of the following forms +The argument, @code{assign}, can either be a literal value, such as a string +@samp{"string"} or a number @samp{9}, or a reference to a table, a list, a +literal example, another code block (with or without arguments), or the +results of evaluating another code block. -@itemize @bullet -@item literal value -either a string @code{"string"} or a number @code{9}. -@item reference -a table name: +Here are examples of passing values by reference: + +@table @dfn +@item table +an Org mode table named with either a @code{#+NAME:} or @code{#+TBLNAME:} line @example -#+tblname: example-table +#+TBLNAME: example-table | 1 | | 2 | | 3 | | 4 | -#+source: table-length -#+begin_src emacs-lisp :var table=example-table +#+NAME: table-length +#+BEGIN_SRC emacs-lisp :var table=example-table (length table) -#+end_src +#+END_SRC #+results: table-length : 4 @end example -a code block name, as assigned by @code{#+srcname:}, followed by -parentheses: +@item list +a simple list named with a @code{#+NAME:} line (note that nesting is not +carried through to the source code block) @example -#+begin_src emacs-lisp :var length=table-length() +#+NAME: example-list + - simple + - not + - nested + - list + +#+BEGIN_SRC emacs-lisp :var x=example-list + (print x) +#+END_SRC + +#+results: +| simple | list | +@end example + +@item code block without arguments +a code block name (from the example above), as assigned by @code{#+NAME:}, +optionally followed by parentheses + +@example +#+BEGIN_SRC emacs-lisp :var length=table-length() (* 2 length) -#+end_src +#+END_SRC #+results: : 8 @end example -In addition, an argument can be passed to the code block referenced -by @code{:var}. The argument is passed within the parentheses following the -code block name: +@item code block with arguments +a code block name, as assigned by @code{#+NAME:}, followed by parentheses and +optional arguments passed within the parentheses following the +code block name using standard function call syntax @example -#+source: double -#+begin_src emacs-lisp :var input=8 +#+NAME: double +#+BEGIN_SRC emacs-lisp :var input=8 (* 2 input) -#+end_src +#+END_SRC #+results: double : 16 -#+source: squared -#+begin_src emacs-lisp :var input=double(input=1) +#+NAME: squared +#+BEGIN_SRC emacs-lisp :var input=double(input=1) (* input input) -#+end_src +#+END_SRC #+results: squared : 4 @end example -@end itemize + +@item literal example +a literal example block named with a @code{#+NAME:} line + +@example +#+NAME: literal-example +#+BEGIN_EXAMPLE +A literal example +on two lines +#+END_EXAMPLE + +#+NAME: read-literal-example +#+BEGIN_SRC emacs-lisp :var x=literal-example + (concatenate 'string x " for you.") +#+END_SRC + +#+results: read-literal-example +: A literal example +: on two lines for you. + +@end example + +@end table @subsubheading Alternate argument syntax It is also possible to specify arguments in a potentially more natural way -using the @code{#+source:} line of a code block. As in the following -example arguments can be packed inside of parenthesis, separated by commas, +using the @code{#+NAME:} line of a code block. As in the following +example, arguments can be packed inside of parentheses, separated by commas, following the source name. @example -#+source: double(input=0, x=2) -#+begin_src emacs-lisp +#+NAME: double(input=0, x=2) +#+BEGIN_SRC emacs-lisp (* 2 (+ input x)) -#+end_src +#+END_SRC @end example @subsubheading Indexable variable values @@ -12291,15 +13166,15 @@ following example assigns the last cell of the first row the table @code{example-table} to the variable @code{data}: @example -#+results: example-table +#+NAME: example-table | 1 | a | | 2 | b | | 3 | c | | 4 | d | -#+begin_src emacs-lisp :var data=example-table[0,-1] +#+BEGIN_SRC emacs-lisp :var data=example-table[0,-1] data -#+end_src +#+END_SRC #+results: : a @@ -12311,16 +13186,16 @@ example the following assigns the middle three rows of @code{example-table} to @code{data}. @example -#+results: example-table +#+NAME: example-table | 1 | a | | 2 | b | | 3 | c | | 4 | d | | 5 | 3 | -#+begin_src emacs-lisp :var data=example-table[1:3] +#+BEGIN_SRC emacs-lisp :var data=example-table[1:3] data -#+end_src +#+END_SRC #+results: | 2 | b | @@ -12334,15 +13209,15 @@ interpreted to mean the entire range and as such are equivalent to column is referenced. @example -#+results: example-table +#+NAME: example-table | 1 | a | | 2 | b | | 3 | c | | 4 | d | -#+begin_src emacs-lisp :var data=example-table[,0] +#+BEGIN_SRC emacs-lisp :var data=example-table[,0] data -#+end_src +#+END_SRC #+results: | 1 | 2 | 3 | 4 | @@ -12353,16 +13228,16 @@ Any number of dimensions can be indexed. Dimensions are separated from one another by commas, as shown in the following example. @example -#+source: 3D -#+begin_src emacs-lisp +#+NAME: 3D +#+BEGIN_SRC emacs-lisp '(((1 2 3) (4 5 6) (7 8 9)) ((10 11 12) (13 14 15) (16 17 18)) ((19 20 21) (22 23 24) (25 26 27))) -#+end_src +#+END_SRC -#+begin_src emacs-lisp :var data=3D[1,,1] +#+BEGIN_SRC emacs-lisp :var data=3D[1,,1] data -#+end_src +#+END_SRC #+results: | 11 | 14 | 17 | @@ -12371,31 +13246,31 @@ another by commas, as shown in the following example. @subsubheading Emacs Lisp evaluation of variables Emacs lisp code can be used to initialize variable values. When a variable -value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be evaluated as -Emacs Lisp and the result of the evaluation will be assigned as the variable -value. The following example demonstrates use of this evaluation to reliably -pass the file-name of the org-mode buffer to a code block---note that -evaluation of header arguments is guaranteed to take place in the original -org-mode file, while there is no such guarantee for evaluation of the code -block body. +value starts with @code{(}, @code{[}, @code{'} or @code{`} it will be +evaluated as Emacs Lisp and the result of the evaluation will be assigned as +the variable value. The following example demonstrates use of this +evaluation to reliably pass the file-name of the Org mode buffer to a code +block---note that evaluation of header arguments is guaranteed to take place +in the original Org mode file, while there is no such guarantee for +evaluation of the code block body. @example -#+begin_src sh :var filename=(buffer-file-name) :exports both +#+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both wc -w $filename -#+end_src +#+END_SRC @end example Note that values read from tables and lists will not be evaluated as Emacs Lisp, as shown in the following example. @example -#+results: table +#+NAME: table | (a b c) | -#+headers: :var data=table[0,0] -#+begin_src perl +#+HEADERS: :var data=table[0,0] +#+BEGIN_SRC perl $data -#+end_src +#+END_SRC #+results: : (a b c) @@ -12414,7 +13289,7 @@ from the code block @item @b{type} header arguments specify what type of result the code block will return---which has implications for how they will be inserted into the -Org-mode buffer +Org mode buffer @item @b{handling} header arguments specify how the results of evaluating the code block should be handled. @@ -12445,31 +13320,31 @@ table or scalar depending on their value. @itemize @bullet @item @code{table}, @code{vector} -The results should be interpreted as an Org-mode table. If a single value is +The results should be interpreted as an Org mode table. If a single value is returned, it will be converted into a table with one row and one column. E.g., @code{:results value table}. @item @code{list} -The results should be interpreted as an Org-mode list. If a single scalar +The results should be interpreted as an Org mode list. If a single scalar value is returned it will be converted into a list with only one element. @item @code{scalar}, @code{verbatim} The results should be interpreted literally---they will not be -converted into a table. The results will be inserted into the Org-mode +converted into a table. The results will be inserted into the Org mode buffer as quoted text. E.g., @code{:results value verbatim}. @item @code{file} The results will be interpreted as the path to a file, and will be inserted -into the Org-mode buffer as a file link. E.g., @code{:results value file}. +into the Org mode buffer as a file link. E.g., @code{:results value file}. @item @code{raw}, @code{org} -The results are interpreted as raw Org-mode code and are inserted directly +The results are interpreted as raw Org mode code and are inserted directly into the buffer. If the results look like a table they will be aligned as -such by Org-mode. E.g., @code{:results value raw}. +such by Org mode. E.g., @code{:results value raw}. @item @code{html} Results are assumed to be HTML and will be enclosed in a @code{begin_html} block. E.g., @code{:results value html}. @item @code{latex} -Results assumed to be LaTeX and are enclosed in a @code{begin_latex} block. +Results assumed to be @LaTeX{} and are enclosed in a @code{begin_latex} block. E.g., @code{:results value latex}. @item @code{code} -Result are assumed to be parseable code and are enclosed in a code block. +Result are assumed to be parsable code and are enclosed in a code block. E.g., @code{:results value code}. @item @code{pp} The result is converted to pretty-printed code and is enclosed in a code @@ -12488,10 +13363,10 @@ results once they are collected. @itemize @bullet @item @code{silent} The results will be echoed in the minibuffer but will not be inserted into -the Org-mode buffer. E.g., @code{:results output silent}. +the Org mode buffer. E.g., @code{:results output silent}. @item @code{replace} The default value. Any existing results will be removed, and the new results -will be inserted into the Org-mode buffer in their place. E.g., +will be inserted into the Org mode buffer in their place. E.g., @code{:results output replace}. @item @code{append} If there are pre-existing results of the code block then the new results will @@ -12507,9 +13382,9 @@ inserted as with @code{replace}. @subsubsection @code{:file} The header argument @code{:file} is used to specify an external file in which -to save code block results. After code block evaluation an Org-mode style +to save code block results. After code block evaluation an Org mode style @code{[[file:]]} link (see @ref{Link format}) to the file will be inserted -into the Org-mode buffer. Some languages including R, gnuplot, dot, and +into the Org mode buffer. Some languages including R, gnuplot, dot, and ditaa provide special handling of the @code{:file} header argument automatically wrapping the code block body in the boilerplate code required to save output to the specified file. This is often useful for saving @@ -12538,9 +13413,9 @@ In other words, if you want your plot to go into a folder called @file{Work} in your home directory, you could use @example -#+begin_src R :file myplot.png :dir ~/Work +#+BEGIN_SRC R :file myplot.png :dir ~/Work matplot(matrix(rnorm(100), 10), type="l") -#+end_src +#+END_SRC @end example @subsubheading Remote execution @@ -12548,14 +13423,14 @@ A directory on a remote machine can be specified using tramp file syntax, in which case the code will be evaluated on the remote machine. An example is @example -#+begin_src R :file plot.png :dir /dand@@yakuba.princeton.edu: +#+BEGIN_SRC R :file plot.png :dir /dand@@yakuba.princeton.edu: plot(1:10, main=system("hostname", intern=TRUE)) -#+end_src +#+END_SRC @end example -Text results will be returned to the local Org-mode buffer as usual, and file +Text results will be returned to the local Org mode buffer as usual, and file output will be created on the remote machine with relative paths interpreted -relative to the remote directory. An Org-mode link to the remote file will be +relative to the remote directory. An Org mode link to the remote file will be created. So, in the above example a plot will be created on the remote machine, @@ -12581,7 +13456,7 @@ currently made to alter the directory associated with an existing session. @code{:dir} should typically not be used to create files during export with @code{:exports results} or @code{:exports both}. The reason is that, in order to retain portability of exported material between machines, during export -links inserted into the buffer will *not* be expanded against @code{default +links inserted into the buffer will @emph{not} be expanded against @code{default directory}. Therefore, if @code{default-directory} is altered using @code{:dir}, it is probable that the file will be created in a location to which the link does not point. @@ -12591,7 +13466,7 @@ which the link does not point. @subsubsection @code{:exports} The @code{:exports} header argument specifies what should be included in HTML -or LaTeX exports of the Org-mode file. +or @LaTeX{} exports of the Org mode file. @itemize @bullet @item @code{code} @@ -12616,14 +13491,14 @@ block should be included in tangled extraction of source code files. @itemize @bullet @item @code{tangle} The code block is exported to a source code file named after the full path -(including the directory) and file name (w/o extension) of the Org-mode file. +(including the directory) and file name (w/o extension) of the Org mode file. E.g., @code{:tangle yes}. @item @code{no} The default. The code block is not exported to a source code file. E.g., @code{:tangle no}. @item other Any other string passed to the @code{:tangle} header argument is interpreted -as a path (directory and file name relative to the directory of the Org-mode +as a path (directory and file name relative to the directory of the Org mode file) to which the block will be exported. E.g., @code{:tangle path}. @end itemize @@ -12650,7 +13525,7 @@ original Org file from which the code was tangled. @item @code{yes} A synonym for ``link'' to maintain backwards compatibility. @item @code{org} -Include text from the org-mode file as a comment. +Include text from the Org mode file as a comment. The text is picked from the leading context of the tangled code and is limited by the nearest headline or source block as the case may be. @@ -12751,37 +13626,39 @@ concatenated together to form the replacement text. By setting this header argument at the sub-tree or file level, simple code block concatenation may be achieved. For example, when tangling the -following Org-mode file, the bodies of code blocks will be concatenated into -the resulting pure code file. +following Org mode file, the bodies of code blocks will be concatenated into +the resulting pure code file@footnote{(The example needs property inheritance +to be turned on for the @code{noweb-ref} property, see @ref{Property +inheritance}).}. @example - #+begin_src sh :tangle yes :noweb yes :shebang #!/bin/sh + #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh <<fullest-disk>> - #+end_src + #+END_SRC * the mount point of the fullest disk :PROPERTIES: :noweb-ref: fullest-disk :END: ** query all mounted disks - #+begin_src sh + #+BEGIN_SRC sh df \ - #+end_src + #+END_SRC ** strip the header row - #+begin_src sh + #+BEGIN_SRC sh |sed '1d' \ - #+end_src + #+END_SRC ** sort by the percent full - #+begin_src sh + #+BEGIN_SRC sh |awk '@{print $5 " " $6@}'|sort -n |tail -1 \ - #+end_src + #+END_SRC ** extract the mount point - #+begin_src sh + #+BEGIN_SRC sh |awk '@{print $2@}' - #+end_src + #+END_SRC @end example @node cache, sep, noweb-ref, Specific header arguments @@ -12811,18 +13688,18 @@ invalidated and the code block is re-run. In the following example, changed since it was last run. @example - #+srcname: random - #+begin_src R :cache yes + #+NAME: random + #+BEGIN_SRC R :cache yes runif(1) - #+end_src + #+END_SRC #+results[a2a72cd647ad44515fab62e144796432793d68e1]: random 0.4659510825295 - #+srcname: caller - #+begin_src emacs-lisp :var x=random :cache yes + #+NAME: caller + #+BEGIN_SRC emacs-lisp :var x=random :cache yes x - #+end_src + #+END_SRC #+results[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller 0.254227238707244 @@ -12832,7 +13709,7 @@ changed since it was last run. @subsubsection @code{:sep} The @code{:sep} header argument can be used to control the delimiter used -when writing tabular results out to files external to Org-mode. This is used +when writing tabular results out to files external to Org mode. This is used either when opening tabular results of a code block by calling the @code{org-open-at-point} function bound to @kbd{C-c C-o} on the code block, or when writing code block results to an external file (see @ref{file}) @@ -12856,17 +13733,17 @@ variable and raises an error. Setting @code{:hlines no} or relying on the default value yields the following results. @example -#+tblname: many-cols +#+TBLNAME: many-cols | a | b | c | |---+---+---| | d | e | f | |---+---+---| | g | h | i | -#+source: echo-table -#+begin_src python :var tab=many-cols +#+NAME: echo-table +#+BEGIN_SRC python :var tab=many-cols return tab -#+end_src +#+END_SRC #+results: echo-table | a | b | c | @@ -12878,17 +13755,17 @@ default value yields the following results. Leaves hlines in the table. Setting @code{:hlines yes} has this effect. @example -#+tblname: many-cols +#+TBLNAME: many-cols | a | b | c | |---+---+---| | d | e | f | |---+---+---| | g | h | i | -#+source: echo-table -#+begin_src python :var tab=many-cols :hlines yes +#+NAME: echo-table +#+BEGIN_SRC python :var tab=many-cols :hlines yes return tab -#+end_src +#+END_SRC #+results: echo-table | a | b | c | @@ -12904,6 +13781,10 @@ Leaves hlines in the table. Setting @code{:hlines yes} has this effect. The @code{:colnames} header argument accepts the values @code{yes}, @code{no}, or @code{nil} for unassigned. The default value is @code{nil}. +Note that the behavior of the @code{:colnames} header argument may differ +across languages. For example Emacs Lisp code blocks ignore the +@code{:colnames} header argument entirely given the ease with which tables +with column names may be handled directly in Emacs Lisp. @itemize @bullet @item @code{nil} @@ -12913,16 +13794,16 @@ names will be removed from the table before processing, then reapplied to the results. @example -#+tblname: less-cols +#+TBLNAME: less-cols | a | |---| | b | | c | -#+srcname: echo-table-again -#+begin_src python :var tab=less-cols +#+NAME: echo-table-again +#+BEGIN_SRC python :var tab=less-cols return [[val + '*' for val in row] for row in tab] -#+end_src +#+END_SRC #+results: echo-table-again | a | @@ -12958,14 +13839,14 @@ The first column of the table is removed from the table before processing, and is then reapplied to the results. @example -#+tblname: with-rownames +#+TBLNAME: with-rownames | one | 1 | 2 | 3 | 4 | 5 | | two | 6 | 7 | 8 | 9 | 10 | -#+srcname: echo-table-once-again -#+begin_src python :var tab=with-rownames :rownames yes +#+NAME: echo-table-once-again +#+BEGIN_SRC python :var tab=with-rownames :rownames yes return [[val + 10 for val in row] for row in tab] -#+end_src +#+END_SRC #+results: echo-table-once-again | one | 11 | 12 | 13 | 14 | 15 | @@ -12988,12 +13869,23 @@ permissions of the tangled file are set to make it executable. @node eval, , shebang, Specific header arguments @subsubsection @code{:eval} The @code{:eval} header argument can be used to limit the evaluation of -specific code blocks. @code{:eval} accepts two arguments ``never'' and -``query''. @code{:eval never} will ensure that a code block is never -evaluated, this can be useful for protecting against the evaluation of -dangerous code blocks. @code{:eval query} will require a query for every -execution of a code block regardless of the value of the -@code{org-confirm-babel-evaluate} variable. +specific code blocks. The @code{:eval} header argument can be useful for +protecting against the evaluation of dangerous code blocks or to ensure that +evaluation will require a query regardless of the value of the +@code{org-confirm-babel-evaluate} variable. The possible values of +@code{:eval} and their effects are shown below. + +@table @code +@item never or no +The code block will not be evaluated under any circumstances. +@item query +Evaluation of the code block will require a query. +@item never-export or no-export +The code block will not be evaluated during export but may still be called +interactively. +@item query-export +Evaluation of the code block during export will require a query. +@end table If this header argument is not set then evaluation is determined by the value of the @code{org-confirm-babel-evaluate} variable see @ref{Code evaluation @@ -13016,7 +13908,7 @@ of the possible results header arguments see @ref{results}. @end multitable Note: With @code{:results value}, the result in both @code{:session} and -non-session is returned to Org-mode as a table (a one- or two-dimensional +non-session is returned to Org mode as a table (a one- or two-dimensional vector of strings or numbers) when appropriate. @subsection Non-session @@ -13062,26 +13954,26 @@ were passed to a non-interactive interpreter running as an external process. For example, compare the following two blocks: @example -#+begin_src python :results output +#+BEGIN_SRC python :results output print "hello" 2 print "bye" -#+end_src +#+END_SRC -#+resname: +#+results: : hello : bye @end example In non-session mode, the `2' is not printed and does not appear. @example -#+begin_src python :results output :session +#+BEGIN_SRC python :results output :session print "hello" 2 print "bye" -#+end_src +#+END_SRC -#+resname: +#+results: : hello : 2 : bye @@ -13109,7 +14001,8 @@ When a code block is tangled or evaluated, whether or not ``noweb'' references are expanded depends upon the value of the @code{:noweb} header argument. If @code{:noweb yes}, then a Noweb reference is expanded before evaluation. If @code{:noweb no}, the default, then the reference is not -expanded before evaluation. +expanded before evaluation. See the @ref{noweb-ref} header argument for +a more flexible way to resolve noweb references. Note: the default value, @code{:noweb no}, was chosen to ensure that correct code is not broken in a language, such as Ruby, where @@ -13117,11 +14010,17 @@ correct code is not broken in a language, such as Ruby, where syntactically valid in languages that you use, then please consider setting the default value. +Note: if noweb tangling is slow in large Org-mode files consider setting the +@code{*org-babel-use-quick-and-dirty-noweb-expansion*} variable to true. +This will result in faster noweb reference resolution at the expense of not +correctly resolving inherited values of the @code{:noweb-ref} header +argument. + @node Key bindings and useful functions, Batch execution, Noweb reference syntax, Working With Source Code @section Key bindings and useful functions @cindex code block, key bindings -Many common Org-mode key sequences are re-bound depending on +Many common Org mode key sequences are re-bound depending on the context. Within a code block, the following key bindings @@ -13138,7 +14037,7 @@ are active: @item @kbd{M-@key{down}} @tab @code{org-babel-pop-to-session} @end multitable -In an Org-mode buffer, the following key bindings are active: +In an Org mode buffer, the following key bindings are active: @multitable @columnfractions 0.45 0.55 @kindex C-c C-v a @@ -13255,7 +14154,7 @@ emacs -Q --batch -l $ORGINSTALL \ @cindex tag completion @cindex link abbreviations, completion of -Emacs would not be Emacs without completion, and Org-mode uses it whenever it +Emacs would not be Emacs without completion, and Org mode uses it whenever it makes sense. If you prefer an @i{iswitchb}- or @i{ido}-like interface for some of the completion prompts, you can specify your preference by setting at most one of the variables @code{org-completion-use-iswitchb} @@ -13290,7 +14189,7 @@ buffer. After @samp{[}, complete link abbreviations (@pxref{Link abbreviations}). @item After @samp{#+}, complete the special keywords like @samp{TYP_TODO} or -@samp{OPTIONS} which set file-specific options for Org-mode. When the +@samp{OPTIONS} which set file-specific options for Org mode. When the option keyword is already complete, pressing @kbd{M-@key{TAB}} again will insert example settings for this keyword. @item @@ -13306,7 +14205,7 @@ Elsewhere, complete dictionary words using Ispell. @cindex template insertion @cindex insertion, of templates -Org-mode supports insertion of empty structural elements (like +Org mode supports insertion of empty structural elements (like @code{#+BEGIN_SRC} and @code{#+END_SRC} pairs) with just a few key strokes. This is achieved through a native template expansion mechanism. Note that Emacs has several other template mechanisms which could be used in @@ -13438,7 +14337,7 @@ lines into the buffer (@pxref{In-buffer settings}). @cindex in-buffer settings @cindex special keywords -Org-mode uses special lines in the buffer to define settings on a +Org mode uses special lines in the buffer to define settings on a per-file basis. These lines start with a @samp{#+} followed by a keyword, a colon, and then individual words defining a setting. Several setting words can be in the same line, but you can also have multiple @@ -13497,14 +14396,14 @@ buffer, most useful for specifying the allowed values of a property. @item #+SETUPFILE: file This line defines a file that holds more in-buffer setup. Normally this is entirely ignored. Only when the buffer is parsed for option-setting lines -(i.e.@: when starting Org-mode for a file, when pressing @kbd{C-c C-c} in a +(i.e.@: when starting Org mode for a file, when pressing @kbd{C-c C-c} in a settings line, or when exporting), then the contents of this file are parsed as if they had been included in the buffer. In particular, the file can be -any other Org-mode file with internal setup. You can visit the file the +any other Org mode file with internal setup. You can visit the file the cursor is in the line with @kbd{C-c '}. @item #+STARTUP: @cindex #+STARTUP: -This line sets options to be used at startup of Org-mode, when an +This line sets options to be used at startup of Org mode, when an Org file is being visited. The first set of options deals with the initial visibility of the outline @@ -13527,7 +14426,7 @@ showeverything @r{show even drawer contents} @cindex @code{indent}, STARTUP keyword @cindex @code{noindent}, STARTUP keyword Dynamic virtual indentation is controlled by the variable -@code{org-startup-indented}@footnote{Emacs 23 and Org-mode 6.29 are required} +@code{org-startup-indented}@footnote{Emacs 23 and Org mode 6.29 are required} @example indent @r{start with @code{org-indent-mode} turned on} noindent @r{start with @code{org-indent-mode} turned off} @@ -13748,6 +14647,8 @@ ordered list. @item If the cursor is on the @code{#+BEGIN} line of a dynamic block, the block is updated. +@item +If the cursor is at a timestamp, fix the day name in the timestamp. @end itemize @node Clean view, TTY keys, The very busy C-c C-c key, Miscellaneous @@ -13956,11 +14857,11 @@ setup. See the installation instructions in the file @item @file{cdlatex.el} by Carsten Dominik @cindex @file{cdlatex.el} @cindex Dominik, Carsten -Org-mode can make use of the CDLa@TeX{} package to efficiently enter +Org mode can make use of the CD@LaTeX{} package to efficiently enter @LaTeX{} fragments into Org files. See @ref{CDLaTeX mode}. @item @file{imenu.el} by Ake Stenhoff and Lars Lindberg @cindex @file{imenu.el} -Imenu allows menu access to an index of items in a file. Org-mode +Imenu allows menu access to an index of items in a file. Org mode supports Imenu---all you need to do to get the index is the following: @lisp (add-hook 'org-mode-hook @@ -13977,7 +14878,7 @@ Org used to use this package for capture, but no longer does. @cindex @file{speedbar.el} @cindex Ludlam, Eric M. Speedbar is a package that creates a special frame displaying files and -index items in files. Org-mode supports Speedbar and allows you to +index items in files. Org mode supports Speedbar and allows you to drill into Org files directly from the Speedbar. It also allows you to restrict the scope of agenda commands to a file or a subtree by using the command @kbd{<} in the Speedbar frame. @@ -13991,8 +14892,8 @@ the command @kbd{<} in the Speedbar frame. Complex ASCII tables with automatic line wrapping, column- and row-spanning, and alignment can be created using the Emacs table package by Takaaki Ota (@uref{http://sourceforge.net/projects/table}, and also part of Emacs 22). -Org-mode will recognize these tables and export them properly. Because of -interference with other Org-mode functionality, you unfortunately cannot edit +Org mode will recognize these tables and export them properly. Because of +interference with other Org mode functionality, you unfortunately cannot edit these tables directly in the buffer. Instead, you need to use the command @kbd{C-c '} to edit them, similar to source code snippets. @@ -14002,7 +14903,7 @@ Edit a @file{table.el} table. Works when the cursor is in a table.el table. @c @orgcmd{C-c ~,org-table-create-with-table.el} Insert a @file{table.el} table. If there is already a table at point, this -command converts it between the @file{table.el} format and the Org-mode +command converts it between the @file{table.el} format and the Org mode format. See the documentation string of the command @code{org-convert-table} for the restrictions under which this is possible. @@ -14011,13 +14912,13 @@ possible. @item @file{footnote.el} by Steven L. Baur @cindex @file{footnote.el} @cindex Baur, Steven L. -Org-mode recognizes numerical footnotes as provided by this package. -However, Org-mode also has its own footnote support (@pxref{Footnotes}), +Org mode recognizes numerical footnotes as provided by this package. +However, Org mode also has its own footnote support (@pxref{Footnotes}), which makes using @file{footnote.el} unnecessary. @end table @node Conflicts, , Cooperation, Interaction -@subsection Packages that lead to conflicts with Org-mode +@subsection Packages that lead to conflicts with Org mode @table @asis @@ -14029,7 +14930,7 @@ This conflicts with the use of @kbd{S-@key{cursor}} commands in Org to change timestamps, TODO keywords, priorities, and item bullet types if the cursor is at such a location. By default, @kbd{S-@key{cursor}} commands outside special contexts don't do anything, but you can customize the variable -@code{org-support-shift-select}. Org-mode then tries to accommodate shift +@code{org-support-shift-select}. Org mode then tries to accommodate shift selection by (i) using it outside of the special contexts where special commands apply, and by (ii) extending an existing active region even if the cursor moves across a special context. @@ -14044,7 +14945,7 @@ region. In fact, Emacs 23 has this built-in in the form of @code{shift-selection-mode}, see previous paragraph. If you are using Emacs 23, you probably don't want to use another package for this purpose. However, if you prefer to leave these keys to a different package while working in -Org-mode, configure the variable @code{org-replace-disputed-keys}. When set, +Org mode, configure the variable @code{org-replace-disputed-keys}. When set, Org will move the following key bindings in Org files, and in the agenda buffer (but not during date selection). @@ -14069,7 +14970,7 @@ fixed this problem: (add-hook 'org-mode-hook (lambda () (org-set-local 'yas/trigger-key [tab]) - (define-key yas/keymap [tab] 'yas/next-field-group))) + (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand))) @end lisp The latest version of yasnippet doesn't play well with Org mode. If the @@ -14096,7 +14997,7 @@ Then, tell Org mode what to do with the new function: @cindex @file{windmove.el} This package also uses the @kbd{S-<cursor>} keys, so everything written in the paragraph above about CUA mode also applies here. If you want make -the windmove function active in locations where Org-mode does not have +the windmove function active in locations where Org mode does not have special functionality on @kbd{S-@key{cursor}}, add this to your configuration: @@ -14112,7 +15013,7 @@ configuration: @cindex @file{viper.el} @kindex C-c / Viper uses @kbd{C-c /} and therefore makes this key not access the -corresponding Org-mode command @code{org-sparse-tree}. You need to find +corresponding Org mode command @code{org-sparse-tree}. You need to find another key for this command, or override the key in @code{viper-vi-global-user-map} with @@ -14197,7 +15098,7 @@ maintained by the Worg project and can be found at A large number of add-on packages have been written by various authors. These packages are not part of Emacs, but they are distributed as contributed -packages with the separate release available at the Org-mode home page at +packages with the separate release available at the Org mode home page at @uref{http://orgmode.org}. The list of contributed packages, along with documentation about each package, is maintained by the Worg project at @uref{http://orgmode.org/worg/org-contrib/}. @@ -14321,7 +15222,7 @@ Add-ons can tap into this functionality by providing a function that detects special context for that add-on and executes functionality appropriate for the context. Here is an example from Dan Davison's @file{org-R.el} which allows you to evaluate commands based on the @file{R} programming language -@footnote{@file{org-R.el} has been replaced by the org-mode functionality +@footnote{@file{org-R.el} has been replaced by the Org mode functionality described in @ref{Working With Source Code} and is now obsolete.}. For this package, special contexts are lines that start with @code{#+R:} or @code{#+RR:}. @@ -14374,12 +15275,12 @@ can use Org's facilities to edit and structure lists by turning @menu * Radio tables:: Sending and receiving radio tables -* A LaTeX example:: Step by step, almost a tutorial +* A @LaTeX{} example:: Step by step, almost a tutorial * Translator functions:: Copy and modify * Radio lists:: Doing the same for lists @end menu -@node Radio tables, A LaTeX example, Tables in arbitrary syntax, Tables in arbitrary syntax +@node Radio tables, A @LaTeX{} example, Tables in arbitrary syntax, Tables in arbitrary syntax @subsection Radio tables @cindex radio tables @@ -14447,7 +15348,7 @@ makes this comment-toggling very easy, in particular if you bind it to a key. @end itemize -@node A LaTeX example, Translator functions, Radio tables, Tables in arbitrary syntax +@node A @LaTeX{} example, Translator functions, Radio tables, Tables in arbitrary syntax @subsection A @LaTeX{} example of radio tables @cindex @LaTeX{}, and Orgtbl mode @@ -14557,7 +15458,7 @@ applied. Similar to @code{fmt}, functions of two arguments can be supplied instead of strings. @end table -@node Translator functions, Radio lists, A LaTeX example, Tables in arbitrary syntax +@node Translator functions, Radio lists, A @LaTeX{} example, Tables in arbitrary syntax @subsection Translator functions @cindex HTML, and Orgtbl mode @cindex translator function @@ -14877,7 +15778,7 @@ You may also modify parameters on the fly like this: @example emacs -batch -l ~/.emacs \ -eval '(org-batch-agenda "a" \ - org-agenda-span month \ + org-agenda-span (quote month) \ org-agenda-include-diary nil \ org-agenda-files (quote ("~/org/project.org")))' \ | lpr @@ -15139,7 +16040,7 @@ The following example counts the number of entries with TODO keyword @uref{http://mobileorg.ncogni.to/, MobileOrg} is an application for the @i{iPhone/iPod Touch} series of devices, developed by Richard Moreland. -@i{MobileOrg} offers offline viewing and capture support for an Org-mode +@i{MobileOrg} offers offline viewing and capture support for an Org mode system rooted on a ``real'' computer. It does also allow you to record changes to existing entries. Android users should check out @uref{http://wiki.github.com/matburt/mobileorg-android/, MobileOrg Android} @@ -15168,7 +16069,7 @@ in-buffer settings, but it will understand the logistics of TODO state MobileOrg needs to interact with Emacs through a directory on a server. If you are using a public server, you should consider to encrypt the files that are -uploaded to the server. This can be done with Org-mode 7.02 and with +uploaded to the server. This can be done with Org mode 7.02 and with @i{MobileOrg 1.5} (iPhone version), and you need an @file{openssl} installation on your system. To turn on encryption, set a password in @i{MobileOrg} and, on the Emacs side, configure the variable @@ -15191,7 +16092,7 @@ Emacs about it: (setq org-mobile-directory "~/Dropbox/MobileOrg") @end lisp -Org-mode has commands to put files for @i{MobileOrg} into that directory, +Org mode has commands to put files for @i{MobileOrg} into that directory, and to read captured notes from there. @node Pushing to MobileOrg, Pulling from MobileOrg, Setting up the staging area, MobileOrg @@ -15204,7 +16105,7 @@ can be included by customizing @code{org-mobile-files}. File names will be staged with paths relative to @code{org-directory}, so all files should be inside this directory. The push operation also creates a special Org file @file{agendas.org} with all custom agenda view defined by the -user@footnote{While creating the agendas, Org-mode will force ID properties +user@footnote{While creating the agendas, Org mode will force ID properties on all referenced entries, so that these entries can be uniquely identified if @i{MobileOrg} flags them for further action. If you do not want to get these properties in so many entries, you can set the variable @@ -15305,7 +16206,7 @@ Before I get to this list, a few special mentions are in order: @table @i @item Bastien Guerry Bastien has written a large number of extensions to Org (most of them -integrated into the core by now), including the LaTeX exporter and the plain +integrated into the core by now), including the @LaTeX{} exporter and the plain list parser. His support during the early days, when he basically acted as co-maintainer, was central to the success of this project. Bastien also invented Worg, helped establishing the Web presence of Org, and sponsors @@ -15340,13 +16241,13 @@ know what I am missing here! @i{Thomas Baumann} wrote @file{org-bbdb.el} and @file{org-mhe.el}. @item @i{Christophe Bataillon} created the great unicorn logo that we use on the -Org-mode website. +Org mode website. @item @i{Alex Bochannek} provided a patch for rounding timestamps. @item @i{Jan Böcker} wrote @file{org-docview.el}. @item -@i{Brad Bozarth} showed how to pull RSS feed data into Org-mode files. +@i{Brad Bozarth} showed how to pull RSS feed data into Org mode files. @item @i{Tom Breton} wrote @file{org-choose.el}. @item @@ -15522,7 +16423,7 @@ tweaks and features. extension system, added support for mairix, and proposed the mapping API. @item @i{Ulf Stegemann} created the table to translate special symbols to HTML, -LaTeX, UTF-8, Latin-1 and ASCII. +@LaTeX{}, UTF-8, Latin-1 and ASCII. @item @i{Andy Stewart} contributed code to @file{org-w3m.el}, to copy HTML content with links transformation to Org syntax. @@ -15530,10 +16431,10 @@ with links transformation to Org syntax. @i{David O'Toole} wrote @file{org-publish.el} and drafted the manual chapter about publishing. @item -@i{Jambunathan K} contributed the OpenDocumentText exporter. +@i{Jambunathan K} contributed the @acronym{ODT} exporter. @item -@i{Sebastien Vauban} reported many issues with LaTeX and BEAMER export and -enabled source code highlighting in Gnus. +@i{Sebastien Vauban} reported many issues with @LaTeX{} and BEAMER export and +enabled source code highlighling in Gnus. @item @i{Stefan Vollmar} organized a video-recorded talk at the Max-Planck-Institute for Neurology. He also inspired the creation of a diff --git a/doc/misc/pcl-cvs.texi b/doc/misc/pcl-cvs.texi index d4f82b6b3a7..32d2114f5a0 100644 --- a/doc/misc/pcl-cvs.texi +++ b/doc/misc/pcl-cvs.texi @@ -6,7 +6,7 @@ @c %**end of header @copying -Copyright @copyright{} 1991-2011 +Copyright @copyright{} 1991-2012 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/pgg.texi b/doc/misc/pgg.texi index 0de12577b2d..5aa9b1eb230 100644 --- a/doc/misc/pgg.texi +++ b/doc/misc/pgg.texi @@ -11,7 +11,7 @@ This file describes PGG @value{VERSION}, an Emacs interface to various PGP implementations. -Copyright @copyright{} 2001, 2003-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2001, 2003-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/rcirc.texi b/doc/misc/rcirc.texi index 3e9ee928822..0174c3fa87f 100644 --- a/doc/misc/rcirc.texi +++ b/doc/misc/rcirc.texi @@ -5,7 +5,7 @@ @c %**end of header @copying -Copyright @copyright{} 2006-2011 +Copyright @copyright{} 2006-2012 Free Software Foundation, Inc. @quotation @@ -524,7 +524,7 @@ your full name, you might want to set it to some pseudonym. @item rcirc-authinfo @vindex rcirc-authinfo -@cindex authentification +@cindex authentication @cindex identification @cindex nickserv @cindex login @@ -547,7 +547,7 @@ And here are the valid method symbols and the arguments they require: @table @code @item nickserv -@cindex nickserv authentification +@cindex nickserv authentication Use this symbol if you need to identify yourself as follows when connecting to a network: @code{/msg nickserv identify secret}. The necessary arguments are the nickname you want to use this for, and the @@ -558,7 +558,7 @@ pick a password for it. Contact @code{nickserv} and check out the details. (Using @code{/msg nickserv help}, for example.) @item chanserv -@cindex chanserv authentification +@cindex chanserv authentication Use this symbol if you need to identify yourself as follows if you want to join a particular channel: @code{/msg chanserv identify #underground secret}. The necessary arguments are the nickname and channel you want @@ -569,7 +569,7 @@ the password to use. Contact @code{chanserv} and check out the details. (Using @code{/msg chanserv help}, for example.) @item bitlbee -@cindex bitlbee authentification +@cindex bitlbee authentication Use this symbol if you need to identify yourself in the Bitlbee channel as follows: @code{identify secret}. The necessary arguments are the nickname you want to use this for, and the password to use. @@ -585,7 +585,7 @@ Bitlbee acts like an IRC server, but in fact it is a gateway to a lot of other instant messaging services. You can either install Bitlbee locally or use a public Bitlbee server. There, you need to create an account with a password. This is the nick and password you need to -provide for the bitlbee authentification method. +provide for the bitlbee authentication method. Later, you will tell Bitlbee about your accounts and passwords on all the other instant messaging services, and Bitlbee will log you in. All diff --git a/doc/misc/reftex.texi b/doc/misc/reftex.texi index 3944b712338..28d0e9cc80c 100644 --- a/doc/misc/reftex.texi +++ b/doc/misc/reftex.texi @@ -27,7 +27,7 @@ citations and indices for LaTeX documents with Emacs. This is edition @value{EDITION} of the @b{Ref@TeX{}} User Manual for @b{Ref@TeX{}} @value{VERSION} -Copyright @copyright{} 1997-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1997-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -90,7 +90,7 @@ Don't be discouraged by the size of this manual, which covers Nutshell}). You can go back later to other parts of this document when needed. -@insertcopying +@insertcopying @menu * Introduction:: Quick-Start information. @@ -157,7 +157,7 @@ Citations * Citation Info:: View the corresponding database entry. * Chapterbib and Bibunits:: Multiple bibliographies in a Document. * Citations Outside LaTeX:: How to make citations in Emails etc. -* BibTeX Database Subsets:: Extract parts of a big database. +* BibTeX Database Subsets:: Extract parts of a big database. Index Support @@ -1672,7 +1672,7 @@ support for citations helps to select the correct key quickly. * Citation Info:: View the corresponding database entry. * Chapterbib and Bibunits:: Multiple bibliographies in a Document. * Citations Outside LaTeX:: How to make citations in Emails etc. -* BibTeX Database Subsets:: Extract parts of a big database. +* BibTeX Database Subsets:: Extract parts of a big database. @end menu @node Creating Citations, Citation Styles, , Citations @@ -1776,12 +1776,12 @@ separate @code{\cite} macro for each of it. @item e Create a new BibTeX database file which contains all @i{marked} entries in the selection buffer. If no entries are marked, all entries are -selected. +selected. @item E Create a new BibTeX database file which contains all @i{unmarked} entries in the selection buffer. If no entries are marked, all entries -are selected. +are selected. @item @key{TAB} Enter a citation key with completion. This may also be a key which does @@ -3215,7 +3215,7 @@ way. Before calling a @b{Ref@TeX{}} function, the style hook should always test for the availability of the function, so that the style file will -also work for people who do not use @b{Ref@TeX{}}. +also work for people who do not use @b{Ref@TeX{}}. Additions made with style files in the way described below remain local to the current document. For example, if one package uses AMSTeX, the @@ -3714,7 +3714,7 @@ Produce a list of all duplicate labels in the document. Create a new BibTeX database file with all entries referenced in document. The command prompts for a filename and writes the collected entries to that file. Only entries referenced in the current document with -any @code{\cite}-like macros are used. +any @code{\cite}-like macros are used. The sequence in the new file is the same as it was in the old database. @end deffn @@ -3819,7 +3819,7 @@ only in that frame. So when creating that frame (with @kbd{d} key in an ordinary TOC window), the automatic recentering is turned on. When the frame gets destroyed, automatic recentering is turned off again. -This feature can be turned on and off from the menu +This feature can be turned on and off from the menu (Ref->Options). @end defopt @@ -4095,7 +4095,7 @@ Possible values for this option are: t @r{This means to trust any label prefixes found.} regexp @r{If a regexp, only prefixes matched by the regexp are trusted.} list @r{List of accepted prefixes, as strings. The colon is part of} - @r{the prefix, e.g. ("fn:" "eqn:" "item:").} + @r{the prefix, e.g. ("fn:" "eqn:" "item:").} nil @r{Never trust a label prefix.} @end example The only disadvantage of using this feature is that the label context @@ -5179,11 +5179,11 @@ Fixed bug with @samp{%F} in a label prefix. Added new escapes @noindent @b{Version 4.24} @itemize @bullet -@item +@item Inserting citation commands now prompts for optional arguments when called with a prefix argument. Related new options are @code{reftex-cite-prompt-optional-args} and -@code{reftex-cite-cleanup-optional-args}. +@code{reftex-cite-cleanup-optional-args}. @item New option @code{reftex-trust-label-prefix}. Configure this variable if you'd like RefTeX to base its classification of labels on prefixes. @@ -5199,7 +5199,7 @@ after words. Disabled indexing in comment lines. @noindent @b{Version 4.22} @itemize @bullet -@item +@item New command @code{reftex-create-bibtex-file} to create a new database with all entries referenced in the current document. @item @@ -5209,7 +5209,7 @@ from entries marked in a citation selection buffer. @noindent @b{Version 4.21} @itemize @bullet -@item +@item Renaming labels from the toc buffer with key @kbd{M-%}. @end itemize @@ -5342,7 +5342,7 @@ default stuff which has been moved to a constant. @item Environments like theorems can be placed into the TOC by putting entries for @samp{"begin@{theorem@}"} in -@code{reftex-setion-levels}. +@code{reftex-section-levels}. @end itemize @noindent @b{Version 4.06} @@ -5425,7 +5425,7 @@ File search further refined. New option @code{reftex-file-extensions}. document, all labels and associated context. New keys @kbd{i}, @kbd{l}, and @kbd{c}. New options @code{reftex-toc-include-labels}, @code{reftex-toc-include-context}, -@code{reftex-toc-include-file-boundaries}. +@code{reftex-toc-include-file-boundaries}. @end itemize @noindent @b{Version 3.41} diff --git a/doc/misc/remember.texi b/doc/misc/remember.texi index e67d6155bbe..a04ba53443d 100644 --- a/doc/misc/remember.texi +++ b/doc/misc/remember.texi @@ -8,7 +8,7 @@ @copying This manual is for Remember Mode, version 1.9 -Copyright @copyright{} 2001, 2004-2005, 2007-2011 +Copyright @copyright{} 2001, 2004-2005, 2007-2012 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/sasl.texi b/doc/misc/sasl.texi index a75b237519c..a31d9ca5e38 100644 --- a/doc/misc/sasl.texi +++ b/doc/misc/sasl.texi @@ -10,7 +10,7 @@ @copying This file describes the Emacs SASL library, version @value{VERSION}. -Copyright @copyright{} 2000, 2004-2011 +Copyright @copyright{} 2000, 2004-2012 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/sc.texi b/doc/misc/sc.texi index 37ccc4045be..6874828d427 100644 --- a/doc/misc/sc.texi +++ b/doc/misc/sc.texi @@ -14,7 +14,7 @@ This document describes Supercite, an Emacs package for citing and attributing replies to mail and news messages. -Copyright @copyright{} 1993, 2001-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1993, 2001-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/sem-user.texi b/doc/misc/sem-user.texi index e1631bcacc8..1984d69a695 100644 --- a/doc/misc/sem-user.texi +++ b/doc/misc/sem-user.texi @@ -1,6 +1,6 @@ @c This file is included by semantic.texi -@c Copyright (C) 1999-2005, 2007, 2009-2011 Free Software Foundation, Inc. +@c Copyright (C) 1999-2005, 2007, 2009-2012 Free Software Foundation, Inc. @c Permission is granted to copy, distribute and/or modify this @c document under the terms of the GNU Free Documentation License, diff --git a/doc/misc/semantic.texi b/doc/misc/semantic.texi index dcfff1fcb96..ad8392c208b 100644 --- a/doc/misc/semantic.texi +++ b/doc/misc/semantic.texi @@ -24,7 +24,7 @@ @copying This manual documents the Semantic library and utilities. -Copyright @copyright{} 1999-2005, 2007, 2009-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1999-2005, 2007, 2009-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -380,7 +380,7 @@ with the search results format. @item semanticdb-ref.el Tracks crossreferences. Cross references are needed when buffer is -reparsed, and must alert other tables that any dependant caches may +reparsed, and must alert other tables that any dependent caches may need to be flushed. References are in the form of include files. @end table @@ -536,7 +536,7 @@ the buffer. @item bovine parser A parser using the bovine parser generator. It is an LL parser -suitible for small simple languages. +suitable for small simple languages. @item context diff --git a/doc/misc/ses.texi b/doc/misc/ses.texi index 8300e6511a6..8cd2ee813ec 100644 --- a/doc/misc/ses.texi +++ b/doc/misc/ses.texi @@ -11,7 +11,7 @@ @copying This file documents SES: the Simple Emacs Spreadsheet. -Copyright @copyright{} 2002-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2002-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/sieve.texi b/doc/misc/sieve.texi index 64fd92f40ca..d13f25c2a55 100644 --- a/doc/misc/sieve.texi +++ b/doc/misc/sieve.texi @@ -11,7 +11,7 @@ @copying This file documents the Emacs Sieve package, for server-side mail filtering. -Copyright @copyright{} 2001-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2001-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/smtpmail.texi b/doc/misc/smtpmail.texi index 854be0d0012..af09783f445 100644 --- a/doc/misc/smtpmail.texi +++ b/doc/misc/smtpmail.texi @@ -3,7 +3,7 @@ @settitle Emacs SMTP Library @syncodeindex vr fn @copying -Copyright @copyright{} 2003-2011 +Copyright @copyright{} 2003-2012 Free Software Foundation, Inc. @quotation diff --git a/doc/misc/speedbar.texi b/doc/misc/speedbar.texi index 9dc47e4574c..6604dc5f0d0 100644 --- a/doc/misc/speedbar.texi +++ b/doc/misc/speedbar.texi @@ -4,7 +4,7 @@ @syncodeindex fn cp @copying -Copyright @copyright{} 1999-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1999-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/tramp.texi b/doc/misc/tramp.texi index 1cea074fa2b..41ba6689f13 100644 --- a/doc/misc/tramp.texi +++ b/doc/misc/tramp.texi @@ -37,7 +37,7 @@ @end macro @copying -Copyright @copyright{} 1999-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1999-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/trampver.texi b/doc/misc/trampver.texi index 63dc78dc4e8..b4fb5f9aa6a 100644 --- a/doc/misc/trampver.texi +++ b/doc/misc/trampver.texi @@ -2,7 +2,7 @@ @c texi/trampver.texi. Generated from trampver.texi.in by configure. @c This is part of the Emacs manual. -@c Copyright (C) 2003-2011 Free Software Foundation, Inc. +@c Copyright (C) 2003-2012 Free Software Foundation, Inc. @c See file doclicense.texi for copying conditions. @c In the Tramp CVS, the version number is auto-frobbed from diff --git a/doc/misc/url.texi b/doc/misc/url.texi index 42594457ab1..6464fba53b4 100644 --- a/doc/misc/url.texi +++ b/doc/misc/url.texi @@ -20,7 +20,7 @@ @copying This file documents the Emacs Lisp URL loading package. -Copyright @copyright{} 1993-1999, 2002, 2004-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1993-1999, 2002, 2004-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/vip.texi b/doc/misc/vip.texi index 03ca65882e5..4b4bbfe5091 100644 --- a/doc/misc/vip.texi +++ b/doc/misc/vip.texi @@ -3,7 +3,7 @@ @settitle VIP @copying -Copyright @copyright{} 1987, 2001-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1987, 2001-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/viper.texi b/doc/misc/viper.texi index 1f0dffee5b4..a660cfb6b9d 100644 --- a/doc/misc/viper.texi +++ b/doc/misc/viper.texi @@ -7,7 +7,7 @@ @setfilename ../../info/viper @copying -Copyright @copyright{} 1995-1997, 2001-2011 Free Software Foundation, Inc. +Copyright @copyright{} 1995-1997, 2001-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/widget.texi b/doc/misc/widget.texi index a778f491e76..24fe3e63ac9 100644 --- a/doc/misc/widget.texi +++ b/doc/misc/widget.texi @@ -8,7 +8,7 @@ @c %**end of header @copying -Copyright @copyright{} 2000-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2000-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document diff --git a/doc/misc/woman.texi b/doc/misc/woman.texi index c869d1a46c7..1ad741d3d30 100644 --- a/doc/misc/woman.texi +++ b/doc/misc/woman.texi @@ -18,7 +18,7 @@ This file documents WoMan: A program to browse Unix manual pages `W.O. (without) man'. -Copyright @copyright{} 2001-2011 Free Software Foundation, Inc. +Copyright @copyright{} 2001-2012 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document |