[Emacs-diffs] emacs/doc/emacs cmdargs.texi

[Chong Yidong]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Chong Yidong <cyd>      08/12/09 14:32:16

Modified files:
        doc/emacs      : cmdargs.texi 

Log message:
        (Font X): Distinguish between client-side and server-side fonts.  List
        valid Fontconfig properties.  Add reference to Fontconfig manual.
        List valid GTK font properties.  Explain use of fc-list.

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/emacs/doc/emacs/cmdargs.texi?cvsroot=emacs&r1=1.11&r2=1.12

Patches:
Index: cmdargs.texi
===================================================================
RCS file: /sources/emacs/emacs/doc/emacs/cmdargs.texi,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -b -r1.11 -r1.12
--- cmdargs.texi        9 Dec 2008 14:27:56 -0000       1.11
+++ cmdargs.texi        9 Dec 2008 14:32:16 -0000       1.12
@@ -818,11 +818,19 @@
 font in your X resources file, you should not quote it.
 
 @cindex fontconfig
+  Emacs recognizes two types of fonts: @dfn{client-side} fonts, which
+are provided by the Xft and Fontconfig libraries, and
address@hidden fonts, which are provided by the X server itself.
+Most client-side fonts support advanced font features such as
+antialiasing and subpixel hinting, while server-side fonts do not.
+
   There are four different ways to express a ``font name''.  The first
-is to use the @dfn{Fontconfig format}, which has the following form:
+format consists of @dfn{Fontconfig patterns}.  Fontconfig patterns
+match only client-side fonts provided by Xft and Fontconfig, and have
+the following form:
 
 @smallexample
address@hidden@var{fontsize}][:@var{property1}][:@var{property2}]...
address@hidden@var{fontsize}][:@address@hidden:@address@hidden
 @end smallexample
 
 @noindent
@@ -830,10 +838,38 @@
 Here, @var{fontname} is the ``family name'' of the font, such as
 @samp{Monospace} or @samp{DejaVu Serif}; @var{fontsize} is the ``point
 size'' of the font (one ``printer's point'' is about 1/72 of an inch);
-and the @var{property} entries specify font settings such as
address@hidden, @samp{italic}, @samp{weight=bold}, @samp{slant=oblique},
-and so forth.  Here are some examples of specifying fonts using the
-Fontconfig format:
+and the @address@hidden@var{values}} entries specify settings such
+as the slant and weight of the font.  Each @var{values} may be a
+single value, or a list of values separated by commas.  In addition,
+some property values are valid with only one kind of property name, in
+which case the @address@hidden part may be omitted.
+
+Here is a list of common font properties:
+
address@hidden @samp
address@hidden slant
+One of @samp{italic}, @samp{oblique} or @samp{roman}.
+
address@hidden weight
+One of @samp{light}, @samp{medium}, @samp{demibold}, @samp{bold} or
address@hidden
+
address@hidden style
+Some fonts define special styles which are a combination of slant and
+weight.  For instance, the font @samp{Dejavu Sans} defines the style
address@hidden  This property, if specified, overrides the slant and
+weight properties.
+
address@hidden width
+One of @samp{condensed}, @samp{normal}, or @samp{expanded}.
+
address@hidden spacing
+One of @samp{monospace}, @samp{proportional}, @samp{dual-width}, or
address@hidden
address@hidden table
+
address@hidden
+Here are some examples of Fontconfig patterns:
 
 @smallexample
 Monospace
@@ -843,16 +879,40 @@
 Monospace-12:weight=bold:slant=italic
 @end smallexample
 
-  The second way to specify a font is to use the @dfn{GTK format}.
-This has the syntax
+See the Fontconfig manual for a more detailed description of
+Fontconfig patterns.  This manual is located in the file
address@hidden, which is distributed with Fontconfig.  It
+is also available online at
address@hidden://fontconfig.org/fontconfig-user.html}.  In particular, the
+manual describes additional font properties that influence how the
+font is hinted, antialiased, or scaled.
+
+  The second way to specify a font is to use a @dfn{GTK font
+description}.  Like Fontconfig patterns, GTK font descriptions match
+only client-side fonts provided by Xft and Fontconfig.  They have the
+syntax
 
 @smallexample
 @var{fontname} address@hidden address@hidden
 @end smallexample
 
address@hidden
 where @var{fontname} is the family name, @var{properties} is a list of
-font properties separated by spaces, and @var{fontsize} is the point
-size.  For example:
+property values separated by spaces, and @var{fontsize} is the point
+size.  The properties that you may specify are as follows:
+
address@hidden @samp
address@hidden style
+One of @samp{roman}, @samp{italic} or @samp{oblique}.  If omitted, the
address@hidden style is used.
address@hidden weight
+One of @samp{medium}, @samp{ultra-light}, @samp{light},
address@hidden, or @samp{bold}.  If omitted, @samp{medium} weight is
+used.
address@hidden table
+
address@hidden
+Here are some examples of GTK font descriptions:
 
 @smallexample
 Monospace 12
@@ -944,14 +1004,24 @@
 @end smallexample
 
 @noindent
-is equivalent to @samp{6x13}.
+is equivalent to @samp{6x13}.  This is the fourth and final method of
+specifying a font.
 
 @cindex listing system fonts
   You will probably want to use a fixed-width default font---that is,
-a font in which all characters have the same width.  Any font with
address@hidden or @samp{c} in the @var{spacing} field of the XLFD is a
-fixed-width font.  Here's how to use the @command{xlsfonts} program to
-list all the fixed-width fonts available on your system:
+a font in which all characters have the same width.  Here's how to use
+the @command{fc-list} command to list all fixed-width Xft and
+Fontconfig fonts available on your system:
+
address@hidden
+fc-list :spacing=mono
+fc-list :spacing=charcell
address@hidden example
+
+  For server-side X fonts, any font with @samp{m} or @samp{c} in the
address@hidden field of the XLFD is a fixed-width font.  Here's how to
+use the @command{xlsfonts} program to list all the fixed-width fonts
+available on your system:
 
 @example
 xlsfonts -fn '*x*' | egrep "^[0-9]+x[0-9]+"