ut1lib.tex

source code: Covert TXT to PDF

  file. Only the first one found is examined.
\item The font database file(s) are tried to be opened and read. This process
  is in detail described in \ref{fontdatabase}. 
  
  If after scanning the complete list of font databases, no font definitions
  have been performed, \verb+T1_InitLib()+ will return with a \verb+NULL+
  pointer indicating the initialization has failed.
\item The number of fonts declared in the database is stored. Note that this
  number of declared fonts must be greater than zero.
\item A flag is set to indicate \tonelib\ is initialized and the pointer to
  the top most area of the global data structures is returned to the
  application. This pointer is guaranteed to be not \verb+NULL+.
\end{enumerate}
For some applications, the described initialization scheme appears to be too
inflexible and overkill. It is well suited for large applications that use
lots of fonts and where it should be possible to add new fonts without
modifying the application itself. For small commandline applications like
\verb+type1afm+ (see \ref{type1afm}), which are designed to read a few font file
names from the commandline, the overhead in configuration file searching and
path reading is much too large. Moreover, to insist on a font database file
might grow to a real disadvantage. In the subsequent paragraphs we should thus
discuss how we can deviate from the initialization scheme described above.

\subsubsection{Fine Control over Font Databases and File Search Paths}
\label{manipulatingpaths}%
First, it is important to mention that it is generally possible to force
\verb+T1_InitLib()+ to skip steps 4 and / or 5 as described above. 

The configuration file is discarded by OR'ing the parameter \verb+log+ of
\verb+T1_InitLib()+ with \verb+IGNORE_CONFIGFILE+.
The default paths or the paths explicitly specified by the application before
are then left untouched during initialization.

Discarding the font database specification from the configuration file is
achieved by bitwise OR'ing \verb+log+ with \verb+IGNORE_FONTDATABASE+. The
result after initialization will be an empty database. This is valid in V.\ 
0.5 and newer since fonts may be added to the database at runtime.

Using the two flags described above, an installed setup can be ignored and an
application may have complete control over its search paths. There are a
number of functions for this purpose and each of these functions allows to
specify exactly {\em one} path element at a given time. Using special
characters like white space or path separators in a path element is thus not
an issue.

The font database may explicitly be specified by the
application using \precorr
\begin{verbatim}
 int T1_SetFontDataBase( char *filename)
\end{verbatim}\index{\verb+T1_SetFontDataBase()+}\postcorr
\verb+filename+ is the pointer to a string containing the name of the font
database file that is to be examined. This function replaces any set of font
databases setup previously and is thus usually to be called before
\verb+T1_InitLib()+. A call to this function after initialization will return
the result -1 and \verb+T1_errno+ will be set to
\verb+T1ERR_OP_NOT_PERMITTED+. For the special case that the font database is
still epmty after initialization this function may also be called after
initialization. But in any case, the database must be empty! For the latter
cases, fonts specified in the new database file are then immediately inserted
into the database. In case of success, the number of available fonts is returned. 

There is also the function \precorr
\begin{verbatim}
 int T1_AddFontDataBase( int mode, char *filename)
\end{verbatim}\index{\verb+T1_AddFontDataBase()+}\postcorr
It can be called at any time and \verb+filename+ is the string of the new font
database's file name. If called before initialization, the parameter
\verb+mode+ can be either \verb+T1_APPEND_PATH+ or \verb+T1_PREPEND_PATH+ and
the name of the new font database simply is either appended or prepended to
the existing list of font databases. Then, the function returns $0$. 

If the function is called after initialization, the parameter \verb+mode+ is
ignored and the new database is appended in any case, because this is the only
meaningful action. Furthermore, the new database is immediately loaded and the
function returns a number indicating the number of available fonts 
(which can also be 0). In the case of an error, \verb+T1_AddFontDataBase()+
returns $-1$.


A similar manipulation as just described for font database file, is
possible for the searchpaths. (Re-)Defining a search 
path is done by calling 
\precorr
\begin{verbatim}
 int T1_SetFileSearchPath( int type, char *pathname)
