Synchronised line endinge with release branch

1 files changed, 659 insertions, 659 deletions

diff --git a/libXfont/doc/fontlib.xml b/libXfont/doc/fontlib.xml
index 3b0829d30..cce83e9bd 100644
--- a/libXfont/doc/fontlib.xml
+++ b/libXfont/doc/fontlib.xml
@@ -1,659 +1,659 @@
-<?xml version="1.0" encoding="UTF-8" ?>

-<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"

-            "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" >

-<!-- lifted from troff+ms by doclifter -->

-<!-- previous version was in xorg-docs/specs/Xserver/fontlib.ms -->

-

-  <article id='fontlib'>

-<!-- .ps 12 -->

-<!-- .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>

+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+            "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" >
+<!-- lifted from troff+ms by doclifter -->
+<!-- previous version was in xorg-docs/specs/Xserver/fontlib.ms -->
+
+  <article id='fontlib'>
+<!-- .ps 12 -->
+<!-- .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>