mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-11-26 07:33:47 +00:00
Code Issues Releases Activity

*** empty log message ***

Browse Source
This commit is contained in:
Phillip Rulon 1999-10-05 23:26:05 +00:00
parent 46fe917b5a
commit a40d4712b2
17 changed files with 436 additions and 328 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
lispref/advice.texi
View File

@ -168,14 +168,15 @@ definition that is generated in order to run the advice (@pxref{Combined
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

6
lispref/anti.texi
View File

@ -104,6 +104,12 @@ The functions @code{color-values}, @code{color-defined-p} and
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.

2
lispref/backups.texi
View File

@ -73,7 +73,7 @@ is @code{nil} (see below).
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

2
lispref/calendar.texi
View File

@ -30,7 +30,7 @@ diary suit your personal tastes.
@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)

12
lispref/commands.texi
View File

@ -2573,15 +2573,15 @@ the commands by accident.
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:
@ -2598,13 +2598,13 @@ programs.
@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

12
lispref/debugging.texi
View File

@ -137,16 +137,16 @@ enter the debugger.
@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:

308
lispref/display.texi
View File

@ -19,8 +19,9 @@ that Emacs presents to the user.
* 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.
@ -313,11 +314,11 @@ subsequently make various subsets visible or invisible by changing the
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
@ -359,6 +360,7 @@ Add the element @var{element} to @code{buffer-invisibility-spec}
@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
@ -446,9 +448,10 @@ lines, or portions of lines, may be made invisible.
@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
@ -780,7 +783,7 @@ This property controls the way text is displayed---for example, which
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
@ -819,8 +822,8 @@ or shorter, higher or lower, wider or narror, or replaced with an image.
@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)}
@ -880,17 +883,13 @@ visible, temporarily, during the search. @xref{Invisible Text}.
@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)}
@ -943,14 +942,15 @@ a Lisp object, but ceases to be attached to the buffer it belonged to,
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}.
@ -1090,8 +1090,9 @@ This face is used for ordinary text.
@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)}
@ -1102,6 +1103,10 @@ old Emacs versions.
@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
@ -1129,7 +1134,8 @@ This face is meant to be used for highlighting for various purposes.
@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
@ -1163,10 +1169,17 @@ This face forces use of a particular fixed-width font.
@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
@ -1177,18 +1190,20 @@ emacs, The GNU Emacs Manual}).
@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}.
@ -1234,15 +1249,25 @@ frame must match one of the @var{value}s specified for it in
@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
@ -1266,9 +1291,9 @@ as if they had a light background.
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.
@ -1276,14 +1301,17 @@ In face merging, when the first face fails to specify a particular
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
@ -1293,19 +1321,22 @@ set width. This should be one of the symbols @code{ultra-condensed},
@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}.
@ -1324,16 +1355,18 @@ Whether or not characters should be displayed in inverse video. The
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.
@ -1356,8 +1389,7 @@ color. The value is used like that of @code{:underline}.
@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
@ -1391,12 +1423,12 @@ is used.
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.
@ -1410,11 +1442,9 @@ even though they are not real face attributes. Here is what that does:
@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.
@ -1433,6 +1463,12 @@ This variable specifies a list of directories for searching
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
@ -1449,7 +1485,7 @@ the attribute for all frames, and the defaults for new frames.
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
@ -1481,7 +1517,8 @@ For 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
@ -1547,6 +1584,8 @@ This function inverts the @code{:inverse-video} attribute of face
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
@ -1798,15 +1837,9 @@ same attributes for display.
@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
@ -2026,18 +2059,22 @@ field.
@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
@ -2047,10 +2084,12 @@ describes several kinds of display specifications and what they mean.
@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}
@ -2066,7 +2105,8 @@ character, multiplied by @var{factor}.
@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
@ -2083,8 +2123,9 @@ of the text having this display specification by @var{factor}.
@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}
@ -2100,10 +2141,11 @@ display specification, it means to display the image instead of the text
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.
@ -2112,8 +2154,10 @@ Here are the possibilities for @var{height}:
@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.
@ -2237,15 +2281,15 @@ supported in the current configuration.
@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
@ -2507,10 +2551,11 @@ Each argument in @var{specs} has the form of a property list, and each
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
@ -2528,11 +2573,12 @@ as @code{nil}.
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;
@ -2540,15 +2586,16 @@ 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}.
@ -2671,14 +2718,14 @@ default is @code{nil}.
@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}.
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 displays mode lines using the face named
@code{modeline}, which is normally the inverse of the default face
unless you change it.
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
@ -2759,9 +2806,10 @@ buffers that do not override it. @xref{Default Value}.
@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
@ -3014,7 +3062,9 @@ capability (@samp{vb}).
@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
@ -3047,7 +3097,7 @@ Emacs is using a character-based terminal.
@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}.

14
lispref/elisp.texi
View File

@ -72,7 +72,7 @@ instead of in the original English.
@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
@ -179,8 +179,7 @@ Reference Manual, corresponding to GNU Emacs version 21.1.
* 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
@ -197,7 +196,7 @@ 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 ---
@ -248,7 +247,7 @@ Programming Types
* 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.
@ -262,7 +261,7 @@ Programming Types
* 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
@ -554,7 +553,7 @@ Keymaps
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.
@ -964,6 +963,7 @@ Object Internals
@c REMOVE this: include non-hacker.texi
@include anti.texi
@include tips.texi
@include internals.texi
@include errors.texi

4
lispref/frames.texi
View File

