* abbrevs.texi (Saving Abbrevs): Abbrev file should be in .emacs.d.
* basic.texi (Moving Point): M-r is now move-to-window-line-top-bottom.
* cmdargs.texi (Initial Options):
* xresources.texi (Resources): Document inhibit-x-resources.
* custom.texi (Specifying File Variables): Note that minor modes are
enabled unconditionally.
* display.texi (Scrolling): Briefly document the old recenter command,
and document recenter-positions.
* files.texi (Visiting):
* buffers.texi (Buffers): Max buffer size is now 512 MB.
* frames.texi (Cut/Paste Other App): Document
save-interprogram-paste-before-kill.
* killing.texi (Kill Options): New node.
+2009-12-24 Chong Yidong <cyd@stupidchicken.com>
+
+ * emacs.texi (Top): Update node listing.
+
+ * abbrevs.texi (Saving Abbrevs): Abbrev file should be in .emacs.d.
+
+ * basic.texi (Moving Point): M-r is now move-to-window-line-top-bottom.
+
+ * cmdargs.texi (Initial Options):
+ * xresources.texi (Resources): Document inhibit-x-resources.
+
+ * custom.texi (Specifying File Variables): Note that minor modes are
+ enabled unconditionally.
+
+ * display.texi (Scrolling): Briefly document the old recenter command,
+ and document recenter-positions.
+
+ * files.texi (Visiting):
+ * buffers.texi (Buffers): Max buffer size is now 512 MB.
+
+ * frames.texi (Cut/Paste Other App): Document
+ save-interprogram-paste-before-kill.
+
+ * killing.texi (Kill Options): New node.
+
2009-12-05 Chong Yidong <cyd@stupidchicken.com>
* misc.texi (Shell Options): ansi-color is now default.
and then reads the file, defining abbrevs according to the contents of
the file. The function @code{quietly-read-abbrev-file} is similar
except that it does not display a message in the echo area; you cannot
-invoke it interactively, and it is used primarily in the @file{.emacs}
-file. If either of these functions is called with @code{nil} as the
-argument, it uses the file name specified in the variable
-@code{abbrev-file-name}, which is by default @code{"~/.abbrev_defs"}.
-That file is your standard abbrev definition file, and Emacs loads
-abbrevs from it automatically when it starts up. (As an exception,
-Emacs does not load the abbrev file when it is started in batch mode.
-@xref{Initial Options}, for a description of batch mode.)
+invoke it interactively, and it is used primarily in your init file
+(@pxref{Init File}). If either of these functions is called with
+@code{nil} as the argument, it uses the file given by the variable
+@code{abbrev-file-name}, which is @file{~/.emacs.d/abbrev_defs} by
+default. This is your standard abbrev definition file, and Emacs
+loads abbrevs from it automatically when it starts up. (As an
+exception, Emacs does not load the abbrev file when it is started in
+batch mode. @xref{Initial Options}, for a description of batch mode.)
@vindex save-abbrevs
Emacs will offer to save abbrevs automatically if you have changed
Move up one screen line (@code{previous-line}). This command
preserves position within the line, like @kbd{C-n}.
@item M-r
-Move point to left margin, vertically centered in the window
-(@code{move-to-window-line}). Text does not move on the screen.
+Without moving the text on the screen, reposition point on the left
+margin of the center-most text line of the window; on subsequent
+consecutive invocations, move point to the left margin of the top-most
+line, the bottom-most line, and so forth, in cyclic order
+(@code{move-to-window-line-top-bottom}).
+
A numeric argument says which screen line to place point on, counting
downward from the top of the window (zero means the top line). A
negative argument counts lines up from the bottom (@minus{}1 means the
bottom line).
+
@item M-<
Move to the top of the buffer (@code{beginning-of-buffer}). With
numeric argument @var{n}, move to @var{n}/10 of the way from the top.
@cindex buffer size, maximum
A buffer's size cannot be larger than some maximum, which is defined
-by the largest buffer position representable by the @dfn{Emacs integer}
-data type. This is because Emacs tracks buffer positions using that
-data type. For 32-bit machines, the largest buffer size is 256
-megabytes.
+by the largest buffer position representable by the @dfn{Emacs
+integer} data type. This is because Emacs tracks buffer positions
+using that data type. For 32-bit machines, the largest buffer size is
+512 megabytes.
@menu
* Select Buffer:: Creating a new buffer or reselecting an old one.
@opindex -Q
@itemx --quick
@opindex --quick
-Start emacs with minimum customizations. This is like using
-@samp{-q}, @samp{--no-site-file}, and @samp{--no-splash} together.
+Start emacs with minimum customizations, similar to using @samp{-q},
+@samp{--no-site-file}, and @samp{--no-splash} together. This also
+stops Emacs from processing X resources by setting
+@code{inhibit-x-resources} to @code{t} (@pxref{Resources}).
@item -daemon
@opindex -daemon
@noindent
You can specify any number of variable/value pairs in this way, each
-pair with a colon and semicolon as shown above. @code{mode:
-@var{modename};} specifies the major mode; this should come first in the
-line. The @var{value}s are not evaluated; they are used literally.
-Here is an example that specifies Lisp mode and sets two variables with
-numeric values:
+pair with a colon and semicolon as shown above. The special
+variable/value pair @code{mode: @var{modename};}, if present,
+specifies a major or minor mode; if you use this to specify a major
+mode, it should come first in the line. The @var{value}s are are used
+literally, and not evaluated.
+
+ Here is an example that specifies Lisp mode and sets two variables
+with numeric values:
@smallexample
;; -*- mode: Lisp; fill-column: 75; comment-column: 50; -*-
@end smallexample
- You can also specify the coding system for a file in this way: just
-specify a value for the ``variable'' named @code{coding}. The ``value''
-must be a coding system name that Emacs recognizes. @xref{Coding
-Systems}. @w{@samp{unibyte: t}} specifies unibyte loading for a
-particular Lisp file. @xref{Enabling Multibyte}.
-
- The @code{eval} pseudo-variable, described below, can be specified in
-the first line as well.
+@noindent
+Aside from @code{mode}, other keywords that have special meanings as
+file variables are @code{coding}, @code{unibyte}, and @code{eval}.
+These are described below.
@cindex shell scripts, and local file variables
@cindex man pages, and local file variables
In shell scripts, the first line is used to identify the script
interpreter, so you cannot put any local variables there. To
accommodate this, Emacs looks for local variable specifications in the
-@emph{second} line when the first line specifies an interpreter.
-The same is true for man pages which start with the magic string
+@emph{second} line if the first line specifies an interpreter. The
+same is true for man pages which start with the magic string
@samp{'\"} to specify a list of troff preprocessors (not all do,
however).
- A @dfn{local variables list} goes near the end of the file. It
-starts with a line containing the string @samp{Local Variables:}, and
-ends with a line containing the string @samp{End:}. In between come
-the variable names and values, one set per line, as
-@samp{@var{variable}:@: @var{value}}. The @var{value}s are not
-evaluated; they are used literally. If a file has both a local
-variables list and a @samp{-*-} line, Emacs processes
-@emph{everything} in the @samp{-*-} line first, and @emph{everything}
-in the local variables list afterward.
+ Instead of 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
+the file is divided into pages.
- Here is an example of a local variables list:
+ If a file has both a local variables list and a @samp{-*-} line,
+Emacs processes @emph{everything} in the @samp{-*-} line first, and
+@emph{everything} in the local variables list afterward.
+
+ A local variables list starts with a line containing the string
+@samp{Local Variables:}, and ends with a line containing the string
+@samp{End:}. In between come the variable names and values, one set
+per line, like this:
@example
/* Local Variables: */
/* End: */
@end example
- In this example, each line starts with the prefix @samp{/*} and each
-line ends with the suffix @samp{*/}. Emacs recognizes these as the
-prefix and suffix by finding them surrounding the magic string
-@samp{Local Variables:}, on 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 as input for. The example above is for the
-C programming language, where comment lines start with @samp{/*} and
-end with @samp{*/}. Don't use a prefix (or a suffix) if you don't
-need one.
-
- If you write a multi-line string value, you should put the prefix
-and suffix on each line, even lines that start or end within the
-string. They will be stripped off for processing the list. If you
-want to split a long string across multiple lines of the file, you can
-use backslash-newline, which is ignored in Lisp string constants.
-Here's an example of doing this:
+@noindent
+In this example, each line starts with the prefix @samp{/*} and ends
+with the suffix @samp{*/}. Emacs recognizes the prefix and suffix by
+finding them surrounding the magic string @samp{Local Variables:}, on
+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{*/}.
+
+ 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
+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
+the list. Here is an example:
@example
# Local Variables:
@end example
Some ``variable names'' have special meanings in a local variables
-list. Specifying the ``variable'' @code{mode} really sets the major
-mode, while any value specified for the ``variable'' @code{eval} is
-simply evaluated as an expression (its value is ignored). A value for
+list:
+
+@itemize
+@item
+@code{mode} enables the specified major or minor mode.
+
+@item
+@code{eval} evaluates the specified Lisp expression (the value
+returned by that expression is ignored).
+
+@item
@code{coding} specifies the coding system for character code
-conversion of this file, and a value of @code{t} for @code{unibyte}
-says to visit the file in a unibyte buffer. These four ``variables''
-are not really variables; setting them in any other context has no
-special meaning.
+conversion of this file. @xref{Coding Systems}.
+
+@item
+@code{unibyte} says to visit the file in a unibyte buffer, if the
+value is @code{t}. @xref{Enabling Multibyte}.
+@end itemize
+
+@noindent
+These four ``variables'' are not really variables; setting them in any
+other context has no special meaning.
@emph{If @code{mode} is used to set a major mode, it should be the
first ``variable'' in the list.} Otherwise, the entries that precede
-it will usually be ignored, since most modes kill all local variables
-as part of their initialization.
-
- You can use the @code{mode} ``variable'' to set minor modes as well
-as the major modes; in fact, you can use it more than once, first to
-set the major mode and then to set minor modes which are specific to
-particular buffers. But most minor modes should not be specified in
-the file at all, because they represent user preferences.
-
- For example, you may be tempted to try to turn on Auto Fill mode with
-a local variable list. That is a mistake. The choice of Auto Fill mode
-or not is a matter of individual taste, not a matter of the contents of
-particular files. If you want to use Auto Fill, set up major mode hooks
-with your @file{.emacs} file to turn it on (when appropriate) for you
-alone (@pxref{Init File}). Don't use a local variable list to impose
-your taste on everyone.
-
- The start of the local variables list must be no more than 3000
-characters from the end of the file, and must be in the last page if
-the file is divided into pages. Otherwise, Emacs will not notice it
-is there. The purpose of this rule is so that Emacs need not take the
-time to search the whole file.
+it will usually have no effect, since most major modes kill all local
+variables as part of their initialization.
+
+ 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.
+
+ Often, however, it is a mistake to enable minor modes this way.
+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,
File-local variables can be dangerous; when you visit someone else's
file, there's no telling what its local variables list could do to
-your Emacs. Improper values of the @code{eval} ``variable,'' and
+your Emacs. Improper values of the @code{eval} ``variable'', and
other variables such as @code{load-path}, could execute Lisp code you
didn't intend to run.
determine whether the values are known to be safe.
@vindex enable-local-eval
+@vindex safe-local-eval-forms
The variable @code{enable-local-eval} controls whether Emacs
processes @code{eval} variables. The three possibilities for the
variable's value are @code{t}, @code{nil}, and anything else, just as
is neither @code{t} nor @code{nil}, so normally Emacs does ask for
confirmation about processing @code{eval} variables.
-@vindex safe-local-eval-forms
- But there is an exception. The @code{safe-local-eval-forms} is a
-customizable list of eval forms which are safe. Emacs does not ask
-for confirmation when it finds these forms for the @code{eval}
-variable.
+ As an exception, Emacs never asks for confirmation to evaluate any
+@code{eval} form if that form occurs within the variable
+@code{safe-local-eval-forms}.
@node Directory Variables
@subsection Per-Directory Local Variables
@table @kbd
@item C-l
-Scroll the selected window to center point vertically within it and
-maybe redisplay the screen (@code{recenter-top-bottom}).
+Scroll the selected window so that the current line is the center-most
+text line; on subsequent consecutive invocations, make the current
+line the top-most line, the bottom-most line, and so forth in cyclic
+order; also, maybe redisplay the screen (@code{recenter-top-bottom}).
@item C-v
@itemx @key{next}
@itemx @key{PageDown}
@kindex C-l
@findex recenter-top-bottom
- The most basic scrolling command is @kbd{C-l}
-(@code{recenter-top-bottom}). This @dfn{recenters} the selected
-window, scrolling it so that the current screen line is exactly in the
-center of the window, or as close to the center as possible. If the
-variable @var{recenter-redisplay} is non-nil, it also clears the
-screen and redisplays all windows; this is useful in case the screen
-becomes garbled for any reason (@pxref{Screen Garbled}). If
-@var{recenter-redisplay} has the special value @code{tty} (the
-default), then redisplay only happens on tty frames.
+ @kbd{C-l} (@code{recenter-top-bottom}) is a basic scrolling command.
+It @dfn{recenters} the selected window, scrolling it so that the
+current screen line is exactly in the center of the window, or as
+close to the center as possible.
Typing @kbd{C-l} twice in a row (@kbd{C-l C-l}) scrolls the window
so that point is on the topmost screen line. Typing a third @kbd{C-l}
scrolls the window so that point is on the bottom-most screen line.
Each successive @kbd{C-l} cycles through these three screen positions.
-(If you change the variable @code{scroll-margin} to a non-zero value
-@var{n}, Emacs leaves @var{n} screen lines between point and the top
-or bottom of the window. @xref{Auto Scrolling}.)
+
+@vindex recenter-positions
+ You can change the cycling order by customizing the list variable
+@code{recenter-positions}. Each list element should be the symbol
+@code{top}, @code{middle}, or @code{bottom}, or a number; an integer
+number means to move the line to the specified screen line, while a
+floating-point number between 0.0 and 1.0 specifies a percentage of
+the screen space from the top. The default, @code{(middle top
+bottom)}, is the cycling order described above. Furthermore, if you
+change the variable @code{scroll-margin} to a non-zero value @var{n},
+Emacs always leaves @var{n} screen lines between point and the top or
+bottom of the window (@pxref{Auto Scrolling}).
You can also supply @kbd{C-l} with a prefix argument. With a plain
prefix argument, @kbd{C-u C-l}, Emacs simply recenters point. With a
lines from the bottom. When given an argument, @kbd{C-l} does not
clear the screen or cycle through different screen positions.
+ The more primitive command @code{recenter} behaves like
+@code{recenter-top-bottom}, but does not cycle among screen positions.
+Prior to Emacs 23, @kbd{C-l} was bound to @code{recenter}.
+
@vindex recenter-redisplay
- When the variable @code{recenter-redisplay} is non-nil, the
-@code{recenter} and @code{recenter-top-bottom} commands redisplay the
-selected frame when they are invoked without a prefix argument.
+ If the variable @code{recenter-redisplay} has a non-@code{nil}
+value, Emacs clears and redisplays the screen each time @kbd{C-l}
+recenters the window; the special value @code{tty} (the default) says
+to do this on text-terminal frames only. Redisplaying is useful in
+case the screen becomes garbled for any reason (@pxref{Screen
+Garbled}).
@kindex C-v
@kindex M-v
@kindex PageUp
@findex scroll-up
@findex scroll-down
- To read the buffer a windowful at a time, use @kbd{C-v}
+ To read the buffer a windowful at a time, type @kbd{C-v}
(@code{scroll-up}). This scrolls forward by nearly the whole window
height. The effect is to take the two lines at the bottom of the
window and put them at the top, followed by lines that were not
* Killing by Lines:: How to kill entire lines of text at one time.
* Other Kill Commands:: Commands to kill large regions of text and
syntactic units such as words and sentences.
+* Kill Options:: Options that affect killing.
Yanking
about 10 megabytes), Emacs asks you for confirmation first. You can
answer @kbd{y} to proceed with visiting the file. Note, however, that
Emacs cannot visit files that are larger than the maximum Emacs buffer
-size, which is around 256 megabytes on 32-bit machines
+size, which is around 512 megabytes on 32-bit machines
(@pxref{Buffers}). If you try, Emacs will display an error message
saying that the maximum buffer size has been exceeded.
the primary selection. @xref{Killing}.
@vindex select-active-regions
+ If you set the region using the keyboard---for instance, by typing
+@kbd{C-@key{SPC}} and moving point away from the mark---the text in
+the region is not normally saved to the primary selection. However,
+if you change the variable @code{select-active-regions} to @code{t},
+the region is saved to the primary selection whenever you activate the
+mark. Each change to the region also updates the primary selection.
+
@vindex yank-pop-change-selection
- If you set the region using the keyboard, the text within the region
-is not normally saved to the primary selection. However, if you
-change the variable @code{select-active-regions} to @code{t}, the
-region is saved to the primary selection each time you activate the
-mark. The primary selection is updated if you subsequently change the
-region by moving point. If you change the variable
-@code{yank-pop-change-selection} to @code{t}, rotating the kill ring
-with @kbd{M-y} (@code{yank-pop}) also saves the new yank to the
-primary selection (@pxref{Yanking}).
+ If you change @code{yank-pop-change-selection} to @code{t}, rotating
+the kill ring with @kbd{M-y} (@code{yank-pop}) also saves the new yank
+to the primary selection (@pxref{Yanking}).
+
+@vindex save-interprogram-paste-before-kill
+ If you change @code{save-interprogram-paste-before-kill} to
+@code{t}, each kill command first saves the existing selection onto
+the kill ring. This prevents you from losing the existing selection,
+at the risk of large memory consumption if other applications generate
+large selections.
@cindex cut buffer
@vindex x-cut-buffer-max
Whenever Emacs saves some text to the primary selection, it may also
save it to the @dfn{cut buffer}. The cut buffer is an obsolete
predecessor to the primary selection; most modern applications do not
-make use of it. Because saving text to the cut buffer is slow and
-inefficient, Emacs only does it if the text is shorter than the value
-of @code{x-cut-buffer-max} (the default is 20000 characters).
+use it. Saving text to the cut buffer is slow and inefficient, so
+Emacs only does it if the text is shorter than the value of
+@code{x-cut-buffer-max} (20000 characters by default).
You can yank the primary selection into Emacs using the usual yank
commands, such as @kbd{C-y} (@code{yank}) and @kbd{Mouse-2}
commands' names and individual descriptions use the words @samp{kill}
and @samp{delete} to say which kind of operation they perform.
-@vindex kill-read-only-ok
-@cindex read-only text, killing
- Some specialized buffers contain @dfn{read-only text}, which cannot
-be modified and therefore cannot be killed. But some users like to
-use the kill commands to copy read-only text into the kill ring,
-without actually changing it. Therefore, the kill commands work
-specially in a read-only buffer: they move over text, and copy it to
-the kill ring, without actually deleting it from the buffer.
-Normally, kill commands beep and display an error message when this
-happens. But if you set the variable @code{kill-read-only-ok} to a
-non-@code{nil} value, they just print a message in the echo area to
-explain why the text has not been erased.
-
You can also use the mouse to kill and yank. @xref{Cut and Paste}.
@menu
* Killing by Lines:: How to kill entire lines of text at one time.
* Other Kill Commands:: Commands to kill large regions of text and
syntactic units such as words and sentences.
+* Kill Options:: Options that affect killing.
@end menu
-@need 1500
@node Deletion
@subsection Deletion
@findex delete-backward-char
numeric argument acts as a repeat count; a negative argument means to
search backward and kill text before point.
+@node Kill Options
+@subsection Options for Killing
+
+@vindex kill-read-only-ok
+@cindex read-only text, killing
+ Some specialized buffers contain @dfn{read-only text}, which cannot
+be modified and therefore cannot be killed. But some users like to
+use the kill commands to copy read-only text into the kill ring,
+without actually changing it. Therefore, the kill commands work
+specially in a read-only buffer: they move over text, and copy it to
+the kill ring, without actually deleting it from the buffer.
+Normally, kill commands beep and display an error message when this
+happens. But if you set the variable @code{kill-read-only-ok} to a
+non-@code{nil} value, they just print a message in the echo area to
+explain why the text has not been erased.
+
+@vindex kill-do-not-save-duplicates
+ If you change the variable @code{kill-do-not-save-duplicates} to a
+non-@code{nil} value, identical subsequent kills yield a single
+kill-ring entry, without duplication.
+
@node Yanking, Accumulating Text, Killing, Top
@section Yanking
@cindex moving text
@end ifnottex
The order in which the lines appear in the file does not matter.
-Also, command-line options always override the X resources file.
+One way to experiment with the effect of different resource settings
+is to use the @code{editres} program. See the @code{editres} man page
+for more details.
+
+ Emacs does not process X resources at all if you set the variable
+@code{inhibit-x-resources} to a non-@code{nil} value, or if you
+specify the @samp{-Q} (or @samp{--quick}) command-line argument
+(@pxref{Initial Options}). (The @samp{-Q} argument automatically sets
+@code{inhibit-x-resources} to @code{t}.)
@ifnottex
- The following X command-line options affect how X resources are
-processed:
+ In addition, you can use the following command-line options to
+override the X resources file:
@table @samp
@item -name @var{name}
@end table
@end ifnottex
- One way to experiment with the effect of different resource settings
-is to use the @code{editres} program. See the @code{editres} man page
-for more details.
-
@node Table of Resources
@appendixsec Table of X Resources for Emacs
projects / emacs.git / commitdiff