procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

* emacs.texi (Top): Update node listing.

Browse source 
* 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.
This commit is contained in:
Chong Yidong 2009-12-25 20:00:32 +00:00
parent 31f9c37613
commit 91ed7ea864
12 changed files with 216 additions and 144 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
doc/emacs/ChangeLog
View file

@ -1,3 +1,28 @@
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.

16
doc/emacs/abbrevs.texi
View file

@ -309,14 +309,14 @@ that, when executed, define the same abbrevs that you currently have.
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

9
doc/emacs/basic.texi
View file

@ -182,12 +182,17 @@ middle of one line, you move to the middle of the next.
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.

8
doc/emacs/buffers.texi
View file

@ -41,10 +41,10 @@ can be different from the value in other buffers. @xref{Locals}.
@cindex buffer size, maximum
A buffer's size cannot be larger than some maximum, which is defined
by the largest buffer position representable by the @dfn{Emacs integer}
data type. This is because Emacs tracks buffer positions using that
data type. For 32-bit machines, the largest buffer size is 256
megabytes.
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.

6
doc/emacs/cmdargs.texi
View file

@ -297,8 +297,10 @@ in your initialization file (@pxref{Entering Emacs}).
@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

158
doc/emacs/custom.texi
View file

@ -1083,46 +1083,48 @@ 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. @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: */
@ -1131,25 +1133,24 @@ in the local variables list afterward.
/* 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.
@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{*/}.
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:
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:
@ -1159,39 +1160,45 @@ Here's an example of doing this:
@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.
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 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.
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.
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.
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,
@ -1202,7 +1209,7 @@ including the local variables list if any. @xref{Choosing Modes}.
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.
@ -1247,6 +1254,7 @@ query you about each file that has local variables, without trying to
determine whether the values are known to be safe.
@vindex enable-local-eval
@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
@ -1254,11 +1262,9 @@ for @code{enable-local-variables}. The default is @code{maybe}, which
is neither @code{t} nor @code{nil}, so normally Emacs does ask for
confirmation about processing @code{eval} variables.
@vindex safe-local-eval-forms
But there is an exception. The @code{safe-local-eval-forms} is a
customizable list of eval forms which are safe. Emacs does not ask
for confirmation when it finds these forms for the @code{eval}
variable.
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

49
doc/emacs/display.texi
View file

@ -53,8 +53,10 @@ commands:
@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}
@ -70,23 +72,27 @@ Scroll heuristically to bring useful information onto the screen
@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
@ -98,10 +104,17 @@ puts point on the bottom line, and @kbd{C-u - 5 C-l} puts it five
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
@ -111,7 +124,7 @@ selected frame when they are invoked without a prefix argument.
@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

1
doc/emacs/emacs.texi
View file

@ -324,6 +324,7 @@ Killing and Moving Text
* 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

2
doc/emacs/files.texi
View file

@ -207,7 +207,7 @@ to reread it.
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.

32
doc/emacs/frames.texi
View file

@ -252,25 +252,33 @@ such as @kbd{M-w} (@code{kill-ring-save}), that text is also saved in
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}

36
doc/emacs/killing.texi
View file

@ -46,19 +46,6 @@ amounts of nontrivial data generally do a kill operation instead. The
commands' names and individual descriptions use the words @samp{kill}
and @samp{delete} to say which kind of operation they perform.
@vindex kill-read-only-ok
@cindex read-only text, killing
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
@ -67,9 +54,9 @@ explain why the text has not been erased.
* 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
@ -224,6 +211,27 @@ including) the next occurrence of that character in the buffer. A
numeric argument acts as a repeat count; a negative argument means to
search backward and kill text before point.
@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

18
doc/emacs/xresources.texi
View file

@ -107,11 +107,19 @@ emacs.borderWidth: 4
@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}
@ -150,10 +158,6 @@ other resource specifications.
@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