This is ../../info/elisp, produced by makeinfo version 4.11 from elisp.texi. This is edition 3.0 of the GNU Emacs Lisp Reference Manual, corresponding to Emacs version 23.2. Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 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 Emacs START-INFO-DIR-ENTRY * Elisp: (elisp). The Emacs Lisp Reference Manual. END-INFO-DIR-ENTRY  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; magnifying text; moving it up or down on the page; adjusting the width of spaces within text. * Display Margins:: Displaying text or images to the side of the main text.  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 `left-fringe', `right-fringe', `left-margin', `right-margin', `scroll-bar', and `text' elements 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::). `(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 that uses a common idiom to provide compatibility with versions of Emacs that lack the variable `image-load-path': (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) (when (boundp 'image-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 ). 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 and 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 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. 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 and to 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 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. -- 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.2 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.  File: elisp, Node: GPL, Next: Tips, Prev: GNU Free Documentation License, Up: Top Appendix C GNU General Public License ************************************* Version 3, 29 June 2007 Copyright (C) 2007 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. Preamble ======== The GNU General Public License is a free, copyleft license for software and other kinds of works. The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things. To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others. For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it. For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions. Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users. Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free. The precise terms and conditions for copying, distribution and modification follow. TERMS AND CONDITIONS ==================== 0. Definitions. "This License" refers to version 3 of the GNU General Public License. "Copyright" also means copyright-like laws that apply to other kinds of works, such as semiconductor masks. "The Program" refers to any copyrightable work licensed under this License. Each licensee is addressed as "you". "Licensees" and "recipients" may be individuals or organizations. To "modify" a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a "modified version" of the earlier work or a work "based on" the earlier work. A "covered work" means either the unmodified Program or a work based on the Program. To "propagate" a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well. To "convey" a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying. An interactive user interface displays "Appropriate Legal Notices" to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion. 1. Source Code. The "source code" for a work means the preferred form of the work for making modifications to it. "Object code" means any non-source form of a work. A "Standard Interface" means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language. The "System Libraries" of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A "Major Component", in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it. The "Corresponding Source" for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work. The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source. The Corresponding Source for a work in source code form is that same work. 2. Basic Permissions. All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law. You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you. Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary. 3. Protecting Users' Legal Rights From Anti-Circumvention Law. No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures. When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures. 4. Conveying Verbatim Copies. You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program. You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee. 5. Conveying Modified Source Versions. You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions: a. The work must carry prominent notices stating that you modified it, and giving a relevant date. b. The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to "keep intact all notices". c. You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it. d. If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so. A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an "aggregate" if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate. 6. Conveying Non-Source Forms. You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways: a. Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange. b. Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge. c. Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b. d. Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements. e. Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d. A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work. A "User Product" is either (1) a "consumer product", which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, "normally used" refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product. "Installation Information" for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made. If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM). The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network. Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying. 7. Additional Terms. "Additional permissions" are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions. When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission. Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms: a. Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or b. Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or c. Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or d. Limiting the use for publicity purposes of names of licensors or authors of the material; or e. Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or f. Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors. All other non-permissive additional terms are considered "further restrictions" within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying. If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms. Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way. 8. Termination. You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11). 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, you do not qualify to receive new licenses for the same material under section 10. 9. Acceptance Not Required for Having Copies. You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so. 10. Automatic Licensing of Downstream Recipients. Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License. An "entity transaction" is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts. You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it. 11. Patents. A "contributor" is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's "contributor version". A contributor's "essential patent claims" are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, "control" includes the right to grant patent sublicenses in a manner consistent with the requirements of this License. Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version. In the following three paragraphs, a "patent license" is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To "grant" such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party. If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. "Knowingly relying" means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid. If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it. A patent license is "discriminatory" if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007. Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law. 12. No Surrender of Others' Freedom. If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program. 13. Use with the GNU Affero General Public License. Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such. 14. Revised Versions of this License. The Free Software Foundation may publish revised and/or new versions of the GNU General Public 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. Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License "or any later version" applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation. If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program. Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version. 15. Disclaimer of Warranty. THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 16. Limitation of Liability. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. 17. Interpretation of Sections 15 and 16. If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee. END OF TERMS AND CONDITIONS =========================== How to Apply These Terms to Your New Programs ============================================= If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. Copyright (C) YEAR NAME OF AUTHOR This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see `http://www.gnu.org/licenses/'. Also add information on how to contact you by electronic and paper mail. If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode: PROGRAM Copyright (C) YEAR NAME OF AUTHOR This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an "about box". You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see `http://www.gnu.org/licenses/'. The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read `http://www.gnu.org/philosophy/why-not-lgpl.html'.  File: elisp, Node: Tips, Next: GNU Emacs Internals, Prev: GPL, Up: Top Appendix D Tips and Conventions ******************************* This chapter describes no additional features of Emacs Lisp. Instead it gives advice on making effective use of the features described in the previous chapters, and describes conventions Emacs Lisp programmers should follow. You can automatically check some of the conventions described below by running the command `M-x checkdoc RET' when visiting a Lisp file. It cannot check all of the conventions, and not all the warnings it gives necessarily correspond to problems, but it is worth examining them all. * Menu: * Coding Conventions:: Conventions for clean and robust programs. * Key Binding Conventions:: Which keys should be bound by which programs. * Programming Tips:: Making Emacs code fit smoothly in Emacs. * Compilation Tips:: Making compiled code run fast. * Warning Tips:: Turning off compiler warnings. * Documentation Tips:: Writing readable documentation strings. * Comment Tips:: Conventions for writing comments. * Library Headers:: Standard headers for library packages.