%----------------------------------------------------------------------------
% ----- File:        getstart.tex 
% ----- Author:      Rainer Menzner (rmz@neuroinformatik.ruhr-uni-bochum.de)
% ----- Date:        04/19/1998
% ----- Description: This file is part of the t1lib-documentation.
% ----- Copyright:   t1lib is copyrighted (c) Rainer Menzner, 1996-1998. 
%                    As of version 0.5, t1lib is distributed under the
%                    GNU General Public Library Lincense. The
%                    conditions can be found in the files LICENSE and
%                    LGPL, which should reside in the toplevel
%                    directory of the distribution.  Please note that 
%                    there are parts of t1lib that are subject to
%                    other licenses:
%                    The parseAFM-package is copyrighted by Adobe Systems
%                    Inc.
%                    The type1 rasterizer is copyrighted by IBM and the
%                    X11-consortium.
% ----- Warranties:  Of course, there's NO WARRANTY OF ANY KIND :-)
% ----- Credits:     I want to thank IBM and the X11-consortium for making
%                    their rasterizer freely available.
%                    Also thanks to Piet Tutelaers for his ps2pk, from
%                    which I took the rasterizer sources in a format
%                    independ from X11.
%                    Thanks to all people who make free software living!
%----------------------------------------------------------------------------

\newpage
\section{Getting Started}
\subsection{Building, Installing and Removing the \tonelib-Package}
\label{compiling}%
As of version 0.2-beta, the \verb+autoconf+-package is used to configure and
build the library. \verb+imake+ is no longer supported.

Here is how to build and install the stuff:
\begin{enumerate}
\item Change to \verb+T1+-directory.
\item Run \verb+./configure+. This will check your system's setup and generate
  the Makefiles. Since version 0.2-beta \tonelib\ is build as a shared
  library if the system it is compiled on does support this. If shared objects
  are not supported by the system a static library is generated instead. 

  If the target system supports shared libraries but a static library is
  needed for some reason 
  \verb+configure+ can be called using the commandline option
  \verb+--with-static-lib+. Then a static library will be built, no matter 
  whether the system does support shared libraries or not.

  If you know shared libraries are supported on your system but
  \verb+configure+ says that no dll can be built, some compiler option
  may be setup incorrect. Please refer to (\ref{othercompilers}). 

  If the X11 window system is installed on the target system \tonelib\ is
  automatically build with special X11 support. In cases where this is
  explicitly not desired the commandline option 
  \verb+--without-x+ may be used to configure a library without extended X11
  support. In this case the test program \verb+xglyph+ is also not build since
  it needs X11.
\item Run \verb+make+. This will build all the stuff including the
  documentation. If you do not have \LaTeXe\, run 
  \verb+make without_doc+. This will skip generating the documentation. 
\item Type \verb+make install+ to install the package. You'll
  probably need to be superuser for installing the package at the standard
  locations. However, the files may be
  located wherever the user wants, as long as the compiler
  finds them at compile time. So, place them where you want. 

  The following files are installed when doing a \verb+make install+:
  \begin{itemize}
  \item \verb+lib/libt1.a+ or \verb+lib/libt1.so.+{\em v}\verb+.+{\em
      r}\verb+.+{\em p} if the system supports shared libraries. In
    the latter case, also two symbolic links to the shared library,
    \verb+libt1.so.+{\em v} and \verb+libt1.so+, are generated. Here,
    {\em v} and {\em r} mean version and revision of the shared
    library. {\em p} is the patch level. Library and links are
    installed in the directory 
    specified by the autoconf-variable \verb+libdir+ which is by
    default \verb+/usr/local/lib+.
  \item The same as above holds for \verb+lib/libt1x.a+ or
    \verb+lib/libt1x.so.+{\em v}\verb+.+{\em r}\verb+.+{\em p}
    respectively, which contain the X11 interface functions. This
    library is only installed if X11 support was possible and not
    suppressed. 
  \item \verb+lib/t1lib.h+ and optionally \verb+lib/t1libx.h+. They are installed
    in the directory pointed to by the autoconf-variable \verb+includedir+
    which is by default\\
    \verb+/usr/local/include+.
  \item The test program \verb+xglyph/xglyph+. If shared libraries are
    supported (and not suppressed by \verb+--with-static-lib+) this
    executable is dynamically linked to \verb+libt1.so+ and
    \verb+libt1x.so+. It is installed in the directory pointed to by
    the autoconf-variable \verb+bindir+ (by default
    \verb+/usr/local/bin+).
  \item The converter \verb+type1afm+. The same applies as above for
    \verb+xglyph+.
  \item A subdirectory named \verb+t1lib-+{\em v}\verb+.+{\em r} is created in
    the directory pointed to by the autoconf-variable \verb+datadir+ (default
    \verb+/usr/local/share+) and a default global configuration file
    \verb+t1lib.config+ is installed there. Note that this configuration is
    not of any use. It has to be setup by the administrator to specify the
    paths to the system's Type 1 fonts and AFM files as well as any
    \tonelib\ encoding files. Notice also that the global configuration file
    is not installed if it already exists. This is to prevent from deletion of
    an existent setup.
  \item A subdirectory \verb+doc+ is created in the directory where the global
    configuration file resides (see above). The \LaTeXe-documentation
    \verb+t1lib_doc.dvi+ as well as all needed graphics files is installed
    there. The \LaTeXe-sources are not installed!
  \item If you ever want to remove \tonelib\ from your system this can be
    achieved by calling \verb+make uninstall+. This reverts all steps
    described above. Of course, this works only if \tonelib\ has not been
    reconfigured using different parameters since the time of install.
  \end{itemize}