\end{verbatim}\index{\verb+T1_SetFileSearchPath()+}\postcorr
before calling \verb+T1_InitLib()+, or respectively, before the database
contains any fonts. An attempt to set the file searchpaths when the database
is no longer empty is denied. The reason is that it is not wise to override
the searchpaths which had been valid previously during the verification of the
existence of font files. Such paths should thus not be removed.  The parameter
\verb+pathname+ points to the string that contains the pathname that should be
used as searchpath. The parameter \verb+type+ is any OR'ed combination of
\verb+T1_PFAB_PATH+, \verb+T1_AFM_PATH+ and \verb+T1_ENC_PATH+. These tell the
function to set the search paths for Type 1 font files, AFM files and encoding
files, respectively. In case of an error \verb+-1+ is returned and otherwise
\verb+0+.

Extending the file searchpaths before {\em and} after initialization
is possible using 
\precorr
\begin{verbatim}
 int T1_AddToFileSearchPath( int pathtype, int mode, char *pathname)
\end{verbatim}\index{\verb+T1_AddToFileSearchPath()+}\postcorr
This might be useful to locate font files that were of no interest
at the time of initialization. 
\verb+pathname+ is the pointer to the string that should be added to the
searchpaths. Only {\em one} particular path element may be specified in one
call. What searchpaths are affected is determined by the parameter
\verb+pathtype+. Again, similar to described above, any
OR'ed combination of \verb+T1_PFAB_PATH+, \verb+T1_AFM_PATH+ and
\verb+T1_ENC_PATH+ is valid. There are two ways to extend an existing
searchpath which are specified by the \verb+mode+ parameter. It must be either
\verb+T1_APPEND_PATH+ or \verb+T1_PREPEND_PATH+, which causes the new path
element to be appended or prepended to the existent path respectively.
Since an existent path specification is not overwritten by
\verb+T1_AddToFileSearchPath()+, this function may be called at any time
before or after initialization.

It might also be of interest to query the current file search
paths and font databases. \tonelib\ provides 
\precorr
\begin{verbatim}
 char *T1_GetFileSearchPath( int type)
\end{verbatim}\index{\verb+T1_GetFileSearchPath()+}\postcorr 
for querying search paths. Again, the parameter \verb+type+ determines what
search path is returned. Exactly one of \verb+T1_PFAB_PATH+,
\verb+T1_AFM_PATH+, \verb+T1_ENC_PATH+ and \verb+T1_FDB_PATH+ should be
specified. If more than one path is specified, the first match wins and only
one path is returned. The types will be checked in the order
\verb+T1_PFAB_PATH+, \verb+T1_AFM_PATH+, \verb+T1_ENC_PATH+ and
\verb+T1_FDB_PATH+. Here, \verb+T1_FDB_PATH+ indicates an interest in the list
of font databases. The paths are separated using the current path separator. 


\subsubsection{Adding Fonts to the Database} 
\label{addingfonts}%
Extending the font database is possible at any time after initialization. In
addition to using \verb+T1_AddFontDataBase()+ (see above), it is done via a
call to \precorr
\begin{verbatim}
 int T1_AddFont( char *fontfilename)
\end{verbatim}\index{\verb+T1_AddFont()+}\postcorr
\verb+fontfilename+ is the pointer to the filename string. The following
actions take place:
\begin{itemize}
\item The font file is searched using the current search path specifications. 
\item If the file has been located, it is checked whether the font database
  contains enough memory to hose an additional font. 
  If so, the font filename
  is stored and the function returns \verb+new_ID+, which is the font ID that
  will be associated with this font in the future. 
\item If there was no free memory for an additional font, the memory is
  reallocated to a greater size. This involves also resetting the new
  area. Finally the value \verb+new_ID+ is returned.
\end{itemize}
If a negative value is returned the function failed. \verb+-1+ indicates the
font file could not be located. \verb+-2+ or \verb+-3+ are returned if a
memory allocation failure occurs.


\subsubsection{Summary of Search Path Handling}

Since the exact handling of search path specifications at the several stages
may appear somewhat confusing we shall summarize the exact rules now:
\begin{enumerate}
\item {\bfseries Before Initialization}\\
  Default paths are not yet setup. Each call of one of the \verb+T1_Set...()+
  functions described above establishes a completely new respective path. Each
  call of one of the \verb+T1_Add...()+ functions extends the respective path
  in the desired manner, or creates a new respective path if previously no
  path existed.
