kpathsea: Programming overview
7.1 Programming overview
========================
Aside from this manual, your best source of information is the source to
the programs that use Kpathsea (
Introduction). Of those, Dviljk
is probably the simplest, and hence a good place to start. Xdvik adds
VF support and the complication of X resources. Dvipsk adds the
complication of its own config files. Web2c is source code I also
maintain, so it uses Kpathsea rather straightforwardly, but is of course
complicated by the Web to C translation. Finally, Kpsewhich is a small
utility program whose sole purpose is to exercise the main
path-searching functionality.
When looking at these program sources, you should know that previous
versions of the library had a different programming interface, to
support re-entrancy. In that interface the library function names were
prefixed with 'kpse_' instead of 'kpathsea_', and they did not need an
instance variable as first argument. This change was made in 2009.
Some of the programs mentioned above may still be using the previous
interface.
Beyond these examples, the '.h' files in the Kpathsea source describe
the interfaces and functionality (and of course the '.c' files define
the actual routines, which are the ultimate documentation).
'pathsearch.h' declares the basic searching routine. 'tex-file.h' and
'tex-glyph.h' define the interfaces for looking up particular kinds of
files. In view of the way the headers depend on each other, it is
recommended to use '#include <kpathsea/kpathsea.h>', which includes
every Kpathsea header.
If you want to include only specific headers, you should still
consider including 'kpathsea/config.h' before including any other
Kpathsea header, as it provides symbols used in the other headers. Note
that 'kpathsea/config.h' includes 'kpathsea/c-auto.h', which is
generated by Autoconf.
The library provides no way for an external program to register new
file types: 'tex-file.[ch]' must be modified to do this. For example,
Kpathsea has support for looking up Dvips config files, even though no
program other than Dvips will likely ever want to do so. I felt this
was acceptable, since along with new file types should also come new
defaults in 'texmf.cnf' (and its descendant 'paths.h'), since it's
simplest for users if they can modify one configuration file for all
kinds of paths.
Kpathsea does not parse any formats itself; it barely opens any
files. Its primary purpose is to return filenames. The GNU font
utilities does contain libraries to read TFM, GF, and PK files, as do
the programs above, of course.
Info Catalog
kpathsea: Programming
kpathsea: Calling sequence