Mercurial > emacs
changeset 25875:6a17c48b52ef
*** empty log message ***
| author | Phillip Rulon <pjr@gnu.org> |
|---|---|
| date | Tue, 05 Oct 1999 23:26:05 +0000 |
| parents | 906a123add31 |
| children | 9542c11c75e3 |
| files | lispref/advice.texi lispref/anti.texi lispref/backups.texi lispref/calendar.texi lispref/commands.texi lispref/debugging.texi lispref/display.texi lispref/elisp.texi lispref/frames.texi lispref/hash.texi lispref/intro.texi lispref/keymaps.texi lispref/loading.texi lispref/modes.texi lispref/os.texi lispref/streams.texi lispref/text.texi |
| diffstat | 17 files changed, 439 insertions(+), 331 deletions(-) [+] |
line wrap: on
line diff
--- a/lispref/advice.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/advice.texi Tue Oct 05 23:26:05 1999 +0000 @@ -168,14 +168,15 @@ 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
--- a/lispref/anti.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/anti.texi Tue Oct 05 23:26:05 1999 +0000 @@ -105,6 +105,12 @@ 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.
--- a/lispref/backups.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/backups.texi Tue Oct 05 23:26:05 1999 +0000 @@ -73,7 +73,7 @@ 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
--- a/lispref/calendar.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/calendar.texi Tue Oct 05 23:26:05 1999 +0000 @@ -30,7 +30,7 @@ @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)
--- a/lispref/commands.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/commands.texi Tue Oct 05 23:26:05 1999 +0000 @@ -2573,15 +2573,15 @@ 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 @@ @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
--- a/lispref/debugging.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/debugging.texi Tue Oct 05 23:26:05 1999 +0000 @@ -137,16 +137,16 @@ @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:
--- a/lispref/display.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/display.texi Tue Oct 05 23:26:05 1999 +0000 @@ -19,8 +19,9 @@ * 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 @@ 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 @@ @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 @@ @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 @@ 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 @@ @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 @@ @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 @@ 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 @@ @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 @@ @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 @@ @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 @@ @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 @@ @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 @@ @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 @@ 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 @@ 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 @@ @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 @@ value should be @code{t} (yes) or @code{nil} (no). @item :stipple -The background stipple, a bitmap name. - -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}. - -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. +The background stipple, a bitmap. + +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 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 @@ @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 @@ 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 @@ @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 @@ 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 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 @@ @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 @@ 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 @@ @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 @@ @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 @@ @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 @@ @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 @@ @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 @@ 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 @@ @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 @@ @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 @@ 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 @@ 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 @@ @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 @@ @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 @@ -2759,9 +2806,10 @@ @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 @@ @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 @@ @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}.
--- a/lispref/elisp.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/elisp.texi Tue Oct 05 23:26:05 1999 +0000 @@ -72,7 +72,7 @@ @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 @@ * 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 @@ * 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 @@ * 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 @@ * 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 @@ 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 @@ @c REMOVE this: include non-hacker.texi +@include anti.texi @include tips.texi @include internals.texi @include errors.texi
--- a/lispref/frames.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/frames.texi Tue Oct 05 23:26:05 1999 +0000 @@ -217,7 +217,7 @@ @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 @@ (@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.
--- a/lispref/hash.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/hash.texi Tue Oct 05 23:26:05 1999 +0000 @@ -99,7 +99,9 @@ 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 @@ 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 @@ @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
--- a/lispref/intro.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/intro.texi Tue Oct 05 23:26:05 1999 +0000 @@ -458,8 +458,8 @@ 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 @@ 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 @@ 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 @@ 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.
--- a/lispref/keymaps.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/keymaps.texi Tue Oct 05 23:26:05 1999 +0000 @@ -620,9 +620,9 @@ 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 @@ 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 @@ @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.
--- a/lispref/loading.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/loading.texi Tue Oct 05 23:26:05 1999 +0000 @@ -192,8 +192,9 @@ 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
--- a/lispref/modes.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/modes.texi Tue Oct 05 23:26:05 1999 +0000 @@ -54,9 +54,9 @@ 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 @@ 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 @@ 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 @@ 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 @@ @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 @@ (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 @@ @group (make-local-variable 'comment-indent-function) (setq comment-indent-function 'lisp-comment-indent)) + @dots{} @end group @end smallexample @@ -642,7 +651,7 @@ 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 @@ @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 @@ @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 @@ 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 @@ 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 @@ @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 @@ 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 @@ 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 @@ @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 @@ 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 @@ 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 @@ 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 @@ 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 @@ @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 @@ @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 @@ @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 @@ @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 @@ 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 @@ 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 @@ 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 @@ @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 @@ 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 @@ 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 @@ 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
--- a/lispref/os.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/os.texi Tue Oct 05 23:26:05 1999 +0000 @@ -85,9 +85,10 @@ @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 @@ @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 @@ 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 @@ @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 @@ 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 @@ @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 @@ @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 @@ @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 @@ 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 @@ @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
--- a/lispref/streams.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/streams.texi Tue Oct 05 23:26:05 1999 +0000 @@ -52,8 +52,8 @@ 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 @@ 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
--- a/lispref/text.texi Tue Oct 05 22:18:23 1999 +0000 +++ b/lispref/text.texi Tue Oct 05 23:26:05 1999 +0000 @@ -424,6 +424,10 @@ 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 @@ -2400,6 +2404,41 @@ @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} (@pxref{Buffer Contents}) which copies text from the buffer but does not copy its properties.