Github/emacs
2
0
Fork 1
mirror of git://git.sv.gnu.org/emacs.git synced 2026-02-23 21:37:34 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge from trunk.

Browse source
This commit is contained in:
Paul Eggert 2011-08-29 23:19:35 -07:00
commit f00b626d88
13 changed files with 267 additions and 454 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
doc/emacs/ChangeLog
View file

@ -1,3 +1,7 @@
2011-08-29 Chong Yidong <cyd@stupidchicken.com>
* modes.texi (Choosing Modes): auto-mode-case-fold is now t.
2011-08-28 Chong Yidong <cyd@stupidchicken.com>
* files.texi (File Archives):

13
doc/emacs/modes.texi
View file

@ -353,12 +353,13 @@ the element has the form @code{(@var{regexp} @var{mode-function}
@var{regexp} and searches the list again for another match.
@vindex auto-mode-case-fold
On systems with case-insensitive file names, such as Microsoft
Windows, Emacs performs a single case-insensitive search through
@code{auto-mode-alist}. On other systems, Emacs normally performs a
single case-sensitive search through the alist. However, if you
change the variable @code{auto-mode-case-fold} to @code{t}, Emacs
performs a second case-insensitive search if the first search fails.
On GNU/Linux and other systems with case-sensitive file names, Emacs
performs a case-sensitive search through @code{auto-mode-alist}; if
this search fails, it performs a second case-insensitive search
through the alist. To suppress the second search, change the variable
@code{auto-mode-case-fold} to @code{nil}. On systems with
case-insensitive file names, such as Microsoft Windows, Emacs performs
a single case-insensitive search through @code{auto-mode-alist}.
@vindex magic-fallback-mode-alist
Finally, if Emacs @emph{still} hasn't found a major mode to use, it

7
doc/lispref/ChangeLog
View file

@ -1,3 +1,10 @@
2011-08-29 Chong Yidong <cyd@stupidchicken.com>
* modes.texi (Basic Major Modes): New node. Callers updated.
(Major Modes): Document fundamental-mode and major-mode.
(Major Mode Basics): Node deleted; text moved to Major Modes.
(Derived Modes): Document derived-mode-p.
2011-08-28 Chong Yidong <cyd@stupidchicken.com>
* files.texi (Changing Files, Create/Delete Dirs): Document new

5
doc/lispref/elisp.texi
View file

@ -765,8 +765,7 @@ Major and Minor Modes
* Major Modes:: Defining major modes.
* Minor Modes:: Defining minor modes.
* Mode Line Format:: Customizing the text that appears in the mode line.
* Imenu:: How a mode can provide a menu
of definitions in the buffer.
* Imenu:: Providing a menu of definitions made in a buffer.
* Font Lock Mode:: How modes can highlight text according to syntax.
* Desktop Save Mode:: How modes can have buffer state saved between
Emacs sessions.
@ -778,12 +777,12 @@ Hooks
Major Modes
* Major Mode Basics::
* Major Mode Conventions:: Coding conventions for keymaps, etc.
* Auto Major Mode:: How Emacs chooses the major mode automatically.
* Mode Help:: Finding out how to use a mode.
* Derived Modes:: Defining a new major mode based on another major
mode.
* Basic Major Modes:: Modes that other modes are often derived from.
* Generic Modes:: Defining a simple major mode that supports
comment syntax and Font Lock mode.
* Mode Hooks:: Hooks run at the end of major mode functions.

337
doc/lispref/modes.texi
View file

@ -19,16 +19,15 @@ user. For related topics such as keymaps and syntax tables, see
@ref{Keymaps}, and @ref{Syntax Tables}.
@menu
* Hooks:: How to use hooks; how to write code that provides hooks.
* Major Modes:: Defining major modes.
* Minor Modes:: Defining minor modes.
* Mode Line Format:: Customizing the text that appears in the mode line.
* Imenu:: How a mode can provide a menu
of definitions in the buffer.
* Font Lock Mode:: How modes can highlight text according to syntax.
* Auto-Indentation:: How to teach Emacs to indent for a major mode.
* Desktop Save Mode:: How modes can have buffer state saved between
Emacs sessions.
* Hooks:: How to use hooks; how to write code that provides hooks.
* Major Modes:: Defining major modes.
* Minor Modes:: Defining minor modes.
* Mode Line Format:: Customizing the text that appears in the mode line.
* Imenu:: Providing a menu of definitions made in a buffer.
* Font Lock Mode:: How modes can highlight text according to syntax.
* Auto-Indentation:: How to teach Emacs to indent for a major mode.
* Desktop Save Mode:: How modes can have buffer state saved between
Emacs sessions.
@end menu
@node Hooks
@ -48,12 +47,12 @@ convention, whenever the hook name ends in @samp{-hook}, that tells
you it is normal. We try to make all hooks normal, as much as
possible, so that you can use them in a uniform way.
Every major mode function is supposed to run a normal hook called
the @dfn{mode hook} as the one of the last steps of initialization.
This makes it easy for a user to customize the behavior of the mode,
by overriding the buffer-local variable assignments already made by
the mode. Most minor mode functions also run a mode hook at the end.
But hooks are used in other contexts too. For example, the hook
Every major mode command is supposed to run a normal hook called the
@dfn{mode hook} as the one of the last steps of initialization. This
makes it easy for a user to customize the behavior of the mode, by
overriding the buffer-local variable assignments already made by the
mode. Most minor mode functions also run a mode hook at the end. But
hooks are used in other contexts too. For example, the hook
@code{suspend-hook} runs just before Emacs suspends itself
(@pxref{Suspending Emacs}).
@ -78,8 +77,8 @@ convention.
its value is just a single function, not a list of functions.
@menu
* Running Hooks:: How to run a hook.
* Setting Hooks:: How to put functions on a hook, or remove them.
* Running Hooks:: How to run a hook.
* Setting Hooks:: How to put functions on a hook, or remove them.
@end menu
@node Running Hooks
@ -195,115 +194,98 @@ from the buffer-local hook list instead of from the global hook list.
@section Major Modes
@cindex major mode
@cindex major mode command
Major modes specialize Emacs for editing particular kinds of text.
Each buffer has only one major mode at a time. For each major mode
there is a function to switch to that mode in the current buffer; its
name should end in @samp{-mode}. These functions work by setting
buffer-local variable bindings and other data associated with the
buffer, such as a local keymap. The effect lasts until you switch
to another major mode in the same buffer.
Each buffer has one major mode at a time. Every major mode is
associated with a @dfn{major mode command}, whose name should end in
@samp{-mode}. This command takes care of switching to that mode in the
current buffer, by setting various buffer-local variables such as a
local keymap. @xref{Major Mode Conventions}.
The least specialized major mode is called @dfn{Fundamental mode},
which has no mode-specific definitions or variable settings.
@deffn Command fundamental-mode
This is the major mode command for Fundamental mode. Unlike other mode
commands, it does @emph{not} run any mode hooks (@pxref{Major Mode
Conventions}), since you are not supposed to customize this mode.
@end deffn
The easiest way to write a major mode is to use the macro
@code{define-derived-mode}, which sets up the new mode as a variant of
an existing major mode. @xref{Derived Modes}. We recommend using
@code{define-derived-mode} even if the new mode is not an obvious
derivative of another mode, as it automatically enforces many coding
conventions for you. @xref{Basic Major Modes}, for common modes to
derive from.
The standard GNU Emacs Lisp directory tree contains the code for
several major modes, in files such as @file{text-mode.el},
@file{texinfo.el}, @file{lisp-mode.el}, and @file{rmail.el}. You can
study these libraries to see how modes are written.
@defopt major-mode
The buffer-local value of this variable is a symbol naming the buffer's
current major mode. Its default value holds the default major mode for
new buffers. The standard default value is @code{fundamental-mode}.
If the default value is @code{nil}, then whenever Emacs creates a new
buffer via a command such as @kbd{C-x b} (@code{switch-to-buffer}), the
new buffer is put in the major mode of the previously current buffer.
As an exception, if the major mode of the previous buffer has a
@code{mode-class} symbol property with value @code{special}, the new
buffer is put in Fundamental mode (@pxref{Major Mode Conventions}).
@end defopt
@menu
* Major Mode Basics::
* Major Mode Conventions:: Coding conventions for keymaps, etc.
* Auto Major Mode:: How Emacs chooses the major mode automatically.
* Mode Help:: Finding out how to use a mode.
* Derived Modes:: Defining a new major mode based on another major
* Major Mode Conventions:: Coding conventions for keymaps, etc.
* Auto Major Mode:: How Emacs chooses the major mode automatically.
* Mode Help:: Finding out how to use a mode.
* Derived Modes:: Defining a new major mode based on another major
mode.
* Generic Modes:: Defining a simple major mode that supports
* Basic Major Modes:: Modes that other modes are often derived from.
* Generic Modes:: Defining a simple major mode that supports
comment syntax and Font Lock mode.
* Mode Hooks:: Hooks run at the end of major mode functions.
* Example Major Modes:: Text mode and Lisp modes.
* Mode Hooks:: Hooks run at the end of major mode commands.
* Example Major Modes:: Text mode and Lisp modes.
@end menu
@node Major Mode Basics
@subsection Major Mode Basics
@cindex Fundamental mode
The least specialized major mode is called @dfn{Fundamental mode}.
This mode has no mode-specific definitions or variable settings, so each
Emacs command behaves in its default manner, and each option is in its
default state. All other major modes redefine various keys and options.
For example, Lisp Interaction mode provides special key bindings for
@kbd{C-j} (@code{eval-print-last-sexp}), @key{TAB}
(@code{lisp-indent-line}), and other keys.
When you need to write several editing commands to help you perform a
specialized editing task, creating a new major mode is usually a good
idea. In practice, writing a major mode is easy (in contrast to
writing a minor mode, which is often difficult).
If the new mode is similar to an old one, it is often unwise to
modify the old one to serve two purposes, since it may become harder
to use and maintain. Instead, copy and rename an existing major mode
definition and alter the copy---or use the @code{define-derived-mode}
macro to define a @dfn{derived mode} (@pxref{Derived Modes}). For
example, Rmail Edit mode is a major mode that is very similar to Text
mode except that it provides two additional commands. Its definition
is distinct from that of Text mode, but uses that of Text mode.
Even if the new mode is not an obvious derivative of any other mode,
we recommend to use @code{define-derived-mode}, since it automatically
enforces the most important coding conventions for you.
For a very simple programming language major mode that handles
comments and fontification, you can use @code{define-generic-mode}.
@xref{Generic Modes}.
Rmail Edit mode offers an example of changing the major mode
temporarily for a buffer, so it can be edited in a different way (with
ordinary Emacs commands rather than Rmail commands). In such cases, the
temporary major mode usually provides a command to switch back to the
buffer's usual mode (Rmail mode, in this case). You might be tempted to
present the temporary redefinitions inside a recursive edit and restore
the usual ones when the user exits; but this is a bad idea because it
constrains the user's options when it is done in more than one buffer:
recursive edits must be exited most-recently-entered first. Using an
alternative major mode avoids this limitation. @xref{Recursive
Editing}.
The standard GNU Emacs Lisp library directory tree contains the code
for several major modes, in files such as @file{text-mode.el},
@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
@file{rmail.el}. They are found in various subdirectories of the
@file{lisp} directory. You can study these libraries to see how modes
are written. Text mode is perhaps the simplest major mode aside from
Fundamental mode. Rmail mode is a complicated and specialized mode.
@node Major Mode Conventions
@subsection Major Mode Conventions
@cindex major mode conventions
@cindex conventions for writing major modes
The code for existing major modes follows various coding conventions,
including conventions for local keymap and syntax table initialization,
global names, and hooks. Please follow these conventions when you
define a new major mode. (Fundamental mode is an exception to many
of these conventions, because its definition is to present the global
state of Emacs.)
The code for every major mode should follow various coding
conventions, including conventions for local keymap and syntax table
initialization, function and variable names, and hooks.
This list of conventions is only partial, because each major mode
should aim for consistency in general with other Emacs major modes.
This makes Emacs as a whole more coherent. It is impossible to list
If you use the @code{define-derived-mode} macro, it will take care of
many of these conventions automatically. @xref{Derived Modes}. Note
also that fundamental mode is an exception to many of these conventions,
because its definition is to present the global state of Emacs.
The following list of conventions is only partial. Each major mode
should aim for consistency in general with other Emacs major modes, as
this makes Emacs as a whole more coherent. It is impossible to list
here all the possible points where this issue might come up; if the
Emacs developers point out an area where your major mode deviates from
the usual conventions, please make it compatible.
@itemize @bullet
@item
Define a command whose name ends in @samp{-mode}, with no arguments,
that switches to the new mode in the current buffer. This command
should set up the keymap, syntax table, and buffer-local variables in an
existing buffer, without changing the buffer's contents.
Define a major mode command whose name ends in @samp{-mode}. When
called with no arguments, this command should switch to the new mode in
the current buffer by setting up the keymap, syntax table, and
buffer-local variables in an existing buffer. It should not change the
buffer's contents.
@item
Write a documentation string for this command that describes the
special commands available in this mode. @kbd{C-h m}
(@code{describe-mode}) in your mode will display this string.
Write a documentation string for this command that describes the special
commands available in this mode. @xref{Mode Help}.
The documentation string may include the special documentation
substrings, @samp{\[@var{command}]}, @samp{\@{@var{keymap}@}}, and
@samp{\<@var{keymap}>}, which enable the documentation to adapt
@samp{\<@var{keymap}>}, which allow the help display to adapt
automatically to the user's own key bindings. @xref{Keys in
Documentation}.
@ -527,10 +509,9 @@ mode when creating new buffers (@pxref{Auto Major Mode}), but with such
Dired, Rmail, and Buffer List use this feature.
The @code{define-derived-mode} macro automatically marks the derived
mode as special if the parent mode is special. The special mode
@code{special-mode} provides a convenient parent for other special
modes to inherit from; it sets @code{buffer-read-only} to @code{t},
and does little else.
mode as special if the parent mode is special. Special mode is a
convenient parent for such modes to inherit from; @xref{Basic Major
Modes}.
@item
If you want to make the new mode the default for files with certain
@ -564,16 +545,6 @@ Even if you never load the file more than once, someone else will.
automatically selects a major mode for the new buffer when a file is
visited. It also processes local variables specified in the file text.
@deffn Command fundamental-mode
Fundamental mode is a major mode that is not specialized for anything
in particular. Other major modes are defined in effect by comparison
with this one---their definitions say what to change, starting from
Fundamental mode. The @code{fundamental-mode} function does @emph{not}
run any mode hooks; you're not supposed to customize it. (If you want Emacs
to behave differently in Fundamental mode, change the @emph{global}
state of Emacs.)
@end deffn
@deffn Command normal-mode &optional find-file
This function establishes the proper major mode and buffer-local variable
bindings for the current buffer. First it calls @code{set-auto-mode}
@ -599,23 +570,22 @@ by the default value of @code{major-mode} (see below).
@cindex file mode specification error
@code{normal-mode} uses @code{condition-case} around the call to the
major mode function, so errors are caught and reported as a @samp{File
mode specification error}, followed by the original error message.
major mode command, so errors are caught and reported as a @samp{File
mode specification error}, followed by the original error message.
@end deffn
@defun set-auto-mode &optional keep-mode-if-same
@cindex visited file mode
This function selects the major mode that is appropriate for the
current buffer. It bases its decision (in order of precedence) on
the @w{@samp{-*-}} line, on any @samp{mode:} local variable near the
end of a file, on the @w{@samp{#!}} line (using
@code{interpreter-mode-alist}), on the text at the beginning of the
buffer (using @code{magic-mode-alist}), and finally on the visited
file name (using @code{auto-mode-alist}). @xref{Choosing Modes, , How
Major Modes are Chosen, emacs, The GNU Emacs Manual}.
If @code{enable-local-variables} is @code{nil}, @code{set-auto-mode}
does not check the @w{@samp{-*-}} line, or near the end of the file,
for any mode tag.
current buffer. It bases its decision (in order of precedence) on the
@w{@samp{-*-}} line, on any @samp{mode:} local variable near the end of
a file, on the @w{@samp{#!}} line (using @code{interpreter-mode-alist}),
on the text at the beginning of the buffer (using
@code{magic-mode-alist}), and finally on the visited file name (using
@code{auto-mode-alist}). @xref{Choosing Modes, , How Major Modes are
Chosen, emacs, The GNU Emacs Manual}. If @code{enable-local-variables}
is @code{nil}, @code{set-auto-mode} does not check the @w{@samp{-*-}}
line, or near the end of the file, for any mode tag.
If @var{keep-mode-if-same} is non-@code{nil}, this function does not
call the mode command if the buffer is already in the proper major
@ -624,21 +594,6 @@ mode. For instance, @code{set-visited-file-name} sets this to
have set.
@end defun
@defopt major-mode
The buffer-local value of this variable holds the major mode
currently active. The default value of this variable holds the
default major mode for new buffers. The standard default value is
@code{fundamental-mode}.
If the default value of @code{major-mode} is @code{nil}, Emacs uses
the (previously) current buffer's major mode as the default major mode
of a new buffer. However, if that major mode symbol has a @code{mode-class}
property with value @code{special}, then it is not used for new buffers;
Fundamental mode is used instead. The modes that have this property are
those such as Dired and Rmail that are useful only with text that has
been specially prepared.
@end defopt
@defun set-buffer-major-mode buffer
This function sets the major mode of @var{buffer} to the default value of
@code{major-mode}; if that is @code{nil}, it uses the
@ -745,18 +700,17 @@ init file.)
@cindex help for major mode
@cindex documentation for major mode
The @code{describe-mode} function is used to provide information
about major modes. It is normally called with @kbd{C-h m}. The
@code{describe-mode} function uses the value of @code{major-mode},
which is why every major mode function needs to set the
@code{major-mode} variable.
The @code{describe-mode} function is provides information about major
modes. It is normally bound to @kbd{C-h m}. It uses the value of the
variable @code{major-mode} (which is why every major mode command needs
to set this variable).
@deffn Command describe-mode
This function displays the documentation of the current major mode.
The @code{describe-mode} function calls the @code{documentation}
function using the value of @code{major-mode} as an argument. Thus, it
displays the documentation string of the major mode function.
displays the documentation string of the major mode command.
(@xref{Accessing Documentation}.)
@end deffn
@ -772,11 +726,12 @@ documentation of the major mode.
@subsection Defining Derived Modes
@cindex derived mode
The recommended way to define a new major mode is to derive it
from an existing one using @code{define-derived-mode}. If there is no
closely related mode, you can inherit from @code{text-mode},
@code{special-mode}, @code{prog-mode}, or in the worst case
@code{fundamental-mode}.
The recommended way to define a new major mode is to derive it from an
existing one using @code{define-derived-mode}. If there is no closely
related mode, you should inherit from either @code{text-mode},
@code{special-mode}, or @code{prog-mode}. @xref{Basic Major Modes}. If
none of these are suitable, you can inherit from @code{fundamental-mode}
(@pxref{Major Modes}).
@defmac define-derived-mode variant parent name docstring keyword-args@dots{} body@dots{}
This macro defines @var{variant} as a major mode command, using
@ -877,6 +832,64 @@ Do not write an @code{interactive} spec in the definition;
@code{define-derived-mode} does that automatically.
@end defmac
@defun derived-mode-p &rest modes
This function returns non-@code{nil} if the current major mode is
derived from any of the major modes given by the symbols @var{modes}.
@end defun
@node Basic Major Modes
@subsection Basic Major Modes
Apart from Fundamental mode, there are three major modes that other
major modes commonly derive from: Text mode, Prog mode, and Special
mode. While Text mode is useful in its own right (e.g. for editing
files ending in @file{.txt}), Prog mode and Special mode exist mainly to
let other modes derive from them.
@vindex prog-mode-hook
As far as possible, new major modes should be derived, either directly
or indirectly, from one of these three modes. One reason is that this
allows users to customize a single mode hook
(e.g. @code{prog-mode-hook}) for an entire family of relevant modes
(e.g. all programming language modes).
@deffn Command text-mode
Text mode is a major mode for editing human languages. It defines the
@samp{"} and @samp{\} characters as having punctuation syntax
(@pxref{Syntax Class Table}), and binds @kbd{M-@key{TAB}} to
@code{ispell-complete-word} (@pxref{Spelling,,, emacs, The GNU Emacs
Manual}).
An example of a major mode derived from Text mode is HTML mode.
@xref{HTML Mode,,SGML and HTML Modes, emacs, The GNU Emacs Manual}.
@end deffn
@deffn Command prog-mode
Prog mode is a basic major mode for buffers containing programming
language source code. Most of the programming language major modes
built into Emacs are derived from it.
Prog mode binds @code{parse-sexp-ignore-comments} to @code{t}
(@pxref{Motion via Parsing}) and @code{bidi-paragraph-direction} to
@code{left-to-right} (@pxref{Bidirectional Display}).
@end deffn
@deffn Command special-mode
Special mode is a basic major mode for buffers containing text that is
produced specially by Emacs, rather than from a file. Major modes
derived from Special mode are given a @code{mode-class} property of
@code{special} (@pxref{Major Mode Conventions}).
Special mode sets the buffer to read-only. Its keymap defines several
common bindings, including @kbd{q} for @code{quit-window}, @kbd{z} for
@code{kill-this-buffer}, and @kbd{g} for @code{revert-buffer}
(@pxref{Reverting}).
An example of a major mode derived from Special mode is Buffer Menu
mode, which is used by the @samp{*Buffer List*} buffer. @xref{List
Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}.
@end deffn
@node Generic Modes
@subsection Generic Modes
@cindex generic mode
@ -921,7 +934,7 @@ before it runs the mode hook variable @code{@var{mode}-hook}.
@node Mode Hooks
@subsection Mode Hooks
Every major mode function should finish by running its mode hook and
Every major mode command should finish by running its mode hook and
the mode-independent normal hook @code{after-change-major-mode-hook}.
It does this by calling @code{run-mode-hooks}. If the major mode is a
derived mode, that is if it calls another major mode (the parent mode)
@ -966,7 +979,7 @@ construct.
@defvar after-change-major-mode-hook
This is a normal hook run by @code{run-mode-hooks}. It is run at the
very end of every properly-written major mode function.
very end of every properly-written major mode command.
@end defvar
@node Example Major Modes
@ -1194,8 +1207,8 @@ And here is the code to set up the keymap for Lisp mode:
@end group
@end smallexample
Finally, here is the complete major mode function definition for
Lisp mode.
Finally, here is the complete major mode command definition for Lisp
mode.
@smallexample
@group
@ -2752,10 +2765,10 @@ highlighting patterns. See the variables
@code{c-font-lock-extra-types}, @code{c++-font-lock-extra-types},
and @code{java-font-lock-extra-types}, for example.
@strong{Warning:} major mode functions must not call
@strong{Warning:} major mode commands must not call
@code{font-lock-add-keywords} under any circumstances, either directly
or indirectly, except through their mode hooks. (Doing so would lead
to incorrect behavior for some minor modes.) They should set up their
or indirectly, except through their mode hooks. (Doing so would lead to
incorrect behavior for some minor modes.) They should set up their
rules for search-based fontification by setting
@code{font-lock-keywords}.
@end defun

7
doc/lispref/vol1.texi
View file

@ -786,8 +786,7 @@ Major and Minor Modes
* Major Modes:: Defining major modes.
* Minor Modes:: Defining minor modes.
* Mode Line Format:: Customizing the text that appears in the mode line.
* Imenu:: How a mode can provide a menu
of definitions in the buffer.
* Imenu:: Providing a menu of definitions made in a buffer.
* Font Lock Mode:: How modes can highlight text according to syntax.
* Desktop Save Mode:: How modes can have buffer state saved between
Emacs sessions.
@ -799,15 +798,15 @@ Hooks
Major Modes
* Major Mode Basics::
* Major Mode Conventions:: Coding conventions for keymaps, etc.
* Auto Major Mode:: How Emacs chooses the major mode automatically.
* Mode Help:: Finding out how to use a mode.
* Derived Modes:: Defining a new major mode based on another major
mode.
* Basic Major Modes:: Modes that other modes are often derived from.
* Generic Modes:: Defining a simple major mode that supports
comment syntax and Font Lock mode.
* Mode Hooks:: Hooks run at the end of major mode functions.
* Mode Hooks:: Hooks run at the end of major mode commands.
* Example Major Modes:: Text mode and Lisp modes.
Minor Modes

7
doc/lispref/vol2.texi
View file

@ -785,8 +785,7 @@ Major and Minor Modes
* Major Modes:: Defining major modes.
* Minor Modes:: Defining minor modes.
* Mode Line Format:: Customizing the text that appears in the mode line.
* Imenu:: How a mode can provide a menu
of definitions in the buffer.
* Imenu:: Providing a menu of definitions made in a buffer.
* Font Lock Mode:: How modes can highlight text according to syntax.
* Desktop Save Mode:: How modes can have buffer state saved between
Emacs sessions.
@ -798,15 +797,15 @@ Hooks
Major Modes
* Major Mode Basics::
* Major Mode Conventions:: Coding conventions for keymaps, etc.
* Auto Major Mode:: How Emacs chooses the major mode automatically.
* Mode Help:: Finding out how to use a mode.
* Derived Modes:: Defining a new major mode based on another major
mode.
* Basic Major Modes:: Modes that other modes are often derived from.
* Generic Modes:: Defining a simple major mode that supports
comment syntax and Font Lock mode.
* Mode Hooks:: Hooks run at the end of major mode functions.
* Mode Hooks:: Hooks run at the end of major mode commands.
* Example Major Modes:: Text mode and Lisp modes.
Minor Modes

6
etc/ChangeLog
View file

@ -1,3 +1,9 @@
2011-08-30 Paul Eggert <eggert@cs.ucla.edu>
* MACHINES: Remove obsolete info and update a bit (Bug#9404).
* PROBLEMS: Remove obsolete comment re Yellow Dog (Bug#9403).
2011-08-24 Steve Chapel <schapel@laptop.stevechapel.com> (tiny change)
* refcards/refcard.tex: Add a few more commands. (Bug#9343)

276
etc/MACHINES
View file

@ -24,227 +24,13 @@ file, and then edit the `configure' script to tell it which
configuration name(s) should select your new machine description and
system description files.
Some obsolete platforms are unsupported beginning with Emacs 23.1, see
Some obsolete platforms are unsupported beginning with Emacs 23.1. See
the list at the end of this file.
** Alpha (DEC) running GNU/Linux (alpha-dec-linux-gnu)
DEC C compiler version 5.9 (DEC C V5.9-005 on Digital UNIX V4.0f)
is reported to produce bogus binaries of Emacs 21.2 when the
command-line switches "-O4 -arch ev6 -tune ev6" are used. Using
just -O4 produces a good executable.
For 4.0 revision 564, and 4.0A and 4.0B, Emacs 20 seems to work
with no special configuration options. However, if you use GCC as
your compiler, you will need version 2.8.1 or later, as older
versions fail to build with a message "Invalid dimension for the
charset-ID 160".
** Apple Macintosh running Mac OS X
** Apple PowerPC Macintosh running GNU/Linux
** HP 9000 series 700 or 800 (Spectrum) (hppa1.0-hp-hpux or hppa1.1-hp-hpux)
Emacs 20 may work on HPUX 10. You need patch PHSS_6202 to install
the Xaw and Xmu libraries. On HPUX 10.20 you may need to compile with GCC;
when Emacs was compiled with HP's C compiler, HP92453-01 A.10.32.03,
the subprocess features failed to work.
If you turn on the DSUSP character (delayed suspend), Emacs 19.26
does not know how to turn it off on HPUX. You need to turn it off manually.
If you are running HP/UX release 8.0 or later, you need the optional
"C/ANSI C" software in order to build Emacs (older releases of HP/UX
do not require any special software). If the file "/etc/filesets/C"
exists on your machine, you have this software, otherwise you do not.
** IBM RS/6000 (rs6000-ibm-aix*)
Emacs 19.26 is believed to work; its pretest was tested.
Compiling with the system's `cc' and CFLAGS containing `-O5' might
fail because libXbsd isn't found. This is a compiler bug;
re-configure Emacs so that it isn't compiled with `-O5'.
On AIX 4.3.x and 4.4, compiling with /bin/c89 fails because it
treats certain warnings as errors. Use `cc' instead.
At last report, Emacs didn't run well on terminals. Informed
persons say that the tty VMIN and VTIME settings have been
corrupted; if you have a fix, please send it to us.
Compiling with -O using the IBM compiler has been known to make
Emacs work incorrectly. There are reports that IBM compiler versions
earlier than 1.03.00.02 fail even without -O.
As of 19.11, if you strip the Emacs executable, it ceases to work.
If anyone can fix the above problems, or confirm that they don't happen
with certain versions of various programs, we would appreciate it.
** IBM System/390 running GNU/Linux (s390-*-linux-gnu)
As of Emacs 21.2, a 31-bit only version is supported on this system.
** Intel 386 (i386-*-freebsd, i386-*-linux-gnu,
i386-*-cygwin, i386-*-msdos, i386-*-windowsnt.
i386 can be replaced with i486, i586, or i686)
In the above configurations, * means that the manufacturer's name
you specify does not matter, and you can use any name you like
(but it should not contain any dashes or stars).
Use i386-*-linux-gnu for GNU/Linux systems; Emacs runs as of version 19.26.
Use i386-*-cygwin for Cygwin; Emacs builds as of version 22.1, in both X11
and non-X11 modes. (The Cygwin site has source and binaries for 21.2.)
On GNU/Linux systems, Emacs 19.23 was said to work properly with libc
version 4.5.21, but not with 4.5.19.
On GNU/Linux, configure may fail to put these definitions in config.h:
#define HAVE_GETTIMEOFDAY
#define HAVE_MKDIR
#define HAVE_RMDIR
#define HAVE_XSCREENNUMBEROFSCREEN
To work around the problem, add those definitions by hand.
It is possible that this problem happens only with X11R6.
Newer system versions have fixed it.
On NetBSD and FreeBSD, at one time, it was necessary to use
GNU make, not the system's make. Assuming it's installed as gmake,
do `gmake install MAKE=gmake'. However, more recently it is
reported that using the system Make on NetBSD 1.3.1 works ok.
Note that use of Linux with GCC 2.4 and the DLL 4.4 libraries
requires the experimental "net 2" network patches (no relation to
Berkeley Net 2). There is a report that (some version of) Linux
requires including `/usr/src/linux/include/linux' in buffer.c
but no coherent explanation of why that might be so. If it is so,
in current versions of Linux, something else should probably be changed.
You may find that adding -I/usr/X/include or -I/usr/netinclude or both
to CFLAGS avoids compilation errors on certain systems.
Some versions convince sysdep.c to try to use `struct tchars'
but define `struct tc' instead; add `#define tchars tc'
to config.h to solve this problem.
** Iris 4D (mips-sgi-irix6.*)
Emacs 21.3 is reported to work on IRIX 6.5.x.
You can build a 64-bit executable (with larger maximum buffer size)
on Irix 6.5 by specifying the 64-bit ABI using the `-64' compiler
flag or otherwise (see cc(1)).
If compiling with GCC on Irix 6 yields an error "conflicting types
for `initstate'", install GCC 2.95 or a newer version, and this
problem should go away. It is possible that this problem results
from upgrading the operating system without reinstalling GCC; so you
could also try reinstalling the same version of GCC, and telling us
whether that fixes the problem.
** Sun 4 (sparc), Sun 386 (sparc-sun-solaris2.*,
i386-sun-solaris2.*, sparc*-*-linux-gnu)
To build a 32-bit Emacs (i.e. if you are having any sort of problem
bootstrapping a 64-bit version), you can use the Sun Studio compiler
and configure Emacs with:
env CC="cc -xarch=v7" CFLAGS='' ./configure # on SPARC systems
env CC="cc -xarch=386" CFLAGS='' ./configure # on x86 systems
On Solaris 2.10, it is also possible to use /usr/sfw/bin/gcc to build
a 32-bit version of Emacs. Just make sure you point ./configure to
the right compiler:
env CC='/usr/sfw/bin/gcc -m32' ./configure
To build a 64-bit Emacs (with larger maximum buffer size and
including large file support) on a Solaris system which supports
64-bit executables, use the Sun compiler, configuring something like
this (see the cc documentation for information on 64-bit
compilation):
env CC="cc -xarch=v9" CFLAGS='' ./configure # on SPARC systems
env CC="cc -xarch=amd64" CFLAGS='' ./configure # on x86 systems
As of version 2.95, GCC doesn't support the 64-bit ABI properly, but
later releases may.
Some versions of Solaris 8 have a bug in their XIM (X Input Method)
implementation which causes Emacs to dump core when one of several
frames is closed. To avoid this, either install patch 108773-12
(for Sparc) or 108874-12 (for x86), or configure Emacs with the
`--with-xim=no' switch (you can use Leim input methods instead).
On Solaris 2.7, building Emacs with WorkShop Compilers 5.0 98/12/15
C 5.0 failed, apparently with non-default CFLAGS, most probably due to
compiler bugs. Using Sun Solaris 2.7 Sun WorkShop 6 update 1 C
release was reported to work without problems. It worked OK on
another system with Solaris 8 using apparently the same 5.0 compiler
and the default CFLAGS.
Emacs 21.1 and 21.2 built with Sun's ProWorks PC3.0.1 compiler on
Intel/Solaris 8 was reported to abort and dump core during startup.
Using GCC or a newer SUN compiler (Sun WokShop 6 update 2 C 5.3
2001/05/15) solves the problem.
Emacs 20.5 and later work on SPARC GNU/Linux with the 32-bit ABI.
As of release 2.95, GCC doesn't work properly with the 64-bit ABI
(applicable on UltraSPARC), but that isn't the default mode.
There are reports that using SunSoft cc with -xO4 -xdepend produces
bad code for some part of Emacs.
Some people report that Emacs crashes immediately on startup when
used with a non-X terminal, but we think this is due to compiling
with GCC and failing to use GCC's "fixed" system header files.
Some Sun versions of X windows use the clipboard, not the selections,
for transferring text between clients. The Cut, Paste and Copy items
in the menu bar Edit menu work with the clipboard.
If you compile with Sun's ANSI compiler acc, you need additional options
when linking temacs, such as
/usr/lang/SC2.0.1/values-Xt.o -L/usr/lang/SC2.0.1/cg87 -L/usr/lang/SC2.0.1
(those should be added just before the libraries) and you need to
add -lansi just before -lc. The precise file names depend on the
compiler version, so we cannot easily arrange to supply them.
On Solaris 2, you need to install patch 100947-02 to fix a system bug.
Presumably this patch comes from Sun. You must alter the definition of
LD_SWITCH_SYSTEM if your X11 libraries are not in /usr/openwin/lib.
You must make sure that /usr/ucblib is not in your LD_LIBRARY_PATH.
On Solaris, do not use /usr/ucb/cc. Use /opt/SUNWspro/bin/cc. Make
sure that /usr/ccs/bin and /opt/SUNWspro/bin are in your PATH before
/usr/ucb. (Most free software packages have the same requirement on
Solaris.) With this compiler, use `/opt/SUNWspro/bin/cc -E' as the
preprocessor. If this inserts extra whitespace into its output (see
the PROBLEMS file) then add the option `-Xs'.
If you have trouble using open-network-stream, get the distribution
of `bind' (the BSD name-server), build libresolv.a, and link Emacs
with -lresolv, by editing LIBRESOLV in src/Makefile. This problem is
due to obsolete software in the nonshared standard library.
Note that Emacs on a Sun is not really as big as it looks. As
dumped, it includes around 200k of zeros between the original text
section and the original data section (now remapped as part of the
text). These are never swapped in.
** SuperH (sh[34]*-*-linux-gnu)
Emacs 23.0.60 was reported to work on GNU/Linux (October 2008).
Tested on a little-endian sh4 system (cpu type SH7751R) running
Gentoo Linux 2008.0.
* Here are notes about some of the systems supported:
** Linux (actually GNU/Linux)
** GNU/Linux
Most of the complete systems which use the Linux kernel are close
enough to the GNU system to be considered variant GNU systems. We
@ -263,31 +49,63 @@ the list at the end of this file.
people to write more free software. See the file LINUX-GNU in this
directory for more explanation.
*** 64-bit GNU/Linux
No special procedures should be needed to build a 64-bit Emacs on a
64-bit GNU/Linux system. To build a 32-bit Emacs, first ensure that
the necessary 32-bit system libraries and include files are
installed. Then use:
./configure CC='gcc -m32' --build=i386-linux-gnu \
--x-libraries=/usr/X11R6/lib
(using the location of the 32-bit X libraries on your system).
*** IBM System/390 running GNU/Linux (s390-*-linux-gnu)
As of Emacs 21.2, a 31-bit only version is supported on this system.
*** SuperH (sh[34]*-*-linux-gnu)
Emacs 23.0.60 was reported to work on GNU/Linux (October 2008).
This was tested on a little-endian sh4 system (cpu type SH7751R) running
Gentoo Linux 2008.0.
** Mac OS X
For installation instructions see the file nextstep/INSTALL.
** MSDOS
** Microsoft Windows
For installation on MSDOS, see the file msdos/INSTALL.
For installation instructions see the file nt/INSTALL.
** MS-DOS
For installation instructions see the file msdos/INSTALL.
See the "MS-DOS" chapter of the manual for information about using
Emacs on MSDOS.
Emacs on MS-DOS.
** MS-Windows NT/95/98/ME/2000
** Solaris
For installation on all versions of the MS-Windows platform, see the
file nt/INSTALL.
On Solaris it is also possible to use either GCC or Solaris Studio
to build Emacs, by pointing ./configure to the right compiler:
** X86_64 GNU/Linux
./configure CC='/usr/sfw/bin/gcc' # GCC
./configure CC='cc' # Solaris Studio
No special procedures should be needed to build a 64-bit Emacs. To
build a 32-bit Emacs, first ensure that the necessary 32-bit system
libraries and include files are installed. Then use:
On Solaris, do not use /usr/ucb/cc. Use /opt/SUNWspro/bin/cc. Make
sure that /usr/ccs/bin and /opt/SUNWspro/bin are in your PATH before
/usr/ucb. (Most free software packages have the same requirement on
Solaris.) With this compiler, use `/opt/SUNWspro/bin/cc -E' as the
preprocessor. If this inserts extra whitespace into its output (see
the PROBLEMS file) then add the option `-Xs'.
env CC="gcc -m32" ./configure --build=i386-linux-gnu \
--x-libraries=/usr/X11R6/lib
To build a 64-bit Emacs (with larger maximum buffer size) on a
Solaris system which supports 64-bit executables, specify the -m64
compiler option. For example:
(using the location of the 32-bit X libraries on your system).
./configure CC='/usr/sfw/bin/gcc -m64' # GCC
./configure CC='cc -m64' # Solaris Studio
* Obsolete platforms

15
etc/NEWS
View file

@ -43,10 +43,12 @@ to configure. Note that other libraries used by Emacs, RSVG and GConf,
also depend on Gtk+. You can disable them with --without-rsvg and
--without-gconf.
---
** There is a new configure option --enable-use-lisp-union-type.
This is only useful for Emacs developers to debug certain types of bugs.
This is not a new feature; only the configure flag is new.
---
** There is a new configure option --with-wide-int.
With it, Emacs integers typically have 62 bits, even on 32-bit machines.
@ -87,6 +89,7 @@ and also when HOME is set to C:\ by default.
* Changes in Emacs 24.1
+++
** auto-mode-case-fold is now enabled by default.
** Completion
@ -314,15 +317,12 @@ for `list-colors-display'.
** An Emacs Lisp package manager is now included.
This is a convenient way to download and install additional packages,
from a package repository at elpa.gnu.org.
from a package repository at http://elpa.gnu.org.
+++
*** `M-x list-packages' shows a list of packages, which can be
selected for installation.
+++
*** New command `describe-package', bound to `C-h P'.
+++
*** By default, all installed packages are loaded and activated
automatically when Emacs starts up. To disable this, set
@ -479,10 +479,8 @@ between applications.
+++
*** Support for X cut buffers has been removed.
*** Support for X clipboard managers has been added.
**** To inhibit use of the clipboard manager, set
`x-select-enable-clipboard-manager' to nil.
*** X clipboard managers are now supported.
To inhibit this, change `x-select-enable-clipboard-manager' to nil.
** New command `rectangle-number-lines', bound to `C-x r N', numbers
the lines in the current rectangle. With an prefix argument, this
@ -1032,6 +1030,7 @@ syntactic rules.
** frame-local variables cannot be let-bound any more.
+++
** prog-mode is a new major-mode meant to be the parent of programming mode.
The prog-mode-hook it defines can be used to enable features for
programming modes. For example:

37
etc/PROBLEMS
View file

@ -2648,43 +2648,6 @@ of PURESIZE in puresize.h.
But in some of the cases listed above, this problem is a consequence
of something else that is wrong. Be sure to check and fix the real problem.
*** Linux: Emacs crashes when dumping itself on Mac PPC running Yellow Dog GNU/Linux.
The crashes happen inside the function Fmake_symbol; here's a typical
C backtrace printed by GDB:
0x190c0c0 in Fmake_symbol ()
(gdb) where
#0 0x190c0c0 in Fmake_symbol ()
#1 0x1942ca4 in init_obarray ()
#2 0x18b3500 in main ()
#3 0x114371c in __libc_start_main (argc=5, argv=0x7ffff5b4, envp=0x7ffff5cc,
This could happen because GCC version 2.95 and later changed the base
of the load address to 0x10000000. Emacs needs to be told about this,
but we currently cannot do that automatically, because that breaks
other versions of GNU/Linux on the MacPPC. Until we find a way to
distinguish between the Yellow Dog and the other varieties of
GNU/Linux systems on the PPC, you will have to manually uncomment the
following section near the end of the file src/m/macppc.h in the Emacs
distribution:
#if 0 /* This breaks things on PPC GNU/Linux except for Yellowdog,
even with identical GCC, as, ld. Let's take it out until we
know what's really going on here. */
/* GCC 2.95 and newer on GNU/Linux PPC changed the load address to
0x10000000. */
#if defined __linux__
#if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ >= 95)
#define DATA_SEG_BITS 0x10000000
#endif
#endif
#endif /* 0 */
Remove the "#if 0" and "#endif" directives which surround this, save
the file, and then reconfigure and rebuild Emacs. The dumping process
should now succeed.
*** OpenBSD 4.0 macppc: Segfault during dumping.
The build aborts with signal 11 when the command `./temacs --batch

5
lisp/ChangeLog
View file

@ -1,3 +1,8 @@
2011-08-29 Juri Linkov <juri@jurta.org>
* isearch.el (isearch-done): Don't display message "Mark saved"
when arg `edit' is non-nil to prevent its flicker in the echo area.
2011-08-28 Chong Yidong <cyd@stupidchicken.com>
* emacs-lisp/package.el (package-menu-mark-delete): Allow marking

2
lisp/isearch.el
View file

@ -952,7 +952,7 @@ NOPUSH is t and EDIT is t."
(or (and transient-mark-mode mark-active)
(progn
(push-mark isearch-opoint t)
(or executing-kbd-macro (> (minibuffer-depth) 0)
(or executing-kbd-macro (> (minibuffer-depth) 0) edit
(message "Mark saved where search started")))))
(and (not edit) isearch-recursive-edit (exit-recursive-edit)))