[Emacs-diffs] emacs/doc/lispref display.texi

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      09/01/09 14:18:59

Modified files:
        doc/lispref    : display.texi 

Log message:
        (Font Lookup): Remove obsolete function
        x-font-family-list.  x-list-fonts accepts Fontconfig/GTK syntax.
        (Low-Level Font): Rename from Fonts, move to end of Faces section.
        (Font Selection): Reorder order of variable descriptions.  Minor
        clarifications.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/lispref/display.texi?cvsroot=emacs&r1=1.32&r2=1.33

Patches:
Index: display.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/display.texi,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -b -r1.32 -r1.33
--- display.texi        8 Jan 2009 20:58:13 -0000       1.32
+++ display.texi        9 Jan 2009 14:18:59 -0000       1.33
@@ -1789,12 +1789,12 @@
 * Face Remapping::     Remapping faces to alternative definitions.
 * Face Functions::      How to define and examine faces.
 * Auto Faces::          Hook for automatic face assignment.
-* Fonts::               Lisp representation for character display fonts.
 * Font Selection::      Finding the best available font for a face.
 * Font Lookup::         Looking up the names of available fonts
                           and information about them.
 * Fontsets::            A fontset is a collection of fonts
                           that handle a range of character sets.
+* Low-Level Font::      Lisp representation for character display fonts.
 @end menu
 
 @node Defining Faces
@@ -2616,189 +2616,48 @@
 usually assign faces to around 400 to 600 characters at each call.
 @end defvar
 
address@hidden Fonts
address@hidden Fonts
address@hidden Font Selection
address@hidden Font Selection
 
   Before Emacs can draw a character on a particular display, it must
 select a @dfn{font} for that address@hidden this context, the
 term @dfn{font} has nothing to do with Font Lock (@pxref{Font Lock
-Mode}).}.  Normally, Emacs automatically chooses a font for displaying
-a character based on the faces assigned to that
-character---specifically, the face attributes @code{:family},
address@hidden:weight}, @code{:slant}, and @code{:width}.  The choice of font
-also depends on the character to be displayed; some fonts can only
-display a limited set of characters.  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: @dfn{font objects}, @dfn{font specs}, and @dfn{font
-entities}.
-
address@hidden fontp object &optional type
-Return @code{t} if @var{object} is a font object, font spec, or font
-entity.  Otherwise, return @code{nil}.
-
-The optional argument @var{type}, if address@hidden, determines the
-exact type of Lisp object to check for.  In that case, @var{type}
-should be one of @code{font-object}, @code{font-spec}, or
address@hidden
address@hidden defun
-
-  A font object is a Lisp object that represents a font that Emacs has
address@hidden  Font objects cannot be modified in Lisp, but they can
-be inspected.  For instance, if you call @code{set-face-attribute} and
-pass a font spec, font entity, or font name string as the value of the
address@hidden: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 @code{:font} attribute for that face.
-
address@hidden font-at position &optional window string
-Return the font object that is being used to display the character at
-position @var{position} in the window @var{window}.  If @var{window}
-is @code{nil}, it defaults to the selected window.  If @var{string} is
address@hidden, @var{position} specifies a position in the current buffer;
-otherwise, @var{string} should be a string, and @var{position}
-specifies a position in that string.
address@hidden defun
-
-  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.
+Mode}).}.  Normally, Emacs automatically chooses a font based on the
+faces assigned to that character---specifically, the face attributes
address@hidden:family}, @code{:weight}, @code{:slant}, and @code{:width}
+(@pxref{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 @dfn{closest matching font}.  The variables in
+this section control how Emacs makes this selection.
 
address@hidden font-spec &rest arguments
-Return a new font spec using the specifications in @var{arguments},
-which should come in @address@hidden pairs.  The possible
-specifications are as follows:
-
address@hidden @code
address@hidden :name
-The font name string, in either XLFD, Fontconfig, or GTK format.
address@hidden X,, Font Specification Options, emacs, The GNU Emacs
-Manual}.
-
address@hidden :family
address@hidden :foundry
address@hidden :weight
address@hidden :slant
address@hidden :width
-These have the same meanings as the face attributes of the same name.
address@hidden Attributes}.
-
address@hidden :size
-The font size---either a non-negative integer that specifies the pixel
-size, or a floating point number that specifies the point size.
-
address@hidden :adstyle
-Additional typographic style information for the font, such as
address@hidden  The value should be a string or a symbol.
-
address@hidden :registry
-The charset registry and encoding of the font, such as
address@hidden  The value should be a string or a symbol.
-
address@hidden :script
-The script that the font must support (a symbol).
address@hidden table
address@hidden defun
-
address@hidden font-put font-spec property value
-Set the font property @var{property} in the font-spec @var{font-spec}
-to @var{value}.
address@hidden defun
-
-  A font entity is a reference to a font that need not have been
-opened.  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, it can be modified in
-Lisp, and creating a font entity does not load the contents of that
-font into computer memory.
-
address@hidden find-font font-spec &optional frame
-Return a font entity that best matches the font spec @var{font-spec}
-on frame @var{frame}.  If @var{frame} is @code{nil}, it defaults to
-the selected frame.
address@hidden defun
-
address@hidden list-fonts font-spec &optional frame num prefer
-This function returns a list of all font entities that match the font
-spec @var{font-spec}.
-
-The optional argument @var{frame}, if address@hidden, specifies the
-frame on which the fonts are to be displayed.  The optional argument
address@hidden, if address@hidden, should be an integer; in that case, the
-function returns a list of at most @var{num} font entities.  The
-optional argument @var{prefer}, if address@hidden, 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.
address@hidden defun
-
-  The following functions can be used to obtain information about font
-objects, font entities, and font specs alike:
-
address@hidden font-get font property
-This function returns the value of the font property @var{property}
-for @var{font}, which should be either a font object, font spec, or
-font entity.
-
-If @var{font} is a font spec and the font spec does not specify
address@hidden, the return value is @code{nil}.  If @var{font} is a
-font object or font entity, the value for the @var{:script} property
-may be a list of scripts supported by the font.
address@hidden defun
-
address@hidden font-face-attributes font &optional frame
-This function returns a list of face attributes corresponding to
address@hidden , which should be either a font name, a font object, a font
-spec, or a font entity.  The optional argument @var{frame} specifies
-the frame on which the font is to be displayed.  If it is @code{nil},
-the selected frame is used.  The return value has the form
-
address@hidden
-(:family @var{family} :height @var{height} :weight @var{weight}
-   :slant @var{slant} :width @var{width})
address@hidden smallexample
-
-where the values of @var{family}, @var{height}, @var{weight},
address@hidden, and @var{width} are face attribute values.  Some of these
-key-attribute pairs may be omitted from the list if they are not
-specified by @var{font}.
address@hidden defun
-
address@hidden font-xlfd-name font &optional fold-wildcards
-This function returns the XLFD (X Logical Font Descriptor), a string,
-matching @var{font}.  @xref{Font X,, Font Specification Options,
-emacs, The GNU Emacs Manual}, for information about XLFDs.  @var{font}
-should be a font spec, font entity, or font object.  If the name is
-too long for an XLFD (which can contain at most 255 characters), the
-function returns @code{nil}.
-
-If the optional argument @var{fold-wildcards} is address@hidden,
-consecutive wildcards in the XLFD are folded into one.
address@hidden defun
address@hidden 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:
 