\end{enumerate}

The top level \verb+Makefile+ further supports the targets \verb+clean+ and
\verb+distclean+. The latter is an extension of \verb+clean+ which also
removes the makefiles as well as the log and cache files of the configuration
process. It forces thus a new call to \verb+configure+. 

A \verb+make clean+ is needed, for example, if someone experiments with static
and shared libraries since the object files for shared libraries require the
additional position independent code options.

The directory \verb+T1/parse_afm+ is not needed at all, it is included only
for completeness. The parts needed from this have been copied to the
\verb+lib/t1lib+-subdirectory. 


\subsection{Building with Compilers Other than GNU C Compiler}
\label{othercompilers}%
While most standard options for compiler are unique between most
compilers at the \verb+cc+ interface, this, alas, does not apply for the
options to build and link shared libraries. For example, if a shared
library is to be generated, the object files must contain position
independent code which requires a special option at compile
time. Further, the linker has to be told to generate a shared 
instead of a static library and enabling version management for shared
libraries still requires one additional option to specify the
\verb+DT_SONAME+ field for the shared library. 

Unfortunately, these parameters cannot be found out by the
\verb+configure+ script. They must be specified somewhere. When
starting \verb+configure+, a script file named \verb+options+, located
in subdirectory \verb+ac-tools+, is executed. This file defines the
necessary options to generate shared libraries for the current
compiler. In practice, this file is a symbolic link the real options
file in the same directory. The default options file is
\verb+options.gcc+, which contains the definitions for the GNU C
compiler. Here is its contents (including comments):
\begin{verbatim}
# File:      options.gcc
# Date:      03/14/1998
# Author:    Rainer Menzner (rmz@neuroinformatik.ruhr-uni-bochum.de)
#
# This file is part of t1lib and used during configuring for 
# examining the compiler options that are necessary for 
# generation of dynamically linked stuff.
#
# Compiler: gcc
#

echo "  --> options configuration for GNU C compiler"

# What to tell CC to save the runtime library path in executable?
RPATH_OPTION="-Wl,-R../lib"

# How to set the DT_SONAME-field for version management in the 
# shared library? 
SONAME_OPTION="-Wl,-soname,"

# How to generate position independent code?
PIC_OPTION="-fPIC"

# How to tell the compiler to generate a shared linked executable?
SHARED_OPTION="-shared"
\end{verbatim}
It should be mostly self explaining. There is one more option file
included in the \tonelib-distribution called \verb+options.sun_native+
which contains option settings for the SUN Workshop Compiler.

It follows that the right way to compile with an unsupported compiler
is to generate a file \verb+options.mycompiler+ in the subdirectory
\verb+ac-tools+ and force the symbolic link \verb+options+ to point to
that newly created file. Then, the steps described in
(\ref{compiling}) have to be executed.


\subsection{Runtime-Setup}
\label{runtimesetup}%
\subsubsection{Searchpath and Environment Setup}
\verb+t1lib+ basically needs four types of files:
\begin{itemize}
\item \verb+.afm+-files: These contain font metric descriptions as
  well as kerning and ligature information for a particular font.
\item \verb+.pfa+-/\verb+.pfb+-files: These contain the character
  outline descriptions.
\item \verb+.enc+-files: These contain encoding arrays in a special but
  simple form. They are only  needed if someone wants to load a special
  encoding to reencode a font.
\item A font database file. The library needs exactly one font
  database file specified. See below for a description of this
  font database file.
