Generate and install PDF versions of the manuals

Fix formatting
Add missing exported functions, fix data types
Add missing pattern elements.
Add missing pattern elements. Document conf.d usage, clarify available
    orthography list. Fix some config file attributes. Complete list of
    constants.
Mark FC_SOURCE deprecated.
Don't set FC_SOURCE any longer.

ChangeLog

@@ -1,3 +1,28 @@
+2005-03-01  Keith Packard  <keithp@keithp.com>
+
+	* doc/Makefile.am:
+	Generate and install PDF versions of the manuals
+
+	* doc/fcpattern.fncs:
+	Fix formatting
+	
+	* doc/fcstring.fncs:
+	Add missing exported functions, fix data types
+	
+	* doc/fontconfig-devel.sgml:
+	Add missing pattern elements.
+	
+	* doc/fontconfig-user.sgml:
+	Add missing pattern elements.  Document conf.d usage,
+	clarify available orthography list.  Fix some config file
+	attributes.  Complete list of constants.
+	
+	* fontconfig/fontconfig.h:
+	Mark FC_SOURCE deprecated.
+	
+	* src/fcfreetype.c: (FcFreeTypeQuery):
+	Don't set FC_SOURCE any longer.
+
 2005-02-28  Keith Packard  <keithp@keithp.com>
 
 	* Makefile.am:

doc/Makefile.am

@@ -30,8 +30,10 @@ DOC_MODULE = fontconfig
 DOC2HTML = docbook2html
 DOC2TXT = docbook2txt
 DOC2MAN = docbook2man
+DOC2PDF = docbook2pdf
 
 TXT = fontconfig-user.txt fontconfig-devel.txt
+PDF = fontconfig-user.pdf fontconfig-devel.pdf
 HTML_FILES = fontconfig-user.html
 HTML_DIR = fontconfig-devel
 SGML = fontconfig-user.sgml fontconfig-devel.sgml
@@ -80,7 +82,7 @@ edit_sgml_SOURCES=edit-sgml.c
 
 docdir=@DOCDIR@
 
