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

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      09/01/08 20:58:13

Modified files:
        doc/lispref    : display.texi 

Log message:
        (Faces): Put Font Selection node after Auto Faces.
        (Face Attributes): Don't link to Font Lookup.  Document 
font-family-list.
        (Fonts): New node.

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

Patches:
Index: display.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/lispref/display.texi,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -b -r1.31 -r1.32
--- display.texi        8 Jan 2009 11:46:04 -0000       1.31
+++ display.texi        8 Jan 2009 20:58:13 -0000       1.32
@@ -1787,9 +1787,10 @@
 * Attribute Functions::  Functions to examine and set face attributes.
 * Displaying Faces::     How Emacs combines the faces specified for a 
character.
 * Face Remapping::     Remapping faces to alternative definitions.
-* Font Selection::      Finding the best available font for a face.
 * 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
@@ -1961,14 +1962,16 @@
 
 @table @code
 @item :family
-Font family name (@pxref{Font Lookup}), or fontset name
-(@pxref{Fontsets}).  If you specify a font family name, the wild-card
-characters @samp{*} and @samp{?} are allowed.  @xref{Font Lookup}.
+Font family name or fontset name (a string).  If you specify a font
+family name, the wild-card characters @samp{*} and @samp{?} are
+allowed.  The function @code{font-family-list}, described below,
+returns a list of available family names.  @xref{Fontsets}, for
+information about fontsets.
 
 @item :foundry
-The @dfn{font foundry} in which the font family specified by the
address@hidden:family} attribute is located.  The wild-card characters
address@hidden and @samp{?} are allowed.  @xref{Font Lookup}.
+The name of the @dfn{font foundry} in which the font family specified
+by the @code{:family} attribute is located (a string).  The wild-card
+characters @samp{*} and @samp{?} are allowed.
 
 @item :width
 Relative proportionate character width, also known as the character
@@ -2082,19 +2085,20 @@
 used automatically to handle certain shades of gray.
 
 @item :font
-The font used to display the face.  Its value should be a font object
-(@pxref{Font Lookup}).
+The font used to display the face.  Its value should be a font object.
address@hidden Selection}, for information about font objects.
 
 When specifying this attribute using @code{set-face-attribute}
-(@pxref{Attribute Functions}), you may supply a font spec, a font
+(@pxref{Attribute Functions}), you may also supply a font spec, a font
 entity, or a string.  Emacs converts such values to an appropriate
-font object, and stores that font object internally.  If you specify a
-string, the contents of the string should be an XLFD font name
-(@pxref{Font X,, Font Specification Options, emacs, The GNU Emacs
-Manual}); if the XLFD contains wildcards, Emacs chooses the first font
-matching those wildcards.  Specifying this attribute also changes the
-values of the @code{:family}, @code{:foundry}, @code{:width},
address@hidden:height}, @code{:weight}, and @code{:slant} attributes.
+font object, and stores that font object as the actual attribute
+value.  If you specify a string, the contents of the string should be
+a font name (@pxref{Font X,, Font Specification Options, emacs, The
+GNU Emacs Manual}); if the font name is an XLFD containing wildcards,
+Emacs chooses the first font matching those wildcards.  Specifying
+this attribute also changes the values of the @code{:family},
address@hidden:foundry}, @code{:width}, @code{:height}, @code{:weight}, and
address@hidden:slant} attributes.
 
 @item :inherit
 The name of a face from which to inherit attributes, or a list of face
@@ -2114,6 +2118,12 @@
 setting the @code{:slant} attribute to @code{italic}, and setting it
 to @code{nil} is equivalent to setting @code{:slant} to @code{normal}.
 
address@hidden font-family-list &optional frame
+This function returns a list of available font family names.  The
+optional argument @var{frame} specifies the frame on which the text is
+to be displayed; if it is @code{nil}, the selected frame is used.
address@hidden defun
+
 @defvar x-bitmap-file-path
 This variable specifies a list of directories for searching
 for bitmap files, for the @code{:stipple} attribute.
@@ -2512,27 +2522,273 @@
 value, which inherits from @var{face}'s global definition.
 @end defun
 
