This is ../../info/elisp, produced by makeinfo version 4.13 from
elisp.texi.

This is edition 3.0 of the GNU Emacs Lisp Reference Manual,
corresponding to Emacs version 23.4.

   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999,
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
2012  Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with the Invariant Sections being "GNU General Public
     License," with the Front-Cover texts being "A GNU Manual," and
     with the Back-Cover Texts as in (a) below.  A copy of the license
     is included in the section entitled "GNU Free Documentation
     License."

     (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
     modify this GNU manual.  Buying copies from the FSF supports it in
     developing GNU and promoting software freedom."

INFO-DIR-SECTION GNU Emacs Lisp
START-INFO-DIR-ENTRY
* Elisp: (elisp).       The Emacs Lisp Reference Manual.
END-INFO-DIR-ENTRY


File: elisp,  Node: Overlay Properties,  Next: Finding Overlays,  Prev: Managing Overlays,  Up: Overlays

38.9.2 Overlay Properties
-------------------------

Overlay properties are like text properties in that the properties that
alter how a character is displayed can come from either source.  But in
most respects they are different.  *Note Text Properties::, for
comparison.

   Text properties are considered a part of the text; overlays and
their properties are specifically considered not to be part of the
text.  Thus, copying text between various buffers and strings preserves
text properties, but does not try to preserve overlays.  Changing a
buffer's text properties marks the buffer as modified, while moving an
overlay or changing its properties does not.  Unlike text property
changes, overlay property changes are not recorded in the buffer's undo
list.

   Since more than one overlay can specify a property value for the
same character, Emacs lets you specify a priority value of each
overlay.  You should not make assumptions about which overlay will
prevail when there is a conflict and they have the same priority.

   These functions read and set the properties of an overlay:

 -- Function: overlay-get overlay prop
     This function returns the value of property PROP recorded in
     OVERLAY, if any.  If OVERLAY does not record any value for that
     property, but it does have a `category' property which is a
     symbol, that symbol's PROP property is used.  Otherwise, the value
     is `nil'.

 -- Function: overlay-put overlay prop value
     This function sets the value of property PROP recorded in OVERLAY
     to VALUE.  It returns VALUE.

 -- Function: overlay-properties overlay
     This returns a copy of the property list of OVERLAY.

   See also the function `get-char-property' which checks both overlay
properties and text properties for a given character.  *Note Examining
Properties::.

   Many overlay properties have special meanings; here is a table of
them:

`priority'
     This property's value (which should be a nonnegative integer
     number) determines the priority of the overlay.  No priority, or
     `nil', means zero.

     The priority matters when two or more overlays cover the same
     character and both specify the same property; the one whose
     `priority' value is larger overrides the other.  For the `face'
     property, the higher priority overlay's value does not completely
     override the other value; instead, its face attributes override
     the face attributes of the lower priority `face' property.

     Currently, all overlays take priority over text properties.  Please
     avoid using negative priority values, as we have not yet decided
     just what they should mean.

`window'
     If the `window' property is non-`nil', then the overlay applies
     only on that window.

`category'
     If an overlay has a `category' property, we call it the "category"
     of the overlay.  It should be a symbol.  The properties of the
     symbol serve as defaults for the properties of the overlay.

`face'
     This property controls the way text is displayed--for example,
     which font and which colors.  *Note 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:

        * A face name (a symbol or string).

        * A property list of face attributes.  This has the form
          (KEYWORD VALUE ...), where each KEYWORD is a face attribute
          name and VALUE is a meaningful value for that attribute.  With
          this feature, you do not need to create a face each time you
          want to specify a particular attribute for certain text.
          *Note Face Attributes::.

        * A cons cell, of the form `(foreground-color . COLOR-NAME)' or
          `(background-color . COLOR-NAME)'.  These elements specify
          just the foreground color or just the background color.

          `(foreground-color . COLOR-NAME)' has the same effect as
          `(:foreground COLOR-NAME)'; likewise for the background.

`mouse-face'
     This property is used instead of `face' when the mouse is within
     the range of the overlay.

`display'
     This property activates various features that change the way text
     is displayed.  For example, it can make text appear taller or
     shorter, higher or lower, wider or narrower, or replaced with an
     image.  *Note Display Property::.

`help-echo'
     If an overlay has a `help-echo' property, then when you move the
     mouse onto the text in the overlay, Emacs displays a help string
     in the echo area, or in the tooltip window.  For details see *note
     Text help-echo::.

`modification-hooks'
     This property's value is a list of functions to be called if any
     character within the overlay is changed or if text is inserted
     strictly within the overlay.

     The hook functions are called both before and after each change.
     If the functions save the information they receive, and compare
     notes between calls, they can determine exactly what change has
     been made in the buffer text.

     When called before a change, each function receives four
     arguments: the overlay, `nil', and the beginning and end of the
     text range to be modified.

     When called after a change, each function receives five arguments:
     the overlay, `t', the beginning and end of the text range just
     modified, and the length of the pre-change text replaced by that
     range.  (For an insertion, the pre-change length is zero; for a
     deletion, that length is the number of characters deleted, and the
     post-change beginning and end are equal.)

     If these functions modify the buffer, they should bind
     `inhibit-modification-hooks' to `t' around doing so, to avoid
     confusing the internal mechanism that calls these hooks.

     Text properties also support the `modification-hooks' property,
     but the details are somewhat different (*note Special
     Properties::).

`insert-in-front-hooks'
     This property's value is a list of functions to be called before
     and after inserting text right at the beginning of the overlay.
     The calling conventions are the same as for the
     `modification-hooks' functions.

`insert-behind-hooks'
     This property's value is a list of functions to be called before
     and after inserting text right at the end of the overlay.  The
     calling conventions are the same as for the `modification-hooks'
     functions.

`invisible'
     The `invisible' property can make the text in the overlay
     invisible, which means that it does not appear on the screen.
     *Note Invisible Text::, for details.

`intangible'
     The `intangible' property on an overlay works just like the
     `intangible' text property.  *Note Special Properties::, for
     details.

`isearch-open-invisible'
     This property tells incremental search how to make an invisible
     overlay visible, permanently, if the final match overlaps it.
     *Note Invisible Text::.

`isearch-open-invisible-temporary'
     This property tells incremental search how to make an invisible
     overlay visible, temporarily, during the search.  *Note Invisible
     Text::.

`before-string'
     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.

`after-string'
     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.

`line-prefix'
     This property specifies a display spec to prepend to each
     non-continuation line at display-time.  *Note Truncation::.

`wrap-prefix'
     This property specifies a display spec to prepend to each
     continuation line at display-time.  *Note Truncation::.

`evaporate'
     If this property is non-`nil', the overlay is deleted automatically
     if it becomes empty (i.e., if its length becomes zero).  If you
     give an empty overlay a non-`nil' `evaporate' property, that
     deletes it immediately.

`local-map'
     If this property is non-`nil', it specifies a keymap for a portion
     of the text.  The property's value replaces the buffer's local
     map, when the character after point is within the overlay.  *Note
     Active Keymaps::.

`keymap'
     The `keymap' property is similar to `local-map' but overrides the
     buffer's local map (and the map specified by the `local-map'
     property) rather than replacing it.

   The `local-map' and `keymap' properties do not affect a string
displayed by the `before-string', `after-string', or `display'
properties.  This is only relevant for mouse clicks and other mouse
events that fall on the string, since point is never on the string.  To
bind special mouse events for the string, assign it a `local-map' or
`keymap' text property.  *Note Special Properties::.


File: elisp,  Node: Finding Overlays,  Prev: Overlay Properties,  Up: Overlays

38.9.3 Searching for Overlays
-----------------------------

 -- Function: overlays-at pos
     This function returns a list of all the overlays that cover the
     character at position POS in the current buffer.  The list is in
     no particular order.  An overlay contains position POS if it
     begins at or before POS, and ends after POS.

     To illustrate usage, here is a Lisp function that returns a list
     of the overlays that specify property PROP for the character at
     point:

          (defun find-overlays-specifying (prop)
            (let ((overlays (overlays-at (point)))
                  found)
              (while overlays
                (let ((overlay (car overlays)))
                  (if (overlay-get overlay prop)
                      (setq found (cons overlay found))))
                (setq overlays (cdr overlays)))
              found))

 -- Function: overlays-in beg end
     This function returns a list of the overlays that overlap the
     region BEG through END.  "Overlap" means that at least one
     character is contained within the overlay and also contained
     within the specified region; however, empty overlays are included
     in the result if they are located at BEG, strictly between BEG and
     END, or at END when END denotes the position at the end of the
     buffer.

 -- Function: next-overlay-change pos
     This function returns the buffer position of the next beginning or
     end of an overlay, after POS.  If there is none, it returns
     `(point-max)'.

 -- Function: previous-overlay-change pos
     This function returns the buffer position of the previous
     beginning or end of an overlay, before POS.  If there is none, it
     returns `(point-min)'.

   As an example, here's a simplified (and inefficient) version of the
primitive function `next-single-char-property-change' (*note Property
Search::).  It searches forward from position POS for the next position
where the value of a given property `prop', as obtained from either
overlays or text properties, changes.

     (defun next-single-char-property-change (position prop)
       (save-excursion
         (goto-char position)
         (let ((propval (get-char-property (point) prop)))
           (while (and (not (eobp))
                       (eq (get-char-property (point) prop) propval))
             (goto-char (min (next-overlay-change (point))
                             (next-single-property-change (point) prop)))))
         (point)))


File: elisp,  Node: Width,  Next: Line Height,  Prev: Overlays,  Up: Display

38.10 Width
===========

Since not all characters have the same width, these functions let you
check the width of a character.  *Note Primitive Indent::, and *note
Screen Lines::, for related functions.

 -- Function: char-width char
     This function returns the width in columns of the character CHAR,
     if it were displayed in the current buffer and the selected window.

 -- Function: string-width string
     This function returns the width in columns of the string STRING,
     if it were displayed in the current buffer and the selected window.

 -- Function: truncate-string-to-width string width &optional
          start-column padding ellipsis
     This function returns the part of STRING that fits within WIDTH
     columns, as a new string.

     If STRING does not reach WIDTH, then the result ends where STRING
     ends.  If one multi-column character in STRING extends across the
     column WIDTH, that character is not included in the result.  Thus,
     the result can fall short of WIDTH but cannot go beyond it.

     The optional argument START-COLUMN specifies the starting column.
     If this is non-`nil', then the first START-COLUMN columns of the
     string are omitted from the value.  If one multi-column character
     in STRING extends across the column START-COLUMN, that character
     is not included.

     The optional argument PADDING, if non-`nil', is a padding
     character added at the beginning and end of the result string, to
     extend it to exactly WIDTH columns.  The padding character is used
     at the end of the result if it falls short of WIDTH.  It is also
     used at the beginning of the result if one multi-column character
     in STRING extends across the column START-COLUMN.

     If ELLIPSIS is non-`nil', it should be a string which will replace
     the end of STR (including any padding) if it extends beyond
     END-COLUMN, unless the display width of STR is equal to or less
     than the display width of ELLIPSIS.  If ELLIPSIS is non-`nil' and
     not a string, it stands for `"..."'.

          (truncate-string-to-width "\tab\t" 12 4)
               => "ab"
          (truncate-string-to-width "\tab\t" 12 4 ?\s)
               => "    ab  "


File: elisp,  Node: Line Height,  Next: Faces,  Prev: Width,  Up: Display

38.11 Line Height
=================

The total height of each display line consists of the height of the
contents of the line, plus optional additional vertical line spacing
above or below the display line.

   The height of the line contents is the maximum height of any
character or image on that display line, including the final newline if
there is one.  (A display line that is continued doesn't include a
final newline.)  That is the default line height, if you do nothing to
specify a greater height.  (In the most common case, this equals the
height of the default frame font.)

   There are several ways to explicitly specify a larger line height,
either by specifying an absolute height for the display line, or by
specifying vertical space.  However, no matter what you specify, the
actual line height can never be less than the default.

   A newline can have a `line-height' text or overlay property that
controls the total height of the display line ending in that newline.

   If the property value is `t', the newline character has no effect on
the displayed height of the line--the visible contents alone determine
the height.  This is useful for tiling small images (or image slices)
without adding blank areas between the images.

   If the property value is a list of the form `(HEIGHT TOTAL)', that
adds extra space _below_ the display line.  First Emacs uses HEIGHT as
a height spec to control extra space _above_ the line; then it adds
enough space _below_ the line to bring the total line height up to
TOTAL.  In this case, the other ways to specify the line spacing are
ignored.

   Any other kind of property value is a height spec, which translates
into a number--the specified line height.  There are several ways to
write a height spec; here's how each of them translates into a number:

`INTEGER'
     If the height spec is a positive integer, the height value is that
     integer.

`FLOAT'
     If the height spec is a float, FLOAT, the numeric height value is
     FLOAT times the frame's default line height.

`(FACE . RATIO)'
     If the height spec is a cons of the format shown, the numeric
     height is RATIO times the height of face FACE.  RATIO can be any
     type of number, or `nil' which means a ratio of 1.  If FACE is
     `t', it refers to the current face.

`(nil . RATIO)'
     If the height spec is a cons of the format shown, the numeric
     height is RATIO times the height of the contents of the line.

   Thus, any valid height spec determines the height in pixels, one way
or another.  If the line contents' height is less than that, Emacs adds
extra vertical space above the line to achieve the specified total
height.

   If you don't specify the `line-height' property, the line's height
consists of the contents' height plus the line spacing.  There are
several ways to specify the line spacing for different parts of Emacs
text.

   On graphical terminals, you can specify the line spacing for all
lines in a frame, using the `line-spacing' frame parameter (*note
Layout Parameters::).  However, if the default value of `line-spacing'
is non-`nil', it overrides the frame's `line-spacing' parameter.  An
integer value specifies the number of pixels put below lines.  A
floating point number specifies the spacing relative to the frame's
default line height.

   You can specify the line spacing for all lines in a buffer via the
buffer-local `line-spacing' variable.  An integer value specifies the
number of pixels put below lines.  A floating point number specifies
the spacing relative to the default frame line height.  This overrides
line spacings specified for the frame.

   Finally, a newline can have a `line-spacing' text or overlay
property that overrides the default frame line spacing and the buffer
local `line-spacing' variable, for the display line ending in that
newline.

   One way or another, these mechanisms specify a Lisp value for the
spacing of each line.  The value is a height spec, and it translates
into a Lisp value as described above.  However, in this case the
numeric height value specifies the line spacing, rather than the line
height.

   On text-only terminals, the line spacing cannot be altered.


File: elisp,  Node: Faces,  Next: Fringes,  Prev: Line Height,  Up: Display

38.12 Faces
===========

A "face" is a collection of graphical attributes for displaying text:
font family, foreground color, background color, optional underlining,
and so on.  Faces control how buffer text is displayed, and how some
parts of the frame, such as the mode-line, are displayed.  *Note
Standard Faces: (emacs)Standard Faces, for the list of faces Emacs
normally comes with.

   For most purposes, you refer to a face in Lisp programs using its
"face name".  This is either a string or (equivalently) a Lisp symbol
whose name is equal to that string.

 -- Function: facep object
     This function returns a non-`nil' value if OBJECT is a Lisp symbol
     or string that names a face.  Otherwise, it returns `nil'.

   Each face name is meaningful for all frames, and by default it has
the same meaning in all frames.  But you can arrange to give a
particular face name a special meaning in one frame if you wish.

* Menu:

* Defining Faces::      How to define a face with `defface'.
* Face Attributes::     What is in a face?
* Attribute Functions::  Functions to examine and set face attributes.
* Displaying Faces::     How Emacs combines the faces specified for a character.
* Face Remapping::     Remapping faces to alternative definitions.
* Face Functions::      How to define and examine faces.
* Auto Faces::          Hook for automatic face assignment.
* Font Selection::      Finding the best available font for a face.
* Font Lookup::         Looking up the names of available fonts
                          and information about them.
* Fontsets::            A fontset is a collection of fonts
                          that handle a range of character sets.
* Low-Level Font::      Lisp representation for character display fonts.


File: elisp,  Node: Defining Faces,  Next: Face Attributes,  Up: Faces

38.12.1 Defining Faces
----------------------

The way to define a new face is with `defface'.  This creates a kind of
customization item (*note Customization::) which the user can customize
using the Customization buffer (*note Easy Customization: (emacs)Easy
Customization.).

   People are sometimes tempted to create variables whose values specify
which faces to use (for example, Font-Lock does this).  In the vast
majority of cases, this is not necessary, and simply using faces
directly is preferable.

 -- Macro: defface face spec doc [keyword value]...
     This declares FACE as a customizable face whose default attributes
     are given by SPEC.  You should not quote the symbol FACE, and it
     should not end in `-face' (that would be redundant).  The argument
     DOC specifies the face documentation.  The keywords you can use in
     `defface' are the same as in `defgroup' and `defcustom' (*note
     Common Keywords::).

     When `defface' executes, it defines the face according to SPEC,
     then uses any customizations that were read from the init file
     (*note Init File::) to override that specification.

     When you evaluate a `defface' form with `C-M-x' in Emacs Lisp mode
     (`eval-defun'), a special feature of `eval-defun' overrides any
     customizations of the face.  This way, the face reflects exactly
     what the `defface' says.

     The purpose of SPEC is to specify how the face should appear on
     different kinds of terminals.  It should be an alist whose elements
     have the form `(DISPLAY ATTS)'.  Each element's CAR, DISPLAY,
     specifies a class of terminals.  (The first element, if its CAR is
     `default', is special--it specifies defaults for the remaining
     elements).  The element's CADR, 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 `custom-face-attributes'.

     The DISPLAY part of an element of SPEC determines which frames the
     element matches.  If more than one element of SPEC matches a given
     frame, the first element that matches is the one used for that
     frame.  There are three possibilities for DISPLAY:

    `default'
          This element of SPEC doesn't match any frames; instead, it
          specifies defaults that apply to all frames.  This kind of
          element, if used, must be the first element of SPEC.  Each of
          the following elements can override any or all of these
          defaults.

    `t'
          This element of SPEC matches all frames.  Therefore, any
          subsequent elements of SPEC are never used.  Normally `t' is
          used in the last (or only) element of SPEC.

    a list
          If DISPLAY is a list, each element should have the form
          `(CHARACTERISTIC VALUE...)'.  Here CHARACTERISTIC specifies a
          way of classifying frames, and the VALUEs are possible
          classifications which DISPLAY should apply to.  Here are the
          possible values of CHARACTERISTIC:

         `type'
               The kind of window system the frame uses--either
               `graphic' (any graphics-capable display), `x', `pc' (for
               the MS-DOS console), `w32' (for MS Windows 9X/NT/2K/XP),
               or `tty' (a non-graphics-capable display).  *Note
               window-system: Window Systems.

         `class'
               What kinds of colors the frame supports--either `color',
               `grayscale', or `mono'.

         `background'
               The kind of background--either `light' or `dark'.

         `min-colors'
               An integer that represents the minimum number of colors
               the frame should support.  This matches a frame if its
               `display-color-cells' value is at least the specified
               integer.

         `supports'
               Whether or not the frame can display the face attributes
               given in VALUE... (*note Face Attributes::).  *Note
               Display Face Attribute Testing::, for more information
               on exactly how this testing is done.

          If an element of DISPLAY specifies more than one VALUE for a
          given CHARACTERISTIC, any of those values is acceptable.  If
          DISPLAY has more than one element, each element should
          specify a different CHARACTERISTIC; then _each_
          characteristic of the frame must match one of the VALUEs
          specified for it in DISPLAY.

   Here's how the standard face `region' is defined:

     (defface region
       '((((class color) (min-colors 88) (background dark))
          :background "blue3")
         (((class color) (min-colors 88) (background light))
          :background "lightgoldenrod2")
         (((class color) (min-colors 16) (background dark))
          :background "blue3")
         (((class color) (min-colors 16) (background light))
          :background "lightgoldenrod2")
         (((class color) (min-colors 8))
          :background "blue" :foreground "white")
         (((type tty) (class mono))
          :inverse-video t)
         (t :background "gray"))
       "Basic face for highlighting the region."
       :group 'basic-faces)

   Internally, `defface' uses the symbol property `face-defface-spec'
to record the specified face attributes.  The attributes saved by the
user with the customization buffer are recorded in the symbol property
`saved-face'; the attributes customized by the user for the current
session, but not saved, are recorded in the symbol property
`customized-face'.  The documentation string is recorded in the symbol
property `face-documentation'.

 -- User Option: frame-background-mode
     This option, if non-`nil', specifies the background type to use for
     interpreting face definitions.  If it is `dark', then Emacs treats
     all frames as if they had a dark background, regardless of their
     actual background colors.  If it is `light', then Emacs treats all
     frames as if they had a light background.


File: elisp,  Node: Face Attributes,  Next: Attribute Functions,  Prev: Defining Faces,  Up: Faces

38.12.2 Face Attributes
-----------------------

The effect of using a face is determined by a fixed set of "face
attributes".  This table lists all the face attributes, their possible
values, and their effects.  You can specify more than one face for a
given piece of text; Emacs merges the attributes of all the faces to
determine how to display the text.  *Note Displaying Faces::.

   In addition to the values given below, each face attribute can also
have the value `unspecified'.  This special value means the face
doesn't specify that attribute.  In face merging, when the first face
fails to specify a particular attribute, the next face gets a chance.
However, the `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.

`:family'
     Font family name or fontset name (a string).  If you specify a font
     family name, the wild-card characters `*' and `?' are allowed.
     The function `font-family-list', described below, returns a list
     of available family names.  *Note Fontsets::, for information
     about fontsets.

`:foundry'
     The name of the "font foundry" in which the font family specified
     by the `:family' attribute is located (a string).  The wild-card
     characters `*' and `?' are allowed.

`:width'
     Relative proportionate character width, also known as the character
     set width.  This should be one of the symbols `ultra-condensed',
     `extra-condensed', `condensed', `semi-condensed', `normal',
     `semi-expanded', `expanded', `extra-expanded', or `ultra-expanded'.

`:height'
     The height of the font.  In the simplest case, this is an integer
     in units of 1/10 point.

     The value can also be a floating point number or a function, which
     specifies the height relative to an "underlying face" (i.e., a
     face that has a lower priority in the list described in *note
     Displaying Faces::).  If the value is a floating point number,
     that specifies the amount by which to scale the height of the
     underlying face.  If the value is a function, that function is
     called with one argument, the height of the underlying face, and
     returns the height of the new face.  If the function is passed an
     integer argument, it must return an integer.

     The height of the default face must be specified using an integer;
     floating point and function values are not allowed.

`:weight'
     Font weight--one of the symbols (from densest to faintest)
     `ultra-bold', `extra-bold', `bold', `semi-bold', `normal',
     `semi-light', `light', `extra-light', or `ultra-light'.  On
     text-only terminals that support variable-brightness text, any
     weight greater than normal is displayed as extra bright, and any
     weight less than normal is displayed as half-bright.

`:slant'
     Font slant--one of the symbols `italic', `oblique', `normal',
     `reverse-italic', or `reverse-oblique'.  On text-only terminals
     that support variable-brightness text, slanted text is displayed
     as half-bright.

`:foreground'
     Foreground color, a string.  The value can be a system-defined
     color name, or a hexadecimal color specification.  *Note Color
     Names::.  On black-and-white displays, certain shades of gray are
     implemented by stipple patterns.

`:background'
     Background color, a string.  The value can be a system-defined
     color name, or a hexadecimal color specification.  *Note Color
     Names::.

`:underline'
     Whether or not characters should be underlined, and in what color.
     If the value is `t', underlining uses the foreground color of the
     face.  If the value is a string, underlining uses that color.  The
     value `nil' means do not underline.

`:overline'
     Whether or not characters should be overlined, and in what color.
     The value is used like that of `:underline'.

`:strike-through'
     Whether or not characters should be strike-through, and in what
     color.  The value is used like that of `:underline'.

`:box'
     Whether or not a box should be drawn around characters, its color,
     the width of the box lines, and 3D appearance.  Here are the
     possible values of the `:box' attribute, and what they mean:

    `nil'
          Don't draw a box.

    `t'
          Draw a box with lines of width 1, in the foreground color.

    COLOR
          Draw a box with lines of width 1, in color COLOR.

    `(:line-width WIDTH :color COLOR :style STYLE)'
          This way you can explicitly specify all aspects of the box.
          The value WIDTH specifies the width of the lines to draw; it
          defaults to 1.  A negative width -N means to draw a line of
          width N that occupies the space of the underlying text, thus
          avoiding any increase in the character height or width.

          The value COLOR specifies the color to draw with.  The
          default is the foreground color of the face for simple boxes,
          and the background color of the face for 3D boxes.

          The value STYLE specifies whether to draw a 3D box.  If it is
          `released-button', the box looks like a 3D button that is not
          being pressed.  If it is `pressed-button', the box looks like
          a 3D button that is being pressed.  If it is `nil' or
          omitted, a plain 2D box is used.

`:inverse-video'
     Whether or not characters should be displayed in inverse video.
     The value should be `t' (yes) or `nil' (no).

`:stipple'
     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 `x-bitmap-file-path'.

     Alternatively, the value can specify the bitmap directly, with a
     list of the form `(WIDTH HEIGHT DATA)'.  Here, WIDTH and HEIGHT
     specify the size in pixels, and DATA is a string containing the
     raw bits of the bitmap, row by row.  Each row occupies (WIDTH + 7)
     / 8 consecutive bytes in the string (which should be a unibyte
     string for best results).  This means that each row always
     occupies at least one whole byte.

     If the value is `nil', that means use no stipple pattern.

     Normally you do not need to set the stipple attribute, because it
     is used automatically to handle certain shades of gray.

`:font'
     The font used to display the face.  Its value should be a font
     object.  *Note Font Selection::, for information about font
     objects.

     When specifying this attribute using `set-face-attribute' (*note
     Attribute Functions::), you may also supply a font spec, a font
     entity, or a string.  Emacs converts such values to an appropriate
     font object, and stores that font object as the actual attribute
     value.  If you specify a string, the contents of the string should
     be a font name (*note Font Specification Options: (emacs)Font X.);
     if the font name is an XLFD containing wildcards, Emacs chooses
     the first font matching those wildcards.  Specifying this
     attribute also changes the values of the `:family', `:foundry',
     `:width', `:height', `:weight', and `:slant' attributes.

`:inherit'
     The name of a face from which to inherit attributes, or a list of
     face names.  Attributes from inherited faces are merged into the
     face like an underlying face would be, with higher priority than
     underlying faces (*note Displaying Faces::).  If a list of faces
     is used, attributes from faces earlier in the list override those
     from later faces.

   For compatibility with Emacs 20, you can also specify values for two
"fake" face attributes: `:bold' and `:italic'.  Their values must be
either `t' or `nil'; a value of `unspecified' is not allowed.  Setting
`:bold' to `t' is equivalent to setting the `:weight' attribute to
`bold', and setting it to `nil' is equivalent to setting `:weight' to
`normal'.  Setting `:italic' to `t' is equivalent to setting the
`:slant' attribute to `italic', and setting it to `nil' is equivalent
to setting `:slant' to `normal'.

 -- Function: font-family-list &optional frame
     This function returns a list of available font family names.  The
     optional argument FRAME specifies the frame on which the text is
     to be displayed; if it is `nil', the selected frame is used.

 -- User Option: underline-minimum-offset
     This variable specifies the minimum distance between the baseline
     and the underline, in pixels, when displaying underlined text.

 -- User Option: x-bitmap-file-path
     This variable specifies a list of directories for searching for
     bitmap files, for the `:stipple' attribute.

 -- Function: bitmap-spec-p object
     This returns `t' if OBJECT is a valid bitmap specification,
     suitable for use with `:stipple' (see above).  It returns `nil'
     otherwise.


File: elisp,  Node: Attribute Functions,  Next: Displaying Faces,  Prev: Face Attributes,  Up: Faces

38.12.3 Face Attribute Functions
--------------------------------

This section describes the functions for accessing and modifying the
attributes of an existing face.

 -- Function: set-face-attribute face frame &rest arguments
     This function sets one or more attributes of FACE for FRAME.  The
     attributes you specify this way override whatever the `defface'
     says.

     The extra arguments ARGUMENTS specify the attributes to set, and
     the values for them.  They should consist of alternating attribute
     names (such as `:family' or `:underline') and corresponding values.
     Thus,

          (set-face-attribute 'foo nil
                              :width 'extended
                              :weight 'bold
                              :underline "red")

     sets the attributes `:width', `:weight' and `:underline' to the
     corresponding values.

     If FRAME is `t', this function sets the default attributes for new
     frames.  Default attribute values specified this way override the
     `defface' for newly created frames.

     If FRAME is `nil', this function sets the attributes for all
     existing frames, and the default for new frames.

 -- Function: face-attribute face attribute &optional frame inherit
     This returns the value of the ATTRIBUTE attribute of FACE on
     FRAME.  If FRAME is `nil', that means the selected frame (*note
     Input Focus::).

     If FRAME is `t', this returns whatever new-frames default value
     you previously specified with `set-face-attribute' for the
     ATTRIBUTE attribute of FACE.  If you have not specified one, it
     returns `nil'.

     If INHERIT is `nil', only attributes directly defined by FACE are
     considered, so the return value may be `unspecified', or a
     relative value.  If INHERIT is non-`nil', FACE's definition of
     ATTRIBUTE is merged with the faces specified by its `:inherit'
     attribute; however the return value may still be `unspecified' or
     relative.  If INHERIT is a face or a list of faces, then the
     result is further merged with that face (or faces), until it
     becomes specified and absolute.

     To ensure that the return value is always specified and absolute,
     use a value of `default' for INHERIT; this will resolve any
     unspecified or relative values by merging with the `default' face
     (which is always completely specified).

     For example,

          (face-attribute 'bold :weight)
               => bold

 -- Function: face-attribute-relative-p attribute value
     This function returns non-`nil' if VALUE, when used as the value
     of the face attribute ATTRIBUTE, is relative.  This means it would
     modify, rather than completely override, any value that comes from
     a subsequent face in the face list or that is inherited from
     another face.

     `unspecified' is a relative value for all attributes.  For
     `:height', floating point and function values are also relative.

     For example:

          (face-attribute-relative-p :height 2.0)
               => t

 -- Function: face-all-attributes face &optional frame
     This function returns an alist of attributes of FACE.  The
     elements of the result are name-value pairs of the form
     `(ATTR-NAME . ATTR-VALUE)'.  Optional argument FRAME specifies the
     frame whose definition of FACE to return; if omitted or `nil', the
     returned value describes the default attributes of FACE for newly
     created frames.

 -- Function: merge-face-attribute attribute value1 value2
     If VALUE1 is a relative value for the face attribute ATTRIBUTE,
     returns it merged with the underlying value VALUE2; otherwise, if
     VALUE1 is an absolute value for the face attribute ATTRIBUTE,
     returns VALUE1 unchanged.

   The following functions provide compatibility with Emacs 20 and
below.  They work by calling `set-face-attribute'.  Values of `t' and
`nil' for their FRAME argument are handled just like
`set-face-attribute' and `face-attribute'.

 -- Function: set-face-foreground face color &optional frame
 -- Function: set-face-background face color &optional frame
     These functions set the `:foreground' attribute (or `:background'
     attribute, respectively) of FACE to COLOR.

 -- Function: set-face-stipple face pattern &optional frame
     This function sets the `:stipple' attribute of FACE to PATTERN.

 -- Function: set-face-font face font &optional frame
     This function sets the `:font' attribute of FACE to FONT.

 -- Function: set-face-bold-p face bold-p &optional frame
     This function sets the `:weight' attribute of FACE to NORMAL if
     BOLD-P is `nil', and to BOLD otherwise.

 -- Function: set-face-italic-p face italic-p &optional frame
     This function sets the `:slant' attribute of FACE to NORMAL if
     ITALIC-P is `nil', and to ITALIC otherwise.

 -- Function: set-face-underline-p face underline &optional frame
     This function sets the `:underline' attribute of FACE to UNDERLINE.

 -- Function: set-face-inverse-video-p face inverse-video-p &optional
          frame
     This function sets the `:inverse-video' attribute of FACE to
     INVERSE-VIDEO-P.

 -- Function: invert-face face &optional frame
     This function swaps the foreground and background colors of face
     FACE.

   The following functions examine the attributes of a face.  If you