-DOC_FILES=$(TXT) $(HTML_FILES)
+DOC_FILES=$(TXT) $(PDF) $(HTML_FILES)
 LOCAL_DOCS=$(man_MANS) $(DOC_FILES) $(HTML_DIR)/*
 
 EXTRA_DIST=$(LOCAL_DOCS) $(SGML) $(DOC_FUNCS_FNCS) $(FNCS_TMPL) confdir.sgml.in
@@ -97,6 +99,10 @@ if USEDOCBOOK
 	$(RM) $@
 	$(DOC2TXT) $<
 
+.sgml.pdf:
+	$(RM) $@
+	$(DOC2PDF) $<
+
 $(man_MANS): func.refs
 
 func.refs: local-fontconfig-devel.sgml $(DOC_FUNCS_SGML) version.sgml confdir.sgml
@@ -133,6 +139,11 @@ fontconfig-devel.txt: local-fontconfig-devel.sgml version.sgml confdir.sgml
 	$(DOC2TXT) local-fontconfig-devel.sgml
 	mv local-fontconfig-devel.txt $@
 
+fontconfig-devel.pdf: local-fontconfig-devel.sgml version.sgml confdir.sgml
+	$(RM) $@
+	$(DOC2PDF) local-fontconfig-devel.sgml
+	mv local-fontconfig-devel.pdf $@
+
 fontconfig-user.html: local-fontconfig-user.sgml version.sgml confdir.sgml
 	$(RM) $@ local-$@ $@.tmp
 	$(DOC2HTML) -u local-fontconfig-user.sgml > $@.tmp
@@ -145,6 +156,11 @@ fontconfig-user.txt: local-fontconfig-user.sgml version.sgml confdir.sgml
 	$(DOC2TXT) local-fontconfig-user.sgml
 	mv local-fontconfig-user.txt $@
 
+fontconfig-user.pdf: local-fontconfig-user.sgml version.sgml confdir.sgml
+	$(RM) $@
+	$(DOC2PDF) local-fontconfig-user.sgml
+	mv local-fontconfig-user.pdf $@
+
 STRIPNL=awk '{ if (NR > 1) printf ("\n"); printf ("%s", $$0); }'
 confdir.sgml: ${DOC_SRC}/confdir.sgml.in
 	sed "s,@CONFDIR\@,${CONFDIR}," < ${DOC_SRC}/confdir.sgml.in | $(STRIPNL) > confdir.sgml

doc/fcpattern.fncs

@@ -150,7 +150,8 @@ any existing list of values.
 @TYPE4@		FcValue *			@ARG4@		v 
 @PURPOSE@	Return a value from a pattern
 @DESC@
-Returns in `v<parameter> the `id</parameter>th value associated with the property `object'.
+Returns in <parameter>v</parameter> the <parameter>id</parameter>'th value
+associated with the property <parameter>object</parameter>.
 The value returned is not a copy, but rather refers to the data stored
 within the pattern directly.  Applications must not free this value.
 @@

doc/fcstring.fncs

@@ -107,6 +107,15 @@ buffer.  Yes, this is <function>strdup</function>, but that function isn't
 available on every platform.
 @@
 
+@RET@		FcChar8 *
+@FUNC@		FcStrDowncase
+@TYPE1@		const FcChar8 *			@ARG1@		s
+@PURPOSE@	create a lower case translation of a string
+@DESC@
+Allocates memory, copies <parameter>s</parameter>, converting upper case
+letters to lower case and returns the allocated buffer.
+@@
+
 @RET@		FcChar8 *
 @FUNC@		FcStrCopyFilename
 @TYPE1@		const FcChar8 *			@ARG1@		s
@@ -119,8 +128,8 @@ Returns NULL if '~' is present in <parameter>s</parameter> and HOME is unset.
 
 @RET@		int
 @FUNC@		FcStrCmpIgnoreCase
-@TYPE1@		const char *			@ARG1@		s1
+@TYPE1@		const FcChar8 *			@ARG1@		s1
-@TYPE2@		const char *			@ARG2@		s2
+@TYPE2@		const FcChar8 *			@ARG2@		s2
 @PURPOSE@	compare UTF-8 strings ignoring ASCII case
 @DESC@
 Returns the usual &lt;0, 0, &gt;0 result of comparing
@@ -129,6 +138,33 @@ case-insensitive in the ASCII range and will operate properly with UTF8
 encoded strings, although it does not check for well formed strings.
 @@
 
+@RET@		FcChar8 *
+@FUNC@		FcStrStr
+@TYPE1@		const char *			@ARG1@		s1
+@TYPE2@		const char *			@ARG2@		s2
+@PURPOSE@	locate UTF-8 substring
+@DESC@
+Returns the location of <parameter>s2</parameter> in
+<parameter>s1</parameter>.  Returns NULL if <parameter>s2</parameter>
+is not present in <parameter>s1</parameter>. This test will operate properly
+with UTF8 encoded strings, although it does not check for well formed
+strings.
+@@
+
+@RET@		FcChar8 *
+@FUNC@		FcStrStrIgnoreCase
+@TYPE1@		const char *			@ARG1@		s1
+@TYPE2@		const char *			@ARG2@		s2
+@PURPOSE@	locate UTF-8 substring ignoring ASCII case
+@DESC@
+Returns the location of <parameter>s2</parameter> in 
+<parameter>s1</parameter>, ignoring ASCII case.  Returns NULL if
+<parameter>s2</parameter> is not present in <parameter>s1</parameter>.
+This test is case-insensitive in the ASCII range and will operate properly
+with UTF8 encoded strings, although it does not check for well formed
+strings.
+@@
+
 @RET@		FcChar8 *
 @FUNC@		FcStrDirname
 @TYPE1@		const FcChar8 *			@ARG1@		file

doc/fontconfig-devel.sgml

@@ -145,6 +145,7 @@ convenience for the applications rendering mechanism.
     weight         FC_WEIGHT            Int     Light, medium, demibold,
                                                 bold or black
     size           FC_SIZE              Double  Point size
+    width          FC_WIDTH             Int     Condensed, normal or expanded
     aspect         FC_ASPECT            Double  Stretches glyphs horizontally
                                                 before hinting
     pixelsize      FC_PIXEL_SIZE        Double  Pixel size
@@ -155,6 +156,7 @@ convenience for the applications rendering mechanism.
                                                 antialiased
     hinting        FC_HINTING           Bool    Whether the rasterizer should
                                                 use hinting
+    hintstyle      FC_HINT_STYLE        Int     Automatic hinting style
     verticallayout FC_VERTICAL_LAYOUT   Bool    Use vertical layout
     autohint       FC_AUTOHINT          Bool    Use autohinter instead of
                                                 normal hinter
@@ -178,6 +180,11 @@ convenience for the applications rendering mechanism.
                                                 the font
     lang           FC_LANG              String  List of RFC-3066-style
                                                 languages this font supports
+    fontversion    FC_FONTVERSION       Int     Version number of the font
+    capability     FC_CAPABILITY        String  List of layout capabilities in
+                                                the font
+    embolden       FC_EMBOLDEN          Bool    Rasterizer should
+                                                synthetically embolden the font
     </programlisting>
   </sect2>
 </sect1>
@@ -365,6 +372,7 @@ Used as a return type for functions manipulating FcPattern objects.
         FcResultTypeMismatch    Object exists, but the type doesn't match
         FcResultNoId            Object exists, but has fewer values
                                 than specified
+        FcResultOutOfMemory     Malloc failed
     </programlisting>
     </para>
   </sect2>

doc/fontconfig-user.sgml

@@ -38,6 +38,7 @@
 <synopsis>
    &confdir;/fonts.conf
    &confdir;/fonts.dtd
+   &confdir;/conf.d
    ~/.fonts.conf
 </synopsis>
 </refsynopsisdiv>
@@ -100,12 +101,14 @@ convenience for the applications rendering mechanism.
   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
@@ -123,6 +126,9 @@ convenience for the applications rendering mechanism.
   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
+  embolden        Bool    Rasterizer should synthetically embolden the font
     </programlisting>
   </refsect2>
   <refsect2>
@@ -216,14 +222,19 @@ Here are some examples:
 Each font in the database contains a list of languages it supports.  This is
 computed by comparing the Unicode coverage of the font with the orthography
 of each language.  Languages are tagged using an RFC-3066 compatible naming
-and occur in two parts -- the ISO639 language tag followed a hyphen and then
+and occur in two parts -- the ISO 639 language tag followed a hyphen and then
 by the ISO 3166 country code.  The hyphen and country code may be elided.
   </para><para>
 Fontconfig has orthographies for several languages built into the library.
 No provision has been made for adding new ones aside from rebuilding the
 library.  It currently supports 122 of the 139 languages named in ISO 639-1,
 141 of the languages with two-letter codes from ISO 639-2 and another 30
-languages with only three-letter codes.
+languages with only three-letter codes.  Languages with both two and three
+letter codes are provided with only the two letter code.
+  </para><para>
+For languages used in multiple territories with radically different
+character sets, fontconfig includes per-territory orthographies.  This
+includes Azerbaijani, Kurdish, Pashto, Tigrinya and Chinese.
   </para>
 </refsect1>
 <refsect1><title>Configuration File Format</title>
@@ -336,14 +347,17 @@ tests are subjected to all the edits.  If 'target' is set to "font" instead
 of the default "pattern", then this element applies to the font name
 resulting from a match rather than a font pattern to be matched.
   </para></refsect2>
-  <refsect2><title><sgmltag>test qual="any" name="property" compare="eq"</></title><para>
+  <refsect2><title><sgmltag>test qual="any" name="property" target="default" compare="eq"</></title><para>
-This element contains a single value which is compared with the pattern
+This element contains a single value which is compared with the target
-property "property" (substitute any of the property names seen 
+('pattern', 'font' or 'default') property "property" (substitute any of the property names seen 
 above). 'compare' can be one of "eq", "not_eq", "less", "less_eq", "more", or
 "more_eq".  'qual' may either be the default, "any", in which case the match
 succeeds if any value associated with the property matches the test value, or
 "all", in which case all of the values associated with the property must
-match the test value.
+match the test value.  When used in a &lt;match target="font"&gt; element,
+the target= attribute in the &lt;test&gt; element selects between matching
+the original pattern or the font.  "default" selects whichever target the
+outer &lt;match&gt; element has selected.
   </para></refsect2>
   <refsect2><title><sgmltag>edit name="property" mode="assign" binding="weak"</></title><para>
 This element contains a list of expression elements (any of the value or
@@ -351,7 +365,9 @@ operator elements).  The expression elements are evaluated at run-time and
 modify the property "property".  The modification depends on whether
 "property" was matched by one of the associated <sgmltag>test</> elements, if so, the
 modification may affect the first matched value.  Any values inserted into
-the property are given the indicated binding. 'mode' is one of:
+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
   ---------------------------------------------------------------------
@@ -385,14 +401,32 @@ symbolic names for common font values:
     <programlisting>
   Constant        Property        Value
   -------------------------------------
-  light           weight          0
+  thin            weight          0
+  extralight      weight          40
+  ultralight      weight          40
+  light           weight          50
+  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
@@ -403,6 +437,10 @@ symbolic names for common font values:
   vrgb            rgba            3
   vbgr            rgba            4
   none            rgba            5
+  hintnone        hintstyle       0
+  hintslight      hintstyle       1
+  hintmedium      hintstyle       2
+  hintfull        hintstyle       3
     </programlisting>
       </para>
     </refsect2>
@@ -483,6 +521,13 @@ This is an example of a system-wide configuration file
 --&gt;
 &lt;include ignore_missing="yes"&gt;~/.fonts.conf&lt;/include&gt;
 
+&lt;!--
+	Load local customization files, but don't complain
+	if there aren't any
+--&gt;
+&lt;include ignore_missing="yes"&gt;conf.d&lt;/include&gt;
+&lt;include ignore_missing="yes"&gt;local.conf&lt;/include&gt;
+
 &lt;!--
 	Alias well known font names to available TrueType fonts.
 	These substitute TrueType faces for similar Type1
@@ -495,7 +540,7 @@ This is an example of a system-wide configuration file
 &lt;/alias&gt;
 &lt;alias&gt;
 	&lt;family&gt;Helvetica&lt;/family&gt;
-	&lt;prefer&gt;&lt;family&gt;Verdana&lt;/family&gt;&lt;/prefer&gt;
+	&lt;prefer&gt;&lt;family&gt;Arial&lt;/family&gt;&lt;/prefer&gt;
 	&lt;default&gt;&lt;family&gt;sans&lt;/family&gt;&lt;/default&gt;
 &lt;/alias&gt;
 &lt;alias&gt;
@@ -515,7 +560,7 @@ This is an example of a system-wide configuration file
 &lt;/alias&gt;
 &lt;alias&gt;
 	&lt;family&gt;sans&lt;/family&gt;
-	&lt;prefer&gt;&lt;family&gt;Verdana&lt;/family&gt;&lt;/prefer&gt;
+	&lt;prefer&gt;&lt;family&gt;Arial&lt;/family&gt;&lt;/prefer&gt;
 &lt;/alias&gt;
 &lt;alias&gt;
 	&lt;family&gt;monospace&lt;/family&gt;
@@ -561,6 +606,15 @@ instructions on editing program specified font patterns before attempting to
 match the available fonts.  It is in xml format.
   </para>
   <para>
+<emphasis>conf.d</emphasis>
+is the conventional name for a directory of additional configuration files
+managed by external applications or the local administrator.  The
+filenames starting with decimal digits are sorted in lexicographic order
+and used as additional configuration files.  All of these files are in xml
+format.  The master fonts.conf file references this directory in an 
+&lt;include&gt; directive.
+  </para>
+  <para>
 <emphasis>fonts.dtd</emphasis>
 is a DTD that describes the format of the configuration files.
   </para>

fontconfig/fontconfig.h

@@ -85,7 +85,7 @@ typedef int		FcBool;
 #define FC_DPI		    "dpi"		/* double */
 #define FC_RGBA		    "rgba"		/* Int */
 #define FC_MINSPACE	    "minspace"		/* Bool use minimum line spacing */
-#define FC_SOURCE	    "source"		/* String (X11, freetype) */
+#define FC_SOURCE	    "source"		/* String (deprecated) */
 #define FC_CHARSET	    "charset"		/* CharSet */
 #define FC_LANG		    "lang"		/* String RFC 3066 langs */
 #define FC_FONTVERSION	    "fontversion"	/* Int from 'head' table */

src/fcfreetype.c

@@ -1281,9 +1281,6 @@ FcFreeTypeQuery (const FcChar8	*file,
     if (!FcPatternAddInteger (pat, FC_INDEX, id))
 	goto bail1;
 
-    if (!FcPatternAddString (pat, FC_SOURCE, (FcChar8 *) "FreeType"))
-	goto bail1;
-
 #if 0
     /*
      * don't even try this -- CJK 'monospace' fonts are really