diff options
| -rw-r--r-- | doc/fontconfig-user.sgml | 590 |
1 files changed, 315 insertions, 275 deletions
diff --git a/doc/fontconfig-user.sgml b/doc/fontconfig-user.sgml index 0f18fce..58fb07d 100644 --- a/doc/fontconfig-user.sgml +++ b/doc/fontconfig-user.sgml @@ -91,57 +91,58 @@ properties for font matching and font completion. Others are provided as a convenience for the applications' rendering mechanism. </para> <programlisting> - Property Type Description - -------------------------------------------------------------- - family String Font family names - familylang String Languages corresponding to each family - style String Font style. Overrides weight and slant - stylelang String Languages corresponding to each style - fullname String Font full names (often includes style) - fullnamelang String Languages corresponding to each fullname - slant Int Italic, oblique or roman - weight Int Light, medium, demibold, bold or black - size Double Point size - width Int Condensed, normal or expanded - aspect Double Stretches glyphs horizontally before hinting - pixelsize Double Pixel size - spacing Int Proportional, dual-width, monospace or charcell - foundry String Font foundry name - antialias Bool Whether glyphs can be antialiased - hinting Bool Whether the rasterizer should use hinting - hintstyle Int Automatic hinting style - verticallayout Bool Use vertical layout - autohint Bool Use autohinter instead of normal hinter - globaladvance Bool Use font global advance data (deprecated) - file String The filename holding the font - index Int The index of the font within the file - ftface FT_Face Use the specified FreeType face object - rasterizer String Which rasterizer is in use (deprecated) - outline Bool Whether the glyphs are outlines - scalable Bool Whether glyphs can be scaled - color Bool Whether any glyphs have color - scale Double Scale factor for point->pixel conversions (deprecated) - dpi Double Target dots per inch - rgba Int unknown, rgb, bgr, vrgb, vbgr, - none - subpixel geometry - lcdfilter Int Type of LCD filter - minspace Bool Eliminate leading from line spacing - charset CharSet Unicode chars encoded by the font - lang String List of RFC-3066-style languages this - font supports - fontversion Int Version number of the font - capability String List of layout capabilities in the font - fontformat String String name of the font format - embolden Bool Rasterizer should synthetically embolden the font - embeddedbitmap Bool Use the embedded bitmap instead of the outline - decorative Bool Whether the style is a decorative variant - fontfeatures String List of the feature tags in OpenType to be enabled - namelang String Language name to be used for the default value of - familylang, stylelang, and fullnamelang - prgname String String Name of the running program - postscriptname String Font family name in PostScript - fonthashint Bool Whether the font has hinting - order Int Order number of the font +Property Type Description +-------------------------------------------------------------- +family String Font family names +familylang String Languages corresponding to each family +style String Font style. Overrides weight and slant +stylelang String Languages corresponding to each style +fullname String Font full names (often includes style) +fullnamelang String Languages corresponding to each fullname +slant Int Italic, oblique or roman +weight Int Light, medium, demibold, bold or black +size Double Point size +width Int Condensed, normal or expanded +aspect Double Stretches glyphs horizontally before hinting +pixelsize Double Pixel size +spacing Int Proportional, dual-width, monospace or charcell +foundry String Font foundry name +antialias Bool Whether glyphs can be antialiased +hinting Bool Whether the rasterizer should use hinting +hintstyle Int Automatic hinting style +verticallayout Bool Use vertical layout +autohint Bool Use autohinter instead of normal hinter +globaladvance Bool Use font global advance data (deprecated) +file String The filename holding the font +index Int The index of the font within the file +ftface FT_Face Use the specified FreeType face object +rasterizer String Which rasterizer is in use (deprecated) +outline Bool Whether the glyphs are outlines +scalable Bool Whether glyphs can be scaled +color Bool Whether any glyphs have color +scale Double Scale factor for point->pixel conversions + (deprecated) +dpi Double Target dots per inch +rgba Int unknown, rgb, bgr, vrgb, vbgr, + none - subpixel geometry +lcdfilter Int Type of LCD filter +minspace Bool Eliminate leading from line spacing +charset CharSet Unicode chars encoded by the font +lang String List of RFC-3066-style languages this + font supports +fontversion Int Version number of the font +capability String List of layout capabilities in the font +fontformat String String name of the font format +embolden Bool Rasterizer should synthetically embolden the font +embeddedbitmap Bool Use the embedded bitmap instead of the outline +decorative Bool Whether the style is a decorative variant +fontfeatures String List of the feature tags in OpenType to be enabled +namelang String Language name to be used for the default value of + familylang, stylelang, and fullnamelang +prgname String String Name of the running program +postscriptname String Font family name in PostScript +fonthashint Bool Whether the font has hinting +order Int Order number of the font </programlisting> </refsect2> <refsect2> @@ -211,7 +212,7 @@ list of family names, second a list of point sizes and finally a list of additional properties: </para> <programlisting> - <families>-<point sizes>:<name1>=<values1>:<name2>=<values2>... +<families>-<point sizes>:<name1>=<values1>:<name2>=<values2>... </programlisting> <para> Values in a list are separated with commas. The name needn't include either @@ -220,13 +221,13 @@ symbolic constants that simultaneously indicate both a name and a value. Here are some examples: </para> <programlisting> - Name Meaning - ---------------------------------------------------------- - Times-12 12 point Times Roman - Times-12:bold 12 point Times Bold - Courier:italic Courier Italic in the default size - Monospace:matrix=1 .1 0 1 The users preferred monospace font - with artificial obliquing +Name Meaning +---------------------------------------------------------- +Times-12 12 point Times Roman +Times-12:bold 12 point Times Bold +Courier:italic Courier Italic in the default size +Monospace:matrix=1 .1 0 1 The users preferred monospace font + with artificial obliquing </programlisting> <para> The '\', '-', ':' and ',' characters in family names must be preceded by a @@ -246,21 +247,21 @@ interpreted as a number, and each bit within that value controls different debugging messages. </para> <programlisting> - Name Value Meaning - --------------------------------------------------------- - MATCH 1 Brief information about font matching - MATCHV 2 Extensive font matching information - EDIT 4 Monitor match/test/edit execution - FONTSET 8 Track loading of font information at startup - CACHE 16 Watch cache files being written - CACHEV 32 Extensive cache file writing information - PARSE 64 (no longer in use) - SCAN 128 Watch font files being scanned to build caches - SCANV 256 Verbose font file scanning information - MEMORY 512 Monitor fontconfig memory usage - CONFIG 1024 Monitor which config files are loaded - LANGSET 2048 Dump char sets used to construct lang values - MATCH2 4096 Display font-matching transformation in patterns +Name Value Meaning +--------------------------------------------------------- +MATCH 1 Brief information about font matching +MATCHV 2 Extensive font matching information +EDIT 4 Monitor match/test/edit execution +FONTSET 8 Track loading of font information at startup +CACHE 16 Watch cache files being written +CACHEV 32 Extensive cache file writing information +PARSE 64 (no longer in use) +SCAN 128 Watch font files being scanned to build caches +SCANV 256 Verbose font file scanning information +MEMORY 512 Monitor fontconfig memory usage +CONFIG 1024 Monitor which config files are loaded +LANGSET 2048 Dump char sets used to construct lang values +MATCH2 4096 Display font-matching transformation in patterns </programlisting> <para> Add the value of the desired debug levels together and assign that (in @@ -301,11 +302,11 @@ The fontconfig document type definition resides in the external entity directory (&confdir;). Each configuration file should contain the following structure: <programlisting> - <?xml version="1.0"?> - <!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd"> - <fontconfig> - ... - </fontconfig> +<?xml version="1.0"?> +<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd"> +<fontconfig> +... +</fontconfig> </programlisting> </para> <refsect2><title><literal><fontconfig></literal></title><para> @@ -449,16 +450,16 @@ the property are given the indicated binding ("strong", "weak" or "same") with "same" binding using the value from the matched pattern element. 'mode' is one of: <programlisting> - Mode With Match Without Match - --------------------------------------------------------------------- - "assign" Replace matching value Replace all values - "assign_replace" Replace all values Replace all values - "prepend" Insert before matching Insert at head of list - "prepend_first" Insert at head of list Insert at head of list - "append" Append after matching Append at end of list - "append_last" Append at end of list Append at end of list - "delete" Delete matching value Delete all values - "delete_all" Delete all values Delete all values +Mode With Match Without Match +--------------------------------------------------------------------- +"assign" Replace matching value Replace all values +"assign_replace" Replace all values Replace all values +"prepend" Insert before matching Insert at head of list +"prepend_first" Insert at head of list Insert at head of list +"append" Append after matching Append at end of list +"append_last" Append at end of list Append at end of list +"delete" Delete matching value Delete all values +"delete_all" Delete all values Delete all values </programlisting> </para></refsect2> <refsect2><title><literal><int></literal>, <literal><double></literal>, <literal><string></literal>, <literal><bool></literal></title><para> @@ -499,54 +500,57 @@ of 'font' in a match that has target="pattern". Holds the name of a constant; these are always integers and serve as symbolic names for common font values: <programlisting> - Constant Property Value - ------------------------------------- - thin weight 0 - extralight weight 40 - ultralight weight 40 - light weight 50 - demilight weight 55 - semilight weight 55 - book weight 75 - regular weight 80 - normal weight 80 - medium weight 100 - demibold weight 180 - semibold weight 180 - bold weight 200 - extrabold weight 205 - black weight 210 - heavy weight 210 - roman slant 0 - italic slant 100 - oblique slant 110 - ultracondensed width 50 - extracondensed width 63 - condensed width 75 - semicondensed width 87 - normal width 100 - semiexpanded width 113 - expanded width 125 - extraexpanded width 150 - ultraexpanded width 200 - proportional spacing 0 - dual spacing 90 - mono spacing 100 - charcell spacing 110 - unknown rgba 0 - rgb rgba 1 - bgr rgba 2 - vrgb rgba 3 - vbgr rgba 4 - none rgba 5 - lcdnone lcdfilter 0 - lcddefault lcdfilter 1 - lcdlight lcdfilter 2 - lcdlegacy lcdfilter 3 - hintnone hintstyle 0 - hintslight hintstyle 1 - hintmedium hintstyle 2 - hintfull hintstyle 3 +Constant Property Value +------------------------------------- +thin weight 0 +extralight weight 40 +ultralight weight 40 +light weight 50 +demilight weight 55 +semilight weight 55 +book weight 75 +regular weight 80 +normal weight 80 +medium weight 100 +demibold weight 180 +semibold weight 180 +bold weight 200 +extrabold weight 205 +ultrabold weight 205 +black weight 210 +heavy weight 210 +extrablack weight 215 +ultrablack weight 215 +roman slant 0 +italic slant 100 +oblique slant 110 +ultracondensed width 50 +extracondensed width 63 +condensed width 75 +semicondensed width 87 +normal width 100 +semiexpanded width 113 +expanded width 125 +extraexpanded width 150 +ultraexpanded width 200 +proportional spacing 0 +dual spacing 90 +mono spacing 100 +charcell spacing 110 +unknown rgba 0 +rgb rgba 1 +bgr rgba 2 +vrgb rgba 3 +vbgr rgba 4 +none rgba 5 +lcdnone lcdfilter 0 +lcddefault lcdfilter 1 +lcdlight lcdfilter 2 +lcdlegacy lcdfilter 3 +hintnone hintstyle 0 +hintslight hintstyle 1 +hintmedium hintstyle 2 +hintfull hintstyle 3 </programlisting> </para> </refsect2> @@ -596,103 +600,135 @@ This is an example of a system-wide configuration file <!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd"> <!-- &confdir;/fonts.conf file to configure system font access --> <fontconfig> -<!-- - Find fonts in these directories ---> -<dir>/usr/share/fonts</dir> -<dir>/usr/X11R6/lib/X11/fonts</dir> + <!-- + Find fonts in these directories + --> + <dir>/usr/share/fonts</dir> + <dir>/usr/X11R6/lib/X11/fonts</dir> -<!-- - Accept deprecated 'mono' alias, replacing it with 'monospace' ---> -<match target="pattern"> - <test qual="any" name="family"><string>mono</string></test> - <edit name="family" mode="assign"><string>monospace</string></edit> -</match> + <!-- + Accept deprecated 'mono' alias, replacing it with 'monospace' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>mono</string> + </test> + <edit name="family" mode="assign"> + <string>monospace</string> + </edit> + </match> -<!-- - Names not including any well known alias are given 'sans-serif' ---> -<match target="pattern"> - <test qual="all" name="family" compare="not_eq"><string>sans-serif</string></test> - <test qual="all" name="family" compare="not_eq"><string>serif</string></test> - <test qual="all" name="family" compare="not_eq"><string>monospace</string></test> - <edit name="family" mode="append_last"><string>sans-serif</string></edit> -</match> + <!-- + Names not including any well known alias are given 'sans-serif' + --> + <match target="pattern"> + <test qual="all" name="family" compare="not_eq"> + <string>sans-serif</string> + </test> + <test qual="all" name="family" compare="not_eq"> + <string>serif</string> + </test> + <test qual="all" name="family" compare="not_eq"> + <string>monospace</string> + </test> + <edit name="family" mode="append_last"> + <string>sans-serif</string> + </edit> + </match> -<!-- - Load per-user customization file, but don't complain - if it doesn't exist ---> -<include ignore_missing="yes" prefix="xdg">fontconfig/fonts.conf</include> + <!-- + Load per-user customization file, but don't complain + if it doesn't exist + --> + <include ignore_missing="yes" prefix="xdg"> + fontconfig/fonts.conf + </include> -<!-- - Load local customization files, but don't complain - if there aren't any ---> -<include ignore_missing="yes">conf.d</include> -<include ignore_missing="yes">local.conf</include> + <!-- + Load local customization files, but don't complain + if there aren't any + --> + <include ignore_missing="yes">conf.d</include> + <include ignore_missing="yes">local.conf</include> -<!-- - Alias well known font names to available TrueType fonts. - These substitute TrueType faces for similar Type1 - faces to improve screen appearance. ---> -<alias> - <family>Times</family> - <prefer><family>Times New Roman</family></prefer> - <default><family>serif</family></default> -</alias> -<alias> - <family>Helvetica</family> - <prefer><family>Arial</family></prefer> - <default><family>sans</family></default> -</alias> -<alias> - <family>Courier</family> - <prefer><family>Courier New</family></prefer> - <default><family>monospace</family></default> -</alias> + <!-- + Alias well known font names to available TrueType fonts. + These substitute TrueType faces for similar Type1 + faces to improve screen appearance. + --> + <alias> + <family>Times</family> + <prefer> + <family>Times New Roman</family> + </prefer> + <default> + <family>serif</family> + </default> + </alias> + <alias> + <family>Helvetica</family> + <prefer> + <family>Arial</family> + </prefer> + <default> + <family>sans</family> + </default> + </alias> + <alias> + <family>Courier</family> + <prefer> + <family>Courier New</family> + </prefer> + <default> + <family>monospace</family> + </default> + </alias> -<!-- - Provide required aliases for standard names - Do these after the users configuration file so that - any aliases there are used preferentially ---> -<alias> - <family>serif</family> - <prefer><family>Times New Roman</family></prefer> -</alias> -<alias> - <family>sans</family> - <prefer><family>Arial</family></prefer> -</alias> -<alias> - <family>monospace</family> - <prefer><family>Andale Mono</family></prefer> -</alias> + <!-- + Provide required aliases for standard names + Do these after the users configuration file so that + any aliases there are used preferentially + --> + <alias> + <family>serif</family> + <prefer> + <family>Times New Roman</family> + </prefer> + </alias> + <alias> + <family>sans</family> + <prefer> + <family>Arial</family> + </prefer> + </alias> + <alias> + <family>monospace</family> + <prefer> + <family>Andale Mono</family> + </prefer> + </alias> -<-- - The example of the requirements of OR operator; - If the 'family' contains 'Courier New' OR 'Courier' - add 'monospace' as the alternative ---> -<match target="pattern"> - <test name="family" compare="eq"> - <string>Courier New</string> - </test> - <edit name="family" mode="prepend"> - <string>monospace</string> - </edit> -</match> -<match target="pattern"> - <test name="family" compare="eq"> - <string>Courier</string> - </test> - <edit name="family" mode="prepend"> - <string>monospace</string> - </edit> -</match> + <-- + The example of the requirements of OR operator; + If the 'family' contains 'Courier New' OR 'Courier' + add 'monospace' as the alternative + --> + <match target="pattern"> + <test name="family" compare="eq"> + <string>Courier New</string> + </test> + <edit name="family" mode="prepend"> + <string>monospace</string> + </edit> + </match> + <match target="pattern"> + <test name="family" compare="eq"> + <string>Courier</string> + </test> + <edit name="family" mode="prepend"> + <string>monospace</string> + </edit> + </match> </fontconfig> </programlisting> @@ -705,57 +741,61 @@ $XDG_CONFIG_HOME/fontconfig/fonts.conf <programlisting> <?xml version="1.0"?> <!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd"> -<!-- $XDG_CONFIG_HOME/fontconfig/fonts.conf for per-user font configuration --> -<fontconfig> - <!-- - Private font directory + $XDG_CONFIG_HOME/fontconfig/fonts.conf for per-user font configuration --> -<dir prefix="xdg">fonts</dir> +<fontconfig> -<!-- - use rgb sub-pixel ordering to improve glyph appearance on - LCD screens. Changes affecting rendering, but not matching - should always use target="font". ---> -<match target="font"> - <edit name="rgba" mode="assign"><const>rgb</const></edit> -</match> -<!-- - use WenQuanYi Zen Hei font when serif is requested for Chinese ---> -<match> - <!-- - If you don't want to use WenQuanYi Zen Hei font for zh-tw etc, - you can use zh-cn instead of zh. - Please note, even if you set zh-cn, it still matches zh. - if you don't like it, you can use compare="eq" - instead of compare="contains". - --> - <test name="lang" compare="contains"> - <string>zh</string> - </test> - <test name="family"> - <string>serif</string> - </test> - <edit name="family" mode="prepend"> - <string>WenQuanYi Zen Hei</string> - </edit> -</match> -<!-- - use VL Gothic font when sans-serif is requested for Japanese ---> -<match> - <test name="lang" compare="contains"> - <string>ja</string> - </test> - <test name="family"> - <string>sans-serif</string> - </test> - <edit name="family" mode="prepend"> - <string>VL Gothic</string> - </edit> -</match> + <!-- + Private font directory + --> + <dir prefix="xdg">fonts</dir> + + <!-- + use rgb sub-pixel ordering to improve glyph appearance on + LCD screens. Changes affecting rendering, but not matching + should always use target="font". + --> + <match target="font"> + <edit name="rgba" mode="assign"> + <const>rgb</const> + </edit> + </match> + <!-- + use WenQuanYi Zen Hei font when serif is requested for Chinese + --> + <match> + <!-- + If you don't want to use WenQuanYi Zen Hei font for zh-tw etc, + you can use zh-cn instead of zh. + Please note, even if you set zh-cn, it still matches zh. + if you don't like it, you can use compare="eq" + instead of compare="contains". + --> + <test name="lang" compare="contains"> + <string>zh</string> + </test> + <test name="family"> + <string>serif</string> + </test> + <edit name="family" mode="prepend"> + <string>WenQuanYi Zen Hei</string> + </edit> + </match> + <!-- + use VL Gothic font when sans-serif is requested for Japanese + --> + <match> + <test name="lang" compare="contains"> + <string>ja</string> + </test> + <test name="family"> + <string>sans-serif</string> + </test> + <edit name="family" mode="prepend"> + <string>VL Gothic</string> + </edit> + </match> </fontconfig> </programlisting> </refsect2> |