@ -217,7 +217,7 @@ doesn't change.
@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
@ -229,7 +229,7 @@ Each element has the form:
(@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.

16
lispref/hash.texi
View File

@ -99,7 +99,9 @@ referenced anywhere else); if a particular value does get collected, the
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
@ -115,10 +117,11 @@ When you add an association to a hash table and the table is ``full,''
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.
@ -278,7 +281,8 @@ This function returns the actual number of entries in @var{table}.
@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

10
lispref/intro.texi
View File

@ -458,8 +458,8 @@ or experiment to learn something not covered in the manual, then perhaps
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
@ -474,7 +474,7 @@ find them. 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 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
@ -924,7 +924,7 @@ Richard M. Stallman and Chris Welty, the volunteers of the GNU manual
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
@ -935,6 +935,6 @@ Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe
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.

12
lispref/keymaps.texi
View File

@ -620,9 +620,9 @@ enables or disables a minor mode. @xref{Keymaps and Minor Modes}.
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
@ -1224,8 +1224,8 @@ Dired mode is set up:
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)
@ -1658,7 +1658,7 @@ currently used by Emacs).
@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.

5
lispref/loading.texi
View File

@ -192,8 +192,9 @@ export EMACSLOADPATH
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

213
lispref/modes.texi
View File

@ -54,9 +54,9 @@ 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 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
@ -73,8 +73,9 @@ 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}. 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
@ -210,8 +211,10 @@ variable local to every buffer in which it is subsequently set, which
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
@ -258,10 +261,9 @@ autoload, you should add this element in the same file that calls
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
@ -300,11 +302,15 @@ the conventions listed above:
@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))
@ -334,6 +340,8 @@ Turning on text-mode runs the hook `text-mode-hook'."
(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")
@ -422,6 +430,7 @@ rest of @code{lisp-mode-variables}.
@group
(make-local-variable 'comment-indent-function)
(setq comment-indent-function 'lisp-comment-indent))
@dots{}
@end group
@end smallexample
@ -642,7 +651,7 @@ file in the proper mode according to the name sans @samp{.gz}.
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
@ -881,16 +890,22 @@ check for an existing element, to avoid duplication. For example:
@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
@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
You can also use @code{add-to-list} to add an element to this list
just once (@pxref{Setting Variables}).
Global minor modes distributed with Emacs should if possible support
enabling and disabling via Custom (@pxref{Customization}). To do this,
the first step is to define the mode variable with @code{defcustom}, and
@ -1064,11 +1079,11 @@ Force redisplay of the current buffer's mode line and header line.
@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
@ -1299,10 +1314,24 @@ status in modes used for communicating with subprocesses. It is
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
@ -1322,6 +1351,9 @@ The default value of @code{default-mode-line-format} is this list:
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
@ -1338,13 +1370,6 @@ The default value of @code{default-mode-line-format} is this list:
@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
@ -1357,6 +1382,9 @@ integer after the @samp{%} to specify how many characters to display.
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}.
@ -1365,13 +1393,34 @@ 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}); @*
@ -1386,28 +1435,6 @@ read-only buffer. @xref{Buffer Modification}.
@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.
@ -1417,12 +1444,12 @@ 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
@ -1467,7 +1494,7 @@ structure, and make @var{form} evaluate to a string that has a
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
@ -1504,9 +1531,10 @@ It is normally @code{nil}, so that ordinary buffers have no header line.
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}:
@ -1528,8 +1556,8 @@ in the top level of the buffer index.
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:
@ -1539,8 +1567,8 @@ 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:
@ -1610,12 +1638,12 @@ variables @code{imenu-prev-index-position-function} and
@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
@ -1630,7 +1658,7 @@ Setting this variable makes it buffer-local in the current buffer.
@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.
@ -1673,16 +1701,16 @@ A nested sub-alist element looks like @code{(@var{index-name}
@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::
@ -1714,7 +1742,7 @@ this:
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.
@ -1737,10 +1765,12 @@ table is stored in @code{font-lock-syntax-table}.
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
@ -2110,7 +2140,7 @@ value is one of those two types.
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
@ -2136,7 +2166,7 @@ a Function}). Most normal hook variables are initially void;
@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},
@ -2161,11 +2191,10 @@ in Lisp Interaction mode:
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
@ -2193,8 +2222,8 @@ This function is the way to run an abnormal hook which passes arguments
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
@ -2252,9 +2281,9 @@ current buffer. When a hook variable is buffer-local, it can have
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

64
lispref/os.texi
View File

@ -85,9 +85,10 @@ It loads the library @file{site-start}, unless the option
@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}
@ -147,36 +148,45 @@ the information they are supposed to see.
@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
@ -200,10 +210,6 @@ way you can change it with real effect is to do so before dumping
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.
@ -253,7 +259,7 @@ the @file{term/aaa} library. If necessary, the library can evaluate
@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.
@ -262,7 +268,7 @@ 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}.
@ -277,9 +283,9 @@ a terminal-specific initialization file as follows:
@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.
@ -287,7 +293,7 @@ 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
@ -327,7 +333,7 @@ kill the Emacs until you are about to log out.)
@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
@ -811,7 +817,7 @@ files or user profile.
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
@ -1788,7 +1794,7 @@ for them using @code{keyboard-translate-table} (@pxref{Translating Input}).
@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

32
lispref/streams.texi
View File

@ -52,8 +52,8 @@ returns the symbol @code{foo}. Printing a list whose elements are
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
@ -783,31 +783,3 @@ If non-@code{nil}, this variable enables detection of uninterned symbols
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

39
lispref/text.texi
View File

@ -424,6 +424,10 @@ syntax. (@xref{Abbrevs}, and @ref{Syntax Class Table}.)
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
@ -2398,6 +2402,41 @@ from the specified range of text. Here's an example:
@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}