address@hidden Face Functions
address@hidden Functions for Working with Faces
+
+  Here are additional functions for creating and working with faces.
+
address@hidden make-face name
+This function defines a new face named @var{name}, initially with all
+attributes @code{nil}.  It does nothing if there is already a face named
address@hidden
address@hidden defun
+
address@hidden face-list
+This function returns a list of all defined face names.
address@hidden defun
+
address@hidden copy-face old-face new-name &optional frame new-frame
+This function defines a face named @var{new-name} as a copy of the existing
+face named @var{old-face}.  It creates the face @var{new-name} if that
+doesn't already exist.
+
+If the optional argument @var{frame} is given, this function applies
+only to that frame.  Otherwise it applies to each frame individually,
+copying attributes from @var{old-face} in each frame to @var{new-face}
+in the same frame.
+
+If the optional argument @var{new-frame} is given, then @code{copy-face}
+copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
+in @var{new-frame}.
address@hidden defun
+
address@hidden face-id face
+This function returns the @dfn{face number} of face @var{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.
address@hidden defun
+
address@hidden face-documentation face
+This function returns the documentation string of face @var{face}, or
address@hidden if none was specified for it.
address@hidden defun
+
address@hidden face-equal face1 face2 &optional frame
+This returns @code{t} if the faces @var{face1} and @var{face2} have the
+same attributes for display.
address@hidden defun
+
address@hidden face-differs-from-default-p face &optional frame
+This returns address@hidden if the face @var{face} displays
+differently from the default face.
address@hidden defun
+
address@hidden face alias
+A @dfn{face alias} provides an equivalent name for a face.  You can
+define a face alias by giving the alias symbol the @code{face-alias}
+property, with a value of the target face name.  The following example
+makes @code{modeline} an alias for the @code{mode-line} face.
+
address@hidden
+(put 'modeline 'face-alias 'mode-line)
address@hidden example
+
address@hidden Auto Faces
address@hidden Automatic Face Assignment
address@hidden automatic face assignment
address@hidden faces, automatic choice
+
+  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.
+
address@hidden fontification-functions
+This variable holds a list of functions that are called by Emacs
+redisplay as needed to assign faces automatically to text in the buffer.
+
+The functions are called in the order listed, with one argument, a
+buffer position @var{pos}.  Each function should attempt to assign faces
+to the text in the current buffer starting at @var{pos}.
+
+Each function should record the faces they assign by setting the
address@hidden property.  It should also add a address@hidden
address@hidden property for all the text it has assigned faces to.
+That property tells redisplay that faces have been assigned to that text
+already.
+
+It is probably a good idea for each function to do nothing if the
+character after @var{pos} already has a address@hidden @code{fontified}
+property, but this is not required.  If one function overrides the
+assignments made by a previous one, the properties as they are
+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.
address@hidden defvar
+
address@hidden Fonts
address@hidden Fonts
+
+  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.
+
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
+
 @node Font Selection
 @subsection Font Selection
 
-  @dfn{Selecting a font} means mapping the specified face attributes for
-a character to a font that is available on a particular display.  The
-face attributes, as determined by face merging, specify most of the
-font choice, but not all.  Part of the choice depends on what character
-it is.
-
-  If the face specifies a fontset name, that fontset determines a
-pattern for fonts of the given charset.  If the face specifies a font
-family, a font pattern is constructed.
-
-  Emacs tries to find an available font for the given face attributes
-and 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.
+  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.
 
 @defvar face-font-selection-order
 This variable specifies the order of importance of the face attributes
@@ -2627,101 +2883,6 @@
 nominal heights and widths would suggest.
 @end defvar
 
address@hidden Face Functions
address@hidden Functions for Working with Faces
-
-  Here are additional functions for creating and working with faces.
-
address@hidden make-face name
-This function defines a new face named @var{name}, initially with all
-attributes @code{nil}.  It does nothing if there is already a face named
address@hidden
address@hidden defun
-
address@hidden face-list
-This function returns a list of all defined face names.
address@hidden defun
-
address@hidden copy-face old-face new-name &optional frame new-frame
-This function defines a face named @var{new-name} as a copy of the existing
-face named @var{old-face}.  It creates the face @var{new-name} if that
-doesn't already exist.
-
-If the optional argument @var{frame} is given, this function applies
-only to that frame.  Otherwise it applies to each frame individually,
-copying attributes from @var{old-face} in each frame to @var{new-face}
-in the same frame.
-
-If the optional argument @var{new-frame} is given, then @code{copy-face}
-copies the attributes of @var{old-face} in @var{frame} to @var{new-name}
-in @var{new-frame}.
address@hidden defun
-
address@hidden face-id face
-This function returns the @dfn{face number} of face @var{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.
address@hidden defun
-
address@hidden face-documentation face
-This function returns the documentation string of face @var{face}, or
address@hidden if none was specified for it.
address@hidden defun
-
address@hidden face-equal face1 face2 &optional frame
-This returns @code{t} if the faces @var{face1} and @var{face2} have the
-same attributes for display.
address@hidden defun
-
address@hidden face-differs-from-default-p face &optional frame
-This returns address@hidden if the face @var{face} displays
-differently from the default face.
address@hidden defun
-
address@hidden face alias
-A @dfn{face alias} provides an equivalent name for a face.  You can
-define a face alias by giving the alias symbol the @code{face-alias}
-property, with a value of the target face name.  The following example
-makes @code{modeline} an alias for the @code{mode-line} face.
-
address@hidden
-(put 'modeline 'face-alias 'mode-line)
address@hidden example
-
-
address@hidden Auto Faces
address@hidden Automatic Face Assignment
address@hidden automatic face assignment
address@hidden faces, automatic choice
-
-  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.
-
address@hidden fontification-functions
-This variable holds a list of functions that are called by Emacs
-redisplay as needed to assign faces automatically to text in the buffer.
-
-The functions are called in the order listed, with one argument, a
-buffer position @var{pos}.  Each function should attempt to assign faces
-to the text in the current buffer starting at @var{pos}.
-
-Each function should record the faces they assign by setting the
address@hidden property.  It should also add a address@hidden
address@hidden property for all the text it has assigned faces to.
-That property tells redisplay that faces have been assigned to that text
-already.
-
-It is probably a good idea for each function to do nothing if the
-character after @var{pos} already has a address@hidden @code{fontified}
-property, but this is not required.  If one function overrides the
-assignments made by a previous one, the properties as they are
-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.
address@hidden defvar
-
 @node Font Lookup
 @subsection Looking Up Fonts