%---------------------------------------------------------------------------- % ----- File: getstart.tex % ----- Author: Rainer Menzner (Rainer.Menzner@web.de) % ----- Date: 2005-05-18 % ----- Description: This file is part of the t1lib-documentation. % ----- Copyright: t1lib is copyrighted (c) Rainer Menzner, 1996-2005. % 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 and build the library. \verb+imake+ is no longer supported. Furthermore, starting with version 0.8-beta GNU \verb+libtool+ is used for managing library-specific stuff. 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 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{Notes on Using GNU {\tt libtool}} \label{libtoolproblems}% \verb+libtool+ might get confused by heterogenous compiler setups. This is the case, for example, on our Solaris system where by default \verb+gcc+ is used in combination with the system specific linker. This configuration leads to \verb+libtool+ reporting that no shared library can be built which definitely is wrong. In most cases such problems can be solved by fiddling with the environment 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 the filesystem, 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 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 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 font databases. 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 Each line starting exactly with \verb+FONTDATABASEXLFD=+ must specify a colon-separated list of font database filenames that adhere to the XLFD (X11 Logical Font Definition) on the remainder of the line. No white space is allowed between \verb+=+ and the path specification, but trailing white space is allowed. This keyword is not an independent key word, rather, it allows to specify a special alternative type of font database---a type that usually exists as part of every X11 system. Standard and XLFD font database files may be specified both in one configuration file. They interact in a way, that if an XLFD font database file is specified, this overwrites the default standard font database setup before the configuration is read. \item All other lines are ignored by the library. \end{itemize} 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 #include #include /* 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