svn merge ^/branches/released .

3 files changed, 744 insertions, 0 deletions

diff --git a/libXfont/doc/fontlib.css b/libXfont/doc/fontlib.css
new file mode 100644
index 000000000..137200fcd
--- /dev/null
+++ b/libXfont/doc/fontlib.css
@@ -0,0 +1,46 @@
+/* Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a
+ * copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, and/or sell copies of the Software, and to permit persons
+ * to whom the Software is furnished to do so, provided that the above
+ * copyright notice(s) and this permission notice appear in all copies of
+ * the Software and that both the above copyright notice(s) and this
+ * permission notice appear in supporting documentation.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+ * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+ * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
+ * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
+ * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+ * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
+ * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ *
+ * Except as contained in this notice, the name of a copyright holder
+ * shall not be used in advertising or otherwise to promote the sale, use
+ * or other dealings in this Software without prior written authorization
+ * of the copyright holder.
+ */
+
+.structname, .property, .errorname, .function, .parameter, .filename {
+  font-family: monospace;
+}
+
+h1, .author, .pubdate {
+  text-align: center;
+}
+
+.legalnotice {
+  text-align: justify;
+  font-size: small;
+  font-style: italic;
+}
+
+.warning {
+  border: 1px solid red;
+  background: yellow;
+}
diff --git a/libXfont/doc/fontlib.xml b/libXfont/doc/fontlib.xml
new file mode 100644
index 000000000..8b7245ef1
--- /dev/null
+++ b/libXfont/doc/fontlib.xml
@@ -0,0 +1,660 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+            "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" >
+<!-- lifted from troff+ms by doclifter -->
+<!-- previous version was in xorg-docs/specs/Xserver/fontlib.ms -->
+
+  <article id='fontlibms'>
+<!-- .ps 12 -->
+<!--  $Xorg: fontlib.ms,v 1.3 2000/08/17 19:42:42 cpqbld Exp $ -->
+<!-- .EF 'Font Library Interface'\- % \-'July 27, 1991' -->
+<!-- .OF 'Font Library Interface'\- % \-'July 27, 1991' -->
+<!-- .EH '''' -->
+<!-- .OH '''' -->
+<!-- body begins here -->
+    <articleinfo>
+      <title>
+	The X Font Library
+      </title>
+      <pubdate>July 27, 1991</pubdate>
+      <authorgroup>
+	<author>
+	  <firstname>Keith</firstname>
+	  <surname>Packard</surname>
+	  <affiliation>
+	    <orgname>MIT X Consortium</orgname>
+	  </affiliation>
+	</author>
+	<author>
+	  <firstname>David</firstname>
+	  <surname>Lemke</surname>
+	  <affiliation>
+	    <orgname>Network Computing Devices</orgname>
+	  </affiliation>
+	</author>
+      </authorgroup>
+      <legalnotice>
+	<para>
+	  Copyright 1993 <orgname>Network Computing Devices</orgname>
+	</para>
+	<para>
+	  Permission to use, copy, modify, distribute, and sell this
+	  software and its documentation for any purpose is hereby
+	  granted without fee, provided that the above copyright
+	  notice appear in all copies and that both that copyright
+	  notice and this permission notice appear in supporting
+	  documentation, and that the name of Network Computing
+	  Devices not be used in advertising or publicity pertaining
+	  to distribution of the software without specific, written
+	  prior permission.  Network Computing Devices makes no
+	  representations about the suitability of this software for
+	  any purpose.  It is provided &ldquo;as is&rdquo; without
+	  express or implied warranty.
+	</para>
+	<para>
+	  Copyright 1993, 1994 <orgname>X Consortium</orgname>
+	</para>
+	<para>
+	  Permission is hereby granted, free of charge, to any person
+	  obtaining a copy of this software and associated
+	  documentation files (the &ldquo;Software&rdquo;), to deal in the
+	  Software without restriction, including without limitation
+	  the rights to use, copy, modify, merge, publish, distribute,
+	  sublicense, and/or sell copies of the Software, and to
+	  permit persons to whom the Software is furnished to do so,
+	  subject to the following conditions:
+	</para><para>
+	  The above copyright notice and this permission notice shall be
+	  included in all copies or substantial portions of the Software.
+	</para><para>
+	  THE SOFTWARE IS PROVIDED &ldquo;AS IS&rdquo;, WITHOUT WARRANTY
+	  OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+	  THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+	  PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X
+	  CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+	  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+	  OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+	  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+	</para><para>
+	  Except as contained in this notice, the name of the X
+	  Consortium shall not be used in advertising or otherwise to
+	  promote the sale, use or other dealings in this Software
+	  without prior written authorization from the X Consortium.
+	</para>
+      </legalnotice>
+    </articleinfo>
+
+    <warning>
+      <para>
+	This document has not been updated since X11R6, and is likely
+	to be somewhat out of date for the current libXfont.
+      </para>
+    </warning>
+
+    <para>
+      This document describes the data structures and interfaces for
+      using the X Font library.  It is intended as a reference for
+      programmers building X and Font servers.  You may want to refer
+      to the following documents:
+    </para>
+
+    <itemizedlist>
+      <listitem>
+	<para>
+	  <citetitle pubwork="article">Definition of the Porting Layer for
+	    the X v11 Sample Server</citetitle> for a discussion on how this
+	  library interacts with the X server
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  <citetitle pubwork="article">Font Server Implementation
+	    Overview</citetitle> which discusses the design of the font
+	  server.
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  <citetitle pubwork="article">Bitmap Distribution Format</citetitle>
+	  which covers the contents of the bitmap font files which this
+	  library reads; although the library is capable of reading other
+	  formats as well, including non-bitmap fonts.
+	</para>
+      </listitem>
+      <listitem>
+	<para>
+	  <citetitle pubwork="article">The X Font Service Protocol</citetitle>
+	  for a description of the constraints placed  on the design by
+	  including support for this font service mechanism.
+	</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>
+      This document assumes the reader is familiar with the X server design,
+      the X protocol as it relates to fonts and the C programming language.
+      As with most MIT produced documentation, this relies heavily on the
+      source code, so have a listing handy.
+    </para>
+
+    <sect1 id='requirements_for_the_font_library'>
+      <title>
+	Requirements for the Font library
+      </title>
+
+      <para>
+	To avoid miles of duplicate code in the X server, the font server
+	and the various font manipulation tools, the font library should
+	provide interfaces appropriate for all of these	tasks.  In
+	particular, the X server and font server should be able to both
+	use the library to access disk based fonts, and	to communicate
+	with a font server.  By providing a general library, we hoped to
+	avoid duplicating code between the X server and font server.
+      </para>
+
+      <para>
+	Another requirement is that the X server (or even a font server)
+	be able to continue servicing requests from other clients while
+	awaiting a response from the font server on behalf of one client.
+	This is the strongest requirement placed on the	font library, and
+	has warped the design in curious ways.	Because both the X server
+	and font server are single threaded, the font library must not
+	suspend internally, rather it returns an indication of suspension
+	to the application which continues processing other things, until
+	the font data is ready, at which time it restarts the suspended
+	request.
+      </para>
+
+      <para>
+	Because the code for reading and manipulating bitmap font data is
+	used by the font applications <command>mkfontdir</command> and
+	<command>bdftopcf</command>, the font library includes
+	bitmap-font specific interfaces which those applications use,
+	instead of the more general interfaces used by the X and font
+	servers, which are unaware of the source of the font data.
+	These routines will be refered to as the bitmap font access
+	methods.
+      </para>
+
+    </sect1>
+
+    <sect1 id='general_font_library_interface_details'>
+      <title>
+	General Font Library Interface details.
+      </title>
+
+      <para>
+	To avoid collision between the #define name space for errors, the Font
+	library defines a new set of return values:
+      </para>
+
+      <programlisting remap='.nf'>
+#define AllocError      80
+#define StillWorking    81
+#define FontNameAlias   82
+#define BadFontName     83
+#define Suspended       84
+#define Successful      85
+#define BadFontPath     86
+#define BadCharRange    87
+#define BadFontFormat   88
+#define FPEResetFailed  89
+      </programlisting> <!-- .fi -->
+
+      <para>
+	Whenever a routine returns <errorname>Suspended</errorname>,
+	the font library will notify the caller (via the ClientSignal
+	interface described below) who should then reinvoke the same routine
+	again with the same arguments.
+      </para>
+
+    </sect1>
+
+    <sect1 id='font_path_elements'>
+      <title>
+	Font Path Elements
+      </title>
+
+      <para>
+	At the center of the general font access methods used by X and
+	<command>xfs</command> is the Font Path Element data structure.
+	Like most structures in the X server, this contains a collection
+	of data and some function pointers for manipulating this data:
+      </para>
+
+      <programlisting remap='.nf'>
+/* External view of font paths */
+typedef struct _FontPathElement {
+    int         name_length;
+    char       *name;
+    int         type;
+    int         refcount;
+    pointer     private;
+} FontPathElementRec, *FontPathElementPtr;
+
+typedef struct _FPEFunctions {
+    int         (*name_check) ( /* name */ );
+    int         (*init_fpe) ( /* fpe */ );
+    int         (*reset_fpe) ( /* fpe */ );
+    int         (*free_fpe) ( /* fpe */ );
+    int         (*open_font) (  /* client, fpe, flags,
+                        name, namelen, format,
+                        fid,  ppfont, alias */ );
+    int         (*close_font) ( /* pfont */ );
+    int         (*list_fonts) ( /* client, fpe, pattern,
+                        patlen, maxnames, paths */ );
+    int         (*start_list_fonts_with_info) (
+                        /* client, fpe, name, namelen,
+                           maxnames, data */ );
+    int         (*list_next_font_with_info) (
+                        /* client, fpe, name, namelen,
+                           info, num, data */ );
+    int         (*wakeup_fpe) ( /* fpe, mask */ );
+    int         (*client_died) ( /* client, fpe */ );
+} FPEFunctionsRec, FPEFunctions;
+      </programlisting> <!-- .fi -->
+
+      <para>
+	The function pointers are split out from the data structure to
+	save memory; additionally, this avoids any complications when
+	initializing the data structure as there would not be any way
+	to discover the appropriate function to	call (a chicken and
+	egg problem).
+      </para>
+
+      <para>
+	When a font path type is initialized, it passes the function
+	pointers to the server which are then stored in an
+	<structname>FPEFunctionsRec</structname>. Each function is
+	described below in turn.
+      </para>
+
+      <sect2 id='name_check'>
+	<title>
+	  (*name_check)
+	</title>
+
+	<para>
+	  Each new font path member is passed to this function; if
+	  the return value is <errorname>Successful</errorname>, then
+	  the FPE recognises the format of the string.  This does not
+	  guarantee that the FPE will be able to successfully use this
+	  member.  For example, the disk-based font directory file
+	  <filename>fonts.dir</filename> may be corrupted, this will
+	  not be detected until the font path is initialized.  This
+	  routine never returns <errorname>Suspended</errorname>.
+	</para>
+      </sect2>
+
+      <sect2 id='init_fpe'>
+	<title>
+	  (*init_fpe)
+	</title>
+
+	<para>
+	  Initialize a new font path element.  This function prepares
+	  a new font path element for other requests: the disk font
+	  routine reads the <filename>fonts.dir</filename> and
+	  <filename>fonts.alias</filename> files into the internal
+	  format, while the font server routine connects to the
+	  requested font server and prepares for using it.  This
+	  routine returns <errorname>Successful</errorname> if
+	  everything went OK, otherwise the return value indicates the
+	  source of the problem.  This routine never returns
+	  <errorname>Suspended</errorname>.
+	</para>
+      </sect2>
+
+      <sect2 id='reset_fpe'>
+	<title>
+	  (*reset_fpe)
+	</title>
+
+	<para>
+	  When the X font path is reset, and some of the new members
+	  are also in the old font path, this function is called to
+	  reinitialize those FPEs.  This routine returns
+	  <errorname>Successful</errorname> if everything went OK.  It
+	  returns <errorname>FPEResetFailed</errorname> if (for some
+	  reason) the reset failed, and the caller should remove the
+	  old FPE and simply create a new one in its place.  This is
+	  used by the disk-based fonts routine as resetting the
+	  internal directory structures would be more complicated than
+	  simply having destroying the old and creating a new.
+	</para>
+      </sect2>
+
+      <sect2 id='free_fpe'>
+	<title>
+	  (*free_fpe)
+	</title>
+
+	<para>
+	  When the server is finished with an FPE, this function is
+	  called to dispose of any internal state.  It should return
+	  <errorname>Successful</errorname>, unless something terrible
+	  happens.
+	</para>
+      </sect2>
+
+      <sect2 id='open_font'>
+	<title>
+	  (*open_font)
+	</title>
+
+	<para>
+	  This routine requests that a font be opened.  The <parameter
+	  class='function'>client</parameter> argument is used by the
+	  font library only in connection with suspending/restarting
+	  the request.  The <parameter class='function'>flags</parameter>
+	  argument specifies some behaviour for the library and can be
+	  any of:
+	</para>
+
+	<programlisting remap='.nf'>
+/* OpenFont flags */
+#define FontLoadInfo    0x0001
+#define FontLoadProps   0x0002
+#define FontLoadMetrics 0x0004
+#define FontLoadBitmaps 0x0008
+#define FontLoadAll     0x000f
+#define FontOpenSync    0x0010
+	</programlisting> <!-- .fi -->
+
+	<para>
+	  The various fields specify which portions of the font should
+	  be loaded at this time.  When <constant>FontOpenSync</constant>
+	  is specified, this routine will not return until all of the
+	  requested portions are loaded.  Otherwise, this routine may
+	  return <errorname>Suspended</errorname>.  When the presented
+	  font name is actually an alias for some other font name,
+	  <errorname>FontNameAlias</errorname> is returned, and the
+	  actual font name is stored in the location pointed to by the
+	  <parameter class='function'>alias</parameter> argument as a
+	  null-terminated string.
+	</para>
+      </sect2>
+
+      <sect2 id='close_font'>
+	<title>
+	  (*close_font)
+	</title>
+
+	<para>
+	  When the server is finished with a font, this routine
+	  disposes of any internal state and frees the font data
+	  structure.
+	</para>
+      </sect2>
+
+      <sect2 id='list_fonts'>
+	<title>
+	  (*list_fonts)
+	</title>
+
+	<para>
+	  The <parameter class='function'>paths</parameter> argument is
+	  a data structure which will be filled with all of the font names
+	  from this directory which match the specified
+	  <parameter class='function'>pattern</parameter>.  At
+	  most <parameter class='function'>maxnames</parameter> will be added.
+	  This routine may return <errorname>Suspended</errorname>.
+	</para>
+      </sect2>
+
+      <sect2 id='start_list_fonts_with_info'>
+	<title>
+	  (*start_list_fonts_with_info)
+	</title>
+
+	<para>
+	  This routine sets any internal state for a verbose listing of
+	  all fonts matching the specified pattern.  This routine may
+	  return <errorname>Suspended</errorname>.
+	</para>
+      </sect2>
+
+      <sect2 id='list_next_font_with_info'>
+	<title>
+	  (*list_next_font_with_info)
+	</title>
+
+	<para>
+	  To avoid storing huge amounts of data, the interface for
+	  ListFontsWithInfo allows the server to get one reply at a time
+	  and forward that to the client.  When the font name returned
+	  is actually an alias for some other font,
+	  <errorname>FontNameAlias</errorname> will be returned.  The
+	  actual font name is return instead, and the font alias which
+	  matched the pattern is returned in the location pointed to by
+	  data as a null-terminated string.  The caller can then get the
+	  information by recursively listing that font name with a
+	  maxnames of 1.  When <errorname>Successful</errorname> is
+	  returned, the matching font name is returned, and a
+	  FontInfoPtr is stored in the location pointed to by
+	  <parameter class='function'>data</parameter>.
+	  <parameter class='function'>Data</parameter> must be initialized
+	  with a pointer to a FontInfoRec allocated by the caller.  When the
+	  pointer pointed to by <parameter class='function'>data</parameter>
+	  is not left pointing at that storage, the caller mustn't free the
+	  associated property data. This routine may return
+	  <errorname>Suspended</errorname>.
+	</para>
+      </sect2>
+
+      <sect2 id='wakeup_fpe'>
+	<title>
+	  (*wakeup_fpe)
+	</title>
+
+	<para>
+	  Whenever an FPE function has returned
+	  <errorname>Suspended</errorname>, this routine is called
+	  whenever the application wakes up from waiting for input
+	  (from <citerefentry><refentrytitle>select</refentrytitle>
+	    <manvolnum>2</manvolnum></citerefentry>).  This
+	    <parameter class='function'>mask</parameter> argument should be
+	    the value returned from <function>select(2)</function>.
+	</para>
+      </sect2>
+
+      <sect2 id='client_died'>
+	<title>
+	  (*client_died)
+	</title>
+
+	<para>
+	  When an FPE function has returned <errorname>Suspended</errorname>
+	  and the associated client is being destroyed, this function
+	  allows the font library to dispose of any state associated
+	  with that client.
+	</para>
+      </sect2>
+    </sect1>
+
+    <sect1 id='fonts'>
+      <title>
+	Fonts
+      </title>
+
+      <para>
+	The data structure which actually contains the font information has
+	changed significantly since previous releases; it now attempts to
+	hide the actual storage format for the data from the application,
+	providing accessor functions to get at the data.  This allows a
+	range of internal details for different font sources.  The structure
+	is split into two pieces, so that ListFontsWithInfo can share
+	information from the font when it has been loaded.  The
+	<structname>FontInfo</structname> structure, then, contains only
+	information germane to LFWI.
+      </para>
+
+      <programlisting remap='.nf'>
+typedef struct _FontInfo {
+    unsigned short firstCol;            /* range of glyphs for this font */
+    unsigned short lastCol;
+    unsigned short firstRow;
+    unsigned short lastRow;
+    unsigned short defaultCh;           /* default character index */
+    unsigned int noOverlap:1;           /* no combination of glyphs overlap */
+    unsigned int terminalFont:1;        /* Character cell font */
+    unsigned int constantMetrics:1;     /* all metrics are the same */
+    unsigned int constantWidth:1;       /* all character widths are the same*/
+    unsigned int inkInside:1;           /* all ink inside character cell */
+    unsigned int inkMetrics:1;          /* font has ink metrics */
+    unsigned int allExist:1;            /* no missing chars in range */
+    unsigned int drawDirection:2;       /* left-to-right/right-to-left*/
+    unsigned int cachable:1;            /* font needn't be opened each time*/
+    unsigned int anamorphic:1;          /* font is strangely scaled */
+    short       maxOverlap;             /* maximum overlap amount */
+    short       pad;                    /* unused */
+    xCharInfo   maxbounds;              /* glyph metrics maximums */
+    xCharInfo   minbounds;              /* glyph metrics minimums */
+    xCharInfo   ink_maxbounds;          /* ink metrics maximums */
+    xCharInfo   ink_minbounds;          /* ink metrics minimums */
+    short       fontAscent;             /* font ascent amount */
+    short       fontDescent;            /* font descent amount */
+    int         nprops;                 /* number of font properties */
+    FontPropPtr props;                  /* font properties */
+    char       *isStringProp;           /* boolean array */
+}           FontInfoRec, *FontInfoPtr;
+      </programlisting> <!-- .fi -->
+
+      <para>
+	The font structure, then, contains a font info record, the format of
+	the bits in each bitmap and the functions which access the font
+	records (which are stored in an opaque format hung off of
+	<structfield>fontPrivate</structfield>).
+      </para>
+
+      <programlisting remap='.nf'>
+typedef struct _Font {
+    int         refcnt;
+    FontInfoRec info;
+    char        bit;                    /* bit order: LSBFirst/MSBFirst */
+    char        byte;                   /* byte order: LSBFirst/MSBFirst */
+    char        glyph;                  /* glyph pad: 1, 2, 4 or 8 */
+    char        scan;                   /* glyph scan unit: 1, 2 or 4 */
+    fsBitmapFormat format;              /* FS-style format (packed) */
+    int         (*get_glyphs)  ( /* font, count, chars, encoding, count, glyphs */ );
+    int         (*get_metrics) ( /* font, count, chars, encoding, count, glyphs */ );
+    int         (*get_bitmaps) ( /* client, font, flags, format,
+                                    flags, nranges, ranges, data_sizep,
+                                    num_glyphsp, offsetsp, glyph_datap,
+                                    free_datap */ );
+    int         (*get_extents) ( /* client, font, flags, nranges,
+                                    ranges, nextentsp, extentsp */);
+    void        (*unload_font) ( /* font */ );
+    FontPathElementPtr fpe;             /* FPE associated with this font */
+    pointer     svrPrivate;             /* X/FS private data */
+    pointer     fontPrivate;            /* private to font */
+    pointer     fpePrivate;             /* private to FPE */
+    int         maxPrivate;             /* devPrivates (see below) */
+    pointer     *devPrivates;           /*  ... */
+}           FontRec, *FontPtr;
+      </programlisting> <!-- .fi -->
+
+      <para>
+	Yes, there are several different private pointers in the
+	<structfield>Font</structfield> structure; they were added
+	haphazardly until the devPrivate pointers were added.  Future
+	releases may remove some (or all) of the specific pointers,
+	leaving only the <structfield>devPrivates</structfield>mechanism.
+      </para>
+
+      <para>
+	There are two similar interfaces implemented -
+	<structfield>get_glyphs</structfield>/<structfield>get_metrics</structfield>
+	and
+	<structfield>get_bitmaps</structfield>/<structfield>get_extents</structfield>.
+	Too little time caused the font-server specific interfaces to
+	be placed in the font library (and portions duplicated in each
+	renderer) instead of having them integrated into the font server
+	itself.  This may change.  The X server uses only
+	<structfield>get_glyphs</structfield>/<structfield>get_metrics</structfield>,
+	and those will not change dramatically.  Each of the routines
+	is described below.
+      </para>
+
+      <sect2 id='get_glyphs'>
+	<title>
+	  (*get_glyphs)
+	</title>
+
+	<para>
+	  This routine returns <structname>CharInfoPtrs</structname>
+	  for each of the requested characters in the font.  If the
+	  character does not exist in the font, the default character
+	  will be returned, unless no default character exists in
+	  which case that character is skipped.  Thus, the number of
+	  glyphs returned will not always be the same as the number of
+	  characters passed in.
+	</para>
+      </sect2>
+
+      <sect2 id='get_metrics'>
+	<title>
+	  (*get_metrics)
+	</title>
+
+	<para>
+	  This is similar to <structfield>(*get_glyphs)</structfield>
+	  except that pointers to <structname>xCharInfo</structname>
+	  structures are returned, and, if the font has ink metrics,
+	  those are returned instead of the bitmap metrics.
+	</para>
+      </sect2>
+
+      <sect2 id='getbitmaps'>
+	<title>
+	  (*get_bitmaps)
+	</title>
+
+	<para>
+	  This packs the glyph image data in the requested
+	  <parameter class='function'>format</parameter> and returns it.  The
+	  <parameter class='function'>ranges</parameter>/<parameter class='function'>nranges</parameter>
+	  argument specify the set of glyphs from the font to pack together.
+	</para>
+      </sect2>
+
+      <sect2 id='get_extents'>
+	<title>
+	  (*get_extents)
+	</title>
+
+	<para>
+	  This returns the metrics for the specified font from the
+	  specified <parameter class='function'>ranges</parameter>.
+	</para>
+
+      </sect2>
+
+      <sect2 id='unload_font'>
+	<title>
+	  (*unload_font)
+	</title>
+
+	<para>
+	  This is called from the FPE routine
+	  <function>(*close_font)</function>, and so should not ever be
+	  called from the application.
+	</para>
+      </sect2>
+
+      <sect2 id='maxprivate'>
+	<title>
+	  maxPrivate
+	</title>
+
+	<para>
+	  When initializing a new font structure,
+	  <structfield>maxPrivate</structfield> should be set to -1 so
+	  that the <function>FontSetPrivate()</function> macro works
+	  properly with an index of 0.  Initializing
+	  <structfield>maxPrivate</structfield> to 0 can cause
+	  problems if the server tries to set something at index 0.
+	</para>
+      </sect2>
+    </sect1>
+  </article>
diff --git a/libXfont/doc/fontlib.xsl b/libXfont/doc/fontlib.xsl
new file mode 100644
index 000000000..644f147d4
--- /dev/null
+++ b/libXfont/doc/fontlib.xsl
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="utf-8"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                version="1.0">
+  <!--
+       Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
+
+       Permission is hereby granted, free of charge, to any person obtaining a
+       copy of this software and associated documentation files (the
+       "Software"), to deal in the Software without restriction, including
+       without limitation the rights to use, copy, modify, merge, publish,
+       distribute, and/or sell copies of the Software, and to permit persons
+       to whom the Software is furnished to do so, provided that the above
+       copyright notice(s) and this permission notice appear in all copies of
+       the Software and that both the above copyright notice(s) and this
+       permission notice appear in supporting documentation.
+
+       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+       OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+       MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+       OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+       HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
+       INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
+       FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+       NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
+       WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+       Except as contained in this notice, the name of a copyright holder
+       shall not be used in advertising or otherwise to promote the sale, use
+       or other dealings in this Software without prior written authorization
+       of the copyright holder.
+   -->
+
+  <xsl:param name="html.stylesheet" select="'fontlib.css'"/>
+  <xsl:param name="chunker.output.indent">yes</xsl:param>
+  <xsl:param name="html.extra.head.links" select="1"></xsl:param>
+  <xsl:param name="saxon.character.representation" select="'entity;decimal'"></xsl:param>
+  <xsl:param name="function.parens" select="0"></xsl:param>
+</xsl:stylesheet>