getstart.tex

source code: Covert TXT to PDF

%----------------------------------------------------------------------------
% ----- File:        getstart.tex 
% ----- Author:      Rainer Menzner ([e-mail])
% ----- 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 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 All other lines are ignored by the library. 
\end{itemize}