%----------------------------------------------------------------------------% ----- File:        getstart.tex % ----- Author:      Rainer Menzner (Rainer.Menzner@web.de)% ----- Date:        2001-10-07% ----- Description: This file is part of the t1lib-documentation.% ----- Copyright:   t1lib is copyrighted (c) Rainer Menzner, 1996-2001. %                    As of version 0.5, t1lib is distributed under the%                    GNU General Public Library License. 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%                    independent 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 andbuild the library. \verb+imake+ is no longer supported. Furthermore, startingwith version 0.8-beta GNU \verb+libtool+ is used for managing library-specificstuff. Here is how to build and install \tonelib:\begin{enumerate}\item Change to \verb+T1+-directory.\item Run \verb+./configure+. This will check your system's setup and generate  the \verb+Makefile+s. By default, shared and static versions of the  libraries are built.  Specifying \verb+--disable-shared+ or \verb+--disable-static+ as a  commandline option to \verb+configure+ will suppress the generation of the  respective library type. Of course, these rules are superseded by the  capability of the system to manage those library types.  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{libtoolproblems}).   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+ and/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 \verb+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 \verb+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 \verb+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 \verb+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 alsoremoves the makefiles as well as the log and cache files of the configurationprocess. It forces thus a new call to \verb+configure+. A \verb+make clean+ is needed, for example, if someone experiments with staticand shared libraries since the object files for shared libraries require theadditional position independent code options.The directory \verb+T1/parse_afm+ is not needed at all, it is included onlyfor completeness. The parts needed from this have been copied to the\verb+lib/t1lib+-subdirectory. \subsection{Notes on Using GNU {\tt libtool}}\label{libtoolproblems}%\verb+libtool+ might get confused by heterogenous compiler setups. This is thecase, for example, on our Solaris system where by default \verb+gcc+ is usedin combination with the system specific linker. This configuration leads to\verb+libtool+ reporting that no shared library can be built which definitelyis wrong. In most cases such problems can be solved by fiddling with theenvironment entries \verb+CC+, \verb+CFLAGS+, \verb+LD+ and \verb+LDFLAGS+.\verb+libtool+ hides the real objects in subdirectories named \verb+.libs+.This means, after a successful build, \verb+libt1.so+ is located in\verb+T1/lib/.libs+. Similarly, if shared libraries are built the executable\verb+T1/xglyph/xglyph+ is a simple wrapper to \verb+T1/xglyph/.libs/xglyph+. \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. Type 1 font files may also lack any extension in their  filename. This is the habit on NeXTStep, for example.\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 at least one font  database file specification. See below for a description of this  font database file. Optionally, multiple font database files can be  specified.\end{itemize}In order to tell \tonelib\ where these files are located in thefilesystem, a configuration file usually 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 itneeds immediately or possibly later. Thefollowing 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 attempts to open a configuration file did not  succeed, all searchpaths are left at defaults (\verb+.+) and the font database  file is  setup 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 an association of font  IDs to font files.\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.} Aside from this, \tonelib\ can generate the  required part of the AFM information on the fly.\end{enumerate}\subsubsection{The {\ttfamily t1lib} Configuration File}\label{subsubsec:configfile}It is the purpose of the configuration file to setup search paths and fontdatabases. The format of this file is quite simple and straightforward:\begin{itemize}\item Each 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.\footnote{A colon is the default path separator    on UNIX systems. For certain other Operating Systems the path separator    may be a semicolon.} The path specification(s) may be  followed by any white space characters.\item Each 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 Each 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 Each line starting exactly with \verb+FONTDATABASE=+ must specify a  colon-separated list of font database filenames 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. \end{itemize}