don't specify FRAME, they refer to the selected frame; `t' refers to
the default data for new frames.  They return the symbol `unspecified'
if the face doesn't define any value for that attribute.

 -- Function: face-foreground face &optional frame inherit
 -- Function: face-background face &optional frame inherit
     These functions return the foreground color (or background color,
     respectively) of face FACE, as a string.

     If INHERIT is `nil', only a color directly defined by the face is
     returned.  If INHERIT is non-`nil', any faces specified by its
     `:inherit' attribute are considered as well, and if INHERIT is a
     face or a list of faces, then they are also considered, until a
     specified color is found.  To ensure that the return value is
     always specified, use a value of `default' for INHERIT.

 -- Function: face-stipple face &optional frame inherit
     This function returns the name of the background stipple pattern
     of face FACE, or `nil' if it doesn't have one.

     If INHERIT is `nil', only a stipple directly defined by the face
     is returned.  If INHERIT is non-`nil', any faces specified by its
     `:inherit' attribute are considered as well, and if INHERIT is a
     face or a list of faces, then they are also considered, until a
     specified stipple is found.  To ensure that the return value is
     always specified, use a value of `default' for INHERIT.

 -- Function: face-font face &optional frame
     This function returns the name of the font of face FACE.

 -- Function: face-bold-p face &optional frame
     This function returns a non-`nil' value if the `:weight' attribute
     of FACE is bolder than normal (i.e., one of `semi-bold', `bold',
     `extra-bold', or `ultra-bold').  Otherwise, it returns `nil'.

 -- Function: face-italic-p face &optional frame
     This function returns a non-`nil' value if the `:slant' attribute
     of FACE is `italic' or `oblique', and `nil' otherwise.

 -- Function: face-underline-p face &optional frame
     This function returns the `:underline' attribute of face FACE.

 -- Function: face-inverse-video-p face &optional frame
     This function returns the `:inverse-video' attribute of face FACE.


File: elisp,  Node: Displaying Faces,  Next: Face Remapping,  Prev: Attribute Functions,  Up: Faces

38.12.4 Displaying Faces
------------------------

Here is how Emacs determines the face to use for displaying any given
piece of text:

   * If the text consists of a special glyph, the glyph can specify a
     particular face.  *Note Glyphs::.

   * If the text lies within an active region, Emacs highlights it using
     the `region' face.  *Note Standard Faces: (emacs)Standard Faces.

   * If the text lies within an overlay with a non-`nil' `face'
     property, Emacs applies the face or face attributes specified by
     that property.  If the overlay has a `mouse-face' property and the
     mouse is "near enough" to the overlay, Emacs applies the face or
     face attributes specified by the `mouse-face' property instead.
     *Note Overlay Properties::.

     When multiple overlays cover one character, an overlay with higher
     priority overrides those with lower priority.  *Note Overlays::.

   * If the text contains a `face' or `mouse-face' property, Emacs
     applies the specified faces and face attributes.  *Note Special
     Properties::.  (This is how Font Lock mode faces are applied.
     *Note Font Lock Mode::.)

   * If the text lies within the mode line of the selected window, Emacs
     applies the `mode-line' face.  For the mode line of a non-selected
     window, Emacs applies the `mode-line-inactive' face.  For a header
     line, Emacs applies the `header-line' face.

   * If any given attribute has not been specified during the preceding
     steps, Emacs applies the attribute of the `default' face.

   If these various sources together specify more than one face for a
particular character, Emacs merges the attributes of the various faces
specified.  For each attribute, Emacs tries using the above order
(i.e., first the face of any special glyph; then the face for region
highlighting, if appropriate; then faces specified by overlays, then
faces specified by text properties, then the `mode-line' or
`mode-line-inactive' or `header-line' face, if appropriate, and finally
the `default' face).


File: elisp,  Node: Face Remapping,  Next: Face Functions,  Prev: Displaying Faces,  Up: Faces

38.12.5 Face Remapping
----------------------

The variable `face-remapping-alist' is used for buffer-local or global
changes in the appearance of a face.  For instance, it can be used to
make the `default' face a variable-pitch face within a particular
buffer.

 -- Variable: face-remapping-alist
     An alist whose elements have the form `(FACE REMAPPING...)'.  This
     causes Emacs to display text using the face FACE using
     REMAPPING... instead of FACE's ordinary definition.  REMAPPING...
     may be any face specification suitable for a `face' text property:
     either a face name, or a property list of attribute/value pairs.
     *Note Special Properties::.

     If `face-remapping-alist' is buffer-local, its local value takes
     effect only within that buffer.

     Two points bear emphasizing:

       1. The new definition REMAPPING... is the complete specification
          of how to display FACE--it entirely replaces, rather than
          augmenting or modifying, the normal definition of that face.

       2. If REMAPPING... recursively references the same face name
          FACE, either directly remapping entry, or via the `:inherit'
          attribute of some other face in REMAPPING..., then that
          reference uses the normal definition of FACE in the selected
          frame, instead of the "remapped" definition.

          For instance, if the `mode-line' face is remapped using this
          entry in `face-remapping-alist':
               (mode-line italic mode-line)
          then the new definition of the `mode-line' face inherits from
          the `italic' face, and the _normal_ (non-remapped) definition
          of `mode-line' face.

   A typical use of the `face-remapping-alist' is to change a buffer's
`default' face; for example, the following changes a buffer's `default'
face to use the `variable-pitch' face, with the height doubled:

     (set (make-local-variable 'face-remapping-alist)
          '((default variable-pitch :height 2.0)))

   The following functions implement a higher-level interface to
`face-remapping-alist', making it easier to use "cooperatively".  They
are mainly intended for buffer-local use, and so all make
`face-remapping-alist' variable buffer-local as a side-effect.  They
use entries in `face-remapping-alist' which have the general form:

       (FACE RELATIVE_SPECS_1 RELATIVE_SPECS_2 ... BASE_SPECS)

   Everything except FACE is a "face spec": a list of face names or
face attribute-value pairs.  All face specs are merged together, with
earlier values taking precedence.

   The RELATIVE_SPECS_n values are "relative specs", and are added by
`face-remap-add-relative' (and removed by `face-remap-remove-relative'.
These are intended for face modifications (such as increasing the
size).  Typical users of these relative specs would be minor modes.

   BASE_SPECS is the lowest-priority value, and by default is just the
face name, which causes the global definition of that face to be used.

   A non-default value of BASE_SPECS may also be set using
`face-remap-set-base'.  Because this _overwrites_ the default base-spec
value (which inherits the global face definition), it is up to the
caller of `face-remap-set-base' to add such inheritance if it is
desired.  A typical use of `face-remap-set-base' would be a major mode
adding a face remappings, e.g., of the default face.

 -- Function: face-remap-add-relative face &rest specs
     This functions adds a face remapping entry of FACE to SPECS in the
     current buffer.

     It returns a "cookie" which can be used to later delete the
     remapping with `face-remap-remove-relative'.

     SPECS can be any value suitable for the `face' text property,
     including a face name, a list of face names, or a face-attribute
     property list.  The attributes given by SPECS will be merged with
     any other currently active face remappings of FACE, and with the
     global definition of FACE (by default; this may be changed using
     `face-remap-set-base'), with the most recently added relative
     remapping taking precedence.

 -- Function: face-remap-remove-relative cookie
     This function removes a face remapping previously added by
     `face-remap-add-relative'.  COOKIE should be a return value from
     that function.

 -- Function: face-remap-set-base face &rest specs
     This function sets the "base remapping" of FACE in the current
     buffer to SPECS.  If SPECS is empty, the default base remapping is
     restored, which inherits from the global definition of FACE; note
     that this is different from SPECS containing a single value `nil',
     which has the opposite result (the global definition of FACE is
     ignored).

 -- Function: face-remap-reset-base face
     This function sets the "base remapping" of FACE to its default
     value, which inherits from FACE's global definition.


File: elisp,  Node: Face Functions,  Next: Auto Faces,  Prev: Face Remapping,  Up: Faces

38.12.6 Functions for Working with Faces
----------------------------------------

Here are additional functions for creating and working with faces.

 -- Function: make-face name
     This function defines a new face named NAME, initially with all
     attributes `nil'.  It does nothing if there is already a face named
     NAME.

 -- Function: face-list
     This function returns a list of all defined face names.

 -- Function: copy-face old-face new-name &optional frame new-frame
     This function defines a face named NEW-NAME as a copy of the
     existing face named OLD-FACE.  It creates the face NEW-NAME if that
     doesn't already exist.

     If the optional argument FRAME is given, this function applies
     only to that frame.  Otherwise it applies to each frame
     individually, copying attributes from OLD-FACE in each frame to
     NEW-FACE in the same frame.

     If the optional argument NEW-FRAME is given, then `copy-face'
     copies the attributes of OLD-FACE in FRAME to NEW-NAME in
     NEW-FRAME.

 -- Function: face-id face
     This function returns the "face number" of face FACE.  This is a
     number that uniquely identifies a face at low levels within Emacs.
     It is seldom necessary to refer to a face by its face number.

 -- Function: face-documentation face
     This function returns the documentation string of face FACE, or
     `nil' if none was specified for it.

 -- Function: face-equal face1 face2 &optional frame
     This returns `t' if the faces FACE1 and FACE2 have the same
     attributes for display.

 -- Function: face-differs-from-default-p face &optional frame
     This returns non-`nil' if the face FACE displays differently from
     the default face.

   A "face alias" provides an equivalent name for a face.  You can
define a face alias by giving the alias symbol the `face-alias'
property, with a value of the target face name.  The following example
makes `modeline' an alias for the `mode-line' face.

     (put 'modeline 'face-alias 'mode-line)

 -- Function: define-obsolete-face-alias obsolete-face current-face
          &optional when
     This function defines a face alias and marks it as obsolete,
     indicating that it may be removed in future.  The optional string
     WHEN indicates when the face was made obsolete (for example, a
     release number).


File: elisp,  Node: Auto Faces,  Next: Font Selection,  Prev: Face Functions,  Up: Faces

38.12.7 Automatic Face Assignment
---------------------------------

This hook is used for automatically assigning faces to text in the
buffer.  It is part of the implementation of Jit-Lock mode, used by
Font-Lock.

 -- Variable: fontification-functions
     This variable holds a list of functions that are called by Emacs
     redisplay as needed, just before doing redisplay.  They are called
     even when Font Lock Mode isn't enabled.  When Font Lock Mode is
     enabled, this variable usually holds just one function,
     `jit-lock-function'.

     The functions are called in the order listed, with one argument, a
     buffer position POS.  Collectively they should attempt to assign
     faces to the text in the current buffer starting at POS.

     The functions should record the faces they assign by setting the
     `face' property.  They should also add a non-`nil' `fontified'
     property to all the text they have assigned faces to.  That
     property tells redisplay that faces have been assigned to that text
     already.

     It is probably a good idea for the functions to do nothing if the
     character after POS already has a non-`nil' `fontified' property,
     but this is not required.  If one function overrides the
     assignments made by a previous one, the properties after the last
     function finishes are the ones that really matter.

     For efficiency, we recommend writing these functions so that they
     usually assign faces to around 400 to 600 characters at each call.


File: elisp,  Node: Font Selection,  Next: Font Lookup,  Prev: Auto Faces,  Up: Faces

38.12.8 Font Selection
----------------------

Before Emacs can draw a character on a particular display, it must
select a "font" for that character(1).  Normally, Emacs automatically
chooses a font based on the faces assigned to that
character--specifically, the face attributes `:family', `:weight',
`:slant', and `:width' (*note Face Attributes::).  The choice of font
also depends on the character to be displayed; some fonts can only
display a limited set of characters.  If no available font exactly fits
the requirements, Emacs looks for the "closest matching font".  The
variables in this section control how Emacs makes this selection.

 -- User Option: face-font-family-alternatives
     If a given family is specified but does not exist, this variable
     specifies alternative font families to try.  Each element should
     have this form:

          (FAMILY ALTERNATE-FAMILIES...)

     If FAMILY is specified but not available, Emacs will try the other
     families given in ALTERNATE-FAMILIES, one by one, until it finds a
     family that does exist.

 -- User Option: face-font-selection-order
     If there is no font that exactly matches all desired face
     attributes (`:width', `:height', `:weight', and `:slant'), this
     variable specifies the order in which these attributes should be
     considered when selecting the closest matching font.  The value
     should be a list containing those four attribute symbols, in order
     of decreasing importance.  The default is `(:width :height :weight
     :slant)'.

     Font selection first finds the best available matches for the first
     attribute in the list; then, among the fonts which are best in that
     way, it searches for the best matches in the second attribute, and
     so on.

     The attributes `:weight' and `:width' have symbolic values in a
     range centered around `normal'.  Matches that are more extreme
     (farther from `normal') are somewhat preferred to matches that are
     less extreme (closer to `normal'); this is designed to ensure that
     non-normal faces contrast with normal ones, whenever possible.

     One example of a case where this variable makes a difference is
     when the default font has no italic equivalent.  With the default
     ordering, the `italic' face will use a non-italic font that is
     similar to the default one.  But if you put `:slant' before
     `:height', the `italic' face will use an italic font, even if its
     height is not quite right.

 -- User Option: face-font-registry-alternatives
     This variable lets you specify alternative font registries to try,
     if a given registry is specified and doesn't exist.  Each element
     should have this form:

          (REGISTRY ALTERNATE-REGISTRIES...)

     If REGISTRY is specified but not available, Emacs will try the
     other registries given in ALTERNATE-REGISTRIES, one by one, until
     it finds a registry that does exist.

   Emacs can make use of scalable fonts, but by default it does not use
them.

 -- User Option: scalable-fonts-allowed
     This variable controls which scalable fonts to use.  A value of
     `nil', the default, means do not use scalable fonts.  `t' means to
     use any scalable font that seems appropriate for the text.

     Otherwise, the value must be a list of regular expressions.  Then a
     scalable font is enabled for use if its name matches any regular
     expression in the list.  For example,

          (setq scalable-fonts-allowed '("muleindian-2$"))

     allows the use of scalable fonts with registry `muleindian-2'.

 -- Variable: face-font-rescale-alist
     This variable specifies scaling for certain faces.  Its value
     should be a list of elements of the form

          (FONTNAME-REGEXP . SCALE-FACTOR)

     If FONTNAME-REGEXP matches the font name that is about to be used,
     this says to choose a larger similar font according to the factor
     SCALE-FACTOR.  You would use this feature to normalize the font
     size if certain fonts are bigger or smaller than their nominal
     heights and widths would suggest.

   ---------- Footnotes ----------

   (1) In this context, the term "font" has nothing to do with Font
Lock (*note Font Lock Mode::).


File: elisp,  Node: Font Lookup,  Next: Fontsets,  Prev: Font Selection,  Up: Faces

38.12.9 Looking Up Fonts
------------------------

 -- Function: x-list-fonts name &optional reference-face frame maximum
          width
     This function returns a list of available font names that match
     NAME.  NAME should be a string containing a font name in either
     the Fontconfig, GTK, or XLFD format (*note Font Specification
     Options: (emacs)Font X.).  Within an XLFD string, wildcard
     characters may be used: the `*' character matches any substring,
     and the `?' character matches any single character.  Case is
     ignored when matching font names.

     If the optional arguments REFERENCE-FACE and FRAME are specified,
     the returned list includes only fonts that are the same size as
     REFERENCE-FACE (a face name) currently is on the frame FRAME.

     The optional argument MAXIMUM sets a limit on how many fonts to
     return.  If it is non-`nil', then the return value is truncated
     after the first MAXIMUM matching fonts.  Specifying a small value
     for MAXIMUM can make this function much faster, in cases where
     many fonts match the pattern.

     The optional argument WIDTH specifies a desired font width.  If it
     is non-`nil', the function only returns those fonts whose
     characters are (on average) WIDTH times as wide as REFERENCE-FACE.

 -- Function: x-family-fonts &optional family frame
     This function returns a list describing the available fonts for
     family FAMILY on FRAME.  If FAMILY is omitted or `nil', this list
     applies to all families, and therefore, it contains all available
     fonts.  Otherwise, FAMILY must be a string; it may contain the
     wildcards `?' and `*'.

     The list describes the display that FRAME is on; if FRAME is
     omitted or `nil', it applies to the selected frame's display
     (*note Input Focus::).

     Each element in the list is a vector of the following form:

          [FAMILY WIDTH POINT-SIZE WEIGHT SLANT
           FIXED-P FULL REGISTRY-AND-ENCODING]

     The first five elements correspond to face attributes; if you
     specify these attributes for a face, it will use this font.

     The last three elements give additional information about the font.
     FIXED-P is non-`nil' if the font is fixed-pitch.  FULL is the full
     name of the font, and REGISTRY-AND-ENCODING is a string giving the
     registry and encoding of the font.

 -- Variable: font-list-limit
     This variable specifies maximum number of fonts to consider in font
     matching.  The function `x-family-fonts' will not return more than
     that many fonts, and font selection will consider only that many
     fonts when searching a matching font for face attributes.  The
     default is currently 100.


File: elisp,  Node: Fontsets,  Next: Low-Level Font,  Prev: Font Lookup,  Up: Faces

38.12.10 Fontsets
-----------------

A "fontset" is a list of fonts, each assigned to a range of character
codes.  An individual font cannot display the whole range of characters
that Emacs supports, but a fontset can.  Fontsets have names, just as
fonts do, and you can use a fontset name in place of a font name when
you specify the "font" for a frame or a face.  Here is information
about defining a fontset under Lisp program control.

 -- Function: create-fontset-from-fontset-spec fontset-spec &optional
          style-variant-p noerror
     This function defines a new fontset according to the specification
     string FONTSET-SPEC.  The string should have this format:

          FONTPATTERN, [CHARSET:FONT]...

     Whitespace characters before and after the commas are ignored.

     The first part of the string, FONTPATTERN, should have the form of
     a standard X font name, except that the last two fields should be
     `fontset-ALIAS'.

     The new fontset has two names, one long and one short.  The long
     name is FONTPATTERN in its entirety.  The short name is
     `fontset-ALIAS'.  You can refer to the fontset by either name.  If
     a fontset with the same name already exists, an error is signaled,
     unless NOERROR is non-`nil', in which case this function does
     nothing.

     If optional argument STYLE-VARIANT-P is non-`nil', that says to
     create bold, italic and bold-italic variants of the fontset as
     well.  These variant fontsets do not have a short name, only a
     long one, which is made by altering FONTPATTERN to indicate the
     bold or italic status.

     The specification string also says which fonts to use in the
     fontset.  See below for the details.

   The construct `CHARSET:FONT' specifies which font to use (in this
fontset) for one particular character set.  Here, CHARSET is the name
of a character set, and FONT is the font to use for that character set.
You can use this construct any number of times in the specification
string.

   For the remaining character sets, those that you don't specify
explicitly, Emacs chooses a font based on FONTPATTERN: it replaces
`fontset-ALIAS' with a value that names one character set.  For the
ASCII character set, `fontset-ALIAS' is replaced with `ISO8859-1'.

   In addition, when several consecutive fields are wildcards, Emacs
collapses them into a single wildcard.  This is to prevent use of
auto-scaled fonts.  Fonts made by scaling larger fonts are not usable
for editing, and scaling a smaller font is not useful because it is
better to use the smaller font in its own size, which Emacs does.

   Thus if FONTPATTERN is this,

     -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24

the font specification for ASCII characters would be this:

     -*-fixed-medium-r-normal-*-24-*-ISO8859-1

and the font specification for Chinese GB2312 characters would be this:

     -*-fixed-medium-r-normal-*-24-*-gb2312*-*

   You may not have any Chinese font matching the above font
specification.  Most X distributions include only Chinese fonts that
have `song ti' or `fangsong ti' in the FAMILY field.  In such a case,
`Fontset-N' can be specified as below:

     Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
             chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*

Then, the font specifications for all but Chinese GB2312 characters have
`fixed' in the FAMILY field, and the font specification for Chinese
GB2312 characters has a wild card `*' in the FAMILY field.

 -- Function: set-fontset-font name character font-spec &optional frame
          add
     This function modifies the existing fontset NAME to use the font
     matching with FONT-SPEC for the character CHARACTER.

     If NAME is `nil', this function modifies the fontset of the
     selected frame or that of FRAME if FRAME is not `nil'.

     If NAME is `t', this function modifies the default fontset, whose
     short name is `fontset-default'.

     CHARACTER may be a cons; `(FROM . TO)', where FROM and TO are
     character codepoints.  In that case, use FONT-SPEC for all
     characters in the range FROM and TO (inclusive).

     CHARACTER may be a charset.  In that case, use FONT-SPEC for all
     character in the charsets.

     CHARACTER may be a script name.  In that case, use FONT-SPEC for
     all character in the charsets.

     FONT-SPEC may be a cons; `(FAMILY . REGISTRY)', where FAMILY is a
     family name of a font (possibly including a foundry name at the
     head), REGISTRY is a registry name of a font (possibly including
     an encoding name at the tail).

     FONT-SPEC may be a font name string.

     The optional argument ADD, if non-`nil', specifies how to add
     FONT-SPEC to the font specifications previously set.  If it is
     `prepend', FONT-SPEC is prepended.  If it is `append', FONT-SPEC
     is appended.  By default, FONT-SPEC overrides the previous
     settings.

     For instance, this changes the default fontset to use a font of
     which family name is `Kochi Gothic' for all characters belonging to
     the charset `japanese-jisx0208'.

          (set-fontset-font t 'japanese-jisx0208
                            (font-spec :family "Kochi Gothic"))

 -- Function: char-displayable-p char
     This function returns `t' if Emacs ought to be able to display
     CHAR.  More precisely, if the selected frame's fontset has a font
     to display the character set that CHAR belongs to.

     Fontsets can specify a font on a per-character basis; when the
     fontset does that, this function's value may not be accurate.


File: elisp,  Node: Low-Level Font,  Prev: Fontsets,  Up: Faces

38.12.11 Low-Level Font Representation
--------------------------------------

Normally, it is not necessary to manipulate fonts directly.  In case
you need to do so, this section explains how.

   In Emacs Lisp, fonts are represented using three different Lisp
object types: "font objects", "font specs", and "font entities".

 -- Function: fontp object &optional type
     Return `t' if OBJECT is a font object, font spec, or font entity.
     Otherwise, return `nil'.

     The optional argument TYPE, if non-`nil', determines the exact
     type of Lisp object to check for.  In that case, TYPE should be
     one of `font-object', `font-spec', or `font-entity'.

   A font object is a Lisp object that represents a font that Emacs has
"opened".  Font objects cannot be modified in Lisp, but they can be
inspected.

 -- Function: font-at position &optional window string
     Return the font object that is being used to display the character
     at position POSITION in the window WINDOW.  If WINDOW is `nil', it
     defaults to the selected window.  If STRING is `nil', POSITION
     specifies a position in the current buffer; otherwise, STRING
     should be a string, and POSITION specifies a position in that
     string.

   A font spec is a Lisp object that contains a set of specifications
that can be used to find a font.  More than one font may match the
specifications in a font spec.

 -- Function: font-spec &rest arguments
     Return a new font spec using the specifications in ARGUMENTS,
     which should come in `property'-`value' pairs.  The possible
     specifications are as follows:

    `:name'
          The font name (a string), in either XLFD, Fontconfig, or GTK
          format.  *Note Font Specification Options: (emacs)Font X.

    `:family'
    `:foundry'
    `:weight'
    `:slant'
    `:width'
          These have the same meanings as the face attributes of the
          same name.  *Note Face Attributes::.

    `:size'
          The font size--either a non-negative integer that specifies
          the pixel size, or a floating point number that specifies the
          point size.

    `:adstyle'
          Additional typographic style information for the font, such as
          `sans'.  The value should be a string or a symbol.

    `:registry'
          The charset registry and encoding of the font, such as
          `iso8859-1'.  The value should be a string or a symbol.

    `:script'
          The script that the font must support (a symbol).

    `:otf'
          The font must be an OpenType font that supports these OpenType
          features, provided Emacs is compiled with support for
          `libotf' (a library for performing complex text layout in
          certain scripts).  The value must be a list of the form

               `(SCRIPT-TAG LANGSYS-TAG GSUB GPOS)'

          where SCRIPT-TAG is the OpenType script tag symbol;
          LANGSYS-TAG is the OpenType language system tag symbol, or
          `nil' to use the default language system; `gsub' is a list of
          OpenType GSUB feature tag symbols, or `nil' if none is
          required; and `gpos' is a list of OpenType GPOS feature tag
          symbols, or `nil' if none is required.  If `gsub' or `gpos'
          is a list, a `nil' element in that list means that the font
          must not match any of the remaining tag symbols.  The `gpos'
          element may be omitted.

 -- Function: font-put font-spec property value
     Set the font property PROPERTY in the font-spec FONT-SPEC to VALUE.

   A font entity is a reference to a font that need not be open.  Its
properties are intermediate between a font object and a font spec: like
a font object, and unlike a font spec, it refers to a single, specific
font.  Unlike a font object, creating a font entity does not load the
contents of that font into computer memory.

 -- Function: find-font font-spec &optional frame
     This function returns a font entity that best matches the font spec
     FONT-SPEC on frame FRAME.  If FRAME is `nil', it defaults to the
     selected frame.

 -- Function: list-fonts font-spec &optional frame num prefer
     This function returns a list of all font entities that match the
     font spec FONT-SPEC.

     The optional argument FRAME, if non-`nil', specifies the frame on
     which the fonts are to be displayed.  The optional argument NUM,
     if non-`nil', should be an integer that specifies the maximum
     length of the returned list.  The optional argument PREFER, if
     non-`nil', should be another font spec, which is used to control
     the order of the returned list; the returned font entities are
     sorted in order of decreasing "closeness" to that font spec.

   If you call `set-face-attribute' and pass a font spec, font entity,
or font name string as the value of the `:font' attribute, Emacs opens
the best "matching" font that is available for display.  It then stores
the corresponding font object as the actual value of the `:font'
attribute for that face.

   The following functions can be used to obtain information about a
font.  For these functions, the FONT argument can be a font object, a
font entity, or a font spec.

 -- Function: font-get font property
     This function returns the value of the font property PROPERTY for
     FONT.

     If FONT is a font spec and the font spec does not specify
     PROPERTY, the return value is `nil'.  If FONT is a font object or
     font entity, the value for the :SCRIPT property may be a list of
     scripts supported by the font.

 -- Function: font-face-attributes font &optional frame
     This function returns a list of face attributes corresponding to
     FONT.  The optional argument FRAME specifies the frame on which
     the font is to be displayed.  If it is `nil', the selected frame
     is used.  The return value has the form

          (:family FAMILY :height HEIGHT :weight WEIGHT
             :slant SLANT :width WIDTH)

     where the values of FAMILY, HEIGHT, WEIGHT, SLANT, and WIDTH are
     face attribute values.  Some of these key-attribute pairs may be
     omitted from the list if they are not specified by FONT.

 -- Function: font-xlfd-name font &optional fold-wildcards
     This function returns the XLFD (X Logical Font Descriptor), a
     string, matching FONT.  *Note Font Specification Options:
     (emacs)Font X, for information about XLFDs.  If the name is too
     long for an XLFD (which can contain at most 255 characters), the
     function returns `nil'.

     If the optional argument FOLD-WILDCARDS is non-`nil', consecutive
     wildcards in the XLFD are folded into one.


File: elisp,  Node: Fringes,  Next: Scroll Bars,  Prev: Faces,  Up: Display

38.13 Fringes
=============

The "fringes" of a window are thin vertical strips down the sides that
are used for displaying bitmaps that indicate truncation, continuation,
horizontal scrolling, and the overlay arrow.

* Menu:

* Fringe Size/Pos::     Specifying where to put the window fringes.
* Fringe Indicators::   Displaying indicator icons in the window fringes.
* Fringe Cursors::      Displaying cursors in the right fringe.
* Fringe Bitmaps::      Specifying bitmaps for fringe indicators.
* Customizing Bitmaps:: Specifying your own bitmaps to use in the fringes.
* Overlay Arrow::       Display of an arrow to indicate position.


File: elisp,  Node: Fringe Size/Pos,  Next: Fringe Indicators,  Up: Fringes

38.13.1 Fringe Size and Position
--------------------------------

The following buffer-local variables control the position and width of
the window fringes.

 -- Variable: fringes-outside-margins
     The fringes normally appear between the display margins and the
     window text.  If the value is non-`nil', they appear outside the
     display margins.  *Note Display Margins::.

 -- Variable: left-fringe-width
     This variable, if non-`nil', specifies the width of the left
     fringe in pixels.  A value of `nil' means to use the left fringe
     width from the window's frame.

 -- Variable: right-fringe-width
     This variable, if non-`nil', specifies the width of the right
     fringe in pixels.  A value of `nil' means to use the right fringe
     width from the window's frame.

   The values of these variables take effect when you display the
buffer in a window.  If you change them while the buffer is visible,
you can call `set-window-buffer' to display it once again in the same
window, to make the changes take effect.

 -- Function: set-window-fringes window left &optional right
          outside-margins
     This function sets the fringe widths of window WINDOW.  If WINDOW
     is `nil', the selected window is used.

     The argument LEFT specifies the width in pixels of the left
     fringe, and likewise RIGHT for the right fringe.  A value of `nil'
     for either one stands for the default width.  If OUTSIDE-MARGINS
     is non-`nil', that specifies that fringes should appear outside of
     the display margins.

 -- Function: window-fringes &optional window
     This function returns information about the fringes of a window
     WINDOW.  If WINDOW is omitted or `nil', the selected window is
     used.  The value has the form `(LEFT-WIDTH RIGHT-WIDTH
     OUTSIDE-MARGINS)'.


File: elisp,  Node: Fringe Indicators,  Next: Fringe Cursors,  Prev: Fringe Size/Pos,  Up: Fringes

38.13.2 Fringe Indicators
-------------------------

The "fringe indicators" are tiny icons Emacs displays in the window
fringe (on a graphic display) to indicate truncated or continued lines,
buffer boundaries, overlay arrow, etc.

 -- User Option: indicate-empty-lines
     When this is non-`nil', Emacs displays a special glyph in the
     fringe of each empty line at the end of the buffer, on graphical
     displays.  *Note Fringes::.  This variable is automatically
     buffer-local in every buffer.

 -- User Option: indicate-buffer-boundaries
     This buffer-local variable controls how the buffer boundaries and
     window scrolling are indicated in the window fringes.

     Emacs can indicate the buffer boundaries--that is, the first and
     last line in the buffer--with angle icons when they appear on the
     screen.  In addition, Emacs can display an up-arrow in the fringe
     to show that there is text above the screen, and a down-arrow to
     show there is text below the screen.

     There are three kinds of basic values:

    `nil'
          Don't display any of these fringe icons.

    `left'
          Display the angle icons and arrows in the left fringe.

    `right'
          Display the angle icons and arrows in the right fringe.

    any non-alist
          Display the angle icons in the left fringe and don't display
          the arrows.

     Otherwise the value should be an alist that specifies which fringe
     indicators to display and where.  Each element of the alist should
     have the form `(INDICATOR . POSITION)'.  Here, INDICATOR is one of
     `top', `bottom', `up', `down', and `t' (which covers all the icons
     not yet specified), while POSITION is one of `left', `right' and
     `nil'.

     For example, `((top . left) (t . right))' places the top angle
     bitmap in left fringe, and the bottom angle bitmap as well as both
     arrow bitmaps in right fringe.  To show the angle bitmaps in the
     left fringe, and no arrow bitmaps, use `((top .  left) (bottom .
     left))'.

 -- Variable: fringe-indicator-alist
     This buffer-local variable specifies the mapping from logical
     fringe indicators to the actual bitmaps displayed in the window
     fringes.

     These symbols identify the logical fringe indicators:

    Truncation and continuation line indicators:
          `truncation', `continuation'.

    Buffer position indicators:
          `up', `down', `top', `bottom', `top-bottom'.

    Empty line indicator:
          `empty-line'.

    Overlay arrow indicator:
          `overlay-arrow'.

    Unknown bitmap indicator:
          `unknown'.

     The value is an alist where each element `(INDICATOR . BITMAPS)'
     specifies the fringe bitmaps used to display a specific logical
     fringe indicator.

     Here, INDICATOR specifies the logical indicator type, and BITMAPS
     is list of symbols `(LEFT RIGHT [LEFT1 RIGHT1])' which specifies
     the actual bitmap shown in the left or right fringe for the
     logical indicator.

     The LEFT and RIGHT symbols specify the bitmaps shown in the left
     and/or right fringe for the specific indicator.  The LEFT1 or
     RIGHT1 bitmaps are used only for the `bottom' and `top-bottom
     indicators when the last (only) line in has no final newline.
     Alternatively, BITMAPS may be a single symbol which is used in
     both left and right fringes.

     When `fringe-indicator-alist' has a buffer-local value, and there
     is no bitmap defined for a logical indicator, or the bitmap is
     `t', the corresponding value from the default value of
     `fringe-indicator-alist' is used.

     To completely hide a specific indicator, set the bitmap to `nil'.

   Standard fringe bitmaps for indicators:
     left-arrow right-arrow up-arrow down-arrow
     left-curly-arrow right-curly-arrow
     left-triangle right-triangle
     top-left-angle top-right-angle
     bottom-left-angle bottom-right-angle
     left-bracket right-bracket
     filled-rectangle hollow-rectangle
     filled-square hollow-square
     vertical-bar horizontal-bar
     empty-line question-mark


File: elisp,  Node: Fringe Cursors,  Next: Fringe Bitmaps,  Prev: Fringe Indicators,  Up: Fringes

38.13.3 Fringe Cursors
----------------------

When a line is exactly as wide as the window, Emacs displays the cursor
in the right fringe instead of using two lines.  Different bitmaps are
used to represent the cursor in the fringe depending on the current
buffer's cursor type.

Logical cursor types:
     `box' , `hollow', `bar', `hbar', `hollow-small'.

   The `hollow-small' type is used instead of `hollow' when the normal
`hollow-rectangle' bitmap is too tall to fit on a specific display line.

 -- User Option: overflow-newline-into-fringe
     If this is non-`nil', lines exactly as wide as the window (not
     counting the final newline character) are not continued.  Instead,
     when point is at the end of the line, the cursor appears in the
     right fringe.

 -- Variable: fringe-cursor-alist
     This variable specifies the mapping from logical cursor type to the
     actual fringe bitmaps displayed in the right fringe.  The value is
     an alist where each element `(CURSOR . BITMAP)' specifies the
     fringe bitmaps used to display a specific logical cursor type in
     the fringe.  Here, CURSOR specifies the logical cursor type and
     BITMAP is a symbol specifying the fringe bitmap to be displayed
     for that logical cursor type.

     When `fringe-cursor-alist' has a buffer-local value, and there is
     no bitmap defined for a cursor type, the corresponding value from
     the default value of `fringes-indicator-alist' is used.

   Standard bitmaps for displaying the cursor in right fringe:
     filled-rectangle hollow-rectangle filled-square hollow-square
     vertical-bar horizontal-bar


File: elisp,  Node: Fringe Bitmaps,  Next: Customizing Bitmaps,  Prev: Fringe Cursors,  Up: Fringes

38.13.4 Fringe Bitmaps
----------------------

The "fringe bitmaps" are the actual bitmaps which represent the logical
fringe indicators for truncated or continued lines, buffer boundaries,
overlay arrow, etc.  Fringe bitmap symbols have their own name space.
The fringe bitmaps are shared by all frames and windows.  You can
redefine the built-in fringe bitmaps, and you can define new fringe
bitmaps.

   The way to display a bitmap in the left or right fringes for a given
line in a window is by specifying the `display' property for one of the
characters that appears in it.  Use a display specification of the form
`(left-fringe BITMAP [FACE])' or `(right-fringe BITMAP [FACE])' (*note
Display Property::).  Here, BITMAP is a symbol identifying the bitmap
you want, and FACE (which is optional) is the name of the face whose
colors should be used for displaying the bitmap, instead of the default
`fringe' face.  FACE is automatically merged with the `fringe' face, so
normally FACE need only specify the foreground color for the bitmap.

 -- Function: fringe-bitmaps-at-pos &optional pos window
     This function returns the fringe bitmaps of the display line
     containing position POS in window WINDOW.  The return value has
     the form `(LEFT RIGHT OV)', where LEFT is the symbol for the
     fringe bitmap in the left fringe (or `nil' if no bitmap), RIGHT is
     similar for the right fringe, and OV is non-`nil' if there is an
     overlay arrow in the left fringe.

     The value is `nil' if POS is not visible in WINDOW.  If WINDOW is
     `nil', that stands for the selected window.  If POS is `nil', that
     stands for the value of point in WINDOW.


File: elisp,  Node: Customizing Bitmaps,  Next: Overlay Arrow,  Prev: Fringe Bitmaps,  Up: Fringes

38.13.5 Customizing Fringe Bitmaps
----------------------------------

 -- Function: define-fringe-bitmap bitmap bits &optional height width
          align
     This function defines the symbol BITMAP as a new fringe bitmap, or
     replaces an existing bitmap with that name.

     The argument BITS specifies the image to use.  It should be either
     a string or a vector of integers, where each element (an integer)
     corresponds to one row of the bitmap.  Each bit of an integer
     corresponds to one pixel of the bitmap, where the low bit
     corresponds to the rightmost pixel of the bitmap.

     The height is normally the length of BITS.  However, you can
     specify a different height with non-`nil' HEIGHT.  The width is
     normally 8, but you can specify a different width with non-`nil'
     WIDTH.  The width must be an integer between 1 and 16.

     The argument ALIGN specifies the positioning of the bitmap
     relative to the range of rows where it is used; the default is to
     center the bitmap.  The allowed values are `top', `center', or
     `bottom'.

     The ALIGN argument may also be a list `(ALIGN PERIODIC)' where
     ALIGN is interpreted as described above.  If PERIODIC is
     non-`nil', it specifies that the rows in `bits' should be repeated
     enough times to reach the specified height.

 -- Function: destroy-fringe-bitmap bitmap
     This function destroy the fringe bitmap identified by BITMAP.  If
     BITMAP identifies a standard fringe bitmap, it actually restores
     the standard definition of that bitmap, instead of eliminating it
     entirely.

 -- Function: set-fringe-bitmap-face bitmap &optional face
     This sets the face for the fringe bitmap BITMAP to FACE.  If FACE
     is `nil', it selects the `fringe' face.  The bitmap's face
     controls the color to draw it in.

     FACE is merged with the `fringe' face, so normally FACE should
     specify only the foreground color.


File: elisp,  Node: Overlay Arrow,  Prev: Customizing Bitmaps,  Up: Fringes

38.13.6 The Overlay Arrow
-------------------------

The "overlay arrow" is useful for directing the user's attention to a
particular line in a buffer.  For example, in the modes used for
interface to debuggers, the overlay arrow indicates the line of code
about to be executed.  This feature has nothing to do with "overlays"
(*note Overlays::).

 -- Variable: overlay-arrow-string
     This variable holds the string to display to call attention to a
     particular line, or `nil' if the arrow feature is not in use.  On
     a graphical display the contents of the string are ignored;
     instead a glyph is displayed in the fringe area to the left of the
     display area.

 -- Variable: overlay-arrow-position
     This variable holds a marker that indicates where to display the
     overlay arrow.  It should point at the beginning of a line.  On a
     non-graphical display the arrow text appears at the beginning of
     that line, overlaying any text that would otherwise appear.  Since
     the arrow is usually short, and the line usually begins with
     indentation, normally nothing significant is overwritten.

     The overlay-arrow string is displayed in any given buffer if the
     value of `overlay-arrow-position' in that buffer points into that
     buffer.  Thus, it is possible to display multiple overlay arrow
     strings by creating buffer-local bindings of
     `overlay-arrow-position'.  However, it is usually cleaner to use
     `overlay-arrow-variable-list' to achieve this result.

   You can do a similar job by creating an overlay with a
`before-string' property.  *Note Overlay Properties::.

   You can define multiple overlay arrows via the variable
`overlay-arrow-variable-list'.

 -- Variable: overlay-arrow-variable-list
     This variable's value is a list of variables, each of which
     specifies the position of an overlay arrow.  The variable
     `overlay-arrow-position' has its normal meaning because it is on
     this list.

   Each variable on this list can have properties
`overlay-arrow-string' and `overlay-arrow-bitmap' that specify an
overlay arrow string (for text-only terminals) or fringe bitmap (for
graphical terminals) to display at the corresponding overlay arrow
position.  If either property is not set, the default
`overlay-arrow-string' or `overlay-arrow' fringe indicator is used.


File: elisp,  Node: Scroll Bars,  Next: Display Property,  Prev: Fringes,  Up: Display

38.14 Scroll Bars
=================

Normally the frame parameter `vertical-scroll-bars' controls whether
the windows in the frame have vertical scroll bars, and whether they
are on the left or right.  The frame parameter `scroll-bar-width'
specifies how wide they are (`nil' meaning the default).  *Note Layout
Parameters::.

 -- Function: frame-current-scroll-bars &optional frame
     This function reports the scroll bar type settings for frame
     FRAME.  The value is a cons cell `(VERTICAL-TYPE .
     HORIZONTAL-TYPE)', where VERTICAL-TYPE is either `left', `right',
     or `nil' (which means no scroll bar.)  HORIZONTAL-TYPE is meant to
     specify the horizontal scroll bar type, but since they are not
     implemented, it is always `nil'.

   You can enable or disable scroll bars for a particular buffer, by
setting the variable `vertical-scroll-bar'.  This variable
automatically becomes buffer-local when set.  The possible values are
`left', `right', `t', which means to use the frame's default, and `nil'
for no scroll bar.

   You can also control this for individual windows.  Call the function
`set-window-scroll-bars' to specify what to do for a specific window:

 -- Function: set-window-scroll-bars window width &optional
          vertical-type horizontal-type
     This function sets the width and type of scroll bars for window
     WINDOW.

     WIDTH specifies the scroll bar width in pixels (`nil' means use
     the width specified for the frame).  VERTICAL-TYPE specifies
     whether to have a vertical scroll bar and, if so, where.  The
     possible values are `left', `right' and `nil', just like the
     values of the `vertical-scroll-bars' frame parameter.

     The argument HORIZONTAL-TYPE is meant to specify whether and where
     to have horizontal scroll bars, but since they are not
     implemented, it has no effect.  If WINDOW is `nil', the selected
     window is used.

 -- Function: window-scroll-bars &optional window
     Report the width and type of scroll bars specified for WINDOW.  If
     WINDOW is omitted or `nil', the selected window is used.  The
     value is a list of the form `(WIDTH COLS VERTICAL-TYPE
     HORIZONTAL-TYPE)'.  The value WIDTH is the value that was
     specified for the width (which may be `nil'); COLS is the number
     of columns that the scroll bar actually occupies.

     HORIZONTAL-TYPE is not actually meaningful.

   If you don't specify these values for a window with
`set-window-scroll-bars', the buffer-local variables `scroll-bar-mode'
and `scroll-bar-width' in the buffer being displayed control the
window's vertical scroll bars.  The function `set-window-buffer'
examines these variables.  If you change them in a buffer that is
already visible in a window, you can make the window take note of the
new values by calling `set-window-buffer' specifying the same buffer
that is already displayed.

 -- User Option: scroll-bar-mode
     This variable, always local in all buffers, controls whether and
     where to put scroll bars in windows displaying the buffer.  The
     possible values are `nil' for no scroll bar, `left' to put a
     scroll bar on the left, and `right' to put a scroll bar on the
     right.

 -- Function: window-current-scroll-bars &optional window
     This function reports the scroll bar type for window WINDOW.  If
     WINDOW is omitted or `nil', the selected window is used.  The
     value is a cons cell `(VERTICAL-TYPE . HORIZONTAL-TYPE)'.  Unlike
     `window-scroll-bars', this reports the scroll bar type actually
     used, once frame defaults and `scroll-bar-mode' are taken into
     account.

 -- Variable: scroll-bar-width
     This variable, always local in all buffers, specifies the width of
     the buffer's scroll bars, measured in pixels.  A value of `nil'
     means to use the value specified by the frame.


File: elisp,  Node: Display Property,  Next: Images,  Prev: Scroll Bars,  Up: Display

38.15 The `display' Property
============================

The `display' text property (or overlay property) is used to insert
images into text, and also control other aspects of how text displays.
The value of the `display' property should be a display specification,
or a list or vector containing several display specifications.  Display
specifications in the same `display' property value generally apply in
parallel to the text they cover.

   If several sources (overlays and/or a text property) specify values
for the `display' property, only one of the values takes effect,
following the rules of `get-char-property'.  *Note Examining
Properties::.

   The rest of this section describes several kinds of display
specifications and what they mean.

* Menu:

* Replacing Specs::      Display specs that replace the text.
* Specified Space::      Displaying one space with a specified width.
* Pixel Specification::  Specifying space width or height in pixels.
* Other Display Specs::     Displaying an image; adjusting the height,
                              spacing, and other properties of text.
* Display Margins::     Displaying text or images to the side of the main text.


File: elisp,  Node: Replacing Specs,  Next: Specified Space,  Up: Display Property

38.15.1 Display Specs That Replace The Text
-------------------------------------------

Some kinds of `display' specifications specify something to display
instead of the text that has the property.  These are called
"replacing" display specifications.  Emacs does not allow the user to
interactively move point into the middle of buffer text that is
replaced in this way.

   If a list of display specifications includes more than one replacing
display specification, the first overrides the rest.  Replacing display
specifications make most other display specifications irrelevant, since
those don't apply to the replacement.

   For replacing display specifications, "the text that has the
property" means all the consecutive characters that have the same Lisp
object as their `display' property; these characters are replaced as a
single unit.  By contrast, characters that have similar but distinct
Lisp objects as their `display' properties are handled separately.
Here's a function that illustrates this point:

     (defun foo ()
       (goto-char (point-min))
       (dotimes (i 5)
         (let ((string (concat "A")))
           (put-text-property (point) (1+ (point)) 'display string)
           (forward-char 1)
           (put-text-property (point) (1+ (point)) 'display string)
           (forward-char 1))))

It gives each of the first ten characters in the buffer string `"A"' as
the `display' property, but they don't all get the same string.  The
first two characters get the same string, so they together are replaced
with one `A'.  The next two characters get a second string, so they
together are replaced with one `A'.  Likewise for each following pair
of characters.  Thus, the ten characters appear as five A's.  This
function would have the same results:

     (defun foo ()
       (goto-char (point-min))
       (dotimes (i 5)
         (let ((string (concat "A")))
           (put-text-property (point) (+ 2 (point)) 'display string)
           (put-text-property (point) (1+ (point)) 'display string)
           (forward-char 2))))

This illustrates that what matters is the property value for each
character.  If two consecutive characters have the same object as the
`display' property value, it's irrelevant whether they got this
property from a single call to `put-text-property' or from two
different calls.


File: elisp,  Node: Specified Space,  Next: Pixel Specification,  Prev: Replacing Specs,  Up: Display Property

38.15.2 Specified Spaces
------------------------

To display a space of specified width and/or height, use a display
specification of the form `(space . PROPS)', where 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 _all_ of those
characters.  These are the properties you can use in PROPS to specify
the weight of the space:

`:width WIDTH'
     If WIDTH is an integer or floating point number, it specifies that
     the space width should be WIDTH times the normal character width.
     WIDTH can also be a "pixel width" specification (*note Pixel
     Specification::).

`:relative-width FACTOR'
     Specifies that the width of the stretch should be computed from the
     first character in the group of consecutive characters that have
     the same `display' property.  The space width is the width of that
     character, multiplied by FACTOR.

`:align-to HPOS'
     Specifies that the space should be wide enough to reach HPOS.  If
     HPOS is a number, it is measured in units of the normal character
     width.  HPOS can also be a "pixel width" specification (*note
     Pixel Specification::).

   You should use one and only one of the above properties.  You can
also specify the height of the space, with these properties:

`:height HEIGHT'
     Specifies the height of the space.  If HEIGHT is an integer or
     floating point number, it specifies that the space height should
     be HEIGHT times the normal character height.  The HEIGHT may also
     be a "pixel height" specification (*note Pixel Specification::).

`:relative-height FACTOR'
     Specifies the height of the space, multiplying the ordinary height
     of the text having this display specification by FACTOR.

`:ascent ASCENT'
     If the value of ASCENT is a non-negative number no greater than
     100, it specifies that ASCENT percent of the height of the space
     should be considered as the ascent of the space--that is, the part
     above the baseline.  The ascent may also be specified in pixel
     units with a "pixel ascent" specification (*note Pixel
     Specification::).


   Don't use both `:height' and `:relative-height' together.

   The `:width' and `:align-to' properties are supported on non-graphic
terminals, but the other space properties in this section are not.


File: elisp,  Node: Pixel Specification,  Next: Other Display Specs,  Prev: Specified Space,  Up: Display Property

38.15.3 Pixel Specification for Spaces
--------------------------------------

The value of the `:width', `:align-to', `:height', and `:ascent'
properties can be a special kind of expression that is evaluated during
redisplay.  The result of the evaluation is used as an absolute number
of pixels.

   The following expressions are supported:

       EXPR ::= NUM | (NUM) | UNIT | ELEM | POS | IMAGE | FORM
       NUM  ::= INTEGER | FLOAT | SYMBOL
       UNIT ::= in | mm | cm | width | height
       ELEM ::= left-fringe | right-fringe | left-margin | right-margin
             |  scroll-bar | text
       POS  ::= left | center | right
       FORM ::= (NUM . EXPR) | (OP EXPR ...)
       OP   ::= + | -

   The form NUM specifies a fraction of the default frame font height
or width.  The form `(NUM)' specifies an absolute number of pixels.  If
NUM is a symbol, SYMBOL, its buffer-local variable binding is used.

   The `in', `mm', and `cm' units specify the number of pixels per
inch, millimeter, and centimeter, respectively.  The `width' and
`height' units correspond to the default width and height of the
current face.  An image specification `image' corresponds to the width
or height of the image.

   The elements `left-fringe', `right-fringe', `left-margin',
`right-margin', `scroll-bar', and `text' specify to the width of the
corresponding area of the window.

   The `left', `center', and `right' positions can be used with
`:align-to' to specify a position relative to the left edge, center, or
right edge of the text area.

   Any of the above window elements (except `text') can also be used
with `:align-to' to specify that the position is relative to the left
edge of the given area.  Once the base offset for a relative position
has been set (by the first occurrence of one of these symbols), further
occurrences of these symbols are interpreted as the width of the
specified area.  For example, to align to the center of the
left-margin, use

     :align-to (+ left-margin (0.5 . left-margin))

   If no specific base offset is set for alignment, it is always
relative to the left edge of the text area.  For example, `:align-to 0'
in a header-line aligns with the first text column in the text area.

   A value of the form `(NUM . EXPR)' stands for the product of the
values of NUM and EXPR.  For example, `(2 . in)' specifies a width of 2
inches, while `(0.5 .  IMAGE)' specifies half the width (or height) of
the specified image.

   The form `(+ EXPR ...)' adds up the value of the expressions.  The
form `(- EXPR ...)' negates or subtracts the value of the expressions.


File: elisp,  Node: Other Display Specs,  Next: Display Margins,  Prev: Pixel Specification,  Up: Display Property

38.15.4 Other Display Specifications
------------------------------------

Here are the other sorts of display specifications that you can use in
the `display' text property.

`STRING'
     Display STRING instead of the text that has this property.

     Recursive display specifications are not supported--STRING's
     `display' properties, if any, are not used.

`(image . IMAGE-PROPS)'
     This kind of display specification is an image descriptor (*note
     Images::).  When used as a display specification, it means to
     display the image instead of the text that has the display
     specification.

`(slice X Y WIDTH HEIGHT)'
     This specification together with `image' specifies a "slice" (a
     partial area) of the image to display.  The elements Y and X
     specify the top left corner of the slice, within the image; WIDTH
     and HEIGHT specify the width and height of the slice.  Integer
     values are numbers of pixels.  A floating point number in the
     range 0.0-1.0 stands for that fraction of the width or height of
     the entire image.

`((margin nil) STRING)'
     A display specification of this form means to display STRING
     instead of the text that has the display specification, at the same
     position as that text.  It is equivalent to using just STRING, but
     it is done as a special case of marginal display (*note Display
     Margins::).

`(left-fringe BITMAP [FACE])'
`(right-fringe BITMAP [FACE])'
     This display specification on any character of a line of text
     causes the specified BITMAP be displayed in the left or right
     fringes for that line.  The optional FACE specifies the colors to
     be used for the bitmap.  *Note Fringe Bitmaps::, for the details.

`(space-width FACTOR)'
     This display specification affects all the space characters within
     the text that has the specification.  It displays all of these
     spaces FACTOR times as wide as normal.  The element 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.

`(height HEIGHT)'
     This display specification makes the text taller or shorter.  Here
     are the possibilities for HEIGHT:

    `(+ N)'
          This means to use a font that is N steps larger.  A "step" is
          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.  N should be an
          integer.

    `(- N)'
          This means to use a font that is N steps smaller.

    a number, FACTOR
          A number, FACTOR, means to use a font that is FACTOR times as
          tall as the default font.

    a symbol, FUNCTION
          A symbol is a function to compute the height.  It is called
          with the current height as argument, and should return the
          new height to use.

    anything else, FORM
          If the HEIGHT value doesn't fit the previous possibilities,
          it is a form.  Emacs evaluates it to get the new height, with
          the symbol `height' bound to the current specified font
          height.

`(raise FACTOR)'
     This kind of display specification raises or lowers the text it
     applies to, relative to the baseline of the line.

     FACTOR must be a number, which is interpreted as a multiple of the
     height of the affected text.  If it is positive, that means to
     display the characters raised.  If it is negative, that means to
     display them lower down.

     If the text also has a `height' display specification, that does
     not affect the amount of raising or lowering, which is based on the
     faces used for the text.

   You can make any display specification conditional.  To do that,
package it in another list of the form `(when CONDITION . SPEC)'.  Then
the specification SPEC applies only when CONDITION evaluates to a
non-`nil' value.  During the evaluation, `object' is bound to the
string or buffer having the conditional `display' property.  `position'
and `buffer-position' are bound to the position within `object' and the
buffer position where the `display' property was found, respectively.
Both positions can be different when `object' is a string.


File: elisp,  Node: Display Margins,  Prev: Other Display Specs,  Up: Display Property

38.15.5 Displaying in the Margins
---------------------------------

A buffer can have blank areas called "display margins" on the left and
on the right.  Ordinary text never appears in these areas, but you can
put things into the display margins using the `display' property.
There is currently no way to make text or images in the margin
mouse-sensitive.

   The way to display something in the margins is to specify it in a
margin display specification in the `display' property of some text.
This is a replacing display specification, meaning that the text you
put it on does not get displayed; the margin display appears, but that
text does not.

   A margin display specification looks like `((margin right-margin)
SPEC)' or `((margin left-margin) SPEC)'.  Here, SPEC is another display
specification that says what to display in the margin.  Typically it is
a string of text to display, or an image descriptor.

   To display something in the margin _in association with_ certain
buffer text, without altering or preventing the display of that text,
put a `before-string' property on the text and put the margin display
specification on the contents of the before-string.

   Before the display margins can display anything, you must give them
a nonzero width.  The usual way to do that is to set these variables:

 -- Variable: left-margin-width
     This variable specifies the width of the left margin.  It is
     buffer-local in all buffers.

 -- Variable: right-margin-width
     This variable specifies the width of the right margin.  It is
     buffer-local in all buffers.

   Setting these variables does not immediately affect the window.
These variables are checked when a new buffer is displayed in the
window.  Thus, you can make changes take effect by calling
`set-window-buffer'.

   You can also set the margin widths immediately.

 -- Function: set-window-margins window left &optional right
     This function specifies the margin widths for window WINDOW.  The
     argument LEFT controls the left margin and RIGHT controls the
     right margin (default `0').

 -- Function: window-margins &optional window
     This function returns the left and right margins of WINDOW as a
     cons cell of the form `(LEFT . RIGHT)'.  If WINDOW is `nil', the
     selected window is used.


File: elisp,  Node: Images,  Next: Buttons,  Prev: Display Property,  Up: Display

38.16 Images
============

To display an image in an Emacs buffer, you must first create an image
descriptor, then use it as a display specifier in the `display'
property of text that is displayed (*note Display Property::).

   Emacs is usually able to display images when it is run on a
graphical terminal.  Images cannot be displayed in a text terminal, on
certain graphical terminals that lack the support for this, or if Emacs
is compiled without image support.  You can use the function
`display-images-p' to determine if images can in principle be displayed
(*note Display Feature Testing::).

* Menu:

* Image Formats::       Supported image formats.
* Image Descriptors::   How to specify an image for use in `:display'.
* XBM Images::          Special features for XBM format.
* XPM Images::          Special features for XPM format.
* GIF Images::          Special features for GIF format.
* TIFF Images::         Special features for TIFF 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.


File: elisp,  Node: Image Formats,  Next: Image Descriptors,  Up: Images

38.16.1 Image Formats
---------------------

Emacs can display a number of different image formats; some of them are
supported only if particular support libraries are installed on your
machine.  In some environments, Emacs can load image libraries on
demand; if so, the variable `image-library-alist' can be used to modify
the set of known names for these dynamic libraries (though it is not
possible to add new image formats).

   The supported image formats include XBM, XPM (this requires the
libraries `libXpm' version 3.4k and `libz'), GIF (requiring `libungif'
4.1.0), PostScript, PBM, JPEG (requiring the `libjpeg' library version
v6a), TIFF (requiring `libtiff' v3.4), PNG (requiring `libpng' 1.0.2),
and SVG (requiring `librsvg' 2.0.0).

   You specify one of these formats with an image type symbol.  The
image type symbols are `xbm', `xpm', `gif', `postscript', `pbm',
`jpeg', `tiff', `png', and `svg'.

 -- Variable: image-types
     This variable contains a list of those image type symbols that are
     potentially supported in the current configuration.  _Potentially_
     here means that Emacs knows about the image types, not necessarily
     that they can be loaded (they could depend on unavailable dynamic
     libraries, for example).

     To know which image types are really available, use
     `image-type-available-p'.

 -- Variable: image-library-alist
     This in an alist of image types vs external libraries needed to
     display them.

     Each element is a list `(IMAGE-TYPE LIBRARY...)', where the car is
     a supported image format from `image-types', and the rest are
     strings giving alternate filenames for the corresponding external
     libraries to load.

     Emacs tries to load the libraries in the order they appear on the
     list; if none is loaded, the running session of Emacs won't support
     the image type.  `pbm' and `xbm' don't need to be listed; they're
     always supported.

     This variable is ignored if the image libraries are statically
     linked into Emacs.

 -- Function: image-type-available-p type
     This function returns non-`nil' if image type TYPE is available,
     i.e., if images of this type can be loaded and displayed in Emacs.
     TYPE should be one of the types contained in `image-types'.

     For image types whose support libraries are statically linked, this
     function always returns `t'; for other image types, it returns `t'
     if the dynamic library could be loaded, `nil' otherwise.


File: elisp,  Node: Image Descriptors,  Next: XBM Images,  Prev: Image Formats,  Up: Images

38.16.2 Image Descriptors
-------------------------

An image description is a list of the form `(image . PROPS)', where
PROPS is a property list containing alternating keyword symbols
(symbols whose names start with a colon) and their values.  You can use
any Lisp object as a property, but the only properties that have any
special meaning are certain symbols, all of them keywords.

   Every image descriptor must contain the property `:type TYPE' to
specify the format of the image.  The value of TYPE should be an image
type symbol; for example, `xpm' for an image in XPM format.

   Here is a list of other properties that are meaningful for all image
types:

`:file FILE'
     The `:file' property says to load the image from file FILE.  If
     FILE is not an absolute file name, it is expanded in
     `data-directory'.

`:data DATA'
     The `:data' property says the actual contents of the image.  Each
     image must use either `:data' or `:file', but not both.  For most
     image types, the value of the `:data' property should be a string
     containing the image data; we recommend using a unibyte string.

     Before using `:data', look for further information in the section
     below describing the specific image format.  For some image types,
     `:data' may not be supported; for some, it allows other data types;
     for some, `:data' alone is not enough, so you need to use other
     image properties along with `:data'.

`:margin MARGIN'
     The `:margin' property specifies how many pixels to add as an
     extra margin around the image.  The value, MARGIN, must be a
     non-negative number, or a pair `(X . Y)' of such numbers.  If it
     is a pair, X specifies how many pixels to add horizontally, and Y
     specifies how many pixels to add vertically.  If `:margin' is not
     specified, the default is zero.

`:ascent ASCENT'
     The `:ascent' property specifies the amount of the image's height
     to use for its ascent--that is, the part above the baseline.  The
     value, ASCENT, must be a number in the range 0 to 100, or the
     symbol `center'.

     If ASCENT is a number, that percentage of the image's height is
     used for its ascent.

     If ASCENT is `center', the image is vertically centered around a
     centerline which would be the vertical centerline of text drawn at
     the position of the image, in the manner specified by the text
     properties and overlays that apply to the image.

     If this property is omitted, it defaults to 50.

`:relief RELIEF'
     The `:relief' property, if non-`nil', adds a shadow rectangle
     around the image.  The value, RELIEF, specifies the width of the
     shadow lines, in pixels.  If RELIEF is negative, shadows are drawn
     so that the image appears as a pressed button; otherwise, it
     appears as an unpressed button.

`:conversion ALGORITHM'
     The `:conversion' property, if non-`nil', specifies a conversion
     algorithm that should be applied to the image before it is
     displayed; the value, ALGORITHM, specifies which algorithm.

    `laplace'
    `emboss'
          Specifies the Laplace edge detection algorithm, which blurs
          out small differences in color while highlighting larger
          differences.  People sometimes consider this useful for
          displaying the image for a "disabled" button.

    `(edge-detection :matrix MATRIX :color-adjust ADJUST)'
          Specifies a general edge-detection algorithm.  MATRIX must be
          either a nine-element list or a nine-element vector of
          numbers.  A pixel at position x/y in the transformed image is
          computed from original pixels around that position.  MATRIX
          specifies, for each pixel in the neighborhood of x/y, a
          factor with which that pixel will influence the transformed
          pixel; element 0 specifies the factor for the pixel at
          x-1/y-1, element 1 the factor for the pixel at x/y-1 etc., as
          shown below:
                 (x-1/y-1  x/y-1  x+1/y-1
                  x-1/y    x/y    x+1/y
                  x-1/y+1  x/y+1  x+1/y+1)

          The resulting pixel is computed from the color intensity of
          the color resulting from summing up the RGB values of
          surrounding pixels, multiplied by the specified factors, and
          dividing that sum by the sum of the factors' absolute values.

          Laplace edge-detection currently uses a matrix of
                 (1  0  0
                  0  0  0
                  9  9 -1)

          Emboss edge-detection uses a matrix of
                 ( 2 -1  0
                  -1  0  1
                   0  1 -2)

    `disabled'
          Specifies transforming the image so that it looks "disabled."

`:mask MASK'
     If MASK is `heuristic' or `(heuristic BG)', build a clipping mask
     for the image, so that the background of a frame is visible behind
     the image.  If BG is not specified, or if BG is `t', determine the
     background color of the image by looking at the four corners of
     the image, assuming the most frequently occurring color from the
     corners is the background color of the image.  Otherwise, BG must
     be a list `(RED GREEN BLUE)' specifying the color to assume for
     the background of the image.

     If MASK is `nil', remove a mask from the image, if it has one.
     Images in some formats include a mask which can be removed by
     specifying `:mask nil'.

`:pointer SHAPE'
     This specifies the pointer shape when the mouse pointer is over
     this image.  *Note Pointer Shape::, for available pointer shapes.

`:map MAP'
     This associates an image map of "hot spots" with this image.

     An image map is an alist where each element has the format `(AREA
     ID PLIST)'.  An AREA is specified as either a rectangle, a circle,
     or a polygon.

     A rectangle is a cons `(rect . ((X0 . Y0) . (X1 . Y1)))' which
     specifies the pixel coordinates of the upper left and bottom right
     corners of the rectangle area.

     A circle is a cons `(circle . ((X0 . Y0) . R))' which specifies
     the center and the radius of the circle; R may be a float or
     integer.

     A polygon is a cons `(poly . [X0 Y0 X1 Y1 ...])' where each pair
     in the vector describes one corner in the polygon.

     When the mouse pointer lies on a hot-spot area of an image, the
     PLIST of that hot-spot is consulted; if it contains a `help-echo'
     property, that defines a tool-tip for the hot-spot, and if it
     contains a `pointer' property, that defines the shape of the mouse
     cursor when it is on the hot-spot.  *Note Pointer Shape::, for
     available pointer shapes.

     When you click the mouse when the mouse pointer is over a
     hot-spot, an event is composed by combining the ID of the hot-spot
     with the mouse event; for instance, `[area4 mouse-1]' if the
     hot-spot's ID is `area4'.

 -- Function: image-mask-p spec &optional frame
     This function returns `t' if image SPEC has a mask bitmap.  FRAME
     is the frame on which the image will be displayed.  FRAME `nil' or
     omitted means to use the selected frame (*note Input Focus::).


File: elisp,  Node: XBM Images,  Next: XPM Images,  Prev: Image Descriptors,  Up: Images

38.16.3 XBM Images
------------------

To use XBM format, specify `xbm' as the image type.  This image format
doesn't require an external library, so images of this type are always
supported.

   Additional image properties supported for the `xbm' image type are:

`:foreground FOREGROUND'
     The value, FOREGROUND, should be a string specifying the image
     foreground color, or `nil' for the default color.  This color is
     used for each pixel in the XBM that is 1.  The default is the
     frame's foreground color.

`:background BACKGROUND'
     The value, BACKGROUND, should be a string specifying the image
     background color, or `nil' for the default color.  This color is
     used for each pixel in the XBM that is 0.  The default is the
     frame's background color.

   If you specify an XBM image using data within Emacs instead of an
external file, use the following three properties:

`:data DATA'
     The value, DATA, specifies the contents of the image.  There are
     three formats you can use for DATA:

        * A vector of strings or bool-vectors, each specifying one line
          of the image.  Do specify `:height' and `:width'.

        * A string containing the same byte sequence as an XBM file
          would contain.  You must not specify `:height' and `:width'
          in this case, because omitting them is what indicates the
          data has the format of an XBM file.  The file contents
          specify the height and width of the image.

        * A string or a bool-vector containing the bits of the image
          (plus perhaps some extra bits at the end that will not be
          used).  It should contain at least WIDTH * `height' bits.  In
          this case, you must specify `:height' and `:width', both to
          indicate that the string contains just the bits rather than a
          whole XBM file, and to specify the size of the image.

`:width WIDTH'
     The value, WIDTH, specifies the width of the image, in pixels.

`:height HEIGHT'
     The value, HEIGHT, specifies the height of the image, in pixels.


File: elisp,  Node: XPM Images,  Next: GIF Images,  Prev: XBM Images,  Up: Images

38.16.4 XPM Images
------------------

To use XPM format, specify `xpm' as the image type.  The additional
image property `:color-symbols' is also meaningful with the `xpm' image
type:

`:color-symbols SYMBOLS'
     The value, SYMBOLS, should be an alist whose elements have the
     form `(NAME . COLOR)'.  In each element, NAME is the name of a
     color as it appears in the image file, and COLOR specifies the
     actual color to use for displaying that name.


File: elisp,  Node: GIF Images,  Next: TIFF Images,  Prev: XPM Images,  Up: Images

38.16.5 GIF Images
------------------

For GIF images, specify image type `gif'.

`:index INDEX'
     You can use `:index' to specify one image from a GIF file that
     contains more than one image.  This property specifies use of image
     number INDEX from the file.  If the GIF file doesn't contain an
     image with index INDEX, the image displays as a hollow box.


File: elisp,  Node: TIFF Images,  Next: PostScript Images,  Prev: GIF Images,  Up: Images

38.16.6 TIFF Images
-------------------

For TIFF images, specify image type `tiff'.

`:index INDEX'
     You can use `:index' to specify one image from a TIFF file that
     contains more than one image.  This property specifies use of image
     number INDEX from the file.  If the TIFF file doesn't contain an
     image with index INDEX, the image displays as a hollow box.


File: elisp,  Node: PostScript Images,  Next: Other Image Types,  Prev: TIFF Images,  Up: Images

38.16.7 PostScript Images
-------------------------

To use PostScript for an image, specify image type `postscript'.  This
works only if you have Ghostscript installed.  You must always use
these three properties:

`:pt-width WIDTH'
     The value, WIDTH, specifies the width of the image measured in
     points (1/72 inch).  WIDTH must be an integer.

`:pt-height HEIGHT'
     The value, HEIGHT, specifies the height of the image in points
     (1/72 inch).  HEIGHT must be an integer.

`:bounding-box BOX'
     The value, BOX, must be a list or vector of four integers, which
     specifying the bounding box of the PostScript image, analogous to
     the `BoundingBox' comment found in PostScript files.

          %%BoundingBox: 22 171 567 738


File: elisp,  Node: Other Image Types,  Next: Defining Images,  Prev: PostScript Images,  Up: Images

38.16.8 Other Image Types
-------------------------

For PBM images, specify image type `pbm'.  Color, gray-scale and
monochromatic images are supported.   For mono PBM images, two
additional image properties are supported.

`:foreground FOREGROUND'
     The value, FOREGROUND, should be a string specifying the image
     foreground color, or `nil' for the default color.  This color is
     used for each pixel in the PBM that is 1.  The default is the
     frame's foreground color.

`:background BACKGROUND'
     The value, BACKGROUND, should be a string specifying the image
     background color, or `nil' for the default color.  This color is
     used for each pixel in the PBM that is 0.  The default is the
     frame's background color.

   For JPEG images, specify image type `jpeg'.

   For TIFF images, specify image type `tiff'.

   For PNG images, specify image type `png'.

   For SVG images, specify image type `svg'.


File: elisp,  Node: Defining Images,  Next: Showing Images,  Prev: Other Image Types,  Up: Images

38.16.9 Defining Images
-----------------------

The functions `create-image', `defimage' and `find-image' provide
convenient ways to create image descriptors.

 -- Function: create-image file-or-data &optional type data-p &rest
          props
     This function creates and returns an image descriptor which uses
     the data in FILE-OR-DATA.  FILE-OR-DATA can be a file name or a
     string containing the image data; DATA-P should be `nil' for the
     former case, non-`nil' for the latter case.

     The optional argument TYPE is a symbol specifying the image type.
     If TYPE is omitted or `nil', `create-image' tries to determine the
     image type from the file's first few bytes, or else from the
     file's name.

     The remaining arguments, PROPS, specify additional image
     properties--for example,

          (create-image "foo.xpm" 'xpm nil :heuristic-mask t)

     The function returns `nil' if images of this type are not
     supported.  Otherwise it returns an image descriptor.

 -- Macro: defimage symbol specs &optional doc
     This macro defines SYMBOL as an image name.  The arguments SPECS
     is a list which specifies how to display the image.  The third
     argument, DOC, is an optional documentation string.

     Each argument in SPECS has the form of a property list, and each
     one should specify at least the `:type' property and either the
     `:file' or the `:data' property.  The value of `:type' should be a
     symbol specifying the image type, the value of `:file' is the file
     to load the image from, and the value of `:data' is a string
     containing the actual image data.  Here is an example:

          (defimage test-image
            ((:type xpm :file "~/test1.xpm")
             (:type xbm :file "~/test1.xbm")))

     `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
     first usable argument is used to make an image descriptor which is
     stored in SYMBOL.

     If none of the alternatives will work, then SYMBOL is defined as
     `nil'.

 -- Function: find-image specs
     This function provides a convenient way to find an image
     satisfying one of a list of image specifications SPECS.

     Each specification in SPECS is a property list with contents
     depending on image type.  All specifications must at least contain
     the properties `:type TYPE' and either `:file FILE' or
     `:data DATA', where TYPE is a symbol specifying the image type,
     e.g. `xbm', FILE is the file to load the image from, and DATA is a
     string containing the actual image data.  The first specification
     in the list whose TYPE is supported, and FILE exists, is used to
     construct the image specification to be returned.  If no
     specification is satisfied, `nil' is returned.

     The image is looked for in `image-load-path'.

 -- Variable: image-load-path
     This variable's value is a list of locations in which to search for
     image files.  If an element is a string or a variable symbol whose
     value is a string, the string is taken to be the name of a
     directory to search.  If an element is a variable symbol whose
     value is a list, that is taken to be a list of directory names to
     search.

     The default is to search in the `images' subdirectory of the
     directory specified by `data-directory', then the directory
     specified by `data-directory', and finally in the directories in
     `load-path'.  Subdirectories are not automatically included in the
     search, so if you put an image file in a subdirectory, you have to
     supply the subdirectory name explicitly.  For example, to find the
     image `images/foo/bar.xpm' within `data-directory', you should
     specify the image as follows:

          (defimage foo-image '((:type xpm :file "foo/bar.xpm")))

 -- Function: image-load-path-for-library library image &optional path
          no-error
     This function returns a suitable search path for images used by the
     Lisp package LIBRARY.

     The function searches for IMAGE first using `image-load-path',
     excluding ``data-directory'/images', and then in `load-path',
     followed by a path suitable for LIBRARY, which includes
     `../../etc/images' and `../etc/images' relative to the library
     file itself, and finally in ``data-directory'/images'.

     Then this function returns a list of directories which contains
     first the directory in which IMAGE was found, followed by the
     value of `load-path'.  If PATH is given, it is used instead of
     `load-path'.

     If NO-ERROR is non-`nil' and a suitable path can't be found, don't
     signal an error.  Instead, return a list of directories as before,
     except that `nil' appears in place of the image directory.

     Here is an example of using `image-load-path-for-library':

          (defvar image-load-path) ; shush compiler
          (let* ((load-path (image-load-path-for-library
                              "mh-e" "mh-logo.xpm"))
                 (image-load-path (cons (car load-path)
                                        image-load-path)))
            (mh-tool-bar-folder-buttons-init))


File: elisp,  Node: Showing Images,  Next: Image Cache,  Prev: Defining Images,  Up: Images

38.16.10 Showing Images
-----------------------

You can use an image descriptor by setting up the `display' property
yourself, but it is easier to use the functions in this section.

 -- Function: insert-image image &optional string area slice
     This function inserts IMAGE in the current buffer at point.  The
     value IMAGE should be an image descriptor; it could be a value
     returned by `create-image', or the value of a symbol defined with
     `defimage'.  The argument STRING specifies the text to put in the
     buffer to hold the image.  If it is omitted or `nil',
     `insert-image' uses `" "' by default.

     The argument AREA specifies whether to put the image in a margin.
     If it is `left-margin', the image appears in the left margin;
     `right-margin' specifies the right margin.  If AREA is `nil' or
     omitted, the image is displayed at point within the buffer's text.

     The argument SLICE specifies a slice of the image to insert.  If
     SLICE is `nil' or omitted the whole image is inserted.  Otherwise,
     SLICE is a list `(X Y WIDTH HEIGHT)' which specifies the X and Y
     positions and WIDTH and HEIGHT of the image area to insert.
     Integer values are in units of pixels.  A floating point number in
     the range 0.0-1.0 stands for that fraction of the width or height
     of the entire image.

     Internally, this function inserts STRING in the buffer, and gives
     it a `display' property which specifies IMAGE.  *Note Display
     Property::.

 -- Function: insert-sliced-image image &optional string area rows cols
     This function inserts IMAGE in the current buffer at point, like
     `insert-image', but splits the image into ROWSxCOLS equally sized
     slices.

 -- Function: put-image image pos &optional string area
     This function puts image IMAGE in front of POS in the current
     buffer.  The argument POS should be an integer or a marker.  It
     specifies the buffer position where the image should appear.  The
     argument STRING specifies the text that should hold the image as
     an alternative to the default.

     The argument IMAGE must be an image descriptor, perhaps returned
     by `create-image' or stored by `defimage'.

     The argument AREA specifies whether to put the image in a margin.
     If it is `left-margin', the image appears in the left margin;
     `right-margin' specifies the right margin.  If AREA is `nil' or
     omitted, the image is displayed at point within the buffer's text.

     Internally, this function creates an overlay, and gives it a
     `before-string' property containing text that has a `display'
     property whose value is the image.  (Whew!)

 -- Function: remove-images start end &optional buffer
     This function removes images in BUFFER between positions START and
     END.  If BUFFER is omitted or `nil', images are removed from the
     current buffer.

     This removes only images that were put into BUFFER the way
     `put-image' does it, not images that were inserted with
     `insert-image' or in other ways.

 -- Function: image-size spec &optional pixels frame
     This function returns the size of an image as a pair
     `(WIDTH . HEIGHT)'.  SPEC is an image specification.  PIXELS
     non-`nil' means return sizes measured in pixels, otherwise return
     sizes measured in canonical character units (fractions of the
     width/height of the frame's default font).  FRAME is the frame on
     which the image will be displayed.  FRAME null or omitted means
     use the selected frame (*note Input Focus::).

 -- Variable: max-image-size
     This variable is used to define the maximum size of image that
     Emacs will load.  Emacs will refuse to load (and display) any
     image that is larger than this limit.

     If the value is an integer, it directly specifies the maximum
     image height and width, measured in pixels.  If it is a floating
     point number, it specifies the maximum image height and width as a
     ratio to the frame height and width.  If the value is non-numeric,
     there is no explicit limit on the size of images.

     The purpose of this variable is to prevent unreasonably large
     images from accidentally being loaded into Emacs.  It only takes
     effect the first time an image is loaded.  Once an image is placed
     in the image cache, it can always be displayed, even if the value
     of MAX-IMAGE-SIZE is subsequently changed (*note Image Cache::).


File: elisp,  Node: Image Cache,  Prev: Showing Images,  Up: Images

38.16.11 Image Cache
--------------------

Emacs caches images so that it can display them again more efficiently.
When Emacs displays an image, it searches the image cache for an
existing image specification `equal' to the desired specification.  If
a match is found, the image is displayed from the cache; otherwise,
Emacs loads the image normally.

   Occasionally, you may need to tell Emacs to refresh the images
associated with a given image specification.  For example, suppose you
display an image using a specification that contains a `:file'
property.  The image is automatically cached, and subsequent displays
of that image, with the same image specification, will use the image
cache.  If the image file changes in the meantime, Emacs would be
displaying the old version of the image.  In such a situation, you can
"refresh" the image by calling `image-refresh'.

   In Emacs' current implementation, each graphical terminal possesses
an image cache, which is shared by all the frames on that terminal
(*note Multiple Terminals::).  Thus, refreshing an image in one frame
also refreshes it in all other frames on the same terminal.

 -- Function: image-refresh spec &optional frame
     This function refreshes any images with image specifications
     `equal' to SPEC on frame FRAME.  If FRAME is `nil', it defaults to
     the selected frame.  If FRAME is `t', the refresh is applied to
     all existing frames.

 -- Function: clear-image-cache &optional filter
     This function clears an image cache, removing all the images
     stored in it.  If FILTER is omitted or `nil', it clears the cache
     for the selected frame.  If FILTER is a frame, it clears the cache
     for that frame.  If FILTER is `t', all image caches are cleared.
     Otherwise, FILTER is taken to be a file name, and all images
     associated with that file name are removed from all image caches.

   If an image in the image cache has not been displayed for a specified
period of time, Emacs removes it from the cache and frees the
associated memory.

 -- Variable: image-cache-eviction-delay
     This variable specifies the number of seconds an image can remain
     in the cache without being displayed.  When an image is not
     displayed for this length of time, Emacs removes it from the image
     cache.

     If the value is `nil', Emacs does not remove images from the cache
     except when you explicitly clear it.  This mode can be useful for
     debugging.


File: elisp,  Node: Buttons,  Next: Abstract Display,  Prev: Images,  Up: Display

38.17 Buttons
=============

The _button_ package defines functions for inserting and manipulating
clickable (with the mouse, or via keyboard commands) buttons in Emacs
buffers, such as might be used for help hyper-links, etc.  Emacs uses
buttons for the hyper-links in help text and the like.

   A button is essentially a set of properties attached (via text
properties or overlays) to a region of text in an Emacs buffer.  These
properties are called "button properties".

   One of these properties (`action') is a function, which will be
called when the user invokes it using the keyboard or the mouse.  The
invoked function may then examine the button and use its other
properties as desired.

   In some ways the Emacs button package duplicates functionality
offered by the widget package (*note Introduction: (widget)Top.), but
the button package has the advantage that it is much faster, much
smaller, and much simpler to use (for elisp programmers--for users, the
result is about the same).  The extra speed and space savings are
useful mainly if you need to create many buttons in a buffer (for
instance an `*Apropos*' buffer uses buttons to make entries clickable,
and may contain many thousands of entries).

* Menu:

* Button Properties::      Button properties with special meanings.
* Button Types::           Defining common properties for classes of buttons.
* Making Buttons::         Adding buttons to Emacs buffers.
* Manipulating Buttons::   Getting and setting properties of buttons.
* Button Buffer Commands:: Buffer-wide commands and bindings for buttons.


File: elisp,  Node: Button Properties,  Next: Button Types,  Up: Buttons

38.17.1 Button Properties
-------------------------

Buttons have an associated list of properties defining their appearance
and behavior, and other arbitrary properties may be used for
application specific purposes.  Some properties that have special
meaning to the button package include:

`action'
     The function to call when the user invokes the button, which is
     passed the single argument BUTTON.  By default this is `ignore',
     which does nothing.

`mouse-action'
     This is similar to `action', and when present, will be used
     instead of `action' for button invocations resulting from
     mouse-clicks (instead of the user hitting <RET>).  If not present,
     mouse-clicks use `action' instead.

`face'
     This is an Emacs face controlling how buttons of this type are
     displayed; by default this is the `button' face.

`mouse-face'
     This is an additional face which controls appearance during
     mouse-overs (merged with the usual button face); by default this is
     the usual Emacs `highlight' face.

`keymap'
     The button's keymap, defining bindings active within the button
     region.  By default this is the usual button region keymap, stored
     in the variable `button-map', which defines <RET> and <mouse-2> to
     invoke the button.

`type'
     The button-type of the button.  When creating a button, this is
     usually specified using the `:type' keyword argument.  *Note
     Button Types::.

`help-echo'
     A string displayed by the Emacs tool-tip help system; by default,
     `"mouse-2, RET: Push this button"'.

`follow-link'
     The follow-link property, defining how a <Mouse-1> click behaves
     on this button, *Note Clickable Text::.

`button'
     All buttons have a non-`nil' `button' property, which may be useful
     in finding regions of text that comprise buttons (which is what the
     standard button functions do).

   There are other properties defined for the regions of text in a
button, but these are not generally interesting for typical uses.


File: elisp,  Node: Button Types,  Next: Making Buttons,  Prev: Button Properties,  Up: Buttons

38.17.2 Button Types
--------------------

Every button has a button _type_, which defines default values for the
button's properties.  Button types are arranged in a hierarchy, with
specialized types inheriting from more general types, so that it's easy
to define special-purpose types of buttons for specific tasks.

 -- Function: define-button-type name &rest properties
     Define a `button type' called NAME (a symbol).  The remaining
     arguments form a sequence of PROPERTY VALUE pairs, specifying
     default property values for buttons with this type (a button's
     type may be set by giving it a `type' property when creating the
     button, using the `:type' keyword argument).

     In addition, the keyword argument `:supertype' may be used to
     specify a button-type from which NAME inherits its default
     property values.  Note that this inheritance happens only when
     NAME is defined; subsequent changes to a supertype are not
     reflected in its subtypes.

   Using `define-button-type' to define default properties for buttons
is not necessary--buttons without any specified type use the built-in
button-type `button'--but it is encouraged, since doing so usually
makes the resulting code clearer and more efficient.


File: elisp,  Node: Making Buttons,  Next: Manipulating Buttons,  Prev: Button Types,  Up: Buttons

38.17.3 Making Buttons
----------------------

Buttons are associated with a region of text, using an overlay or text
properties to hold button-specific information, all of which are
initialized from the button's type (which defaults to the built-in
button type `button').  Like all Emacs text, the appearance of the
button is governed by the `face' property; by default (via the `face'
property inherited from the `button' button-type) this is a simple
underline, like a typical web-page link.

   For convenience, there are two sorts of button-creation functions,
those that add button properties to an existing region of a buffer,
called `make-...button', and those that also insert the button text,
called `insert-...button'.

   The button-creation functions all take the `&rest' argument
PROPERTIES, which should be a sequence of PROPERTY VALUE pairs,
specifying properties to add to the button; see *note Button
Properties::.  In addition, the keyword argument `:type' may be used to
specify a button-type from which to inherit other properties; see *note
Button Types::.  Any properties not explicitly specified during
creation will be inherited from the button's type (if the type defines
such a property).

   The following functions add a button using an overlay (*note
Overlays::) to hold the button properties:

 -- Function: make-button beg end &rest properties
     This makes a button from BEG to END in the current buffer, and
     returns it.

 -- Function: insert-button label &rest properties
     This insert a button with the label LABEL at point, and returns it.

   The following functions are similar, but use Emacs text properties
(*note Text Properties::) to hold the button properties, making the
button actually part of the text instead of being a property of the
buffer.  Buttons using text properties do not create markers into the
buffer, which is important for speed when you use extremely large
numbers of buttons.  (However, if there is an existing face text
property at the site of the button, the button face may not be visible.)
Both functions return the position of the start of the new button:

 -- Function: make-text-button beg end &rest properties
     This makes a button from BEG to END in the current buffer, using
     text properties.

 -- Function: insert-text-button label &rest properties
     This inserts a button with the label LABEL at point, using text
     properties.


File: elisp,  Node: Manipulating Buttons,  Next: Button Buffer Commands,  Prev: Making Buttons,  Up: Buttons

38.17.4 Manipulating Buttons
----------------------------

These are functions for getting and setting properties of buttons.
Often these are used by a button's invocation function to determine
what to do.

   Where a BUTTON parameter is specified, it means an object referring
to a specific button, either an overlay (for overlay buttons), or a
buffer-position or marker (for text property buttons).  Such an object
is passed as the first argument to a button's invocation function when
it is invoked.

 -- Function: button-start button
     Return the position at which BUTTON starts.

 -- Function: button-end button
     Return the position at which BUTTON ends.

 -- Function: button-get button prop
     Get the property of button BUTTON named PROP.

 -- Function: button-put button prop val
     Set BUTTON's PROP property to VAL.

 -- Function: button-activate button &optional use-mouse-action
     Call BUTTON's `action' property (i.e., invoke it).  If
     USE-MOUSE-ACTION is non-`nil', try to invoke the button's
     `mouse-action' property instead of `action'; if the button has no
     `mouse-action' property, use `action' as normal.

 -- Function: button-label button
     Return BUTTON's text label.

 -- Function: button-type button
     Return BUTTON's button-type.

 -- Function: button-has-type-p button type
     Return `t' if BUTTON has button-type TYPE, or one of TYPE's
     subtypes.

 -- Function: button-at pos
     Return the button at position POS in the current buffer, or `nil'.

 -- Function: button-type-put type prop val
     Set the button-type TYPE's PROP property to VAL.

 -- Function: button-type-get type prop
     Get the property of button-type TYPE named PROP.

 -- Function: button-type-subtype-p type supertype
     Return `t' if button-type TYPE is a subtype of SUPERTYPE.


File: elisp,  Node: Button Buffer Commands,  Prev: Manipulating Buttons,  Up: Buttons

38.17.5 Button Buffer Commands
------------------------------

These are commands and functions for locating and operating on buttons
in an Emacs buffer.

   `push-button' is the command that a user uses to actually `push' a
button, and is bound by default in the button itself to <RET> and to
<mouse-2> using a region-specific keymap.  Commands that are useful
outside the buttons itself, such as `forward-button' and
`backward-button' are additionally available in the keymap stored in
`button-buffer-map'; a mode which uses buttons may want to use
`button-buffer-map' as a parent keymap for its keymap.

   If the button has a non-`nil' `follow-link' property, and
MOUSE-1-CLICK-FOLLOWS-LINK is set, a quick <Mouse-1> click will also
activate the `push-button' command.  *Note Clickable Text::.

 -- Command: push-button &optional pos use-mouse-action
     Perform the action specified by a button at location POS.  POS may
     be either a buffer position or a mouse-event.  If USE-MOUSE-ACTION
     is non-`nil', or POS is a mouse-event (*note Mouse Events::), try
     to invoke the button's `mouse-action' property instead of
     `action'; if the button has no `mouse-action' property, use
     `action' as normal.  POS defaults to point, except when
     `push-button' is invoked interactively as the result of a
     mouse-event, in which case, the mouse event's position is used.
     If there's no button at POS, do nothing and return `nil',
     otherwise return `t'.

 -- Command: forward-button n &optional wrap display-message
     Move to the Nth next button, or Nth previous button if N is
     negative.  If N is zero, move to the start of any button at point.
     If WRAP is non-`nil', moving past either end of the buffer
     continues from the other end.  If DISPLAY-MESSAGE is non-`nil',
     the button's help-echo string is displayed.  Any button with a
     non-`nil' `skip' property is skipped over.  Returns the button
     found.

 -- Command: backward-button n &optional wrap display-message
     Move to the Nth previous button, or Nth next button if N is
     negative.  If N is zero, move to the start of any button at point.
     If WRAP is non-`nil', moving past either end of the buffer
     continues from the other end.  If DISPLAY-MESSAGE is non-`nil',
     the button's help-echo string is displayed.  Any button with a
     non-`nil' `skip' property is skipped over.  Returns the button
     found.

 -- Function: next-button pos &optional count-current
 -- Function: previous-button pos &optional count-current
     Return the next button after (for `next-button' or before (for
     `previous-button') position POS in the current buffer.  If
     COUNT-CURRENT is non-`nil', count any button at POS in the search,
     instead of starting at the next button.


File: elisp,  Node: Abstract Display,  Next: Blinking,  Prev: Buttons,  Up: Display

38.18 Abstract Display
======================

The Ewoc package constructs buffer text that represents a structure of
Lisp objects, and updates the text to follow changes in that structure.
This is like the "view" component in the "model/view/controller" design
paradigm.

   An "ewoc" is a structure that organizes information required to
construct buffer text that represents certain Lisp data.  The buffer
text of the ewoc has three parts, in order: first, fixed "header" text;
next, textual descriptions of a series of data elements (Lisp objects
that you specify); and last, fixed "footer" text.  Specifically, an
ewoc contains information on:

   * The buffer which its text is generated in.

   * The text's start position in the buffer.

   * The header and footer strings.

   * A doubly-linked chain of "nodes", each of which contains:

        * A "data element", a single Lisp object.

        * Links to the preceding and following nodes in the chain.

   * A "pretty-printer" function which is responsible for inserting the
     textual representation of a data element value into the current
     buffer.

   Typically, you define an ewoc with `ewoc-create', and then pass the
resulting ewoc structure to other functions in the Ewoc package to
build nodes within it, and display it in the buffer.  Once it is
displayed in the buffer, other functions determine the correspondance
between buffer positions and nodes, move point from one node's textual
representation to another, and so forth.  *Note Abstract Display
Functions::.

   A node "encapsulates" a data element much the way a variable holds a
value.  Normally, encapsulation occurs as a part of adding a node to
the ewoc.  You can retrieve the data element value and place a new
value in its place, like so:

     (ewoc-data NODE)
     => value

     (ewoc-set-data NODE NEW-VALUE)
     => NEW-VALUE

You can also use, as the data element value, a Lisp object (list or
vector) that is a container for the "real" value, or an index into some
other structure.  The example (*note Abstract Display Example::) uses
the latter approach.

   When the data changes, you will want to update the text in the
buffer.  You can update all nodes by calling `ewoc-refresh', or just
specific nodes using `ewoc-invalidate', or all nodes satisfying a
predicate using `ewoc-map'.  Alternatively, you can delete invalid
nodes using `ewoc-delete' or `ewoc-filter', and add new nodes in their
place.  Deleting a node from an ewoc deletes its associated textual
description from buffer, as well.

* Menu:

* Abstract Display Functions::  Functions in the Ewoc package.
* Abstract Display Example::    Example of using Ewoc.


File: elisp,  Node: Abstract Display Functions,  Next: Abstract Display Example,  Up: Abstract Display

38.18.1 Abstract Display Functions
----------------------------------

In this subsection, EWOC and NODE stand for the structures described
above (*note Abstract Display::), while DATA stands for an arbitrary
Lisp object used as a data element.

 -- Function: ewoc-create pretty-printer &optional header footer nosep
     This constructs and returns a new ewoc, with no nodes (and thus no
     data elements).  PRETTY-PRINTER should be a function that takes one
     argument, a data element of the sort you plan to use in this ewoc,
     and inserts its textual description at point using `insert' (and
     never `insert-before-markers', because that would interfere with
     the Ewoc package's internal mechanisms).

     Normally, a newline is automatically inserted after the header,
     the footer and every node's textual description.  If NOSEP is
     non-`nil', no newline is inserted.  This may be useful for
     displaying an entire ewoc on a single line, for example, or for
     making nodes "invisible" by arranging for PRETTY-PRINTER to do
     nothing for those nodes.

     An ewoc maintains its text in the buffer that is current when you
     create it, so switch to the intended buffer before calling
     `ewoc-create'.

 -- Function: ewoc-buffer ewoc
     This returns the buffer where EWOC maintains its text.

 -- Function: ewoc-get-hf ewoc
     This returns a cons cell `(HEADER . FOOTER)' made from EWOC's
     header and footer.

 -- Function: ewoc-set-hf ewoc header footer
     This sets the header and footer of EWOC to the strings HEADER and
     FOOTER, respectively.

 -- Function: ewoc-enter-first ewoc data
 -- Function: ewoc-enter-last ewoc data
     These add a new node encapsulating DATA, putting it, respectively,
     at the beginning or end of EWOC's chain of nodes.

 -- Function: ewoc-enter-before ewoc node data
 -- Function: ewoc-enter-after ewoc node data
     These add a new node encapsulating DATA, adding it to EWOC before
     or after NODE, respectively.

 -- Function: ewoc-prev ewoc node
 -- Function: ewoc-next ewoc node
     These return, respectively, the previous node and the next node of
     NODE in EWOC.

 -- Function: ewoc-nth ewoc n
     This returns the node in EWOC found at zero-based index N.  A
     negative N means count from the end.  `ewoc-nth' returns `nil' if
     N is out of range.

 -- Function: ewoc-data node
     This extracts the data encapsulated by NODE and returns it.

 -- Function: ewoc-set-data node data
     This sets the data encapsulated by NODE to DATA.

 -- Function: ewoc-locate ewoc &optional pos guess
     This determines the node in EWOC which contains point (or POS if
     specified), and returns that node.  If EWOC has no nodes, it
     returns `nil'.  If POS is before the first node, it returns the
     first node; if POS is after the last node, it returns the last
     node.  The optional third arg GUESS should be a node that is
     likely to be near POS; this doesn't alter the result, but makes
     the function run faster.

 -- Function: ewoc-location node
     This returns the start position of NODE.

 -- Function: ewoc-goto-prev ewoc arg
 -- Function: ewoc-goto-next ewoc arg
     These move point to the previous or next, respectively, ARGth node
     in EWOC.  `ewoc-goto-prev' does not move if it is already at the
     first node or if EWOC is empty, whereas `ewoc-goto-next' moves
     past the last node, returning `nil'.  Excepting this special case,
     these functions return the node moved to.

 -- Function: ewoc-goto-node ewoc node
     This moves point to the start of NODE in EWOC.

 -- Function: ewoc-refresh ewoc
     This function regenerates the text of EWOC.  It works by deleting
     the text between the header and the footer, i.e., all the data
     elements' representations, and then calling the pretty-printer
     function for each node, one by one, in order.

 -- Function: ewoc-invalidate ewoc &rest nodes
     This is similar to `ewoc-refresh', except that only NODES in EWOC
     are updated instead of the entire set.

 -- Function: ewoc-delete ewoc &rest nodes
     This deletes each node in NODES from EWOC.

 -- Function: ewoc-filter ewoc predicate &rest args
     This calls PREDICATE for each data element in EWOC and deletes
     those nodes for which PREDICATE returns `nil'.  Any ARGS are
     passed to PREDICATE.

 -- Function: ewoc-collect ewoc predicate &rest args
     This calls PREDICATE for each data element in EWOC and returns a
     list of those elements for which PREDICATE returns non-`nil'.  The
     elements in the list are ordered as in the buffer.  Any ARGS are
     passed to PREDICATE.

 -- Function: ewoc-map map-function ewoc &rest args
     This calls MAP-FUNCTION for each data element in EWOC and updates
     those nodes for which MAP-FUNCTION returns non-`nil'.  Any ARGS
     are passed to MAP-FUNCTION.


File: elisp,  Node: Abstract Display Example,  Prev: Abstract Display Functions,  Up: Abstract Display

38.18.2 Abstract Display Example
--------------------------------

Here is a simple example using functions of the ewoc package to
implement a "color components display," an area in a buffer that
represents a vector of three integers (itself representing a 24-bit RGB
value) in various ways.

     (setq colorcomp-ewoc nil
           colorcomp-data nil
           colorcomp-mode-map nil
           colorcomp-labels ["Red" "Green" "Blue"])

     (defun colorcomp-pp (data)
       (if data
           (let ((comp (aref colorcomp-data data)))
             (insert (aref colorcomp-labels data) "\t: #x"
                     (format "%02X" comp) " "
                     (make-string (ash comp -2) ?#) "\n"))
         (let ((cstr (format "#%02X%02X%02X"
                             (aref colorcomp-data 0)
                             (aref colorcomp-data 1)
                             (aref colorcomp-data 2)))
               (samp " (sample text) "))
           (insert "Color\t: "
                   (propertize samp 'face
                               `(foreground-color . ,cstr))
                   (propertize samp 'face
                               `(background-color . ,cstr))
                   "\n"))))

     (defun colorcomp (color)
       "Allow fiddling with COLOR in a new buffer.
     The buffer is in Color Components mode."
       (interactive "sColor (name or #RGB or #RRGGBB): ")
       (when (string= "" color)
         (setq color "green"))
       (unless (color-values color)
         (error "No such color: %S" color))
       (switch-to-buffer
        (generate-new-buffer (format "originally: %s" color)))
       (kill-all-local-variables)
       (setq major-mode 'colorcomp-mode
             mode-name "Color Components")
       (use-local-map colorcomp-mode-map)
       (erase-buffer)
       (buffer-disable-undo)
       (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8))
                                          (color-values color))))
             (ewoc (ewoc-create 'colorcomp-pp
                                "\nColor Components\n\n"
                                (substitute-command-keys
                                 "\n\\{colorcomp-mode-map}"))))
         (set (make-local-variable 'colorcomp-data) data)
         (set (make-local-variable 'colorcomp-ewoc) ewoc)
         (ewoc-enter-last ewoc 0)
         (ewoc-enter-last ewoc 1)
         (ewoc-enter-last ewoc 2)
         (ewoc-enter-last ewoc nil)))

   This example can be extended to be a "color selection widget" (in
other words, the controller part of the "model/view/controller" design
paradigm) by defining commands to modify `colorcomp-data' and to
"finish" the selection process, and a keymap to tie it all together
conveniently.

     (defun colorcomp-mod (index limit delta)
       (let ((cur (aref colorcomp-data index)))
         (unless (= limit cur)
           (aset colorcomp-data index (+ cur delta)))
         (ewoc-invalidate
          colorcomp-ewoc
          (ewoc-nth colorcomp-ewoc index)
          (ewoc-nth colorcomp-ewoc -1))))

     (defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1))
     (defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1))
     (defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1))
     (defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1))
     (defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1))
     (defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1))

     (defun colorcomp-copy-as-kill-and-exit ()
       "Copy the color components into the kill ring and kill the buffer.
     The string is formatted #RRGGBB (hash followed by six hex digits)."
       (interactive)
       (kill-new (format "#%02X%02X%02X"
                         (aref colorcomp-data 0)
                         (aref colorcomp-data 1)
                         (aref colorcomp-data 2)))
       (kill-buffer nil))

     (setq colorcomp-mode-map
           (let ((m (make-sparse-keymap)))
             (suppress-keymap m)
             (define-key m "i" 'colorcomp-R-less)
             (define-key m "o" 'colorcomp-R-more)
             (define-key m "k" 'colorcomp-G-less)
             (define-key m "l" 'colorcomp-G-more)
             (define-key m "," 'colorcomp-B-less)
             (define-key m "." 'colorcomp-B-more)
             (define-key m " " 'colorcomp-copy-as-kill-and-exit)
             m))

   Note that we never modify the data in each node, which is fixed when
the ewoc is created to be either `nil' or an index into the vector
`colorcomp-data', the actual color components.


File: elisp,  Node: Blinking,  Next: Usual Display,  Prev: Abstract Display,  Up: Display

38.19 Blinking Parentheses
==========================

This section describes the mechanism by which Emacs shows a matching
open parenthesis when the user inserts a close parenthesis.

 -- Variable: blink-paren-function
     The value of this variable should be a function (of no arguments)
     to be called whenever a character with close parenthesis syntax is
     inserted.  The value of `blink-paren-function' may be `nil', in
     which case nothing is done.

 -- User Option: blink-matching-paren
     If this variable is `nil', then `blink-matching-open' does nothing.

 -- User Option: blink-matching-paren-distance
     This variable specifies the maximum distance to scan for a matching
     parenthesis before giving up.

 -- User Option: blink-matching-delay
     This variable specifies the number of seconds for the cursor to
     remain at the matching parenthesis.  A fraction of a second often
     gives good results, but the default is 1, which works on all
     systems.

 -- Command: blink-matching-open
     This function is the default value of `blink-paren-function'.  It
     assumes that point follows a character with close parenthesis
     syntax and moves the cursor momentarily to the matching opening
     character.  If that character is not already on the screen, it
     displays the character's context in the echo area.  To avoid long
     delays, this function does not search farther than
     `blink-matching-paren-distance' characters.

     Here is an example of calling this function explicitly.

          (defun interactive-blink-matching-open ()
            "Indicate momentarily the start of sexp before point."
            (interactive)
            (let ((blink-matching-paren-distance
                   (buffer-size))
                  (blink-matching-paren t))
              (blink-matching-open)))


File: elisp,  Node: Usual Display,  Next: Display Tables,  Prev: Blinking,  Up: Display

38.20 Usual Display Conventions
===============================

The usual display conventions define how to display each character
code.  You can override these conventions by setting up a display table
(*note Display Tables::).  Here are the usual display conventions:

   * Character codes 32 through 126 map to glyph codes 32 through 126.
     Normally this means they display as themselves.

   * Character code 9 is a horizontal tab.  It displays as whitespace
     up to a position determined by `tab-width'.

   * Character code 10 is a newline.

   * All other codes in the range 0 through 31, and code 127, display
     in one of two ways according to the value of `ctl-arrow'.  If it is
     non-`nil', these codes map to sequences of two glyphs, where the
     first glyph is the ASCII code for `^'.  (A display table can
     specify a glyph to use instead of `^'.)  Otherwise, these codes map
     just like the codes in the range 128 to 255.

     On MS-DOS terminals, Emacs arranges by default for the character
     code 127 to be mapped to the glyph code 127, which normally
     displays as an empty polygon.  This glyph is used to display
     non-ASCII characters that the MS-DOS terminal doesn't support.
     *Note MS-DOS and MULE: (emacs)MS-DOS and MULE.

   * Character codes 128 through 255 map to sequences of four glyphs,
     where the first glyph is the ASCII code for `\', and the others are
     digit characters representing the character code in octal.  (A
     display table can specify a glyph to use instead of `\'.)

   * Multibyte character codes above 256 are displayed as themselves,
     or as a question mark or empty box if the terminal cannot display
     that character.

   The usual display conventions apply even when there is a display
table, for any character whose entry in the active display table is
`nil'.  Thus, when you set up a display table, you need only specify
the characters for which you want special behavior.

   These display rules apply to carriage return (character code 13),
when it appears in the buffer.  But that character may not appear in the
buffer where you expect it, if it was eliminated as part of end-of-line
conversion (*note Coding System Basics::).

   These variables affect the way certain characters are displayed on
the screen.  Since they change the number of columns the characters
occupy, they also affect the indentation functions.  These variables
also affect how the mode line is displayed; if you want to force
redisplay of the mode line using the new values, call the function
`force-mode-line-update' (*note Mode Line Format::).

 -- User Option: ctl-arrow
     This buffer-local variable controls how control characters are
     displayed.  If it is non-`nil', they are displayed as a caret
     followed by the character: `^A'.  If it is `nil', they are
     displayed as a backslash followed by three octal digits: `\001'.

 -- User Option: tab-width
     The value of this buffer-local variable is the spacing between tab
     stops used for 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 `tab-to-tab-stop'.  *Note Indent Tabs::.


File: elisp,  Node: Display Tables,  Next: Beeping,  Prev: Usual Display,  Up: Display

38.21 Display Tables
====================

You can use the "display table" feature to control how all possible
character codes display on the screen.  This is useful for displaying
European languages that have letters not in the ASCII character set.

   The display table maps each character code into a sequence of
"glyphs", each glyph being a graphic that takes up one character
position on the screen.  You can also define how to display each glyph
on your terminal, using the "glyph table".

   Display tables affect how the mode line is displayed; if you want to
force redisplay of the mode line using a new display table, call
`force-mode-line-update' (*note Mode Line Format::).

* Menu:

* Display Table Format::  What a display table consists of.
* Active Display Table::  How Emacs selects a display table to use.
* Glyphs::              How to define a glyph, and what glyphs mean.


File: elisp,  Node: Display Table Format,  Next: Active Display Table,  Up: Display Tables

38.21.1 Display Table Format
----------------------------

A display table is actually a char-table (*note Char-Tables::) with
`display-table' as its subtype.

 -- Function: make-display-table
     This creates and returns a display table.  The table initially has
     `nil' in all elements.

   The ordinary elements of the display table are indexed by character
codes; the element at index C says how to display the character code C.
The value should be `nil' or a vector of the glyphs to be output (*note
Glyphs::).  `nil' says to display the character C according to the
usual display conventions (*note Usual Display::).

   *Warning:* if you use the display table to change the display of
newline characters, the whole buffer will be displayed as one long
"line."

   The display table also has six "extra slots" which serve special
purposes.  Here is a table of their meanings; `nil' in any slot means
to use the default for that slot, as stated below.

0
     The glyph for the end of a truncated screen line (the default for
     this is `$').  *Note Glyphs::.  On graphical terminals, Emacs uses
     arrows in the fringes to indicate truncation, so the display table
     has no effect.

1
     The glyph for the end of a continued line (the default is `\').
     On graphical terminals, Emacs uses curved arrows in the fringes to
     indicate continuation, so the display table has no effect.

2
     The glyph for indicating a character displayed as an octal
     character code (the default is `\').

3
     The glyph for indicating a control character (the default is `^').

4
     A vector of glyphs for indicating the presence of invisible lines
     (the default is `...').  *Note Selective Display::.

5
     The glyph used to draw the border between side-by-side windows (the
     default is `|').  *Note Splitting Windows::.  This takes effect
     only when there are no scroll bars; if scroll bars are supported
     and in use, a scroll bar separates the two windows.

   For example, here is how to construct a display table that mimics the
effect of setting `ctl-arrow' to a non-`nil' value:

     (setq disptab (make-display-table))
     (let ((i 0))
       (while (< i 32)
         (or (= i ?\t) (= i ?\n)
             (aset disptab i (vector ?^ (+ i 64))))
         (setq i (1+ i)))
       (aset disptab 127 (vector ?^ ??)))

 -- Function: display-table-slot display-table slot
     This function returns the value of the extra slot SLOT of
     DISPLAY-TABLE.  The argument SLOT may be a number from 0 to 5
     inclusive, or a slot name (symbol).  Valid symbols are
     `truncation', `wrap', `escape', `control', `selective-display',
     and `vertical-border'.

 -- Function: set-display-table-slot display-table slot value
     This function stores VALUE in the extra slot SLOT of
     DISPLAY-TABLE.  The argument SLOT may be a number from 0 to 5
     inclusive, or a slot name (symbol).  Valid symbols are
     `truncation', `wrap', `escape', `control', `selective-display',
     and `vertical-border'.

 -- Function: describe-display-table display-table
     This function displays a description of the display table
     DISPLAY-TABLE in a help buffer.

 -- Command: describe-current-display-table
     This command displays a description of the current display table
     in a help buffer.


File: elisp,  Node: Active Display Table,  Next: Glyphs,  Prev: Display Table Format,  Up: Display Tables

38.21.2 Active Display Table
----------------------------

Each window can specify a display table, and so can each buffer.  When
a buffer B is displayed in window W, display uses the display table for
window W if it has one; otherwise, the display table for buffer B if it
has one; otherwise, the standard display table if any.  The display
table chosen is called the "active" display table.

 -- Function: window-display-table &optional window
     This function returns WINDOW's display table, or `nil' if WINDOW
     does not have an assigned display table.  The default for WINDOW
     is the selected window.

 -- Function: set-window-display-table window table
     This function sets the display table of WINDOW to TABLE.  The
     argument TABLE should be either a display table or `nil'.

 -- Variable: buffer-display-table
     This variable is automatically buffer-local in all buffers; its
     value in a particular buffer specifies the display table for that
     buffer.  If it is `nil', that means the buffer does not have an
     assigned display table.

 -- Variable: standard-display-table
     This variable's value is the default display table, used whenever a
     window has no display table and neither does the buffer displayed
     in that window.  This variable is `nil' by default.

   If there is no display table to use for a particular window--that is,
if the window specifies none, its buffer specifies none, and
`standard-display-table' is `nil'--then Emacs uses the usual display
conventions for all character codes in that window.  *Note Usual
Display::.

   A number of functions for changing the standard display table are
defined in the library `disp-table'.


File: elisp,  Node: Glyphs,  Prev: Active Display Table,  Up: Display Tables

38.21.3 Glyphs
--------------

A "glyph" is a generalization of a character; it stands for an image
that takes up a single character position on the screen.  Normally
glyphs come from vectors in the display table (*note Display Tables::).

   A glyph is represented in Lisp as a "glyph code".  A glyph code can
be "simple" or it can be defined by the "glyph table".  A simple glyph
code is just a way of specifying a character and a face to output it
in.  *Note Faces::.

   The following functions are used to manipulate simple glyph codes:

 -- Function: make-glyph-code char &optional face
     This function returns a simple glyph code representing char CHAR
     with face FACE.

 -- Function: glyph-char glyph
     This function returns the character of simple glyph code GLYPH.

 -- Function: glyph-face glyph
     This function returns face of simple glyph code GLYPH, or `nil' if
     GLYPH has the default face (face-id 0).  *Note Face Functions::.

   On character terminals, you can set up a "glyph table" to define the
meaning of glyph codes (represented as small integers).

 -- Variable: glyph-table
     The value of this variable is the current glyph table.  It should
     be `nil' or a vector whose Gth element defines glyph code G.

     If a glyph code is greater than or equal to the length of the glyph
     table, that code is automatically simple.  If `glyph-table' is
     `nil' then all glyph codes are simple.

     The glyph table is used only on character terminals.  On graphical
     displays, all glyph codes are simple.

   Here are the meaningful types of elements in the glyph table:

STRING
     Send the characters in STRING to the terminal to output this glyph
     code.

CODE
     Define this glyph code as an alias for glyph code CODE created by
     `make-glyph-code'.  You can use such an alias to define a
     small-numbered glyph code which specifies a character with a face.

`nil'
     This glyph code is simple.

 -- Function: create-glyph string
     This function returns a newly-allocated glyph code which is set up
     to display by sending STRING to the terminal.


File: elisp,  Node: Beeping,  Next: Window Systems,  Prev: Display Tables,  Up: Display

38.22 Beeping
=============

This section describes how to make Emacs ring the bell (or blink the
screen) to attract the user's attention.  Be conservative about how
often you do this; frequent bells can become irritating.  Also be
careful not to use just beeping when signaling an error is more
appropriate.  (*Note Errors::.)

 -- Function: ding &optional do-not-terminate
     This function beeps, or flashes the screen (see `visible-bell'
     below).  It also terminates any keyboard macro currently executing
     unless DO-NOT-TERMINATE is non-`nil'.

 -- Function: beep &optional do-not-terminate
     This is a synonym for `ding'.

 -- User Option: visible-bell
     This variable determines whether Emacs should flash the screen to
     represent a bell.  Non-`nil' means yes, `nil' means no.  This is
     effective on graphical displays, and on text-only terminals
     provided the terminal's Termcap entry defines the visible bell
     capability (`vb').

 -- Variable: ring-bell-function
     If this is non-`nil', it specifies how Emacs should "ring the
     bell."  Its value should be a function of no arguments.  If this is
     non-`nil', it takes precedence over the `visible-bell' variable.


File: elisp,  Node: Window Systems,  Prev: Beeping,  Up: Display

38.23 Window Systems
====================

Emacs works with several window systems, most notably the X Window
System.  Both Emacs and X use the term "window," but use it
differently.  An Emacs frame is a single window as far as X is
concerned; the individual Emacs windows are not known to X at all.

 -- Variable: window-system
     This frame-local variable tells Lisp programs what window system
     Emacs is using for displaying the frame.  The possible values are

    `x'
          Emacs is displaying the frame using X.

    `w32'
          Emacs is displaying the frame using native MS-Windows GUI.

    `ns'
          Emacs is displaying the frame using the Nextstep interface
          (used on GNUstep and Mac OS X).

    `pc'
          Emacs is displaying the frame using MS-DOS direct screen
          writes.

    `nil'
          Emacs is displaying the frame on a character-based terminal.

 -- Variable: initial-window-system
     This variable holds the value of `window-system' used for the
     first frame created by Emacs during startup.  (When Emacs is
     invoked with the `--daemon' option, it does not create any initial
     frames, so `initial-window-system' is `nil'.  *Note daemon:
     (emacs)Initial Options.)

 -- Function: window-system &optional frame
     This function returns a symbol whose name tells what window system
     is used for displaying FRAME (which defaults to the currently
     selected frame).  The list of possible symbols it returns is the
     same one documented for the variable `window-system' above.

   Do _not_ use `window-system' and `initial-window-system' as
predicates or boolean flag variables, if you want to write code that
works differently on text terminals and graphic displays.  That is
because `window-system' is not a good indicator of Emacs capabilities
on a given display type.  Instead, use `display-graphic-p' or any of
the other `display-*-p' predicates described in *note Display Feature
Testing::.

 -- Variable: 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 init file, the default initialization file (if any),
     and the terminal-specific Lisp code, and running the hook
     `term-setup-hook'.

     This hook is used for internal purposes: setting up communication
     with the window system, and creating the initial window.  Users
     should not interfere with it.


File: elisp,  Node: System Interface,  Next: Antinews,  Prev: Display,  Up: Top

39 Operating System Interface
*****************************

This chapter is about starting and getting out of Emacs, access to
values in the operating system environment, and terminal input, output,
and flow control.

   *Note Building Emacs::, for related information.  *Note Display::,
for additional operating system status information pertaining to the
terminal and the screen.

* Menu:

* Starting Up::         Customizing Emacs startup processing.
* Getting Out::         How exiting works (permanent or temporary).
* System Environment::  Distinguish the name and kind of system.
* User Identification:: Finding the name and user id of the user.
* Time of Day::         Getting the current time.
* Time Conversion::     Converting a time from numeric form to
                          calendrical data and vice versa.
* Time Parsing::        Converting a time from numeric form to text
                          and vice versa.
* Processor Run Time::  Getting the run time used by Emacs.
* Time Calculations::   Adding, subtracting, comparing times, etc.
* Timers::              Setting a timer to call a function at a certain time.
* Idle Timers::         Setting a timer to call a function when Emacs has
                          been idle for a certain length of time.
* Terminal Input::      Accessing and recording terminal input.
* Terminal Output::     Controlling and recording terminal output.
* Sound Output::        Playing sounds on the computer's speaker.
* X11 Keysyms::         Operating on key symbols for X Windows.
* Batch Mode::          Running Emacs without terminal interaction.
* Session Management::  Saving and restoring state with X Session Management.


File: elisp,  Node: Starting Up,  Next: Getting Out,  Up: System Interface

39.1 Starting Up Emacs
======================

This section describes what Emacs does when it is started, and how you
can customize these actions.

* Menu:

* Startup Summary::         Sequence of actions Emacs performs at startup.
* Init File::               Details on reading the init file.
* Terminal-Specific::       How the terminal-specific Lisp file is read.
* Command-Line Arguments::  How command-line arguments are processed,
                              and how you can customize them.


File: elisp,  Node: Startup Summary,  Next: Init File,  Up: Starting Up

39.1.1 Summary: Sequence of Actions at Startup
----------------------------------------------

When Emacs is started up, it performs the following operations (which
are defined in `startup.el'):

  1. It adds subdirectories to `load-path', by running the file named
     `subdirs.el' in each directory in the list.  Normally, this file
     adds the directory's subdirectories to the list, and those are
     scanned in their turn.  The files `subdirs.el' are normally
     generated automatically when Emacs is installed.

  2. It sets the variable `before-init-time' to the value of
     `current-time' (*note Time of Day::).  It also sets
     `after-init-time' to `nil', which signals to Lisp programs that
     Emacs is being initialized.

  3. It loads the initialization library for the window system
     specified by the variable `initial-window-system' (*note
     initial-window-system: Window Systems.).  This library's name is
     `term/WINDOWSYSTEM-win.el', where WINDOWSYSTEM is the value of
     `initial-window-system'.  From that library, it calls the
     appropriate initialization function.  The initialization function
     for each supported window system is specified by
     `window-system-initialization-alist'.

  4. It sets the language environment and the terminal coding system,
     if requested by environment variables such as `LANG'.

  5. It processes the initial options.  (Some of them are handled even
     earlier than this.)

  6. It runs the normal hook `before-init-hook'.

  7. It initializes the window frame and faces, if appropriate, and
     turns on the menu bar and tool bar, if the initial frame needs
     them.

  8. It loads the library `site-start', if it exists.  This is not done
     if the options `-Q' or `--no-site-file' were specified.  

  9. It loads your init file (*note Init File::).  This is not done if
     the options `-q', `-Q', or `--batch' were specified.  If the `-u'
     option was specified, Emacs looks for the init file in that user's
     home directory instead.

 10. It loads the library `default', if it exists.  This is not done if
     `inhibit-default-init' is non-`nil', nor if the options `-q',
     `-Q', or `--batch' were specified.  

 11. It loads your abbrevs from the file specified by
     `abbrev-file-name', if that file exists and can be read (*note
     abbrev-file-name: Abbrev Files.).  This is not done if the option
     `--batch' was specified.

 12. It sets the variable `after-init-time' to the value of
     `current-time'.  This variable was set to `nil' earlier; setting
     it to the current time signals that the initialization phase is
     over, and, together with `before-init-time', provides the
     measurement of how long it took.

 13. It runs the normal hook `after-init-hook'.

 14. If the buffer `*scratch*' exists and is still in Fundamental mode
     (as it should be by default), it sets its major mode according to
     `initial-major-mode'.

 15. If started on a text-only terminal, it loads the terminal-specific
     Lisp library, which is specified by the variable
     `term-file-prefix' (*note Terminal-Specific::).  This is not done
     in `--batch' mode, nor if `term-file-prefix' is `nil'.

 16. It displays the initial echo area message, unless you have
     suppressed that with `inhibit-startup-echo-area-message'.

 17. It processes the action arguments from the command line.

 18. It now exits if the option `--batch' was specified.

 19. If `initial-buffer-choice' is a string, it visits the file with
     that name.  Furthermore, if the `*scratch*' buffer exists and is
     empty, it inserts `initial-scratch-message' into that buffer.

 20. It runs `emacs-startup-hook' and then `term-setup-hook'.

 21. It calls `frame-notice-user-settings', which modifies the
     parameters of the selected frame according to whatever the init
     files specify.

 22. It runs `window-setup-hook'.  *Note Window Systems::.

 23. If the option `--daemon' was specified, it calls `server-start'
     and detaches from the controlling terminal.  *Note Emacs Server:
     (emacs)Emacs Server.

 24. It displays the "startup screen", which is a special buffer that
     contains information about copyleft and basic Emacs usage.  This is
     not done if `initial-buffer-choice' or `inhibit-startup-screen'
     are `nil', nor if the `--no-splash' or `-Q' command-line options
     were specified.

 25. If started by the X session manager, it calls
     `emacs-session-restore' passing it as argument the ID of the
     previous session.  *Note Session Management::.

 -- User Option: inhibit-startup-screen
     This variable, if non-`nil', inhibits the startup screen.  In that
     case, Emacs typically displays the `*scratch*' buffer; but see
     `initial-buffer-choice', below.

     Do not set this variable in the init file of a new user, or in a
     way that affects more than one user, as that would prevent new
     users from receiving information about copyleft and basic Emacs
     usage.

     `inhibit-startup-message' and `inhibit-splash-screen' are aliases
     for this variable.

 -- User Option: initial-buffer-choice
     This variable, if non-`nil', determines a file or buffer for Emacs
     to display after starting up, instead of the startup screen.  If
     its value is `t', Emacs displays the `*scratch*' buffer.  If its
     value is a string, that specifies the name of a file for Emacs to
     visit.

 -- User Option: 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 init file:

          (setq inhibit-startup-echo-area-message
                "YOUR-LOGIN-NAME")

     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
     `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
     init file will not inhibit the message for someone else.

 -- User Option: initial-scratch-message
     This variable, if non-`nil', should be a string, which is inserted
     into the `*scratch*' buffer when Emacs starts up.  If it is `nil',
     the `*scratch*' buffer is empty.


File: elisp,  Node: Init File,  Next: Terminal-Specific,  Prev: Startup Summary,  Up: Starting Up

39.1.2 The Init File, `.emacs'
------------------------------

When you start Emacs, it normally attempts to load your "init file".
This is either a file named `.emacs' or `.emacs.el' in your home
directory, or a file named `init.el' in a subdirectory named `.emacs.d'
in your home directory.  Whichever place you use, you can also compile
the file (*note Byte Compilation::); then the actual file loaded will
be `.emacs.elc' or `init.elc'.

   The command-line switches `-q', `-Q', and `-u' control whether and
where to find the init file; `-q' (and the stronger `-Q') says not to
load an init file, while `-u USER' says to load USER's init file
instead of yours.  *Note Entering Emacs: (emacs)Entering Emacs.  If
neither option is specified, Emacs uses the `LOGNAME' environment
variable, or the `USER' (most systems) or `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.

   A site may have a "default init file", which is the library named
`default.el'.  Emacs finds the `default.el' file through the standard
search path for libraries (*note How Programs Do Loading::).  The Emacs
distribution does not come with this file; sites may provide one for
local customizations.  If the default init file exists, it is loaded
whenever you start Emacs, except in batch mode or if `-q' (or `-Q') is
specified.  But your own personal init file, if any, is loaded first;
if it sets `inhibit-default-init' to a non-`nil' value, then Emacs does
not subsequently load the `default.el' file.

   Another file for site-customization is `site-start.el'.  Emacs loads
this _before_ the user's init file.  You can inhibit the loading of
this file with the option `--no-site-file'.

 -- User Option: site-run-file
     This variable specifies the site-customization file to load before
     the user's init file.  Its normal value is `"site-start"'.  The
     only way you can change it with real effect is to do so before
     dumping Emacs.

   *Note Init File Examples: (emacs)Init Examples, for examples of how
to make various commonly desired customizations in your `.emacs' file.

 -- User Option: inhibit-default-init
     This variable prevents Emacs from loading the default
     initialization library file for your session of Emacs.  If its
     value is non-`nil', then the default library is not loaded.  The
     default value is `nil'.

 -- Variable: before-init-hook
     This normal hook is run, once, just before loading all the init
     files (the user's init file, `default.el', and/or `site-start.el').
     (The only way to change it with real effect is before dumping
     Emacs.)

 -- Variable: after-init-hook
     This normal hook is run, once, just after loading all the init
     files (the user's init file, `default.el', and/or `site-start.el'),
     before loading the terminal-specific library and processing the
     command-line action arguments.

 -- Variable: emacs-startup-hook
     This normal hook is run, once, just after handling the command line
     arguments, just before `term-setup-hook'.

 -- Variable: user-init-file
     This variable holds the absolute file name of the user's init
     file.  If the actual init file loaded is a compiled file, such as
     `.emacs.elc', the value refers to the corresponding source file.

 -- Variable: user-emacs-directory
     This variable holds the name of the `.emacs.d' directory.  It is
     ordinarily `~/.emacs.d', but differs on some platforms.


File: elisp,  Node: Terminal-Specific,  Next: Command-Line Arguments,  Prev: Init File,  Up: Starting Up

39.1.3 Terminal-Specific Initialization
---------------------------------------

Each terminal type can have its own Lisp library that Emacs loads when
run on that type of terminal.  The library's name is constructed by
concatenating the value of the variable `term-file-prefix' and the
terminal type (specified by the environment variable `TERM').
Normally, `term-file-prefix' has the value `"term/"'; changing this is
not recommended.  Emacs finds the file in the normal manner, by
searching the `load-path' directories, and trying the `.elc' and `.el'
suffixes.

   The usual function of a terminal-specific library is to enable
special keys to send sequences that Emacs can recognize.  It may also
need to set or add to `input-decode-map' if the Termcap or Terminfo
entry does not specify all the terminal's function keys.  *Note
Terminal Input::.

   When the name of the terminal type contains a hyphen, and no library
is found whose name is identical to the terminal's name, Emacs strips
from the terminal's name the last hyphen and everything that follows
it, and tries again.  This process is repeated until Emacs finds a
matching library or until there are no more hyphens in the name (the
latter means the terminal doesn't have any library specific to it).
Thus, for example, if there are no `aaa-48' and `aaa-30' libraries,
Emacs will try the same library `term/aaa.el' for terminal types
`aaa-48' and `aaa-30-rv'.  If necessary, the library can evaluate
`(getenv "TERM")' to find the full name of the terminal type.

   Your init file can prevent the loading of the terminal-specific
library by setting the variable `term-file-prefix' to `nil'.  This
feature is useful when experimenting with your own peculiar
customizations.

   You can also arrange to override some of the actions of the
terminal-specific library by setting the variable `term-setup-hook'.
This is a normal hook which Emacs runs using `run-hooks' at the end of
Emacs initialization, after loading both 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.
*Note Hooks::.

 -- Variable: term-file-prefix
     If the `term-file-prefix' variable is non-`nil', Emacs loads a
     terminal-specific initialization file as follows:

          (load (concat term-file-prefix (getenv "TERM")))

     You may set the `term-file-prefix' variable to `nil' in your init
     file if you do not wish to load the terminal-initialization file.
     To do this, put the following in your init file: `(setq
     term-file-prefix nil)'.

     On MS-DOS, if the environment variable `TERM' is not set, Emacs
     uses `internal' as the terminal type.

 -- Variable: term-setup-hook
     This variable is a normal hook that Emacs runs after loading your
     init file, the default initialization file (if any) and the
     terminal-specific Lisp file.

     You can use `term-setup-hook' to override the definitions made by a
     terminal-specific file.

   See `window-setup-hook' in *note Window Systems::, for a related
feature.


File: elisp,  Node: Command-Line Arguments,  Prev: Terminal-Specific,  Up: Starting Up

39.1.4 Command-Line Arguments
-----------------------------

You can use command-line arguments to request various actions when you
start Emacs.  Since you do not need to start Emacs more than once per
day, and will often leave your Emacs session running longer than that,
command-line arguments are hardly ever used.  As a practical matter, it
is best to avoid making the habit of using them, since this habit would
encourage you to kill and restart Emacs unnecessarily often.  These
options exist for two reasons: to be compatible with other editors (for
invocation by other programs) and to enable shell scripts to run
specific Lisp programs.

   This section describes how Emacs processes command-line arguments,
and how you can customize them.

 -- Function: command-line
     This function parses the command line that Emacs was called with,
     processes it, loads the user's init file and displays the startup
     messages.

 -- Variable: command-line-processed
     The value of this variable is `t' once the command line has been
     processed.

     If you redump Emacs by calling `dump-emacs', you may wish to set
     this variable to `nil' first in order to cause the new dumped Emacs
     to process its new command-line arguments.

 -- Variable: command-switch-alist
     The value of this variable is an alist of user-defined command-line
     options and associated handler functions.  This variable exists so
     you can add elements to it.

     A "command-line option" is an argument on the command line, which
     has the form:

          -OPTION

     The elements of the `command-switch-alist' look like this:

          (OPTION . HANDLER-FUNCTION)

     The CAR, OPTION, is a string, the name of a command-line option
     (not including the initial hyphen).  The HANDLER-FUNCTION is
     called to handle OPTION, and receives the option name as its sole
     argument.

     In some cases, the option is followed in the command line by an
     argument.  In these cases, the HANDLER-FUNCTION can find all the
     remaining command-line arguments in the variable
     `command-line-args-left'.  (The entire list of command-line
     arguments is in `command-line-args'.)

     The command-line arguments are parsed by the `command-line-1'
     function in the `startup.el' file.  See also *note Command Line
     Arguments for Emacs Invocation: (emacs)Emacs Invocation.

 -- Variable: command-line-args
     The value of this variable is the list of command-line arguments
     passed to Emacs.

 -- Variable: command-line-args-left
     The value of this variable is the list of command-line arguments
     that have not yet been processed.  `argv' is an alias for this.

 -- Variable: command-line-functions
     This variable's value is a list of functions for handling an
     unrecognized command-line argument.  Each time the next argument
     to be processed has no special meaning, the functions in this list
     are called, in order of appearance, until one of them returns a
     non-`nil' value.

     These functions are called with no arguments.  They can access the
     command-line argument under consideration through the variable
     `argi', which is bound temporarily at this point.  The remaining
     arguments (not including the current one) are in the variable
     `command-line-args-left'.

     When a function recognizes and processes the argument in `argi', it
     should return a non-`nil' value to say it has dealt with that
     argument.  If it has also dealt with some of the following
     arguments, it can indicate that by deleting them from
     `command-line-args-left'.

     If all of these functions return `nil', then the argument is used
     as a file name to visit.


File: elisp,  Node: Getting Out,  Next: System Environment,  Prev: Starting Up,  Up: System Interface

39.2 Getting Out of Emacs
=========================

There are two ways to get out of Emacs: you can kill the Emacs job,
which exits permanently, or you can suspend it, which permits you to
reenter the Emacs process later.  As a practical matter, you seldom kill
Emacs--only when you are about to log out.  Suspending is much more
common.

* Menu:

* Killing Emacs::        Exiting Emacs irreversibly.
* Suspending Emacs::     Exiting Emacs reversibly.


File: elisp,  Node: Killing Emacs,  Next: Suspending Emacs,  Up: Getting Out

39.2.1 Killing Emacs
--------------------

Killing Emacs means ending the execution of the Emacs process.  The
parent process normally resumes control.  The low-level primitive for
killing Emacs is `kill-emacs'.

 -- Command: kill-emacs &optional exit-data
     This command exits the Emacs process and kills it.

     If EXIT-DATA is an integer, then it is used as the exit status of
     the Emacs process.  (This is useful primarily in batch operation;
     see *note Batch Mode::.)

     If EXIT-DATA is a string, its contents are stuffed into the
     terminal input buffer so that the shell (or whatever program next
     reads input) can read them.

   All the information in the Emacs process, aside from files that have
been saved, is lost when the Emacs process is killed.  Because killing
Emacs inadvertently can lose a lot of work, Emacs queries for
confirmation before actually terminating if you have buffers that need
saving or subprocesses that are running.  This is done in the function
`save-buffers-kill-emacs', the higher level function from which
`kill-emacs' is usually called.

 -- Variable: kill-emacs-query-functions
     After asking the standard questions, `save-buffers-kill-emacs'
     calls the functions in the list `kill-emacs-query-functions', in
     order of appearance, with no arguments.  These functions can ask
     for additional confirmation from the user.  If any of them returns
     `nil', `save-buffers-kill-emacs' does not kill Emacs, and does not
     run the remaining functions in this hook.  Calling `kill-emacs'
     directly does not run this hook.

 -- Variable: kill-emacs-hook
     This variable is a normal hook; once `save-buffers-kill-emacs' is
     finished with all file saving and confirmation, it calls
     `kill-emacs' which runs the functions in this hook.  `kill-emacs'
     does not run this hook in batch mode.

     `kill-emacs' may be invoked directly (that is not via
     `save-buffers-kill-emacs') if the terminal is disconnected, or in
     similar situations where interaction with the user is not possible.
     Thus, if your hook needs to interact with the user, put it on
     `kill-emacs-query-functions'; if it needs to run regardless of how
     Emacs is killed, put it on `kill-emacs-hook'.


File: elisp,  Node: Suspending Emacs,  Prev: Killing Emacs,  Up: Getting Out

39.2.2 Suspending Emacs
-----------------------

On text-only terminals, it is possible to "suspend Emacs", which means
stopping Emacs temporarily and returning control to its superior
process, which is usually the shell.  This allows you to resume editing
later in the same Emacs process, with the same buffers, the same kill
ring, the same undo history, and so on.  To resume Emacs, use the
appropriate command in the parent shell--most likely `fg'.

   Suspending works only on a terminal device from which the Emacs
session was started.  We call that device the "controlling terminal" of
the session.  Suspending is not allowed if the controlling terminal is
a graphical terminal.

   Some operating systems do not support suspension of jobs; on these
systems, "suspension" actually creates a new shell temporarily as a
subprocess of Emacs.  Then you would exit the shell to return to Emacs.

 -- Command: suspend-emacs &optional string
     This function stops Emacs and returns control to the superior
     process.  If and when the superior process resumes Emacs,
     `suspend-emacs' returns `nil' to its caller in Lisp.

     This function works only on the controlling terminal of the Emacs
     session; to relinquish control of other tty devices, use
     `suspend-tty' (see below).  If the Emacs session uses more than
     one terminal, you must delete the frames on all the other terminals
     before suspending Emacs, or this function signals an error.  *Note
     Multiple Terminals::.

     If STRING is non-`nil', its characters are sent to Emacs's
     superior shell, to be read as terminal input.  The characters in
     STRING are not echoed by the superior shell; only the results
     appear.

     Before suspending, `suspend-emacs' runs the normal hook
     `suspend-hook'.  After the user resumes Emacs, `suspend-emacs'
     runs the normal hook `suspend-resume-hook'.  *Note Hooks::.

     The next redisplay after resumption will redraw the entire screen,
     unless the variable `no-redraw-on-reenter' is non-`nil'.  *Note
     Refresh Screen::.

     In the following example, note that `pwd' is not echoed after
     Emacs is suspended.  But it is read and executed by the shell.

          (suspend-emacs)
               => nil

          (add-hook 'suspend-hook
                    (function (lambda ()
                                (or (y-or-n-p
                                      "Really suspend? ")
                                    (error "Suspend canceled")))))
               => (lambda nil
                    (or (y-or-n-p "Really suspend? ")
                        (error "Suspend canceled")))
          (add-hook 'suspend-resume-hook
                    (function (lambda () (message "Resumed!"))))
               => (lambda nil (message "Resumed!"))
          (suspend-emacs "pwd")
               => nil
          ---------- Buffer: Minibuffer ----------
          Really suspend? y
          ---------- Buffer: Minibuffer ----------

          ---------- Parent Shell ----------
          lewis@slug[23] % /user/lewis/manual
          lewis@slug[24] % fg

          ---------- Echo Area ----------
          Resumed!

 -- Variable: suspend-hook
     This variable is a normal hook that Emacs runs before suspending.

 -- Variable: suspend-resume-hook
     This variable is a normal hook that Emacs runs on resuming after a
     suspension.

 -- Function: suspend-tty &optional tty
     If TTY specifies a terminal device used by Emacs, this function
     relinquishes the device and restores it to its prior state.  Frames
     that used the device continue to exist, but are not updated and
     Emacs doesn't read input from them.  TTY can be a terminal object,
     a frame (meaning the terminal for that frame), or `nil' (meaning
     the terminal for the selected frame).  *Note Multiple Terminals::.

     If TTY is already suspended, this function does nothing.

     This function runs the hook `suspend-tty-functions', passing the
     terminal object as an argument to each function.

 -- Function: resume-tty &optional tty
     This function resumes the previously suspended terminal device
     TTY; TTY can be a terminal object, a frame (meaning the terminal
     for that frame), or `nil' (meaning the terminal for the selected
     frame).

     This function reopens the terminal device, re-initializes it, and
     redraws its with that terminal's selected frame.  It then runs the
     hook `resume-tty-functions', passing the terminal object as an
     argument to each function.

     If the same device is already used by another Emacs terminal, this
     function signals an error.

 -- Function: controlling-tty-p &optional terminal
     This function returns non-`nil' if TERMINAL is the controlling
     terminal of the Emacs session; `terminal' can be a terminal
     object, a frame (meaning the terminal for that frame), or `nil'
     (meaning the terminal for the selected frame).

 -- Command: suspend-frame
     This command "suspends" a frame.  For GUI frames, it calls
     `iconify-frame' (*note Visibility of Frames::); for text-only
     frames, it calls either `suspend-emacs' or `suspend-tty',
     depending on whether the frame is displayed on the controlling
     terminal device or not.


File: elisp,  Node: System Environment,  Next: User Identification,  Prev: Getting Out,  Up: System Interface

39.3 Operating System Environment
=================================

Emacs provides access to variables in the operating system environment
through various functions.  These variables include the name of the
system, the user's UID, and so on.

 -- Variable: system-configuration
     This variable holds the standard GNU configuration name for the
     hardware/software configuration of your system, as a string.  The
     convenient way to test parts of this string is with `string-match'.

 -- Variable: system-type
     The value of this variable is a symbol indicating the type of
     operating system Emacs is operating on.  Here is a table of the
     possible values:

    `aix'
          IBM's AIX.

    `berkeley-unix'
          Berkeley BSD and its variants.

    `cygwin'
          Cygwin, a Posix layer on top of MS-Windows.

    `darwin'
          Darwin (Mac OS X).

    `gnu'
          The GNU system (using the GNU kernel, which consists of the
          HURD and Mach).

    `gnu/linux'
          A GNU/Linux system--that is, a variant GNU system, using the
          Linux kernel.  (These systems are the ones people often call
          "Linux," but actually Linux is just the kernel, not the whole
          system.)

    `gnu/kfreebsd'
          A GNU (glibc-based) system with a FreeBSD kernel.

    `hpux'
          Hewlett-Packard HPUX operating system.

    `irix'
          Silicon Graphics Irix system.

    `lynxos 3.0.1'
          LynxOS-3.0.1.

    `ms-dos'
          Microsoft MS-DOS "operating system."  Emacs compiled with
          DJGPP for MS-DOS binds `system-type' to `ms-dos' even when
          you run it on MS-Windows.

    `usg-unix-v'
          AT&T Unix System V.

    `windows-nt'
          Microsoft Windows NT and later.  The same executable supports
          Windows 9X, but the value of `system-type' is `windows-nt' in
          either case.


     We do not wish to add new symbols to make finer distinctions
     unless it is absolutely necessary!  In fact, we hope to eliminate
     some of these alternatives in the future.  We recommend using
     `system-configuration' to distinguish between different operating
     systems.

 -- Function: system-name
     This function returns the name of the machine you are running on.
          (system-name)
               => "www.gnu.org"

   The symbol `system-name' is a variable as well as a function.  In
fact, the function returns whatever value the variable `system-name'
currently holds.  Thus, you can set the variable `system-name' in case
Emacs is confused about the name of your system.  The variable is also
useful for constructing frame titles (*note Frame Titles::).

 -- User Option: mail-host-address
     If this variable is non-`nil', it is used instead of `system-name'
     for purposes of generating email addresses.  For example, it is
     used when constructing the default value of `user-mail-address'.
     *Note User Identification::.  (Since this is done when Emacs
     starts up, the value actually used is the one saved when Emacs was
     dumped.  *Note Building Emacs::.)

 -- Command: getenv var &optional frame
     This function returns the value of the environment variable VAR,
     as a string.  VAR should be a string.  If VAR is undefined in the
     environment, `getenv' returns `nil'.  If returns `""' if VAR is
     set but null.  Within Emacs, the environment variable values are
     kept in the Lisp variable `process-environment'.

          (getenv "USER")
               => "lewis"

          lewis@slug[10] % printenv
          PATH=.:/user/lewis/bin:/usr/bin:/usr/local/bin
          USER=lewis
          TERM=ibmapa16
          SHELL=/bin/csh
          HOME=/user/lewis

 -- Command: setenv variable &optional value
     This command sets the value of the environment variable named
     VARIABLE to VALUE.  VARIABLE should be a string.  Internally,
     Emacs Lisp can handle any string.  However, normally VARIABLE
     should be a valid shell identifier, that is, a sequence of
     letters, digits and underscores, starting with a letter or
     underscore.  Otherwise, errors may occur if subprocesses of Emacs
     try to access the value of VARIABLE.  If VALUE is omitted or
     `nil', `setenv' removes VARIABLE from the environment.  Otherwise,
     VALUE should be a string.

     `setenv' works by modifying `process-environment'; binding that
     variable with `let' is also reasonable practice.

     `setenv' returns the new value of VARIABLE, or `nil' if it removed
     VARIABLE from the environment.

 -- Variable: process-environment
     This variable is a list of strings, each describing one environment
     variable.  The functions `getenv' and `setenv' work by means of
     this variable.

          process-environment
          => ("l=/usr/stanford/lib/gnuemacs/lisp"
              "PATH=.:/user/lewis/bin:/usr/class:/nfsusr/local/bin"
              "USER=lewis"
              "TERM=ibmapa16"
              "SHELL=/bin/csh"
              "HOME=/user/lewis")

     If `process-environment' contains "duplicate" elements that
     specify the same environment variable, the first of these elements
     specifies the variable, and the other "duplicates" are ignored.

 -- Variable: initial-environment
     This variable holds the list of environment variables Emacs
     inherited from its parent process.  It is computed during startup,
     see *note Startup Summary::.

 -- Variable: path-separator
     This variable holds a string which says which character separates
     directories in a search path (as found in an environment
     variable).  Its value is `":"' for Unix and GNU systems, and `";"'
     for MS-DOS and MS-Windows.

 -- Function: parse-colon-path path
     This function takes a search path string such as would be the
     value of the `PATH' environment variable, and splits it at the
     separators, returning a list of directory names.  `nil' in this
     list stands for "use the current directory."  Although the
     function's name says "colon," it actually uses the value of
     `path-separator'.

          (parse-colon-path ":/foo:/bar")
               => (nil "/foo/" "/bar/")

 -- Variable: invocation-name
     This variable holds the program name under which Emacs was
     invoked.  The value is a string, and does not include a directory
     name.

 -- Variable: invocation-directory
     This variable holds the directory from which the Emacs executable
     was invoked, or perhaps `nil' if that directory cannot be
     determined.

 -- Variable: installation-directory
     If non-`nil', this is a directory within which to look for the
     `lib-src' and `etc' subdirectories.  This is non-`nil' when Emacs
     can't find those directories in their standard installed
     locations, but can find them in a directory related somehow to the
     one containing the Emacs executable.

 -- Function: load-average &optional use-float
     This function returns the current 1-minute, 5-minute, and
     15-minute load averages, in a list.

     By default, the values are integers that are 100 times the system
     load averages, which indicate the average number of processes
     trying to run.  If USE-FLOAT is non-`nil', then they are returned
     as floating point numbers and without multiplying by 100.

     If it is impossible to obtain the load average, this function
     signals an error.  On some platforms, access to load averages
     requires installing Emacs as setuid or setgid so that it can read
     kernel information, and that usually isn't advisable.

     If the 1-minute load average is available, but the 5- or 15-minute
     averages are not, this function returns a shortened list containing
     the available averages.

          (load-average)
               => (169 48 36)
          (load-average t)
               => (1.69 0.48 0.36)

          lewis@rocky[5] % uptime
           11:55am  up 1 day, 19:37,  3 users,
           load average: 1.69, 0.48, 0.36

 -- Function: emacs-pid
     This function returns the process ID of the Emacs process, as an
     integer.

 -- Variable: tty-erase-char
     This variable holds the erase character that was selected in the
     system's terminal driver, before Emacs was started.  The value is
     `nil' if Emacs is running under a window system.


File: elisp,  Node: User Identification,  Next: Time of Day,  Prev: System Environment,  Up: System Interface

39.4 User Identification
========================

 -- Variable: init-file-user
     This variable says which user's init files should be used by
     Emacs--or `nil' if none.  `""' stands for the user who originally
     logged in.  The value reflects command-line options such as `-q'
     or `-u USER'.

     Lisp packages that load files of customizations, or any other sort
     of user profile, should obey this variable in deciding where to
     find it.  They should load the profile of the user name found in
     this variable.  If `init-file-user' is `nil', meaning that the `-q'
     option was used, then Lisp packages should not load any
     customization files or user profile.

 -- User Option: user-mail-address
     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 init file if
     you do not want to use the default value.

 -- Function: user-login-name &optional uid
     If you don't specify UID, this function returns the name under
     which the user is logged in.  If the environment variable `LOGNAME'
     is set, that value is used.  Otherwise, if the environment variable
     `USER' is set, that value is used.  Otherwise, the value is based
     on the effective UID, not the real UID.

     If you specify UID, the value is the user name that corresponds to
     UID (which should be an integer), or `nil' if there is no such
     user.

          (user-login-name)
               => "lewis"

 -- Function: user-real-login-name
     This function returns the user name corresponding to Emacs's real
     UID.  This ignores the effective UID and ignores the environment
     variables `LOGNAME' and `USER'.

 -- Function: user-full-name &optional uid
     This function returns the full name of the logged-in user--or the
     value of the environment variable `NAME', if that is set.

          (user-full-name)
               => "Bil Lewis"

     If the Emacs job's user-id does not correspond to any known user
     (and provided `NAME' is not set), the value is `"unknown"'.

     If UID is non-`nil', then it should be a number (a user-id) or a
     string (a login name).  Then `user-full-name' returns the full
     name corresponding to that user-id or login name.  If you specify a
     user-id or login name that isn't defined, it returns `nil'.

   The symbols `user-login-name', `user-real-login-name' and
`user-full-name' are variables as well as functions.  The functions
return the same values that the variables hold.  These variables allow
you to "fake out" Emacs by telling the functions what to return.  The
variables are also useful for constructing frame titles (*note Frame
Titles::).

 -- Function: user-real-uid
     This function returns the real UID of the user.  The value may be
     a floating point number.

          (user-real-uid)
               => 19

 -- Function: user-uid
     This function returns the effective UID of the user.  The value
     may be a floating point number.


File: elisp,  Node: Time of Day,  Next: Time Conversion,  Prev: User Identification,  Up: System Interface

39.5 Time of Day
================

This section explains how to determine the current time and the time
zone.

 -- Function: current-time-string &optional time-value
     This function returns the current time and date as a human-readable
     string.  The format of the string is unvarying; the number of
     characters used for each part is always the same, so you can
     reliably use `substring' to extract pieces of it.  It is wise to
     count the characters from the beginning of the string rather than
     from the end, as additional information may some day be added at
     the end.

     The argument TIME-VALUE, if given, specifies a time to format
     instead of the current time.  This argument should have the same
     form as the times obtained from `current-time' (see below) and from
     `file-attributes' (*note Definition of file-attributes::).  It
     should be a list whose first two elements are integers; a third
     (microsecond) element, if present, is ignored.  TIME-VALUE can
     also be a cons of two integers, but this usage is obsolete.

          (current-time-string)
               => "Wed Oct 14 22:21:05 1987"

 -- Function: current-time
     This function returns the system's time value as a list of three
     integers: `(HIGH LOW MICROSEC)'.  The integers HIGH and LOW
     combine to give the number of seconds since 0:00 January 1, 1970
     UTC (Coordinated Universal Time), which is HIGH * 2**16 + LOW.

     The third element, MICROSEC, gives the microseconds since the
     start of the current second (or 0 for systems that return time with
     the resolution of only one second).

     The first two elements can be compared with file time values such
     as you get with the function `file-attributes'.  *Note Definition
     of file-attributes::.

 -- Function: current-time-zone &optional time-value
     This function returns a list describing the time zone that the
     user is in.

     The value has the form `(OFFSET NAME)'.  Here OFFSET is an integer
     giving the number of seconds ahead of UTC (east of Greenwich).  A
     negative value means west of Greenwich.  The second element, NAME,
     is a string giving the name of the time zone.  Both elements
     change when daylight saving time begins or ends; if the user has
     specified a time zone that does not use a seasonal time
     adjustment, then the value is constant through time.

     If the operating system doesn't supply all the information
     necessary to compute the value, the unknown elements of the list
     are `nil'.

     The argument TIME-VALUE, if given, specifies a time to analyze
     instead of the current time.  The argument should have the same
     form as for `current-time-string' (see above).  Thus, you can use
     times obtained from `current-time' (see above) and from
     `file-attributes'.  *Note Definition of file-attributes::.

 -- Function: set-time-zone-rule tz
     This function specifies the local time zone according to TZ.  If
     TZ is `nil', that means to use an implementation-defined default
     time zone.  If TZ is `t', that means to use Universal Time.
     Otherwise, TZ should be a string specifying a time zone rule.

 -- Function: float-time &optional time-value
     This function returns the current time as a floating-point number
     of seconds since the epoch.  The argument TIME-VALUE, if given,
     specifies a time to convert instead of the current time.  The
     argument should have the same form as for `current-time-string'
     (see above).  Thus, it accepts the output of `current-time' and
     `file-attributes' (*note Definition of file-attributes::).

     _Warning_: Since the result is floating point, it may not be
     exact.  Do not use this function if precise time stamps are
     required.


File: elisp,  Node: Time Conversion,  Next: Time Parsing,  Prev: Time of Day,  Up: System Interface

39.6 Time Conversion
====================

These functions convert time values (lists of two or three integers) to
calendrical information and vice versa.  You can get time values from
the functions `current-time' (*note Time of Day::) and
`file-attributes' (*note Definition of file-attributes::).

   Many operating systems are limited to time values that contain 32
bits of information; these systems typically handle only the times from
1901-12-13 20:45:52 UTC through 2038-01-19 03:14:07 UTC.  However, some
operating systems have larger time values, and can represent times far
in the past or future.

   Time conversion functions always use the Gregorian calendar, even
for dates before the Gregorian calendar was introduced.  Year numbers
count the number of years since the year 1 B.C., and do not skip zero
as traditional Gregorian years do; for example, the year number -37
represents the Gregorian year 38 B.C.

 -- Function: decode-time &optional time
     This function converts a time value into calendrical information.
     If you don't specify TIME, it decodes the current time.  The return
     value is a list of nine elements, as follows:

          (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST ZONE)

     Here is what the elements mean:

    SECONDS
          The number of seconds past the minute, as an integer between
          0 and 59.  On some operating systems, this is 60 for leap
          seconds.

    MINUTES
          The number of minutes past the hour, as an integer between 0
          and 59.

    HOUR
          The hour of the day, as an integer between 0 and 23.

    DAY
          The day of the month, as an integer between 1 and 31.

    MONTH
          The month of the year, as an integer between 1 and 12.

    YEAR
          The year, an integer typically greater than 1900.

    DOW
          The day of week, as an integer between 0 and 6, where 0
          stands for Sunday.

    DST
          `t' if daylight saving time is effect, otherwise `nil'.

    ZONE
          An integer indicating the time zone, as the number of seconds
          east of Greenwich.

     *Common Lisp Note:* Common Lisp has different meanings for DOW and
     ZONE.

 -- Function: encode-time seconds minutes hour day month year &optional
          zone
     This function is the inverse of `decode-time'.  It converts seven
     items of calendrical data into a time value.  For the meanings of
     the arguments, see the table above under `decode-time'.

     Year numbers less than 100 are not treated specially.  If you want
     them to stand for years above 1900, or years above 2000, you must
     alter them yourself before you call `encode-time'.

     The optional argument ZONE defaults to the current time zone and
     its daylight saving time rules.  If specified, it can be either a
     list (as you would get from `current-time-zone'), a string as in
     the `TZ' environment variable, `t' for Universal Time, or an
     integer (as you would get from `decode-time').  The specified zone
     is used without any further alteration for daylight saving time.

     If you pass more than seven arguments to `encode-time', the first
     six are used as SECONDS through YEAR, the last argument is used as
     ZONE, and the arguments in between are ignored.  This feature
     makes it possible to use the elements of a list returned by
     `decode-time' as the arguments to `encode-time', like this:

          (apply 'encode-time (decode-time ...))

     You can perform simple date arithmetic by using out-of-range
     values for the SECONDS, MINUTES, HOUR, DAY, and MONTH arguments;
     for example, day 0 means the day preceding the given month.

     The operating system puts limits on the range of possible time
     values; if you try to encode a time that is out of range, an error
     results.  For instance, years before 1970 do not work on some
     systems; on others, years as early as 1901 do work.


File: elisp,  Node: Time Parsing,  Next: Processor Run Time,  Prev: Time Conversion,  Up: System Interface

39.7 Parsing and Formatting Times
=================================

These functions convert time values (lists of two or three integers) to
text in a string, and vice versa.

 -- Function: date-to-time string
     This function parses the time-string STRING and returns the
     corresponding time value.

 -- Function: format-time-string format-string &optional time universal
     This function converts TIME (or the current time, if TIME is
     omitted) to a string according to FORMAT-STRING.  The argument
     FORMAT-STRING may contain `%'-sequences which say to substitute
     parts of the time.  Here is a table of what the `%'-sequences mean:

    `%a'
          This stands for the abbreviated name of the day of week.

    `%A'
          This stands for the full name of the day of week.

    `%b'
          This stands for the abbreviated name of the month.

    `%B'
          This stands for the full name of the month.

    `%c'
          This is a synonym for `%x %X'.

    `%C'
          This has a locale-specific meaning.  In the default locale
          (named C), it is equivalent to `%A, %B %e, %Y'.

    `%d'
          This stands for the day of month, zero-padded.

    `%D'
          This is a synonym for `%m/%d/%y'.

    `%e'
          This stands for the day of month, blank-padded.

    `%h'
          This is a synonym for `%b'.

    `%H'
          This stands for the hour (00-23).

    `%I'
          This stands for the hour (01-12).

    `%j'
          This stands for the day of the year (001-366).

    `%k'
          This stands for the hour (0-23), blank padded.

    `%l'
          This stands for the hour (1-12), blank padded.

    `%m'
          This stands for the month (01-12).

    `%M'
          This stands for the minute (00-59).

    `%n'
          This stands for a newline.

    `%p'
          This stands for `AM' or `PM', as appropriate.

    `%r'
          This is a synonym for `%I:%M:%S %p'.

    `%R'
          This is a synonym for `%H:%M'.

    `%S'
          This stands for the seconds (00-59).

    `%t'
          This stands for a tab character.

    `%T'
          This is a synonym for `%H:%M:%S'.

    `%U'
          This stands for the week of the year (01-52), assuming that
          weeks start on Sunday.

    `%w'
          This stands for the numeric day of week (0-6).  Sunday is day
          0.

    `%W'
          This stands for the week of the year (01-52), assuming that
          weeks start on Monday.

    `%x'
          This has a locale-specific meaning.  In the default locale
          (named `C'), it is equivalent to `%D'.

    `%X'
          This has a locale-specific meaning.  In the default locale
          (named `C'), it is equivalent to `%T'.

    `%y'
          This stands for the year without century (00-99).

    `%Y'
          This stands for the year with century.

    `%Z'
          This stands for the time zone abbreviation (e.g., `EST').

    `%z'
          This stands for the time zone numerical offset (e.g.,
          `-0500').

     You can also specify the field width and type of padding for any of
     these `%'-sequences.  This works as in `printf': you write the
     field width as digits in the middle of a `%'-sequences.  If you
     start the field width with `0', it means to pad with zeros.  If you
     start the field width with `_', it means to pad with spaces.

     For example, `%S' specifies the number of seconds since the minute;
     `%03S' means to pad this with zeros to 3 positions, `%_3S' to pad
     with spaces to 3 positions.  Plain `%3S' pads with zeros, because
     that is how `%S' normally pads to two positions.

     The characters `E' and `O' act as modifiers when used between `%'
     and one of the letters in the table above.  `E' specifies using
     the current locale's "alternative" version of the date and time.
     In a Japanese locale, for example, `%Ex' might yield a date format
     based on the Japanese Emperors' reigns.  `E' is allowed in `%Ec',
     `%EC', `%Ex', `%EX', `%Ey', and `%EY'.

     `O' means to use the current locale's "alternative" representation
     of numbers, instead of the ordinary decimal digits.  This is
     allowed with most letters, all the ones that output numbers.

     If UNIVERSAL is non-`nil', that means to describe the time as
     Universal Time; `nil' means describe it using what Emacs believes
     is the local time zone (see `current-time-zone').

     This function uses the C library function `strftime' (*note
     Formatting Calendar Time: (libc)Formatting Calendar Time.) to do
     most of the work.  In order to communicate with that function, it
     first encodes its argument using the coding system specified by
     `locale-coding-system' (*note Locales::); after `strftime' returns
     the resulting string, `format-time-string' decodes the string
     using that same coding system.

 -- Function: seconds-to-time seconds
     This function converts SECONDS, a floating point number of seconds
     since the epoch, to a time value and returns that.  To perform the
     inverse conversion, use `float-time'.

 -- Function: format-seconds format-string seconds
     This function converts its argument SECONDS into a string of
     years, days, hours, etc., according to FORMAT-STRING.  The
     argument FORMAT-STRING may contain `%'-sequences which control the
     conversion.  Here is a table of what the `%'-sequences mean:

    `%y'
    `%Y'
          The integer number of 365-day years.

    `%d'
    `%D'
          The integer number of days.

    `%h'
    `%H'
          The integer number of hours.

    `%m'
    `%M'
          The integer number of minutes.

    `%s'
    `%S'
          The integer number of seconds.

    `%z'
          Non-printing control flag.  When it is used, other specifiers
          must be given in the order of decreasing size, i.e. years
          before days, hours before minutes, etc.  Nothing will be
          produced in the result string to the left of `%z' until the
          first non-zero conversion is encountered.  For example, the
          default format used by `emacs-uptime' (*note emacs-uptime:
          Processor Run Time.)  `"%Y, %D, %H, %M, %z%S"' means that the
          number of seconds will always be produced, but years, days,
          hours, and minutes will only be shown if they are non-zero.

    `%%'
          Produces a literal `%'.

     Upper-case format sequences produce the units in addition to the
     numbers, lower-case formats produce only the numbers.

     You can also specify the field width by following the `%' with a
     number; shorter numbers will be padded with blanks.  An optional
     period before the width requests zero-padding instead.  For
     example, `"%.3Y"' might produce `"004 years"'.

     _Warning:_ This function works only with values of SECONDS that
     don't exceed `most-positive-fixnum' (*note most-positive-fixnum:
     Integer Basics.).


File: elisp,  Node: Processor Run Time,  Next: Time Calculations,  Prev: Time Parsing,  Up: System Interface

39.8 Processor Run time
=======================

Emacs provides several functions and primitives that return time, both
elapsed and processor time, used by the Emacs process.

 -- Command: emacs-uptime &optional format
     This function returns a string representing the Emacs
     "uptime"--the elapsed wall-clock time this instance of Emacs is
     running.  The string is formatted by `format-seconds' according to
     the optional argument FORMAT.  For the available format
     descriptors, see *note format-seconds: Time Parsing.  If FORMAT is
     `nil' or omitted, it defaults to `"%Y, %D, %H, %M, %z%S"'.

     When called interactively, it prints the uptime in the echo area.

 -- Function: get-internal-run-time
     This function returns the processor run time used by Emacs as a
     list of three integers: `(HIGH LOW MICROSEC)'.  The integers HIGH
     and LOW combine to give the number of seconds, which is HIGH *
     2**16 + LOW.

     The third element, MICROSEC, gives the microseconds (or 0 for
     systems that return time with the resolution of only one second).

     Note that the time returned by this function excludes the time
     Emacs was not using the processor, and if the Emacs process has
     several threads, the returned value is the sum of the processor
     times used up by all Emacs threads.

     If the system doesn't provide a way to determine the processor run
     time, `get-internal-run-time' returns the same time as
     `current-time'.

 -- Command: emacs-init-time
     This function returns the duration of the Emacs initialization
     (*note Startup Summary::) in seconds, as a string.  When called
     interactively, it prints the duration in the echo area.


File: elisp,  Node: Time Calculations,  Next: Timers,  Prev: Processor Run Time,  Up: System Interface

39.9 Time Calculations
======================

These functions perform calendrical computations using time values (the
kind of list that `current-time' returns).

 -- Function: time-less-p t1 t2
     This returns `t' if time value T1 is less than time value T2.

 -- Function: time-subtract t1 t2
     This returns the time difference T1 - T2 between two time values,
     in the same format as a time value.

 -- Function: time-add t1 t2
     This returns the sum of two time values, one of which ought to
     represent a time difference rather than a point in time.  Here is
     how to add a number of seconds to a time value:

          (time-add TIME (seconds-to-time SECONDS))

 -- Function: time-to-days time
     This function returns the number of days between the beginning of
     year 1 and TIME.

 -- Function: time-to-day-in-year time
     This returns the day number within the year corresponding to TIME.

 -- Function: date-leap-year-p year
     This function returns `t' if YEAR is a leap year.


File: elisp,  Node: Timers,  Next: Idle Timers,  Prev: Time Calculations,  Up: System Interface

39.10 Timers for Delayed Execution
==================================

You can set up a "timer" to call a function at a specified future time
or after a certain length of idleness.

   Emacs cannot run timers at any arbitrary point in a Lisp program; it
can run them only when Emacs could accept output from a subprocess:
namely, while waiting or inside certain primitive functions such as
`sit-for' or `read-event' which _can_ wait.  Therefore, a timer's
execution may be delayed if Emacs is busy.  However, the time of
execution is very precise if Emacs is idle.

   Emacs binds `inhibit-quit' to `t' before calling the timer function,
because quitting out of many timer functions can leave things in an
inconsistent state.  This is normally unproblematical because most
timer functions don't do a lot of work.  Indeed, for a timer to call a
function that takes substantial time to run is likely to be annoying.
If a timer function needs to allow quitting, it should use
`with-local-quit' (*note Quitting::).  For example, if a timer function
calls `accept-process-output' to receive output from an external
process, that call should be wrapped inside `with-local-quit', to
ensure that `C-g' works if the external process hangs.

   It is usually a bad idea for timer functions to alter buffer
contents.  When they do, they usually should call `undo-boundary' both
before and after changing the buffer, to separate the timer's changes
from user commands' changes and prevent a single undo entry from
growing to be quite large.

   Timer functions should also avoid calling functions that cause Emacs
to wait, such as `sit-for' (*note Waiting::).  This can lead to
unpredictable effects, since other timers (or even the same timer) can
run while waiting.  If a timer function needs to perform an action
after a certain time has elapsed, it can do this by scheduling a new
timer.

   If a timer function calls functions that can change the match data,
it should save and restore the match data.  *Note Saving Match Data::.

 -- Command: run-at-time time repeat function &rest args
     This sets up a timer that calls the function FUNCTION with
     arguments ARGS at time TIME.  If REPEAT is a number (integer or
     floating point), the timer is scheduled to run again every REPEAT
     seconds after TIME.  If REPEAT is `nil', the timer runs only once.

     TIME may specify an absolute or a relative time.

     Absolute times may be specified using a string with a limited
     variety of formats, and are taken to be times _today_, even if
     already in the past.  The recognized forms are `XXXX', `X:XX', or
     `XX:XX' (military time), and `XXam', `XXAM', `XXpm', `XXPM',
     `XX:XXam', `XX:XXAM', `XX:XXpm', or `XX:XXPM'.  A period can be
     used instead of a colon to separate the hour and minute parts.

     To specify a relative time as a string, use numbers followed by
     units.  For example:

    `1 min'
          denotes 1 minute from now.

    `1 min 5 sec'
          denotes 65 seconds from now.

    `1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year'
          denotes exactly 103 months, 123 days, and 10862 seconds from
          now.

     For relative time values, Emacs considers a month to be exactly
     thirty days, and a year to be exactly 365.25 days.

     Not all convenient formats are strings.  If TIME is a number
     (integer or floating point), that specifies a relative time
     measured in seconds.  The result of `encode-time' can also be used
     to specify an absolute value for TIME.

     In most cases, REPEAT has no effect on when _first_ call takes
     place--TIME alone specifies that.  There is one exception: if TIME
     is `t', then the timer runs whenever the time is a multiple of
     REPEAT seconds after the epoch.  This is useful for functions like
     `display-time'.

     The function `run-at-time' returns a timer value that identifies
     the particular scheduled future action.  You can use this value to
     call `cancel-timer' (see below).

   A repeating timer nominally ought to run every REPEAT seconds, but
remember that any invocation of a timer can be late.  Lateness of one
repetition has no effect on the scheduled time of the next repetition.
For instance, if Emacs is busy computing for long enough to cover three
scheduled repetitions of the timer, and then starts to wait, it will
immediately call the timer function three times in immediate succession
(presuming no other timers trigger before or between them).  If you
want a timer to run again no less than N seconds after the last
invocation, don't use the REPEAT argument.  Instead, the timer function
should explicitly reschedule the timer.

 -- Variable: timer-max-repeats
     This variable's value specifies the maximum number of times to
     repeat calling a timer function in a row, when many previously
     scheduled calls were unavoidably delayed.

 -- Macro: with-timeout (seconds timeout-forms...) body...
     Execute BODY, but give up after SECONDS seconds.  If BODY finishes
     before the time is up, `with-timeout' returns the value of the
     last form in BODY.  If, however, the execution of BODY is cut
     short by the timeout, then `with-timeout' executes all the
     TIMEOUT-FORMS and returns the value of the last of them.

     This macro works by setting a timer to run after SECONDS seconds.
     If BODY finishes before that time, it cancels the timer.  If the
     timer actually runs, it terminates execution of BODY, then
     executes TIMEOUT-FORMS.

     Since timers can run within a Lisp program only when the program
     calls a primitive that can wait, `with-timeout' cannot stop
     executing BODY while it is in the midst of a computation--only
     when it calls one of those primitives.  So use `with-timeout' only
     with a BODY that waits for input, not one that does a long
     computation.

   The function `y-or-n-p-with-timeout' provides a simple way to use a
timer to avoid waiting too long for an answer.  *Note Yes-or-No
Queries::.

 -- Function: cancel-timer timer
     This cancels the requested action for TIMER, which should be a
     timer--usually, one previously returned by `run-at-time' or
     `run-with-idle-timer'.  This cancels the effect of that call to
     one of these functions; the arrival of the specified time will not
     cause anything special to happen.


File: elisp,  Node: Idle Timers,  Next: Terminal Input,  Prev: Timers,  Up: System Interface

39.11 Idle Timers
=================

Here is how to set up a timer that runs when Emacs is idle for a
certain length of time.  Aside from how to set them up, idle timers
work just like ordinary timers.

 -- Command: run-with-idle-timer secs repeat function &rest args
     Set up a timer which runs when Emacs has been idle for SECS
     seconds.  The value of SECS may be an integer or a floating point
     number; a value of the type returned by `current-idle-time' is
     also allowed.

     If REPEAT is `nil', the timer runs just once, the first time Emacs
     remains idle for a long enough time.  More often REPEAT is
     non-`nil', which means to run the timer _each time_ Emacs remains
     idle for SECS seconds.

     The function `run-with-idle-timer' returns a timer value which you
     can use in calling `cancel-timer' (*note Timers::).

   Emacs becomes "idle" when it starts waiting for user input, and it
remains idle until the user provides some input.  If a timer is set for
five seconds of idleness, it runs approximately five seconds after Emacs
first becomes idle.  Even if REPEAT is non-`nil', this timer will not
run again as long as Emacs remains idle, because the duration of
idleness will continue to increase and will not go down to five seconds
again.

   Emacs can do various things while idle: garbage collect, autosave or
handle data from a subprocess.  But these interludes during idleness do
not interfere with idle timers, because they do not reset the clock of
idleness to zero.  An idle timer set for 600 seconds will run when ten
minutes have elapsed since the last user command was finished, even if
subprocess output has been accepted thousands of times within those ten
minutes, and even if there have been garbage collections and autosaves.

   When the user supplies input, Emacs becomes non-idle while executing
the input.  Then it becomes idle again, and all the idle timers that are
set up to repeat will subsequently run another time, one by one.

 -- Function: current-idle-time
     If Emacs is idle, this function returns the length of time Emacs
     has been idle, as a list of three integers: `(HIGH LOW MICROSEC)'.
     The integers HIGH and LOW combine to give the number of seconds of
     idleness, which is HIGH * 2**16 + LOW.

     The third element, MICROSEC, gives the microseconds since the
     start of the current second (or 0 for systems that return time with
     the resolution of only one second).

     When Emacs is not idle, `current-idle-time' returns `nil'.  This
     is a convenient way to test whether Emacs is idle.

     The main use of this function is when an idle timer function wants
     to "take a break" for a while.  It can set up another idle timer to
     call the same function again, after a few seconds more idleness.
     Here's an example:

          (defvar resume-timer nil
            "Timer that `timer-function' used to reschedule itself, or nil.")

          (defun timer-function ()
            ;; If the user types a command while `resume-timer'
            ;; is active, the next time this function is called from
            ;; its main idle timer, deactivate `resume-timer'.
            (when resume-timer
              (cancel-timer resume-timer))
            ...DO THE WORK FOR A WHILE...
            (when TAKING-A-BREAK
              (setq resume-timer
                    (run-with-idle-timer
                      ;; Compute an idle time BREAK-LENGTH
                      ;; more than the current value.
                      (time-add (current-idle-time)
                                (seconds-to-time BREAK-LENGTH))
                      nil
                      'timer-function))))

   Some idle timer functions in user Lisp packages have a loop that
does a certain amount of processing each time around, and exits when
`(input-pending-p)' is non-`nil'.  That approach seems very natural but
has two problems:

   * It blocks out all process output (since Emacs accepts process
     output only while waiting).

   * It blocks out any idle timers that ought to run during that time.

To avoid these problems, don't use that technique.  Instead, write such
idle timers to reschedule themselves after a brief pause, using the
method in the `timer-function' example above.


File: elisp,  Node: Terminal Input,  Next: Terminal Output,  Prev: Idle Timers,  Up: System Interface

39.12 Terminal Input
====================

This section describes functions and variables for recording or
manipulating terminal input.  See *note Display::, for related
functions.

* Menu:

* Input Modes::         Options for how input is processed.
* Recording Input::     Saving histories of recent or all input events.


File: elisp,  Node: Input Modes,  Next: Recording Input,  Up: Terminal Input

39.12.1 Input Modes
-------------------

 -- Function: set-input-mode interrupt flow meta &optional quit-char
     This function sets the mode for reading keyboard input.  If
     INTERRUPT is non-null, then Emacs uses input interrupts.  If it is
     `nil', then it uses CBREAK mode.  The default setting is
     system-dependent.  Some systems always use CBREAK mode regardless
     of what is specified.

     When Emacs communicates directly with X, it ignores this argument
     and uses interrupts if that is the way it knows how to communicate.

     If FLOW is non-`nil', then Emacs uses XON/XOFF (`C-q', `C-s') flow
     control for output to the terminal.  This has no effect except in
     CBREAK mode.

     The argument META controls support for input character codes above
     127.  If META is `t', Emacs converts characters with the 8th bit
     set into Meta characters.  If META is `nil', Emacs disregards the
     8th bit; this is necessary when the terminal uses it as a parity
     bit.  If META is neither `t' nor `nil', Emacs uses all 8 bits of
     input unchanged.  This is good for terminals that use 8-bit
     character sets.

     If QUIT-CHAR is non-`nil', it specifies the character to use for
     quitting.  Normally this character is `C-g'.  *Note Quitting::.

   The `current-input-mode' function returns the input mode settings
Emacs is currently using.

 -- Function: current-input-mode
     This function returns the current mode for reading keyboard input.
     It returns a list, corresponding to the arguments of
     `set-input-mode', of the form `(INTERRUPT FLOW META QUIT)' in
     which:
    INTERRUPT
          is non-`nil' when Emacs is using interrupt-driven input.  If
          `nil', Emacs is using CBREAK mode.

    FLOW
          is non-`nil' if Emacs uses XON/XOFF (`C-q', `C-s') flow
          control for output to the terminal.  This value is meaningful
          only when INTERRUPT is `nil'.

    META
          is `t' if Emacs treats the eighth bit of input characters as
          the meta bit; `nil' means Emacs clears the eighth bit of every
          input character; any other value means Emacs uses all eight
          bits as the basic character code.

    QUIT
          is the character Emacs currently uses for quitting, usually
          `C-g'.


File: elisp,  Node: Recording Input,  Prev: Input Modes,  Up: Terminal Input

39.12.2 Recording Input
-----------------------

 -- Function: recent-keys
     This function returns a vector containing the last 300 input
     events from the keyboard or mouse.  All input events are included,
     whether or not they were used as parts of key sequences.  Thus,
     you always get the last 100 input events, not counting events
     generated by keyboard macros.  (These are excluded because they
     are less interesting for debugging; it should be enough to see the
     events that invoked the macros.)

     A call to `clear-this-command-keys' (*note Command Loop Info::)
     causes this function to return an empty vector immediately
     afterward.

 -- Command: open-dribble-file filename
     This function opens a "dribble file" named FILENAME.  When a
     dribble file is open, each input event from the keyboard or mouse
     (but not those from keyboard macros) is written in that file.  A
     non-character event is expressed using its printed representation
     surrounded by `<...>'.

     You close the dribble file by calling this function with an
     argument of `nil'.

     This function is normally used to record the input necessary to
     trigger an Emacs bug, for the sake of a bug report.

          (open-dribble-file "~/dribble")
               => nil

   See also the `open-termscript' function (*note Terminal Output::).


File: elisp,  Node: Terminal Output,  Next: Sound Output,  Prev: Terminal Input,  Up: System Interface

39.13 Terminal Output
=====================

The terminal output functions send output to a text terminal, or keep
track of output sent to the terminal.  The variable `baud-rate' tells
you what Emacs thinks is the output speed of the terminal.

 -- User Option: baud-rate
     This variable's value is the output speed of the terminal, as far
     as Emacs knows.  Setting this variable does not change the speed
     of actual data transmission, but the value is used for
     calculations such as padding.

     It also affects decisions about whether to scroll part of the
     screen or repaint on text terminals.  *Note Forcing Redisplay::,
     for the corresponding functionality on graphical terminals.

     The value is measured in baud.

   If you are running across a network, and different parts of the
network work at different baud rates, the value returned by Emacs may be
different from the value used by your local terminal.  Some network
protocols communicate the local terminal speed to the remote machine, so
that Emacs and other programs can get the proper value, but others do
not.  If Emacs has the wrong value, it makes decisions that are less
than optimal.  To fix the problem, set `baud-rate'.

 -- Function: send-string-to-terminal string &optional terminal
     This function sends STRING to TERMINAL without alteration.
     Control characters in STRING have terminal-dependent effects.
     This function operates only on text terminals.  TERMINAL may be a
     terminal object, a frame, or `nil' for the selected frame's
     terminal.  In batch mode, STRING is sent to `stdout' when TERMINAL
     is `nil'.

     One use of this function is to define function keys on terminals
     that have downloadable function key definitions.  For example,
     this is how (on certain terminals) to define function key 4 to
     move forward four characters (by transmitting the characters `C-u
     C-f' to the computer):

          (send-string-to-terminal "\eF4\^U\^F")
               => nil

 -- Command: open-termscript filename
     This function is used to open a "termscript file" that will record
     all the characters sent by Emacs to the terminal.  It returns
     `nil'.  Termscript files are useful for investigating problems
     where Emacs garbles the screen, problems that are due to incorrect
     Termcap entries or to undesirable settings of terminal options more
     often than to actual Emacs bugs.  Once you are certain which
     characters were actually output, you can determine reliably
     whether they correspond to the Termcap specifications in use.

     You close the termscript file by calling this function with an
     argument of `nil'.

     See also `open-dribble-file' in *note Recording Input::.

          (open-termscript "../junk/termscript")
               => nil


File: elisp,  Node: Sound Output,  Next: X11 Keysyms,  Prev: Terminal Output,  Up: System Interface

39.14 Sound Output
==================

To play sound using Emacs, use the function `play-sound'.  Only certain
systems are supported; if you call `play-sound' on a system which
cannot really do the job, it gives an error.  Emacs version 20 and
earlier did not support sound at all.

   The sound must be stored as a file in RIFF-WAVE format (`.wav') or
Sun Audio format (`.au').

 -- Function: play-sound sound
     This function plays a specified sound.  The argument, SOUND, has
     the form `(sound PROPERTIES...)', where the PROPERTIES consist of
     alternating keywords (particular symbols recognized specially) and
     values corresponding to them.

     Here is a table of the keywords that are currently meaningful in
     SOUND, and their meanings:

    `:file FILE'
          This specifies the file containing the sound to play.  If the
          file name is not absolute, it is expanded against the
          directory `data-directory'.

    `:data DATA'
          This specifies the sound to play without need to refer to a
          file.  The value, DATA, should be a string containing the
          same bytes as a sound file.  We recommend using a unibyte
          string.

    `:volume VOLUME'
          This specifies how loud to play the sound.  It should be a
          number in the range of 0 to 1.  The default is to use
          whatever volume has been specified before.

    `:device DEVICE'
          This specifies the system device on which to play the sound,
          as a string.  The default device is system-dependent.

     Before actually playing the sound, `play-sound' calls the
     functions in the list `play-sound-functions'.  Each function is
     called with one argument, SOUND.

 -- Function: play-sound-file file &optional volume device
     This function is an alternative interface to playing a sound FILE
     specifying an optional VOLUME and DEVICE.

 -- Variable: play-sound-functions
     A list of functions to be called before playing a sound.  Each
     function is called with one argument, a property list that
     describes the sound.


File: elisp,  Node: X11 Keysyms,  Next: Batch Mode,  Prev: Sound Output,  Up: System Interface

39.15 Operating on X11 Keysyms
==============================

To define system-specific X11 keysyms, set the variable
`system-key-alist'.

 -- Variable: system-key-alist
     This variable's value should be an alist with one element for each
     system-specific keysym.  Each element has the form `(CODE .
     SYMBOL)', where CODE is the numeric keysym code (not including the
     "vendor specific" bit, -2**28), and SYMBOL is the name for the
     function key.

     For example `(168 . mute-acute)' defines a system-specific key
     (used by HP X servers) whose numeric code is -2**28 + 168.

     It is not crucial to exclude from the alist the keysyms of other X
     servers; those do no harm, as long as they don't conflict with the
     ones used by the X server actually in use.

     The variable is always local to the current terminal, and cannot be
     buffer-local.  *Note Multiple Terminals::.

   You can specify which keysyms Emacs should use for the Meta, Alt,
Hyper, and Super modifiers by setting these variables:

 -- Variable: x-alt-keysym
 -- Variable: x-meta-keysym
 -- Variable: x-hyper-keysym
 -- Variable: x-super-keysym
     The name of the keysym that should stand for the Alt modifier
     (respectively, for Meta, Hyper, and Super).  For example, here is
     how to swap the Meta and Alt modifiers within Emacs:
          (setq x-alt-keysym 'meta)
          (setq x-meta-keysym 'alt)


File: elisp,  Node: Batch Mode,  Next: Session Management,  Prev: X11 Keysyms,  Up: System Interface

39.16 Batch Mode
================

The command-line option `-batch' causes Emacs to run noninteractively.
In this mode, Emacs does not read commands from the terminal, it does
not alter the terminal modes, and it does not expect to be outputting
to an erasable screen.  The idea is that you specify Lisp programs to
run; when they are finished, Emacs should exit.  The way to specify the
programs to run is with `-l FILE', which loads the library named FILE,
or `-f FUNCTION', which calls FUNCTION with no arguments, or `--eval
FORM'.

   Any Lisp program output that would normally go to the echo area,
either using `message', or using `prin1', etc., with `t' as the stream,
goes instead to Emacs's standard error descriptor when in batch mode.
Similarly, input that would normally come from the minibuffer is read
from the standard input descriptor.  Thus, Emacs behaves much like a
noninteractive application program.  (The echo area output that Emacs
itself normally generates, such as command echoing, is suppressed
entirely.)

 -- Variable: noninteractive
     This variable is non-`nil' when Emacs is running in batch mode.


File: elisp,  Node: Session Management,  Prev: Batch Mode,  Up: System Interface

39.17 Session Management
========================

Emacs supports the X Session Management Protocol, which is used to
suspend and restart applications.  In the X Window System, a program
called the "session manager" is responsible for keeping track of the
applications that are running.  When the X server shuts down, the
session manager asks applications to save their state, and delays the
actual shutdown until they respond.  An application can also cancel the
shutdown.

   When the session manager restarts a suspended session, it directs
these applications to individually reload their saved state.  It does
this by specifying a special command-line argument that says what saved
session to restore.  For Emacs, this argument is `--smid SESSION'.

 -- Variable: emacs-save-session-functions
     Emacs supports saving state via a hook called
     `emacs-save-session-functions'.  Emacs runs this hook when the
     session manager tells it that the window system is shutting down.
     The functions are called with no arguments, and with the current
     buffer set to a temporary buffer.  Each function can use `insert'
     to add Lisp code to this buffer.  At the end, Emacs saves the
     buffer in a file, called the "session file".

     Subsequently, when the session manager restarts Emacs, it loads the
     session file automatically (*note Loading::).  This is performed
     by a function named `emacs-session-restore', which is called during
     startup.  *Note Startup Summary::.

     If a function in `emacs-save-session-functions' returns non-`nil',
     Emacs tells the session manager to cancel the shutdown.

   Here is an example that just inserts some text into `*scratch*' when
Emacs is restarted by the session manager.

     (add-hook 'emacs-save-session-functions 'save-yourself-test)

     (defun save-yourself-test ()
       (insert "(save-current-buffer
       (switch-to-buffer \"*scratch*\")
       (insert \"I am restored\"))")
       nil)


File: elisp,  Node: Antinews,  Next: GNU Free Documentation License,  Prev: System Interface,  Up: Top

Appendix A Emacs 22 Antinews
****************************

For those users who live backwards in time, here is information about
downgrading to Emacs version 22.3.  We hope you will enjoy the greater
simplicity that results from the absence of many Emacs 23.4 features.

A.1 Old Lisp Features in Emacs 22
=================================

   * The internal character representation used by Emacs is not longer
     based on Unicode.  In this representation, called `emacs-mule',
     each character belongs to one and only one script.  Emacs makes no
     attempt to distinguish between "similar" characters occurring in
     different scripts.

   * The `^' interactive spec code, the function
     `handle-shift-selection', and the variable
     `this-command-keys-shift-translated' have all been removed.
     Shift-translated keys are no longer treated specially, making
     Emacs' handling of keybindings much more consistent.

   * Temporarily-active regions are not created by giving the variable
     `transient-mark-mode' values of the form `(only . OLDVAR)'.  We
     instead use a more complicated scheme: setting
     `transient-mark-mode' to `only' enables Transient Mark mode for
     the following command only, during which the value of
     `transient-mark-mode' is set to `identity'; if it is still
     `identity' at the end of the command, Transient Mark mode is
     disabled.

   * Many minibuffer functions, such as `read-file-name' and
     `minibuffer-complete', have been rewritten in C for greater speed.
     The completion code has been considerably simplified; the
     completion style can no longer be changed via
     `completion-styles-alist', and `completing-read' no longer
     recognizes the special values `confirm-only' and
     `confirm-after-completion' for its REQUIRE-MATCH argument.

   * Emacs no longer supports explicitly-numbered groups in regular
     expressions.

   * The `permanent-local-hook' function property has no special
     meaning.

   * The `functionp' function now returns `t' for special forms.

   * The `interactive-form' symbol property has no special meaning.
     Once you supply a function with an interactive form, the only way
     to change it is to redefine the function.

   * The `ignore-errors' macro has been moved into the `cl' package.

   * Variables can now be both buffer-local and frame-local;
     buffer-local bindings take precedence over frame-local bindings.

   * Faces can no longer be remapped.

   * Lisp programs now specify fonts by their names, which are strings
     following the XLFD (X logical font descriptor) format.  Fonts are
     no longer represented using a special set of "font" data types.
     The various functions that act on these data types, such as
     `fontp', `font-spec', and `list-fonts', have all been deleted.

   * Emacs does not recognize the `FontBackend' X resource and the
     `font-backend' frame parameter.  On the X Window System, fonts are
     always drawn using the X core font driver.

   * Display terminals are no longer represented using a "terminal" data
     type; this is not necessary, because we have removed the ability to
     display on graphical and text-only terminals simultaneously.  For
     the same reason, the `window-system' variable is no longer
     frame-local, and the `window-system' function has been removed.

   * The functions `list-system-processes' and `process-attributes'
     have been removed.  To get information about system processes,
     call an external program, such as `ps'.

   * The function `locate-user-emacs-file' and the variable
     `user-emacs-directory' have been removed.  Instead, use hard-coded
     values pointing to `~/.emacs.d'.

   * `vertical-motion' can no longer be told to move to a specific
     column; it always puts point on the first column of a line.

   * Windows no longer have parameters.

   * The `display-buffer' function has been rewritten in C.  Its
     window-splitting heuristics are a little less sophisticated, and a
     little less documented.  Window-splitting is handled internally,
     instead of using `split-window-preferred-function' (which has been
     removed).  Windows are never split horizontally; the variable
     `split-width-threshold' has been removed.

   * The `mode-name' variable now accepts only string values, and
     cannot take the form of a mode-line construct.

   * The behavior of `map-char-table' has changed.  It calls the
     mapping function for every single character in the table, instead
     of using cons cells to represent contiguous character code ranges.

   * Several keymaps have been eliminated: `input-decode-map',
     `local-function-key-map', `search-map', `multi-query-replace-map',
     and `minibuffer-local-shell-command-map'.

   * Many functions have been removed, including: `buffer-swap-text',
     `emacs-init-time', `emacs-uptime', `use-region-p',
     `region-active-p', `start-file-process', `process-lines',
     `image-refresh', `match-substitute-replacement',
     `word-search-forward-lax', and `word-search-backward-lax'.

   * Many variables have been removed, including `read-circle',
     `after-init-time' and `before-init-time',
     `generate-autoload-cookie', `file-local-variables-alist',
     `replace-search-function' and `replace-re-search-function',
     `inhibit-changing-match-data', `wrap-prefix', and `line-prefix',


File: elisp,  Node: GNU Free Documentation License,  Next: GPL,  Prev: Antinews,  Up: Top

Appendix B GNU Free Documentation License
*****************************************

                     Version 1.3, 3 November 2008

     Copyright (C) 2000, 2001, 2002, 2007, 2008, 2009 Free Software Foundation, Inc.
     `http://fsf.org/'

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     functional and useful document "free" in the sense of freedom: to
     assure everyone the effective freedom to copy and redistribute it,
     with or without modifying it, either commercially or
     noncommercially.  Secondarily, this License preserves for the
     author and publisher a way to get credit for their work, while not
     being considered responsible for modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.
     We recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work, in any medium,
     that contains a notice placed by the copyright holder saying it
     can be distributed under the terms of this License.  Such a notice
     grants a world-wide, royalty-free license, unlimited in duration,
     to use that work under the conditions stated herein.  The
     "Document", below, refers to any such manual or work.  Any member
     of the public is a licensee, and is addressed as "you".  You
     accept the license if you copy, modify or distribute the work in a
     way requiring permission under copyright law.

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter section
     of the Document that deals exclusively with the relationship of the
     publishers or authors of the Document to the Document's overall
     subject (or to related matters) and contains nothing that could
     fall directly within that overall subject.  (Thus, if the Document
     is in part a textbook of mathematics, a Secondary Section may not
     explain any mathematics.)  The relationship could be a matter of
     historical connection with the subject or with related matters, or
     of legal, commercial, philosophical, ethical or political position
     regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License.  If a section does not fit the above definition of
     Secondary then it is not allowed to be designated as Invariant.
     The Document may contain zero Invariant Sections.  If the Document
     does not identify any Invariant Sections then there are none.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.  A
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
     be at most 25 words.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, that is suitable for revising the document
     straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters.  A copy made in an
     otherwise Transparent file format whose markup, or absence of
     markup, has been arranged to thwart or discourage subsequent
     modification by readers is not Transparent.  An image format is
     not Transparent if used for any substantial amount of text.  A
     copy that is not "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML, PostScript or PDF designed for
     human modification.  Examples of transparent image formats include
     PNG, XCF and JPG.  Opaque formats include proprietary formats that
     can be read and edited only by proprietary word processors, SGML or
     XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML, PostScript or PDF
     produced by some word processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

     The "publisher" means any person or entity that distributes copies
     of the Document to the public.

     A section "Entitled XYZ" means a named subunit of the Document
     whose title either is precisely XYZ or contains XYZ in parentheses
     following text that translates XYZ in another language.  (Here XYZ
     stands for a specific section name mentioned below, such as
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
     To "Preserve the Title" of such a section when you modify the
     Document means that it remains a section "Entitled XYZ" according
     to this definition.

     The Document may include Warranty Disclaimers next to the notice
     which states that this License applies to the Document.  These
     Warranty Disclaimers are considered to be included by reference in
     this License, but only as regards disclaiming warranties: any other
     implication that these Warranty Disclaimers may have is void and
     has no effect on the meaning of this License.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies (or copies in media that commonly
     have printed covers) of the Document, numbering more than 100, and
     the Document's license notice requires Cover Texts, you must
     enclose the copies in covers that carry, clearly and legibly, all
     these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the
     title equally prominent and visible.  You may add other material
     on the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a computer-network location from
     which the general network-using public has access to download
     using public-standard network protocols a complete Transparent
     copy of the Document, free of added material.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it.  In addition, you must do these
     things in the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of
          previous versions (which should, if there were any, be listed
          in the History section of the Document).  You may use the
          same title as a previous version if the original publisher of
          that version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has fewer than five), unless they release you
          from this requirement.

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section Entitled "History", Preserve its Title,
          and add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on
          the Title Page.  If there is no section Entitled "History" in
          the Document, create one stating the title, year, authors,
          and publisher of the Document as given on its Title Page,
          then add an item describing the Modified Version as stated in
          the previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in
          the "History" section.  You may omit a network location for a
          work that was published at least four years before the
          Document itself, or if the original publisher of the version
          it refers to gives permission.

       K. For any section Entitled "Acknowledgements" or "Dedications",
          Preserve the Title of the section, and preserve in the
          section all the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document,
          unaltered in their text and in their titles.  Section numbers
          or the equivalent are not considered part of the section
          titles.

       M. Delete any section Entitled "Endorsements".  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section to be Entitled
          "Endorsements" or to conflict in title with any Invariant
          Section.

       O. Preserve any Warranty Disclaimers.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant.  To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.

     You may add a section Entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version.  Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity.  If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice, and that you preserve all
     their Warranty Disclaimers.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections Entitled
     "History" in the various original documents, forming one section
     Entitled "History"; likewise combine any sections Entitled
     "Acknowledgements", and any sections Entitled "Dedications".  You
     must delete all sections Entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, is called an "aggregate" if the
     copyright resulting from the compilation is not used to limit the
     legal rights of the compilation's users beyond what the individual
     works permit.  When the Document is included in an aggregate, this
     License does not apply to the other works in the aggregate which
     are not themselves derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one half
     of the entire aggregate, the Document's Cover Texts may be placed
     on covers that bracket the Document within the aggregate, or the
     electronic equivalent of covers if the Document is in electronic
     form.  Otherwise they must appear on printed covers that bracket
     the whole aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License, and all the license notices in the
     Document, and any Warranty Disclaimers, provided that you also
     include the original English version of this License and the
     original versions of those notices and disclaimers.  In case of a
     disagreement between the translation and the original version of
     this License or a notice or disclaimer, the original version will
     prevail.

     If a section in the Document is Entitled "Acknowledgements",
     "Dedications", or "History", the requirement (section 4) to
     Preserve its Title (section 1) will typically require changing the
     actual title.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense, or distribute it is void,
     and will automatically terminate your rights under this License.

     However, if you cease all violation of this License, then your
     license from a particular copyright holder is reinstated (a)
     provisionally, unless and until the copyright holder explicitly
     and finally terminates your license, and (b) permanently, if the
     copyright holder fails to notify you of the violation by some
     reasonable means prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
     reinstated permanently if the copyright holder notifies you of the
     violation by some reasonable means, this is the first time you have
     received notice of violation of this License (for any work) from
     that copyright holder, and you cure the violation prior to 30 days
     after your receipt of the notice.

     Termination of your rights under this section does not terminate
     the licenses of parties who have received copies or rights from
     you under this License.  If your rights have been terminated and
     not permanently reinstated, receipt of a copy of some or all of
     the same material does not give you any rights to use it.

 10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     `http://www.gnu.org/copyleft/'.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If
     the Document does not specify a version number of this License,
     you may choose any version ever published (not as a draft) by the
     Free Software Foundation.  If the Document specifies that a proxy
     can decide which future versions of this License can be used, that
     proxy's public statement of acceptance of a version permanently
     authorizes you to choose that version for the Document.

 11. RELICENSING

     "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
     World Wide Web server that publishes copyrightable works and also
     provides prominent facilities for anybody to edit those works.  A
     public wiki that anybody can edit is an example of such a server.
     A "Massive Multiauthor Collaboration" (or "MMC") contained in the
     site means any set of copyrightable works thus published on the MMC
     site.

     "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
     license published by Creative Commons Corporation, a not-for-profit
     corporation with a principal place of business in San Francisco,
     California, as well as future copyleft versions of that license
     published by that same organization.

     "Incorporate" means to publish or republish a Document, in whole or
     in part, as part of another Document.

     An MMC is "eligible for relicensing" if it is licensed under this
     License, and if all works that were first published under this
     License somewhere other than this MMC, and subsequently
     incorporated in whole or in part into the MMC, (1) had no cover
     texts or invariant sections, and (2) were thus incorporated prior
     to November 1, 2008.

     The operator of an MMC Site may republish an MMC contained in the
     site under CC-BY-SA on the same site at any time before August 1,
     2009, provided the MMC is eligible for relicensing.


ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.3
       or any later version published by the Free Software Foundation;
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
       Texts.  A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

   If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts." line with this:

         with the Invariant Sections being LIST THEIR TITLES, with
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
         being LIST.

   If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.

