aboutsummaryrefslogtreecommitdiff
path: root/libXfont/doc/fontlib.xml
blob: cce83e9bdc9cb17ca8d9ae10d69c6fb746a6e732 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
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>