\end{itemize}
In order to tell \tonelib\ where these files might be located in the
filesystem, a configuration file has to be set up by the user.  
At time of initialization (see \ref{initialization} on page
\pageref{initialization}) the library tries to locate all data it
needs immediately or possibly later. The
following actions take place in order:
\begin{enumerate}
\item The library tries to read the variable \verb+T1LIB_CONFIG+ from
  the program's environment.
  The value of this variable is expected to be the
  pathname of a configuration file for \verb+t1lib+. 
\item If the variable \verb+T1LIB_CONFIG+ exists, the file pointed to
  by this variable will be tried to be opened. In case no environment
  variable exists, the library will attempt to open a file called
  \verb+.t1librc+ in the user's home directory.
  If this file as well does
  not exist, the global configuration file \verb+t1lib.config+ is tried to be
  opened.\footnote{The filenames for the user's and the global configuration
    file as well as the name of the environment entry are default names 
    defined in {\ttfamily lib/t1lib/t1misc.h}. They may be redefined by the
    user at compile time if necessary.}
  If all these attemps to open a configuration file failed did not
  succeed, 
  all searchpaths are set to \verb+.+ and the font database
  file is assumed to be \verb+./FontDataBase+. If this file cannot be
  opened, the call to \verb+T1_InitLib()+ returns a NULL-pointer thus
  indicating an error condition. The program should then exit because
  \tonelib\ would not be able to do anything without a font database.
\item Assuming a configuration file has been found and opened at any of the
  above three locations, this file
  is parsed and all relevant information in this file is recorded.
\item Using the paths specified in the configuration file, the
  font database is opened and processed. The existence of every Type 1
  file that might later be needed is ensured. The existence of the
  corresponding AFM file is not verified during
  initialization, because this information is not ultimatively
  critical when generating a character bitmap.\footnote{For example, a
  program may generate a character table of a Type 1 font without
  having AFM information.} But note that most
  parts of the library will not work correctly, if no AFM information is
  available.
\end{enumerate}
The three file search paths and the font database file, mentioned at the
beginning of this subsection, are extracted from the configuration
file using the following rules.
\begin{itemize}
\item A line starting exactly with \verb+ENCODING=+ is read in. The
  remainder of the line is expected to be a list of searchpath
  specifications for encoding files. No white space may appear
  between \verb+=+ and the path specification(s).
  Multiple paths may be specified by separating
  the single paths with colons. The path specification(s) may be
  followed by any white space characters.
\item A line starting exactly with \verb+AFM=+ is read in. The
  remainder of the line is expected to be a list of searchpath
  specifications for Adobe Font Metric files. No white space may
  appear 
  between \verb+=+ and the path specification(s). 
  Multiple paths may be specified by separating 
  the single paths with colons. The path specification(s) may be
  followed by any white space characters.
\item A line starting exactly with \verb+TYPE1=+ is read in. The
  remainder of the line is expected to be a list of searchpath
  specifications for Type 1 font files. No white space may
  space between \verb+=+ and the path specification(s). 
  Multiple paths may be specified by separating
  the single paths with colons. The path specification(s) may be
  followed by any white space characters.
\item A line starting exactly with \verb+FONTDATABASE=+ must
  specify the name of exactly one font database file on the remainder
  of the line.
  No white space is allowed between \verb+=+ and the path
  specification, but trailing white space is allowed.
\item All other lines are ignored by the library. However, one should
  not store books in this file since its contents are 
  completely held in memory for the lifetime of the program.
\end{itemize}

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=~/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 tcsh, or\\ 
\verb+export T1LIB_CONFIG=~/t1.config+\\
 for bash. Provided that the path specifications in the
 configuration file are correct, the setup is done.


\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.
\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 the library. 

{\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.
This program must be compiled to object format and then linked with
the library \verb+libt1.a+ or \verb+libt1.so+, respectively. At runtime, a
well defined setup must be found, i.e., a configuration file with path
definitions and a font database file. 

\begin{verbatim}
#include <stdio.h>
#include <t1lib.h>  /* All needed declarations */

int main( void)
{

  GLYPH *glyph;
  int i;
  
  /* Set our environment to a config file in current directory */
  putenv( "T1LIB_CONFIG=./t1.config");

  /* Pad bitmaps to 16 bits */
  T1_SetBitmapPad( 16);
  
  /* Initialize t1lib and return if error occurs. A log file will be
     generated */
  if ((T1_InitLib(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, KERNING, 25.0, 0.0);
    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 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}