* nsmenu.m (update_frame_tool_bar): Remove NSLog on invalid image.

[emacs.git] / doc / emacs / major.texi

@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001,
@c   2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Major Modes, Indentation, International, Top
@chapter Major Modes
@cindex major modes
@cindex mode, major
@kindex TAB @r{(and major modes)}
@kindex DEL @r{(and major modes)}
@kindex C-j @r{(and major modes)}

  Emacs provides many alternative @dfn{major modes}, each of which
customizes Emacs for editing text of a particular sort.  The major modes
are mutually exclusive, and each buffer has one major mode at any time.
The mode line normally shows the name of the current major mode, in
parentheses (@pxref{Mode Line}).

  The least specialized major mode is called @dfn{Fundamental mode}.
This mode has no mode-specific redefinitions or variable settings, so
that each Emacs command behaves in its most general manner, and each
user option variable is in its default state.  For editing text of a
specific type that Emacs knows about, such as Lisp code or English
text, you should switch to the appropriate major mode, such as Lisp
mode or Text mode.

  Selecting a major mode changes the meanings of a few keys to become
more specifically adapted to the language being edited.  The ones that
are changed frequently are @key{TAB}, @key{DEL}, and @kbd{C-j}.  The
prefix key @kbd{C-c} normally contains mode-specific commands.  In
addition, the commands which handle comments use the mode to determine
how comments are to be delimited.  Many major modes redefine the
syntactical properties of characters appearing in the buffer.
@xref{Syntax}.

  The major modes fall into three major groups.  The first group
contains modes for normal text, either plain or with mark-up.  It
includes Text mode, HTML mode, SGML mode, @TeX{} mode and Outline
mode.  The second group contains modes for specific programming
languages.  These include Lisp mode (which has several variants), C
mode, Fortran mode, and others.  The remaining major modes are not
intended for use on users' files; they are used in buffers created for
specific purposes by Emacs, such as Dired mode for buffers made by
Dired (@pxref{Dired}), Message mode for buffers made by @kbd{C-x m}
(@pxref{Sending Mail}), and Shell mode for buffers used for
communicating with an inferior shell process (@pxref{Interactive
Shell}).

  Most programming-language major modes specify that only blank lines
separate paragraphs.  This is to make the paragraph commands useful.
(@xref{Paragraphs}.)  They also cause Auto Fill mode to use the
definition of @key{TAB} to indent the new lines it creates.  This is
because most lines in a program are usually indented
(@pxref{Indentation}).

@menu
* Choosing Modes::     How major modes are specified or chosen.
@end menu

@node Choosing Modes,,Major Modes,Major Modes
@section How Major Modes are Chosen

@cindex choosing a major mode
  You can select a major mode explicitly for the current buffer, but
most of the time Emacs determines which mode to use based on the file
name or on special text in the file.

  To explicitly select a new major, you use an @kbd{M-x} command.
Take the name of a major mode and add @code{-mode} to get the name of
the command to select that mode.  Thus, you can enter Lisp mode by
executing @kbd{M-x lisp-mode}.

@vindex auto-mode-alist
  When you visit a file, Emacs usually chooses the right major mode
automatically.  Normally, it makes the choice based on the file
name---for example, files whose names end in @samp{.c} are normally
edited in C mode---but sometimes it chooses the major mode based on
the contents of the file.  Here is the exact procedure:

  First, Emacs checks whether the file contains a file-local variable
that specifies the major mode.  If so, it uses that major mode,
ignoring all other criteria.  @xref{File Variables}.  There are
several methods to specify a major mode using a file-local variable;
the simplest is to put the mode name in the first nonblank line,
preceded and followed by @samp{-*-}.  Other text may appear on the
line as well.  For example,

@example
; -*-Lisp-*-
@end example

@noindent
tells Emacs to use Lisp mode.  Note how the semicolon is used to make
Lisp treat this line as a comment.  Alternatively, you could write

@example
; -*- mode: Lisp;-*-
@end example

@noindent
The latter format allows you to specify local variables as well, like
this:

@example
; -*- mode: Lisp; tab-width: 4; -*-
@end example

@vindex interpreter-mode-alist
  Second, Emacs checks whether the file's contents begin with
@samp{#!}.  If so, that indicates that the file can serve as an
executable shell command, which works by running an interpreter named
on the file's first line (the rest of the file is used as input to the
interpreter).  Therefore, Emacs tries to use the interpreter name to
choose a mode.  For instance, a file that begins with
@samp{#!/usr/bin/perl} is opened in Perl mode.  The variable
@code{interpreter-mode-alist} specifies the correspondence between
interpreter program names and major modes.

  When the first line starts with @samp{#!}, you usually cannot use
the @samp{-*-} feature on the first line, because the system would get
confused when running the interpreter.  So Emacs looks for @samp{-*-}
on the second line in such files as well as on the first line.  The
same is true for man pages which start with the magic string
@samp{'\"} to specify a list of troff preprocessors.

@vindex magic-mode-alist
  Third, Emacs tries to determine the major mode by looking at the
text at the start of the buffer, based on the variable
@code{magic-mode-alist}.  By default, this variable is @code{nil} (an
empty list), so Emacs skips this step; however, you can customize it
in your init file (@pxref{Init File}).  The value should be a list of
elements of the form

@example
(@var{regexp} . @var{mode-function})
@end example

@noindent
where @var{regexp} is a regular expression (@pxref{Regexps}), and
@var{mode-function} is a Lisp function that toggles a major mode.  If
the text at the beginning of the file matches @var{regexp}, Emacs
chooses the major mode specified by @var{mode-function}.

Alternatively, an element of @code{magic-mode-alist} may have the form

@example
(@var{match-function} . @var{mode-function})
@end example

@noindent
where @var{match-function} is a Lisp function that is called at the
beginning of the buffer; if the function returns non-@code{nil}, Emacs
set the major mode wit @var{mode-function}.

  Fourth---if Emacs still hasn't found a suitable major mode---it
looks at the file's name.  The correspondence between file names and
major modes is controlled by the variable @code{auto-mode-alist}.  Its
value is a list in which each element has this form,

@example
(@var{regexp} . @var{mode-function})
@end example

@noindent
or this form,

@example
(@var{regexp} @var{mode-function} @var{flag})
@end example

@noindent
For example, one element normally found in the list has the form
@code{(@t{"\\.c\\'"} . c-mode)}, and it is responsible for selecting C
mode for files whose names end in @file{.c}.  (Note that @samp{\\} is
needed in Lisp syntax to include a @samp{\} in the string, which must
be used to suppress the special meaning of @samp{.} in regexps.)  If
the element has the form @code{(@var{regexp} @var{mode-function}
@var{flag})} and @var{flag} is non-@code{nil}, then after calling
@var{mode-function}, Emacs discards the suffix that matched
@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.

@vindex magic-fallback-mode-alist
  Finally, if Emacs @emph{still} hasn't found a major mode to use, it
compares the text at the start of the buffer to the variable
@code{magic-fallback-mode-alist}.  This variable works like
@code{magic-mode-alist}, described above, except that is consulted
only after @code{auto-mode-alist}.  By default,
@code{magic-fallback-mode-alist} contains forms that check for image
files, HTML/XML/SGML files, and Postscript files.

@vindex major-mode
  Once a major mode is chosen, Emacs sets the value of the variable
@code{major-mode} to the symbol for that major mode (e.g.,
@code{text-mode} for Text mode).  This is a per-buffer variable
(@pxref{Locals}); its buffer-local value is set automatically, and you
should not change it yourself.

  The default value of @code{major-mode} determines the major mode to
use for files that do not specify a major mode, and for new buffers
created with @kbd{C-x b}.  Normally, this default value is the symbol
@code{fundamental-mode}, which specifies Fundamental mode.  You can
change it via the Customization interface (@pxref{Easy
Customization}), or by adding a line like this to your init file
(@pxref{Init File}):

@smallexample
(setq-default major-mode 'text-mode)
@end smallexample

@noindent
If the default value of @code{major-mode} is @code{nil}, the major
mode is taken from the previously current buffer.

@findex normal-mode
  If you have changed the major mode of a buffer, you can return to
the major mode Emacs would have chosen automatically, by typing
@kbd{M-x normal-mode}.  This is the same function that
@code{find-file} calls to choose the major mode.  It also processes
the file's @samp{-*-} line or local variables list (if any).
@xref{File Variables}.

@vindex change-major-mode-with-file-name
  The commands @kbd{C-x C-w} and @code{set-visited-file-name} change to
a new major mode if the new file name implies a mode (@pxref{Saving}).
(@kbd{C-x C-s} does this too, if the buffer wasn't visiting a file.)
However, this does not happen if the buffer contents specify a major
mode, and certain ``special'' major modes do not allow the mode to
change.  You can turn off this mode-changing feature by setting
@code{change-major-mode-with-file-name} to @code{nil}.

@ignore
   arch-tag: f2558800-cf32-4839-8acb-7d3b4df2a155
@end ignore