address@hidden Font Selection
address@hidden Font Selection
address@hidden
+(@var{family} @address@hidden)
address@hidden example
 
-  Emacs tries to find an available font to display each character
-based on the face attributes and the character's registry and
-encoding.  If there is a font that matches exactly, it is used, of
-course.  The hard case is when no available font exactly fits the
-specification.  Then Emacs looks for one that is ``close''---one
-attribute at a time.  You can specify the order to consider the
-attributes.  In the case where a specified font family is not
-available, you can specify a set of mappings for alternatives to try.
+If @var{family} is specified but not available, Emacs will try the other
+families given in @var{alternate-families}, one by one, until it finds a
+family that does exist.
address@hidden defvar
 
 @defvar face-font-selection-order
-This variable specifies the order of importance of the face attributes
address@hidden:width}, @code{:height}, @code{:weight}, and @code{:slant}.  The
-value should be a list containing those four symbols, in order of
-decreasing importance.
+If there is no font that exactly matches all desired face attributes
+(@code{:width}, @code{:height}, @code{:weight}, and @code{: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 @code{(:width :height :weight
+:slant)}.
 
 Font selection first finds the best available matches for the first
-attribute listed; then, among the fonts which are best in that way, it
-searches for the best matches in the second attribute, and so on.
+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 @code{:weight} and @code{:width} have symbolic values in
 a range centered around @code{normal}.  Matches that are more extreme
@@ -2806,11 +2665,6 @@
 less extreme (closer to @code{normal}); this is designed to ensure that
 non-normal faces contrast with normal ones, whenever possible.
 
-The default is @code{(:width :height :weight :slant)}, which means first
-find the fonts closest to the specified @code{:width}, then---among the
-fonts with that width---find a best match for the specified font height,
-and so on.
-
 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
 @code{italic} face will use a non-italic font that is similar to the
@@ -2819,20 +2673,6 @@
 quite right.
 @end defvar
 
address@hidden face-font-family-alternatives
-This variable lets you specify alternative font families to try, if a
-given family is specified and doesn't exist.  Each element should have
-this form:
-
address@hidden
-(@var{family} @address@hidden)
address@hidden example
-
-If @var{family} is specified but not available, Emacs will try the other
-families given in @var{alternate-families}, one by one, until it finds a
-family that does exist.
address@hidden defvar
-
 @defvar 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
@@ -2848,8 +2688,7 @@
 @end defvar
 
   Emacs can make use of scalable fonts, but by default it does not use
-them, since the use of too many or too big scalable fonts can crash
-XFree86 servers.
+them.
 
 @defvar scalable-fonts-allowed
 This variable controls which scalable fonts to use.  A value of
@@ -2886,25 +2725,25 @@
 @node Font Lookup
 @subsection Looking Up Fonts
 
address@hidden x-list-fonts pattern &optional face frame maximum
address@hidden x-list-fonts name &optional reference-face frame maximum
 This function returns a list of available font names that match
address@hidden  If the optional arguments @var{face} and @var{frame} are
-specified, then the list is limited to fonts that are the same size as
address@hidden currently is on @var{frame}.
-
-The argument @var{pattern} should be a string, perhaps with wildcard
-characters: the @samp{*} character matches any substring, and the
address@hidden character matches any single character.  Pattern matching
-of font names ignores case.
-
-If you specify @var{face} and @var{frame}, @var{face} should be a face name
-(a symbol) and @var{frame} should be a frame.
address@hidden  @var{name} should be a string containing a font name in
+either the Fontconfig, GTK, or XLFD format (@pxref{Font X,, Font
+Specification Options, emacs, The GNU Emacs Manual}).  Within an XLFD
+string, wildcard characters may be used: the @samp{*} character
+matches any substring, and the @samp{?} character matches any single
+character.  Case is ignored when matching font names.
+
+If the optional arguments @var{reference-face} and @var{frame} are
+specified, the returned list includes only fonts that are the same
+size as @var{reference-face} (a face name) currently is on the frame
address@hidden
 
 The optional argument @var{maximum} sets a limit on how many fonts to
-return.  If this is address@hidden, then the return value is truncated
-after the first @var{maximum} matching fonts.  Specifying a small value
-for @var{maximum} can make this function much faster, in cases where
-many fonts match the pattern.
+return.  If it is address@hidden, then the return value is truncated
+after the first @var{maximum} matching fonts.  Specifying a small
+value for @var{maximum} can make this function much faster, in cases
+where many fonts match the pattern.
 @end defun
 
 @defun x-family-fonts &optional family frame
@@ -2918,7 +2757,7 @@
 omitted or @code{nil}, it applies to the selected frame's display
 (@pxref{Input Focus}).
 
-The list contains a vector of the following form for each font:
+Each element in the list is a vector of the following form:
 
 @example
 address@hidden @var{width} @var{point-size} @var{weight} @var{slant}
@@ -2933,24 +2772,6 @@
 @var{full} is the full name of the font, and
 @var{registry-and-encoding} is a string giving the registry and
 encoding of the font.
-
-The result list is sorted according to the current face font sort order.
address@hidden defun
-
address@hidden x-font-family-list &optional frame
-This function returns a list of the font families available for
address@hidden's display.  If @var{frame} is omitted or @code{nil}, it
-describes the selected frame's display (@pxref{Input Focus}).
-
-The value is a list of elements of this form:
-
address@hidden
-(@var{family} . @var{fixed-p})
address@hidden example
-
address@hidden
-Here @var{family} is a font family, and @var{fixed-p} is
address@hidden if fonts of that family are fixed-pitch.
 @end defun
 
 @defvar font-list-limit
@@ -3095,6 +2916,156 @@
 does that, this function's value may not be accurate.
 @end defun
 
address@hidden Low-Level Font
address@hidden 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
+qobject types: @dfn{font objects}, @dfn{font specs}, and @dfn{font
+entities}.
+
address@hidden fontp object &optional type
+Return @code{t} if @var{object} is a font object, font spec, or font
+entity.  Otherwise, return @code{nil}.
+
+The optional argument @var{type}, if address@hidden, determines the
+exact type of Lisp object to check for.  In that case, @var{type}
+should be one of @code{font-object}, @code{font-spec}, or
address@hidden
address@hidden defun
+
+  A font object is a Lisp object that represents a font that Emacs has
address@hidden  Font objects cannot be modified in Lisp, but they can
+be inspected.  If you call @code{set-face-attribute} and pass a font
+spec, font entity, or font name string as the value of the
address@hidden: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 @code{:font} attribute for that face.
+
address@hidden font-at position &optional window string
+Return the font object that is being used to display the character at
+position @var{position} in the window @var{window}.  If @var{window}
+is @code{nil}, it defaults to the selected window.  If @var{string} is
address@hidden, @var{position} specifies a position in the current buffer;
+otherwise, @var{string} should be a string, and @var{position}
+specifies a position in that string.
address@hidden defun
+
+  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.
+
address@hidden font-spec &rest arguments
+Return a new font spec using the specifications in @var{arguments},
+which should come in @address@hidden pairs.  The possible
+specifications are as follows:
+
address@hidden @code
address@hidden :name
+The font name (a string), in either XLFD, Fontconfig, or GTK format.
address@hidden X,, Font Specification Options, emacs, The GNU Emacs
+Manual}.
+
address@hidden :family
address@hidden :foundry
address@hidden :weight
address@hidden :slant
address@hidden :width
+These have the same meanings as the face attributes of the same name.
address@hidden Attributes}.
+
address@hidden :size
+The font size---either a non-negative integer that specifies the pixel
+size, or a floating point number that specifies the point size.
+
address@hidden :adstyle
+Additional typographic style information for the font, such as
address@hidden  The value should be a string or a symbol.
+
address@hidden :registry
+The charset registry and encoding of the font, such as
address@hidden  The value should be a string or a symbol.
+
address@hidden :script
+The script that the font must support (a symbol).
address@hidden table
address@hidden defun
+
address@hidden font-put font-spec property value
+Set the font property @var{property} in the font-spec @var{font-spec}
+to @var{value}.
address@hidden defun
+
+  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.
+
address@hidden find-font font-spec &optional frame
+This function returns a font entity that best matches the font spec
address@hidden on frame @var{frame}.  If @var{frame} is @code{nil},
+it defaults to the selected frame.
address@hidden defun
+
address@hidden list-fonts font-spec &optional frame num prefer
+This function returns a list of all font entities that match the font
+spec @var{font-spec}.
+
+The optional argument @var{frame}, if address@hidden, specifies the
+frame on which the fonts are to be displayed.  The optional argument
address@hidden, if address@hidden, should be an integer that specifies the
+maximum length of the returned list.  The optional argument
address@hidden, if address@hidden, 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.
address@hidden defun
+
+  The following functions can be used to obtain information about a
+font.  For these functions, the @var{font} argument can be a font
+object, a font entity, or a font spec.
+
address@hidden font-get font property
+This function returns the value of the font property @var{property}
+for @var{font}.
+
+If @var{font} is a font spec and the font spec does not specify
address@hidden, the return value is @code{nil}.  If @var{font} is a
+font object or font entity, the value for the @var{:script} property
+may be a list of scripts supported by the font.
address@hidden defun
+
address@hidden font-face-attributes font &optional frame
+This function returns a list of face attributes corresponding to
address@hidden  The optional argument @var{frame} specifies the frame on
+which the font is to be displayed.  If it is @code{nil}, the selected
+frame is used.  The return value has the form
+
address@hidden
+(:family @var{family} :height @var{height} :weight @var{weight}
+   :slant @var{slant} :width @var{width})
address@hidden smallexample
+
+where the values of @var{family}, @var{height}, @var{weight},
address@hidden, and @var{width} are face attribute values.  Some of these
+key-attribute pairs may be omitted from the list if they are not
+specified by @var{font}.
address@hidden defun
+
address@hidden font-xlfd-name font &optional fold-wildcards
+This function returns the XLFD (X Logical Font Descriptor), a string,
+matching @var{font}.  @xref{Font X,, Font Specification Options,
+emacs, The GNU Emacs Manual}, for information about XLFDs.  If the
+name is too long for an XLFD (which can contain at most 255
+characters), the function returns @code{nil}.
+
+If the optional argument @var{fold-wildcards} is address@hidden,
+consecutive wildcards in the XLFD are folded into one.
address@hidden defun
+
 @node Fringes
 @section Fringes
 @cindex fringes