\item {\bfseries At the Beginning of the Initialization}\\
  Each path type for which a path had not already been explicitly created
  using the\\ \verb+T1_Set...()+ or \verb+T1_Add...()+ functions receives a
  default value. This is ``\verb+.+'' for the file search paths and
  \verb+./FontDataBase+ for the font database.
\item {\bfseries During Initialization}\\
  Each path element read from the configuration file overwrites an existing
  respective default path but preserves an existing respective explicitly
  setup path by appending to the latter. The newly setup search path is used
  to locate files while scanning the font database file(s).
\item {\bfseries After Inititialization but before the Database is being
    filled}\\ 
  At this stage, all \verb+T1_Set...()+ and \verb+T1_Add...()+ functions still
  work as described under~(1). Notice that this phase usually is not
  accessible when using the standard initialization scheme. It only becomes
  accessible if no fonts have been added during initialization.
\item {\bfseries After at least one Font is insterted into the Database}\\
  Once there are fonts in the database, the paths setup up
  to now must be preserved in any case. Hence, the \verb+T1_Set...()+ may not
  be called any longer. The \verb+T1_Add...()+ functions {\em extend} the
  current set of search paths. In particular, possibly existing default search
  path elements, then, are not overwritten any longer because they might have
  been used before to verify the existance of required files. 
\end{enumerate}
A call to \verb+T1_AddFontDataBase()+ will not only append the specified
file name to the existing list of databases, but will also immediately
locate the fonts specified therein and assign additional font IDs.


\subsubsection{Bypassing the \tonelib\ File Search Machinery} 
\label{afmfilenames}%
Usually, \tonelib\ takes care for locating files according to the path
specifications in the configuration file. There might, however, arise the need
to explicitly tell \tonelib\ which particular file to use. Forcing \tonelib\ to
use particular Type 1 font files can be achieved using the function
\verb+T1_AddFont()+, described just above. If a pathname passed to this
function is a complete path, \tonelib\ will use this complete path to locate
the font file, forgetting about its own search path list. A filename path is
assumed to be complete if 
\begin{itemize}
\item it starts with the directory separator character, usually
  ``\verb+/+''. In this case it is an {\em absolute} path specification, meaning
  that the start point is at the root of the filesystem, or
\item if it starts with ``\verb+./+'' or ``\verb+../+'' (where it is assumed
  that ``\verb+/+'' is the directory separator character). Here we have a {\em
    relative} path specification in which ``\verb+.+'' refers to the current
  working directory while ``\verb+..+'' refers to the parent directory of the
  current working directory. Since the notion of the {\em current working
    directory} is fundamental for every process that has access to a
  filesystem, a relative path specification also uniquely identifies one
  particular file in the filesystem.
\end{itemize}
If a font file whose complete path had been specified could not be found by
\tonelib, the paths from the configuration file are searched as a fallback
mechanism. 

What can be done for the Type 1 font files is also possible for AFM files,
which are needed on a per-font basis. The function
\precorr
\begin{verbatim}
 int T1_SetAfmFileName( int FontID, char *afm_name)
\end{verbatim}\index{\verb+T1_SetAfmFileName()+}\postcorr
allows to set the complete path of the AFM file belonging to the font
identified by \verb+FontID+, overriding the internal
search mechanism. This function is to be called after initialization but
before the font \verb+FontID+ is loaded. It returns 0 if all goes right and
$-1$ otherwise. In the latter case \verb+T1_errno+ will also be set
appropriately. Notice that \verb+FontID+ must also be valid with respect to
its upper limit, it is an error condition if the font database has less than
\verb+FontID+ entries. 

There is also the function 
\precorr
\begin{verbatim}
 char *T1_GetAfmFileName( int FontID)
\end{verbatim}\index{\verb+T1_GetAfmFileName()+}\postcorr
which allows to query the AFM filename of a font. It returns a pointer to the
filename if it had explicitly been specified or \verb+NULL+
otherwise. \verb+NULL+ will also be returned if \verb+FontID+ was invalid. In
this case also \verb+T1_errno+ will be set.  

Just for the sake of completeness we should mention that what has been said 
about absolute and relative path specification