Definition}). Therefore, the advice expressions can use the argument
variables in this list to access argument values.
-This argument list must be compatible with the argument list of the
-original function, so that it can handle the ways the function is
-actually called. If more than one piece of advice specifies an argument
-list, then the first one (the one with the smallest position) found in
-the list of all classes of advice is used.
+The argument list used in advice need not be the same as the argument
+list used in the original function, but must be compatible with it, so
+that it can handle the ways the function is actually called. If two
+pieces of advice for a function both specify an argument list, they must
+specify the same argument list.
@xref{Argument Access in Advice}, for more information about argument
-lists and advice.
+lists and advice, and a more flexible way for advice to access the
+arguments.
The remaining elements, @var{flags}, are symbols that specify further
information about how to use this piece of advice. Here are the valid
Windows cannot be made fixed-width or fixed-height;
Emacs will adjust the size of all windows when it needs to.
+@item
+The string used as the value of the @code{before-string} or
+@code{after-string} property must contain only characters that display
+as a single column---control characters, including tabs and newlines,
+will give strange results.
+
@item
The minibuffer prompt does not actually appear in content of the
minibuffer; it is displayed specially in the minibuffer window.
The following example shows how to change the @code{make-backup-files}
variable only in the Rmail buffers and not elsewhere. Setting it
@code{nil} stops Emacs from making backups of these files, which may
-save disk space. (You would put this code in your @file{.emacs} file.)
+save disk space. (You would put this code in your init file.)
@smallexample
@group
@code{t}, calling up the calendar automatically displays the diary
entries for the current date as well. The diary dates appear only if
the current date is visible. If you add both of the following lines to
-your @file{.emacs} file:@refill
+your init file:@refill
@example
(setq view-diary-entries-initially t)
The low-level mechanism for disabling a command is to put a
non-@code{nil} @code{disabled} property on the Lisp symbol for the
command. These properties are normally set up by the user's
-@file{.emacs} file with Lisp expressions such as this:
+init file (@pxref{Init File}) with Lisp expressions such as this:
@example
(put 'upcase-region 'disabled t)
@end example
@noindent
-For a few commands, these properties are present by default and may be
-removed by the @file{.emacs} file.
+For a few commands, these properties are present by default (you can
+remove them in your init file if you wish).
If the value of the @code{disabled} property is a string, the message
saying the command is disabled includes that string. For example:
@deffn Command enable-command command
Allow @var{command} to be executed without special confirmation from now
-on, and (if the user confirms) alter the user's @file{.emacs} file so
-that this will apply to future sessions.
+on, and (if the user confirms) alter the user's init file (@pxref{Init
+File}) so that this will apply to future sessions.
@end deffn
@deffn Command disable-command command
Require special confirmation to execute @var{command} from now on, and
-(if the user confirms) alter the user's @file{.emacs} file so that this
+(if the user confirms) alter the user's init file so that this
will apply to future sessions.
@end deffn
@code{debug-on-error} is @code{nil}.
@end defopt
- To debug an error that happens during loading of the @file{.emacs}
-file, use the option @samp{--debug-init}, which binds
-@code{debug-on-error} to @code{t} while loading @file{.emacs}, and
+ To debug an error that happens during loading of the init
+file, use the option @samp{--debug-init}. This binds
+@code{debug-on-error} to @code{t} while loading the init file., and
bypasses the @code{condition-case} which normally catches errors in the
init file.
- If your @file{.emacs} file sets @code{debug-on-error}, the effect may
-not last past the end of loading @file{.emacs}. (This is an undesirable
+ If your init file sets @code{debug-on-error}, the effect may
+not last past the end of loading the init file. (This is an undesirable
byproduct of the code that implements the @samp{--debug-init} command
-line option.) The best way to make @file{.emacs} set
+line option.) The best way to make the init file set
@code{debug-on-error} permanently is with @code{after-init-hook}, like
this:
* Overlay Arrow:: Display of an arrow to indicate position.
* Temporary Displays:: Displays that go away automatically.
* Overlays:: Use overlays to highlight parts of the buffer.
-* Width:: How wide is a character or string.
-* Faces:: A face defines a graphics appearance: font, color, etc.
+* Width:: How wide a character or string is on the screen.
+* Faces:: A face defines a graphics style for text characters:
+ font, colors, etc.
* Display Property:: Enabling special display features.
* Images:: Displaying images in Emacs buffers.
* Blinking:: How Emacs shows the matching open parenthesis.
value of @code{buffer-invisibility-spec}.
Controlling visibility with @code{buffer-invisibility-spec} is
-especially useful in a program to display the list of entries in a data
-base. It permits the implementation of convenient filtering commands to
-view just a part of the entries in the data base. Setting this variable
-is very fast, much faster than scanning all the text in the buffer
-looking for properties to change.
+especially useful in a program to display the list of entries in a
+database. It permits the implementation of convenient filtering
+commands to view just a part of the entries in the database. Setting
+this variable is very fast, much faster than scanning all the text in
+the buffer looking for properties to change.
@defvar buffer-invisibility-spec
This variable specifies which kinds of @code{invisible} properties
@defun remove-from-invisibility-spec element
@tindex remove-from-invisibility-spec
Remove the element @var{element} from @code{buffer-invisibility-spec}.
+This does nothing if @var{element} is not in the list.
@end defun
One convention about the use of @code{buffer-invisibility-spec} is
@itemize @bullet
@item
-If the value of @code{selective-display} is @code{t}, then any portion
-of a line that follows a control-m is not displayed. This is explicit
-selective display.
+If the value of @code{selective-display} is @code{t}, then the character
+control-m marks the start of invisible text; the control-m, and the rest
+of the line following it, are not displayed. This is explicit selective
+display.
@item
If the value of @code{selective-display} is a positive integer, then
font and which colors. @xref{Faces}, for more information.
In the simplest case, the value is a face name. It can also be a list;
-then each element can be any of these possibilities;
+then each element can be any of these possibilities:
@itemize @bullet
@item
@kindex help-echo @r{(text property)}
If an overlay has a string as its @code{help-echo} property, then when
you move the mouse onto the text in the overlay, Emacs displays that
-string in the echo area, or in the tooltip window. It is available
-starting in Emacs 21.
+string in the echo area, or in the tooltip window. This feature is
+available starting in Emacs 21.
@item modification-hooks
@kindex modification-hooks @r{(overlay property)}
@kindex before-string @r{(overlay property)}
This property's value is a string to add to the display at the beginning
of the overlay. The string does not appear in the buffer in any
-sense---only on the screen. The string should contain only characters
-that display as a single column---control characters, including tabs or
-newlines, will give strange results.
+sense---only on the screen.
@item after-string
@kindex after-string @r{(overlay property)}
This property's value is a string to add to the display at the end of
the overlay. The string does not appear in the buffer in any
-sense---only on the screen. The string should contain only characters
-that display as a single column---control characters, including tabs or
-newlines, will give strange results.
+sense---only on the screen.
@item evaporate
@kindex evaporate @r{(overlay property)}
and ceases to have any effect on display.
A deleted overlay is not permanently useless. You can give it
-a new buffer position by calling @code{move-overlay}.
+a position in a buffer again by calling @code{move-overlay}.
@end defun
@defun move-overlay overlay start end &optional buffer
This function moves @var{overlay} to @var{buffer}, and places its bounds
at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
must specify buffer positions; they may be integers or markers. If
-@var{buffer} is omitted, the overlay stays in the same buffer.
+@var{buffer} is omitted, @var{overlay} stays in the same buffer;
+if @var{overlay} was deleted, it goes into the current buffer.
The return value is @var{overlay}.
@item mode-line
@kindex mode-line @r{(face name)}
-This face is used for mode lines, and for menu bars
-when toolkit menus are not used.
+This face is used for mode lines, and for menu bars when toolkit menus
+are not used---but only if @code{mode-line-inverse-video} is
+non-@code{nil}.
@item modeline
@kindex modeline @r{(face name)}
@kindex header-line @r{(face name)}
This face is used for the header lines of windows that have them.
+@item menu
+This face controls the display of menus, both their colors and their
+font. (This works only on certain systems.)
+
@item fringe
@kindex fringe @r{(face name)}
This face controls the colors of window fringes, the thin areas on
@item trailing-whitespace
@kindex trailing-whitespace @r{(face name)}
-This face is used to display excess whitespace at the end of a line.
+This face is used to display excess whitespace at the end of a line,
+if @code{show-trailing-whitespace} is non-@code{nil}.
@end table
In contrast, these faces are provided to change the appearance of text
@item variable-patch
@kindex variable-patch @r{(face name)}
This face forces use of a particular variable-width font. It's
-reasonable to customize this to use a diffrent variable-width font, if
+reasonable to customize this to use a different variable-width font, if
you like, but you should not make it a fixed-width font.
@end table
+@defvar show-trailing-whitespace
+@tindex show-trailing-whitespace
+If this variable is non-@code{nil}, Emacs uses the
+@code{trailing-whitespace} face to display any spaces and tabs at the
+end of a line.
+@end defvar
+
@node Defining Faces
@subsection Defining Faces
@defmac defface face spec doc [keyword value]...
@tindex defface
-Declare @var{face} as a customizable face that defaults according to
-@var{spec}. Do not quote the symbol @var{face}. The argument @var{doc}
-specifies the face documentation.
+This declares @var{face} as a customizable face that defaults according
+to @var{spec}. You should not quote the symbol @var{face}. The
+argument @var{doc} specifies the face documentation. The keywords you
+can use in @code{defface} are the same ones that are meaningful in both
+@code{defgroup} and @code{defcustom} (@pxref{Common Keywords}).
When @code{defface} executes, it defines the face according to
@var{spec}, then uses any customizations that were read from the
-@file{.emacs} file to override that specification.
+init file (@pxref{Init File}) to override that specification.
The purpose of @var{spec} is to specify how the face should appear on
different kinds of terminals. It should be an alist whose elements have
-the form @code{(@var{display} @var{atts})}. The element's @sc{car},
-@var{display}, specifies a class of terminals. The @sc{cdr},
+the form @code{(@var{display} @var{atts})}. Each element's @sc{car},
+@var{display}, specifies a class of terminals. The element's second element,
@var{atts}, is a list of face attributes and their values; it specifies
what the face should look like on that kind of terminal. The possible
attributes are defined in the value of @code{custom-face-attributes}.
@end table
@end defmac
- Here's how the standard face @code{region} could be defined
-with @code{defface}:
+ Here's how the standard face @code{region} is defined:
@example
+@group
(defface region
- ((((class color) (background dark))
- (:background "blue"))
- (t (:background "gray")))
- "Used for displaying the region.")
+ `((((type tty) (class color))
+ (:background "blue" :foreground "white"))
+@end group
+ (((type tty) (class mono))
+ (:inverse-video t))
+ (((class color) (background dark))
+ (:background "blue"))
+ (((class color) (background light))
+ (:background "lightblue"))
+ (t (:background "gray")))
+@group
+ "Basic face for highlighting the region."
+ :group 'basic-faces)
+@end group
@end example
Internally, @code{defface} uses the symbol property
The effect of using a face is determined by a fixed set of @dfn{face
attributes}. This table lists all the face attributes, and what they
-mean. Note that in general, more than one face be specified for a given
-piece of text; when that happens, the attributes of all the faces are
-merged to specify how to display the text. @xref{Merging Faces}.
+mean. Note that in general, more than one face can be specified for a
+given piece of text; when that happens, the attributes of all the faces
+are merged to specify how to display the text. @xref{Merging Faces}.
In Emacs 21, any attribute in a face can have the value
@code{unspecified}. This means the face doesn't specify that attribute.
attribute, that means the next face gets a chance. However, the
@code{default} face must specify all attributes.
- Some of these font attributes are meaningful only on certain
-kinds of displays---if your display cannot handle a certain attribute,
-the attribute is ignored.
+ Some of these font attributes are meaningful only on certain kinds of
+displays---if your display cannot handle a certain attribute, the
+attribute is ignored. (The attributes @code{:family}, @code{:width},
+@code{:height}, @code{:weight}, and @code{:slant} correspond to parts of
+an X Logical Font Descriptor.)
@table @code
@item :family
Font family name, or fontset name (@pxref{Fontsets}). If you specify a
-font family name, the wild-cards @samp{*} and @samp{?} are allowed.
+font family name, the wild-card characters @samp{*} and @samp{?} are
+allowed.
@item :width
Relative proportionate width, also known as the character set width or
@code{extra-expanded}, or @code{ultra-expanded}.
@item :height
-Font height, an integer in units of 1/10pt.
+Font height, an integer in units of 1/10 point.
@item :weight
Font weight---a symbol from this series (from most dense to most faint):
@code{ultra-bold}, @code{extra-bold}, @code{bold}, @code{semi-bold},
@code{normal}, @code{semi-light}, @code{light}, @code{extra-light},
-@code{ultra-light}, or else @code{nil} meaning this attribute is not
-specified.
+or @code{ultra-light}.
On a text-only terminal, any weight greater than normal is displayed as
extra bright, and any weight less than normal is displayed as
half-bright (This is provided the terminal supports the feature.)
+On a text-only terminal, any weight greater than normal is displayed as
+extra bright, and any weight less than normal is displayed as
+half-bright (provided the terminal supports the feature).
+
@item :slant
Font slant---one of the symbols @code{italic}, @code{oblique}, @code{normal},
@code{reverse-italic}, or @code{reverse-oblique}.
value should be @code{t} (yes) or @code{nil} (no).
@item :stipple
-The background stipple, a bitmap name.
+The background stipple, a bitmap.
-The value can be a string; then is the name of a file of pixmap data.
-The file is found in the directories listed in the variable
-@code{x-bitmap-file-path}.
+The value can be a string; that should be the name of a file containing
+external-format X bitmap data. The file is found in the directories
+listed in the variable @code{x-bitmap-file-path}.
-Alternatively, the value can be a list of the form @code{(@var{width}
-@var{height} @var{data})}. Here, width and height are the size in
-pixels, and @var{data} is a string containing the raw bits of the
-bitmap.
+Alternatively, the value can specify the bitmap directly, with a list of
+the form @code{(@var{width} @var{height} @var{data})}. Here,
+@var{width} and @var{height} specify the size in pixels, and @var{data}
+is a string containing the raw bits of the bitmap, row by row. Each row
+occupies @math{(@var{width} + 7) / 8} consecutie bytes in the string
+(which should be a unibyte string for best results).
If the value is @code{nil}, that means use no stipple pattern.
@item :box
Whether or not a box should be drawn around characters, its color, the
-width of the box lines, and 3D appearance. See below for the possible
-values and what they mean.
+width of the box lines, and 3D appearance.
@end table
Here are the possible values of the @code{:box} attribute, and what
The attributes @code{:overline}, @code{:strike-through} and
@code{:box} are new in Emacs 21. The attributes @code{:family},
@code{:height}, @code{:width}, @code{:weight}, @code{:slant} are also
-new, previous versions had another way to specify some of the same
-information.
+new; previous versions used the following attributes, now semi-obsolete,
+to specify some of the same information:
@table @code
@item :font
-This attribute specified the font name.
+This attribute specifies the font name.
@item :bold
A non-@code{nil} value specifies a bold font.
@table @code
@item :font
-@code{:font} is not really a font attribute, but you can use it in
-@code{set-face-attribute} to specify several attributes at once. You
-specify an X font name as the value, and based on this font name, and
-it sets the attributes @code{:family}, @code{:width}, @code{:height},
-@code{:weight}, and @code{:slant} according to the font name.
+You can specify an X font name as the ``value'' of this ``attribute'';
+that sets the @code{:family}, @code{:width}, @code{:height},
+@code{:weight}, and @code{:slant} attributes according to the font name.
If the value is a pattern with wildcards, the first font that matches
the pattern is used to set these attributes.
for bitmap files, for the @code{:stipple} attribute.
@end defvar
+@defun pixmap-spec-p object
+This returns @code{t} if @var{object} is a valid bitmap
+specification, suitable for use with @code{:stipple}.
+It returns @code{nil} otherwise.
+@end defun
+
@node Attribute Functions
@subsection Face Attribute Functions
The extra arguments @var{arguments} specify the attributes to set, and
the values for them. They should consist of alternating attribute names
-(such as @code{:family} or @code{:underline} and corresponding values.
+(such as @code{:family} or @code{:underline}) and corresponding values.
Thus,
@example
@end example
@end defun
- For older Emacs versions, you can these functions to set
+ The functions above did not exist before Emacs 21. For compatibility
+with older Emacs versions, you can use the following functions to set
and examine the face attributes which existed in those versions.
@defun set-face-foreground face color &optional frame
These functions examine the attributes of a face. If you don't
specify @var{frame}, they refer to the default data for new frames.
+They return the symbol @code{unspecified} if the face doesn't define any
+value for that attribute.
@defun face-foreground face &optional frame
@defunx face-background face &optional frame
@defun face-differs-from-default-p face &optional frame
This returns @code{t} if the face @var{face} displays differently from
-the default face. A face is considered to be ``the same'' as the normal
-face if each attribute is either the same as that of the default face or
-@code{nil} (meaning to inherit from the default).
-@end defun
-
-@tindex frame-update-face-colors
-@defun frame-update-face-colors frame
-This function updates the way faces display on @var{frame}, for a change
-in @var{frame}'s foreground or background color.
+the default face. A face is considered to be ``the same'' as the
+default face if each attribute is either the same as that of the default
+face, or unspecified (meaning to inherit from the default).
@end defun
@node Auto Faces
@cindex display specification
@kindex display @r{(text property)}
- The @code{display} text property is used to insert images into text,
-and also control other aspects of how text displays. These features are
-available starting in Emacs 21. The value of the @code{display}
-property should be a display specification, or a list or vector
-containing several display specifications. The rest of this section
-describes several kinds of display specifications and what they mean.
+ The @code{display} text property (or overlay property) is used to
+insert images into text, and also control other aspects of how text
+displays. These features are available starting in Emacs 21. The value
+of the @code{display} property should be a display specification, or a
+list or vector containing several display specifications. The rest of
+this section describes several kinds of display specifications and what
+they mean.
@menu
-* Specified Space::
-* Other Display Specs::
-* Display Margins::
-* Conditional Display::
+* Specified Space:: Displaying one space with a specified width.
+* Other Display Specs:: Displaying an image; magnifying text; moving it
+ up or down on the page; adjusting the width
+ of spaces within text.
+* Display Margins:: Displaying text or images to the side of the main text.
+* Conditional Display:: Making any of the above features conditional
+ depending on some Lisp expression.
@end menu
@node Specified Space
@cindex variable-width spaces
To display a space of specified width and/or height, use a display
-specification of the form @code{(space @var{props})}, where @var{props}
-is a property list (see below). You can put this property on one or
-more consecutive characters; a space of the specified height and width
-is displayed in place of @emph{all} of those characters.
+specification of the form @code{(space . @var{props})}, where
+@var{props} is a property list (a list of alternating properties and
+values). You can put this property on one or more consecutive
+characters; a space of the specified height and width is displayed in
+place of @emph{all} of those characters. These are the properties you
+can use to specify the weight of the space:
@table @code
@item :width @var{width}
@item :align-to @var{hpos}
Specifies that the space should be wide enough to reach @var{hpos}. The
-value @var{hpos} is measured in units of the normal character width.
+value @var{hpos} is measured in units of the normal character width. It
+may be an interer or a floating point number.
@end table
Exactly one of the above properties should be used. You can also
@item :ascent @var{ascent}
Specifies that @var{ascent} percent of the height of the space should be
-considered as the ascent of the space. The value of @var{ascent} must
-be a non-negative number no greater than 100.
+considered as the ascent of the space---that is, the part above the
+baseline. The value of @var{ascent} must be a non-negative number no
+greater than 100.
@end table
You should not use both @code{:height} and @code{:relative-height}
that has the display specification.
@item (space-width @var{factor})
-This display specification affects all the spaces in the text that has
-the specification. It displays all of these spaces @var{factor} times
-as wide as normal. The element @var{factor} should be an integer or
-float.
+This display specification affects all the space characters within the
+text that has the specification. It displays all of these spaces
+@var{factor} times as wide as normal. The element @var{factor} should
+be an integer or float. Characters other than spaces are not affected
+at all; in particular, this has no effect on tab characters.
@item (height @var{height})
This display specification makes the text taller or shorter.
@table @asis
@item @code{(+ @var{n})}
This means to use a font that is @var{n} steps larger. A ``step'' is
-defined by the set of available fonts; each size for which a font is
-available counts as a step. @var{n} should be an integer.
+defined by the set of available fonts---specifically, those that match
+what was otherwise specified for this text, in all attributes except
+height. Each size for which a suitable font is available counts as
+another step. @var{n} should be an integer.
@item @code{(- @var{n})}
This means to use a font that is @var{n} steps smaller.
@end defvar
@menu
-* Image Descriptors::
-* XBM Images::
-* XPM Images::
-* GIF Images::
-* Postscript Images::
-* Other Image Types::
-* Defining Images::
-* Showing Images::
-* Image Cache::
+* Image Descriptors:: How to specify an image for use in @code{:display}.
+* XBM Images:: Special features for XBM format.
+* XPM Images:: Special features for XPM format.
+* GIF Images:: Special features for GIF format.
+* Postscript Images:: Special features for Postscript format.
+* Other Image Types:: Various other formats are supported.
+* Defining Images:: Convenient ways to define an image for later use.
+* Showing Images:: Convenient ways to display an image once it is defined.
+* Image Cache:: Internal mechanisms of image display.
@end menu
@node Image Descriptors
one should specify at least the @code{:type} property and the
@code{:file} property. Here is an example:
-@smallexample
-(defimage test-image ((:type xpm :file \"~/test1.xpm\")
- (:type xbm :file \"~/test1.xbm\")))"
-@end smallexample
+@example
+(defimage test-image
+ '((:type xpm :file "~/test1.xpm")
+ (:type xbm :file "~/test1.xbm")))
+@end example
@code{defimage} tests each argument, one by one, to see if it is
usable---that is, if the type is supported and the file exists. The
property yourself, but it is easier to use the functions in this
section.
-@defun insert-image image &optional area
+@defun insert-image image string &optional area
This function inserts @var{image} in the current buffer at point. The
value @var{image} should be an image descriptor; it could be a value
returned by @code{create-image}, or the value of a symbol defined with
-@code{defimage}.
+@code{defimage}. The argument @var{string} specifies the text to put in
+the buffer to hold the image.
The argument @var{area} specifies whether to put the image in a margin.
If it is @code{left-margin}, the image appears in the left margin;
@code{nil} or omitted, the image is displayed at point within the
buffer's text.
-Internally, this function inserts an @samp{x} in the buffer, and gives
-it a @code{display} property which specifies this image. @xref{Display
+Internally, this function inserts @var{string} in the buffer, and gives
+it a @code{display} property which specifies @var{image}. @xref{Display
Property}.
@end defun
-@defun put-image image pos &optional area
+@defun put-image image pos string &optional area
This function puts image @var{image} in front of @var{pos} in the
current buffer. The argument @var{pos} should be an integer or a
marker. It specifies the buffer position where the image should appear.
+The argument @var{string} specifies the text that should hold the image.
The argument @var{image} must be an image descriptor, perhaps returned
by @code{create-image} or stored by @code{defimage}.
@end defopt
@defopt mode-line-inverse-video
-This variable controls the use of inverse video for mode lines. If it
-is non-@code{nil}, then mode lines are displayed in inverse video.
-Otherwise, mode lines are displayed normally, just like text. The
-default is @code{t}.
-
-For window frames, this displays mode lines using the face named
-@code{modeline}, which is normally the inverse of the default face
-unless you change it.
+This variable controls the use of inverse video for mode lines and menu
+bars. If it is non-@code{nil}, then these lines are displayed in
+inverse video. Otherwise, they lines are displayed normally, just like
+other text. The default is @code{t}.
+
+For window frames, this feature actually applies the face named
+@code{mode-line}; that face is normally set up as the inverse of the
+default face, unless you change it.
@end defopt
@node Usual Display
@defopt tab-width
The value of this variable is the spacing between tab stops used for
-displaying tab characters in Emacs buffers. The default is 8. Note
-that this feature is completely independent of the user-settable tab
-stops used by the command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
+displaying tab characters in Emacs buffers. The value is in units of
+columns, and the default is 8. Note that this feature is completely
+independent of the user-settable tab stops used by the command
+@code{tab-to-tab-stop}. @xref{Indent Tabs}.
@end defopt
@node Display Tables
@defvar ring-bell-function
@tindex ring-bell-function
If this is non-@code{nil}, it specifies how Emacs should ``ring the
-bell.'' Its value should be a function of no arguments.
+bell.'' Its value should be a function of no arguments. If this is
+non-@code{nil}, it takes precedence over the @code{visible-bell}
+variable.
@end defvar
@node Window Systems
@defvar window-setup-hook
This variable is a normal hook which Emacs runs after handling the
initialization files. Emacs runs this hook after it has completed
-loading your @file{.emacs} file, the default initialization file (if
+loading your init file, the default initialization file (if
any), and the terminal-specific Lisp code, and running the hook
@code{term-setup-hook}.
@titlepage
@title GNU Emacs Lisp Reference Manual
-@subtitle For Emacs Version 20.4
+@subtitle For Emacs Version 21
@c The edition number appears in several places in this file
@c and also in the file intro.texi.
@subtitle Revision 2.6, September 1999
* Processes:: Running and communicating with subprocesses.
* System Interface:: Getting the user id, system type, environment
variables, and other such things.
-* Display:: Parameters controlling screen usage.
- The bell. Waiting for input.
+* Display:: Features for controlling the screen display.
* Calendar:: Customizing the calendar and diary.
Appendices
* Index:: Index including concepts, functions, variables,
and other terms.
-* New Symbols:: New functions and variables in Emacs 20.
+* New Symbols:: New functions and variables in Emacs 21.
--- The Detailed Node Listing ---
* Integer Type:: Numbers without fractional parts.
* Floating Point Type:: Numbers with fractional parts and with a large range.
* Character Type:: The representation of letters, numbers and
- control characters.
+ control characters.
* Sequence Type:: Both lists and arrays are classified as sequences.
* Cons Cell Type:: Cons cells, and lists (which are made from cons cells).
* Array Type:: Arrays include strings and vectors.
* Primitive Function Type:: A function written in C, callable from Lisp.
* Byte-Code Type:: A function written in Lisp, then compiled.
* Autoload Type:: A type used for automatically loading seldom-used
- functions.
+ functions.
List Type
or for use from the terminal.
* Active Keymaps:: Each buffer has a local keymap
to override the standard (global) bindings.
- Each minor mode can also override them.
+ Each minor mode can also override them.
* Key Lookup:: How extracting elements from keymaps works.
* Functions for Key Lookup:: How to request key lookup.
* Changing Key Bindings:: Redefining a key in a keymap.
@c REMOVE this: include non-hacker.texi
+@include anti.texi
@include tips.texi
@include internals.texi
@include errors.texi
@subsection Initial Frame Parameters
You can specify the parameters for the initial startup frame
-by setting @code{initial-frame-alist} in your @file{.emacs} file.
+by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
@defvar initial-frame-alist
This variable's value is an alist of parameter values used when creating
(@var{parameter} . @var{value})
@end example
-Emacs creates the initial frame before it reads your @file{~/.emacs}
+Emacs creates the initial frame before it reads your init
file. After reading that file, Emacs checks @code{initial-frame-alist},
and applies the parameter settings in the altered value to the already
created initial frame.
corresponding association is removed from the hash table.
The default for @var{weak} is @code{nil}, so that all keys and values
-referenced in the hash table are preserved from garbage collection.
+referenced in the hash table are preserved from garbage collection. If
+@var{weak} is @code{t}, neither keys nor values are protected (that is,
+both are weak).
@item :size @var{size}
This specifies a hint for how many associations you plan to store in the
it grows automatically. This value specifies how to make the hash table
larger, at that time.
-If @var{rehash-size} is an integer, it had better be positive, and the
-hash table grows by adding that much to the size. If @var{rehash-size}
-is a floating point number, it had better be greater than 1, and the
-hash table grows by multiplying the old size by that number.
+If @var{rehash-size} is an integer, it should be positive, and the hash
+table grows by adding that much to the nominal size. If
+@var{rehash-size} is a floating point number, it had better be greater
+than 1, and the hash table grows by multiplying the old size by that
+number.
The default value is 1.5.
@tindex hash-table-rehash-test
@defun hash-table-rehash-test table
-This returns the test @var{table} uses to hash and compare keys---see
+This returns the @var{test} value that was given when @var{table} was
+created, to specify how to hash and compare keys. See
@code{make-hash-table} (@pxref{Creating Hash}).
@end defun
the manual should be fixed. Please let us know.
@iftex
- As you use the manual, we ask that you mark pages with corrections so
-you can later look them up and send them in. If you think of a simple,
+ As you use this manual, we ask that you mark pages with corrections so
+you can later look them up and send them to us. If you think of a simple,
real-life example for a function or group of functions, please make an
effort to write it up and send it in. Please reference any comments to
the chapter name, section name, and function name, as appropriate, since
or group of functions, please make an effort to write it up and send it
in. Please reference any comments to the node name and function or
variable name, as appropriate. Also state the number of the edition
-which you are criticizing.
+you are criticizing.
@end ifinfo
Please mail comments and corrections to
group, in an effort extending over several years. Robert J. Chassell
helped to review and edit the manual, with the support of the Defense
Advanced Research Projects Agency, ARPA Order 6082, arranged by Warren
-A. Hunt, Jr. of Computational Logic, Inc.
+A. Hunt, Jr.@: of Computational Logic, Inc.
Corrections were supplied by Karl Berry, Jim Blandy, Bard Bloom,
Stephane Boucher, David Boyes, Alan Carroll, Richard Davis, Lawrence
Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland
McGrath, Skip Montanaro, John Gardiner Myers, Thomas A. Peterson,
Francesco Potorti, Friedrich Pukelsheim, Arnold D. Robbins, Raul
-Rockwell, Per Starback, Shinichirou Sugou, Kimmo Suominen, Edward Tharp,
+Rockwell, Per Starb@"ack, Shinichirou Sugou, Kimmo Suominen, Edward Tharp,
Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty,
Dale Worley, Rusty Wright, and David D. Zuhn.
Note that elements of @code{minor-mode-map-alist} do not have the same
structure as elements of @code{minor-mode-alist}. The map must be the
-@sc{cdr} of the element; a list with the map as the @sc{cadr} will not
-do. The @sc{cadr} can be either a keymap (a list) or a symbol
-whose function definition is a keymap.
+@sc{cdr} of the element; a list with the map as the second element will
+not do. The @sc{cdr} can be either a keymap (a list) or a symbol whose
+function definition is a keymap.
When more than one minor mode keymap is active, their order of priority
is the order of @code{minor-mode-map-alist}. But you should design
This section describes some convenient interactive interfaces for
changing key bindings. They work by calling @code{define-key}.
- People often use @code{global-set-key} in their @file{.emacs} file for
-simple customization. For example,
+ People often use @code{global-set-key} in their init files
+(@pxref{Init File}) for simple customization. For example,
@smallexample
(global-set-key "\C-x\C-\\" 'next-line)
@item :button (@var{type} . @var{selected})
This property provides a way to define radio buttons and toggle buttons.
-The @sc{car}, @var{type}, says which: is should be @code{:toggle} or
+The @sc{car}, @var{type}, says which: it should be @code{:toggle} or
@code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the
result of evaluating it says whether this button is currently selected.
EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
@end smallexample
- Here is an example of code you can place in a @file{.emacs} file to add
-several directories to the front of your default @code{load-path}:
+ Here is an example of code you can place in your init file (@pxref{Init
+File}) to add several directories to the front of your default
+@code{load-path}:
@smallexample
@group
maintain. Instead, copy and rename an existing major mode definition
and alter the copy---or define a @dfn{derived mode} (@pxref{Derived
Modes}). For example, Rmail Edit mode, which is in
-@file{emacs/lisp/rmailedit.el}, is a major mode that is very similar to
-Text mode except that it provides three additional commands. Its
-definition is distinct from that of Text mode, but was derived from it.
+@file{emacs/lisp/mail/rmailedit.el}, 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.
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
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}. You can study these libraries to see how modes are
-written. Text mode is perhaps the simplest major mode aside from
+@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.
@menu
would affect buffers that do not use this mode. It is undesirable for a
mode to have such global effects. @xref{Buffer-Local Variables}.
-It's OK to use @code{make-variable-buffer-local}, if you wish, for a
-variable used only within a single Lisp package.
+With rare exceptions, the only reasonable way to use use
+@code{make-variable-buffer-local} in a Lisp package is for a variable
+which is used only within that package. Using it on a variable used by
+other packages would interfere with them.
@item
@cindex mode hook
file that contains the mode definition. @xref{Auto Major Mode}.
@item
-@cindex @file{.emacs} customization
In the documentation, you should provide a sample @code{autoload} form
and an example of how to add to @code{auto-mode-alist}, that users can
-include in their @file{.emacs} files.
+include in their init files (@pxref{Init File}).
@item
@cindex mode loading
@end group
@group
-(defvar text-mode-map nil) ; @r{Create a mode-specific keymap.}
+(defvar text-mode-map nil ; @r{Create a mode-specific keymap.}
+ "Keymap for Text mode.
+Many other modes, such as Mail mode, Outline mode and Indented Text mode,
+inherit all the commands defined in this map.")
(if text-mode-map
() ; @r{Do not change the keymap if it is already set up.}
(setq text-mode-map (make-sparse-keymap))
+ (define-key text-mode-map "\e\t" 'ispell-complete-word)
(define-key text-mode-map "\t" 'indent-relative)
(define-key text-mode-map "\es" 'center-line)
(define-key text-mode-map "\eS" 'center-paragraph))
(setq paragraph-start (concat "[ \t]*$\\|" page-delimiter))
(make-local-variable 'paragraph-separate)
(setq paragraph-separate paragraph-start)
+ (make-local-variable 'indent-line-function)
+ (setq indent-line-function 'indent-relative-maybe)
@end group
@group
(setq mode-name "Text")
@group
(make-local-variable 'comment-indent-function)
(setq comment-indent-function 'lisp-comment-indent))
+ @dots{}
@end group
@end smallexample
Here is an example of how to prepend several pattern pairs to
@code{auto-mode-alist}. (You might use this sort of expression in your
-@file{.emacs} file.)
+init file.)
@smallexample
@group
@smallexample
@group
-(or (assq 'leif-mode minor-mode-alist)
- (setq minor-mode-alist
- (cons '(leif-mode " Leif") minor-mode-alist)))
+(unless (assq 'leif-mode minor-mode-alist)
+ (setq minor-mode-alist
+ (cons '(leif-mode " Leif") minor-mode-alist)))
@end group
@end smallexample
-@end itemize
- You can also use @code{add-to-list} to add an element to this list
-just once (@pxref{Setting Variables}).
+@noindent
+or like this, using @code{add-to-list} (@pxref{Setting Variables}):
+
+@smallexample
+@group
+(add-to-list 'minor-mode-alist '(leif-mode " Leif"))
+@end group
+@end smallexample
+@end itemize
Global minor modes distributed with Emacs should if possible support
enabling and disabling via Custom (@pxref{Customization}). To do this,
@cindex mode line construct
The mode line contents are controlled by a data structure of lists,
-strings, symbols, and numbers kept in the buffer-local variable
-@code{mode-line-format}. The data structure is called a @dfn{mode line
-construct}, and it is built in recursive fashion out of simpler mode line
-constructs. The same data structure is used for constructing
-frame titles (@pxref{Frame Titles}).
+strings, symbols, and numbers kept in buffer-local variables. The data
+structure is called a @dfn{mode line construct}, and it is built in
+recursive fashion out of simpler mode line constructs. The same data
+structure is used for constructing frame titles (@pxref{Frame Titles})
+and header lines (@pxref{Header Lines}).
@defvar mode-line-format
The value of this variable is a mode line construct with overall
displayed immediately following the major mode name, with no intervening
space. For example, its value in the @samp{*shell*} buffer is
@code{(":%s")}, which allows the shell to display its status along
-with the major mode as: @samp{(Shell:@: run)}. Normally this variable
+with the major mode as: @samp{(Shell:run)}. Normally this variable
is @code{nil}.
@end defvar
+ Some variables are used by @code{minor-mode-alist} to display
+a string for various minor modes when enabled. This is a typical
+example:
+
+@defvar vc-mode
+The variable @code{vc-mode}, buffer-local in each buffer, records
+whether the buffer's visited file is maintained with version control,
+and, if so, which kind. Its value is a string that appears in the mode
+line, or @code{nil} for no version control.
+@end defvar
+
+ The variable @code{default-mode-line-format} is where
+@code{mode-line-format} usually gets its value:
+
@defvar default-mode-line-format
This variable holds the default @code{mode-line-format} for buffers
that do not override it. This is the same as @code{(default-value
global-mode-string
@group
" %[("
+ ;; @r{@code{mode-line-mode-name} is a function}
+ ;; @r{that copies the mode name and adds text
+ ;; @r{properties to make it mouse-sensitive.}
(:eval (mode-line-mode-name))
mode-line-process
minor-mode-alist
@end example
@end defvar
-@defvar vc-mode
-The variable @code{vc-mode}, buffer-local in each buffer, records
-whether the buffer's visited file is maintained with version control,
-and, if so, which kind. Its value is @code{nil} for no version control,
-or a string that appears in the mode line.
-@end defvar
-
@node %-Constructs
@subsection @code{%}-Constructs in the Mode Line
The current buffer name, obtained with the @code{buffer-name} function.
@xref{Buffer Names}.
+@item %c
+The current column number of point.
+
@item %f
The visited file name, obtained with the @code{buffer-file-name}
function. @xref{Buffer File Name}.
The title (only on a window system) or the name of the selected frame.
@xref{Window Frame Parameters}.
-@item %c
-The current column number of point.
-
@item %l
The current line number of point, counting within the accessible portion
of the buffer.
+@item %n
+@samp{Narrow} when narrowing is in effect; nothing otherwise (see
+@code{narrow-to-region} in @ref{Narrowing}).
+
+@item %p
+The percentage of the buffer text above the @strong{top} of window, or
+@samp{Top}, @samp{Bottom} or @samp{All}. Note that the default
+mode-line specification truncates this to three characters.
+
+@item %P
+The percentage of the buffer text that is above the @strong{bottom} of
+the window (which includes the text visible in the window, as well as
+the text above the top), plus @samp{Top} if the top of the buffer is
+visible on screen; or @samp{Bottom} or @samp{All}.
+
+@item %s
+The status of the subprocess belonging to the current buffer, obtained with
+@code{process-status}. @xref{Process Information}.
+
+@item %t
+Whether the visited file is a text file or a binary file. This is a
+meaningful distinction only on certain operating systems (@pxref{MS-DOS
+File Types}).
+
@item %*
@samp{%} if the buffer is read only (see @code{buffer-read-only}); @*
@samp{*} if the buffer is modified (see @code{buffer-modified-p}); @*
@item %&
@samp{*} if the buffer is modified, and @samp{-} otherwise.
-@item %s
-The status of the subprocess belonging to the current buffer, obtained with
-@code{process-status}. @xref{Process Information}.
-
-@item %t
-Whether the visited file is a text file or a binary file. (This is a
-meaningful distinction only on certain operating systems.)
-
-@item %p
-The percentage of the buffer text above the @strong{top} of window, or
-@samp{Top}, @samp{Bottom} or @samp{All}.
-
-@item %P
-The percentage of the buffer text that is above the @strong{bottom} of
-the window (which includes the text visible in the window, as well as
-the text above the top), plus @samp{Top} if the top of the buffer is
-visible on screen; or @samp{Bottom} or @samp{All}.
-
-@item %n
-@samp{Narrow} when narrowing is in effect; nothing otherwise (see
-@code{narrow-to-region} in @ref{Narrowing}).
-
@item %[
An indication of the depth of recursive editing levels (not counting
minibuffer levels): one @samp{[} for each editing level.
One @samp{]} for each recursive editing level (not counting minibuffer
levels).
+@item %-
+Dashes sufficient to fill the remainder of the mode line.
+
@item %%
The character @samp{%}---this is how to include a literal @samp{%} in a
string in which @code{%}-constructs are allowed.
-
-@item %-
-Dashes sufficient to fill the remainder of the mode line.
@end table
The following two @code{%}-constructs are still supported, but they are
You use the @code{local-map} property to specify a keymap. Like any
keymap, it can bind character keys and function keys; but that has no
-effect, since is impossible to move point into the mode line, This
+effect, since it is impossible to move point into the mode line. This
keymap can only take real effect for mouse clicks.
@node Header Lines
section in the buffer, from a menu which lists all of them, to go
directly to that location in the buffer. Imenu works by constructing a
buffer index which lists the names and buffer positions of the
-definitions, or portions of the buffer, so the user can pick one of them
-to move to. This section explains how to customize Imenu for a major
-mode.
+definitions, or other named portions of the buffer; then the user can
+choose one of them and move point to it. This section explains how to
+customize how Imenu finds the definitions or buffer portions for a
+particular major mode.
The usual and simplest way is to set the variable
@code{imenu-generic-expression}:
The second item in the list, @var{regexp}, is a regular expression
(@pxref{Regular Expressions}); anything in the buffer that it matches is
-considered a definition, to mention in the buffer index. The third
-item, @var{subexp}, indicates which subexpression in @var{regexp}
+considered a definition, something to mention in the buffer index. The
+third item, @var{subexp}, indicates which subexpression in @var{regexp}
matches the definition's name.
An element can also look like this:
@end example
Each match for this element creates a special index item which, if
-selected by the user, calls @var{function} with arguments
-@var{item-name}, the buffer position, and @var{arguments}.
+selected by the user, calls @var{function} with arguments consisting of
+the item name, the buffer position, and @var{arguments}.
For Emacs Lisp mode, @var{pattern} could look like this:
@code{imenu-extract-index-name-function}:
@defvar imenu-prev-index-position-function
-If this variable is non-@code{nil}, its value should be a function for
-finding the next definition to mention in the buffer index, moving
-backwards in the file.
-
-The function should leave point at the place to be connected to the
-index item; it should return @code{nil} if it doesn't find another item.
+If this variable is non-@code{nil}, its value should be a funtion that
+finds the next ``definition'' to put in the buffer index, scanning
+backward in the buffer from point. It should return @code{nil} if it
+doesn't find another ``definition'' before point. Otherwise it shuould
+leave point at the place it finds a ``definition,'' and return any
+non-@code{nil} value.
Setting this variable makes it buffer-local in the current buffer.
@end defvar
@end defvar
The last way to customize Imenu for a major mode is to set the
-variables @code{imenu-create-index-function}:
+variable @code{imenu-create-index-function}:
@defvar imenu-create-index-function
This variable specifies the function to use for creating a buffer index.
@dfn{Font Lock mode} is a feature that automatically attaches
@code{face} properties to certain parts of the buffer based on their
syntactic role. How it parses the buffer depends on the major mode;
-most major modes define syntactic criteria for which faces to use, in
+most major modes define syntactic criteria for which faces to use in
which contexts. This section explains how to customize Font Lock for a
-particular language---in other words, for a particular major mode.
+particular major mode.
Font Lock mode finds text to highlight in two ways: through syntactic
parsing based on the syntax table, and through searching (usually for
regular expressions). Syntactic fontification happens first; it finds
comments and string constants, and highlights them using
@code{font-lock-comment-face} and @code{font-lock-string-face}
-(@pxref{Faces for Font Lock}); search-based fontification follows.
+(@pxref{Faces for Font Lock}). Search-based fontification follows.
@menu
* Font Lock Basics::
The first element, @var{keywords}, indirectly specifies the value of
@code{font-lock-keywords}. It can be a symbol, a variable whose value
-is list to use for @code{font-lock-keywords}. It can also be a list of
+is the list to use for @code{font-lock-keywords}. It can also be a list of
several such symbols, one for each possible level of fontification. The
first symbol specifies how to do level 1 fontification, the second
symbol how to do level 2, and so on.
The fifth element, @var{syntax-begin}, specifies the value of
@code{font-lock-beginning-of-syntax-function} (see below).
-Any further elements @var{other-vars} are of the form
-@code{(@var{variable} . @var{value})}. This kind of element means to
-make @var{variable} buffer-local and then set it to @var{value}. This
-is used to set other variables that affect fontification.
+All the remaining elements (if any) are collectively called
+@var{other-vars}. Each of these elements should have the form
+@code{(@var{variable} . @var{value})}---which means, make @var{variable}
+buffer-local and then set it to @var{value}. You can use these
+@var{other-vars} to set other variables that affect fontification,
+aside from those you can control with the first five elements.
@end defvar
@node Search-based Fontification
A @dfn{hook} is a variable where you can store a function or functions
to be called on a particular occasion by an existing program. Emacs
provides hooks for the sake of customization. Most often, hooks are set
-up in the @file{.emacs} file, but Lisp programs can set them also.
+up in the init file (@pxref{Init File}), but Lisp programs can set them also.
@xref{Standard Hooks}, for a list of standard hook variables.
@cindex normal hook
@cindex abnormal hook
If the hook variable's name does not end with @samp{-hook}, that
-indicates it is probably an @dfn{abnormal hook}; you should look at its
+indicates it is probably an @dfn{abnormal hook}. Then you should look at its
documentation to see how to use the hook properly.
If the variable's name ends in @samp{-functions} or @samp{-hooks},
run particular hooks. This function calls the hook functions that have
been added with @code{add-hook}.
-@defun run-hooks &rest hookvar
+@defun run-hooks &rest hookvars
This function takes one or more hook variable names as arguments, and
-runs each hook in turn. Each @var{hookvar} argument should be a symbol
-that is a hook variable. These arguments are processed in the order
-specified.
+runs each hook in turn. Each argument should be a symbol that is a hook
+variable. These arguments are processed in the order specified.
If a hook variable has a non-@code{nil} value, that value may be a
function or a list of functions. If the value is a function (either a
to the hook functions, and stops as soon as any hook function fails. It
calls each of the hook functions, passing each of them the arguments
@var{args}, until some hook function returns @code{nil}. Then it stops,
-and returns @code{nil} if some hook function did, and otherwise
-returns a non-@code{nil} value.
+and returns @code{nil} if some hook function returned @code{nil}.
+Otherwise it returns a non-@code{nil} value.
@end defun
@defun run-hook-with-args-until-success hook &rest args
buffer-local and global hook functions, and @code{run-hooks} runs all of
them.
-This function works by making @code{t} an element of the buffer-local
-value. That serves as a flag to use the hook functions in the default
-value of the hook variable as well as those in the buffer-local value.
+This function works by adding @code{t} as an element of the buffer-local
+value. That serves as a flag to use the hook functions listed in the default
+value of the hook variable, as well as those listed in the buffer-local value.
Since @code{run-hooks} understands this flag, @code{make-local-hook}
works with all normal hooks. It works for only some non-normal
hooks---those whose callers have been updated to understand this meaning
@cindex @file{site-start.el}
@item
-It loads the file @file{~/.emacs}, unless @samp{-q} or @samp{-batch} was
-specified on the command line. The @samp{-u} option can specify another
-user whose home directory should be used instead of @file{~}.
+It loads your init file (usually @file{~/.emacs}), unless @samp{-q} or
+@samp{-batch} was specified on the command line. The @samp{-u} option
+can specify another user whose home directory should be used instead of
+@file{~}.
@item
It loads the library @file{default}, unless @code{inhibit-default-init}
@defopt inhibit-startup-echo-area-message
This variable controls the display of the startup echo area message.
You can suppress the startup echo area message by adding text with this
-form to your @file{.emacs} file:
+form to your init file:
@example
(setq inhibit-startup-echo-area-message
"@var{your-login-name}")
@end example
-Emacs explicitly checks for an expression as shown above in your
-@file{.emacs} file; your login name must appear in the expression as a
-Lisp string constant. Other methods of setting
+Emacs explicitly checks for an expression as shown above in your init
+file; your login name must appear in the expression as a Lisp string
+constant. Other methods of setting
@code{inhibit-startup-echo-area-message} to the same value do not
inhibit the startup message.
This way, you can easily inhibit the message for yourself if you wish,
-but thoughtless copying of your @file{.emacs} file will not inhibit the
-message for someone else.
+but thoughtless copying of your init file will not inhibit the message
+for someone else.
@end defopt
@node Init File
-@subsection The Init File: @file{.emacs}
+@subsection The Init File, @file{.emacs}
@cindex init file
@cindex @file{.emacs}
- When you start Emacs, it normally attempts to load the file
-@file{.emacs} from your home directory. This file is called your
-@dfn{init file}. If it exists, it must contain Lisp code. The
-command-line switches @samp{-q} and @samp{-u} affect the use of the init
-file; @samp{-q} says not to load an init file, and @samp{-u} says to
-load a specified user's init file instead of yours. @xref{Entering
-Emacs,,, emacs, The GNU Emacs Manual}.
+ When you start Emacs, it normally attempts to load your @dfn{init
+file}, a file in your home directory. Its normal name is @file{.emacs},
+but you can alternatively call it @file{.emacs.el}, which enables you to
+byte-compile it (@pxref{Byte Compilation}); then the actual file loaded
+will be @file{.emacs.elc}.
+
+ The command-line switches @samp{-q} and @samp{-u} control whether and
+where to find the init file; @samp{-q} says not to load an init file,
+and @samp{-u @var{user}} says to load @var{user}'s init file instead of
+yours. @xref{Entering Emacs,,, emacs, The GNU Emacs Manual}. If
+neither option is specified, Emacs uses the @code{LOGNAME} environment
+variable, or the @code{USER} (most systems) or @code{USERNAME} (MS
+systems) variable, to find your home directory and thus your init file;
+this way, even if you have su'd, Emacs still loads your own init file.
+If those environment variables are absent, though, Emacs uses your
+user-id to find your home directory.
@cindex default init file
A site may have a @dfn{default init file}, which is the library named
Emacs.
@end defvar
- If there is a great deal of code in your @file{.emacs} file, you
-can make it load faster by renaming it to @file{.emacs.el}
-and then byte-compiling it (@pxref{Byte Compilation}).
-
@xref{Init File Examples,,, emacs, The GNU Emacs Manual}, for
examples of how to make various commonly desired customizations in your
@file{.emacs} file.
@code{(getenv "TERM")} to find the full name of the terminal
type.@refill
- Your @file{.emacs} file can prevent the loading of the
+ Your init file can prevent the loading of the
terminal-specific library by setting the variable
@code{term-file-prefix} to @code{nil}. This feature is useful when
experimenting with your own peculiar customizations.
terminal-specific library by setting the variable
@code{term-setup-hook}. This is a normal hook which Emacs runs using
@code{run-hooks} at the end of Emacs initialization, after loading both
-your @file{.emacs} file and any terminal-specific libraries. You can
+your init file and any terminal-specific libraries. You can
use this variable to define initializations for terminals that do not
have their own libraries. @xref{Hooks}.
@noindent
You may set the @code{term-file-prefix} variable to @code{nil} in your
-@file{.emacs} file if you do not wish to load the
+init file if you do not wish to load the
terminal-initialization file. To do this, put the following in
-your @file{.emacs} file: @code{(setq term-file-prefix nil)}.
+your init file: @code{(setq term-file-prefix nil)}.
On MS-DOS, if the environment variable @code{TERM} is not set, Emacs
uses @samp{internal} as the terminal type.
@defvar term-setup-hook
This variable is a normal hook that Emacs runs after loading your
-@file{.emacs} file, the default initialization file (if any) and the
+init file, the default initialization file (if any) and the
terminal-specific Lisp file.
You can use @code{term-setup-hook} to override the definitions made by a
@defun command-line
This function parses the command line that Emacs was called with,
-processes it, loads the user's @file{.emacs} file and displays the
+processes it, loads the user's init file and displays the
startup messages.
@end defun
This holds the nominal email address of the user who is using Emacs.
Emacs normally sets this variable to a default value after reading your
init files, but not if you have already set it. So you can set the
-variable to some other value in your @file{~/.emacs} file if you do not
+variable to some other value in your init file if you do not
want to use the default value.
@end defvar
@end deffn
You can use the function @code{enable-flow-control-on} in your
-@file{.emacs} file to enable flow control automatically on certain
+init file to enable flow control automatically on certain
terminal types.
@defun enable-flow-control-on &rest termtypes
text produces a list (but not the same list) with elements @code{a}
and @code{b}.
- However, these two operations are not precisely inverses. There are
-three kinds of exceptions:
+ However, these two operations are not precisely inverse to each other.
+There are three kinds of exceptions:
@itemize @bullet
@item
uninterned symbols print with the prefix @samp{#:}, which tells the Lisp
reader to produce an uninterned symbol.
@end defvar
-
-@tindex print-continuous-numbering
-@defvar print-continuous-numbering
-To print several objects with shared structure in common, you should
-bind @code{print-continuous-numbering} to @code{t} around them all.
-That tells @code{print} not to reinitialize @code{print-number-table}
-each time.
-@end defvar
-
-@tindex print-number-table
-@defvar print-number-table
-This variable holds the table used as the basis of outputting
-@samp{#@var{n}=} and @samp{#@var{n}#} constructs for circular and shared
-structure. When you want to print several objects with shared structure
-in common, you should bind @code{print-number-table} to @code{nil}
-around them all.
-@end defvar
-
- Here is an example of printing two objects with a common
-set of shared substructure:
-
-@example
-(let ((print-circle t)
- (print-continuous-numbering t)
- print-number-table)
- (print1 x)
- (print1 y))
-@end example
This is also responsible for calling @code{blink-paren-function} when
the inserted character has close parenthesis syntax (@pxref{Blinking}).
+
+Do not try substituting your own definition of
+@code{self-insert-command} for the standard one. The editor command
+loop handles this function specially.
@end deffn
@deffn Command newline &optional number-of-newlines
@example
(set-text-properties @var{start} @var{end} nil)
@end example
+@end defun
+
+ The easiest way to make a string with text properties
+is with @code{propertize}:
+
+@defun propertize string &rest properties
+@tindex propertize
+This function returns a copy of @var{string} which has the text
+properties @var{properties}. These properties apply to all the
+characters in the string that is returned. Here is an example that
+constructs a string with a @code{face} property and a @code{mouse-face}
+property:
+
+@smallexample
+(propertize "foo" 'face 'italic
+ 'mouse-face 'bold-italic)
+ @result{} #("foo" 0 3 (mouse-face bold-italic face italic))
+@end smallexample
+
+To put different properties on various parts of a string, you can
+construct each part with @code{propertize} and then combine them with
+@code{concat}:
+
+@smallexample
+(concat
+ (propertize "foo" 'face 'italic
+ 'mouse-face 'bold-italic)
+ " and "
+ (propertize "bar" 'face 'italic
+ 'mouse-face 'bold-italic))
+ @result{} #("foo and bar"
+ 0 3 (face italic mouse-face bold-italic)
+ 3 8 nil
+ 8 11 (face italic mouse-face bold-italic))
+@end smallexample
@end defun
See also the function @code{buffer-substring-no-properties}
projects / emacs.git / commitdiff