A configuration file may contain multiple path declarations of one type. In thiscase, a list of path elements is built internally in the same order that thespecifications appear in the configuration file. For example, the statement \begin{verbatim}TYPE1=/usr/X11/fonts/Type1:/home/user/fonts/Type1\end{verbatim}is equivalent to the two statements\begin{verbatim}TYPE1=/usr/X11/fonts/Type1TYPE1=/home/user/fonts/Type1\end{verbatim}In order to specify paths that incorporate {\em unusual} characters like whitespace or the path separator, it is possible to quote the path string elementusing double quotes ``\verb+"+''. All characters after the leading quotationmark are verbatim read to the path until the closing quotation markappears. The double quotes may also become part of a path specification by using the escape sequence ``\verb+\"+''. Hence, the followingstatement specifies a correct albeit somewhat unusual search path:\begin{verbatim}TYPE1=/usr/X11/fonts/Type1:"/home/user/My \"Best\" Fonts/Type1"\end{verbatim}Here is an example of how a user could do the runtime setup: \\[2mm]{\bfseries Example}: \\Create a file, say, named \verb+t1.config+ with the followingcontents in your HOME-directory:\begin{verbatim}# This is a configuration file for t1lib  These two lines are considered to be commentsFONTDATABASE=/home/user/test/myprog/FontDataBaseENCODING=/usr/local/lib/fonts/type1/enc:.AFM=/usr/local/lib/fonts/type1/afm:.TYPE1=/usr/local/lib/fonts/type1/outlines:.\end{verbatim}After this, make the environment variable \verb+T1LIB_CONFIG+  pointto this file, i.e., \\\verb+setenv T1LIB_CONFIG ~/t1.config+\\ for \verb+tcsh+, or\\ \verb+export T1LIB_CONFIG=~/t1.config+\\for \verb+bash+. Provided that the path specifications in theconfiguration file are correct, the setup is done. When setting\verb+T1LIB_CONFIG+ in an interactive shell as described above, the shell doesthe tilde expansion. Notice that \tonelib\ never does tilde expansion.\subsubsection{The Font Database File}\label{fontdatabase}%This is one more file important at startup time. I call it``font database file'' because it makes fonts declared in this fileknown to the library. Moreover, the association {\em declared font  $\Longleftrightarrow$ FontID} is done using information from thisfile. The format specification of this file is relatively free. Here arethe exact rules:\begin{itemize}\item Line 1 contains a positive integer specifying the  number of fonts declared in that file. This is as in the  \verb+fonts.dir+ files of the X11-system.\item All remaining lines contain declarations of one font each. The  only thing taken from such a line is the last string  (delimited by white space) in it. It is assumed to be a  filename of the format {\em basename}\verb+.+{\em someextension}.  Furthermore, the {\em basename}-part is assumed to be the basename  of a fontfile name.  After such a string has been parsed, the  {\em extension} is cut off and replaced in turn with \verb+.pfa+ and  \verb+.pfb+. The initialization routine tries to open a font  file with one of the resulting filenames.  Since V.~0.9 the ``\verb+.+'' as well as the ``{\em someextension}'' may be  missing completely. Moreover, \tonelib\ looks for Type 1 Font files whose  name do not have any extension at all. This is due to conventions of some  UNIX-systems. \item The remaining of the line, i.e., from beginning to the start of the  filename string is completely ignored and may contain some  information for other programs or be empty.\end{itemize}The format described above may seem to be underspecified, but it hasbeen chosen to be compatible with the \verb+SciFonts+-fileformat,which is used during the initialization of the SciTeXt wordprocessor. \\[2mm]{\bfseries Example 1}: A minimal font database file for 4 fonts:{\footnotesize\begin{verbatim}4isvl.afmisvli.afmisvd.afmisvdi.afm\end{verbatim}}%This file is {\em minimal}, because it contains just the informationneeded, and nothing not needed by \tonelib. {\bfseries Example 2}: A morerealistic example, which allows an application to match a fullyqualified X11 fontname to a FontID in \tonelib. This is also avalid font database file:{\footnotesize\hfuzz=30pt\relax\begin{verbatim}4Souvenir   Souvenir-Light        ---   -itc-souvenir-light-r-normal--#-0-0-0-p-0-iso8859-1  isvl.afm"          Souvenir-LightItalic  -*-   -itc-souvenir-light-i-normal--#-0-0-0-p-0-iso8859-1  isvli.afm"          Souvenir-Demi         *--   -itc-souvenir-demi-r-normal--#-0-0-0-p-0-iso8859-1   isvd.afm"          Souvenir-DemiItalic   **-   -itc-souvenir-demi-i-normal--#-0-0-0-p-0-iso8859-1   isvdi.afm\end{verbatim}}%\subsubsection{Alternative Runtime Setups}The runtime setup described above is the most simple principle ofgetting started. However, there might be applications that deal withonly one font file. A good example is the \verb+type1afm+-utilitywhich is described in section \ref{type1afm}. In such situations it seems tobe overkill to read a font database file and several load paths. Forthis reason there are alternative ways to specify what should be readfrom where. Their description is deferred to section\ref{initialization}.   \subsection{A Very Simple Programming Example}\label{programmingexample}The following code is a very simple programming example of how to use\tonelib. It even runs on an ASCII-terminal. It is provided in the\verb+examples+-subdirectory of the distribution as \verb+t1example1.c+.This program must be compiled to object format and then linked withthe library \verb+libt1.a+ or \verb+libt1.so+, respectively. On most systemsthe commandline \begin{verbatim} cc -o t1example1 -I ../lib t1example1.c -L../lib -lt1 -lm\end{verbatim}should do it. For convenience reasons a \verb+Makefile.in+ is included in theexamples directory and the stuff is built automatically. At runtime, awell defined setup must be found, i.e., a configuration file with pathdefinitions and a font database file. These also are located in the\verb+examples+ subdirectory.\begin{verbatim}#include <stdio.h>#include <stdlib.h>#include <t1lib.h>  /* All needed declarations */int main( void){  GLYPH *glyph;  int i;    /* Set our environment to an existent config file directory */  putenv( "T1LIB_CONFIG=./t1lib.config");  /* Pad bitmaps to 16 bits, the default being 8 bits */  T1_SetBitmapPad( 16);    /* Initialize t1lib and return if error occurs. No logfile will be     generated */  if ((T1_InitLib(NO_LOGFILE)==NULL)){    fprintf(stderr, "Initialization of t1lib failed\n");    return(-1);  }  /* For every font in the database, generate a glyph for the string     "Test" at 25 bp. Use Kerning. Then dump an ASCII representation     of the glyph to stdout */  for( i=0; i<T1_Get_no_fonts(); i++){    glyph=T1_SetString( i, "Test", 0, 0, T1_KERNING, 25.0, NULL);    T1_DumpGlyph( glyph);  }  /* Close library and free all data */  T1_CloseLib();    return( 0);  }\end{verbatim}We assume that in the current directory there is a file\verb+FontDataBase+ which declares two fonts, Souvenir Light and a bolditalic variant and further, that these fonts and theirAFM files can be found using the paths from the configurationfile. If the resulting program is run, it produces some output like the following on \verb+stdout+: \newpage\begin{verbatim}Dataformat: T1_bit=0, T1_byte=1, T1_wordsize=16, T1_pad=16GlyphInfo: h=18, w=44, paddedW=48.XXXXXXXXXXXXXX. ................ ................ XXX....XX....XXX ................ ................ X......XX......X ................ ........X....... .......XX....... ................ ........X....... .......XX....... ................ .......XX....... .......XX....... ................ .......XX....... .......XX....... ...XXXX.......XX XXX..XXXXXXX.... .......XX....... .XX...XX.....XX. ..XX...XX....... .......XX....... XX.....XX...XX.. ...X...XX....... .......XX....... XX.....XX...XX.. .......XX....... .......XX......X X......XX...XXX. .......XX....... .......XX......X X....XXX.....XXX XXX....XX....... .......XX......X XXXXXXX.......XX XXXX...XX....... .......XX......X XX.............. ..XXX..XX....... .......XX......X X............... ...XX..XX....... .......XX....... XX......XX..X... ...XX..XX....... .......XX....... XXX....X....XX.. ..XX...XX....... .....XXXXXX..... ..XXXXX.......XX XXX....XXXXX.... Dataformat: T1_bit=0, T1_byte=1, T1_wordsize=16, T1_pad=16GlyphInfo: h=18, w=51, paddedW=64.XXXXXXXXXXXXXXX X............... ................ ................ .XXXXXXXXXXXXXXX X............... ................ ................ .XX....XXXX....X X............... ...............X X............... .X.....XXXX..... X............... ...............X X............... ......XXXXX..... ................ ..............XX X............... ......XXXXX..... ................ ..............XX X............... ......XXXX...... ....XXXXXX...... .XXXXX.....XXXXX XXX............. ......XXXX...... ..XXXXXXXXXX...X XXXXXXXX...XXXXX XXX............. ......XXXX...... .XXXX...XXXX..XX XX...XXX....XXXX ................ ......XXXX...... XXXX....XXXX..XX XX....XX....XXXX ................ .....XXXXX...... XXXX...XXXX...XX XXXX........XXXX ................ .....XXXXX.....X XXX..XXXXX.....X XXXXXX......XXXX ................ .....XXXX......X XXXXXXXX........ XXXXXXXX....XXXX ................ .....XXXX......X XXX............. ..XXXXXX...XXXX. ................ .....XXXX......X XXX.......X..XX. ....XXXX...XXXX. ................ .....XXXX....... XXXX....XXX.XXXX ....XXXX...XXXXX XX.............. ....XXXXXX...... XXXXXXXXXX...XXX XXXXXXX....XXXXX XX.............. ...XXXXXXX...... ..XXXXXX.......X XXXXX......XXXX. ................ \end{verbatim}%%% Local Variables: %%% mode: latex%%% TeX-master: "t1lib_doc"%%% TeX-master: "ut1lib"%%% End: