getstart.tex

source code: Covert TXT to PDF

A configuration file may contain multiple path declarations of one type. In this
case, a list of path elements is built internally in the same order that the
specifications 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/Type1
TYPE1=/home/user/fonts/Type1
\end{verbatim}

In order to specify paths that incorporate {\em unusual} characters like white
space or the path separator, it is possible to quote the path string element
using double quotes ``\verb+"+''. All characters after the leading quotation
mark are verbatim read to the path until the closing quotation mark
appears. The double quotes may also become part of a path 
specification by using the escape sequence ``\verb+\"+''. Hence, the following
statement 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 following
contents in your HOME-directory:
\begin{verbatim}
# This is a configuration file for t1lib
  These two lines are considered to be comments

FONTDATABASE=/home/user/test/myprog/FontDataBase
ENCODING=/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+  point
to 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 the
configuration file are correct, the setup is done. When setting
\verb+T1LIB_CONFIG+ in an interactive shell as described above, the shell does
the 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 file
known to the library. Moreover, the association {\em declared font
  $\Longleftrightarrow$ FontID} is done using information from this
file. The format specification of this file is relatively free. Here are
the 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 has
been chosen to be compatible with the \verb+SciFonts+-fileformat,
which is used during the initialization of the SciTeXt word
processor. \\[2mm]
{\bfseries Example 1}: A minimal font database file for 4 fonts:

{\footnotesize
\begin{verbatim}
4
isvl.afm
isvli.afm
isvd.afm
isvdi.afm
\end{verbatim}
}%

This file is {\em minimal}, because it contains just the information
needed, and nothing not needed by \tonelib. 

{\bfseries Example 2}: A more
realistic example, which allows an application to match a fully
qualified X11 fontname to a FontID in \tonelib. This is also a
valid font database file:

{\footnotesize\hfuzz=30pt\relax
\begin{verbatim}
4
Souvenir   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 of
getting started. However, there might be applications that deal with
only one font file. A good example is the \verb+type1afm+-utility
which is described in section \ref{type1afm}. In such situations it seems to
be overkill to read a font database file and several load paths. For
this reason there are alternative ways to specify what should be read
from 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 with
the library \verb+libt1.a+ or \verb+libt1.so+, respectively. On most systems
the 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 the
examples directory and the stuff is built automatically. 

At runtime, a
well defined setup must be found, i.e., a configuration file with path
definitions 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 bold
italic variant and further, that these fonts and their
AFM files can be found using the paths from the configuration
file. 
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=16
GlyphInfo: 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=16
GlyphInfo: 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: